diff --git a/docs/docs/protocol-concepts/Fees.mdx b/docs/docs/fees/intro.mdx similarity index 95% rename from docs/docs/protocol-concepts/Fees.mdx rename to docs/docs/fees/intro.mdx index d0c7d2f..5902df5 100644 --- a/docs/docs/protocol-concepts/Fees.mdx +++ b/docs/docs/fees/intro.mdx @@ -1,6 +1,6 @@ --- title: Fees -sidebar_position: 4 +sidebar_position: 0 description: "Learn about fees in StakeWise protocol" --- @@ -25,7 +25,7 @@ $$ A Vault fee is a percentage fee charged by Vault operators on staking rewards. This fee varies by Vault operator and can range **from 0% to 100%**. -The fee is automatically deducted from staking rewards when the Vault state is updated and is transferred to the Vault’s designated fee recipient (typically the Vault operator). +The fee is automatically deducted from staking rewards when the Vault state is updated and is transferred to the Vault's designated fee recipient (typically the Vault operator). The fee is a **dynamic parameter** set during the Vault creation process. Importantly, fees can only be increased by **20% at a time** (e.g., from 5% to 6%) with **a 3-day delay** between updates. diff --git a/docs/docs/governance/dao-treasury.mdx b/docs/docs/governance/dao-treasury.mdx new file mode 100644 index 0000000..39773f9 --- /dev/null +++ b/docs/docs/governance/dao-treasury.mdx @@ -0,0 +1,34 @@ +--- +title: DAO Treasury +sidebar_position: 2 +--- + +# DAO Treasury + +

Learn more about the Treasury

