Instructions

posl_initialize#

Creates the pool once: state, the three trees, epoch 0 (opened), and the vault. Checks: the signer is the admin written in the program (mainnet, devnet); check_params; on mainnet the mint must be the ZEC SPL mint A7bdiYdS5GjqGFtxf17ppRHtDKPkkRqbKtR27dxvQXaS (WrongMint).

posl_update_params#

Admin only (has_one = authority). Runs check_params, refuses a new epoch length, and stores the parameters as pending. posl_advance_epoch applies them after the delay (Admin powers).

posl_set_paused#

Admin only (has_one = authority), immediate. Sets paused. While paused, posl_transact refuses a deposit (ext_amount > 0) and posl_lock refuses every lock (Paused). Withdrawals, private transfers, unlocks and claims are not touched (Admin powers).

posl_advance_epoch#

Permissionless. Opens epoch = current + 1 once now >= genesis_ts + epoch_len * epoch (WrongEpoch, EpochNotOver). Applies a due pending parameter change, removes the locks that ended with the previous epoch from active_stake, and snapshots active_stake and stake_start_index for the new epoch. Creates the epoch account if a lock has not created it already.

posl_fund#

Anyone adds ZEC to the current epoch's budget, split by stake_share_bps. Amount must be above 0.

posl_finalize_epoch#

Permissionless. For an epoch before the current one, opened and not yet finalized: fixes stake_rate and volume_rate, records what they allocate, rolls the rest into the current epoch, adds the allocation to total_allocated and emits PoslEpochFinalized.

posl_transact#

Deposit (ext_amount > 0), withdrawal (< 0) or private transfer (= 0) through the unmodified core circuit transaction2. Checks, in order: clean logs; the signer owns signer_token_account; the root is known; publicAmount = ext_amount - fee (a deposit must exceed its fee); the fee matches the deposit or withdrawal rate within the margin; the credit key and blinding are field elements; the proof, with the ext data hash computed on chain. Then: moves tokens (deposit capped by max_deposit_amount), pays the relayer share of the fee, adds the protocol share to the epoch budgets, appends both outputs to the main tree, and appends a volume credit worth credit_value(fee) to the credit tree when above 0. The credit blinding is the first input nullifier (unique and already public).

posl_lock#

Moves a denomination from the main tree to the stake tree. Checks: clean logs; denom is one of the pool's denominations (InvalidDenomination); current < lock_epoch <= current + max_lock_epochs (InvalidLockEpoch); fee <= max_relayer_fee; known root; the lock proof. Then: pays the fee to the relayer, appends the change note (main) and the locked note (stake), adds the size to the end epoch's expiring, to active_stake and to total_locked.

posl_unlock#

Returns a locked note after its end epoch. Checks: clean logs; fee <= max_relayer_fee; known stake root; the unlock proof with the current epoch as public input (the circuit proves lockEpoch < currentEpoch). Creates the unlock marker, pays the fee, appends the output note.

posl_claim_stake#

One locked note, one finalized epoch (NotFinalized). The proof uses the epoch's stake_start_index and stake_rate as public inputs. Creates the reward marker ["posl_rnf", reward_nullifier], appends the reward note, counts the claim.

posl_claim_volume#

Up to four credit notes of one finalized epoch. The proof uses the epoch's volume_rate; the circuit refuses a reward of 0. Creates four credit markers, appends the reward note, counts the claim.