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:

Text
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 as protocolFeeShareBps.
commission_bpsu16
The solver's commission, set when it registered. una.solver(address) returns it as commissionBps.

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.

TypeScript
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:

Text
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:

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

StepArithmeticResult
Protocol fee50,000,000 × 2,000 / 10,00010,000,000 atoms
Solver fee50,000,000 − 10,000,00040,000,000 atoms
Commission40,000,000 × 1,000 / 10,0004,000,000 atoms
Staker fee40,000,000 − 4,000,00036,000,000 atoms
Accumulator rises byfloor(36,000,000 × 2^64 / 5,000,000,000)132,816,557,330,708,771
This stake earnsfloor(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.

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's index.
is_operator_commissionboolrequired
false claims a stake's rewards. true claims 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

ErrorRaised when
InvalidIndextoken_index is 32 or more.
UnauthorizedThe 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.
NothingToClaimThe 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.