+ +The DAO Treasury is a [Gnosis Safe ↗](https://safe.global/) with a committee of 7 persons and a [SafeSnap Module ↗](https://docs.snapshot.box/v1-interface/plugins/safesnap-reality) that allows the submission of transactions on behalf of the governance token holders. + +**Treasury Addresses:** +- **Ethereum:** [0x144a98cb1CdBb23610501fE6108858D9B7D24934 ↗](https://etherscan.io/address/0x144a98cb1CdBb23610501fE6108858D9B7D24934) +- **Gnosis:** [0x8737f638E9af54e89ed9E1234dbC68B115CD169e ↗](https://gnosisscan.io/address/0x8737f638E9af54e89ed9E1234dbC68B115CD169e) + +The goal of the DAO committee is to monitor and reject the transactions that are not supposed to be executed on behalf of the DAO Treasury, since such malicious transactions can be submitted by an arbitrary account. In order to reject the transaction, a threshold of 4 out of 7 committee members must sign the rejection. + +As the \$SWISE tokens become more distributed with time, the community will be able to fulfill the committee responsibilities by placing \$SWISE bonds on whether the transaction should be executed or not. As a result, the committee could be dissolved in the future. + +## Current Committee Members (Multisig) + +- **[Ali Nuraldin ↗](https://x.com/Ali_run)** (0x7E36F1fF26cffD6906c11Cd7Eca5f6E993Ba6CE3) +- **[Andreas Dittrich ↗](https://www.linkedin.com/in/andreas-dittrich-eu/?originalSubdomain=de)** (0xc0c9707B552C6970f66Ab91D563Bf9b6048E9da6) +- **[Auryn Macmillan ↗](https://x.com/auryn_macmillan)** (0x9Aa6Db877742aD8D8c7fE209F561fbd2bE19D5F4) +- **[Dmitri Tsumak ↗](https://x.com/tsudmi)** (0x61B01a33Aea3e827B3941Ab097778bd3FA48a332) +- **[Gleb Dudka ↗](https://x.com/gleb0x)** (0xC46e791d4fB1207fAB8Cb0e44889127138539c69) +- **[Mikko Ohtamaa ↗](https://x.com/moo9000)** (0x9cC9c3de8e710781983a65b90B7efEaaD2D3D7D8) +- **[Otto de Voogd ↗](https://x.com/ottodv)** (0x1C86117156Ba31b5d62f02eB56bE9aC5a06610d3) + +## Former Committee Members (rotated after the DAO vote) + +- **[Anthony Sassano ↗](https://x.com/sassal0x)** (0x648aA14e4424e0825A5cE739C8C68610e143FB79) +- **[Jascha Samadi ↗](https://x.com/jaschasamadi)** (0x152E9Af50257Fc12a84Bb47241cc0bd01ECD2ac1) +- **[Miko Matsumura ↗](https://x.com/mikojava)** (0xA2E49855d672C3258A8442FA15F9Bc28f5A55980) diff --git a/docs/docs/governance/intro.mdx b/docs/docs/governance/intro.mdx new file mode 100644 index 0000000..59b4640 --- /dev/null +++ b/docs/docs/governance/intro.mdx @@ -0,0 +1,30 @@ +--- +title: Governance +sidebar_position: 0 +--- + +# Governance + +StakeWise is governed by its community through the **SWISE** token. The governance system empowers token holders to shape the protocol's future by voting on key parameters and proposals. + +## How Governance Works + +The StakeWise DAO is responsible for making critical decisions about the protocol, including: + +- Setting fees and commissions +- Managing oracles and node operators +- Approving protocol upgrades and new features +- Controlling the DAO Treasury + +Governance decisions are implemented through **StakeWise Improvement Proposals (SWIPs)**, which are discussed and voted on by SWISE token holders. + +:::custom-stakewise[Participate in Governance] +Join the conversation and vote on proposals at [StakeWise Forum ↗](https://forum.stakewise.io/) and [StakeWise Snapshot ↗](https://vote.stakewise.io/#/) +::: + +## Governance Structure + +The governance system consists of two main components: + +- **[StakeWise DAO →](./stakewise-dao)**: The community-driven governance mechanism powered by the SWISE token +- **[DAO Treasury →](./dao-treasury)**: A multi-signature wallet managed by a committee that executes approved governance decisions diff --git a/docs/docs/governance/stakewise-dao.mdx b/docs/docs/governance/stakewise-dao.mdx new file mode 100644 index 0000000..36724d8 --- /dev/null +++ b/docs/docs/governance/stakewise-dao.mdx @@ -0,0 +1,50 @@ +--- +title: StakeWise DAO +sidebar_position: 1 +--- + +# StakeWise DAO + +

Learn the basics of StakeWise DAO governance

+ +## Community-first approach + +The sole purpose of StakeWise's existence is to make staking as seamless and profitable as possible. + +Community feedback and adoption matter a lot for achieving this goal, and therefore StakeWise aims to create a cohesive community of stakers by putting the governance of the protocol in their hands. + +## Role of the DAO + +The DAO's job will be to govern the important system parameters like: + +- fees paid by stakers, +- commissions paid to node operators, +- onboarding and offboarding of oracles and node operators, +- principles of liquidity mining campaigns, +- whitelisting of gauge contracts, +- Insurance Fund payout triggers, +- approval of contract changes for the introduction of new features, and more. + +When choosing these parameters, the community will need to optimize for both its immediate interests as stakers and the long-term success of the protocol through a correct choice of parameters. + +## Tokenomics + +:::custom-info[$SWISE Token Contract] +`0x48C3399719B582dD63eB5AADf12A40B4C3f52FA2` +::: + +![Token Allocation & Emission Chart](/img/tokenomics.png) +

Token allocation and emission

+ +Alignment of interests of the platform and its participants shall happen through an allocation of 51% of the governance token supply to the community and the existence of basic mechanisms that allow gaining voting power by simply staking with StakeWise. Other token holders will be investors and the development team behind StakeWise. + +**Total supply:** 1,000,000,000 $SWISE + +**Vesting & allocation:** + +- **Community:** 510,000,000 $SWISE, 4-year vesting +- **Investors:** 251,500,000 $SWISE, 6-month cliff + 18-month linear vesting +- **Team:** 217,000,000 $SWISE, 6-month cliff + 42-month linear vesting +- **Future fundraise:** 21,500,000 $SWISE, available immediately + +The starting date for the emission is April 1st, 2021. diff --git a/docs/docs/guides/01-running-a-vault.mdx b/docs/docs/guides/01-running-a-vault.mdx deleted file mode 100644 index 5c09ab9..0000000 --- a/docs/docs/guides/01-running-a-vault.mdx +++ /dev/null @@ -1,177 +0,0 @@ ---- -title: Running a Vault -sidebar_position: 2 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import Admonition from '@theme/Admonition'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -# Running a Vault - -This comprehensive guide walks you through creating your own StakeWise Vault step by step. - -A [Vault →](/docs/protocol-concepts/Vaults) is a customizable smart contract that can be deployed by anyone to stake their own capital and/or offer staking to others, all in a non-custodial way. - -Each Vault is isolated from others and relies on its own set of validators to produce rewards on the consensus layer. However, a Vault may participate in [MEV smoothing →](/docs/protocol-concepts/Vaults/#mev-strategy) to avoid volatility in the execution layer earnings. - -Staked ETH/GNO in any Vault can be made liquid by minting [osETH/osGNO →](/docs/protocol-concepts/osToken) – a liquid staking token. - -Choose your settings based on your intended use case: - -| Use case | Recommended settings | -|----------|---------------------| -| 🏠 **Liquid solo staking** | • 0% fee • Private Vault • No Vault token • Smoothing Pool | -| 🌐 **Community staking pool** | • Custom capacity & fee • Public Vault • No Vault token • Smoothing Pool | -| 🏢 **Node operator service** | • Custom capacity & fee • Private Vault per customer • No Vault token • Smoothing Pool (compliance dependent) | -| 💎 **Service with custom LST** | • Custom capacity & fee • Public Vault • Enable Vault token • Smoothing Pool (compliance dependent) | -| 🔒 **Service without LST** | • Custom capacity & fee • Public Vault • No Vault token • Disable osToken access | - -:::custom-notes[New to these terms?] -Learn about [Vault token →](/docs/protocol-concepts/Vaults#erc-20-vaults--for-custom-utility--liquidity-ecosystem), [Smoothing Pool →](/docs/protocol-concepts/Vaults#smoothing-pool--pooled-rewards), [osToken →](/docs/protocol-concepts/osToken), and [Public vs Private Vaults →](/docs/protocol-concepts/Vaults#vault-type). -::: - -💡 Don't see your use case above? Contact the [StakeWise team 📧](mailto:info@stakewise.io) for personalized guidance. - -Below you'll find step-by-step instructions to create your Vault and get it running. - -## How to create a Vault? - -### Getting Started - -:::custom-notes[Wallet Requirements] -You'll need an Ethereum wallet such as [Rabby Wallet ↗](https://rabby.io/). -The process will look very similar in other wallets. -::: - -1. Navigate to the [StakeWise App ↗](https://app.stakewise.io) and go to the **"Operate"** section -2. Click the **"Create Vault"** button on the **"Operate your vault"** page to begin the setup process - -### Step 1: Configure Vault Parameters - -The first step involves setting up the fundamental parameters for your Vault. - -:::custom-warning[Permanent Settings] -Most of these settings **cannot be changed later**. Choose carefully before proceeding. -::: - -- **📐 Vault Capacity** – Set maximum ETH capacity (default: unlimited ∞). [Learn more →](/docs/protocol-concepts/Vaults#capacity) -- **💎 Vault Token** – Enable tradeable ERC-20 token (requires name & symbol) -- **🔑 Private Vault** – Restrict to approved wallets only -- **⚠️ Block List** – Prevent specific addresses from depositing - -:::custom-info[Vault Fees] -**💰 Vault Fees** can be set during creation and updated later. [Learn more about fee management →](/docs/protocol-concepts/Fees#vault-fees) -::: - -:::custom-warning[Required Acknowledgment] -You must check **"I understand that the parameters above cannot be changed later"** before proceeding. -::: - -### Step 2: Block Rewards Destination - -Choose how block rewards are distributed. This is a **permanent decision**. - -Most operators choose [Smoothing Pool →](/docs/protocol-concepts/Vaults#smoothing-pool--pooled-rewards) for stable returns, while [Vault Escrow →](/docs/protocol-concepts/Vaults#own-escrow--own-rewards) gives you full control but with volatile rewards. - -:::custom-warning[Required Acknowledgment] -You must check **"I understand that block rewards destination cannot be changed later"** before proceeding. -::: - -### Step 3: Add Branding - -Customize your Vault's appearance with name, description, and logo. - -:::custom-notes[Branding Can Be Changed Later] -Unlike Vault parameters, you can update branding anytime via your Vault interface: press **Settings → Branding → Edit → Save**. -::: - -### Step 4: Summary - -Review all your settings before final submission. This is your last chance to verify everything is correct, such as name, type, MEV strategy, fees, and capacity. - -:::custom-warning[Risk Acknowledgment] -You must check **"I understand the risks of operating the Vault and confirm my configuration choices"** before proceeding. -::: - -Click **"Create Vault"** to submit your configuration and create the Vault. - -### Step 5: Transaction Confirmation - -Complete the blockchain transaction to deploy your Vault. - -1. **Review Details**: Verify the transaction details in your wallet -2. **Confirm**: Click **"Confirm"** to submit the transaction -3. **Wait**: Transaction confirms (~12 sec) - -Once the transaction confirms, your Vault is live and operational! 🎉 - -Your new Vault appears: -- ✅ Listed on the Operate page as "Your Name Vault" -- 📅 Shows creation date: "Created [date]" -- 🔧 Displays MEV strategy and Vault type - -At the bottom of your Vault page, you'll see the **"Details"** section containing all the important information about your Vault. - -:::custom-info[Next Steps After Creation] - -**Set up validators** – Essential for Vault operation - -**Reach out to the [StakeWise team 📧](mailto:info@stakewise.io)** for Vault verification (better visibility and trust with potential stakers) -::: - -## Vault Administration - -Once your Vault is created, you can manage all settings through the **"Settings"** button in the StakeWise interface. - -### What You Can Control - - - - **Update anytime:** - - 📝 Vault name - - 📋 Description - - 🖼️ Logo - - - **Manage fees:** - - Set rates: 0-100% of staking rewards - - Update frequency: Once every 3 days, limited to 20% increase per update - - Special case: If initial fee is 0%, first increase is limited to 1% - - Configure multiple recipients with percentage splits - - Enable automatic periodic claims - - - **Delegate permissions:** - - **Admin**: Full Vault control - - **Fee Claimer**: Claim fees for shareholders - - **Validators Manager**: Authorize validator registrations, funding, and withdrawals ([Learn more →](/operator/validators-manager)) - - **Whitelist/Blocklist Manager**: Update accounts that can deposit (whitelist) or cannot deposit (blocklist). Only appears for Private Vaults or Vaults with blocklist functionality enabled - - - -## Getting Your Vault Running - -To start accepting ETH in your Vault, your infrastructure must be properly set up. -Follow the steps below to get everything running. - -**🚀 Setup difficulty:** Moderate – requires running Ethereum nodes and basic command-line familiarity. - -### Setup Checklist ✅ - -**1. Execution Client** – A fully synced execution client that supports the [ETH Execution API specification ↗](https://ethereum.github.io/execution-apis/api-documentation/). -Supported clients include Nethermind, Besu, Erigon, Geth, and Reth. -[Detailed setup instructions →](/operator/prerequisites#execution-client). - -**2. Consensus Client** – A fully synced consensus client that supports the [ETH Beacon Node API specification ↗](https://ethereum.github.io/beacon-APIs/#/). -Supported clients include Lighthouse, Nimbus, Prysm, Teku, and Lodestar. -[Detailed setup instructions →](/operator/prerequisites#consensus-client) - -**3. MEV-Boost** – Set up MEV-Boost to capture execution layer rewards. If your Vault uses the Smoothing Pool, you must use one of the StakeWise DAO-approved MEV relays. -[Learn about MEV strategy options →](/docs/protocol-concepts/Vaults#mev-strategy) and [Smoothing Pool relays →](/operator/smoothing-pool-relays). - -**4. Operator Service** – Specialized software that automates essential validator management tasks for your Vault, such as validator registrations, withdrawals, state updates, and fee claims. -The Operator Service runs seamlessly with any node setup, supporting your preferred execution and consensus clients, MEV relay, and distributed validator technology. [Complete setup guide →](/operator/intro) - -**5. Running Validators** – You must upload the allocated validator keys to the validator client and start it. Instructions can be found on your consensus client’s page. The validators will be registered automatically via the Operator Service. diff --git a/docs/docs/guides/02-staking.mdx b/docs/docs/guides/02-staking.mdx deleted file mode 100644 index e392d8b..0000000 --- a/docs/docs/guides/02-staking.mdx +++ /dev/null @@ -1,202 +0,0 @@ ---- -title: Staking -sidebar_position: 1 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import Admonition from '@theme/Admonition'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -# Staking - -## Start Your Staking Journey - -This comprehensive guide walks you through staking your ETH and GNO with StakeWise step by step. - -StakeWise is a liquid staking platform that gives you complete control over how your assets are staked. Whether you're a beginner seeking simplicity or an advanced user wanting custom terms, StakeWise offers flexible staking solutions that earn rewards while keeping your stake liquid. - -Choose your staking method based on your needs: - -| Method | Best for | Key advantages | -|--------|----------|----------------| -| 🚀 **One-click staking** | Beginners, simple staking | • Instant staking in seconds • Protection from all slashing • No technical knowledge required | -| 🎯 **Staking with Vaults** | Custom control, higher yields | • Choose your node operators • Higher potential yields • Lower fees • Protection from other Vaults | -| 🏠 **Solo staking** | Advanced users, maximum control | • Run your own validators • Highest yields possible • Complete control over setup | - -:::custom-notes[New to liquid staking?] -Learn about [osToken →](/docs/protocol-concepts/osToken), [Vaults →](/docs/protocol-concepts/Vaults), and [how StakeWise works →](/docs/intro). -::: - -💡 Not sure which method to choose? Start with one-click staking for simplicity, then explore Vault options as you become more familiar with the platform. - -Below you'll find step-by-step instructions for each staking method. - -
- 
-    Flow Staking Flow
-    ETH Your Assets → Vault StakeWise Vaults → osETH osTokens → 💰 Earn Rewards
-
-
- -## How to stake with one click? - -:::custom-notes[Wallet Requirements] -You'll need an Ethereum wallet such as [Rabby Wallet ↗](https://rabby.io/). -The process will look very similar in other wallets. -::: - -One-click staking routes your assets through a MetaVault that automatically distributes them among selected Vaults. This converts your assets into osTokens, StakeWise's liquid staking tokens, while providing diversified exposure across multiple professional operators. - -:::custom-info[What are osTokens?] -osTokens (osETH on Ethereum, osGNO on Gnosis Chain) represent your staked assets plus accumulated rewards. Use osTokens to trade, borrow, restake, or instantly unstake your staked assets via liquidity pools. [Learn more about osTokens →](/docs/protocol-concepts/osToken) -::: - -1. **Open [StakeWise App ↗](https://app.stakewise.io)** and connect your wallet -2. **Click the "Stake"** button to begin one-click staking -3. **Enter the amount** you want to stake in the input field -4. **Review conversion details** - The interface shows osTokens you'll receive, current rate, and estimated rewards -5. **Click "Stake"** and confirm the transaction in your wallet -6. **Wait for confirmation** (12-30 seconds) - osTokens will appear in your wallet and you start earning rewards - -:::custom-warning[Important Notes] -Ensure you have enough balance for both staking and gas fees for the transaction. -::: - -:::custom-info[Next Steps After Staking] -**Track your rewards** – osToken value increases over time as rewards accumulate - -**Use your osTokens** – Trade, provide liquidity, or use in DeFi protocols while earning staking rewards - -**Convert back anytime** – Swap osTokens back to the underlying asset through the app or exchanges when needed -::: - -## How to stake with Vaults? - -### Understanding Vault Staking - -Vault staking gives you control over exactly how your assets are staked. Unlike one-click staking, you can choose specific node operators, MEV strategies, and fee structures that match your preferences. - -:::custom-notes[Why Choose Vault Staking?] -**Higher potential yields** – Access to specialized operators and strategies - -**Custom terms** – Choose fee rates, node operators, and MEV handling - -**Isolated rewards** – Earn from your chosen Vault's performance only - -**Slashing protection** – Protected from penalties in other Vaults -::: - -1. **Navigate to Vaults** from the StakeWise homepage and connect your wallet -2. **Browse available Vaults** using filters for performance, APY, and TVL -3. **Select your Vault** and review its APY, operator info, fees, and capacity -4. **Click "Stake"** and enter the amount you want to stake -5. **Review terms** and confirm the transaction in your wallet - - -### Making Your Stake Liquid (Optional) - -After staking in a Vault, you can mint osTokens against your stake to maintain liquidity: - -1. **Access Mint Option**: On your Vault's page, find the **"Mint osToken"** section -2. **Choose Amount**: Use the slider or enter the amount of osTokens to mint - - Maximum: 90% of your stake (99.99% for select Vaults) - - Your full staking rewards continue regardless of minting ratio - -3. **Complete Minting**: Confirm the transaction to receive osTokens -4. **Monitor Health**: Keep track of your position health in the Vault interface - -:::custom-info[Position Health] -Your osToken position has health levels (Healthy, Moderate, Risky, Unhealthy) based on your Vault's performance relative to osTokens. Monitor this regularly to avoid liquidation. [Learn more →](/docs/protocol-concepts/osToken#position-health) -::: - -### Vault Staking Management - -Once staked in a Vault, you can: - -- **📈 Track Performance**: Monitor your Vault's APY and your earned rewards -- **🔄 Mint/Burn osTokens**: Adjust your liquid staking position as needed ([Learn about minting →](/docs/protocol-concepts/osToken#minting) | [Learn about burning →](/docs/protocol-concepts/osToken#burning)) -- **⚡ Use Boost**: Increase your staking rewards with additional yield opportunities -- **📤 Unstake**: Exit the Vault (requires burning all minted osTokens first) -- **💱 Switch Vaults**: Unstake from one and stake in another for better terms - -## Solo Staking with StakeWise - -For advanced users who want to run their own validators while maintaining liquidity, StakeWise offers solo staking through personal Vaults. This gives you maximum control and the highest potential yields. - -:::custom-info[Advanced Feature] -Solo staking requires technical expertise to run Ethereum / Gnosis Chain validators. It's recommended for experienced users comfortable with node operation and command-line tools. -::: - -**Benefits of solo staking with StakeWise:** -- 🎯 **Full control** over your validators and staking setup -- 💰 **Highest yields** with minimal fees -- 🔄 **Maintain liquidity** by minting osTokens against your stake -- ⚙️ **MEV smoothing** for stable execution layer rewards - -**To get started with solo staking:** -1. **Create your own Vault** using our [Vault creation guide →](/docs/guides/running-a-vault) -2. **Set up validator infrastructure** following our [operator documentation →](/operator/intro) -3. **Stake in your Vault** and optionally [mint osTokens for liquidity →](/docs/protocol-concepts/osToken#minting) - -## How to unstake? - -Unstaking is as simple and straightforward as staking, varying just slightly depending on how you staked your assets. - -
- 
-    Flow Unstaking Flow
-    🔥 Burn osTokens → 🚪 Unstaking → 📥 Claim Rewards → 👛 Receive Assets
-
-
- -### From One-Click Staking - -If you staked directly for osTokens, you can convert them back anytime: - -1. **Convert osTokens** – Go to StakeWise app, click **"Unstake"**, enter amount to convert back -2. **Confirm transaction** – Review conversion rate and confirm in your wallet -3. **Receive assets** – Get your original assets plus rewards immediately - -### From Vault Staking - -:::custom-warning[Required Step] -To unstake from a Vault, you must first **burn the osTokens you minted**. The interface shows exactly how much to burn. -::: - -:::custom-notes[When unstaking from Vaults:] -Burn osETH → Enter unstake amount → Confirm transaction → Join unstake queue → Claim ETH. -::: - -1. **Burn osTokens** – Click **minus (–)** button, enter amount or click **"Max"**, click **"Confirm"** -2. **Unstake assets** – Click **minus (–)** button, enter withdrawal amount, click **"Unstake"** -3. **Join queue** – Confirmation shows **"Added to unstake queue"** -4. **Claim assets** – Once assets are exited, click **"Claim"** to receive your assets - -:::custom-notes[Processing Times] -- **One-click unstaking**: Immediate conversion -- **osETH burning in Vaults**: Immediate once confirmed -- **Vault unstaking**: 24-48 hours depending on the queue -::: diff --git a/docs/docs/guides/_category_.json b/docs/docs/guides/_category_.json deleted file mode 100644 index f389501..0000000 --- a/docs/docs/guides/_category_.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "label": "Guides", - "position": 3, - "link": { - "type": "generated-index" - } -} diff --git a/docs/docs/guides/defi/_category_.json b/docs/docs/guides/defi/_category_.json deleted file mode 100644 index 87a4fc2..0000000 --- a/docs/docs/guides/defi/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "DeFi", - "position": 4, - "link": { - "type": "doc", - "id": "docs/guides/defi/index" - } -} diff --git a/docs/docs/guides/defi/01-boost.mdx b/docs/docs/guides/defi/boost-feature.mdx similarity index 97% rename from docs/docs/guides/defi/01-boost.mdx rename to docs/docs/guides/defi/boost-feature.mdx index 257a024..1703ef7 100644 --- a/docs/docs/guides/defi/01-boost.mdx +++ b/docs/docs/guides/defi/boost-feature.mdx @@ -57,7 +57,7 @@ As an additional safety layer, Boost includes an "escape hatch" mechanism that a ### How to Use Boost :::custom-info[Prerequisites] -To use Boost, you need osTokens in your wallet. If you don't have any, see the [staking guide →](/docs/guides/staking) for instructions on minting osTokens from your stake. +To use Boost, you need osTokens in your wallet. If you don't have any, see the [staking guide →](/docs/guides/staking/intro) for instructions on minting osTokens from your stake. ::: #### Boosting Process diff --git a/docs/docs/guides/defi/index.mdx b/docs/docs/guides/defi/intro.mdx similarity index 88% rename from docs/docs/guides/defi/index.mdx rename to docs/docs/guides/defi/intro.mdx index 0ab7938..59ac7a5 100644 --- a/docs/docs/guides/defi/index.mdx +++ b/docs/docs/guides/defi/intro.mdx @@ -10,7 +10,7 @@ Whether it's Boost, which amplifies staking returns by looping assets on Aave, o Explore this section to understand how DeFi features can enhance your yield while staying connected to the StakeWise ecosystem. -[Boost →](./boost) – amplify staking returns by looping assets on Aave for maximum yield. +[Boost feature →](./boost-feature) – amplify staking returns by looping assets on Aave for maximum yield. [SWISE-ETH Liquidity →](./swise-eth-liquidity) – earn fees as a liquidity provider in the SWISE-ETH pool. diff --git a/docs/docs/guides/defi/02-swise-eth-liquidity.mdx b/docs/docs/guides/defi/swise-eth-liquidity.mdx similarity index 100% rename from docs/docs/guides/defi/02-swise-eth-liquidity.mdx rename to docs/docs/guides/defi/swise-eth-liquidity.mdx diff --git a/docs/docs/guides/03-reward-splitter.mdx b/docs/docs/guides/fee-splitter.mdx similarity index 88% rename from docs/docs/guides/03-reward-splitter.mdx rename to docs/docs/guides/fee-splitter.mdx index 940a660..afa92c9 100644 --- a/docs/docs/guides/03-reward-splitter.mdx +++ b/docs/docs/guides/fee-splitter.mdx @@ -44,7 +44,7 @@ Changes require a new transaction and only affect future fee distributions. ::: :::custom-notes[Further Reading] -- [Vault fee management →](/docs/protocol-concepts/Fees#vault-fees) -- [Vault creation guide →](/docs/guides/running-a-vault) -- [Fee claiming →](/docs/guides/running-a-vault) +- [Vault fee management →](/docs/fees/intro#vault-fees) +- [Vault creation guide →](/docs/guides/running-a-vault/intro) +- [Fee claiming →](/docs/guides/running-a-vault/vault-administration) ::: diff --git a/docs/docs/guides/intro.mdx b/docs/docs/guides/intro.mdx new file mode 100644 index 0000000..894ce5d --- /dev/null +++ b/docs/docs/guides/intro.mdx @@ -0,0 +1,25 @@ +--- +title: Guides +sidebar_position: 0 +--- + +# Guides + +Welcome to the StakeWise Guides! This section provides step-by-step tutorials to help you get started with staking, running a Vault, and more. + +## 📚 Available Guides + +### ETH [Staking →](/docs/guides/staking/intro) +Learn how to stake your ETH and GNO with StakeWise. Choose from one-click staking, Vault staking, or solo staking options. + +### 🏗️ [Running a Vault →](/docs/guides/running-a-vault/how-to-create-a-vault) +Create and manage your own StakeWise Vault. Set up custom parameters, branding, and start accepting deposits. + +### 💰 [Fee Splitter →](/docs/guides/fee-splitter) +Configure fee distribution among multiple shareholders for your Vault's staking rewards. + +### ETH [DeFi →](/docs/guides/defi/intro) +Maximize your staking rewards with DeFi strategies like Boost and liquidity provision. + +### 🔄 [StakeWise V2 →](/docs/guides/stakewise-v2/migrate-to-stakewise-v3-on-ethereum) +Migration guides and resources for StakeWise V2 users. diff --git a/docs/docs/guides/running-a-vault/getting-your-vault-running.mdx b/docs/docs/guides/running-a-vault/getting-your-vault-running.mdx new file mode 100644 index 0000000..9e01c13 --- /dev/null +++ b/docs/docs/guides/running-a-vault/getting-your-vault-running.mdx @@ -0,0 +1,31 @@ +--- +title: Getting Your Vault Running +sidebar_position: 3 +--- + +import Admonition from '@theme/Admonition'; + +# Getting Your Vault Running + +To start accepting ETH in your Vault, your infrastructure must be properly set up. +Follow the steps below to get everything running. + +**🚀 Setup difficulty:** Moderate – requires running Ethereum nodes and basic command-line familiarity. + +## Setup Checklist ✅ + +**1. Execution Client** – A fully synced execution client that supports the [ETH Execution API specification ↗](https://ethereum.github.io/execution-apis/api-documentation/). +Supported clients include Nethermind, Besu, Erigon, Geth, and Reth. +[Detailed setup instructions →](/operator/Prerequisites#execution-client). + +**2. Consensus Client** – A fully synced consensus client that supports the [ETH Beacon Node API specification ↗](https://ethereum.github.io/beacon-APIs/#/). +Supported clients include Lighthouse, Nimbus, Prysm, Teku, and Lodestar. +[Detailed setup instructions →](/operator/Prerequisites#consensus-client) + +**3. MEV-Boost** – Set up MEV-Boost to capture execution layer rewards. If your Vault uses the Smoothing Pool, you must use one of the StakeWise DAO-approved MEV relays. +[Learn about MEV strategy options →](/docs/vaults/customization#mev-strategy) and [Smoothing Pool relays →](/operator/smoothing-pool-relays). + +**4. Operator Service** – Specialized software that automates essential validator management tasks for your Vault, such as validator registrations, withdrawals, state updates, and fee claims. +The Operator Service runs seamlessly with any node setup, supporting your preferred execution and consensus clients, MEV relay, and distributed validator technology. [Complete setup guide →](/operator/intro) + +**5. Running Validators** – You must upload the allocated validator keys to the validator client and start it. Instructions can be found on your consensus client's page. The validators will be registered automatically via the Operator Service. diff --git a/docs/docs/guides/running-a-vault/how-to-create-a-vault.mdx b/docs/docs/guides/running-a-vault/how-to-create-a-vault.mdx new file mode 100644 index 0000000..53ba39e --- /dev/null +++ b/docs/docs/guides/running-a-vault/how-to-create-a-vault.mdx @@ -0,0 +1,94 @@ +--- +title: How to Create a Vault +sidebar_position: 1 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import Admonition from '@theme/Admonition'; +import useBaseUrl from '@docusaurus/useBaseUrl'; + +# How to Create a Vault + +### Getting Started + +:::custom-notes[Wallet Requirements] +You'll need an Ethereum wallet such as [Rabby Wallet ↗](https://rabby.io/). +The process will look very similar in other wallets. +::: + +1. Navigate to the [StakeWise App ↗](https://app.stakewise.io) and go to the **"Operate"** section +2. Click the **"Create Vault"** button on the **"Operate your vault"** page to begin the setup process + +### Step 1: Configure Vault Parameters + +The first step involves setting up the fundamental parameters for your Vault. + +:::custom-warning[Permanent Settings] +Most of these settings **cannot be changed later**. Choose carefully before proceeding. +::: + +- **📐 Vault Capacity** – Set maximum ETH capacity (default: unlimited ∞). [Learn more →](/docs/vaults/customization#capacity) +- **💎 Vault Token** – Enable tradeable ERC-20 token (requires name & symbol) +- **🔑 Private Vault** – Restrict to approved wallets only +- **⚠️ Block List** – Prevent specific addresses from depositing + +:::custom-info[Vault Fees] +**💰 Vault Fees** can be set during creation and updated later. [Learn more about fee management →](/docs/fees/intro#vault-fees) +::: + +:::custom-warning[Required Acknowledgment] +You must check **"I understand that the parameters above cannot be changed later"** before proceeding. +::: + +### Step 2: Block Rewards Destination + +Choose how block rewards are distributed. This is a **permanent decision**. + +Most operators choose [Smoothing Pool →](/docs/vaults/customization#smoothing-pool--pooled-rewards) for stable returns, while [Vault Escrow →](/docs/vaults/customization#own-escrow--own-rewards) gives you full control but with volatile rewards. + +:::custom-warning[Required Acknowledgment] +You must check **"I understand that block rewards destination cannot be changed later"** before proceeding. +::: + +### Step 3: Add Branding + +Customize your Vault's appearance with name, description, and logo. + +:::custom-notes[Branding Can Be Changed Later] +Unlike Vault parameters, you can update branding anytime via your Vault interface: press **Settings → Branding → Edit → Save**. +::: + +### Step 4: Summary + +Review all your settings before final submission. This is your last chance to verify everything is correct, such as name, type, MEV strategy, fees, and capacity. + +:::custom-warning[Risk Acknowledgment] +You must check **"I understand the risks of operating the Vault and confirm my configuration choices"** before proceeding. +::: + +Click **"Create Vault"** to submit your configuration and create the Vault. + +### Step 5: Transaction Confirmation + +Complete the blockchain transaction to deploy your Vault. + +1. **Review Details**: Verify the transaction details in your wallet +2. **Confirm**: Click **"Confirm"** to submit the transaction +3. **Wait**: Transaction confirms (~12 sec) + +Once the transaction confirms, your Vault is live and operational! 🎉 + +Your new Vault appears: +- ✅ Listed on the Operate page as "Your Name Vault" +- 📅 Shows creation date: "Created [date]" +- 🔧 Displays MEV strategy and Vault type + +At the bottom of your Vault page, you'll see the **"Details"** section containing all the important information about your Vault. + +:::custom-info[Next Steps After Creation] + +**Set up validators** – Essential for Vault operation + +**Reach out to the [StakeWise team 📧](mailto:info@stakewise.io)** for Vault verification (better visibility and trust with potential stakers) +::: diff --git a/docs/docs/guides/running-a-vault/intro.mdx b/docs/docs/guides/running-a-vault/intro.mdx new file mode 100644 index 0000000..dfa6ccd --- /dev/null +++ b/docs/docs/guides/running-a-vault/intro.mdx @@ -0,0 +1,37 @@ +--- +title: Running a Vault +sidebar_position: 0 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import Admonition from '@theme/Admonition'; +import useBaseUrl from '@docusaurus/useBaseUrl'; + +# Running a Vault + +This comprehensive guide walks you through creating your own StakeWise Vault step by step. + +A [Vault →](/docs/vaults/intro) is a customizable smart contract that can be deployed by anyone to stake their own capital and/or offer staking to others, all in a non-custodial way. + +Each Vault is isolated from others and relies on its own set of validators to produce rewards on the consensus layer. However, a Vault may participate in [MEV smoothing →](/docs/vaults/customization#mev-strategy) to avoid volatility in the execution layer earnings. + +Staked ETH/GNO in any Vault can be made liquid by minting [osETH/osGNO →](/docs/ostoken/intro) – a liquid staking token. + +Choose your settings based on your intended use case: + +| Use case | Recommended settings | +|----------|---------------------| +| 🏠 **Liquid solo staking** | • 0% fee • Private Vault • No Vault token • Smoothing Pool | +| 🌐 **Community staking pool** | • Custom capacity & fee • Public Vault • No Vault token • Smoothing Pool | +| 🏢 **Node operator service** | • Custom capacity & fee • Private Vault per customer • No Vault token • Smoothing Pool (compliance dependent) | +| 💎 **Service with custom LST** | • Custom capacity & fee • Public Vault • Enable Vault token • Smoothing Pool (compliance dependent) | +| 🔒 **Service without LST** | • Custom capacity & fee • Public Vault • No Vault token • Disable osToken access | + +:::custom-notes[New to these terms?] +Learn about [Vault token →](/docs/vaults/customization#erc-20-vaults--for-custom-utility--liquidity-ecosystem), [Smoothing Pool →](/docs/vaults/customization#smoothing-pool--pooled-rewards), [osToken →](/docs/ostoken/intro), and [Public vs Private Vaults →](/docs/vaults/customization#vault-type). +::: + +💡 Don't see your use case above? Contact the [StakeWise team 📧](mailto:info@stakewise.io) for personalized guidance. + +Next you'll find step-by-step instructions to create your Vault and get it running. diff --git a/docs/docs/guides/running-a-vault/vault-administration.mdx b/docs/docs/guides/running-a-vault/vault-administration.mdx new file mode 100644 index 0000000..f0cc3ee --- /dev/null +++ b/docs/docs/guides/running-a-vault/vault-administration.mdx @@ -0,0 +1,37 @@ +--- +title: Vault Administration +sidebar_position: 2 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import Admonition from '@theme/Admonition'; + +# Vault Administration + +Once your Vault is created, you can manage all settings through the **"Settings"** button in the StakeWise interface. + +## What You Can Control + + + + **Update anytime:** + - 📝 Vault name + - 📋 Description + - 🖼️ Logo + + + **Manage fees:** + - Set rates: 0-100% of staking rewards + - Update frequency: Once every 3 days, limited to 20% increase per update. If initial fee is 0%, first increase is limited to 1%. + - Configure multiple recipients with percentage splits + - Enable automatic periodic claims + + + **Delegate permissions:** + - **Admin**: Full Vault control + - **Fee Claimer**: Claim fees for shareholders + - **Validators Manager**: Authorize validator registrations, funding, and withdrawals ([Learn more →](/operator/validators-manager)) + - **Whitelist/Blocklist Manager**: Update accounts that can deposit (whitelist) or cannot deposit (blocklist). Only appears for Private Vaults or Vaults with blocklist functionality enabled + + diff --git a/docs/docs/guides/staking/intro.mdx b/docs/docs/guides/staking/intro.mdx new file mode 100644 index 0000000..e781f8d --- /dev/null +++ b/docs/docs/guides/staking/intro.mdx @@ -0,0 +1,33 @@ +--- +title: Staking +sidebar_position: 0 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import Admonition from '@theme/Admonition'; +import useBaseUrl from '@docusaurus/useBaseUrl'; + +# Staking + +## Start Your Staking Journey + +This comprehensive guide walks you through staking your ETH and GNO with StakeWise step by step. + +StakeWise is a liquid staking platform that gives you complete control over how your assets are staked. Whether you're a beginner seeking simplicity or an advanced user wanting custom terms, StakeWise offers flexible staking solutions that earn rewards while keeping your stake liquid. + +Choose your staking method based on your needs: + +| Method | Best for | Key advantages | +|--------|----------|----------------| +| 🚀 **One-click staking** | Beginners, simple staking | • Instant staking in seconds • Protection from all slashing • No technical knowledge required | +| 🎯 **Staking with Vaults** | Custom control, higher yields | • Choose your node operators • Higher potential yields • Lower fees • Protection from other Vaults | +| 🏠 **Solo staking** | Advanced users, maximum control | • Run your own validators • Highest yields possible • Complete control over setup | + +:::custom-notes[New to liquid staking?] +Learn about [osToken →](/docs/ostoken/intro), [Vaults →](/docs/vaults/intro), and [how StakeWise works →](/docs/intro). +::: + +💡 Not sure which method to choose? Start with one-click staking for simplicity, then explore Vault options as you become more familiar with the platform. + +Next you'll find step-by-step instructions for each staking method. diff --git a/docs/docs/guides/staking/one-click-staking.mdx b/docs/docs/guides/staking/one-click-staking.mdx new file mode 100644 index 0000000..be81c87 --- /dev/null +++ b/docs/docs/guides/staking/one-click-staking.mdx @@ -0,0 +1,56 @@ +--- +title: One-Click Staking +sidebar_position: 1 +--- + +import Admonition from '@theme/Admonition'; + +# How to stake with one click? + +One-click staking routes your assets through a MetaVault that automatically distributes them among selected Vaults. This converts your assets into osTokens, StakeWise's liquid staking tokens, while providing diversified exposure across multiple professional operators. + +
+ 
+    Flow Staking Flow
+    ETH Your Assets → Vault StakeWise Vaults → osETH osTokens → 💰 Earn Rewards
+
+
+ +:::custom-notes[Wallet Requirements] +You'll need an Ethereum wallet such as [Rabby Wallet ↗](https://rabby.io/). +The process will look very similar in other wallets. +::: + +:::custom-info[What are osTokens?] +osTokens (osETH on Ethereum, osGNO on Gnosis Chain) represent your staked assets plus accumulated rewards. Use osTokens to trade, borrow, restake, or instantly unstake your staked assets via liquidity pools. [Learn more about osTokens →](/docs/ostoken/intro) +::: + +1. **Open [StakeWise App ↗](https://app.stakewise.io)** and connect your wallet +2. **Click the "Stake"** button to begin one-click staking +3. **Enter the amount** you want to stake in the input field +4. **Review conversion details** - The interface shows osTokens you'll receive, current rate, and estimated rewards +5. **Click "Stake"** and confirm the transaction in your wallet +6. **Wait for confirmation** (12-30 seconds) - osTokens will appear in your wallet and you start earning rewards + +:::custom-warning[Important Notes] +Ensure you have enough balance for both staking and gas fees for the transaction. +::: + +:::custom-info[Next Steps After Staking] +**Track your rewards** – osToken value increases over time as rewards accumulate + +**Use your osTokens** – Trade, provide liquidity, or use in DeFi protocols while earning staking rewards + +**Convert back anytime** – Swap osTokens back to the underlying asset through the app or exchanges when needed +::: diff --git a/docs/docs/guides/staking/overview.mdx b/docs/docs/guides/staking/overview.mdx new file mode 100644 index 0000000..22535f9 --- /dev/null +++ b/docs/docs/guides/staking/overview.mdx @@ -0,0 +1,36 @@ +--- +title: Staking Overview +sidebar_position: 0 +--- + +# Staking with StakeWise + +Stake your ETH and GNO to earn rewards while maintaining liquidity and control over your assets. + +## Choose Your Staking Method + +### 🚀 [One-Click Staking](./one-click-staking) +**Best for:** Beginners, simple staking + +Instant staking with automatic diversification across top-performing Vaults. Get osTokens immediately for instant liquidity. + +### 🎯 [Staking with Vaults](./staking-with-vaults) +**Best for:** Custom control, higher yields + +Choose specific node operators, fee structures, and MEV strategies. Optionally mint osTokens for liquidity. + +### 🏠 [Solo Staking](./solo-staking) +**Best for:** Advanced users, maximum control + +Run your own validators while maintaining liquidity through osTokens. Highest potential yields with full infrastructure control. + +--- + +## Need to Exit? + +### 🚪 [Unstaking](./unstaking) +Learn how to convert osTokens back to ETH/GNO or exit from Vault positions. + +--- + +💡 **Not sure which method to choose?** Start with one-click staking for simplicity, then explore Vault options as you become more familiar with the platform. diff --git a/docs/docs/guides/staking/solo-staking.mdx b/docs/docs/guides/staking/solo-staking.mdx new file mode 100644 index 0000000..02c6243 --- /dev/null +++ b/docs/docs/guides/staking/solo-staking.mdx @@ -0,0 +1,25 @@ +--- +title: Solo Staking +sidebar_position: 3 +--- + +import Admonition from '@theme/Admonition'; + +# Solo Staking with StakeWise + +For advanced users who want to run their own validators while maintaining liquidity, StakeWise offers solo staking through personal Vaults. This gives you maximum control and the highest potential yields. + +:::custom-info[Advanced Feature] +Solo staking requires technical expertise to run Ethereum / Gnosis Chain validators. It's recommended for experienced users comfortable with node operation and command-line tools. +::: + +**Benefits of solo staking with StakeWise:** +- 🎯 **Full control** over your validators and staking setup +- 💰 **Highest yields** with minimal fees +- 🔄 **Maintain liquidity** by minting osTokens against your stake +- ⚙️ **MEV smoothing** for stable execution layer rewards + +**To get started with solo staking:** +1. **Create your own Vault** using our [Vault creation guide →](/docs/guides/running-a-vault/how-to-create-a-vault) +2. **Set up validator infrastructure** following our [operator documentation →](/operator/intro) +3. **Stake in your Vault** and optionally [mint osTokens for liquidity →](/docs/ostoken/how-ostoken-works#minting) diff --git a/docs/docs/guides/staking/staking-with-vaults.mdx b/docs/docs/guides/staking/staking-with-vaults.mdx new file mode 100644 index 0000000..2960ba2 --- /dev/null +++ b/docs/docs/guides/staking/staking-with-vaults.mdx @@ -0,0 +1,55 @@ +--- +title: Staking with Vaults +sidebar_position: 3 +--- + +import Admonition from '@theme/Admonition'; + +# How to stake with Vaults? + +## Understanding Vault Staking + +Vault staking gives you control over exactly how your assets are staked. Unlike one-click staking, you can choose specific node operators, MEV strategies, and fee structures that match your preferences. + +:::custom-notes[Why Choose Vault Staking?] +**Higher potential yields** – Access to specialized operators and strategies + +**Custom terms** – Choose fee rates, node operators, and MEV handling + +**Isolated rewards** – Earn from your chosen Vault's performance only + +**Slashing protection** – Protected from penalties in other Vaults +::: + +1. **Navigate to Vaults** from the StakeWise homepage and connect your wallet +2. **Browse available Vaults** using filters for performance, APY, and TVL +3. **Select your Vault** and review its APY, operator info, fees, and capacity +4. **Click "Stake"** and enter the amount you want to stake +5. **Review terms** and confirm the transaction in your wallet + + +## Making Your Stake Liquid (Optional) + +After staking in a Vault, you can mint osTokens against your stake to maintain liquidity: + +1. **Access Mint Option**: On your Vault's page, find the **"Mint osToken"** section +2. **Choose Amount**: Use the slider or enter the amount of osTokens to mint + - Maximum: 90% of your stake (99.99% for selected Vaults) + - Your full staking rewards continue regardless of minting ratio + +3. **Complete Minting**: Confirm the transaction to receive osTokens +4. **Monitor Health**: Keep track of your position health in the Vault interface + +:::custom-info[Position Health] +Your osToken position has health levels (Healthy, Moderate, Risky, Unhealthy) based on your Vault's performance relative to osTokens. Monitor this to avoid liquidation. [Learn more →](/docs/ostoken/how-ostoken-works#position-health) +::: + +## Vault Staking Management + +Once staked in a Vault, you can: + +- **📈 Track Performance**: Monitor your Vault's APY and your earned rewards +- **🔄 Mint/Burn osTokens**: Adjust your liquid staking position as needed ([Learn about minting →](/docs/ostoken/how-ostoken-works#minting) | [Learn about burning →](/docs/ostoken/how-ostoken-works#burning)) +- **⚡ Use Boost**: Increase your staking rewards with additional yield opportunities +- **📤 Unstake**: Exit the Vault (requires burning all minted osTokens first) +- **💱 Switch Vaults**: Unstake from one and stake in another for better terms diff --git a/docs/docs/guides/staking/unstaking.mdx b/docs/docs/guides/staking/unstaking.mdx new file mode 100644 index 0000000..b8c860b --- /dev/null +++ b/docs/docs/guides/staking/unstaking.mdx @@ -0,0 +1,57 @@ +--- +title: Unstaking +sidebar_position: 4 +--- + +import Admonition from '@theme/Admonition'; + +# How to unstake? + +Unstaking is as simple and straightforward as staking, varying just slightly depending on how you staked your assets. + +
+ 
+    Flow Unstaking Flow
+    🔥 Burn osTokens → 🚪 Unstaking → 📥 Claim Rewards → 👛 Receive Assets
+
+
+ +## From One-Click Staking + +If you staked directly for osTokens, you can convert them back anytime: + +1. **Convert osTokens** – Go to StakeWise app, click **"Unstake"**, enter amount to convert back +2. **Confirm transaction** – Review conversion rate and confirm in your wallet +3. **Receive assets** – Get your original assets plus rewards immediately + +## From Vault Staking + +:::custom-warning[Required Step] +To unstake from a Vault, you must first **burn the osTokens you minted**. The interface shows exactly how much to burn. +::: + +:::custom-notes[When unstaking from Vaults:] +Burn osETH → Enter unstake amount → Confirm transaction → Join unstake queue → Claim ETH. +::: + +1. **Burn osTokens** – Click **minus (–)** button, enter amount or click **"Max"**, click **"Confirm"** +2. **Unstake assets** – Click **minus (–)** button, enter withdrawal amount, click **"Unstake"** +3. **Join queue** – Confirmation shows **"Added to unstake queue"** +4. **Claim assets** – Once assets are exited, click **"Claim"** to receive your assets + +:::custom-notes[Processing Times] +- **One-click unstaking**: Immediate conversion +- **osETH burning in Vaults**: Immediate once confirmed +- **Vault unstaking**: Depends on the network exit queue length +::: diff --git a/docs/docs/intro.mdx b/docs/docs/intro.mdx index 220bf34..29a13cb 100644 --- a/docs/docs/intro.mdx +++ b/docs/docs/intro.mdx @@ -91,13 +91,13 @@ StakeWise is a liquid staking protocol that gives you the benefits of permission Operating across Ethereum and Gnosis Chain, StakeWise creates a comprehensive staking network that serves diverse participants through three distinct approaches: -**[Vaults →](./protocol-concepts/Vaults)**: For advanced users seeking full control, choose from diverse staking pool offerings with distinct fee structures, MEV strategies, and risk profiles, empowering you to easily earn staking yields with complete control over your assets and validator selection. Instant liquidity and DeFi integrations are available on-demand by opting to receive osToken when staking. +**[Vaults →](./vaults/intro)**: For advanced users seeking full control, choose from diverse staking pool offerings with distinct fee structures, MEV strategies, and risk profiles, empowering you to easily earn staking yields with complete control over your assets and validator selection. Instant liquidity and DeFi integrations are available on-demand by opting to receive osToken when staking. -**[One-click staking →](./guides/staking#how-to-stake-with-one-click)**: For users who want to start earning immediately without thinking twice, go for streamlined staking that automatically allocates your stake across proven Vaults that minimize fees and maximize your yield. osToken is issued automatically, granting access to instant liquidity and DeFi by default. +**[One-click staking →](./guides/staking/one-click-staking)**: For users who want to start earning immediately without thinking twice, go for streamlined staking that automatically allocates your stake across proven Vaults that minimize fees and maximize your yield. osToken is issued automatically, granting access to instant liquidity and DeFi by default. -**[Run own Vault →](./guides/running-a-vault)**: For users and organizations that seek to run their own nodes to access liquidity for their stake, or offer a staking service to others, Vaults allow you to set up isolated, non-custodial, and customizable staking environments that preserve optional access to liquidity via osToken. Vaults already handle billions of US dollars worth of staked assets, powering solutions from [MetaMask ↗](https://metamask.io/), [Chorus One ↗](https://chorus.one/), [Blockchain.com ↗](http://Blockchain.com), [Ledger Live ↗](https://www.ledger.com/ledger-live), and others. +**[Run own Vault →](./guides/running-a-vault/how-to-create-a-vault)**: For users and organizations that seek to run their own nodes to access liquidity for their stake, or offer a staking service to others, Vaults allow you to set up isolated, non-custodial, and customizable staking environments that preserve optional access to liquidity via osToken. Vaults already handle billions of US dollars worth of staked assets, powering solutions from [MetaMask ↗](https://metamask.io/), [Chorus One ↗](https://chorus.one/), [Blockchain.com ↗](http://Blockchain.com), [Ledger Live ↗](https://www.ledger.com/ledger-live), and others. -StakeWise also continuously develops innovative strategies to maximize your rewards, such as [Boost →](./guides/defi/boost), with more features coming soon. +StakeWise also continuously develops innovative strategies to maximize your rewards, such as [Boost →](./guides/defi/boost-feature), with more features coming soon. ### Architecture StakeWise's modular architecture is built on three foundational pillars: Vaults, osToken, and Oracles. @@ -116,7 +116,7 @@ This open marketplace model democratizes liquid staking, giving you the freedom - **Risk Isolation**: Each Vault operates independently — issues in one do not affect others. :::custom-notes[Deep Dive] -Learn more about [Vaults →](./protocol-concepts/Vaults) +Learn more about [Vaults →](./vaults/intro) ::: #### osToken — Overcollateralized Staking Token @@ -131,7 +131,7 @@ It can be minted by staking in Vaults or acquired directly on a DEX to start ear - **DeFi Ready**: Fully composable and compatible with lending, trading, and yield-farming protocols. :::custom-notes[Deep Dive] -Learn more about [osToken →](./protocol-concepts/osToken) +Learn more about [osToken →](./ostoken/intro) ::: #### Oracles — Decentralized Infrastructure Layer @@ -141,10 +141,10 @@ 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 →](./protocol-concepts/osToken#reward-accrual--fee-mechanism) +- **Token Stability**: Maintains accurate osToken exchange rates and safeguards peg stability. [Learn more →](./ostoken/how-ostoken-works#reward-accrual--fee-mechanism) :::custom-notes[Deep Dive] -Learn more about [Oracles →](./protocol-concepts/Oracles) +Learn more about [Oracles →](./oracles/intro) ::: ### Governance & SWISE Token diff --git a/docs/docs/oracles/intro.mdx b/docs/docs/oracles/intro.mdx new file mode 100644 index 0000000..0c45d71 --- /dev/null +++ b/docs/docs/oracles/intro.mdx @@ -0,0 +1,46 @@ +--- +title: Oracles +sidebar_position: 0 +description: "Learn how Oracles validate transactions and distribute rewards" +--- + +import Admonition from '@theme/Admonition'; + +```mdx-code-block +import Tooltip from '@site/src/components/Tooltip/Tooltip'; +``` + +# Oracles + +Oracles are specialized entities that connect blockchains to external data sources, enabling smart contracts to access real-world information. + +In the StakeWise protocol, Oracles monitor validator performance data on the Beacon Chain and reach consensus on validator registration approvals, reward distribution, and exit processes within Vaults. + +Oracles are a crucial part of the protocol, and they must remain sufficiently decentralized and maintain high uptime for StakeWise to work seamlessly. + +The protocol operates with [11 Oracles](#oracle-network-participants) selected and [approved ↗](https://vote.stakewise.io/#/proposal/0x54ceedefd1060fbad17ab6181be5a90da4c686dc071d1f6121d24c0398700be6) +by the StakeWise DAO through governance processes. +These Oracles form a decentralized network of independent nodes that ensures protocol resilience and prevents single points of failure. +This distributed approach eliminates centralized control, reduces regulatory capture risks, and ensures protocol longevity through consensus-based decision making. + +Oracle decisions require threshold-based consensus depending on the operation. +Validator registration requires 8 out of 11 Oracle signatures, while reward updates need 6 out of 11 signatures. + +Through Oracle consensus, all Vaults stay synced with the Beacon Chain, display accurate information, trigger secure and timely new validator registrations, and fulfill exit requests. +These duties are performed automatically using Oracle software developed by the StakeWise team, with no manual actions involved. + +Oracles are one of the protocol's building blocks to deliver seamless staking and unstaking experiences. + +## Oracle Network Participants + +1. [Chorus One ↗](https://chorus.one/) +2. [Stake.fish ↗](https://stake.fish/) +3. [Telekom ↗](https://www.telekom-mms.com/) (formerly T-Systems MMS) +4. [Finoa Consensus Services ↗](https://www.finoa.io/) +5. [Bitfly ↗](https://gobitfly.com/) (operators of the [Beaconchain ↗](https://beaconcha.in/) explorer) +6. [SenseiNode ↗](https://www.senseinode.com/) +7. [Gateway.fm ↗](https://gateway.fm/) +8. [Gnosis Chain ↗](https://www.gnosis.io/) team +9. [P2P ↗](https://p2p.org/) +10. [DSRV ↗](https://www.dsrvlabs.com/) +11. [StakeWise Labs ↗](https://x.com/stakewise_io) (the development team) diff --git a/docs/docs/protocol-concepts/Oracles.mdx b/docs/docs/oracles/oracle-duties.mdx similarity index 55% rename from docs/docs/protocol-concepts/Oracles.mdx rename to docs/docs/oracles/oracle-duties.mdx index 939f775..a77df04 100644 --- a/docs/docs/protocol-concepts/Oracles.mdx +++ b/docs/docs/oracles/oracle-duties.mdx @@ -1,7 +1,7 @@ --- -title: Oracles -sidebar_position: 3 -description: "Learn how Oracles validate transactions and distribute rewards" +title: Oracle Duties +sidebar_position: 1 +description: "Learn about validator registration approval, reward distribution, and validator exits" --- import Admonition from '@theme/Admonition'; @@ -10,40 +10,17 @@ import Admonition from '@theme/Admonition'; import Tooltip from '@site/src/components/Tooltip/Tooltip'; ``` -# Oracles - -## Introduction - -Oracles are specialized entities that connect blockchains to external data sources, enabling smart contracts to access real-world information. - -In the StakeWise protocol, Oracles monitor validator performance data on the Beacon Chain and reach consensus on validator registration approvals, reward distribution, and exit processes within Vaults. - -Oracles are a crucial part of the protocol, and they must remain sufficiently decentralized and maintain high uptime for StakeWise to work seamlessly. - -The protocol operates with [11 Oracles](#oracle-network-participants) selected and [approved ↗](https://vote.stakewise.io/#/proposal/0x54ceedefd1060fbad17ab6181be5a90da4c686dc071d1f6121d24c0398700be6) -by the StakeWise DAO through governance processes. -These Oracles form a decentralized network of independent nodes that ensures protocol resilience and prevents single points of failure. -This distributed approach eliminates centralized control, reduces regulatory capture risks, and ensures protocol longevity through consensus-based decision making. - -Oracle decisions require threshold-based consensus depending on the operation. -Validator registration requires 8 out of 11 Oracle signatures, while reward updates need 6 out of 11 signatures. - -Through Oracle consensus, all Vaults stay synced with the Beacon Chain, display accurate information, trigger secure and timely new validator registrations, and fulfill exit requests. -These duties are performed automatically using Oracle software developed by the StakeWise team, with no manual actions involved. - -Oracles are one of the protocol’s building blocks to deliver seamless staking and unstaking experiences. - -## Oracle Duties +# Oracle Duties Oracles run the [v3-oracle ↗](https://github.com/stakewise/v3-oracle) nodes and are responsible for validator registration, reward distribution, and validator exits. -### Validator Registration Approval +## Validator Registration Approval Oracles approve validator registration requests before they are submitted to the Beacon Chain [Deposit Contract ↗](https://etherscan.io/address/0x00000000219ab540356cbb839cbe05303d7705fa#code). The [Operator Service →](../../operator/start-operator) periodically checks whether its Vaults have accumulated enough ETH for registering new validator(s). When the Vault has enough ETH, the operator sends a registration approval request to Oracles that includes encrypted exit signature(s) for the validator(s) it is attempting to create. -This is done to maintain the protocol’s ability to exit validators on demand, and to perform checks against the front-running withdrawal credentials attack described [here ↗](https://blog.lido.fi/vulnerability-response-update/). +This is done to maintain the protocol's ability to exit validators on demand, and to perform checks against the front-running withdrawal credentials attack described [here ↗](https://blog.lido.fi/vulnerability-response-update/). The operator must receive **8 out of 11 approvals** from Oracles to register a validator for the Vault. :::custom-notes[Approval Process] @@ -57,10 +34,10 @@ The operator must receive **8 out of 11 approvals** from Oracles to register a v This process ensures Oracles approve validators based on current Beacon Chain state, bridging the consensus and execution layers while preventing stale approvals and replay attacks. :::custom-notes[Deep Dive] -For details on how the Operator Service initiates and prepares validator registration, see the [Validator Registration →](./Vaults#validator-registration) section in Vaults. +For details on how the Operator Service initiates and prepares validator registration, see the [Validator Registration →](../vaults/how-vaults-work#validator-registration) section in Vaults. ::: -### Reward Distribution +## Reward Distribution Oracles periodically vote on the consensus rewards/penalties accumulated by the Vaults in the Beacon Chain and execution rewards (MEV & priority fees) for the Vaults connected to the Smoothing Pool. @@ -79,7 +56,7 @@ The reward distribution process consists of the following steps: The reward update process has protocol-wide impact. -### Validator Exits +## Validator Exits The validator exit process is automated and trustless. Validator exits require exit signatures that are generated during the [Validator Registration →](../../operator/start-operator) process. @@ -89,17 +66,3 @@ As part of registration, the Operator Service encrypts exit signatures using Sha :::custom-notes[Key Benefit] This approach ensures validators can be exited on demand while maintaining protocol security through decentralized signature management. ::: - -## Oracle Network Participants - -1. [Chorus One ↗](https://chorus.one/) -2. [Stake.fish ↗](https://stake.fish/) -3. [Telekom ↗](https://www.telekom-mms.com/) (formerly T-Systems MMS) -4. [Finoa Consensus Services ↗](https://www.finoa.io/) -5. [Bitfly ↗](https://gobitfly.com/) (operators of the [Beaconchain ↗](https://beaconcha.in/) explorer) -6. [SenseiNode ↗](https://www.senseinode.com/) -7. [Gateway.fm ↗](https://gateway.fm/) -8. [Gnosis Chain ↗](https://www.gnosis.io/) team -9. [P2P ↗](https://p2p.org/) -10. [DSRV ↗](https://www.dsrvlabs.com/) -11. [StakeWise Labs ↗](https://x.com/stakewise_io) (the development team) diff --git a/docs/docs/protocol-concepts/OsToken.mdx b/docs/docs/ostoken/how-ostoken-works.mdx similarity index 88% rename from docs/docs/protocol-concepts/OsToken.mdx rename to docs/docs/ostoken/how-ostoken-works.mdx index 878365d..c0217df 100644 --- a/docs/docs/protocol-concepts/OsToken.mdx +++ b/docs/docs/ostoken/how-ostoken-works.mdx @@ -1,36 +1,21 @@ --- -title: osToken -sidebar_position: 2 -description: "Learn what osToken is and how to get it" +title: How osToken Works +sidebar_position: 1 +description: "Learn about osToken minting, burning, exchange rate, and peg maintenance" --- import Admonition from '@theme/Admonition'; -# osToken - -## Introduction - -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: - -- **osETH** on Ethereum -- **osGNO** on Gnosis Chain - -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. - -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. - -## How osToken Works +# 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. -### Minting +## 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 +### Loan-to-Value Limits The LTV ratio determines what portion of your stake can be tokenized with osToken: @@ -41,7 +26,7 @@ The LTV ratio determines what portion of your stake can be tokenized with osToke This ensures that even if some validators get slashed, there are enough assets to back all outstanding osTokens. -#### LTV Threshold Settings +### LTV Threshold Settings The StakeWise DAO sets **Loan-to-Value (LTV) thresholds** that determine how much osToken can be minted against staked assets in each Vault. @@ -72,7 +57,7 @@ StakeWise DAO has the capability to increase or decrease the osETH minting thres - Overcollateralization: `10 ETH` remains as safety buffer ::: -#### Minting & Buying Options +### Minting & Buying Options osToken can be acquired via four methods: @@ -84,10 +69,10 @@ osToken can be acquired via four methods: All methods yield the same asset that appreciates through the same exchange rate mechanism. :::custom-notes[Deep Dive] -Find step-by-step instructions for each staking option in the [Staking Guide →](/docs/guides/staking). +Find step-by-step instructions for each staking option in the [Staking Guide →](/docs/guides/staking/intro). ::: -#### Position Health +### Position Health Position health is continuously tracked through LTV thresholds: @@ -105,7 +90,7 @@ Position health is continuously tracked through LTV thresholds: 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. -### Burning +## Burning 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. @@ -138,7 +123,7 @@ Bob stakes **100 ETH** and mints **50 osETH** at an exchange rate of **1.05 ETH/ - Position health: `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 position health = **90%** +After unstaking **41.667 ETH**, Bob's position health = **90%** ::: :::custom-notes[Alice's 99.99% LTV Position] @@ -147,10 +132,10 @@ Alice stakes **100 ETH** and mints **50 osETH** at the same **1.05** rate. - Position health: `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 position health = **99.99%** +After unstaking **47.495 ETH**, Alice's position health = **99.99%** ::: -### Peg Maintenance +## Peg Maintenance 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. @@ -158,7 +143,7 @@ Redemption acts as early intervention when positions drift toward risky erosion 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. -#### Redemption Mechanism +### Redemption Mechanism 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. @@ -191,7 +176,7 @@ Bob stakes **100 ETH** and mints **87.238 osETH** at an exchange rate of **1.05 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 Mechanism +### Liquidation Mechanism 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. @@ -222,7 +207,7 @@ Alice stakes **100 ETH** and mints **87.629 osETH** at an exchange rate of **1.0 Positions in **99.99% LTV Vaults** are exempt from liquidation, as their APY parity ensures position health remains stable. -### Exchange Rate Appreciation +## Exchange Rate Appreciation 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. @@ -233,7 +218,7 @@ As rewards accrue, the redemption value increases, creating the "repricing" effe 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. -### Reward Accrual & Fee Mechanism +## Reward Accrual & Fee Mechanism 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. @@ -258,5 +243,5 @@ your debt grows by **0.000001**—your proportional share of the protocol's accu ::: :::custom-info[Learn More] -For comprehensive information about all protocol fees, see the [Fees →](./Fees) chapter. +For comprehensive information about all protocol fees, see the [Fees →](../fees/intro) chapter. ::: diff --git a/docs/docs/ostoken/intro.mdx b/docs/docs/ostoken/intro.mdx new file mode 100644 index 0000000..0084d22 --- /dev/null +++ b/docs/docs/ostoken/intro.mdx @@ -0,0 +1,18 @@ +--- +title: osToken +sidebar_position: 0 +description: "Learn what osToken is and how to get it" +--- + +# 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: + +- **osETH** on Ethereum +- **osGNO** on Gnosis Chain + +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. + +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. diff --git a/docs/docs/protocol-concepts/_category_.json b/docs/docs/protocol-concepts/_category_.json deleted file mode 100644 index ae63504..0000000 --- a/docs/docs/protocol-concepts/_category_.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "label": "Protocol Concepts", - "position": 2, - "link": { - "type": "generated-index" - } -} diff --git a/docs/docs/vaults/customization.mdx b/docs/docs/vaults/customization.mdx new file mode 100644 index 0000000..5955562 --- /dev/null +++ b/docs/docs/vaults/customization.mdx @@ -0,0 +1,127 @@ +--- +title: Customization +sidebar_position: 2 +description: "Learn how to customize Vault settings, types, fees, and management roles" +--- + +# Customization + +Each Vault is highly customizable. +Core parameters such as Vault type, capacity, and MEV strategy are immutable and set once upon deployment, +while management roles, branding, and fees can be changed later. + +## Vault Type + +All Vault types support osToken minting. The Vault types differ in their specific characteristics and restrictions. + +### Standard Vaults — Most Common + +Receive staking deposits from any wallet and issue non-transferable Vault shares that earn rewards. + +### ERC-20 Vaults — For Custom Utility & Liquidity Ecosystem + +Allow Vault operators to build their own DeFi ecosystem using the Vault's token. +The operator sets the token's name and symbol (e.g., mntETH), which will be visible in most portfolio tracking applications. +Users can mint osToken and transfer their stake in the Vault as long as they don't have osToken minted. + +:::custom-info[Note] +Standard Vaults (tokenless) help avoid potential tax events that could be triggered by exchanging ETH for a Vault token. +::: + +### Private Vaults — Restricted Access + +Receive staking deposits from wallets that have been whitelisted by the Vault Admin. + +### Blocklist Vaults — Open with Exceptions + +Receive staking deposits from any wallets except those on a blocklist. + +### Meta Vaults — Diversified Strategy + +Meta Vaults do not register validators directly — +instead, they delegate accumulated assets to sub-Vaults, which are managed by the Vault Admin. +Each sub-Vault must have at least one registered validator. + +Deposits are distributed across underlying sub-Vaults (up to 50 maximum) according to curator-defined allocation logic. The default `BalancedCurator` distributes assets evenly across eligible sub-Vaults. +The Curator contract can be changed by the Admin. + +MetaVaults can be deployed using the `EthMetaVaultFactory` contract, and currently, +only the factory owner is permitted to deploy new MetaVaults. + +## Capacity + +Vault capacity is an immutable deposit limit that Vault operators set once during initialization to control the maximum amount of ETH their Vault can accept. When left unset, Vaults have unlimited capacity by default. The capacity is enforced on every +deposit transaction, reverting with a `CapacityExceeded` error if exceeded. Capacity helps control validator set size based on operator infrastructure capabilities. + +## MEV Strategy + +MEV (Maximum Extractable Value) represents additional profits that validators can earn when proposing blocks. +Vaults can use either a Smoothing Pool or Own Escrow for collecting the block rewards. + +### Smoothing Pool — Pooled Rewards + +Rewards are pooled across multiple Vaults and distributed evenly, providing more stable and predictable returns regardless of block proposal frequency. + +For example, a Vault with only a few validators can receive periodic small payouts from the Smoothing Pool, which come from the block proposal rewards contributed by other participating Vaults. +In return, when the Vault does get the chance to earn a block proposal reward, it will flow to the Smoothing Pool as well, to be shared amongst all participating Vaults. + +The main advantage of using the Smoothing Pool is achieving a consistent level of rewards from block production, and a consistent Vault APY. + +Any Vault that opts into using the Smoothing Pool is required to operate one of the StakeWise DAO-approved MEV relays. This is necessary to ensure a consistently high contribution to the Smoothing Pool from every participating Vault. + +### Own Escrow — Own Rewards + +Rewards are collected solely by individual Vaults. +Own Escrow allows a Vault to choose an independent approach to earning block production rewards, +like using any relay of choice, because it does not rely on sharing such rewards with other Vaults. +Own Escrow targets maximum value capture but with increased variability. + +## Management Roles + +Every Vault has several key roles for the internal management of the staking process: + +### Admin + +Primary controller of the Vault. Responsible for overall Vault configuration. + - Manage all roles and permissions + - Modify fees and fee recipients + - Update Vault branding (name, description, image) + - Configure Vault settings and parameters + +The Admin can be a single wallet, multisig, or DAO and can be changed through the `setAdmin` function. +Only the current Admin can call this function. + +### Vault fee claimer + +Can claim accumulated Vault fees on behalf of shareholders. + +### Whitelist / Blocklist manager + +Access controller for deposit permissions. + - Add/remove accounts authorized to deposit (whitelist) + - Add/remove accounts prohibited from depositing (blocklist) + +This role only appears for Private Vaults or Vaults with blocklist functionality enabled. + +### Validators manager + +Technical operator responsible for validator operations. + +## Branding + +Vault operators can set their Vault's name, description, and image simply through the StakeWise interface and these can be updated anytime by the Admin. + +:::custom-stakewise[Authenticity Guarantee] +Stakers can be confident about the authenticity of this information, i.e., a Vault branded by Operator A is indeed controlled and run by Operator A. +Verification is a manual process managed by the core StakeWise team. +::: + +## Fee + +Vault operators can charge fees on staking rewards to compensate for infrastructure and management costs. +These fees are set by the Vault Admin and can be updated over time, +subject to protocol-enforced restrictions to protect users from sudden changes. + +:::custom-notes[Deep Dive] +For complete details about Vault fees, see [Fees →](../fees/intro). +::: diff --git a/docs/docs/protocol-concepts/Vaults.mdx b/docs/docs/vaults/how-vaults-work.mdx similarity index 53% rename from docs/docs/protocol-concepts/Vaults.mdx rename to docs/docs/vaults/how-vaults-work.mdx index a2c2bf2..50277d9 100644 --- a/docs/docs/protocol-concepts/Vaults.mdx +++ b/docs/docs/vaults/how-vaults-work.mdx @@ -1,45 +1,32 @@ --- -title: Vaults +title: How Vaults Work sidebar_position: 1 -description: "Learn what Vaults are and what you can do with them" +description: "Learn how Vaults register validators, distribute rewards, and process withdrawals" --- ```mdx-code-block import Tooltip from '@site/src/components/Tooltip/Tooltip'; ``` -# Vaults +# How Vaults Work -## Introduction - -Vaults are isolated staking pools that process ETH and GNO deposits for staking, distribute rewards, and handle withdrawals in a trustless and non-custodial manner. - -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. - -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. - -All deposits, reward distribution, and withdrawals are handled by smart contracts, making staking in Vaults fully non-custodial. - -## How Vaults Work - -### Validator registration +## Validator registration Vaults collect user deposits and manage the validator lifecycle through smart contracts. When a Vault accumulates enough assets — 32 ETH on Ethereum or 1 GNO on Gnosis — the system initiates validator registration. Vault operator(s)
Entities or individuals who run validators for a Vault. They operate the infrastructure and run the operator service software ↗ that automates essential Vault management tasks — such as validator registration, consolidations, and withdrawals.}>The Vault operator -runs specialized software (the [operator ↗](https://github.com/stakewise/v3-operator) service) alongside their Ethereum [consensus →](../../operator/prerequisites#consensus-client) and [execution →](../../operator/prerequisites#execution-client) clients +runs specialized software (the [operator ↗](https://github.com/stakewise/v3-operator) service) alongside their Ethereum [consensus →](../../operator/Prerequisites#consensus-client) and [execution →](../../operator/Prerequisites#execution-client) clients that monitor deposit levels and handle the technical validator setup process. -When sufficient funds are available, this service submits validator registration requests to the StakeWise [Oracle network →](./Oracles). +When sufficient funds are available, this service submits validator registration requests to the StakeWise [Oracle network →](../oracles/intro). The Operator Service must receive 8 out of 11 approvals from Oracles to register a validator for the Vault. The service automatically generates deposit data during registration, eliminating the need for pre-uploaded deposit data files. Once approved, validators enter the Beacon Chain's activation queue. [Network ↗](https://www.validatorqueue.com/) conditions determine how quickly they begin earning staking rewards. Vaults support two types of validators: `0x01` or `0x02`1. The default type is `0x02`. 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 technical process for registering validators involves coordination between the [Operator Service →](../../operator/intro) and the [Oracle network →](./Oracles): +The technical process for registering validators involves coordination between the [Operator Service →](../../operator/intro) and the [Oracle network →](../oracles/intro): :::custom-notes[Validator Registration Process] The Operator Service performs the following steps: @@ -56,10 +43,10 @@ The Operator Service performs the following steps: Vaults can have several node operators running validators and support Distributed Validator Technology
A solution designed to overcome a single-operator trust problem by splitting a validator's private key among multiple independent operators.
More on DVT - ethereum.org ↗}>Distributed Validator Technology (DVT) to increase redundancy. :::custom-notes[Deep Dive] -For more details on how Oracles handle the validator registration approval process, see [Validator Registration Approval →](./Oracles#validator-registration-approval). +For more details on how Oracles handle the validator registration approval process, see [Validator Registration Approval →](../oracles/oracle-duties#validator-registration-approval). ::: -### Reward Distribution +## Reward Distribution Once validators are registered and active, they earn: - **Consensus layer rewards**: Block proposals, attestations, and sync committee participation @@ -69,7 +56,7 @@ Validators receive rewards only between their activation and exit epochs. The Vault initially holds rewards as liquid ETH until there is enough to register additional validators. -After the Pectra
The Prague/Electra (Pectra) hardfork activated in May 2025, introducing significant changes to both execution and consensus layers. Key features include variable validator effective balance (32-2048 ETH), execution layer triggerable exits, improved deposit processing, BLS12-381 precompile for cheaper zkSNARK verification, programmable EOAs, and increased blob throughput, establishing a base layer for future scaling efforts.}>[Pectra ↗](https://ethereum.org/en/roadmap/pectra/) upgrade, +After the Pectra
The Prague/Electra (Pectra) hardfork activated on 07-May-2025 at epoch 364032, introducing significant changes to both execution and consensus layers. Key features include variable validator effective balance (32-2048 ETH via EIP-7251), execution layer triggerable exits (EIP-7002), improved deposit processing (EIP-6110), BLS12-381 precompile (EIP-2537), programmable EOAs (EIP-7702), and increased blob throughput (EIP-7691), establishing a base layer for future scaling efforts.}>[Pectra ↗](https://ethereum.org/en/roadmap/pectra/) upgrade, EIP-7251
Ethereum Improvement Proposal that increases the maximum effective balance of validators from 32 ETH to 2048 ETH, enabling validator consolidation and partial withdrawals.}>[EIP-7251 ↗](https://eips.ethereum.org/EIPS/eip-7251) allows Vaults to merge multiple 32 ETH validators into fewer `0x02` compound validators with higher effective balances, thus improving efficiency and reducing infrastructure overhead, while allowing partial withdrawals of rewards above 32 ETH. Each Vault decides whether to: @@ -82,10 +69,10 @@ within the Vault for greater liquidity. Rewards are calculated off-chain by the StakeWise Oracle Network. :::custom-notes[Deep Dive] -For detailed information about the reward distribution process, see [*Oracles*: Reward Distribution →](./Oracles#reward-distribution). +For detailed information about the reward distribution process, see [*Oracles*: Reward Distribution →](../oracles/oracle-duties#reward-distribution). ::: -### Withdrawals +## Withdrawals 
4.
+Partial withdrawals for `0x02` compound validators are now supported and can now be triggered from the execution layer via [EIP-7002](https://eips.ethereum.org/EIPS/eip-7002)4.
 The withdrawal fulfillment process is automated by the [Operator Service →](../../operator/intro), which manages validator exits and partial withdrawals among other responsibilities to ensure timely processing of the exit queue.
 
 :::custom-info[Processing Time]
 On mainnet, partial withdrawals typically complete faster (≈27–28 hours), while full exits can take **up to one month** to finalize.
 :::
 
-#### Validator Exits
+### Validator Exits
 
 The Operator Service automatically triggers validator exits when required.
 By default, the Operator Service checks every **12 hours** (configurable via `WITHDRAWALS_INTERVAL`) to process queued withdrawal requests.
@@ -142,217 +129,16 @@ Exit processing time depends on the Ethereum network conditions.
 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 according to their ticket number.
 
-### osToken
+## osToken
 
 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 Vaults6.
 
 :::custom-notes[Deep Dive]
-For more details on how osToken works, see [osToken →](osToken).
+For more details on how osToken works, see [osToken →](../ostoken/intro).
 :::
 
-## Customization
-
-Each Vault is highly customizable.
-Core parameters such as Vault type, capacity, and MEV strategy are immutable and set once upon deployment,
-while management roles, branding, and fees can be changed later.
-
-### Vault Type
-
-All Vault types support osToken minting. The Vault types differ in their specific characteristics and restrictions.
-
-#### Standard Vaults — Most Common
-
-Receive staking deposits from any wallet and issue non-transferable Vault shares that earn rewards.
-
-#### ERC-20 Vaults — For Custom Utility & Liquidity Ecosystem
-
-Allow Vault operators to build their own DeFi ecosystem using the Vault's token.
-The operator sets the token's name and symbol (e.g., mntETH), which will be visible in most portfolio tracking applications.
-Users can mint osToken and transfer their stake in the Vault as long as they don't have osToken minted.
-
-:::custom-info[Note]
-Standard Vaults (tokenless) help avoid potential tax events that could be triggered by exchanging ETH for a Vault token.
-:::
-
-#### Private Vaults — Restricted Access
-
-Receive staking deposits from wallets that have been whitelisted by the Vault Admin.
-
-#### Blocklist Vaults — Open with Exceptions
-
-Receive staking deposits from any wallets except those on a blocklist.
-
-#### Meta Vaults — Diversified Strategy
-
-Meta Vaults do not register validators directly —
-instead, they delegate accumulated assets to sub-Vaults, which are managed by the Vault Admin.
-Each sub-Vault must have at least one registered validator.
-
-Deposits are distributed across underlying sub-Vaults (up to 50 maximum) according to curator-defined allocation logic. The default `BalancedCurator` distributes assets evenly across eligible sub-Vaults.
-The Curator contract can be changed by the Admin.
-
-MetaVaults can be deployed using the `EthMetaVaultFactory` contract, and currently,
-only the factory owner is permitted to deploy new MetaVaults.
-
-### Capacity
-
-Vault capacity is an immutable deposit limit that Vault operators set once during initialization to control the maximum amount of ETH their Vault can accept. When left unset, Vaults have unlimited capacity by default. The capacity is enforced on every
-deposit transaction, reverting with a `CapacityExceeded` error if exceeded. Capacity helps control validator set size based on operator infrastructure capabilities.
-
-### MEV Strategy
-
-MEV (Maximum Extractable Value) represents additional profits that validators can earn when proposing blocks.
-Vaults can use either a Smoothing Pool or Own Escrow for collecting the block rewards.
-
-#### Smoothing Pool — Pooled Rewards
-
-Rewards are pooled across multiple Vaults and distributed evenly, providing more stable and predictable returns regardless of block proposal frequency.
-
-For example, a Vault with only a few validators can receive periodic small payouts from the Smoothing Pool, which come from the block proposal rewards contributed by other participating Vaults.
-In return, when the Vault does get the chance to earn a block proposal reward, it will flow to the Smoothing Pool as well, to be shared amongst all participating Vaults.
-
-The main advantage of using the Smoothing Pool is achieving a consistent level of rewards from block production, and a consistent Vault APY.
-
-Any Vault that opts into using the Smoothing Pool is required to operate one of the StakeWise DAO-approved MEV relays. This is necessary to ensure a consistently high contribution to the Smoothing Pool from every participating Vault.
-
-#### Own Escrow — Own Rewards
-
-Rewards are collected solely by individual Vaults.
-Own Escrow allows a Vault to choose an independent approach to earning block production rewards,
-like using any relay of choice, because it does not rely on sharing such rewards with other Vaults.
-Own Escrow targets maximum value capture but with increased variability.
-
-### Management Roles
-
-Every Vault has several key roles for the internal management of the staking process:
-
-#### Admin
-
-Primary controller of the Vault. Responsible for overall Vault configuration.
-  - Manage all roles and permissions
-  - Modify fees and fee recipients
-  - Update Vault branding (name, description, image)
-  - Configure Vault settings and parameters
-
-The Admin can be a single wallet, multisig, or DAO and can be changed through the `setAdmin` function.
-Only the current Admin can call this function.
-
-#### Vault fee claimer
-
-Can claim accumulated Vault fees on behalf of shareholders.
-
-#### Whitelist / Blocklist manager
-
-Access controller for deposit permissions.
-  - Add/remove accounts authorized to deposit (whitelist)
-  - Add/remove accounts prohibited from depositing (blocklist)
-
-This role only appears for Private Vaults or Vaults with blocklist functionality enabled.
-
-#### Validators manager
-
-Technical operator responsible for validator operations.
-
-### Branding
-
-Vault operators can set their Vault's name, description, and image simply through the StakeWise interface and these can be updated anytime by the Admin.
-
-:::custom-stakewise[Authenticity Guarantee]
-Stakers can be confident about the authenticity of this information, i.e., a Vault branded by Operator A is indeed controlled and run by Operator A.
-Verification is a manual process managed by the core StakeWise team.
-:::
-
-### Fee
-
-Vault operators can charge fees on staking rewards to compensate for infrastructure and management costs.
-These fees are set by the Vault Admin and can be updated over time,
-subject to protocol-enforced restrictions to protect users from sudden changes.
-
-:::custom-notes[Deep Dive]
-For complete details about Vault fees, see [Fees →](./Fees).
-:::
-
-## Staking into a Vault
-
-When staking into a Vault, users deposit ETH or GNO and receive Vault shares representing their proportional ownership of the pool's assets. There are no minimum deposit requirements and no maximum limits except the Vault's capacity limit.
-
-Vaults use a shares-based accounting system where:
-- Shares are non-transferable (unless the Vault is an ERC-20 Vault)
-- Shares may not appear in portfolio tracking applications
-- Share value increases automatically as staking rewards accumulate
-- No token swaps or conversions occur during staking
-
-For immediate liquidity, users can mint osTokens (`osETH` or `osGNO`) using their Vault shares as collateral.
-
-### Evaluating Vault Performance
-
-StakeWise provides performance grades (Excellent, Good, Moderate, Bad) to help users evaluate Vault quality based on validator operational excellence. These grades reflect the average Vault performance over the last 7 days. [View detailed grade criteria →](/operator/vault-performance#-performance-grades).
-
-:::custom-warning[Important]
-Performance grades help users identify well-operated Vaults but should be considered alongside other factors like fees, capacity, and operator reputation.
-:::
-
-:::custom-notes[Technical Details]
-For operators seeking detailed information about performance calculations, scoring formulas, and optimization strategies, see [Vault Performance →](/operator/vault-performance).
-:::
-
-## Technical Architecture
-
-### Vault Deployment
-
-Each Vault in the StakeWise protocol is deployed as an upgradeable [ERC-1967 ↗](https://eips.ethereum.org/EIPS/eip-1967) proxy contract. The proxy is the contract users interact with. It holds all persistent state — including user balances — and stores Vault-specific configuration set during initialization, which defines its core operational characteristics.
-Vaults are created through factory contracts such as [VaultFactory ↗](https://etherscan.io/address/0x7a8cbbf690084e43de778173cfacf7313c9122dd#code) by:
-
-1. Deploying a proxy that reserves storage for all Vault data and sets its initial configuration during the initializer call.
-2. Pointing the proxy to a shared implementation contract that contains the Vault's logic and module integration.
-3. Registering the Vault in the [VaultsRegistry ↗](https://etherscan.io/address/0x3a0008a588772446f6e656133C2D5029CC4FC20E#code) — the canonical on-chain list of all valid Vaults and factories.
-
-:::custom-warning[Important]
-To mitigate economic attacks during the vulnerable initial phase of a Vault's lifetime, the factory requires a security deposit of 1 gwei at creation.
-:::
-
-:::custom-notes[Deep Dive]
-All Vault factory addresses can be found in [Networks →](../../contracts/networks/).
-:::
-
-### Modular Design
-
-The constructor parameters set during deployment link the Vault to essential StakeWise infrastructure
-and the Ethereum Beacon Chain. Each Vault is built from specialized modules that split responsibilities into distinct areas, including:
-
-**Validator lifecycle** — adding, approving, and exiting validators.
-
-**Deposit and withdrawal** — staking to and withdrawing from the Beacon Chain.
-
-**Fee enforcement** — calculating and applying protocol and operator fees.
-
-**MEV capture** — routing execution-layer rewards either to a Vault-specific escrow or to a Smoothing Pool.
-
-:::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.
-:::
-
-### State Tracking
-
-Vaults maintain an internal accounting ledger that tracks the value of all user stakes.
-This ledger is updated whenever user activity or protocol events affect stake values, such as deposits, withdrawals, reward distributions, or MEV payouts.
-Updates occur automatically when users interact with the Vault, and operators can trigger updates manually when necessary, for example, to refresh valuations before osETH minting.
-
-### Upgrade Flexibility
-
-Every Vault is an independent staking pool, and its smart contracts cannot be unilaterally changed or upgraded by the StakeWise DAO.
-Because the proxy pattern separates storage from logic, upgrades can be applied without affecting user balances or redeploying the contract.
-Only the implementation contract changes, while the proxy — holding all state — remains untouched.
-
-The DAO may release new Vault contract versions to improve efficiency or safety, but upgrading is always optional —
-Vaults can opt to keep their current version.
-All upgrades are subject to community governance approval, providing strong guarantees for user protection and protocol integrity.
-
-The Vault architecture is deployed in parallel on both the Ethereum and Gnosis networks through equivalent contract implementations,
-such as `EthVault` and `GnoVault`.
-
 

   1. `0x01` and `0x02` refer to withdrawal credential types that determine validator capabilities:
   `0x01` validators (Type 1) use the current 32 ETH limit with automatic sweeps of excess balance, while
diff --git a/docs/docs/vaults/intro.mdx b/docs/docs/vaults/intro.mdx
new file mode 100644
index 0000000..6e28ff3
--- /dev/null
+++ b/docs/docs/vaults/intro.mdx
@@ -0,0 +1,14 @@
+---
+title: Vaults
+sidebar_position: 0
+description: "Learn what Vaults are and what you can do with them"
+---
+
+Vaults are isolated staking pools that process ETH and GNO deposits for staking, distribute rewards, and handle withdrawals in a trustless and non-custodial manner.
+
+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.
+
+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.
+
+All deposits, reward distribution, and withdrawals are handled by smart contracts, making staking in Vaults fully non-custodial.
diff --git a/docs/docs/vaults/staking-into-a-vault.mdx b/docs/docs/vaults/staking-into-a-vault.mdx
new file mode 100644
index 0000000..934c94e
--- /dev/null
+++ b/docs/docs/vaults/staking-into-a-vault.mdx
@@ -0,0 +1,29 @@
+---
+title: Staking into a Vault
+sidebar_position: 3
+description: "Learn how to stake into a Vault and evaluate Vault performance"
+---
+
+# Staking into a Vault
+
+When staking into a Vault, users deposit ETH or GNO and receive Vault shares representing their proportional ownership of the pool's assets. There are no minimum deposit requirements and no maximum limits except the Vault's capacity limit.
+
+Vaults use a shares-based accounting system where:
+- Shares are non-transferable (unless the Vault is an ERC-20 Vault)
+- Shares may not appear in portfolio tracking applications
+- Share value increases automatically as staking rewards accumulate
+- No token swaps or conversions occur during staking
+
+For immediate liquidity, users can mint osTokens (`osETH` or `osGNO`) using their Vault shares as collateral.
+
+## Evaluating Vault Performance
+
+StakeWise provides performance grades (Excellent, Good, Moderate, Bad) to help users evaluate Vault quality based on validator operational excellence. These grades reflect the average Vault performance over the last 7 days. [View detailed grade criteria →](/operator/vault-performance#-performance-grades).
+
+:::custom-warning[Important]
+Performance grades help users identify well-operated Vaults but should be considered alongside other factors like fees, capacity, and operator reputation.
+:::
+
+:::custom-notes[Technical Details]
+For operators seeking detailed information about performance calculations, scoring formulas, and optimization strategies, see [Vault Performance →](/operator/vault-performance).
+:::
diff --git a/docs/docs/vaults/technical-architecture.mdx b/docs/docs/vaults/technical-architecture.mdx
new file mode 100644
index 0000000..462bacc
--- /dev/null
+++ b/docs/docs/vaults/technical-architecture.mdx
@@ -0,0 +1,60 @@
+---
+title: Technical Architecture
+sidebar_position: 4
+description: "Learn about Vault deployment, modular design, and upgrade flexibility"
+---
+
+# Technical Architecture
+
+## Vault Deployment
+
+Each Vault in the StakeWise protocol is deployed as an upgradeable [ERC-1967 ↗](https://eips.ethereum.org/EIPS/eip-1967) proxy contract. The proxy is the contract users interact with. It holds all persistent state — including user balances — and stores Vault-specific configuration set during initialization, which defines its core operational characteristics.
+Vaults are created through factory contracts such as [VaultFactory ↗](https://etherscan.io/address/0x7a8cbbf690084e43de778173cfacf7313c9122dd#code) by:
+
+1. Deploying a proxy that reserves storage for all Vault data and sets its initial configuration during the initializer call.
+2. Pointing the proxy to a shared implementation contract that contains the Vault's logic and module integration.
+3. Registering the Vault in the [VaultsRegistry ↗](https://etherscan.io/address/0x3a0008a588772446f6e656133C2D5029CC4FC20E#code) — the canonical on-chain list of all valid Vaults and factories.
+
+:::custom-warning[Important]
+To mitigate economic attacks during the vulnerable initial phase of a Vault's lifetime, the factory requires a security deposit of 1 gwei at creation.
+:::
+
+:::custom-notes[Deep Dive]
+All Vault factory addresses can be found in [Networks →](../../contracts/networks/).
+:::
+
+## Modular Design
+
+The constructor parameters set during deployment link the Vault to essential StakeWise infrastructure
+and the Ethereum Beacon Chain. Each Vault is built from specialized modules that split responsibilities into distinct areas, including:
+
+**Validator lifecycle** — adding, approving, and exiting validators.
+
+**Deposit and withdrawal** — staking to and withdrawing from the Beacon Chain.
+
+**Fee enforcement** — calculating and applying protocol and operator fees.
+
+**MEV capture** — routing execution-layer rewards either to a Vault-specific escrow or to a Smoothing Pool.
+
+:::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.
+:::
+
+## State Tracking
+
+Vaults maintain an internal accounting ledger that tracks the value of all user stakes.
+This ledger is updated whenever user activity or protocol events affect stake values, such as deposits, withdrawals, reward distributions, or MEV payouts.
+Updates occur automatically when users interact with the Vault, and operators can trigger updates manually when necessary, for example, to refresh valuations before osETH minting.
+
+## Upgrade Flexibility
+
+Every Vault is an independent staking pool, and its smart contracts cannot be unilaterally changed or upgraded by the StakeWise DAO.
+Because the proxy pattern separates storage from logic, upgrades can be applied without affecting user balances or redeploying the contract.
+Only the implementation contract changes, while the proxy — holding all state — remains untouched.
+
+The DAO may release new Vault contract versions to improve efficiency or safety, but upgrading is always optional —
+Vaults can opt to keep their current version.
+All upgrades are subject to community governance approval, providing strong guarantees for user protection and protocol integrity.
+
+The Vault architecture is deployed in parallel on both the Ethereum and Gnosis networks through equivalent contract implementations,
+such as `EthVault` and `GnoVault`.
diff --git a/docs/operator/Installation.mdx b/docs/operator/Installation.mdx
index 5552758..b6f6d7e 100644
--- a/docs/operator/Installation.mdx
+++ b/docs/operator/Installation.mdx
@@ -30,7 +30,7 @@ This guide is for Vault version 5 (Ethereum) or version 3 (Gnosis). Check the [P
     ```bash
     ./operator COMMAND --flagA=123 --flagB=xyz
     ```
-    :::custom-notes[Optional]
+    :::custom-notes[Note]
       The use of flags is optional.
     :::
 
@@ -90,7 +90,7 @@ This guide is for Vault version 5 (Ethereum) or version 3 (Gnosis). Check the [P
     --flagB=xyz
     ```
 
-    :::custom-notes[Optional]
+    :::custom-notes[Note]
       The use of flags is optional.
     :::
 
@@ -123,7 +123,7 @@ This guide is for Vault version 5 (Ethereum) or version 3 (Gnosis). Check the [P
     ```bash
     PYTHONPATH=. poetry run python src/main.py COMMAND --flagA=123 --flagB=xyz
     ```
-    :::custom-notes[Optional]
+    :::custom-notes[Note]
         The use of flags is optional.
     :::
   
diff --git a/docs/operator/intro.mdx b/docs/operator/intro.mdx
index a838578..abdacf6 100644
--- a/docs/operator/intro.mdx
+++ b/docs/operator/intro.mdx
@@ -10,9 +10,9 @@ import useBaseUrl from '@docusaurus/useBaseUrl';
 
 # Overview
 
-**StakeWise** is a decentralized liquid staking protocol that allows anyone to participate in Ethereum staking without the traditional barriers of technical complexity or capital requirements. The protocol enables users to stake their ETH while maintaining liquidity through [osToken →](/docs/protocol-concepts/osToken), StakeWise's liquid staking token.
+**StakeWise** is a decentralized liquid staking protocol that allows anyone to participate in Ethereum staking without the traditional barriers of technical complexity or capital requirements. The protocol enables users to stake their ETH while maintaining liquidity through [osToken →](/docs/ostoken/intro), StakeWise's liquid staking token.
 
-At the core of StakeWise are individual staking pools called [Vaults →](/docs/protocol-concepts/Vaults). Anyone – from solo stakers to professional operators – can create and operate their own Vault, offering flexible staking solutions that serve diverse needs: solo stakers can access liquid staking for their own ETH, while individuals and organizations can stake on their terms and offer liquid staking services to others.
+At the core of StakeWise are individual staking pools called [Vaults →](/docs/vaults/intro). Anyone – from solo stakers to professional operators – can create and operate their own Vault, offering flexible staking solutions that serve diverse needs: solo stakers can access liquid staking for their own ETH, while individuals and organizations can stake on their terms and offer liquid staking services to others.
 
 **Deploying a Vault requires running the StakeWise [Operator Service ↗](https://github.com/stakewise/v3-operator)** – specialized software that manages validator operations and ensures your Vault functions properly. Each Vault must have at least one node operator running this service to handle validator registrations, exits, and other critical operations that keep the Vault operational.
 
@@ -82,7 +82,7 @@ The Operator Service periodically checks whether the Vault has accumulated enoug
 By default, the Operator Service registers new `0x02` validators, prioritizing funding existing compound validators when possible; otherwise, it registers new validators up to the maximum balance.
 
 :::custom-notes[Deep Dive]
-For detailed information about the validator registration process, see [Validator Registration →](/docs/protocol-concepts/Vaults#validator-registration)
+For detailed information about the validator registration process, see [Validator Registration →](/docs/vaults/how-vaults-work#validator-registration)
 :::
 
 ### Validator Consolidation
diff --git a/docs/operator/smoothing-pool-relays.mdx b/docs/operator/smoothing-pool-relays.mdx
index 1e4328d..0471121 100644
--- a/docs/operator/smoothing-pool-relays.mdx
+++ b/docs/operator/smoothing-pool-relays.mdx
@@ -54,11 +54,6 @@ https://0xb0b07cd0abef743db4260b0ed50619cf6ad4d82064cb4fbec9d3ec530f7c5e6793d9f2
 https://0xa15b52576bcbf1072f4a011c0f99f9fb6c66f3e1ff321f11f461d15e31b1cb359caa092c71bbded0bae5b5ea401aab7e@aestus.live
 ```
 
-### Eden Network
-```
-https://0xb3ee7afcf27f1f1259ac1787876318c6584ee353097a50ed84f51a1f21a323b3736f271a895c7ce918c038e4265918be@relay.edennetwork.io
-```
-
 ### Titan Relay
 ```
 https://0x8c4ed5e24fe5c6ae21018437bde147693f68cda427cd1122cf20819c30eda7ed74f72dece09bb313f2a1855595ab677d@titanrelay.xyz
@@ -76,5 +71,5 @@ Learn more about MEV-Boost setup and configuration at the [official repository 
 :::
 
 :::custom-notes[Further Reading]
-Learn more about how [Smoothing Pool works →](/docs/protocol-concepts/Vaults#smoothing-pool--pooled-rewards).
+Learn more about how [Smoothing Pool works →](/docs/vaults/customization#smoothing-pool--pooled-rewards).
 :::
diff --git a/docs/operator/v4-upgrade-guide.mdx b/docs/operator/v4-upgrade-guide.mdx
index 61d0c75..fd84fba 100644
--- a/docs/operator/v4-upgrade-guide.mdx
+++ b/docs/operator/v4-upgrade-guide.mdx
@@ -9,7 +9,7 @@ import Admonition from '@theme/Admonition';
 
 # V4 Upgrade Guide
 
-This guide covers the key changes and upgrade steps for StakeWise Operator V4, including Pectra upgrade support.
+This guide covers the key changes and upgrade steps for StakeWise Operator V4, including support for the Pectra upgrade (activated on 07-May-2025 at epoch 364032).
 
 :::custom-info[Prerequisites]
 Ensure your Vault is updated to **version 5** for Ethereum network or **version 3** for Gnosis network for full Pectra compatibility. See [Prerequisites →](./Prerequisites#deployed-vault) for details on checking and upgrading your Vault version.
@@ -19,8 +19,8 @@ Additionally, ensure your Operator Service wallet has the [Validators Manager 
 
 ## Validator Changes
 ### Registration
-After the Pectra upgrade:
-- **Validator balances are no longer limited** to 32 ETH or 1 GNO
+After the Pectra upgrade ([EIP-7251 ↗](https://eips.ethereum.org/EIPS/eip-7251)):
+- **Validator balances are no longer limited** to 32 ETH or 1 GNO (now up to 2048 ETH or 64 GNO)
 - **`0x02` validators are registered by default**
 - To register `0x01` validators, add the flag `--validators-type=0x01`
 
@@ -47,7 +47,7 @@ The Pectra upgrade introduces significantly improved withdrawal mechanisms:
 - Significantly faster than full validator exits, improving withdrawal queue processing times
 
 #### More Efficient Full Validator Exits
-- **Full validator exits** are now processed via **execution request calls** instead of the traditional oracle-based method
+- **Full validator exits** are now processed via **execution layer triggerable exits** ([EIP-7002 ↗](https://eips.ethereum.org/EIPS/eip-7002)) instead of the traditional oracle-based method
 - **Automatic fallback**: If the Operator Service does not initiate partial or full withdrawals, the Oracle network will automatically execute a full withdrawal after 24 hours using the exit signatures they have received during validator registration
 
 :::custom-info[Withdrawal Logic & Prioritization]
diff --git a/docs/operator/validator-keys.mdx b/docs/operator/validator-keys.mdx
index c5a8c76..fecc4b0 100644
--- a/docs/operator/validator-keys.mdx
+++ b/docs/operator/validator-keys.mdx
@@ -136,9 +136,9 @@ You must use the **"Block reward recipient"** address from the **"Details"** sec
 
 Validator keystores don't need to be stored locally. You can instead use:
 
-- **[Remote Signer →](./alternative-key-management/remote-signer)** - Sign deposit/exit messages via a remote signer
-- **[HashiCorp Vault →](./alternative-key-management/hashicorp-vault)** - Load keys from a remote Vault instance
-- **[API Mode →](./alternative-key-management/api-mode)** - Run Operator as API service with external key management
+- **[Remote Signer →](./alternative-key-management/remote-signer)** — Sign deposit/exit messages via a remote signer
+- **[HashiCorp Vault →](./alternative-key-management/hashicorp-vault)** — Load keys from a remote Vault instance
+- **[API Mode →](./alternative-key-management/api-mode)** — Run Operator as API service with external key management
 
 ## Next Steps
 
diff --git a/docusaurus.config.ts b/docusaurus.config.ts
index 40199ae..c7799c3 100644
--- a/docusaurus.config.ts
+++ b/docusaurus.config.ts
@@ -99,7 +99,7 @@ const config: Config = {
         },
         {
           label: 'Guides',
-          to: 'docs/guides/staking',
+          to: 'docs/guides/intro',
           activeBaseRegex: `/docs/guides/`,
           sidebarId: 'guidesSidebar',
         },
diff --git a/sidebars.ts b/sidebars.ts
index b486adc..55ce7de 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -7,19 +7,106 @@ const sidebars: SidebarsConfig = {
     'docs/intro',
     {
       type: 'category',
-      label: 'Protocol Concepts',
+      label: 'Vaults',
+      link: {
+        type: 'doc',
+        id: 'docs/vaults/intro',
+      },
       items: [
-        {
-          type: 'autogenerated',
-          dirName: 'docs/protocol-concepts',
-        },
+        'docs/vaults/how-vaults-work',
+        'docs/vaults/customization',
+        'docs/vaults/staking-into-a-vault',
+        'docs/vaults/technical-architecture',
       ],
     },
+    {
+      type: 'category',
+      label: 'osToken',
+      link: {
+        type: 'doc',
+        id: 'docs/ostoken/intro',
+      },
+      items: [
+        'docs/ostoken/how-ostoken-works',
+      ],
+    },
+    {
+      type: 'category',
+      label: 'Oracles',
+      link: {
+        type: 'doc',
+        id: 'docs/oracles/intro',
+      },
+      items: [
+        'docs/oracles/oracle-duties',
+      ],
+    },
+    'docs/fees/intro',
+    {
+      type: 'category',
+      label: 'Governance',
+      link: {
+        type: 'doc',
+        id: 'docs/governance/intro',
+      },
+      items: [
+        'docs/governance/stakewise-dao',
+        'docs/governance/dao-treasury',
+      ],
+    },
+
   ],
   guidesSidebar: [
+    'docs/guides/intro',
     {
-      type: 'autogenerated',
-      dirName: 'docs/guides'
+      type: 'category',
+      label: 'Staking',
+      link: {
+        type: 'doc',
+        id: 'docs/guides/staking/intro',
+      },
+      items: [
+        'docs/guides/staking/one-click-staking',
+        'docs/guides/staking/staking-with-vaults',
+        'docs/guides/staking/solo-staking',
+        'docs/guides/staking/unstaking',
+      ],
+    },
+    {
+      type: 'category',
+      label: 'Running a Vault',
+      link: {
+        type: 'doc',
+        id: 'docs/guides/running-a-vault/intro',
+      },
+      items: [
+        'docs/guides/running-a-vault/how-to-create-a-vault',
+        'docs/guides/running-a-vault/vault-administration',
+        'docs/guides/running-a-vault/getting-your-vault-running',
+      ],
+    },
+    'docs/guides/fee-splitter',
+    {
+      type: 'category',
+      label: 'DeFi',
+      link: {
+        type: 'doc',
+        id: 'docs/guides/defi/intro',
+      },
+      items: [
+        'docs/guides/defi/boost-feature',
+        'docs/guides/defi/swise-eth-liquidity',
+      ],
+    },
+    {
+      type: 'category',
+      label: 'StakeWise V2',
+      items: [
+        {
+          type: 'autogenerated',
+          dirName: 'docs/guides/stakewise-v2',
+        },
+      ],
     },
   ],
   operatorSidebar: [
diff --git a/src/components/DocsSections/Blocks/Blocks.tsx b/src/components/DocsSections/Blocks/Blocks.tsx
index cbfea2f..379bdf8 100644
--- a/src/components/DocsSections/Blocks/Blocks.tsx
+++ b/src/components/DocsSections/Blocks/Blocks.tsx
@@ -14,7 +14,7 @@ const blocks: BlockProps[] = [
     title: 'Guides',
     text: 'Step-by-step tutorials for staking, running a Vault, and DeFi strategies',
     Svg: require("@site/static/icon/file.svg").default,
-    href: '/docs/guides/staking',
+    href: '/docs/guides/intro',
   },
   {
     title: 'Operator',
diff --git a/static/img/tokenomics.png b/static/img/tokenomics.png
new file mode 100644
index 0000000..89e1c34
Binary files /dev/null and b/static/img/tokenomics.png differ