osToken redemptions by ulieth · Pull Request #106 · stakewise/stakewise-docs

ulieth · 2026-05-08T14:36:12Z

No description provided.

vercel · 2026-05-08T14:36:17Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Jun 30, 2026 3:20pm

Copilot

Pull request overview

This PR expands and refines the osToken documentation by adding a dedicated “osToken Redemptions” page, rewriting key parts of “How osToken Works”, and updating multiple cross-links/navigation entries to point at the new/updated sections.

Changes:

Added a new osToken Redemptions doc and included it in the osToken sidebar.
Reworked How osToken Works structure/content (LTV, exchange rate, redemption/liquidation, burning) and updated related deep links.
Updated a few staker/protocol/operator docs for revised anchors and minor UI/icon adjustments.

Reviewed changes

Copilot reviewed 8 out of 9 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
staker/vault-staking.mdx	Updates “Position Health” links to new anchors in osToken docs.
staker/risks.mdx	Updates osETH depeg explanation link to the new redemption anchor.
sidebars.ts	Adds the new osToken redemptions doc to navigation.
operator/start-operator.mdx	Swaps the checklist icon asset.
docs/docs/stakewise-protocol/what-is-stakewise.mdx	Updates oracle “Token Stability” deep link to the exchange rate section.
docs/docs/ostoken/ostoken-redemptions.mdx	Adds new documentation explaining the redemption mechanism and flow.
docs/docs/ostoken/intro.mdx	Updates osToken intro copy for clarity and positioning.
docs/docs/ostoken/how-ostoken-works.mdx	Major rewrite/restructure of the osToken mechanics page.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: ulieth <uliana.eth@proton.me>

…idation, and burning

kiriyha · 2026-06-29T13:25:20Z

-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 osToken exchange rate is the amount of the underlying asset that a user receives from StakeWise when redeeming the osToken.

kiriyha · 2026-06-29T13:30:08Z

-|----------------|------------------|----------------|----------------------------------|
-| 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.


When a user no longer needs the osToken, burning it unlocks the underlying stake. If osTokens remain minted but become thinly collateralized, liquidations act as a last resort to restore healthy collateralization.

kiriyha · 2026-06-29T13:36:44Z

-### 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.


based on how close LTV is to the liquidation threshold.

kiriyha · 2026-06-29T13:50:38Z


-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):


canonical -> protocol-calculated

kiriyha · 2026-06-29T13:51:03Z


-## Burning
+```
+exchange rate = total assets backing osToken / total osToken supply


нет, удалить

kiriyha · 2026-06-30T16:02:08Z

+A portion of this profit (`feePercent`) is minted as new osToken to the DAO treasury; the remainder grows the exchange rate for all holders.

-The protocol calculates the **maximum unstakable ETH** as:
+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.


(highest LTV across DAO-approved 100% LTV Vaults)

kiriyha · 2026-07-01T21:41:43Z

-{\small MaxUnstakeableETH = StakedETH - \dfrac{osETHMinted \times ExchangeRate}{0.9}}
-$$
-:::
+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.


убрать про "when necessary..."

kiriyha · 2026-07-01T21:42:18Z


-After unstaking **41.667 ETH**, Bob's position health = **90%**
-:::
+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.


manages redemptions

kiriyha · 2026-07-01T22:18:31Z

-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.
+### Permissionless Redemption


netu permissionless redemptions u nas

kiriyha · 2026-07-01T22:20:33Z


-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.


or free up -> and free up

kiriyha · 2026-07-01T22:23:55Z

+
+<div id="fn-1" style={{fontSize: '0.85em', color: 'var(--ifm-color-content-secondary)', marginTop: '2rem', listStyle: 'none', fontFamily: 'Fragment Mono, ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, Liberation Mono, Courier New, monospace'}}>
+  <span>1.</span> 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. <a href="#fnref-1" style={{color: 'var(--ifm-color-content-secondary)', textDecoration: 'none'}}>↩</a>
+</div>


nado by dobavit' text pro to, chto ves svoj stake iz Vaulta mozhno zabrat' tolko polnostju zaburniv svoju osToken poziciju

kiriyha · 2026-07-01T22:25:09Z

 # 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.


ETH and GNO staked in a Vault earn rewards, but the stake itself is a non-transferable share of the Vault's staking pool.

kiriyha · 2026-07-01T22:26:23Z

+
+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**.


minted against Vault collateral (user's stake in the Vault)

can burn the osToken at any time to repay the debt and withdraw their stake

ubrat' predlozhenie pro invariant

kiriyha · 2026-07-01T22:28:01Z

+
+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.


the minter's on-chain debt in the Vault is unchanged.

no longer tied to the minter.

kiriyha · 2026-07-01T22:30:54Z

+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


propuskaem tut poidee shag gde osToken byl kuplen s rynka pered tem kak byt' otpravlennym v kontrakt?

kiriyha · 2026-07-01T22:34:00Z

+
+`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.


