Stake
Unstaking and the cooldown
Request an unstake, wait out the cooldown, and withdraw the deposit.
Leaving a solver takes two instructions with a wait between them. request_unstake marks shares of a stake as leaving and starts the cooldown. withdraw_stake pays them out once the cooldown has passed.
The statuses of a stake
una.stakes() gives every stake one of three statuses, and the app shows the same three.
| Status | In the app | The stake is | What moves it on |
|---|---|---|---|
staked | Staked | Holding shares with no unstake requested. | request_unstake moves it to unstaking. |
unstaking | Unstaking, with the time left | Holding shares marked as leaving, before their unlock slot. | The chain reaching the unlock slot moves it to withdrawable. |
withdrawable | Withdrawable | Holding shares marked as leaving, at or past their unlock slot. | withdraw_stake pays them out and moves it to staked. |
A stake account stays open after a withdrawal. A stake that requested only part of its shares reports unstaking and then withdrawable while the rest of its shares stay staked, and returns to staked with those after the withdrawal.
While an unstake is in progress the stake carries an unstakeRequest with unlockSlot, unlockAt, slotsLeft, secondsLeft and withdrawable. The fields are under UnstakeRequest.
The cooldown's length
The cooldown is unstake_cooldown_slots in the program's Config, a number of slots above zero that the admin sets with set_config. Una sets it to one proof window: 300 slots by default, about 60 seconds at 200 ms a slot. una.protocol() returns the live value as unstakeCooldownSlots.
console.log(`cooldown: ${protocol.unstakeCooldownSlots} slots of ${protocol.slotMs} ms`)The unlock slot is fixed when the request lands:
unlock_slot = slot of the request + unstake_cooldown_slots
A batch's proof deadline is its clearing slot plus the proof window. With the cooldown at one proof window, every batch the solver cleared before the request has reached its proof deadline by the unlock slot.
Request an unstake
On /stake, under Your stakes, a stake with the status Staked has an Unstake button. Press it and sign. The button requests the stake's whole staked amount. The status becomes Unstaking with the time left beside it.
// `amount` is in atoms of the bond mint. The stake's whole staked amount requests all of it.
const requested = await una.requestUnstake(stake.address, { amount: stake.stakedAmount })
console.log(`unstake requested in ${requested.signature}`)una.requestUnstake(stakeAddress, body)
stakeAddressaddressrequired- The stake's account,
addressinuna.stakes(). amountu64 string, above 0required- How much to unstake, in atoms of the bond mint. A stake's
stakedAmountrequests all of it.
The API converts the amount to the instruction's shares at the pool's rate when it builds the transaction: floor(amount * pool_shares / pool_amount), at least 1 share, and all of the stake's shares when amount is its whole staked amount. It answers INSUFFICIENT_BALANCE when amount is more than the stake is worth.
The call signs, submits and follows the transaction, and resolves with build, tx and signature.
The request_unstake instruction
Arguments
sharesu64required- Shares of the solver's pool to mark as leaving. Above zero and no more than the stake holds.
The owner signs. For a stake in a liquid staking token the stake pool account is passed and checked as it is in stake. The program then:
- Syncs the stake's rewards.
- Values the shares now:
est_tokens = floor(shares * pool_amount / pool_shares), andest_lamportsis that amount at the current rate. - Moves
sharesfrom the stake'ssharesto itsunstake_shares. - Adds
est_lamportsto the stake'sunstake_lamports_reservedand to the solver'spending_unstake_lamports. - Sets
unstake_unlock_slotto the current slot plusunstake_cooldown_slots.
No tokens move. It emits UnstakeRequested with stake, solver, owner, shares and unlock_slot.
A stake has one unlock slot. A second request while one is in progress adds its shares to unstake_shares and sets the unlock slot again from the slot of the second request, for all of them.
| Error | Raised when |
|---|---|
ZeroLiquidity | shares is 0. |
Unauthorized | The signer is not the stake's owner. |
InsufficientStake | shares is more than the stake's shares. |
InvalidStakePool | The stake is in a liquid staking token and the stake pool account passed is not the listed one or fails the checks on its rate. |
MathOverflow | A sum or product leaves 64 bits. |
During the cooldown
Shares between the request and the withdrawal stop backing new batches at once. A solver's free bond is its pools valued in lamports, less the bond locked behind cleared batches, less pending_unstake_lamports. clear_batch locks bond only from what is free, so the reserved lamports are out of every clearing after the request.
They keep earning. The stake's reward weight does not change until withdraw_stake, so the stake is credited its full part of every batch the solver proves during the cooldown. Rewards has the arithmetic.
They stay in the pool. The shares still count in the solver's pool for that mint, and a slash lowers the pool's amount for every share in it, the leaving ones included. The withdrawal pays what the shares are worth at the moment of the withdrawal. Slashing and cover has how much a slash takes.
Withdraw
When the time left reaches zero the status becomes Withdrawable and the row's button becomes Withdraw. Press it and sign. The deposit arrives in the wallet's token account for the bond token.
let current = (await una.stakes({ solver: solver.address })).items.find((s) => s.address === stake.address)!
while (current.status === 'unstaking') {
await new Promise((r) => setTimeout(r, 1000 * Math.max(1, current.unstakeRequest?.secondsLeft ?? 1)))
current = (await una.stakes({ solver: solver.address })).items.find((s) => s.address === stake.address)!
}
if (current.status === 'withdrawable') {
const withdrawn = await una.withdrawStake(stake.address)
console.log(`withdrawn in ${withdrawn.signature}`)
}una.withdrawStake(stakeAddress) takes the stake's address. The transaction first creates the wallet's associated token account for the bond mint if it does not exist, then sends withdraw_stake.
The withdraw_stake instruction
It takes no arguments and pays out all of the stake's unstake_shares. The owner signs.
payout = floor(unstake_shares * pool_amount / pool_shares)
payout atoms of the bond mint move from the solver's vault to the owner's associated token account for that mint, and the program accepts no other destination. A stake in SOL is paid in wrapped SOL.
The same instruction:
- Syncs the stake's rewards before anything changes.
- Takes
payoutfrom the pool's amount andunstake_sharesfrom the pool's shares. - Takes the stake's
unstake_lamports_reservedoff the solver'spending_unstake_lamports. - Lowers the stake's reward weight by
floor(reward_weight * unstake_shares / (shares + unstake_shares))and the solver's total weight by the same. - Sets
unstake_shares,unstake_lamports_reservedandunstake_unlock_slotto zero.
It emits StakeWithdrawn with stake, solver, owner, bond_mint_idx, shares and amount.
Rewards are a separate claim. A withdrawal leaves the stake's pending_rewards in place, and claim_rewards pays them after it as before.
| Error | Raised when |
|---|---|
Unauthorized | The signer is not the stake's owner, or the destination is not the owner's associated token account for the bond mint. |
NothingToClaim | The stake has no unstake_shares. |
CooldownActive | The current slot is before unstake_unlock_slot. |
UnsupportedBondMint | The mint or token program passed is not the one listed for the stake's bond mint. |
MathOverflow | A product leaves 64 bits. |
What it costs
The program takes no fee on a request or a withdrawal. The wallet pays the network fee of each, and the rent of a token account for the bond mint if it has none when it withdraws.