osToken redemptions

docs/docs/ostoken/intro.mdx

@@ -1,21 +1,19 @@
 ---
 title: osToken
-description: Learn what osToken is and how to get it
+description: osToken is StakeWise's liquid, overcollateralized staking token on Ethereum and Gnosis.
 ---
 
 import Image from '@theme/IdealImage'
 
 # osToken
 
-osToken is a liquid staking token that accrues staking rewards when held. It is a generic name for StakeWise's network-specific ERC-20 tokens:
+Staked ETH and GNO earn rewards, but the stake itself is a non-transferable share of the staking pool. osToken turns that stake into a transferable asset that can be [used across DeFi](https://app.stakewise.io/ecosystem) to earn additional rewards.
+
+osToken is the generic name for StakeWise's network-specific liquid staking ERC-20 tokens:
 
 - **osETH** on Ethereum
 - **osGNO** on Gnosis Chain
 
-<Image img={require('./img/osToken_intro.png')} alt="osToken overview - liquid staking token for StakeWise" />
-
-osToken is issued against assets staked in a Vault to allow using staked capital in decentralized applications to trade, borrow, lend, and restake. Hence, osTokens represent the underlying staked assets and the rewards earned.
+osToken is overcollateralized: more ETH or GNO is always staked than osToken issued. osToken is a repricing token: it accrues staking rewards by appreciating against the underlying asset, rather than increasing the token balance in the user's wallet.
 
-Short for **Overcollateralized Staked Token**, osToken requires that the value of staked assets exceed the value of osToken issued. This overcollateralization acts as a safety buffer, protecting holders and the protocol from validator penalties or underperformance of permissionless Vaults.
-
-A defining feature is that osToken can be minted against validators run by anyone – from solo stakers to professional operators – making access to liquid staking fully permissionless and non-custodial.
+<Image img={require('./img/osToken_intro.png')} alt="osToken overview - liquid staking token for StakeWise" />

docs/docs/ostoken/ostoken-redemptions.mdx

@@ -0,0 +1,95 @@
+---
+title: osToken Redemptions
+description: How osToken redemptions work under the hood.
+---
+
+import Admonition from '@theme/Admonition';
+import Image from '@theme/IdealImage';
+
+# osToken Redemptions
+
+Redemptions are a protocol-internal peg-maintenance mechanism that converts osToken back to ETH/GNO at the protocol exchange rate.
+
+Every osToken is minted against Vault collateral 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. The protocol's invariant is **total osToken supply = total debt**.
+
+If the minter transfers the osToken away, the minter's on-chain debt 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 a 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
+
+<Image img={require('./img/redemptions.png')} alt="redemptions flow" />
+
+The redemption flow is a coordinated process between the [Operator Service ↗](https://github.com/stakewise/v3-operator) and the [OsTokenRedeemer ↗](https://etherscan.io/address/0xc43A7b16A7a167c0318390Cba16787C11e9e1FD0) contract.
+
+The Operator Service has two responsibilities:
+
+1. **Computes redeemable positions** — the "who can be redeemed, and by how much" calculation. It uploads the list of eligible positions to [IPFS](https://ipfs.stakewise.io/ipfs/bafkreihbwhyaqskcczhuanu2nbdgdlfbwfwgbirue6kvlw4nrc5d2snqxa) and computes a Merkle tree that commits to each entry. StakeWise then submits the root and IPFS hash on-chain, incrementing the `nonce` — a version tag baked into every entry of the list, so bumping it automatically invalidates every proof from the previous version.
+
+2. **Processes redemptions** — runs a loop that reads and writes to `OsTokenRedeemer`. When the redemption conditions are met, it fetches all positions from IPFS, decides how much to redeem from each position, builds a Merkle multi-proof, and submits a multicall that refreshes Vault state and calls `redeemOsTokenPositions`. The Operator Service runs from the `positionsManager` address set by StakeWise.
+
+The `OsTokenRedeemer` is the on-chain contract that holds all redemption state: the published Merkle root and IPFS hash, the nonce, per-position redemption progress, and the exit queue. It also executes the redemption itself: verifies the Merkle proofs, calls each Vault's `redeemOsToken` to burn the minter's debt and release the corresponding ETH/GNO, and manages the exit queue.
+
+:::custom-notes[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](../vaults/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: mainnet, Arbitrum, and DeFi protocols indexed by DeBank or Rabby. Anything else 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.
+:::
+
+## Flow
+### 1. osToken Enters the Queue
+
+osToken is sent to the `OsTokenRedeemer` contract and a ticket is issued — a unique cumulative index recording the entry's place in the queue and how much is owed. The entry now carries the right to claim ETH/GNO later.
+
+### 2. Operator Service Prepares the Next Redemption
+
+The Operator Service monitors the on-chain state. If a previous redemption round has redeemed ETH/GNO 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.
+
+### 3. 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 builds a Merkle multiproof against the published root and submits a multicall to `OsTokenRedeemer` that refreshes Vault state and calls `redeemOsTokenPositions`.
+
+The redemption is now in flight; verification and execution happen on-chain.
+
+### 4. 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 (using the Vault's just-updated state) to the redeemer.
+
+The queued shares are now matched against missing positions — settled, but not yet claimable.
+
+### 5. Batch Is Checkpointed
+
+Once the configured delay has elapsed, `processExitQueue` is called and the contract creates a new checkpoint that matches the redeemed shares to their ETH/GNO and marks the assets as claimable. Tickets that fall within this checkpoint can now be claimed.
+
+:::custom-notes[Dive Deeper: The Exit Queue and Checkpoints]
+
+**The queue**
+
+**Note:** 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 drains as the contract processes redemptions, moving shares from *queued* to *redeemed*. Redeemed 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 of its tickets are now exited (covered by the checkpoint),
+- 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.
+:::
+
+### 6. ETH/GNO Is Claimed
+
+`claimExitedAssets` is called with the ticket and the matching checkpoint index. The contract pays out the corresponding ETH/GNO; if the ticket spans more than one checkpoint, a residual is left for future rounds.

docs/docs/stakewise-protocol/what-is-stakewise.mdx

@@ -66,7 +66,7 @@ The decentralized Oracle network connects StakeWise smart contracts to Ethereum'
 
 - **Validator Lifecycle**: Manages validator registration, consolidations, rewards, penalties, and exits.
 
-- **Token Stability**: Maintains accurate osToken exchange rates and safeguards peg stability. [Learn more →](../ostoken/how-ostoken-works#reward-accrual--fee-mechanism)
+- **Token Stability**: Maintains accurate osToken exchange rates and safeguards peg stability. [Learn more →](../ostoken/how-ostoken-works#exchange-rate)
 
 :::custom-notes[Deep Dive]
 Learn more about [Oracles →](../oracles/intro)

operator/start-operator.mdx

@@ -10,7 +10,7 @@ import { CheckItem } from '@site/src/components';
 
 # Start Operator
 
-## Setup Checklist <img src="/icons/stakewise/tick.png" alt="tick" style={{width: '36px', height: '36px', verticalAlign: 'middle', display: 'inline'}} />
+## Setup Checklist <img src="/icons/sw_rocket.gif" alt="rocket" style={{width: '36px', height: '36px', display: 'inline', verticalAlign: 'middle'}} />
 
 Before starting the Operator Service, confirm that everything is in place:
 

sidebars.ts

@@ -42,6 +42,7 @@ const sidebars: SidebarsConfig = {
       },
       items: [
         'docs/ostoken/how-ostoken-works',
+        'docs/ostoken/ostoken-redemptions',
       ],
     },
     {

staker/risks.mdx

@@ -19,7 +19,7 @@ All DeFi protocols carry smart contract risk. StakeWise runs on battle-tested, [
 
 ## osETH Depeg
 
-osETH could temporarily trade below its fair value on secondary markets. The protocol's [redemption and liquidation mechanisms](/docs/ostoken/how-ostoken-works#peg-maintenance) create arbitrage incentives that keep the market price aligned with the underlying value.
+osETH could temporarily trade below its fair value on secondary markets. The protocol's [redemption](/docs/ostoken/how-ostoken-works#redemption) and [liquidation](/docs/ostoken/how-ostoken-works#liquidation) mechanisms create arbitrage incentives that keep the market price aligned with the underlying value.
 
 ## Boost
 

staker/vault-staking.mdx

@@ -29,7 +29,7 @@ Pick a Vault that matches your preferences and start staking in just a few steps
 Your stake starts earning rewards as soon as the Vault's validators are active.
 
 :::custom-info[Position Health]
-If you mint osETH, your position gets a [health score](/docs/ostoken/how-ostoken-works#position-health) based on how much osETH you've minted relative to your staked ETH (the <Tooltip content="The ratio of minted osETH value to your staked ETH. The higher the LTV, the closer your position is to redemption or liquidation.">Loan-to-Value ratio</Tooltip>). There are four health levels — healthy, moderate, risky, and unhealthy. If your position becomes unhealthy, it may be subject to [redemption or liquidation](/docs/ostoken/how-ostoken-works#peg-maintenance). You can improve it anytime by burning osETH or adding more stake.
+If you mint osETH, your position gets a [health score](/docs/ostoken/how-ostoken-works#ltv-ratio) based on how much osETH you've minted relative to your staked ETH (the <Tooltip content="The ratio of minted osETH value to your staked ETH. The higher the LTV, the closer your position is to redemption or liquidation.">Loan-to-Value ratio</Tooltip>). There are four health levels — healthy, moderate, risky, and unhealthy. If your position becomes unhealthy, it may be subject to [redemption](/docs/ostoken/how-ostoken-works#redemption) or [liquidation](/docs/ostoken/how-ostoken-works#liquidation). You can improve it anytime by burning osETH or adding more stake.
 
 Position health depends on the APY of osETH relative to the Vault APY. The larger the gap (Vault APY < osETH APY), the worse the position health can get. If the Vault is running normally with close to the average APY across all Vaults, it's very unlikely that the position will drop below healthy.
 :::