"drains" zamenit' na "clears"

kiriyha · 2026-07-01T22:35:53Z


 :::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.


unhealthy -> liquidation
risky -> redemption

osToken redemptions

de0542b

vercel Bot had a problem deploying to Preview May 8, 2026 14:36 Failure

fix broken links

28104e9

vercel Bot deployed to Preview May 8, 2026 14:50 View deployment

cyc60 requested a review from Copilot May 8, 2026 14:52

Copilot started reviewing on behalf of cyc60 May 8, 2026 14:53 View session

Copilot AI reviewed May 8, 2026

View reviewed changes

fixed inaccuracies and added a new visual

94a9c78

vercel Bot deployed to Preview May 12, 2026 14:39 View deployment

fix hyperlink targets

4d1d1ad

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: ulieth <uliana.eth@proton.me>

vercel Bot deployed to Preview May 12, 2026 14:44 View deployment

fix hyperlink targets for redemption and liquidation

716b694

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: ulieth <uliana.eth@proton.me>

vercel Bot deployed to Preview May 12, 2026 14:45 View deployment

removed file extension suffixe from the name

65be5fa

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: ulieth <uliana.eth@proton.me>

vercel Bot deployed to Preview May 12, 2026 14:47 View deployment

fix color reference

e3333e7

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: ulieth <uliana.eth@proton.me>

vercel Bot deployed to Preview May 12, 2026 14:51 View deployment

fix alt description

47c9e9a

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: ulieth <uliana.eth@proton.me>

vercel Bot deployed to Preview May 12, 2026 14:52 View deployment

ulieth added 3 commits May 15, 2026 17:05

removed unused import of admonition component

0689eb6

made osToken use consistent

c287df7

overhaul ostoken docs across redemption, exchange rate, minting, liqu…

17da8dc

…idation, and burning

vercel Bot deployed to Preview May 15, 2026 14:11 View deployment

kiriyha reviewed Jun 29, 2026

View reviewed changes

address review comments and fix osToken docs grammar

4b8df94

vercel Bot deployed to Preview June 30, 2026 08:15 View deployment

restructure osToken redemptions into a seven-step flow

8c4df36

vercel Bot deployed to Preview June 30, 2026 15:20 View deployment

kiriyha reviewed Jun 30, 2026

View reviewed changes

kiriyha reviewed Jul 1, 2026

View reviewed changes

kiriyha requested changes Jul 1, 2026

View reviewed changes


		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.


		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.


		`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.

Uh oh!

Conversation

ulieth commented May 8, 2026

Uh oh!

vercel Bot commented May 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kiriyha Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kiriyha Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kiriyha Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kiriyha Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vercel Bot commented May 8, 2026 •

edited

Loading

kiriyha Jun 29, 2026 •

edited

Loading

kiriyha Jun 29, 2026 •

edited

Loading

kiriyha Jul 1, 2026 •

edited

Loading

kiriyha Jul 1, 2026 •

edited

Loading