Private Staking with the SDK
A nomination pool whose root opened it to private members takes entries and exits from shielded
notes. Reading those pools needs only @orbinum/protocol and a node; opening a pool needs its
root's signature; entering and exiting spend notes, so the user's wallet makes them. This page
covers all four, and the indexer endpoints that serve a pool's
private state and history. How the runtime settles everything is in
ZK-NPoS: Private Staking.
Table of Contents
- What runs where
- Reading private pools
- Checking an entry or exit before proving
- Opening a pool to private members
- Entering and exiting from a wallet
- Indexer endpoints
What runs where
| Task | Package | Needs |
|---|---|---|
| List private pools, read a pool's price, supply and minimum | @orbinum/protocol (client.privateStaking) | A node |
| Quote an entry or exit and say why the chain would refuse it | @orbinum/protocol | A node |
| Open or close a pool to private entries | @orbinum/protocol (setPrivate) | The pool root's signer |
| Enter or exit a pool | The user's wallet; a dApp sends the user there | The spending key, a prover and the vault |
| A pool's private totals and history | The indexer, under /staking/pools | HTTP |
Reading private pools
import {
OrbinumClient,
formatBalance,
privateMinFeeShares,
privateShareValue,
privateSharesFor,
} from '@orbinum/protocol';
const client = await OrbinumClient.connect({ substrateWs: 'wss://rpc-1.testnet.orbinum.io' });
try {
const ORB = { decimals: 18, symbol: 'ORB' };
const [pools, minEntry, unbondingEras, minSpendFee] = await Promise.all([
client.privateStaking.pools(),
client.privateStaking.minEntry(),
client.privateStaking.exitUnbondingEras(),
client.shieldedPool.minSpendFee(),
]);
console.log('minimum entry:', formatBalance(minEntry, ORB), '— exits unlock after', unbondingEras, 'eras');
for (const pool of pools) {
const quote = await client.privateStaking.quote(pool.poolId);
if (!quote) continue;
const oneShare = 10n ** 18n;
console.log(`pool #${pool.poolId} (s${pool.poolId}, asset ${pool.assetId})`, {
open: pool.enabled && !pool.windDown,
supply: formatBalance(quote.supply, { decimals: 18, symbol: `s${pool.poolId}` }),
oneShareIsWorth: formatBalance(privateShareValue(quote, oneShare), ORB),
sharesFor100Orb: privateSharesFor(quote, 100n * 10n ** 18n),
feeFloorInShares: privateMinFeeShares(quote, minSpendFee),
member: client.privateStaking.memberAddress(pool.poolId),
});
}
} finally {
client.destroy();
}
| Call | Returns |
|---|---|
pools() | Every pool ever opened to private members, as PrivatePool: poolId, assetId, enabled, supply, compoundedEra (or null), windDown (or null) |
pool(poolId) | One PrivatePool, or null if its root never opened it |
poolOfAsset(assetId) | The pool a share asset belongs to, or null |
quote(poolId) | PrivatePoolQuote: supply, netValue (what the minted shares are worth), virtualOffset and windDown; null for a pool never opened |
minEntry() | The smallest private entry, in planck |
exitUnbondingEras() | Eras an exit waits before its ORB is minted |
memberAddress(poolId) | The pool's private member account, in SS58 |
enabled says whether new entries are taken; exits never close. windDown is set once the pool is
destroying: its shares are then worth a fixed value, with liquid, unlockEra and withdrawn
saying how much of it is paid out yet.
Pricing
The pricing helpers round exactly as the runtime does:
| Helper | Computes |
|---|---|
privateShareValue(quote, shares) | The ORB shares are worth now, rounded down, never above pro rata |
privateSharesFor(quote, value) | The shares an entry of value would take at the current price. An estimate: an entry is priced when it settles, after its era compounds |
privateMinFeeShares(quote, minSpendFee) | The smallest fee, in shares, that a spend of the pool's share asset pays |
privateExitValue(quote, shares, fee) | What an exit of shares paying fee shares is paid now |
Pass client.shieldedPool.minSpendFee() as minSpendFee, so the floor follows the chain.
Checking an entry or exit before proving
A refused bound spend costs a proof. Both refusal checks read the chain at the best block and
return null when the chain would accept:
import { privateExitValue, privateMinFeeShares } from '@orbinum/protocol';
const amount = 50n * 10n ** 18n;
const entry = await client.privateStaking.entryRefusal(poolId, amount);
if (entry === 'QueueFull') console.log('this era is full; the pool takes entries again next era');
const quote = (await client.privateStaking.quote(poolId))!;
const fee = privateMinFeeShares(quote, await client.shieldedPool.minSpendFee());
const shares = 10n ** 18n;
const minValue = (privateExitValue(quote, shares, fee) * 99n) / 100n; // accept up to 1 % less
const exit = await client.privateStaking.exitRefusal(poolId, shares, fee, minValue);
entryRefusal(poolId, amount) | Meaning |
|---|---|
NoSuchPool | No such nomination pool |
NotPrivate | Not open to private entries, or winding down |
PoolNotOpen | The pool is blocked or destroying |
PoolSlashed | Slashed past MaxPointsToBalance: it takes no one |
BelowMinimum | Below minEntry(), or below the pool's join minimum for its first private entry |
TooManyMembers | The pool or the pools pallet is full (first private entry only) |
QueueFull | This era's entry queue for the pool is full |
exitRefusal(poolId, shares, fee, minValue) | Meaning |
|---|---|
NoSuchPool | Not a private pool |
NothingToRedeem | The shares are worth nothing, or shares is zero |
SharesExceedSupply | shares + fee is more than the pool has issued |
RemainderBelowMinimum | The exit would leave the private membership below the join minimum, or a nominating pool's stake below the nominator minimum |
TooManyUnbonding | The pool's private member has no room for another unbonding chunk this era |
BelowMinimumOutput | The shares are worth less than minValue |
minValue (exit) is the slippage bound the proof commits to; the paid value ignores pool-point
rounding of a few planck, so leave that margin in it.
minShares (entry) is the fewest shares the entry accepts when it settles. Pass 1n. Rewards
compounded before an entry settles raise the share price: the entry then receives fewer shares
worth the same, so a floor set from the estimate only refunds honest entries. One unit still turns
an entry that would round down to no shares into a refund, which keeps its ORB. An entry the pool
cannot settle is refunded at once, in full, not failed.
Opening a pool to private members
The pool's root opens it; the first opening registers the pool's share asset.
import { protocolRefusal } from '@orbinum/protocol';
try {
const result = await client.privateStaking.setPrivate(poolId, true, rootSigner);
if (!result.ok) throw new Error(result.error);
} catch (error) {
const refusal = protocolRefusal(error);
if (!refusal) throw error;
// 'NoSuchPool' | 'NotRoot' | 'PoolNotOpen' | 'NotPrivate'
console.log(refusal.reason, refusal.detail.poolId);
}
| Refusal | When |
|---|---|
NoSuchPool | No such pool |
NotRoot | The signer is not the pool's root |
PoolNotOpen | Opening a destroying pool, or one whose private side wound down |
NotPrivate | Closing a pool never opened |
setPrivate(poolId, false, signer) stops new entries; members can always exit. EVM and Solana
roots sign it as text, with getEcdsaTextSigner or getEd25519TextSigner.
The pool operator's view is in Private Pools.
Entering and exiting from a wallet
Entering and exiting spend a note, so they need its spending key and only the user's wallet makes
them; a dApp shows the pool and sends the user to their wallet. Both are
bound spends: an unshield proof that pays the pool's
private member account and whose memo_hash commits to the action. The output — shares, or ORB —
is minted later to a one-time key the wallet reserves
before proving.
| Action | Spends | Output |
|---|---|---|
| Enter | One ORB note: the amount staked and the fee, the rest back as change | The pool's shares, minted when the entry settles after its era compounds; or the ORB, refunded at once, when the pool cannot settle it |
| Exit | One note of the pool's share asset: the shares redeemed and the fee in shares, the rest back as change | ORB, minted when the unbonding unlocks |
| The user chooses | |
|---|---|
| The pool | Any pool open to private members |
| The amount (enter) or the shares (exit) | Up to the value of one note; the fee comes out of the same note |
| The fee | At least MinSpendFee for an entry; for an exit, at least the pool's privateMinFeeShares in shares |
| A floor | For an exit, the least ORB its shares may be worth now. For an entry, one share unit (see above) |
The wallet builds the note's Merkle path locally from subtree roots, so it never names the note to
a node. A request the wallet can tell is wrong (a note of the wrong asset, a negative floor, a note
already being spent) is refused before anything is proved. To tell the user why the chain would
refuse an entry or exit before sending them to the wallet, run entryRefusal or exitRefusal
first (see Checking an entry or exit before proving).
Receiving the output
The output is a note the chain mints itself (NoteMinted), with no memo. The wallet keeps the
one-time key's index with the entry or exit. Once a settlement event names the block that minted
it, the wallet reads that block's events from the node, recomputes the commitment with its key and
keeps the note with its leaf, spendable without a scan. The settlement events are EntrySettled
(shares) and ExitSettled (an exit's or a refund's ORB), served by the indexer as
private_entry_settled and private_exit_settled on /staking/pools/{id}/events?kind=. The wallet
reads them for every private pool, not only the one entered, so the requests do not tell which
pool it waits on.
Following an entry or exit
Every event of an entry or exit names its one-time key as owner_pk: Entered, EntrySettled,
EntryRefunded, Exited and ExitSettled. The key is public already, in the action; the events
let a wallet follow its own entries and exits without decoding calls or matching amounts. The key
is the bound key's ownerPk as 32 little-endian bytes: compare
leHexToBigint(event.owner_pk) (@orbinum/protocol) with deriveBoundKey(spendingKey, index).ownerPk.
| An entry or exit | Its status |
|---|---|
| Nothing minted to its key yet | Entering, or Leaving |
EntryRefunded names its key | Refunded; its ORB is paid in the same block |
| A share note minted to its key | Joined |
| An ORB note minted to an entry's key | Refunded, back in the vault |
| An ORB note minted to an exit's key | Exited |
Read refunds and the entry and exit events for every private pool, closed ones included (the
indexer's pool list keeps a pool's private side with closed: true after the runtime forgets it),
never for one key or one pool: which pools a wallet asks about would tell where it stakes. A note
minted to a key the vault has no record of (after a restore) takes its origin from the Entered or
Exited event with that key and the transaction behind it (extrinsicHash).
A scan finds the same notes: it matches minted leaves against the wallet's one-time keys and adds
them to the vault. It is the fallback after a restore. An indexer or explorer decodes the minted
notes of a block with @orbinum/protocol's mintedLeaves.
A pool's recent return
Compounded carries the minted shares' value and supply after each era: the share price is
value / supply. A pool's return over time is the growth of that price from one era to the next,
averaged over its last eras and scaled to a year by the time between them. Entries and exits buy
and sell at the price, so only rewards and slashes move it.
Indexer endpoints
An Orbinum indexer serves each pool's private side next to its public state. Every list is
paginated with ?page= and ?limit= and answers { data, pagination: { page, limit, total } }.
| Endpoint | Returns |
|---|---|
GET /staking/pools?state= | Pools by active stake, each with private |
GET /staking/pools/:id | The pool with private, its nominations (targets) and recentEvents |
GET /staking/pools/:id/members?account=&sort=stake|unbonding&dir=desc|asc | Current members; the private member account has isPrivateMember: true. account (SS58, or an EVM address as its mapped account) keeps one member |
GET /staking/pools/:id/events?kind=&account= | The pool's events, newest first, each with extrinsicHash: the transaction that emitted it, or null for block work (settlements, compounding) |
GET /staking/pool-members/:account | An account's membership, with isPrivateMember |
private is null for a pool never opened to private members, else:
{
"enabled": true,
"assetId": 3,
"memberAccount": "5EYCAe5…",
"totalEntered": "250000000000000000000",
"totalExited": "40000000000000000000",
"entryCount": 9,
"exitCount": 2,
"lastCompoundedEra": 41,
"windDown": null,
"closed": false,
"updatedAtBlock": 812345
}
windDown is { value, unlockEra } once the pool is destroying. Amounts are planck as decimal
strings.
Each PrivateStaking event is a pool event row whose kind is one of private_members_set,
private_entered, private_exited, private_compounded, private_entry_settled,
private_entry_refunded, private_exit_settled, private_output_dropped,
private_fees_redeemed, private_withdrawn, private_winding_down, private_pool_closed or
private_min_entry_set. ?kind= matches one kind exactly. In these rows amount is the ORB moved
(the shares minted for private_entry_settled; none for private_compounded, whose value and
supply stay in data), era the entry or unlock era, and account the validator of
private_fees_redeemed; no row names a private member. data holds every field of the event as
the runtime emitted it, owner_pk included.
Minted notes appear in the indexer's commitment feeds as leaves with source: "mint" and their
mintedAssetId and mintedValue; bound spends appear among unshields with kind: "bound_spend"
and the member account as recipient. See Note Discovery.
Related
- ZK-NPoS: Private Staking — bound spends, share price and settlement
- Private Pools — the user's and the operator's flow in the app
- @orbinum/protocol — the package reference
- Indexing Events — the events behind the history
- Spend Fees — fees paid in shares