restructure and refine Vaults docs#114
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There was a problem hiding this comment.
Pull request overview
This PR restructures and refreshes the Vaults documentation set by replacing the old “Customization” and “Meta Vaults” pages with clearer “Vault Types” and “Configuration” docs, while updating cross-doc links and rewriting several Vault concept pages for improved clarity and navigation.
Changes:
- Replaced
/docs/vaults/customizationand/docs/vaults/meta-vaultscontent with new/docs/vaults/configurationand/docs/vaults/vault-typesdocs, and updated the Vaults sidebar accordingly. - Updated staker/operator docs to point to the new Vault docs locations (including anchors), and added client redirects for legacy URLs.
- Refined multiple Vault pages (How Vaults Work, Boost, Technical Architecture, Vault Performance) and updated the custom StakeWise admonition icon asset reference.
Reviewed changes
Copilot reviewed 19 out of 30 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| staker/simple-staking.mdx | Updates Meta Vault doc link to the new “Vault Types” page anchor. |
| staker/risks.mdx | Updates Boost safety link anchor to match the revised Boost doc structure. |
| staker/rewards.mdx | Updates Smoothing Pool link to the new “Configuration” page anchor. |
| src/theme/Admonition/Types.js | Switches the custom-stakewise admonition icon to sw_logo.gif. |
| sidebars.ts | Reorders Vault docs and replaces removed pages with vault-types + configuration. |
| redirects.ts | Adds redirects from removed Vault doc routes to their replacements. |
| operator/meta-vault/overview.mdx | Updates Meta Vault link to the new “Vault Types” anchor. |
| operator/meta-vault/create-meta-vault.mdx | Updates capacity link to the new “Configuration” page anchor. |
| operator/introduction.mdx | Updates MEV strategy link to the new “Configuration” page anchor. |
| operator/create-regular-vault.mdx | Updates capacity/MEV strategy links to the new “Configuration” page anchors. |
| docs/docs/vaults/vault-types.mdx | New doc introducing and explaining Vault variants, including MetaVaults. |
| docs/docs/vaults/vault-performance.mdx | Rewrites/streamlines performance scoring explanation and presentation. |
| docs/docs/vaults/technical-architecture.mdx | Rewrites architecture overview with clearer deployment/module explanations. |
| docs/docs/vaults/meta-vaults.mdx | Removes standalone Meta Vaults page (content moved into Vault Types). |
| docs/docs/vaults/intro.mdx | Refreshes the Vaults landing page copy and adds glossary Tooltip usage. |
| docs/docs/vaults/how-vaults-work.mdx | Restructures the page into deposits/registration/rewards/withdrawals with diagrams. |
| docs/docs/vaults/customization.mdx | Removes old customization page (replaced by Configuration + Vault Types). |
| docs/docs/vaults/configuration.mdx | New doc describing immutable parameters, roles, branding, and fees. |
| docs/docs/vaults/boost.mdx | Rewrites Boost overview with clearer mechanics, safety framing, and links. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| The Vault's name, description, and image. Set and updated on the Vault page under **Settings → Branding**. | ||
|
|
||
| :::custom-stakewise[Authenticity Guarantee] | ||
| Before Vault branding appears in the StakeWise interface, the StakeWise team manually verifies that the operator controls the Vault. This prevents impersonation — a Vault displayed as "Operator A" is always controlled and run by Operator A. |
There was a problem hiding this comment.
Branching updates appear instantly. The Stakewise team only manages the vault verification label.
So if you update or create new branding, you will see the following label:
Unverified Vault
The Vault owner has not been verified. Please conduct your own research before staking.
There was a problem hiding this comment.
Settings term (mutable category) is too wide. Let's be specific:
- branding
- vault fee
- roles
|
|
||
| ### MEV Strategy | ||
|
|
||
| <Image img={require('./img/mev_strategy.png')} alt="Vault MEV strategy options - Smoothing Pool vs Own Escrow" /> |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: ulieth <uliana.eth@proton.me>
|
|
||
| There is also a special type — the **MetaVault** — which doesn't run validators itself but delegates staking to underlying sub-vaults. Like the Standard Vault, it can layer on the same tokenization (**ERC-20**) and whitelist (**Private**) modules. | ||
|
|
||
| Every Vault supports optional osETH minting via the [`VaultOsToken`](../../contracts/api/vaults/modules/VaultOsToken) module, letting depositors [mint osETH](/staker/vault-staking) against their staked position without unstaking. |
There was a problem hiding this comment.
That 'without unstaking' ending looks like torn out from another sentence. Maybe 'against their staked position as collateral' ?
|
|
||
| <Image img={require('./img/MetaVaults_Architecture_Diagram.png')} alt="MetaVaults Architecture Diagram" /> | ||
|
|
||
| A MetaVault is a specialized Vault that doesn't run validators itself. Instead, it accepts deposits and routes them across a set of underlying Vaults — called *sub-vaults* — which handle validator operations. Just like with a regular Vault, stakers can mint osETH against their position and redeem it for the underlying stake at any time. |
There was a problem hiding this comment.
stakers can mint osETH .. and redeem ...
Typically we use 'burn' word as opposite for minting. Redemptions is another feature, not released yet.
|
|
||
| <Image img={require('./img/deposit_flow.png')} alt="Deposit flow - user deposits ETH and gets Vault shares" /> | ||
|
|
||
| When a user deposits ETH, the Vault issues **shares** representing their proportional ownership of the pool's assets. Share value increases automatically as rewards accumulate — no token swaps or conversions occur during staking. Shares are non-transferable, except in [ERC-20 Vaults](./vault-types#erc-20-vault), where they are issued as a tradable token. |
There was a problem hiding this comment.
When a user deposits assets into the Vault (ETH or GNO), ...
| <Tooltip content={<><strong>Vault operator(s)</strong> <br /> Entities or individuals who run validators for a Vault. They operate the infrastructure and run the <a href="https://github.com/stakewise/v3-operator" className="tooltip-link">operator service software ↗</a> that automates essential Vault management tasks — such as validator registration, consolidations, and withdrawals.</>}>The Vault operator</Tooltip> | ||
| runs specialized software (the [Operator Service ↗](https://github.com/stakewise/v3-operator)) alongside their Ethereum [consensus →](../../operator/staking-nodes#consensus-client) and [execution →](../../operator/staking-nodes#execution-client) clients | ||
| that monitor deposit levels and handle the technical validator setup process. | ||
| Depositors can also mint [osETH](../ostoken/intro) against their stake — a liquid token usable across DeFi while the underlying stake keeps earning rewards. osETH grows in value over time: each osETH is worth more ETH as staking rewards accrue. How much osETH a user can mint depends on the Vault's LTV (Loan-to-Value) ratio. |
There was a problem hiding this comment.
can mint osToken (osETH or osGNO)...
osToken grows in value over time: for example, each osETH is worth more ETH ...
how much osToken a user can mint depends on the ...
| The default type is `0x02`. To register `0x01` validators instead, add the `--validators-type=0x01` flag when starting the Operator Service. Note that automatic funding (topping up existing validators) is disabled when using `0x01` validators. | ||
| Existing `0x01` validators can be migrated to `0x02` via [consolidation](../../operator/manage-validators/consolidate-validators). | ||
| When registering validators, the Operator Service prioritizes funding existing `0x02` validators by selecting those with the highest current balance and topping them up to 2048 ETH before creating new validators. | ||
| The Operator Service monitors Vault balances and submits validator registration requests to the StakeWise [Oracle network](../oracles/intro), generating the deposit data automatically. Each registration requires [approval from 6 of 11 Oracles](../oracles/oracle-duties#validator-registration-approval) before it is submitted on-chain. Once approved, the Vault contract sends the 32 ETH deposit to the Ethereum deposit contract. Before the validator becomes active and starts attesting or proposing blocks, it travels through the Beacon Chain's activation pipeline. |
There was a problem hiding this comment.
once approved, the Vault contract sends the required amount of assets to the network's staking deposit contract.
| - Encrypt each signature share with the corresponding Oracle's public key | ||
| - Send the encrypted shares to all Oracles and receive registration signatures in return | ||
| 5. Submit a transaction to the Vault contract to register the validator. | ||
| 1. **Deposit queue** — the deposit joins the Consensus Layer's processing queue (`state.pending_deposits`), rate-limited to 16 deposits per epoch and a churn budget of 256 ETH per epoch, shared between activations and exits. Under heavy demand, deposits can wait weeks or months. |
| ::: | ||
|
|
||
| Vaults can have several node operators running validators and support <Tooltip content={<><strong>Distributed Validator Technology</strong> <br /> A solution designed to overcome a single-operator trust problem by splitting a validator's private key among multiple independent operators. <br /> More on DVT - <a href="https://ethereum.org/en/staking/dvt/" className="tooltip-link" target="_blank" rel="noopener noreferrer nofollow">ethereum.org ↗</a></>}>Distributed Validator Technology</Tooltip> (DVT) to increase redundancy. | ||
| The [Pectra ↗](https://ethereum.org/en/roadmap/pectra/) upgrade ([EIP-7251 ↗](https://eips.ethereum.org/EIPS/eip-7251)) raised the maximum validator balance from 32 ETH to 2048 ETH, enabling **consolidation** — merging many `0x01` validators<sup><a href="#fn-1" id="fnref-1" style={{textDecoration: 'none'}}>1</a></sup> (capped at 32 ETH) into fewer high-balance `0x02` ones (up to 2048 ETH) to reduce infrastructure overhead and allow partial withdrawals of rewards above 32 ETH without exiting. |
There was a problem hiding this comment.
add "Similar upgrade was introduced on Gnosis Chain."
| Vaults can have several node operators running validators and support <Tooltip content={<><strong>Distributed Validator Technology</strong> <br /> A solution designed to overcome a single-operator trust problem by splitting a validator's private key among multiple independent operators. <br /> More on DVT - <a href="https://ethereum.org/en/staking/dvt/" className="tooltip-link" target="_blank" rel="noopener noreferrer nofollow">ethereum.org ↗</a></>}>Distributed Validator Technology</Tooltip> (DVT) to increase redundancy. | ||
| The [Pectra ↗](https://ethereum.org/en/roadmap/pectra/) upgrade ([EIP-7251 ↗](https://eips.ethereum.org/EIPS/eip-7251)) raised the maximum validator balance from 32 ETH to 2048 ETH, enabling **consolidation** — merging many `0x01` validators<sup><a href="#fn-1" id="fnref-1" style={{textDecoration: 'none'}}>1</a></sup> (capped at 32 ETH) into fewer high-balance `0x02` ones (up to 2048 ETH) to reduce infrastructure overhead and allow partial withdrawals of rewards above 32 ETH without exiting. | ||
|
|
||
| The Operator Service registers new validators as `0x02` by default, and existing `0x01` validators can be migrated via [consolidation](../../operator/manage-validators/consolidate-validators). When registering, it prioritizes funding existing `0x02` validators — selecting those with the highest current balance and topping them up to 2048 ETH before creating new ones. |
There was a problem hiding this comment.
esli est' chto skazat' pro nash treatment 0x02 na gnosise, nado dobavit' v konce. vrode u nas net 0x02 na gno, check with Dima
| For more details on how Oracles handle the validator registration approval process, see [Validator Registration Approval →](../oracles/oracle-duties#validator-registration-approval). | ||
| :::custom-notes[Under the Hood] | ||
| The Operator Service performs the following steps: | ||
| 1. Check if the Vault has enough assets to register a validator (32 ETH on Ethereum). |
| ::: | ||
|
|
||
| Rewards are calculated off-chain by the StakeWise Oracle Network. | ||
| The Vault then decides what to do with that ETH: |
There was a problem hiding this comment.
what to do with those assets (ETH or GNO):
| :::custom-notes[Deep Dive] | ||
| For detailed information about the reward distribution process, see [*Oracles*: Reward Distribution →](../oracles/oracle-duties#reward-distribution). | ||
| ::: | ||
| - **Top up** — add ETH to existing `0x02` validators, growing their effective balance up to the 2048 ETH maximum. |
| ::: | ||
| - **Top up** — add ETH to existing `0x02` validators, growing their effective balance up to the 2048 ETH maximum. | ||
| - **Consolidate** — merge multiple `0x01` validators into a single `0x02` validator (`0x01` + `0x01` → `0x02`). | ||
| - **Keep ETH as-is** — leave the ETH in the Vault for greater liquidity. |
There was a problem hiding this comment.
keep assets as-is - leave ETH or GNO in the Vault...
| ## Withdrawals | ||
|
|
||
| <Image img={require('./img/withdrawal_process.png')} alt="Vault withdrawal and exit queue process" /> | ||
| <Image img={require('./img/withdrawal_process.png')} alt="Vault withdrawal process - check queue, pay from available ETH, partial withdrawals, full exits" /> |
| Users can mint osTokens for instant liquidity or withdraw. When users choose to unstake, they enter the Vault's **exit queue** and receive an **exit queue ticket** that tracks their place in line. | ||
| As ETH becomes available to the Vault, users can claim what is available. | ||
| If only part of the requested amount is available, they can claim that portion immediately and receive an updated ticket for the remainder. | ||
| Every **12 hours**, the Operator Service: |
There was a problem hiding this comment.
esli net podderzhki etogo na gnosise, razdelit' etu sekciju otdelno na Ethereum i Gnosis Chain, pro Gnosis napisat' chto 0x02 validators not supported.
| :::custom-notes[Deep Dive] | ||
| For more details on how osToken works, see [osToken →](../ostoken/intro). | ||
| ::: | ||
| Staked assets continue earning rewards until validators complete the exit. Once a validator fully exits, its balance is [swept ↗](https://ethereum.org/en/staking/withdrawals/#validator-sweeping) to the Vault and becomes claimable by users in ticket order. Exit processing time depends on Ethereum network conditions — check the current [validator queue ↗](https://www.validatorqueue.com/) for up-to-date estimates. |
There was a problem hiding this comment.
on the network conditions - check the current validator queue on Ethereum and Gnosis Chain for up-to-date estimates
| ETH and GNO deposits into any Vault can only be used to launch validators for that specific Vault. Any rewards (or penalties) accumulated by these validators will belong to the Vault. | ||
| This isolates each Vault, allowing depositors to customize their staking experience to their needs. | ||
| A Vault is an isolated staking pool — a <Tooltip content="A program that runs on the Ethereum blockchain — a collection of code (its functions) and data (its state) that resides at a specific address on-chain.">smart contract</Tooltip> that processes ETH and GNO deposits, distributes rewards, and handles withdrawals in a trustless, non-custodial manner. | ||
| Vaults do not socialize risk: each deposit can only fund that Vault's validators, and any [rewards](/staker/rewards) or penalties are contained within it. |
| Vaults do not socialize risk: each deposit can only fund that Vault's validators, and any [rewards](/staker/rewards) or penalties are contained within it. | ||
|
|
||
| Individuals, professional node operators, DAOs, communities, and institutions can deploy a Vault to enable ETH and GNO staking on specific terms, like a bespoke staking fee, unique mix of operators, custom MEV strategy, capacity, branding, and optional ERC-20 Vault Token issuance. | ||
| Anyone — from solo stakers to DAOs and institutions — can [create a Vault](/operator/create-regular-vault) and run it on their own terms: bespoke fee, MEV strategy, and an optional ERC-20 Vault token. [MetaMask ↗](https://blog.stakewise.io/caseStudy/how-metamask-launched-pooled-staking-with-stakewise), [Chorus One ↗](https://blog.stakewise.io/caseStudy/how-chorus-one-launched-retail-staking-with-stakewise), and [NodeSet ↗](https://blog.stakewise.io/caseStudy/how-nodeset-launched-decentralized-pooled-staking-with-stakewise) use the same infrastructure to power their staking products. |
There was a problem hiding this comment.
use StakeWise Vaults to power their staking products.
| Anyone — from solo stakers to DAOs and institutions — can [create a Vault](/operator/create-regular-vault) and run it on their own terms: bespoke fee, MEV strategy, and an optional ERC-20 Vault token. [MetaMask ↗](https://blog.stakewise.io/caseStudy/how-metamask-launched-pooled-staking-with-stakewise), [Chorus One ↗](https://blog.stakewise.io/caseStudy/how-chorus-one-launched-retail-staking-with-stakewise), and [NodeSet ↗](https://blog.stakewise.io/caseStudy/how-nodeset-launched-decentralized-pooled-staking-with-stakewise) use the same infrastructure to power their staking products. | ||
|
|
||
| All deposits, reward distribution, and withdrawals are handled by smart contracts, making staking in Vaults fully non-custodial. | ||
| Every Vault lets depositors mint [osETH](../ostoken/intro) against their staked position as collateral. osETH is an overcollateralized, liquid token that unlocks [DeFi yield opportunities](https://app.stakewise.io/ecosystem) while continuing to earn staking rewards. |
| - Shares may not appear in portfolio tracking applications | ||
| - Share value increases automatically as staking rewards accumulate | ||
| - No token swaps or conversions occur during staking | ||
| Beyond base staking rewards, most Vaults with osETH minting enabled also include [Boost](./boost), a built-in one-click strategy that uses osETH as collateral to borrow ETH on Aave and restake it in the Vault, leading to more rewards. |
There was a problem hiding this comment.
... rewards, StakeWise Vaults on Ethereum include access to Boost....
, potentially leading to more rewards.
| :::custom-notes[Architecture Note] | ||
| This modular architecture ensures that all Vault types (ETH, GNO, private, ERC-20) share consistent behavior and allows new features to be added without breaking existing Vaults. | ||
| ::: | ||
| At initialization, the Vault is linked to [StakeWise smart contracts](../../contracts/networks/) and the Ethereum Beacon Chain. These links are immutable: once set, they cannot be changed. Each Vault is then composed from specialized modules, each responsible for a distinct area: |
| ### Calculation Method | ||
|
|
||
| We calculate the `proposal_score` by dividing the number of produced blocks by the total number of blocks. Validators are not negatively penalized for missed blocks; they get a score of 0 if they miss all their opportunities. | ||
| The `proposal_score` is calculated by dividing the number of proposed blocks by the total number of blocks. Validators are not penalized for missed blocks; a validator only scores 0 if it misses every opportunity. |
There was a problem hiding this comment.
by dividing the number of actually proposed blocks by the total number of block proposal duties.
| :::custom-warning[Block Reward Recipient] | ||
| A block is considered **missing** if the transaction fee or MEV is sent to the incorrect address, which negatively impacts the Vault performance score. | ||
|
|
||
| Verify that your validator clients are configured with the correct **fee recipient address**. You can locate this address (Block reward recipient) on the Vault page in the **Details** section. |
There was a problem hiding this comment.
Operators: Verify that your validator clients...
| ### Attestation Rewards | ||
|
|
||
| 85% of validator rewards come from attestations containing valuable information about consensus layer correctness and inclusion delay. | ||
| Attestations are the primary source of validator income — roughly 85% of all rewards — and pay for correct consensus votes that are included on time. |
|
|
||
| import Image from '@theme/IdealImage' | ||
|
|
||
| Each Vault is [assembled from modules](./technical-architecture#modular-design) that define how it operates, and different combinations produce different Vault types. The **Standard** Vault is the base type: adding a tokenization module makes its shares a transferable token (**ERC-20**), a whitelist module restricts deposits to approved addresses (**Private**), and a blocklist module blocks specific addresses from depositing (**Blocklist**). |
There was a problem hiding this comment.
a whitelist module only allows deposits from approved addresses ...
|
|
||
| There is also a special type — the **MetaVault** — which doesn't run validators itself but delegates staking to underlying sub-vaults. Like the Standard Vault, it can layer on the same tokenization (**ERC-20**) and whitelist (**Private**) modules. | ||
|
|
||
| Every Vault supports optional osETH minting via the [`VaultOsToken`](../../contracts/api/vaults/modules/VaultOsToken) module, letting depositors [mint osETH](/staker/vault-staking) against their staked position as collateral. |
|
|
||
| ## ERC-20 Vault | ||
|
|
||
| Issues Vault shares as a transferable ERC-20 token, letting operators build a DeFi ecosystem around the Vault. The operator sets the token's name and symbol (e.g., `mntETH`), so it appears in most portfolio trackers. Users can move the token freely — or put it to work as collateral, for example to [borrow against it on Morpho ↗](https://blog.stakewise.io/guide/stakewise-morpho-borrow-against-your-vault-token-without-unstaking) — as long as their remaining balance still covers any minted osETH position at the current LTV. |
There was a problem hiding this comment.
ecosystem around the Vault's own token.
as long as their remaining balance still covers any minted osToken position...
|
|
||
| <Image img={require('./img/MetaVaults_Architecture_Diagram.png')} alt="MetaVaults Architecture Diagram" /> | ||
|
|
||
| A MetaVault is a specialized Vault that doesn't run validators itself. Instead, it accepts deposits and routes them across a set of underlying Vaults — called *sub-vaults* — which handle validator operations. Just like with a regular Vault, stakers can mint osETH against their position and burn it to unlock their stake at any time. |
|
|
||
| Any third party can deploy a MetaVault permissionlessly, which opens up modular, layered staking strategies: | ||
|
|
||
| - [Diversified staking ↗](https://blog.stakewise.io/guide/diversified-staking-with-metavaults) — spread stake across multiple operators through a single MetaVault, reducing single-operator exposure, optimizing fees, and giving stakers one place to deposit, withdraw, and manage their osETH position. |
|
|
||
| ### How MetaVaults Work | ||
|
|
||
| Allocation is handled by a **Curator** — a contract that decides how ETH is distributed to and withdrawn from sub-vaults. Curator contracts must be approved by the DAO and registered in the [`CuratorsRegistry` ↗](https://etherscan.io/address/0xa23F7c8d25f4503cA4cEd84d9CC2428e8745933C#code). Currently, one Curator is available: the [`BalancedCurator` ↗](https://etherscan.io/address/0xe01351f866C118FbD04d222f9262A470F1d44d90#code), which spreads deposits and withdrawals evenly across sub-vaults. |
There was a problem hiding this comment.
that decides how deposited assets are distributed
| Most of these parameters are permanent — only the [Vault fee](/docs/fees/intro#vault-fee) can be changed after creation: | ||
|
|
||
| - **Vault capacity** – Set maximum [ETH capacity](/docs/vaults/customization#capacity) (default: unlimited ∞). | ||
| - **Vault capacity** – Set maximum [ETH capacity](/docs/vaults/configuration#capacity) (default: unlimited ∞). |
| Most of these parameters are permanent — only the [Vault fee](/docs/fees/intro#vault-fee) can be changed after creation: | ||
|
|
||
| - **Vault capacity** – Set maximum [ETH capacity](/docs/vaults/customization#capacity) (default: unlimited ∞). | ||
| - **Vault capacity** – Set maximum [ETH capacity](/docs/vaults/configuration#capacity) (default: unlimited ∞). |

No description provided.