Skip to main content

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​

TaskPackageNeeds
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/protocolA node
Open or close a pool to private entries@orbinum/protocol (setPrivate)The pool root's signer
Enter or exit a poolThe user's wallet; a dApp sends the user thereThe spending key, a prover and the vault
A pool's private totals and historyThe indexer, under /staking/poolsHTTP

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();
}
CallReturns
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:

HelperComputes
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
NoSuchPoolNo such nomination pool
NotPrivateNot open to private entries, or winding down
PoolNotOpenThe pool is blocked or destroying
PoolSlashedSlashed past MaxPointsToBalance: it takes no one
BelowMinimumBelow minEntry(), or below the pool's join minimum for its first private entry
TooManyMembersThe pool or the pools pallet is full (first private entry only)
QueueFullThis era's entry queue for the pool is full
exitRefusal(poolId, shares, fee, minValue)Meaning
NoSuchPoolNot a private pool
NothingToRedeemThe shares are worth nothing, or shares is zero
SharesExceedSupplyshares + fee is more than the pool has issued
RemainderBelowMinimumThe exit would leave the private membership below the join minimum, or a nominating pool's stake below the nominator minimum
TooManyUnbondingThe pool's private member has no room for another unbonding chunk this era
BelowMinimumOutputThe 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);
}
RefusalWhen
NoSuchPoolNo such pool
NotRootThe signer is not the pool's root
PoolNotOpenOpening a destroying pool, or one whose private side wound down
NotPrivateClosing 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.

ActionSpendsOutput
EnterOne ORB note: the amount staked and the fee, the rest back as changeThe pool's shares, minted when the entry settles after its era compounds; or the ORB, refunded at once, when the pool cannot settle it
ExitOne note of the pool's share asset: the shares redeemed and the fee in shares, the rest back as changeORB, minted when the unbonding unlocks
The user chooses
The poolAny 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 feeAt least MinSpendFee for an entry; for an exit, at least the pool's privateMinFeeShares in shares
A floorFor 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 exitIts status
Nothing minted to its key yetEntering, or Leaving
EntryRefunded names its keyRefunded; its ORB is paid in the same block
A share note minted to its keyJoined
An ORB note minted to an entry's keyRefunded, back in the vault
An ORB note minted to an exit's keyExited

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 } }.

EndpointReturns
GET /staking/pools?state=Pools by active stake, each with private
GET /staking/pools/:idThe pool with private, its nominations (targets) and recentEvents
GET /staking/pools/:id/members?account=&sort=stake|unbonding&dir=desc|ascCurrent 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/:accountAn 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.