diff --git a/docs/docs/ostoken/how-ostoken-works.mdx b/docs/docs/ostoken/how-ostoken-works.mdx index b4ed2a51..7caf20a0 100644 --- a/docs/docs/ostoken/how-ostoken-works.mdx +++ b/docs/docs/ostoken/how-ostoken-works.mdx @@ -1,239 +1,204 @@ --- title: How osToken Works -description: Learn about osToken minting, burning, exchange rate, and peg maintenance +description: Learn how osToken works. --- import Image from '@theme/IdealImage' # How osToken Works -osToken turns staked ETH or GNO into liquid, yield-bearing assets. Its operation is governed by four core mechanisms: -minting, burning, exchange rate appreciation, and peg maintenance. +osToken is created through **minting** — issuing new osTokens against ETH or GNO staked as collateral in a Vault. A maximum **Loan-to-Value (LTV)** ratio limits how much osToken can be minted against the stake, keeping every osToken overcollateralized. -## Minting - -Minting involves staking assets into a Vault and issuing osTokens against those staked assets acting as collateral. Minting limits are in place to ensure each issued token is fully backed. These limits are set by the **Loan-to-Value (LTV) ratio**. - -### Loan-to-Value Limits +The osToken **exchange rate** is the ratio between the total assets backing osToken and its total supply. It rises as staking rewards accrue, making each osToken worth more of the underlying asset over time. -The LTV ratio determines what portion of your stake can be tokenized with osToken: +**Redemptions** convert osToken back to ETH/GNO at this exchange rate. Used by the protocol to close any gap between the market price and the exchange rate, they keep osToken's market value aligned with its fair value. -| Vault Type | Ethereum (osETH) | Gnosis (osGNO) | Safety Mechanism | -|----------------|------------------|----------------|----------------------------------| -| Standard | 90% LTV | 90% LTV | 10% overcollateralization buffer | -| DAO-Approved | 99.99% LTV | 99.95% LTV | 5M SWISE operator bond | +If a position becomes thinly collateralized, **liquidations** act as a last resort to restore its collateralization. When a user wants to exit voluntarily, **burning** osToken returns it to the Vault and unlocks the underlying stake. -This ensures that even if some validators get slashed, there are enough assets to back all outstanding osTokens. +Together, these mechanisms keep osToken safe to hold and use. -### LTV Threshold Settings +## Minting -The StakeWise DAO sets **Loan-to-Value (LTV) thresholds** that determine how much osToken can be minted against staked assets in each Vault. +You can get osToken in three ways: -**Standard Vaults** -- **Default LTV**: 90% of staked ETH/GNO value -- All Vaults can mint osToken up to this threshold by default +- [Stake on the main app page](/staker/simple-staking) — your ETH is routed through a [Meta Vault](/docs/vaults/meta-vaults) that distributes deposits across the best-performing Sub-vaults (currently just the [Genesis Vault ↗](https://app.stakewise.io/vault/mainnet/0xac0f906e433d58fa868f936e8a43230473652885)), and osToken is minted against your stake automatically. +- [Pick a specific Vault from the marketplace](/staker/vault-staking) — stake into it, then optionally mint osToken against your stake. +- Buy osToken on a DEX. -**DAO-approved Vaults** -- **Enhanced LTV**: Up to 99.99% of staked value -- Reserved for DAO-approved Vaults meeting strict performance criteria +How much osToken you can mint against a given stake is capped by the Vault's maximum Loan-to-Value (LTV) ratio. -:::custom-notes[DAO-approved Vault Requirements] -To qualify for the 99.99% LTV threshold, Vaults must meet all criteria: +Only registered Vaults that are collateralized (have active validators) and harvested (rewards synced via the Keeper) can mint osToken. Minting acts as a price-stability mechanism: when osToken trades at a premium, anyone can stake, mint at the protocol rate, and sell — pushing the price back down until the premium clears. -- **Scale**: Minimum 10,000 ETH staked -- **Fee Cap**: Maximum 5% Vault fee -- **Performance**: Consistently above median network performance -- **Technology**: Latest Vault version deployed -- **Collateral**: 5M SWISE tokens locked as slashing insurance -::: +## LTV Ratio -StakeWise DAO has the capability to increase or decrease the osETH minting threshold based on any given Vault's risk parameters. +The LTV ratio creates a buffer between the collateral and the issued osToken. :::custom-notes[Example] - With 100 ETH staked in a 90% LTV Vault at 1.05 exchange rate: +With 100 ETH staked in a 90% LTV Vault at 1.05 exchange rate: - - Maximum mintable osETH: `100 × 0.9 ÷ 1.05 = 85.71 osETH` - - Overcollateralization: `10 ETH` remains as safety buffer +- Maximum mintable osToken: `100 × 0.9 ÷ 1.05 = 85.71 osToken` +- Overcollateralization: `10 ETH` remains as safety buffer ::: -### Minting & Buying Options +LTV limits vary by Vault type: -osToken can be acquired via four methods: +| Vault Type | Ethereum (osETH) | Gnosis (osGNO) | Safety Mechanism | +|----------------|------------------|----------------|-----------------------------------------------| +| Standard | 90% LTV | 90% LTV | 10% overcollateralization buffer | +| DAO-Approved | 99.99% LTV | 99.95% LTV | 5M SWISE operator bond | -1. **Simple staking** – Deposit ETH or GNO through the [StakeWise App ↗](https://app.stakewise.io/) to receive osETH or osGNO. No validator setup or Vault selection required. -2. **Vault staking** – Select a specific Vault (operator, fees, performance). Rewards and penalties are isolated per Vault. Minting capacity is constrained by LTV limits. -3. **Solo staking** – Operate private validators and mint osTokens against self-staked collateral, retaining full infrastructure control. Minting capacity is constrained by LTV limits. -4. **DEX purchase** – Acquire osTokens on decentralized exchanges. Tokens have the same exchange-rate appreciation as minted tokens and do not create a Vault position (no LTV or liquidation exposure). +To qualify for the 99.99% LTV, Vaults must meet strict performance criteria1 and post a SWISE slashing bond. +StakeWise DAO can adjust any individual Vault's LTV based on its risk profile. -All methods yield the same asset that appreciates through the same exchange rate mechanism. +LTV is continuously tracked through thresholds that determine position status: -:::custom-notes[Deep Dive] -Find step-by-step instructions for each staking option in the [Staker Guide →](/staker/introduction). -::: - -### Position Health - -Position health is continuously tracked through LTV thresholds: +Each minter's position falls into one of four grades — Healthy, Moderate, Risky, Unhealthy — based on how close LTV is to the mint cap and the liquidation threshold. In **DAO-approved Vaults** these thresholds don't apply. osToken position health grades - Healthy, Moderate, Risky, Unhealthy -Positions that exceed **91.5% LTV** become eligible for [redemption](#redemption-mechanism), and those above **92% LTV** are subject to [liquidation](#liquidation-mechanism). +## Exchange Rate -Users can maintain healthy positions by keeping LTV well below limits, adding more collateral, or burning osToken. -In 99.99% (osETH) / 99.95% (osGNO) Vaults, redemptions and liquidations do not apply, positions remain healthy by design. +osToken exchange rate is the canonical conversion rate between osToken and the underlying staked asset (ETH or GNO): -## Burning +``` +exchange rate = total assets backing osToken / total osToken supply +``` -Burning is the process of returning minted osTokens to the Vault in exchange for unlocking the staked collateral that backs them. -To fully unstake, a user must burn the entire amount of osTokens they minted, plus any protocol fees accrued. +The protocol uses this rate as the single source of truth for every conversion between osToken and the underlying asset. -Partial burns are also possible, allowing users to reduce debt, improve position health, or free up a portion of their stake. -The burn amount is calculated using the current fair exchange rate to ensure that the redeemed assets always match the true underlying value of the returned tokens. +The rate rises over time as staking rewards accrue. Appreciation is controlled by a single on-chain variable, `avgRewardPerSecond`, on the [`OsTokenVaultController`](https://etherscan.io/address/0x2A261e60FB14586B474C208b1B7AC6D0f5000306). On every state update, the protocol adds new profit to total assets: -The amount of ETH that can be unstaked at any moment is determined by maintaining the osToken position within its healthy Loan-to-Value (LTV) range. -After unstaking, the value of minted osETH must remain at or below: -- **90%** of staked ETH in a **90% LTV Vault** -- **99.99%** of staked ETH in a **99.99% LTV Vault** +``` +profit = avgRewardPerSecond × totalAssets × timeElapsed +``` -The protocol calculates the **maximum unstakable ETH** as: +A portion of this profit (`feePercent`) is minted as new osToken to the DAO treasury; the remainder grows the exchange rate for all holders. -:::custom-notes[Formula - 90% LTV] -$$ -{\small MaxUnstakeableETH = StakedETH - \dfrac{osETHMinted \times ExchangeRate}{0.9}} -$$ -::: +Only the [`Keeper`](https://etherscan.io/address/0x6B5815467da09DaA7DC83Db21c9239d98Bb487b5) contract — the rewards aggregator for StakeWise's decentralized oracle network — can update `avgRewardPerSecond`. Off-chain, oracles identify the most exposed user (highest LTV across all Vaults) and match `avgRewardPerSecond` to that user's Vault APY. -:::custom-notes[Formula – 99.99% LTV] -$$ -{\small MaxUnstakeableETH = StakedETH - \dfrac{osETHMinted \times ExchangeRate}{0.9999}} -$$ -::: +This guarantees osToken appreciation never outpaces the collateral backing it: even the most exposed position grows fast enough to stay solvent. When necessary, oracles adjust `avgRewardPerSecond` downward so osToken appreciation stays conservative relative to actual collateral performance. -:::custom-notes[Example: Bob's 90% LTV Position] -Bob stakes **100 ETH** and mints **50 osETH** at an exchange rate of **1.05 ETH/osETH**. -- Value of minted osETH: `50 × 1.05 = 52.5 ETH` -- Position health: `52.5 ÷ 100 = 52.5%` → safely below **90%** -- Maximum unstakable ETH: `100 − (52.5 ÷ 0.9) = 41.667 ETH` +## Redemption -After unstaking **41.667 ETH**, Bob's position health = **90%** -::: +Redemptions are the process of converting osToken back to its underlying asset (ETH or GNO) at the protocol exchange rate. -:::custom-notes[Alice's 99.99% LTV Position] -Alice stakes **100 ETH** and mints **50 osETH** at the same **1.05** rate. -- Value of minted osETH: `52.5 ETH` -- Position health: `52.5 ÷ 100 = 52.5%` → well below **99.99%** -- Maximum unstakable ETH: `100 − (52.5 ÷ 0.9999) = 47.495 ETH` +StakeWise manages them through the [`OsTokenRedeemer`](https://etherscan.io/address/0xc43A7b16A7a167c0318390Cba16787C11e9e1FD0) contract. Vaults version 1 (mainnet only) retain a permissionless mechanism that's currently disabled. -After unstaking **47.495 ETH**, Alice's position health = **99.99%** -::: +### Managed Redemption -## Peg Maintenance +osToken's market price on DEXes can drift from the protocol exchange rate. StakeWise monitors this spread and performs redemptions whenever osToken trades at a discount. -osToken maintains a soft peg to its underlying asset (ETH or GNO) through minting, redemptions, and liquidations. -Minting helps prevent secondary market premiums on osTokens. -Redemption acts as early intervention when positions drift toward risky erosion of collateral, -while liquidation serves as the last resort for closing thinly collateralized positions. -Together, they create arbitrage opportunities that keep osToken's market price closely aligned with its fair exchange rate. +See [osToken Redemptions](/docs/ostoken/ostoken-redemptions) for the exact mechanics. -### Redemption Mechanism +### Permissionless Redemption -In **90% LTV Vaults**, the redemption mechanism activates when a position's Loan-to-Value (LTV) reaches the **redemption threshold of 91.5%**. -At this point, anyone can burn part of that position's osTokens in exchange for an equivalent share of the Vault's collateral. -The burn amount is calculated so that the position's LTV is restored precisely to 90%. -Importantly, the staker whose tokens are redeemed does not lose value – they keep the osTokens burned on their behalf. +When a position's LTV crosses 91.5%, anyone can redeem part of its osToken against its collateral to restore the LTV to 90%. :::custom-notes[Formula: Redeemable Amount (90% LTV)] $$ -{\small Redeemable\ osETH = \frac{10 \times Minted\ osETH \times Exchange\ Rate - 9 \times Staked\ ETH}{Exchange\ Rate}} +{\small Redeemable\ osToken = \frac{Minted\ osToken \times Exchange\ Rate - 0.9 \times Staked\ ETH}{0.1 \times Exchange\ Rate}} $$ + +Derived by solving `(Minted − R) × Rate / (Staked − R × Rate) = 0.9`, where `R` is the redeemable osToken amount. ::: -:::custom-notes[Example: Bob's Redemption at 91.6% LTV] -Bob stakes **100 ETH** and mints **87.238 osETH** at an exchange rate of **1.05 ETH/osETH**. +:::custom-notes[Example: Redemption Above the 91.5% Threshold] +Bob stakes **100 ETH** and mints **85.714 osToken** at an exchange rate of **1.05 ETH/osToken** — the 90% LTV cap. -- Value of minted osETH: `87.238 × 1.05 = 91.6 ETH` -- Loan-to-Value: `91.6 ÷ 100 = 91.6%` → above **91.5% threshold** +Over time, the exchange rate rises to **1.0687**, lifting his LTV: +- Value of minted osToken: `85.714 × 1.0687 ≈ 91.6 ETH` +- Loan-to-Value: `91.6 ETH ÷ 100 ETH = 91.6%` → above **91.5% threshold** **Redemption calculation:** -- Redeemable osETH = `(10 × 87.238 × 1.05 - 9 × 100) ÷ 1.05 = 15.238` -- Redeemer burns **15.238 osETH** and receives **16 ETH** +- Redeemable osToken = `(85.714 × 1.0687 − 0.9 × 100) ÷ (0.1 × 1.0687) = 1.6 ÷ 0.10687 ≈ 14.97` +- The redeemer burns **14.97 osToken** and receives **16 ETH** from Bob's collateral (`14.97 × 1.0687`) **After redemption:** -- Bob's minted balance: **72 osETH** +- Bob's minted balance: **70.74 osToken** - Bob's staked collateral: **84 ETH** -- New LTV: **90%** (restored to safety) -- Bob **retains the 15.238 osETH** burned on his behalf → **no value lost** +- New LTV: `(70.74 × 1.0687) ÷ 84 ETH = 90%` (restored to the cap) +- The position shrinks at fair value: the released ETH matches the debt cleared at the protocol exchange rate — no value lost. ::: -Positions in **99.99% LTV Vaults** are also subject to redemption, with amounts redeemed determined by the protocol's redemption request volume. -The LTV of redeemed positions will remain above or equal to 99.99% after redemption, not affecting the position owner in any scenario. +## Liquidation -### Liquidation Mechanism +Liquidation is the last resort for closing thinly collateralized positions. In **90% LTV Vaults**, the liquidation threshold is set to **92% LTV**: when a position crosses it, anyone can liquidate part or all of it. -Liquidation is the system's final safeguard, closing unhealthy positions to protect overcollateralization. -In **90% LTV Vaults**, if a position exceeds the **92% LTV liquidation threshold**, anyone can close it entirely by burning all minted osTokens against the collateral. -The liquidator receives the underlying collateral value plus a **1% liquidation premium**, deducted from the staker's collateral as a penalty. +A liquidator burns their own osToken to clear a portion of the staker's debt and receives the underlying value plus a **1% premium**, deducted from the staker's collateral. :::custom-notes[Formula: Liquidation Payout] $$ -{\small ETH\ Payout = (Minted\ osETH \times Exchange\ Rate) \times 1.01} +{\small ETH\ Payout = (Burned\ osToken \times Exchange\ Rate) \times 1.01} $$ ::: -:::custom-notes[Example: Alice's Liquidation at 92% LTV] -Alice stakes **100 ETH** and mints **87.629 osETH** at an exchange rate of **1.05 ETH/osETH**. +:::custom-notes[Example: Full Liquidation at 92.01% LTV] +Alice stakes **100 ETH** and mints **85.714 osToken** at an exchange rate of **1.05 ETH/osToken** — the 90% LTV cap. -- Value of minted osETH: `87.629 × 1.05 = 92.01 ETH` -- Loan-to-Value: `92.01 ÷ 100 = 92.01%` → above **92% threshold** +Over time, the exchange rate rises to **1.0735**, lifting her LTV past the **92% liquidation threshold**: +- Value of minted osToken: `85.714 × 1.0735 ≈ 92.01 ETH` +- Loan-to-Value: `92.01 ETH ÷ 100 ETH = 92.01%` → above the **92% threshold** -**Liquidation process:** -- ETH payout = `(87.629 × 1.05) × 1.01 = 92.93 ETH` -- Liquidator burns **87.629 osETH** and receives **92.93 ETH** +**Liquidation (full):** +- A liquidator burns **85.714 osToken** from their wallet +- ETH payout = `(85.714 × 1.0735) × 1.01 ≈ 92.93 ETH`, taken from Alice's collateral -**After liquidation:** -- Alice's minted balance: **0 osETH** +**After:** +- Alice's minted balance: **0 osToken** (debt cleared) - Alice's remaining collateral: **7.07 ETH** -- Alice keeps her original **87.629 osETH** -- **Loss: 1% of collateral** as liquidation penalty +- Alice's wallet osToken: unchanged +- Net loss: **~0.92 ETH** — the 1% premium on the liquidated debt, deducted from her collateral ::: -Positions in **99.99% LTV Vaults** are exempt from liquidation, as their APY parity ensures position health remains stable. +Positions in **99.99% LTV Vaults** are exempt: liquidations are disabled at the contract level. The exemption is safe because the exchange rate appreciation is capped at those Vaults' APY, so positions stay solvent by design. -## Exchange Rate Appreciation +## Burning -osToken is a **repricing token**, meaning its redemption value increases over time as staking rewards accrue. -Each osToken represents a growing share of the underlying staked ETH or GNO. +Burning is the process of returning minted osToken to the Vault in exchange for unlocking the staked collateral that backs it. -The **fair exchange rate** is the amount of assets a user can receive when redeeming osToken within the protocol. -As rewards accrue, the redemption value increases, creating the "repricing" effect where each osETH becomes worth more ETH over time. +Users can burn any amount: a full burn clears the entire debt, while partial burns reduce debt, improve LTV, or free up a portion of the stake. Protocol fees accrue automatically into the position over time, so a full burn includes the original mint plus accrued fees. The burn amount is calculated at the current protocol exchange rate. -The fair exchange rate is reflected through `convertToAssets` and `convertToShares` functions in the [osTokenVaultController ↗](https://etherscan.io/address/0x2A261e60FB14586B474C208b1B7AC6D0f5000306#code) contract, -which manages osToken supply, collateral, and reward accrual. +The amount of ETH that can be unstaked at any moment is determined by maintaining the osToken position within its LTV cap. After unstaking, the value of minted osToken must remain at or below: -## Reward Accrual & Fee Mechanism +- **90%** of staked ETH in a **90% LTV Vault** +- **99.99%** of staked ETH in a **99.99% LTV Vault** -A decentralized Oracle network uses the [VaultUserLtvTracker ↗](https://etherscan.io/address/0xe0ae8b04922d6e3fa06c2496a94ef2875efcc7bb#code) contract to identify the user with the highest osToken LTV position across all Vaults. -Oracles then set the `avgRewardPerSecond` parameter to match that user's Vault APY performance. -This rate drives the continuous calculation of osToken value appreciation: +The protocol calculates the **maximum unstakable ETH** as: -:::custom-notes[Formula: Profit Accrual] +:::custom-notes[Formula: 90% LTV] $$ -{\small profitAccrued = avgRewardPerSecond \times totalAssets \times timeElapsed} +{\small MaxUnstakableETH = StakedETH - \dfrac{osTokenMinted \times ExchangeRate}{0.9}} $$ ::: -This mechanism ensures that osETH appreciation keeps pace with the least collateralized position in the entire protocol. -When necessary, Oracles adjust `avgRewardPerSecond` downward to prevent any LTV from exceeding 100% due to insufficient Vault performance. +:::custom-notes[Formula: 99.99% LTV] +$$ +{\small MaxUnstakableETH = StakedETH - \dfrac{osTokenMinted \times ExchangeRate}{0.9999}} +$$ +::: -From these rewards, the protocol deducts a 5% fee that increases users' osETH debt—the amount they must burn to fully exit their positions. -This fee creates new tokens for the StakeWise DAO Treasury and increases the osETH balance that users owe back to their Vaults. -The remaining 95% of rewards increase the backing assets, raising the fair exchange rate for all osToken holders. +:::custom-notes[Example: Bob's 90% LTV Position] +Bob stakes **100 ETH** and mints **50 osToken** at an exchange rate of **1.05 ETH/osToken**. -:::custom-notes[Example: Fee Impact] -If you minted **1 osToken** and after fee collection it increases to **1.000001**, -your debt grows by **0.000001**—your proportional share of the protocol's accumulated fees. +- Value of minted osToken: `50 × 1.05 = 52.5 ETH` +- LTV: `52.5 ÷ 100 = 52.5%` → safely below **90%** +- Maximum unstakable ETH: `100 − (52.5 ÷ 0.9) = 41.667 ETH` + +After unstaking **41.667 ETH**, Bob's LTV = **90%**. ::: -:::custom-info[Learn More] -For comprehensive information about all protocol fees, see the [Fees →](../fees/intro) chapter. +:::custom-notes[Example: Alice's 99.99% LTV Position] +Alice stakes **100 ETH** and mints **50 osToken** at the same **1.05** rate. + +- Value of minted osToken: `52.5 ETH` +- LTV: `52.5 ÷ 100 = 52.5%` → well below **99.99%** +- Maximum unstakable ETH: `100 − (52.5 ÷ 0.9999) = 47.495 ETH` + +After unstaking **47.495 ETH**, Alice's LTV = **99.99%**. ::: + +When a user exits a Vault while still holding osToken debt, the Vault may not have liquid ETH immediately available — validators must go through the Ethereum exit queue. An escrow contract holds the osToken position alongside the underlying stake until ETH is freed, then unwinds both in lockstep. This keeps every osToken fully backed throughout the exit process. + +
+ 1. DAO-approved Vault requirements: minimum 10,000 ETH staked, maximum 5% Vault fee, consistently above-median network performance, latest Vault version deployed, and 5M SWISE tokens locked as slashing insurance. ↩ +
diff --git a/docs/docs/ostoken/img/redemptions.png b/docs/docs/ostoken/img/redemptions.png new file mode 100644 index 00000000..58c09460 Binary files /dev/null and b/docs/docs/ostoken/img/redemptions.png differ diff --git a/docs/docs/ostoken/intro.mdx b/docs/docs/ostoken/intro.mdx index e3b5c901..f4f771da 100644 --- a/docs/docs/ostoken/intro.mdx +++ b/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 -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. +osToken overview - liquid staking token for StakeWise diff --git a/docs/docs/ostoken/ostoken-redemptions.mdx b/docs/docs/ostoken/ostoken-redemptions.mdx new file mode 100644 index 00000000..34948ea4 --- /dev/null +++ b/docs/docs/ostoken/ostoken-redemptions.mdx @@ -0,0 +1,97 @@ +--- +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 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 + +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 governance 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 governance. + +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 + +The redemption lifecycle moves osToken through six stages — from entering the redeemer's queue to claiming ETH/GNO once the batch is checkpointed. + +### 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. diff --git a/docs/docs/stakewise-protocol/what-is-stakewise.mdx b/docs/docs/stakewise-protocol/what-is-stakewise.mdx index 6dfce22e..3f638b2a 100644 --- a/docs/docs/stakewise-protocol/what-is-stakewise.mdx +++ b/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) diff --git a/operator/start-operator.mdx b/operator/start-operator.mdx index 690aa072..59a5abd7 100644 --- a/operator/start-operator.mdx +++ b/operator/start-operator.mdx @@ -10,7 +10,7 @@ import { CheckItem } from '@site/src/components'; # Start Operator -## Setup Checklist tick +## Setup Checklist rocket Before starting the Operator Service, confirm that everything is in place: diff --git a/sidebars.ts b/sidebars.ts index 34fb016a..212beb7b 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -42,6 +42,7 @@ const sidebars: SidebarsConfig = { }, items: [ 'docs/ostoken/how-ostoken-works', + 'docs/ostoken/ostoken-redemptions', ], }, { diff --git a/staker/risks.mdx b/staker/risks.mdx index 89b06bbe..151976ca 100644 --- a/staker/risks.mdx +++ b/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 diff --git a/staker/vault-staking.mdx b/staker/vault-staking.mdx index ed5ff225..7d7e5287 100644 --- a/staker/vault-staking.mdx +++ b/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 Loan-to-Value ratio). 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 Loan-to-Value ratio). 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. ::: diff --git a/static/icons/sw_rocket.gif b/static/icons/sw_rocket.gif new file mode 100644 index 00000000..22451ea0 Binary files /dev/null and b/static/icons/sw_rocket.gif differ