Stake
Rewards
How a proven batch's clearing fee reaches a stake, and how to claim it.
A stake earns from the clearing fee of every batch its solver proves. The fee is split when the proof verifies, the stakers' part is credited to a running total on the solver, and each stake claims its part in the tokens the fee was paid in.
Where a reward comes from
Each filled order pays the clearing fee out of what it receives, so a batch carries one fee amount per token, in atoms of that token. The solver posts those amounts with the clearing and the proof commits to them. The batch page shows them in the Clearing fee column, and una.batch(id) returns them as prices[].feeAmount.
prove_batch splits each token's fee the moment the proof verifies:
protocol_fee = floor(fee * protocol_fee_share_bps / 10000) solver_fee = fee - protocol_fee commission = floor(solver_fee * commission_bps / 10000) staker_fee = solver_fee - commission
feeu64- The batch's clearing fee in one token, in atoms.
protocol_fee_share_bpsu16- The protocol's share, from the program's Config.
una.protocol()returns it asprotocolFeeShareBps. commission_bpsu16- The solver's commission, set when it registered.
una.solver(address)returns it ascommissionBps.
protocol_fee goes to the fee recipient in the same instruction. Fees and UNA says what happens to it. commission is added to the operator's balance for that token. staker_fee goes to the stakers. All three stay in the token the fee was paid in. Both divisions round down, so the stakers' part keeps the remainder.
The clearing fee rate is clearingFeeBps in una.protocol(). Fees has what one order pays.
const protocol = await una.protocol()
console.log(`clearing fee ${protocol.clearingFeeBps} bps, protocol share ${protocol.protocolFeeShareBps} bps, commission ${solver.commissionBps} bps`)How it is credited
The solver's account keeps one accumulator per listed token, reward_per_share, a Q64.64 number: atoms of that token earned per lamport of reward weight since the solver registered. prove_batch raises it:
reward_per_share[token] += floor(staker_fee * 2^64 / total_bond_weight)
total_bond_weight is the sum of the reward weights of all the solver's stakes, in lamports. A stake's weight is what its deposits were worth in SOL when they were made, across every bond mint. Stake behind a solver says how a deposit sets it.
A stake remembers the accumulator's value at its last sync as reward_debt. A sync adds what it earned since then to pending_rewards, one balance per token:
earned[token] = floor((reward_per_share[token] - reward_debt[token]) * reward_weight / 2^64)
The program syncs a stake in every instruction that touches it: stake on an existing stake, request_unstake, withdraw_stake and claim_rewards. The accumulator holds what a stake earns between syncs.
A stake's part of one batch is therefore reward_weight / total_bond_weight of that batch's staker_fee, in each token the batch paid fees in. A stake in a liquid staking token earns the same tokens as a stake in SOL.
When a solver has no stake weight, or the stakers' part of a token is zero, the whole solver_fee for that token is added to the operator's commission balance.
A worked batch
Sample inputs: a batch's fee in one token is 50,000,000 atoms, the protocol share is 2,000 basis points, the solver's commission is 1,000 basis points, the solver's total weight is 5,000,000,000 lamports, and one stake has a weight of 3,000,000,000.
| Step | Arithmetic | Result |
|---|---|---|
| Protocol fee | 50,000,000 × 2,000 / 10,000 | 10,000,000 atoms |
| Solver fee | 50,000,000 − 10,000,000 | 40,000,000 atoms |
| Commission | 40,000,000 × 1,000 / 10,000 | 4,000,000 atoms |
| Staker fee | 40,000,000 − 4,000,000 | 36,000,000 atoms |
| Accumulator rises by | floor(36,000,000 × 2^64 / 5,000,000,000) | 132,816,557,330,708,771 |
| This stake earns | floor(132,816,557,330,708,771 × 3,000,000,000 / 2^64) | 21,599,999 atoms |
Three fifths of 36,000,000 is 21,600,000. The two divisions each round down, and the stake is credited one atom less.
Claim rewards
On /stake, under Your stakes, the Rewards column shows what a stake can claim, valued in SOL, or None yet. A stake with rewards has a Claim rewards button on its row. Press it and sign. The same row is on the solver's page under Your stake here.
One press claims every token the stake has rewards in. The tokens arrive in the wallet's own token accounts.
const { items: earning } = await una.stakes()
for (const s of earning) {
if (s.rewardsClaimableLamports === '0') continue
const claimed = await una.claimRewards(s.address)
console.log(`claimed rewards of ${s.address} in ${claimed.signature}`)
}una.claimRewards(stakeAddress) takes the stake's address. The API reads the stake and its solver from the chain, and for every listed token in which the stake has pending or newly earned rewards it puts two instructions in one transaction: one that creates the wallet's associated token account for that token if it does not exist, and one claim_rewards for that token. The call signs, submits and follows the transaction, and resolves with build, tx and signature.
When no token has anything to claim the API answers NOTHING_TO_CLAIM and builds nothing.
The claim_rewards instruction
One instruction claims one token.
Arguments
token_indexu16required- The index of the listed token to claim, below 32.
una.tokens()returns each token'sindex. is_operator_commissionboolrequiredfalseclaims a stake's rewards.trueclaims the solver operator's commission.
The signer is owner. The payout moves from the program's vault for that token to the signer's associated token account for its mint, and the program accepts no other destination.
With is_operator_commission = false the program checks that the stake account is a Stake of this program, that it is behind the solver passed, and that its owner is the signer. It syncs the stake, pays pending_rewards[token_index] in full and sets it to zero.
With is_operator_commission = true the signer is the solver's operator. The program pays operator_commission[token_index] in full and sets it to zero. It does not read the stake account in this case. Commission and payouts covers the operator's side.
It emits RewardsClaimed with solver, owner, token_index, amount and is_operator_commission.
Errors
| Error | Raised when |
|---|---|
InvalidIndex | token_index is 32 or more. |
Unauthorized | The destination is not the signer's associated token account for the token. For a stake's rewards: the stake account is not a Stake of this program, is behind another solver, or has another owner. For commission: the signer is not the solver's operator. |
NothingToClaim | The balance for that token is zero after the sync. |
What it costs
The program takes no fee on a claim. The wallet pays the network fee and, for a reward token it has never held, the rent of a new token account.
Rewards through an unstake
Requesting an unstake leaves a stake's reward weight as it is, so the stake goes on earning through the cooldown. withdraw_stake syncs the stake and then lowers its weight. Rewards already in pending_rewards stay there after a withdrawal until they are claimed. Unstaking and the cooldown has the steps.