osToken redemptions

docs/docs/glossary.mdx

@@ -50,10 +50,10 @@ The StakeWise smart contract that coordinates communication between the Operator
 The original validator type with a fixed stake of 32 ETH (or 1 GNO on Gnosis Chain). These validators automatically sweep excess balance above 32 ETH back to the withdrawal address. No top-up funding is available for 0x01 validators.
 
 ### Liquidation
-In 90% LTV Vaults, the process of closing an unhealthy osToken position that exceeds 92% LTV. Anyone can liquidate by burning all minted osTokens against the collateral. The liquidator receives the underlying collateral value plus a 1% premium, with the penalty deducted from the staker's collateral. Positions in 99.99% LTV Vaults are exempt from liquidation.
+In 90% LTV Vaults, the process of closing an unhealthy osToken position that exceeds 92% LTV. Anyone can liquidate by burning all minted osTokens against the collateral. The liquidator receives the underlying collateral value plus a 1% premium, with the penalty deducted from the staker's collateral. Positions in 100% LTV Vaults are exempt from liquidation.
 
 ### LTV (Loan-to-Value)
-The ratio of minted osToken value to staked collateral value, expressed as a percentage. Standard Vaults have 90% LTV, while DAO-approved Vaults can have up to 99.99% LTV (osETH) or 99.95% LTV (osGNO). This determines the maximum amount of osToken that can be minted against staked assets.
+The ratio of minted osToken value to staked collateral value, expressed as a percentage. Standard Vaults have 90% LTV, while DAO-approved Vaults can have up to 100% LTV (osETH) or 99.95% LTV (osGNO). This determines the maximum amount of osToken that can be minted against staked assets.
 
 ### Meta Vault
 A Vault type that does not register validators directly, instead delegating accumulated assets to sub-Vaults managed by the Vault Admin. Deposits are distributed across underlying sub-Vaults (up to 50 maximum) according to curator-defined allocation logic.

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:
+ETH and GNO staked in a Vault earn rewards, but the stake itself is a non-transferable share of the Vault's 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 the osToken issued against it. As a repricing token, osToken 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,92 @@
+---
+title: osToken Redemptions
+description: How osToken redemptions work under the hood.
+---
+
+import Image from '@theme/IdealImage';
+
+# osToken Redemptions
+
+Redemptions are an in-protocol peg-maintenance mechanism that converts osToken back to ETH or GNO at the protocol [exchange rate](/docs/ostoken/how-ostoken-works#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
+
+<Image img={require('./img/redemptions.png')} alt="osToken redemption flow between the Operator Service and the OsTokenRedeemer contract" />
+
+The redemption flow is coordinated between three actors: the [Operator Service ↗](https://github.com/stakewise/v3-operator), which computes who can be redeemed and by how much; StakeWise, which authorizes positions on-chain and supplies the osToken to redeem; and the [OsTokenRedeemer ↗](https://etherscan.io/address/0xc43A7b16A7a167c0318390Cba16787C11e9e1FD0) contract, which executes redemptions.
+
+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 StakeWise buys and queues osToken whenever it trades below peg (Step 2). The remaining steps consume both. In full, it runs in seven steps:
+
+### 1. Operator Service Computes the Redeemable Positions
+
+The Operator Service uploads the list of eligible positions to [IPFS ↗](https://ipfs.stakewise.io/ipfs/bafkreihbwhyaqskcczhuanu2nbdgdlfbwfwgbirue6kvlw4nrc5d2snqxa) 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.
+
+:::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](/docs/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.
+:::
+
+### 2. osToken Enters the Queue
+
+When osToken trades below the protocol exchange rate, StakeWise buys it on the secondary market and sends it to the `OsTokenRedeemer`, entering the queue. A ticket is issued — 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.
+
+### 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 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.
+
+### 5. 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.
+
+### 6. 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 clears 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 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.
+::::
+
+### 7. 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)

docs/docs/vaults/how-vaults-work.mdx

@@ -118,7 +118,7 @@ Once a validator fully exits, its balance is [swept ↗](https://ethereum.org/en
 
 osTokens (`osETH` or `osGNO`) are ERC-20 tokens that users can mint from any Vault using their shares as backing (aka collateral), providing liquidity without unstaking. osToken can be traded or used in DeFi while the underlying stake continues earning rewards.
 
-The system keeps more staked assets backing each osToken than the token is worth. This safety buffer protects users and keeps the system stable. The Vault's Loan-to-Value ratio determines how much users can mint — this ranges from standard ratios around 90% up to 99.99% for DAO-approved Vaults<sup><a href="#fn-6" id="fnref-6">6</a></sup>.
+For all Vaults other than DAO-approved Vaults with 100% LTV enabled, the system maintains more staked assets backing each osToken than the token is worth. This safety buffer protects users and helps keep the system stable. A Vault’s loan-to-value (LTV) ratio determines how much users can mint, ranging from the standard ratio of 90% to 100% for DAO-approved Vaults.<sup><a href="#fn-6" id="fnref-6">6</a></sup>
 
 :::custom-notes[Deep Dive]
 For more details on how osToken works, see [osToken →](../ostoken/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 mechanism](/docs/ostoken/ostoken-redemptions) keeps the market price tightly tethered to the protocol exchange rate by buying discounted osETH and redeeming it for ETH (or minting and selling fresh osETH when it trades at a premium).
 
 ## Boost
 

staker/vault-staking.mdx

@@ -28,8 +28,10 @@ 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.
 
+osETH can only be minted in Vaults that are **collateralized** (have active validators) and **harvested** (rewards synced via the Keeper).
+
 :::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. A risky position is subject to [redemption](/docs/ostoken/how-ostoken-works#redemption), while an unhealthy one is subject to [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.
 :::