ZK-NPoS: Private Staking
ZK-NPoS (Zero-Knowledge Nominated Proof-of-Stake) is Orbinum's private staking, a design created by Orbinum: it adds zero-knowledge membership to Nominated Proof-of-Stake without changing NPoS itself. The election, the pools, the validators and the rewards are the chain's ordinary staking; what ZK-NPoS hides is who is staking.
ZK-NPoS lets a holder of shielded ORB join a nomination pool, earn its rewards and leave again without any of their accounts appearing on chain. A pool's root opens the pool to private members; the runtime then holds one membership in it on their behalf and issues a share asset whose notes are shares of that membership. Nobody signs anything: entries and exits are unsigned bound spends, and what they return are notes the chain mints itself. This page describes the mechanism as the runtime implements it. The user flow is in Private Pools, and the SDK side in Private Staking with the SDK.
Table of Contents
- Overview
- Bound spends
- The private member account
- Opening a pool
- Share assets
- Entering
- Settlement in on_idle
- The share price
- Minted notes
- Exiting
- Fees
- Wind-down
- Events
- What is public
- Parameters and errors
Overview
| Piece | Where | Role |
|---|---|---|
ShieldedPool.bound_spend | pallet-shielded-pool, call 20 | Spends one note into a runtime action, with an unshield proof bound to that action |
BoundAction | The runtime | The actions a bound spend can carry. Today only PrivateStaking, with Enter or Exit |
PrivateStaking | The runtime's staking::private pallet | Holds each pool's private membership, issues its share asset, holds entries until they settle, and settles entries, exits and fees |
ShieldedPool.mint_note | Called by private staking, not an extrinsic | Inserts a note the chain computed from a key and blinding the action carried |
Bound spends
bound_spend (call index 20 of the shielded pool) is an unshield whose proof also commits to an
action. It is accepted only unsigned, like every spend; a signed or Root origin fails with
BadOrigin.
| Argument | Meaning |
|---|---|
proof | An unshield proof (circuit unshield, version 3) |
merkle_root, nullifier, asset_id, amount, fee, change_commitment, change_encrypted_memo, circuit_version | As in unshield |
action | The BoundAction the value goes to. Its SCALE encoding is bound by the proof |
There is no recipient argument. The runtime asks the action for its executor, the account it
runs as, and uses it as the proof's recipient; for private staking it is the pool's
private member account. A proof that pays anyone else fails.
The digest
A plain unshield's memo_hash is blake2_256(SCALE([change_memo])). A bound spend's memo_hash
commits to more:
memo_hash = blake2_256(
"orbinum:bound-spend:v1"
‖ genesis_hash
‖ blake2_256(SCALE(action))
‖ blake2_256(SCALE([change_memo]))
) mod r
| Bound in | Effect |
|---|---|
The domain orbinum:bound-spend:v1 | The digest never equals a plain unshield's, so neither proof passes as the other |
genesis_hash | A proof made for one chain is valid on no other |
blake2_256(SCALE(action)) | Everything the action decides, its output key, blinding and minimum included, is fixed by the proof: a copier who changes the pool or the key invalidates it |
| The change memo | As in an unshield: the change note stays recoverable by its owner |
boundSpendDigest(genesisHash, action, changeMemo) in @orbinum/protocol computes it byte for byte
as the runtime does, and encodeBoundAction(action) gives the action's SCALE encoding.
The bound action
BoundAction::PrivateStaking(Action) (index 0)
Action::Enter { pool_id: u32, owner_pk: [u8; 32], blinding: [u8; 32], min_shares: u128 } (index 0)
Action::Exit { pool_id: u32, owner_pk: [u8; 32], blinding: [u8; 32], min_value: u128 } (index 1)
owner_pk and blinding are the output note's owner key and blinding, little-endian field
elements. Both must be canonical and non-zero (InvalidKey): a zero key has no secret behind it,
and a zero blinding exposes the note. The wallet derives them from a
one-time bound key.
Checks
A bound spend passes every check of an unshield except the asset and recipient rules, plus the action's own:
| Check | Error |
|---|---|
fee at least the asset's floor: MinSpendFee for ORB, the shares worth it for a share asset | FeeTooLow |
Known root, unspent canonical nullifier, non-zero amount, pool balance for amount + fee, change memo of 180 bytes or empty | As in unshield |
| The asset is spendable: verified ORB, or a pallet-backed asset | AssetNotVerified, AssetNotSupported |
| The action has an executor (the pool is private) and it is the proof's recipient | InvalidBoundAction, InvalidRecipient |
| The action's own checks (entering, exiting) | InvalidBoundAction |
| The proof verifies against the bound digest | ProofVerificationFailed |
Pool admission runs the same checks before the proof, so a refused action never reaches a block; it
is rejected with pool code 14 (INVALID_ACTION). A plain unshield refuses any executor as
recipient, so the value a bound spend hands an action can only arrive through that action.
Execution order
- The note is spent: for ORB,
amountmoves from the pool account to the executor; for a share asset,amountis burned from the pool's ledger. A change note is inserted with its memo. - The action runs with the asset,
amountandfee(EnteredorExited). - The fee is credited to the block author (Fees).
BoundSpent { nullifier, asset_id, amount, executor, change_commitment, change_encrypted_memo, change_leaf_index }is emitted.
The private member account
Each private pool has one member account, m_P, that holds every private member's stake in it:
m_P = "modl" ‖ "orb/pstk" ‖ u32_le(pool_id) zero-padded to 32 bytes
It is PalletId(*b"orb/pstk").into_sub_account_truncating(pool_id): keyless, so no one can sign for
it. To the nomination pool it is an ordinary member whose points stand for all private members
together.
| Rule | Enforced by |
|---|---|
Only the private staking pallet unbonds or withdraws m_P | The runtime's call filter refuses NominationPools.unbond and withdraw_unbonded naming any account in PrivateStaking.Members |
A plain unshield cannot pay m_P | unshield refuses an executor as recipient (InvalidRecipient) |
ORB withdrawn for outputs not paid yet stays in m_P | Kept as Escrow, which compounding leaves alone |
ORB of entries not settled yet stays in m_P, unbonded | Kept as EntryEscrow, which compounding leaves alone |
privateMemberAddress(poolId) and privateMemberAccountId(poolId) in @orbinum/protocol derive it;
the indexer marks it with isPrivateMember: true in a pool's member list.
Opening a pool
PrivateStaking.set_private(pool_id, enabled) (call index 0) is signed by the pool's root only
(NotRoot).
| Call | Effect |
|---|---|
First set_private(pool, true) | Registers the pool's share asset, records m_P in Members, emits PrivateMembersSet { pool_id, enabled: true, asset_id } |
set_private(pool, false) | Stops new private entries. Exits never close |
set_private(pool, true) again | Reopens to entries; refused for a destroying pool or one whose private side wound down (PoolNotOpen) |
| Closing a pool never opened | NotPrivate |
set_private is text-signable, so EVM and Solana roots sign it too: the text
shows the pool and private members: on|off.
Share assets
Opening a pool registers an asset in the shielded pool's registry, issued by the private staking pallet:
| Field | Value |
|---|---|
| Name | Private stake in pool #N |
| Symbol | sN |
| Decimals | 18 |
| Backend | Pallet-backed (orb/pstk), registered as verified. Governance cannot verify or unverify it (AssetManagedByPallet) |
A share note is a claim on part of m_P's stake. Its supply is the pool's supply: notes in
existence plus fee shares not yet redeemed, always equal to the shielded pool's ledger for that
asset.
| Operation | Share notes |
|---|---|
private_transfer | Allowed: shares move privately between notes, with the fee in shares |
bound_spend with Exit | The only way out |
shield, unshield | Refused: only ORB enters or leaves the pool publicly |
Entering
An entry is a bound spend of an ORB note with Enter { pool_id, owner_pk, blinding, min_shares }.
The action checks, in order:
| Check | Error |
|---|---|
| The spent asset is ORB | WrongAsset |
| The pool is private, open to entries and not winding down | NotPrivate |
The nomination pool exists and is Open | NoSuchPool, PoolNotOpen |
The pool is not slashed past MaxPointsToBalance | PoolSlashed |
amount is at least MinEntry (10 ORB until governance sets another) | BelowMinimum |
owner_pk and blinding are non-zero field elements | InvalidKey |
For the pool's first private entry, amount meets MinJoinBond and the member limits have room | BelowMinimum, TooManyMembers |
| This era's entry queue for the pool has room | QueueFull |
The spend has already paid amount to m_P. It is not bonded: it waits in m_P's free
balance, counted in EntryEscrow, and the entry is queued for the active era with its value,
min_shares, key and blinding. Entered { pool_id, value, era, owner_pk } is emitted.
A waiting entry has no pool points. The pool hands out rewards by points at payout time, so ORB bonded at once would draw rewards for an era its stake was not exposed in, and compounding would then give them to the shares already minted. Held unbonded, a waiting entry draws no rewards and bears no slash. Once the pool has compounded the era it entered in, the entry is settled: priced, bonded and its shares minted. From then on it earns like every other share.
| Queue | Bound |
|---|---|
| Entries per pool per era | 32 pages of 256: 8,192. Past that the pool takes entries again next era (QueueFull) |
| Exits and fees | Any number of pages per unlock era: never refused for room |
Settlement in on_idle
Everything that happens after the bound spend happens in the pallet's on_idle hook, after the
block's extrinsics, in the Finalization phase: no extrinsic and no signer.
| Bound | Value |
|---|---|
| Weight per block | The block's leftover weight, at most 10 % of the maximum block weight |
| Order | Pool by pool, starting after the pool the last block stopped at. A pool that took a step hands the next block to the pools after it, so a long queue delays only its own pool |
For each pool, in order:
-
Forget a dissolved or wound-down pool with nothing left to settle (
PoolClosed). -
Compound the previous era once
pallet-auto-payouthas paid it: bondm_P's pending pool rewards and its free balance, lessEscrowandEntryEscrow, back into the pool (Compounded { pool_id, era, value, supply }: the minted shares' value and count after it, the share price for the era). While auto-payout is paused, nothing is known to be paid, so the pool waits. -
Settle each entry whose era was compounded, one by one:
- price it at the share price after compounding: its ORB was never bonded, so it is not part of the value it is priced against;
- bond its ORB from
m_P's free balance (bond_extra, orjoinfor the pool's first private entry); - mint its shares (
EntrySettled { pool_id, shares, commitment, owner_pk }andNoteMinted).
The entry is refunded at once instead when the pool is destroying, when it would receive fewer than
min_shares, or when the pool refuses the bond. Its ORB never leftm_P, so it is queued as an output already funded and paid in the same block, with no unbonding (EntryRefunded { pool_id, value, unlock_era, owner_pk }, whereunlock_erais the active era, thenExitSettledfor the ORB note). -
Wind down a destroying pool (Wind-down).
-
Withdraw each unlock era that has come, once:
withdraw_unbondedform_P, recording which share of what was owed it paid (Withdrawn { pool_id, value, paid }). The share is below one only if the unbonding stake was slashed. If staking refuses the withdrawal for now, the pool tries again next block. -
Pay the due outputs page by page: each exit's or refund's ORB note (
ExitSettled { pool_id, value, commitment, owner_pk }andNoteMinted) and each redeemed fee (FeesRedeemed).
An output that cannot be paid now stays queued and is tried again; nothing is skipped.
The share price
The pool's minted shares are worth netValue: what m_P's points are worth. Waiting entries hold
no points, so they are never part of it. With supply shares in existence and a virtual offset
V:
value(shares) = min( shares · (netValue + V) / (supply + V), shares · netValue / supply ) rounded down
shares(value) = value · (supply + V) / (netValue + V) rounded down
| Rule | Why |
|---|---|
V = 1 ORB of virtual value and virtual shares (VirtualOffset) | Inflating the first shares by donating to m_P costs more than it could take |
| Never above pro rata | Below a price of one, after a slash, the offset price would overvalue every share but the last |
| The last shares take everything left | value(supply) = netValue: no dust is stranded |
| Rounding favours the pool | Shares minted round down; value paid rounds down; a fee floor rounds up |
The price rises as compounding bonds rewards back, and falls with a slash; entries and exits buy and
sell at it, so they do not move it. Compounded announces value and supply after each era, so
the price history, and a pool's return over time, can be read from the events.
client.privateStaking.quote(poolId) reads supply, netValue and V, and privateShareValue,
privateSharesFor and privateMinFeeShares compute with them exactly as the runtime rounds.
Minted notes
Every output — an entry's shares, an exit's or a refund's ORB — is inserted by
ShieldedPool.mint_note as Poseidon4(value, asset_id, owner_pk, blinding), from the key and
blinding the action carried.
| Property | Detail |
|---|---|
| No memo | The chain stores none and emits NoteMinted { commitment, asset_id, value, leaf_index }. The wallet that chose the key recognises the note by recomputing the commitment from value and asset_id |
| No second proof | The output is computed by the chain, so it cannot be swapped and needs no signer |
| Funding | Shares are issued by the pallet; ORB (an exit's or a refund's) is transferred from m_P to the pool account |
| Collision | If a note with that value and key exists already, the value one or two units lower is minted instead. Past three attempts the output is dropped (OutputDropped) and its value stays with the other members |
The wallet derives a fresh key per action from its spending key and a counter, so the owner keys of two outputs are unrelated, and a restored wallet finds every output from its seed. See One-time bound keys and Minted notes.
Exiting
An exit is a bound spend of a share note of the pool, with amount the shares redeemed and
Exit { pool_id, owner_pk, blinding, min_value }. The action checks:
| Check | Error |
|---|---|
| The spent asset is this pool's share asset | WrongAsset |
owner_pk and blinding are non-zero field elements | InvalidKey |
shares > 0 and shares + fee within the supply | NothingToRedeem, SharesExceedSupply |
What is left of m_P's membership is zero or at least MinJoinBond, unless every other share is dust (worth less than MinSpendFee): then the last holder unbonds all of m_P and takes the dust | RemainderBelowMinimum |
| A nominating pool keeps its stake at the nominator minimum, or none | RemainderBelowMinimum |
m_P has room for another unbonding chunk (MaxUnbonding), unless one exists for this unlock era | TooManyUnbonding |
The shares are worth at least min_value now | BelowMinimumOutput |
Then the shares are burned and their value unbonded from m_P, unlocking after the nominator
unbonding time (2 eras). An exit that leaves only its own fee's shares takes the whole minted value
less what the fee is worth. The exit is queued for its unlock era and Exited { pool_id, shares, value, unlock_era, owner_pk } is emitted. When the era is withdrawn, the ORB note is minted: its promised
value, scaled down by the era's paid share if the unbonding stake was slashed.
Shares can move between notes by private transfer, so an exit need not mirror an entry's amount.
Fees
A bound spend pays its fee from the spent note, in the note's asset:
| Spend | Fee |
|---|---|
| Entry (ORB note) | At least MinSpendFee, credited to the block author as pending ORB, like any spend |
| Exit, or a private transfer of shares | At least the shares worth MinSpendFee, rounded up and at least one. Redeemed at once for the author: the shares are burned, their value unbonded, and paid in ORB to the validator's public account when it unlocks (FeesRedeemed). A fee that cannot be redeemed at once is credited as pending shares, redeemed later by claim_fees |
The fee is credited after the action runs, so the action is checked against the state the admission check saw. See Fees in share assets.
Wind-down
When the nomination pool goes into Destroying, its private side winds down in on_idle:
- Every waiting entry is refunded at once (
EntryRefunded): its ORB was never bonded, so it is paid back in the same block. m_Punbonds everything left (chilling the pool first if its stake must stay at the nominator minimum), and the shares' value is fixed: what its points were worth plus its free balance (WindingDown { pool_id, value, unlock_era }).- Exits keep working against that fixed value, paid once the unbonding is withdrawn; afterwards they are paid in the next settlement.
- Once no shares, entries, unlocks or membership are left, the private side is forgotten
(
PoolClosed), and a new pool with the same id can open to private members again.
Events
| Pallet | Events |
|---|---|
ShieldedPool | BoundSpent, NoteMinted, and for share-asset fees FeesClaimed |
PrivateStaking | PrivateMembersSet, Entered, Exited, Compounded, EntrySettled, EntryRefunded, ExitSettled, OutputDropped, FeesRedeemed, Withdrawn, WindingDown, PoolClosed, MinEntrySet |
Their fields, phases and order are in Indexing Events.
What is public
| Public | Hidden |
|---|---|
Which pools are private, their share asset and m_P | Who enters or exits: each action is an unsigned spend with a nullifier |
| Each entry's pool, ORB amount and era; each exit's pool, shares, value and unlock era | Which note paid for an entry, and which share note an exit spent |
Each action's one-time output key (owner_pk), in the action and in every event of that entry or exit, so an entry can be followed to its settlement or refund | Whose key it is: it is derived for one action and unrelated to the wallet's address or its other keys |
| Each minted note's commitment, asset and value | Who owns a minted note: its owner key is a one-time key unrelated to the wallet's address |
| The pool's private total, share supply and price, era by era | Any member's balance or history |
| The block author paid each redeemed fee | Who paid it |
In a pool with few private members, amounts and timing can link an entry to its shares, or an exit to an earlier entry: each pool's members form their own anonymity set. Round amounts, splitting, spacing actions and moving shares between notes before an exit all widen it.
Parameters and errors
| Parameter | Value |
|---|---|
PrivateStakingId | orb/pstk |
VirtualOffset | 1 ORB |
MinEntry | 10 ORB by default; set by the staking admin origin with set_min_entry, never below MinJoinBond |
MaxQueue × MaxPages | 256 × 32 entries per pool per era |
| Idle weight | At most 10 % of the maximum block weight |
| Exit unlock | The active era plus the nominator unbonding duration (2 eras) |
| Error | Cause |
|---|---|
NoSuchPool | No such nomination pool |
NotRoot | set_private from an account that is not the pool's root |
NotPrivate | The pool is not open to private entries, or was never opened |
PoolNotOpen | The pool takes no new members (blocked or destroying), or its private side wound down |
BelowMinimum | Below MinEntry, or below the pool's join minimum for its first private entry |
QueueFull | This era's entry queue for the pool is full |
InvalidKey | The owner key or blinding is zero or not a field element |
WrongAsset | The spent asset is not the one the action takes |
NothingToRedeem | The shares are worth nothing |
RemainderBelowMinimum | The exit would leave the membership or the pool's stake below its minimum |
TooManyMembers | The pool or the pools pallet is full |
BelowMinimumOutput | The shares are worth less than min_value |
PoolSlashed | The pool was slashed past MaxPointsToBalance |
TooManyUnbonding | m_P has as many unbonding chunks as it can hold |
SharesExceedSupply | More shares than the pool has issued |
Inside a bound spend, any of these surfaces as ShieldedPool.InvalidBoundAction.
Related
- Private Pools — entering and leaving a private pool in the app
- Private Staking with the SDK — reading private pools, and what the wallet does to enter and exit
- Keys & Identity — one-time bound keys
- Note Discovery — how the wallet finds minted notes
- Spend Fees — fees paid in shares
- Indexing Events — the events and their order
- Unshield Circuit — the proof a bound spend reuses