osToken Redemptions

Redemptions are an in-protocol peg-maintenance mechanism that converts osToken back to ETH or GNO at the protocol exchange rate.

Every osToken is minted against Vault collateral (the user's stake in the Vault) and must remain backed by that collateral. The minter takes on a corresponding debt against their Vault collateral and can burn the osToken at any time to repay the debt and withdraw their stake.

If the minter transfers the osToken away, the minter's on-chain debt in the Vault is unchanged. From the protocol's perspective: the minter owes X osToken worth of debt, but only Y < X is still in their hands. The delta X − Y is what the protocol calls redeemable — osToken that exists somewhere but is no longer tied to the minter.

Redemption burns the missing portion of the minter's debt against their collateral and releases the corresponding ETH/GNO at the protocol exchange rate.

How Redemptions Work

The redemption flow is coordinated between five actors: osToken holders, who supply the osToken to redeem by entering the redeemer's exit queue; the Operator Service ↗, which computes who can be redeemed and by how much, and executes the redemptions on-chain as the redeemer's positionsManager; StakeWise, which authorizes the list of redeemable positions on-chain; the Oracle network, which keeps Vault state current and forces validator exits when queued redemptions go unfilled; and the OsTokenRedeemer ↗ contract, which verifies and settles them.

The flow draws on two independent tracks that converge once both are ready: the Operator Service publishes the list of redeemable positions (Step 1), while osToken holders queue osToken for redemption (Step 2). The remaining steps consume both. In full, it runs in eight steps:

1. Operator Service Computes the Redeemable Positions

The Operator Service uploads the list of eligible positions to IPFS ↗ and builds a Merkle tree that commits to each entry. StakeWise then submits the root and IPFS hash on-chain to authorize the listed positions for redemption.

Under the Hood

The Operator Service computes the redeemable positions in five steps:

1. Pin the snapshot to a finalized block so all the following steps read the same on-chain state.
2. Fetch all allocators (addresses that have minted osToken) from the subgraph.
3. Skip Boost positions. Each Boost leverage position has its own proxy contract that holds the osToken on the user's behalf, so those proxy addresses are removed from the minters list, and each user's leveraged shares are subtracted from their balance to avoid double-counting.
4. Compute kept shares — osToken in trackable locations: wallet balances on the Vault's own chain and DeFi protocols on that chain indexed by DeBank or Rabby. Anything held elsewhere, including on other chains, is treated as missing.
5. Compute redeemable = minted − kept, split it across the user's Vaults proportionally to where they minted, and sort by LTV descending then amount descending so the riskiest positions are drawn down first.

2. osToken Enters the Queue

Anyone holding osToken can enter the redeemer's exit queue — there is no whitelist and no privileged role. enterExitQueue is permissionless: the caller approves (or permits ↗) their osToken to the OsTokenRedeemer, and the contract pulls the shares in and issues a ticket — a unique cumulative index recording the entry's place in the queue and how much is owed — carrying the right to claim ETH/GNO later.

In practice this is done from the main page of app.stakewise.io ↗, which wraps the approval and the queue entry into a single flow.

This is what maintains the peg. Redemption pays out at the protocol exchange rate, so whenever osToken trades below that rate on the secondary market, buying it and redeeming it through the queue is profitable. That arbitrage is open to anyone, and it is what pulls the market price back toward the protocol rate.

3. Operator Service Prepares the Next Redemption

The Operator Service monitors the on-chain state. If a previous redemption round has redeemed ETH/GNO that is waiting to be checkpointed, it first calls processExitQueue to finalize that batch so the assets become claimable.

It then checks whether there's enough queued osToken to submit a new redemption.

4. Operator Service Submits a Redemption

The Operator Service downloads the published list from IPFS, picks a batch of eligible positions, and decides how much to redeem from each. If a target Vault is a MetaVault without enough liquidity on hand, the Operator Service first pulls assets up from sub-vaults via a separate redeemSubVaultsAssets transaction. It then refreshes the state of the target Vaults in a separate multicall transaction, builds a Merkle multiproof against the published root, and calls redeemOsTokenPositions on OsTokenRedeemer for each position.

The state refresh is only possible because the Oracles have voted on and signed a rewards root: a Vault that has fallen more than one reward update behind cannot be redeemed from until it is harvested against that root. See Reward Distribution.

The redemption is now in flight; verification and execution happen on-chain.

5. Oracles Force Exits if the Queue Stalls

A Vault can only pay out what it holds in liquid assets, so a redemption is capped by the Vault's withdrawable balance. Operator Services set aside the assets their Vaults owe to the redeemer before registering new validators, which normally keeps enough on hand. When it does not — the Vault has everything staked, or its Operator Service is unresponsive — the Oracle network steps in and forces validator exits until the queue can be filled.

This is the same enforcement that backs the Vault exit queue, applied to redemption demand instead of withdrawal requests.

Under the Hood

Every cycle, each Oracle records the redeemer's cumulative exit queue ticket. It then looks up the ticket as it stood one forced withdrawals period ago and calls getExitQueueMissingAssets on it — whatever is still unfilled after that grace period is a shortfall the Vaults have to cover.

The shortfall is padded by a small multiplier (1.0023 by default) to absorb the osToken exchange rate rising while the assets are exiting, then split across Vaults using the same published positions list. Each Vault's share is added to its withdrawal demand, and the Oracles release the exit signature shards for as many of its validators as it takes to cover the amount.

6. OsTokenRedeemer Executes the Redemption

The contract rebuilds each leaf, verifies the Merkle multiproof against the stored root, and caps the amount independently per position. For each verified position, it calls the Vault's redeemOsToken to burn the minter's osToken debt and send the equivalent ETH/GNO (using the Vault's just-updated state) to the redeemer.

The queued shares are now matched against missing positions — settled, but not yet claimable.

7. Batch Is Checkpointed

Once the configured delay has elapsed — 12 hours on both Ethereum and Gnosis — processExitQueue creates a new checkpoint that matches the redeemed shares to their ETH/GNO and marks the assets as claimable. This call is also permissionless, so anyone can trigger it; in practice the Operator Service does. Tickets that fall within this checkpoint can now be claimed.

Dive Deeper: The Exit Queue and Checkpoints

The queue

Not the Vault Exit Queue

This is the OsTokenRedeemer's own exit queue, independent of the Vault exit queue.

When osToken enters the queue, the assets aren't released right away. The contract tracks this line with a single number, the positionTicket:

positionTicket = (all previously processed shares) + (shares already queued ahead)

The queue clears in one of two ways, both of which move shares out of queued and pair them with assets:

• Redemption — the Operator Service redeems the queued shares against the published redeemable positions (Steps 4–5), drawing ETH/GNO out of the Vaults.
• Swap — anyone can call swapAssetsToOsTokenShares (sending ETH, or approving GNO on Gnosis) to take queued osToken off the front of the queue at the protocol exchange rate. This fills the queue directly, without touching any minter's position.

Either way the shares are matched with ETH/GNO but can't be claimed yet — that requires a checkpoint.

Checkpoints

A checkpoint is a snapshot that says: "at this point in the queue, this many shares were exchanged for this many assets." When a ticket is claimed, the checkpoint covering it tells the contract:

• how many tickets it now covers (marked exited),
• and how many assets those tickets are worth, at the rate the checkpoint locked in.

If only some of the ticket is covered and the rest is still queued, the contract pays out the covered portion and rolls the remainder into a new exit request at the next ticket. The rest can be claimed after the next checkpoint.

8. ETH/GNO Is Claimed

The ticket holder calls claimExitedAssets with their ticket and the matching checkpoint index, and the contract pays out the corresponding ETH/GNO. If the ticket spans more than one checkpoint, the covered portion is paid out and the remainder rolls into a new ticket that can be claimed after a later checkpoint.

Deep Dive

For more details on how Oracles distribute rewards and enforce validator exits, see Oracle Duties →.