From a81bf8eef134f278e090dc10012a22cdcf0becbb Mon Sep 17 00:00:00 2001 From: taylorferran Date: Mon, 12 Jan 2026 17:21:25 +0000 Subject: [PATCH 1/3] ssv staking first commit --- SSV-Staking-Doc-Updates-Map.md | 393 ++++++++++++++++++ SSV-Staking-Doc-Updates-Tasks.csv | 118 ++++++ SSV-Staking-context.doc | 0 SSV_Staking-design-info.doc | 318 ++++++++++++++ docs/learn/glossary.md | 80 +++- docs/learn/introduction/ssv-token.md | 18 +- .../protocol-overview/tokenomics/README.md | 51 ++- docs/stakers/ssv-staking/README.md | 133 ++++++ docs/stakers/ssv-staking/claim-rewards.md | 107 +++++ docs/stakers/ssv-staking/faq.md | 323 ++++++++++++++ docs/stakers/ssv-staking/stake-ssv.md | 114 +++++ docs/stakers/ssv-staking/unstake-ssv.md | 170 ++++++++ 12 files changed, 1813 insertions(+), 12 deletions(-) create mode 100644 SSV-Staking-Doc-Updates-Map.md create mode 100644 SSV-Staking-Doc-Updates-Tasks.csv create mode 100644 SSV-Staking-context.doc create mode 100644 SSV_Staking-design-info.doc create mode 100644 docs/stakers/ssv-staking/README.md create mode 100644 docs/stakers/ssv-staking/claim-rewards.md create mode 100644 docs/stakers/ssv-staking/faq.md create mode 100644 docs/stakers/ssv-staking/stake-ssv.md create mode 100644 docs/stakers/ssv-staking/unstake-ssv.md diff --git a/SSV-Staking-Doc-Updates-Map.md b/SSV-Staking-Doc-Updates-Map.md new file mode 100644 index 0000000..c7ad765 --- /dev/null +++ b/SSV-Staking-Doc-Updates-Map.md @@ -0,0 +1,393 @@ +# SSV Staking Documentation Updates Map + +This document maps all required documentation updates for SSV Staking (ETH clusters, cSSV staking, EB oracle system, etc.) to the specific documentation pages that need to be updated. + +--- + +## 1. ETH Clusters & Migration + +### Update all cluster lifecycle docs to ETH-first (create, fund, run) + +**Pages to Update:** +- [Cluster Management Overview](https://docs.ssv.network/stakers/cluster-management) - `docs/stakers/cluster-management/README.md` +- [Validator Onboarding](https://docs.ssv.network/stakers/validators/validator-onboarding) - `docs/stakers/validators/validator-onboarding.md` +- [Creating a New Validator](https://docs.ssv.network/stakers/validator-management/creating-a-new-validator) - `docs/stakers/validator-management/creating-a-new-validator.md` +- [Distributing a Validator](https://docs.ssv.network/stakers/validator-management/distributing-a-validator) - `docs/stakers/validator-management/distributing-a-validator.md` +- [Cluster Balance](https://docs.ssv.network/stakers/clusters/cluster-balance) - `docs/stakers/clusters/cluster-balance.md` +- [Depositing SSV](https://docs.ssv.network/stakers/cluster-management/depositing-ssv) - `docs/stakers/cluster-management/depositing-ssv.md` +- [Payments](https://docs.ssv.network/learn/protocol-overview/tokenomics/payments) - `docs/learn/protocol-overview/tokenomics/payments.md` + +### Add explicit one-way migration warning (SSV → ETH cannot revert) + +**Pages to Update:** +- [Cluster Management Overview](https://docs.ssv.network/stakers/cluster-management) - `docs/stakers/cluster-management/README.md` +- [Cluster Balance](https://docs.ssv.network/stakers/clusters/cluster-balance) - `docs/stakers/clusters/cluster-balance.md` +- **NEW SECTION NEEDED**: Migration Guide (create new file in `docs/stakers/cluster-management/`) + +### Document migrateClusterToETH() flow step-by-step + +**Pages to Update:** +- **NEW PAGE**: Migration Guide - `docs/stakers/cluster-management/migrating-to-eth-clusters.md` +- [SSVNetwork Smart Contract](https://docs.ssv.network/developers/smart-contracts/ssvnetwork) - `docs/developers/smart-contracts/ssvnetwork.md` +- [Cluster Module SDK](https://docs.ssv.network/developers/SSV-SDK/module-reference/cluster-module) - `docs/developers/SSV-SDK/module-reference/cluster-module.md` + +### Add ETH funding + runway examples (remove SSV-centric assumptions) + +**Pages to Update:** +- [Validator Onboarding](https://docs.ssv.network/stakers/validators/validator-onboarding) - `docs/stakers/validators/validator-onboarding.md` +- [Cluster Balance](https://docs.ssv.network/stakers/clusters/cluster-balance) - `docs/stakers/clusters/cluster-balance.md` +- [Staking Services Integration](https://docs.ssv.network/developers/integration-guides/staking-services) - `docs/developers/integration-guides/staking-services.md` +- [Staking Pools - Initialization](https://docs.ssv.network/developers/integration-guides/staking-pools/initialization-stage) - `docs/developers/integration-guides/staking-pools/initialization-stage.md` + +### Clearly mark SSV clusters as legacy and transitional + +**Pages to Update:** +- [Cluster Management Overview](https://docs.ssv.network/stakers/cluster-management) - `docs/stakers/cluster-management/README.md` +- [Clusters Overview](https://docs.ssv.network/stakers/clusters) - `docs/stakers/clusters/README.md` +- [Validator Onboarding](https://docs.ssv.network/stakers/validators/validator-onboarding) - `docs/stakers/validators/validator-onboarding.md` +- [Payments](https://docs.ssv.network/learn/protocol-overview/tokenomics/payments) - `docs/learn/protocol-overview/tokenomics/payments.md` + +--- + +## 2. Operator ETH Fees & Rules + +### Update operator onboarding docs for ETH-only operators + +**Pages to Update:** +- [Operator Onboarding](https://docs.ssv.network/operators/operator-onboarding) - `docs/operators/operator-onboarding/README.md` +- [Operator Registration](https://docs.ssv.network/operators/operator-management/registration) - `docs/operators/operator-management/registration.md` +- [Operators Overview](https://docs.ssv.network/operators) - `docs/operators/README.md` + +### Document ETH fee defaults and DAO-defined fallback behavior + +**Pages to Update:** +- [Operator Onboarding](https://docs.ssv.network/operators/operator-onboarding) - `docs/operators/operator-onboarding/README.md` +- [Operator Registration](https://docs.ssv.network/operators/operator-management/registration) - `docs/operators/operator-management/registration.md` +- [Fees](https://docs.ssv.network/learn/protocol-overview/tokenomics/fees) - `docs/learn/protocol-overview/tokenomics/fees.md` +- [Governance](https://docs.ssv.network/learn/introduction/governance) - `docs/learn/introduction/governance.md` + +### Explain migration-period fee override (2× default, one-time) + +**Pages to Update:** +- [Update Fee](https://docs.ssv.network/operators/operator-onboarding/update-fee) - `docs/operators/operator-onboarding/update-fee.md` +- [Updating Operator Fees](https://docs.ssv.network/operators/operator-management/updating-operator-fees) - `docs/operators/operator-management/updating-operator-fees.md` +- **NEW SECTION**: Migration-specific fee rules in operator docs + +### Clarify that ETH and SSV earnings are separate balances + +**Pages to Update:** +- [Withdrawing Earnings](https://docs.ssv.network/operators/operator-management/withdrawing-earnings) - `docs/operators/operator-management/withdrawing-earnings.md` +- [Operator Onboarding](https://docs.ssv.network/operators/operator-onboarding) - `docs/operators/operator-onboarding/README.md` +- [Fees](https://docs.ssv.network/learn/protocol-overview/tokenomics/fees) - `docs/learn/protocol-overview/tokenomics/fees.md` + +### Explicitly state that ETH-only operators cannot receive SSV fees + +**Pages to Update:** +- [Operator Onboarding](https://docs.ssv.network/operators/operator-onboarding) - `docs/operators/operator-onboarding/README.md` +- [Operator Registration](https://docs.ssv.network/operators/operator-management/registration) - `docs/operators/operator-management/registration.md` +- [Fees](https://docs.ssv.network/learn/protocol-overview/tokenomics/fees) - `docs/learn/protocol-overview/tokenomics/fees.md` + +--- + +## 3. Effective Balance (vUnits) Accounting + +### Add a new conceptual doc explaining vUnits and EB weighting + +**Pages to Update:** +- **NEW PAGE**: vUnits and Effective Balance - `docs/learn/protocol-overview/tokenomics/effective-balance.md` +- [Tokenomics Overview](https://docs.ssv.network/learn/protocol-overview/tokenomics) - `docs/learn/protocol-overview/tokenomics/README.md` +- [Glossary](https://docs.ssv.network/learn/glossary) - `docs/learn/glossary.md` + +### Document EB vs validatorCount differences (ETH vs SSV clusters) + +**Pages to Update:** +- **NEW PAGE**: vUnits and Effective Balance - `docs/learn/protocol-overview/tokenomics/effective-balance.md` +- [Cluster Balance](https://docs.ssv.network/stakers/clusters/cluster-balance) - `docs/stakers/clusters/cluster-balance.md` +- [Payments](https://docs.ssv.network/learn/protocol-overview/tokenomics/payments) - `docs/learn/protocol-overview/tokenomics/payments.md` + +### Explain fallback behavior when EB data is missing (32 ETH default) + +**Pages to Update:** +- **NEW PAGE**: vUnits and Effective Balance - `docs/learn/protocol-overview/tokenomics/effective-balance.md` +- [Cluster Balance](https://docs.ssv.network/stakers/clusters/cluster-balance) - `docs/stakers/clusters/cluster-balance.md` + +### Add examples showing fee scaling with EB (32 vs 64 vs 2048 ETH) + +**Pages to Update:** +- **NEW PAGE**: vUnits and Effective Balance - `docs/learn/protocol-overview/tokenomics/effective-balance.md` +- [Fees](https://docs.ssv.network/learn/protocol-overview/tokenomics/fees) - `docs/learn/protocol-overview/tokenomics/fees.md` +- [Validator Onboarding](https://docs.ssv.network/stakers/validators/validator-onboarding) - `docs/stakers/validators/validator-onboarding.md` + +### Update any fee math references that assume 1 validator = 32 ETH + +**Pages to Update:** +- [Validator Onboarding](https://docs.ssv.network/stakers/validators/validator-onboarding) - `docs/stakers/validators/validator-onboarding.md` +- [Cluster Balance](https://docs.ssv.network/stakers/clusters/cluster-balance) - `docs/stakers/clusters/cluster-balance.md` +- [Liquidations](https://docs.ssv.network/learn/protocol-overview/tokenomics/liquidations) - `docs/learn/protocol-overview/tokenomics/liquidations.md` +- [Fees](https://docs.ssv.network/learn/protocol-overview/tokenomics/fees) - `docs/learn/protocol-overview/tokenomics/fees.md` +- [Staking Services Integration](https://docs.ssv.network/developers/integration-guides/staking-services) - `docs/developers/integration-guides/staking-services.md` + +--- + +## 4. EB Oracle System (v1) + +### Add EB Oracle architecture overview (why oracles exist at all) + +**Pages to Update:** +- **NEW PAGE**: EB Oracle System - `docs/learn/protocol-overview/eb-oracle-system.md` +- [Protocol Overview](https://docs.ssv.network/learn/protocol-overview) - `docs/learn/protocol-overview/README.md` +- [Tech Overview](https://docs.ssv.network/learn/introduction/tech-overview) - `docs/learn/introduction/tech-overview.md` + +### Document commitRoot → updateClusterBalance lifecycle + +**Pages to Update:** +- **NEW PAGE**: EB Oracle System - `docs/learn/protocol-overview/eb-oracle-system.md` +- [SSVNetwork Smart Contract](https://docs.ssv.network/developers/smart-contracts/ssvnetwork) - `docs/developers/smart-contracts/ssvnetwork.md` +- [Cluster Balance](https://docs.ssv.network/stakers/clusters/cluster-balance) - `docs/stakers/clusters/cluster-balance.md` + +### Explain Merkle root + proof verification in simple terms + +**Pages to Update:** +- **NEW PAGE**: EB Oracle System - `docs/learn/protocol-overview/eb-oracle-system.md` +- [Tech Overview](https://docs.ssv.network/learn/introduction/tech-overview) - `docs/learn/introduction/tech-overview.md` + +### Clearly state v1 constraints: 4 fixed oracles, 75% quorum + +**Pages to Update:** +- **NEW PAGE**: EB Oracle System - `docs/learn/protocol-overview/eb-oracle-system.md` +- [Governance](https://docs.ssv.network/learn/introduction/governance) - `docs/learn/introduction/governance.md` + +### Document oracle update frequency and finality assumptions + +**Pages to Update:** +- **NEW PAGE**: EB Oracle System - `docs/learn/protocol-overview/eb-oracle-system.md` +- [Tech Overview](https://docs.ssv.network/learn/introduction/tech-overview) - `docs/learn/introduction/tech-overview.md` + +--- + +## 5. SSV Staking (cSSV + ETH Rewards) + +### Add full staking user journey (stake → earn → claim → unstake) + +**Pages to Update:** +- **NEW PAGE**: SSV Staking Guide - `docs/stakers/ssv-staking/README.md` +- **NEW PAGE**: Stake SSV - `docs/stakers/ssv-staking/stake-ssv.md` +- **NEW PAGE**: Claim Rewards - `docs/stakers/ssv-staking/claim-rewards.md` +- **NEW PAGE**: Unstake SSV - `docs/stakers/ssv-staking/unstake-ssv.md` +- [SSV Token](https://docs.ssv.network/learn/introduction/ssv-token) - `docs/learn/introduction/ssv-token.md` + +### Explain cSSV non-rebasing, index-based reward model + +**Pages to Update:** +- **NEW PAGE**: SSV Staking Guide - `docs/stakers/ssv-staking/README.md` +- [SSV Token](https://docs.ssv.network/learn/introduction/ssv-token) - `docs/learn/introduction/ssv-token.md` +- [Tokenomics Overview](https://docs.ssv.network/learn/protocol-overview/tokenomics) - `docs/learn/protocol-overview/tokenomics/README.md` +- [Glossary](https://docs.ssv.network/learn/glossary) - `docs/learn/glossary.md` + +### Document ETH reward flow from clusters → staking contract + +**Pages to Update:** +- **NEW PAGE**: SSV Staking Guide - `docs/stakers/ssv-staking/README.md` +- [Validator Rewards](https://docs.ssv.network/stakers/validators/validator-rewards) - `docs/stakers/validators/validator-rewards.md` +- [Tokenomics Overview](https://docs.ssv.network/learn/protocol-overview/tokenomics) - `docs/learn/protocol-overview/tokenomics/README.md` + +### Add unstaking cooldown explanation and its implications + +**Pages to Update:** +- **NEW PAGE**: Unstake SSV - `docs/stakers/ssv-staking/unstake-ssv.md` +- **NEW PAGE**: SSV Staking Guide - `docs/stakers/ssv-staking/README.md` +- [Glossary](https://docs.ssv.network/learn/glossary) - `docs/learn/glossary.md` + +### Clarify that rewards stop accruing during cooldown + +**Pages to Update:** +- **NEW PAGE**: Unstake SSV - `docs/stakers/ssv-staking/unstake-ssv.md` +- **NEW PAGE**: SSV Staking Guide - `docs/stakers/ssv-staking/README.md` + +--- + +## 6. Oracle Delegation (Auto-split v1) + +### Document automatic stake-weight splitting across all oracles + +**Pages to Update:** +- **NEW PAGE**: Oracle Delegation - `docs/learn/protocol-overview/oracle-delegation.md` +- **NEW PAGE**: SSV Staking Guide - `docs/stakers/ssv-staking/README.md` +- [Governance](https://docs.ssv.network/learn/introduction/governance) - `docs/learn/introduction/governance.md` + +### Explicitly state that users do not choose oracles in v1 + +**Pages to Update:** +- **NEW PAGE**: Oracle Delegation - `docs/learn/protocol-overview/oracle-delegation.md` +- **NEW PAGE**: SSV Staking Guide - `docs/stakers/ssv-staking/README.md` + +### Explain voting weight behavior during unstake cooldown + +**Pages to Update:** +- **NEW PAGE**: Oracle Delegation - `docs/learn/protocol-overview/oracle-delegation.md` +- **NEW PAGE**: Unstake SSV - `docs/stakers/ssv-staking/unstake-ssv.md` +- [Governance](https://docs.ssv.network/learn/introduction/governance) - `docs/learn/introduction/governance.md` + +### Set expectations for v2 (manual delegation, variable oracles) + +**Pages to Update:** +- **NEW PAGE**: Oracle Delegation - `docs/learn/protocol-overview/oracle-delegation.md` +- **NEW PAGE**: EB Oracle System - `docs/learn/protocol-overview/eb-oracle-system.md` + +--- + +## 7. Liquidation Behavior + +### Document ETH cluster liquidation (EB-weighted logic) + +**Pages to Update:** +- [Liquidations](https://docs.ssv.network/learn/protocol-overview/tokenomics/liquidations) - `docs/learn/protocol-overview/tokenomics/liquidations.md` +- [Liquidator Bot](https://docs.ssv.network/operators/liquidator-bot) - `docs/operators/liquidator-bot/README.md` +- [Cluster Balance](https://docs.ssv.network/stakers/clusters/cluster-balance) - `docs/stakers/clusters/cluster-balance.md` + +### Document legacy SSV cluster liquidation separately + +**Pages to Update:** +- [Liquidations](https://docs.ssv.network/learn/protocol-overview/tokenomics/liquidations) - `docs/learn/protocol-overview/tokenomics/liquidations.md` +- [Liquidator Bot](https://docs.ssv.network/operators/liquidator-bot) - `docs/operators/liquidator-bot/README.md` + +### Add warnings about calling the wrong liquidation path + +**Pages to Update:** +- [Liquidations](https://docs.ssv.network/learn/protocol-overview/tokenomics/liquidations) - `docs/learn/protocol-overview/tokenomics/liquidations.md` +- [Liquidator Bot](https://docs.ssv.network/operators/liquidator-bot) - `docs/operators/liquidator-bot/README.md` +- [SSVNetwork Smart Contract](https://docs.ssv.network/developers/smart-contracts/ssvnetwork) - `docs/developers/smart-contracts/ssvnetwork.md` + +### Update any liquidation thresholds/examples to be EB-aware + +**Pages to Update:** +- [Liquidations](https://docs.ssv.network/learn/protocol-overview/tokenomics/liquidations) - `docs/learn/protocol-overview/tokenomics/liquidations.md` +- [Cluster Balance](https://docs.ssv.network/stakers/clusters/cluster-balance) - `docs/stakers/clusters/cluster-balance.md` +- [Reactivation](https://docs.ssv.network/stakers/clusters/reactivation) - `docs/stakers/clusters/reactivation.md` +- [Re-activating a Cluster](https://docs.ssv.network/stakers/cluster-management/re-activating-a-cluster) - `docs/stakers/cluster-management/re-activating-a-cluster.md` + +--- + +## 8. Incentivized Mainnet (IM) Alignment + +### Update IM docs to state ETH clusters only are eligible + +**Pages to Update:** +- **NEW PAGE**: Incentivized Mainnet - `docs/learn/protocol-overview/incentivized-mainnet.md` +- [Network Overview](https://docs.ssv.network/learn/introduction/network-overview) - `docs/learn/introduction/network-overview.md` +- [Operators Overview](https://docs.ssv.network/operators) - `docs/operators/README.md` + +### Remove all references to off-chain EB fee deductions + +**Pages to Update:** +- [Fees](https://docs.ssv.network/learn/protocol-overview/tokenomics/fees) - `docs/learn/protocol-overview/tokenomics/fees.md` +- [Operator Onboarding](https://docs.ssv.network/operators/operator-onboarding) - `docs/operators/operator-onboarding/README.md` +- [Payments](https://docs.ssv.network/learn/protocol-overview/tokenomics/payments) - `docs/learn/protocol-overview/tokenomics/payments.md` + +### Document IM as a migration incentive, not a permanent system + +**Pages to Update:** +- **NEW PAGE**: Incentivized Mainnet - `docs/learn/protocol-overview/incentivized-mainnet.md` +- [Governance](https://docs.ssv.network/learn/introduction/governance) - `docs/learn/introduction/governance.md` + +### Add guidance for operators losing IM rewards on SSV clusters + +**Pages to Update:** +- **NEW PAGE**: Incentivized Mainnet - `docs/learn/protocol-overview/incentivized-mainnet.md` +- [Operators Overview](https://docs.ssv.network/operators) - `docs/operators/README.md` +- [Operator Onboarding](https://docs.ssv.network/operators/operator-onboarding) - `docs/operators/operator-onboarding/README.md` + +--- + +## 9. DAO & Governance Parameters + +### Update governance docs with new ETH-related params: DEFAULT_OPERATOR_ETH_FEE, MINIMAL_OPERATOR_ETH_FEE, RewardsPeriod + +**Pages to Update:** +- [Governance](https://docs.ssv.network/learn/introduction/governance) - `docs/learn/introduction/governance.md` +- [SSVNetworkViews Smart Contract](https://docs.ssv.network/developers/smart-contracts/ssvnetworkviews) - `docs/developers/smart-contracts/ssvnetworkviews.md` +- [SSV Subgraph Examples](https://docs.ssv.network/developers/tools/ssv-subgraph/subgraph-examples) - `docs/developers/tools/ssv-subgraph/subgraph-examples.md` + +### Explain how these parameters affect staker APR and operator revenue + +**Pages to Update:** +- [Governance](https://docs.ssv.network/learn/introduction/governance) - `docs/learn/introduction/governance.md` +- [Fees](https://docs.ssv.network/learn/protocol-overview/tokenomics/fees) - `docs/learn/protocol-overview/tokenomics/fees.md` +- **NEW PAGE**: SSV Staking Guide - `docs/stakers/ssv-staking/README.md` + +### Add references to where these values are read on-chain + +**Pages to Update:** +- [SSVNetworkViews Smart Contract](https://docs.ssv.network/developers/smart-contracts/ssvnetworkviews) - `docs/developers/smart-contracts/ssvnetworkviews.md` +- [SSV Subgraph Examples](https://docs.ssv.network/developers/tools/ssv-subgraph/subgraph-examples) - `docs/developers/tools/ssv-subgraph/subgraph-examples.md` +- [Governance](https://docs.ssv.network/learn/introduction/governance) - `docs/learn/introduction/governance.md` + +--- + +## 10. Legacy & Compatibility Notices + +### Add clear "Legacy SSV Mode" labeling across relevant pages + +**Pages to Update:** +- [Cluster Management Overview](https://docs.ssv.network/stakers/cluster-management) - `docs/stakers/cluster-management/README.md` +- [Clusters Overview](https://docs.ssv.network/stakers/clusters) - `docs/stakers/clusters/README.md` +- [Validator Onboarding](https://docs.ssv.network/stakers/validators/validator-onboarding) - `docs/stakers/validators/validator-onboarding.md` +- [Depositing SSV](https://docs.ssv.network/stakers/cluster-management/depositing-ssv) - `docs/stakers/cluster-management/depositing-ssv.md` +- [Payments](https://docs.ssv.network/learn/protocol-overview/tokenomics/payments) - `docs/learn/protocol-overview/tokenomics/payments.md` +- [Fees](https://docs.ssv.network/learn/protocol-overview/tokenomics/fees) - `docs/learn/protocol-overview/tokenomics/fees.md` + +### Add migration FAQ (what still works, what doesn't) + +**Pages to Update:** +- **NEW PAGE**: Migration FAQ - `docs/stakers/cluster-management/migration-faq.md` +- [Stakers Overview](https://docs.ssv.network/stakers) - `docs/stakers/README.md` +- [Quickstart](https://docs.ssv.network/stakers/quickstart) - `docs/stakers/quickstart.md` + +### Update old examples/snippets that assume SSV fees + +**Pages to Update:** +- [Validator Onboarding](https://docs.ssv.network/stakers/validators/validator-onboarding) - `docs/stakers/validators/validator-onboarding.md` +- [Cluster Balance](https://docs.ssv.network/stakers/clusters/cluster-balance) - `docs/stakers/clusters/cluster-balance.md` +- [Liquidations](https://docs.ssv.network/learn/protocol-overview/tokenomics/liquidations) - `docs/learn/protocol-overview/tokenomics/liquidations.md` +- [Staking Services Integration](https://docs.ssv.network/developers/integration-guides/staking-services) - `docs/developers/integration-guides/staking-services.md` +- [Cluster Balance Script](https://docs.ssv.network/developers/code-examples-and-snippets/cluster-balance-script) - `docs/developers/code-examples-and-snippets/cluster-balance-script.md` +- All SDK examples in `docs/developers/SSV-SDK/examples/` + +### Add versioning notes to avoid mixing v0 mental models with v1 + +**Pages to Update:** +- [Stakers Overview](https://docs.ssv.network/stakers) - `docs/stakers/README.md` +- [Operators Overview](https://docs.ssv.network/operators) - `docs/operators/README.md` +- [Developers Overview](https://docs.ssv.network/developers) - `docs/developers/README.md` +- [Protocol Overview](https://docs.ssv.network/learn/protocol-overview) - `docs/learn/protocol-overview/README.md` +- **NEW PAGE**: Version Differences Guide - `docs/learn/protocol-overview/version-differences.md` + +--- + +## Summary of New Pages to Create + +1. **Migration Guide** - `docs/stakers/cluster-management/migrating-to-eth-clusters.md` +2. **vUnits and Effective Balance** - `docs/learn/protocol-overview/tokenomics/effective-balance.md` +3. **EB Oracle System** - `docs/learn/protocol-overview/eb-oracle-system.md` +4. **SSV Staking Guide** (folder) - `docs/stakers/ssv-staking/README.md` +5. **Stake SSV** - `docs/stakers/ssv-staking/stake-ssv.md` +6. **Claim Rewards** - `docs/stakers/ssv-staking/claim-rewards.md` +7. **Unstake SSV** - `docs/stakers/ssv-staking/unstake-ssv.md` +8. **Oracle Delegation** - `docs/learn/protocol-overview/oracle-delegation.md` +9. **Incentivized Mainnet** - `docs/learn/protocol-overview/incentivized-mainnet.md` +10. **Migration FAQ** - `docs/stakers/cluster-management/migration-faq.md` +11. **Version Differences Guide** - `docs/learn/protocol-overview/version-differences.md` + +--- + +## Summary Statistics + +- **Total Tasks**: 62 +- **Existing Pages to Update**: ~50 pages +- **New Pages to Create**: 11 pages +- **Primary Sections Affected**: + - Stakers (30 tasks) + - Learn/Protocol Overview (18 tasks) + - Operators (10 tasks) + - Developers (4 tasks) + diff --git a/SSV-Staking-Doc-Updates-Tasks.csv b/SSV-Staking-Doc-Updates-Tasks.csv new file mode 100644 index 0000000..de32b6c --- /dev/null +++ b/SSV-Staking-Doc-Updates-Tasks.csv @@ -0,0 +1,118 @@ +Section Task Page Title Page URL File Path Notes +ETH Clusters & Migration Update all cluster lifecycle docs to ETH-first Cluster Management Overview https://docs.ssv.network/stakers/cluster-management docs/stakers/cluster-management/README.md Update overview to prioritize ETH clusters +ETH Clusters & Migration Update all cluster lifecycle docs to ETH-first Validator Onboarding https://docs.ssv.network/stakers/validators/validator-onboarding docs/stakers/validators/validator-onboarding.md Replace SSV funding examples with ETH examples +ETH Clusters & Migration Update all cluster lifecycle docs to ETH-first Creating a New Validator https://docs.ssv.network/stakers/validator-management/creating-a-new-validator docs/stakers/validator-management/creating-a-new-validator.md Update validator creation flow for ETH clusters +ETH Clusters & Migration Update all cluster lifecycle docs to ETH-first Distributing a Validator https://docs.ssv.network/stakers/validator-management/distributing-a-validator docs/stakers/validator-management/distributing-a-validator.md Update distribution process for ETH clusters +ETH Clusters & Migration Update all cluster lifecycle docs to ETH-first Cluster Balance https://docs.ssv.network/stakers/clusters/cluster-balance docs/stakers/clusters/cluster-balance.md Update balance calculations for ETH-first approach +ETH Clusters & Migration Update all cluster lifecycle docs to ETH-first Depositing SSV https://docs.ssv.network/stakers/cluster-management/depositing-ssv docs/stakers/cluster-management/depositing-ssv.md May need to rename to reflect ETH deposits too +ETH Clusters & Migration Update all cluster lifecycle docs to ETH-first Payments https://docs.ssv.network/learn/protocol-overview/tokenomics/payments docs/learn/protocol-overview/tokenomics/payments.md Update payment mechanisms for ETH clusters +ETH Clusters & Migration Add explicit one-way migration warning (SSV → ETH cannot revert) Cluster Management Overview https://docs.ssv.network/stakers/cluster-management docs/stakers/cluster-management/README.md Add prominent warning banner +ETH Clusters & Migration Add explicit one-way migration warning (SSV → ETH cannot revert) Cluster Balance https://docs.ssv.network/stakers/clusters/cluster-balance docs/stakers/clusters/cluster-balance.md Add warning in relevant sections +ETH Clusters & Migration Add explicit one-way migration warning (SSV → ETH cannot revert) Migration Guide https://docs.ssv.network/stakers/cluster-management/migrating-to-eth-clusters docs/stakers/cluster-management/migrating-to-eth-clusters.md NEW PAGE - Create dedicated migration guide +ETH Clusters & Migration Document migrateClusterToETH() flow step-by-step Migration Guide https://docs.ssv.network/stakers/cluster-management/migrating-to-eth-clusters docs/stakers/cluster-management/migrating-to-eth-clusters.md NEW PAGE - Step-by-step migration process +ETH Clusters & Migration Document migrateClusterToETH() flow step-by-step SSVNetwork Smart Contract https://docs.ssv.network/developers/smart-contracts/ssvnetwork docs/developers/smart-contracts/ssvnetwork.md Add migrateClusterToETH function documentation +ETH Clusters & Migration Document migrateClusterToETH() flow step-by-step Cluster Module SDK https://docs.ssv.network/developers/SSV-SDK/module-reference/cluster-module docs/developers/SSV-SDK/module-reference/cluster-module.md Add SDK method for migration +ETH Clusters & Migration Add ETH funding + runway examples (remove SSV runway /flow ) Validator Onboarding https://docs.ssv.network/stakers/validators/validator-onboarding docs/stakers/validators/validator-onboarding.md Replace funding examples with ETH-based calculations +ETH Clusters & Migration Add ETH funding + runway examples (remove SSV runway /flow ) Cluster Balance https://docs.ssv.network/stakers/clusters/cluster-balance docs/stakers/clusters/cluster-balance.md Add ETH runway calculation examples +ETH Clusters & Migration Add ETH funding + runway examples (remove SSV runway /flow ) Staking Services Integration https://docs.ssv.network/developers/integration-guides/staking-services docs/developers/integration-guides/staking-services.md Update integration examples for ETH funding +ETH Clusters & Migration Add ETH funding + runway examples (remove SSV runway /flow ) Staking Pools - Initialization https://docs.ssv.network/developers/integration-guides/staking-pools/initialization-stage docs/developers/integration-guides/staking-pools/initialization-stage.md Update pool initialization for ETH clusters +ETH Clusters & Migration Clearly mark SSV clusters as legacy and transitional Cluster Management Overview https://docs.ssv.network/stakers/cluster-management docs/stakers/cluster-management/README.md Add legacy label and migration path +ETH Clusters & Migration Clearly mark SSV clusters as legacy and transitional Clusters Overview https://docs.ssv.network/stakers/clusters docs/stakers/clusters/README.md Add legacy label and migration path +ETH Clusters & Migration Clearly mark SSV clusters as legacy and transitional Validator Onboarding https://docs.ssv.network/stakers/validators/validator-onboarding docs/stakers/validators/validator-onboarding.md Distinguish between legacy SSV and new ETH clusters +ETH Clusters & Migration Clearly mark SSV clusters as legacy and transitional Payments https://docs.ssv.network/learn/protocol-overview/tokenomics/payments docs/learn/protocol-overview/tokenomics/payments.md Mark SSV payment model as legacy +Operator ETH Fees & Rules Update operator onboarding docs for ETH-only operators Operator Onboarding https://docs.ssv.network/operators/operator-onboarding docs/operators/operator-onboarding/README.md Add ETH-only operator registration flow +Operator ETH Fees & Rules Update operator onboarding docs for ETH-only operators Operator Registration https://docs.ssv.network/operators/operator-management/registration docs/operators/operator-management/registration.md Update registration for ETH-only operators +Operator ETH Fees & Rules Update operator onboarding docs for ETH-only operators Operators Overview https://docs.ssv.network/operators docs/operators/README.md Introduce ETH-only operator concept +Operator ETH Fees & Rules Clarify that ETH and SSV earnings are separate balances Withdrawing Earnings https://docs.ssv.network/operators/operator-management/withdrawing-earnings docs/operators/operator-management/withdrawing-earnings.md Update to show separate ETH/SSV balance withdrawals +Operator ETH Fees & Rules Clarify that ETH and SSV earnings are separate balances Operator Onboarding https://docs.ssv.network/operators/operator-onboarding docs/operators/operator-onboarding/README.md Explain dual balance system +Operator ETH Fees & Rules Clarify that ETH and SSV earnings are separate balances Fees https://docs.ssv.network/learn/protocol-overview/tokenomics/fees docs/learn/protocol-overview/tokenomics/fees.md Document separate balance tracking +Operator ETH Fees & Rules Explicitly state that ETH-only operators cannot receive SSV fees Operator Onboarding https://docs.ssv.network/operators/operator-onboarding docs/operators/operator-onboarding/README.md Add clear statement about fee limitations +Operator ETH Fees & Rules Explicitly state that ETH-only operators cannot receive SSV fees Operator Registration https://docs.ssv.network/operators/operator-management/registration docs/operators/operator-management/registration.md Clarify ETH-only operator constraints +Operator ETH Fees & Rules Explicitly state that ETH-only operators cannot receive SSV fees Fees https://docs.ssv.network/learn/protocol-overview/tokenomics/fees docs/learn/protocol-overview/tokenomics/fees.md Document operator type fee restrictions +Effective Balance (vUnits) Accounting Add a new conceptual doc explaining vUnits and EB weighting vUnits and Effective Balance https://docs.ssv.network/learn/protocol-overview/tokenomics/effective-balance docs/learn/protocol-overview/tokenomics/effective-balance.md NEW PAGE - Complete EB and vUnits explanation +Effective Balance (vUnits) Accounting Add a new conceptual doc explaining vUnits and EB weighting Tokenomics Overview https://docs.ssv.network/learn/protocol-overview/tokenomics docs/learn/protocol-overview/tokenomics/README.md Add link to new EB page +Effective Balance (vUnits) Accounting Add a new conceptual doc explaining vUnits and EB weighting Glossary https://docs.ssv.network/learn/glossary docs/learn/glossary.md Add vUnits and Effective Balance definitions +Effective Balance (vUnits) Accounting Document EB vs validatorCount differences (ETH vs SSV clusters) vUnits and Effective Balance https://docs.ssv.network/learn/protocol-overview/tokenomics/effective-balance docs/learn/protocol-overview/tokenomics/effective-balance.md NEW PAGE - Explain accounting differences +Effective Balance (vUnits) Accounting Document EB vs validatorCount differences (ETH vs SSV clusters) Cluster Balance https://docs.ssv.network/stakers/clusters/cluster-balance docs/stakers/clusters/cluster-balance.md Update formulas to reflect EB vs validator count +Effective Balance (vUnits) Accounting Document EB vs validatorCount differences (ETH vs SSV clusters) Payments https://docs.ssv.network/learn/protocol-overview/tokenomics/payments docs/learn/protocol-overview/tokenomics/payments.md Update payment calculations for EB +Effective Balance (vUnits) Accounting Explain fallback behavior when EB data is missing (32 ETH default) vUnits and Effective Balance https://docs.ssv.network/learn/protocol-overview/tokenomics/effective-balance docs/learn/protocol-overview/tokenomics/effective-balance.md NEW PAGE - Document fallback mechanism +Effective Balance (vUnits) Accounting Explain fallback behavior when EB data is missing (32 ETH default) Cluster Balance https://docs.ssv.network/stakers/clusters/cluster-balance docs/stakers/clusters/cluster-balance.md Explain default EB assumptions +Effective Balance (vUnits) Accounting Add examples showing fee scaling with EB (32 vs 64 vs 2048 ETH) vUnits and Effective Balance https://docs.ssv.network/learn/protocol-overview/tokenomics/effective-balance docs/learn/protocol-overview/tokenomics/effective-balance.md NEW PAGE - Add comprehensive examples +Effective Balance (vUnits) Accounting Add examples showing fee scaling with EB (32 vs 64 vs 2048 ETH) Fees https://docs.ssv.network/learn/protocol-overview/tokenomics/fees docs/learn/protocol-overview/tokenomics/fees.md Add EB-scaled fee examples +Effective Balance (vUnits) Accounting Add examples showing fee scaling with EB (32 vs 64 vs 2048 ETH) Validator Onboarding https://docs.ssv.network/stakers/validators/validator-onboarding docs/stakers/validators/validator-onboarding.md Update funding examples with EB scaling +Effective Balance (vUnits) Accounting Update any fee math references that assume 1 validator = 32 ETH Validator Onboarding https://docs.ssv.network/stakers/validators/validator-onboarding docs/stakers/validators/validator-onboarding.md Replace fixed 32 ETH assumptions +Effective Balance (vUnits) Accounting Update any fee math references that assume 1 validator = 32 ETH Cluster Balance https://docs.ssv.network/stakers/clusters/cluster-balance docs/stakers/clusters/cluster-balance.md Update formulas to use EB +Effective Balance (vUnits) Accounting Update any fee math references that assume 1 validator = 32 ETH Liquidations https://docs.ssv.network/learn/protocol-overview/tokenomics/liquidations docs/learn/protocol-overview/tokenomics/liquidations.md Update liquidation math for EB +Effective Balance (vUnits) Accounting Update any fee math references that assume 1 validator = 32 ETH Fees https://docs.ssv.network/learn/protocol-overview/tokenomics/fees docs/learn/protocol-overview/tokenomics/fees.md Update fee examples for EB +Effective Balance (vUnits) Accounting Update any fee math references that assume 1 validator = 32 ETH Staking Services Integration https://docs.ssv.network/developers/integration-guides/staking-services docs/developers/integration-guides/staking-services.md Update integration code for EB +EB Oracle System (v1) Add EB Oracle architecture overview EB Oracle System https://docs.ssv.network/learn/protocol-overview/eb-oracle-system docs/learn/protocol-overview/eb-oracle-system.md NEW PAGE - Complete oracle architecture +EB Oracle System (v1) Add EB Oracle architecture overview Protocol Overview https://docs.ssv.network/learn/protocol-overview docs/learn/protocol-overview/README.md Add link to oracle system +EB Oracle System (v1) Add EB Oracle architecture overview Tech Overview https://docs.ssv.network/learn/introduction/tech-overview docs/learn/introduction/tech-overview.md Add oracle system to tech stack +EB Oracle System (v1) Document commitRoot → updateClusterBalance lifecycle EB Oracle System https://docs.ssv.network/learn/protocol-overview/eb-oracle-system docs/learn/protocol-overview/eb-oracle-system.md NEW PAGE - Document oracle lifecycle +EB Oracle System (v1) Document commitRoot → updateClusterBalance lifecycle SSVNetwork Smart Contract https://docs.ssv.network/developers/smart-contracts/ssvnetwork docs/developers/smart-contracts/ssvnetwork.md Add oracle method documentation +EB Oracle System (v1) Document commitRoot → updateClusterBalance lifecycle Cluster Balance https://docs.ssv.network/stakers/clusters/cluster-balance docs/stakers/clusters/cluster-balance.md Explain oracle's role in balance updates +EB Oracle System (v1) Explain Merkle root + proof verification in simple terms EB Oracle System https://docs.ssv.network/learn/protocol-overview/eb-oracle-system docs/learn/protocol-overview/eb-oracle-system.md NEW PAGE - Add simple Merkle explanation +EB Oracle System (v1) Explain Merkle root + proof verification in simple terms Tech Overview https://docs.ssv.network/learn/introduction/tech-overview docs/learn/introduction/tech-overview.md Add Merkle verification overview +EB Oracle System (v1) 4 fixed oracles 75% quorum EB Oracle System https://docs.ssv.network/learn/protocol-overview/eb-oracle-system docs/learn/protocol-overview/eb-oracle-system.md NEW PAGE - Document v1 limitations +EB Oracle System (v1) 4 fixed oracles 75% quorum Governance https://docs.ssv.network/learn/introduction/governance docs/learn/introduction/governance.md Add oracle governance parameters +EB Oracle System (v1) Document oracle update frequency EB Oracle System https://docs.ssv.network/learn/protocol-overview/eb-oracle-system docs/learn/protocol-overview/eb-oracle-system.md NEW PAGE - Document update cadence +EB Oracle System (v1) Document oracle update frequency Tech Overview https://docs.ssv.network/learn/introduction/tech-overview docs/learn/introduction/tech-overview.md Add oracle timing information +SSV Staking (cSSV + ETH Rewards) Add full staking user journey (stake → earn → claim → unstake) SSV Staking Guide https://docs.ssv.network/stakers/ssv-staking docs/stakers/ssv-staking/README.md NEW PAGE - Complete staking overview +SSV Staking (cSSV + ETH Rewards) Add full staking user journey (stake → earn → claim → unstake) Stake SSV https://docs.ssv.network/stakers/ssv-staking/stake-ssv docs/stakers/ssv-staking/stake-ssv.md NEW PAGE - How to stake +SSV Staking (cSSV + ETH Rewards) Add full staking user journey (stake → earn → claim → unstake) Claim Rewards https://docs.ssv.network/stakers/ssv-staking/claim-rewards docs/stakers/ssv-staking/claim-rewards.md NEW PAGE - How to claim rewards +SSV Staking (cSSV + ETH Rewards) Add full staking user journey (stake → earn → claim → unstake) Unstake SSV https://docs.ssv.network/stakers/ssv-staking/unstake-ssv docs/stakers/ssv-staking/unstake-ssv.md NEW PAGE - How to unstake +SSV Staking (cSSV + ETH Rewards) Add full staking user journey (stake → earn → claim → unstake) SSV Token https://docs.ssv.network/learn/introduction/ssv-token docs/learn/introduction/ssv-token.md Add staking as new utility +SSV Staking (cSSV + ETH Rewards) Explain cSSV non-rebasing index-based reward model SSV Staking Guide https://docs.ssv.network/stakers/ssv-staking docs/stakers/ssv-staking/README.md NEW PAGE - Explain cSSV mechanics +SSV Staking (cSSV + ETH Rewards) Explain cSSV non-rebasing index-based reward model SSV Token https://docs.ssv.network/learn/introduction/ssv-token docs/learn/introduction/ssv-token.md Add cSSV explanation +SSV Staking (cSSV + ETH Rewards) Explain cSSV non-rebasing index-based reward model Tokenomics Overview https://docs.ssv.network/learn/protocol-overview/tokenomics docs/learn/protocol-overview/tokenomics/README.md Add staking tokenomics +SSV Staking (cSSV + ETH Rewards) Explain cSSV non-rebasing index-based reward model Glossary https://docs.ssv.network/learn/glossary docs/learn/glossary.md Add cSSV definition +SSV Staking (cSSV + ETH Rewards) Document ETH reward flow from clusters → staking contract SSV Staking Guide https://docs.ssv.network/stakers/ssv-staking docs/stakers/ssv-staking/README.md NEW PAGE - Document reward flow +SSV Staking (cSSV + ETH Rewards) Document ETH reward flow from clusters → staking contract Validator Rewards https://docs.ssv.network/stakers/validators/validator-rewards docs/stakers/validators/validator-rewards.md Add ETH reward distribution info +SSV Staking (cSSV + ETH Rewards) Document ETH reward flow from clusters → staking contract Tokenomics Overview https://docs.ssv.network/learn/protocol-overview/tokenomics docs/learn/protocol-overview/tokenomics/README.md Update reward flow diagram +SSV Staking (cSSV + ETH Rewards) Add unstaking cooldown explanation and its implications Unstake SSV https://docs.ssv.network/stakers/ssv-staking/unstake-ssv docs/stakers/ssv-staking/unstake-ssv.md NEW PAGE - Explain cooldown period +SSV Staking (cSSV + ETH Rewards) Add unstaking cooldown explanation and its implications SSV Staking Guide https://docs.ssv.network/stakers/ssv-staking docs/stakers/ssv-staking/README.md NEW PAGE - Document cooldown implications +SSV Staking (cSSV + ETH Rewards) Add unstaking cooldown explanation and its implications Glossary https://docs.ssv.network/learn/glossary docs/learn/glossary.md Add cooldown definition +SSV Staking (cSSV + ETH Rewards) Clarify that rewards stop accruing during cooldown Unstake SSV https://docs.ssv.network/stakers/ssv-staking/unstake-ssv docs/stakers/ssv-staking/unstake-ssv.md NEW PAGE - Add reward cessation warning +SSV Staking (cSSV + ETH Rewards) Clarify that rewards stop accruing during cooldown SSV Staking Guide https://docs.ssv.network/stakers/ssv-staking docs/stakers/ssv-staking/README.md NEW PAGE - Explain reward behavior +Oracle Delegation (Auto-split v1) Document automatic stake-weight splitting across all oracles Oracle Delegation https://docs.ssv.network/learn/protocol-overview/oracle-delegation docs/learn/protocol-overview/oracle-delegation.md NEW PAGE - Explain auto-delegation +Oracle Delegation (Auto-split v1) Document automatic stake-weight splitting across all oracles SSV Staking Guide https://docs.ssv.network/stakers/ssv-staking docs/stakers/ssv-staking/README.md NEW PAGE - Add delegation info +Oracle Delegation (Auto-split v1) Document automatic stake-weight splitting across all oracles Governance https://docs.ssv.network/learn/introduction/governance docs/learn/introduction/governance.md Add oracle voting mechanism +Oracle Delegation (Auto-split v1) Explicitly state that users do not choose oracles in v1 Oracle Delegation https://docs.ssv.network/learn/protocol-overview/oracle-delegation docs/learn/protocol-overview/oracle-delegation.md NEW PAGE - Clarify v1 constraints +Oracle Delegation (Auto-split v1) Explicitly state that users do not choose oracles in v1 SSV Staking Guide https://docs.ssv.network/stakers/ssv-staking docs/stakers/ssv-staking/README.md NEW PAGE - Set user expectations +Oracle Delegation (Auto-split v1) Explain voting weight behavior during unstake cooldown Oracle Delegation https://docs.ssv.network/learn/protocol-overview/oracle-delegation docs/learn/protocol-overview/oracle-delegation.md NEW PAGE - Document cooldown voting weight +Oracle Delegation (Auto-split v1) Explain voting weight behavior during unstake cooldown Unstake SSV https://docs.ssv.network/stakers/ssv-staking/unstake-ssv docs/stakers/ssv-staking/unstake-ssv.md NEW PAGE - Add voting weight info +Oracle Delegation (Auto-split v1) Explain voting weight behavior during unstake cooldown Governance https://docs.ssv.network/learn/introduction/governance docs/learn/introduction/governance.md Update voting weight rules +Oracle Delegation (Auto-split v1) Set expectations for v2 (manual delegation variable oracles) Oracle Delegation https://docs.ssv.network/learn/protocol-overview/oracle-delegation docs/learn/protocol-overview/oracle-delegation.md NEW PAGE - Roadmap to v2 +Oracle Delegation (Auto-split v1) Set expectations for v2 (manual delegation variable oracles) EB Oracle System https://docs.ssv.network/learn/protocol-overview/eb-oracle-system docs/learn/protocol-overview/eb-oracle-system.md NEW PAGE - Mention v2 improvements +Liquidation Behavior Document ETH cluster liquidation (EB-weighted logic) Liquidations https://docs.ssv.network/learn/protocol-overview/tokenomics/liquidations docs/learn/protocol-overview/tokenomics/liquidations.md Add ETH cluster liquidation section +Liquidation Behavior Document ETH cluster liquidation (EB-weighted logic) Liquidator Bot https://docs.ssv.network/operators/liquidator-bot docs/operators/liquidator-bot/README.md Update for EB-weighted liquidations +Liquidation Behavior Document ETH cluster liquidation (EB-weighted logic) Cluster Balance https://docs.ssv.network/stakers/clusters/cluster-balance docs/stakers/clusters/cluster-balance.md Update liquidation thresholds for EB +Liquidation Behavior Document legacy SSV cluster liquidation separately Liquidations https://docs.ssv.network/learn/protocol-overview/tokenomics/liquidations docs/learn/protocol-overview/tokenomics/liquidations.md Add legacy SSV liquidation section +Liquidation Behavior Document legacy SSV cluster liquidation separately Liquidator Bot https://docs.ssv.network/operators/liquidator-bot docs/operators/liquidator-bot/README.md Separate legacy liquidation logic +Liquidation Behavior Add warnings about calling the wrong liquidation path Liquidations https://docs.ssv.network/learn/protocol-overview/tokenomics/liquidations docs/learn/protocol-overview/tokenomics/liquidations.md Add error prevention warnings +Liquidation Behavior Add warnings about calling the wrong liquidation path Liquidator Bot https://docs.ssv.network/operators/liquidator-bot docs/operators/liquidator-bot/README.md Add path selection guidance +Liquidation Behavior Add warnings about calling the wrong liquidation path SSVNetwork Smart Contract https://docs.ssv.network/developers/smart-contracts/ssvnetwork docs/developers/smart-contracts/ssvnetwork.md Document liquidation method differences +Liquidation Behavior Update any liquidation thresholds/examples to be EB-aware Liquidations https://docs.ssv.network/learn/protocol-overview/tokenomics/liquidations docs/learn/protocol-overview/tokenomics/liquidations.md Replace validator count with EB +Liquidation Behavior Update any liquidation thresholds/examples to be EB-aware Cluster Balance https://docs.ssv.network/stakers/clusters/cluster-balance docs/stakers/clusters/cluster-balance.md Update threshold calculations +Liquidation Behavior Update any liquidation thresholds/examples to be EB-aware Reactivation https://docs.ssv.network/stakers/clusters/reactivation docs/stakers/clusters/reactivation.md Update reactivation math for EB +Liquidation Behavior Update any liquidation thresholds/examples to be EB-aware Re-activating a Cluster https://docs.ssv.network/stakers/cluster-management/re-activating-a-cluster docs/stakers/cluster-management/re-activating-a-cluster.md Update reactivation guide for EB +Incentivized Mainnet (IM) Alignment Update IM docs to state ETH clusters only are eligible Incentivized Mainnet https://docs.ssv.network/learn/protocol-overview/incentivized-mainnet docs/learn/protocol-overview/incentivized-mainnet.md NEW PAGE - IM program overview +Incentivized Mainnet (IM) Alignment Update IM docs to state ETH clusters only are eligible Network Overview https://docs.ssv.network/learn/introduction/network-overview docs/learn/introduction/network-overview.md Add IM program mention +Incentivized Mainnet (IM) Alignment Update IM docs to state ETH clusters only are eligible Operators Overview https://docs.ssv.network/operators docs/operators/README.md Add IM eligibility info +Incentivized Mainnet (IM) Alignment Remove all references to off-chain EB fee deductions Fees https://docs.ssv.network/learn/protocol-overview/tokenomics/fees docs/learn/protocol-overview/tokenomics/fees.md Remove off-chain deduction references +Incentivized Mainnet (IM) Alignment Remove all references to off-chain EB fee deductions Operator Onboarding https://docs.ssv.network/operators/operator-onboarding docs/operators/operator-onboarding/README.md Remove off-chain deduction references +Incentivized Mainnet (IM) Alignment Remove all references to off-chain EB fee deductions Payments https://docs.ssv.network/learn/protocol-overview/tokenomics/payments docs/learn/protocol-overview/tokenomics/payments.md Remove off-chain deduction references +Incentivized Mainnet (IM) Alignment Document IM as a migration incentive not a permanent system Incentivized Mainnet https://docs.ssv.network/learn/protocol-overview/incentivized-mainnet docs/learn/protocol-overview/incentivized-mainnet.md NEW PAGE - Clarify temporary nature +Incentivized Mainnet (IM) Alignment Document IM as a migration incentive not a permanent system Governance https://docs.ssv.network/learn/introduction/governance docs/learn/introduction/governance.md Add IM program context +Incentivized Mainnet (IM) Alignment Add guidance for operators losing IM rewards on SSV clusters Incentivized Mainnet https://docs.ssv.network/learn/protocol-overview/incentivized-mainnet docs/learn/protocol-overview/incentivized-mainnet.md NEW PAGE - Migration guidance for operators +Incentivized Mainnet (IM) Alignment Add guidance for operators losing IM rewards on SSV clusters Operators Overview https://docs.ssv.network/operators docs/operators/README.md Add IM transition guidance +Incentivized Mainnet (IM) Alignment Add guidance for operators losing IM rewards on SSV clusters Operator Onboarding https://docs.ssv.network/operators/operator-onboarding docs/operators/operator-onboarding/README.md Add IM impact on operators +DAO & Governance Parameters Update governance docs with new ETH-related params (DEFAULT_OPERATOR_ETH_FEE MINIMAL_OPERATOR_ETH_FEE RewardsPeriod) Governance https://docs.ssv.network/learn/introduction/governance docs/learn/introduction/governance.md Add all new ETH parameters +DAO & Governance Parameters Update governance docs with new ETH-related params (DEFAULT_OPERATOR_ETH_FEE MINIMAL_OPERATOR_ETH_FEE RewardsPeriod) SSVNetworkViews Smart Contract https://docs.ssv.network/developers/smart-contracts/ssvnetworkviews docs/developers/smart-contracts/ssvnetworkviews.md Add getter methods for new parameters +DAO & Governance Parameters Update governance docs with new ETH-related params (DEFAULT_OPERATOR_ETH_FEE MINIMAL_OPERATOR_ETH_FEE RewardsPeriod) SSV Subgraph Examples https://docs.ssv.network/developers/tools/ssv-subgraph/subgraph-examples docs/developers/tools/ssv-subgraph/subgraph-examples.md Add subgraph queries for new params +DAO & Governance Parameters Explain how these parameters affect staker APR and operator revenue Governance https://docs.ssv.network/learn/introduction/governance docs/learn/introduction/governance.md Add impact analysis +DAO & Governance Parameters Explain how these parameters affect staker APR and operator revenue Fees https://docs.ssv.network/learn/protocol-overview/tokenomics/fees docs/learn/protocol-overview/tokenomics/fees.md Show parameter impact on fees +DAO & Governance Parameters Explain how these parameters affect staker APR and operator revenue SSV Staking Guide https://docs.ssv.network/stakers/ssv-staking docs/stakers/ssv-staking/README.md NEW PAGE - Explain APR calculation +DAO & Governance Parameters Add references to where these values are read on-chain SSVNetworkViews Smart Contract https://docs.ssv.network/developers/smart-contracts/ssvnetworkviews docs/developers/smart-contracts/ssvnetworkviews.md Add code examples for reading params +DAO & Governance Parameters Add references to where these values are read on-chain SSV Subgraph Examples https://docs.ssv.network/developers/tools/ssv-subgraph/subgraph-examples docs/developers/tools/ssv-subgraph/subgraph-examples.md Add GraphQL queries +DAO & Governance Parameters Add references to where these values are read on-chain Governance https://docs.ssv.network/learn/introduction/governance docs/learn/introduction/governance.md Link to on-chain references \ No newline at end of file diff --git a/SSV-Staking-context.doc b/SSV-Staking-context.doc new file mode 100644 index 0000000..e69de29 diff --git a/SSV_Staking-design-info.doc b/SSV_Staking-design-info.doc new file mode 100644 index 0000000..ab262aa --- /dev/null +++ b/SSV_Staking-design-info.doc @@ -0,0 +1,318 @@ +SSV Staking v1: ETH Fees, Effective Balance & Staking Rewards +Summary +SSV Network is transitioning from SSV token-based fees to native ETH fees. This enables SSV to become an ETH Accrual Token - where real ETH revenue from network activity flows directly to SSV stakers. + +Why this matters: + +For stakers: Stake SSV, earn ETH. Network fees flow to SSV stakers proportionally. +For clusters & operators: Pay and earn fees in ETH. Simpler accounting, no SSV token management. +For the protocol: Sustainable economics tied to real usage. As the network grows, more fees flow to stakers. + +Post-Pectra compatibility: Ethereum's Pectra upgrade allows validators to have variable effective balances (32-2048 ETH). The new accounting model ensures fees scale proportionally to actual staked ETH, not just validator count. + + +Overview: Three Core Changes +Change +What +Why +ETH Clusters +Clusters pay fees in ETH instead of SSV +Enables ETH revenue to flow to stakers +Effective Balance Accounting +Fees weighted by actual validator ETH, not validator count +Fair fee distribution for variable-balance validators +SSV Staking +Stake SSV to earn ETH network fees +Creates real yield for SSV holders + + +These changes work together: ETH Clusters generate ETH fees, Effective Balance ensures fair accounting, and SSV Staking distributes the fees to token holders. + + +1. ETH Clusters +What Changes +Before: Clusters deposited SSV tokens to pay operator and network fees. + +After: Clusters deposit ETH to pay fees. SSV clusters can migrate to ETH clusters. +Migration Path +New clusters: Automatically use ETH payments +Existing clusters: Can migrate via migrateClusterToETH() +Deposit ETH to cover fees +Receive refund of SSV balance +One-way migration (cannot revert to SSV) +Impact on Users +Role +Impact +Cluster owners +Deposit ETH instead of SSV. SSV clusters can continue running until liquidated or migrated. +Operators +Can serve both SSV and ETH clusters during transition. Earnings accumulate separately. +DAO +Sets upgrade parameters such as operator migration deadline + +Operator ETH Migration +Operators supporting the new system: + +New operators: Start as ETH-only +Existing operators: ETH fee set to 0 if SSV fee was 0, otherwise set to DAO default +Fee changes: Use `declareOperatorFee()` and `executeOperatorFee()` to adjust fees + + +2. Effective Balance Accounting +The Problem +Currently, all validators are treated equally for fee calculations. But post-Pectra, validators can hold 32-2048 ETH. A validator with 64 ETH generates ~2x the rewards of a 32 ETH validator, so fees should scale accordingly. +The Solution: vUnits +vUnits (virtual units) weight fees by actual staked ETH: + +vUnits = (effectiveBalance / 32 ETH) x 100 + +Validator Balance +vUnits +32 ETH +100 +64 ETH +200 +2048 ETH +6400 + + +Fee calculation by cluster type +ETH Clusters: Fees calculated using vUnits (proportional to actual effective balance) +SSV Clusters: Fees calculated using legacy method (1 validator = 32 ETH, regardless of actual EB) + +EB reporting by oracles happens for all clusters regardless of type. + +How Effective Balance is Reported +Since on-chain contracts cannot read beacon chain state directly, an oracle system reports effective balances. + +Fallback behavior: A cluster's EB is the sum of its validators' EBs (minimum 32 ETH per validator). If no EB data exists, the vUnit amount defaults to validatorCount x 100. +Oracle System (v1) +Aspect +v1 Implementation +Oracle count +4 permissioned oracles +Quorum +75% weight required to accept a commitment +Weight distribution +Equal weight across all oracles +Update frequency +Configurable epoch intervals + + +The oracle commits happen in phases: + +Oracle commits root: Calls commitRoot() with Merkle root. Once 75% threshold reached, emits RootCommitted. +Cluster update: Anyone calls updateClusterBalance() with proof. Updates vUnits and fee accounting. Emits ClusterBalanceUpdated. + + + + +3. SSV Staking +How It Works +Stake SSV -> Receive cSSV (transferable ERC-20 token) +Earn ETH -> Network fees flow to stakers proportionally +Claim anytime -> Withdraw accrued ETH rewards +Unstake -> 7-day cooldown, then withdraw SSV + remaining rewards +Token Mechanics +cSSV is a non-rebasing token using index-based reward tracking: + +Your cSSV balance stays constant +ETH rewards accrue separately and can be claimed anytime +Full DeFi composability (can use cSSV in other protocols) +Based on synthetix StakingRewards.sol +Reward Flow +Cluster pays ETH fees + | + v +Network fee portion + | + v +SSV Staking contract + | + v +Distributed to cSSV holders + +Oracle Delegation (v1) +When you stake SSV, your weight is automatically split equally across all 4 oracles. This simplified model ensures: + +All stakers participate in oracle consensus +75% quorum required for commitments +No manual delegation needed +Unstaking Process +Step +Duration +Notes +Initiate unstake +Immediate +Weight remains active for oracle voting +Cooldown period +7 days +Rewards stop accruing +Withdraw +After cooldown +Receive SSV + unclaimed ETH + + +The cooldown period exists to maintain protocol stability and prepare for future governance mechanisms. + + +v1 Scope & Limitations +This is an MVP release focused on core functionality. Known limitations: + +v1 (Current) +v2 (Future) +4 fixed oracles +Variable number of oracles +Auto-split delegation +Staker-chosen delegation +Equal oracle rewards +Performance-based rewards +Basic stake/unstake +Entry/exit queues +Separate liquidators +Oracles handle liquidations + + + +Key Safety Properties +Migration is one-way: Once converted to ETH, clusters/operators cannot revert to SSV +Backward compatible: Legacy SSV clusters continue working until migrated or liquidated +Default accounting: Clusters without EB data assume 32 ETH per validator +Real yield: Staker rewards come from actual network fees collected +Transfer settlement: When cSSV moves, accrued rewards stay with the original holder + + +Timeline & Migration +Contract upgrade: New functionality deployed +Migration period: Operators can set initial ETH fees +Cluster migration: Owners migrate clusters to ETH +Staking launch: SSV staking activated (requires DAO approval) + + + +FAQ +Q: What happens to my SSV when I migrate my cluster? A: Your SSV balance is automatically refunded to you during the migration to ETH process. + +Q: What happens to a new validator's effective balance before oracles report it? A: New validators default to 32 ETH (100 vUnits) until the oracle updates the cluster's effective balance. + +Q: Can operators earn both SSV and ETH? A: Yes, during the transition period operators can serve both cluster types and withdraw earnings separately. + +Q: How much can I earn staking SSV? A: Rewards depend on: total ETH staked through SSV, network fee rate, and your share of staked SSV. See the SSV Staking Calculator for estimates. + +Q: Why is there a 7-day unstaking cooldown? A: The cooldown maintains oracle voting stability and prepares the system for future governance where staked SSV may serve as protocol backstop. + +Q: What if the oracles report incorrect data? A: Merkle proofs ensure only valid data is accepted. Any submission not matching the committed root is rejected. The 75% quorum prevents any single oracle from manipulating data. + + + + + + + +Appendix: Technical Details +Contract Changes +Dual-Currency Storage Model +Operators and clusters now have parallel storage for SSV and ETH: + +Component +SSV Storage +ETH Storage +Operator fee +fee +ethFee +Operator snapshot +snapshot +ethSnapshot +Validator count +validatorCount +ethValidatorCount +Cluster data +s.clusters[hash] +s.ethClusters[hash] + + +New Functions +Migration: + +migrateClusterToETH() - Requires ETH deposit via msg.value, refunds SSV balance, updates DAO accounting + +Operator Withdrawals: + +withdrawOperatorEarnings() - Withdraw ETH earnings +withdrawOperatorEarningsSSV() - Withdraw SSV earnings +withdrawAllVersionOperatorEarnings() - Withdraw both ETH and SSV in one transaction + +Effective Balance: + +commitRoot(merkleRoot, blockNum) - Oracle commits Merkle root of all cluster EBs +updateClusterBalance(proof) - Anyone can update a cluster's EB with Merkle proof + + + +Liquidation: + +liquidate() - For ETH clusters (uses EB-weighted accounting) +liquidateSSV() - For SSV clusters (legacy behavior) +New Events +Event +Description +ClusterMigratedToETH +Cluster migrated from SSV to ETH +RootCommitted +Oracle Merkle root accepted (75% quorum reached) +ClusterBalanceUpdated +Cluster EB updated via Merkle proof + +Operator Rules +New operators: ETH-only, cannot receive SSV payments +Legacy operators: Must migrate to ETH before changing fees (increase/decrease) +Migration period: Operators can set ETH fee up to 2x default (one-time, bypasses 10% limit) +After migration period: Normal 10% fee increase limit applies +Cluster Operations +ETH clusters use native ETH via msg.value for register, deposit, withdraw, reactivate +Migration updates DAO accounting: decrements SSV validator count, increments ETH validator count + +New DAO parameters +Name +Description +DEFAULT_OPERATOR_ETH_FEE +Default ETH fee for operators +MINIMAL_OPERATOR_ETH_FEE +Minimal ETH fee for operators +RewardsPeriod (SSV Staking) +Rewards distribution period. Regulates the speed of rewards distribution. + + + + +Oracle Client Overview +The oracle client is an off-chain service that periodically publishes effective balances to the contract. +Core Loop +Fetch config - Get startEpoch and epochInterval +Calculate target epoch - Determine current target epoch based on finalized beacon state +Wait for finalization - Ensure target epoch is finalized +Fetch cluster EBs - Get effective balances for all validators, sum per cluster +Build Merkle root - Deterministic encoding and sorting +Submit commit - Call commitRoot(merkleRoot, blockNum) with retry logic +Optional: Update clusters - Call updateClusterBalance() for each cluster after RootCommitted +Key Components +Component +Responsibility +Scheduler +Triggers loop at fixed intervals +Epoch Manager +Tracks finalized epochs from the beacon node +Data Fetcher +Syncs SSV contract events, fetches validator EBs +Merkle Builder +Builds a deterministic root from cluster data +TX Manager +Handles nonces, gas pricing, and retries + +EB Calculation +For each cluster, the oracle: + +Sums effective balances of all validators in the cluster +Validators with EB ≤ 32 ETH are rounded up to 32 ETH +Encodes as (clusterId, totalEffectiveBalance) in the Merkle tree + diff --git a/docs/learn/glossary.md b/docs/learn/glossary.md index e74b15a..b4e4498 100644 --- a/docs/learn/glossary.md +++ b/docs/learn/glossary.md @@ -13,12 +13,35 @@ The Beacon Chain is a brand-new, proof-of-stake blockchain that stores and manag ### Cluster -The group (usually 4, in compliance with [the fault tolerance rule is accepted](../../../stakers/validators/validator-onboarding)) of non-trusting operators that manage a set (one, or multiple) validator(s). Each operator in the cluster holds a share of the complete validator key, for more information, see [Shamir Secret Sharing](glossary.md#shamir-secret-sharing). +The group (usually 4, in compliance with [the fault tolerance rule is accepted](../../../stakers/validators/validator-onboarding)) of non-trusting operators that manage a set (one, or multiple) validator(s). Each operator in the cluster holds a share of the complete validator key, for more information, see [Shamir Secret Sharing](glossary.md#shamir-secret-sharing). + +Clusters can be **ETH clusters** (pay fees in ETH) or **SSV clusters** (legacy, pay fees in SSV tokens). ### Consensus Client Formerly known as an Eth2 client. Runs the Ethereum PoS (Proof-of-Stake) consensus layer, aka the Beacon Chain, checking the validity of transactions and new blocks. Examples of consensus clients include Prysm, Teku, Lighthouse, Nimbus, and Lodestar. +### Cooldown Period + +The mandatory 7-day waiting period between initiating SSV token unstaking and being able to withdraw your staked SSV. During this cooldown: +- Rewards stop accruing immediately +- Oracle voting weight remains active +- The process cannot be cancelled +- Unclaimed rewards can still be claimed + +The cooldown exists to maintain oracle voting stability and prepare for future governance mechanisms. + +### cSSV (Compound SSV) + +A non-rebasing ERC-20 token received when you stake SSV tokens. Key properties: + +- **Non-rebasing** - Your cSSV balance stays constant; it doesn't auto-increase +- **Transferable** - Can be transferred, traded, or used in DeFi protocols +- **Index-based rewards** - ETH rewards accrue separately via an increasing reward index +- **Initial 1:1 ratio** - When you stake SSV, you initially receive equal amounts of cSSV + +cSSV represents your staked position and determines your share of network fee rewards. When you unstake, cSSV is burned and you receive back your original SSV plus any unclaimed rewards. + ### Custodial Staking Centralized service that manages the entire ETH staking process on behalf of the user and retains custody over user private validator keys and withdrawal keys. Custodial staking risks include: severe slashing penalties, reduced overall rewards and increased likelihood of attack on user keys as they are held in a centralized fashion by the service. @@ -35,10 +58,25 @@ A cryptographic process to generate a shared public and private key set, calcula Distributed Validator Technology is another name for SSV (Secret Shared Validator). SSV can also be referred to as DVT because the validator is distributed over multiple non-trusting nodes. +### Effective Balance (EB) + +The active stake balance of a validator on the Beacon Chain, used to calculate rewards and voting weight. After Ethereum's Pectra upgrade, validators can have variable effective balances from 32 to 2048 ETH (previously fixed at 32 ETH). + +In SSV Network, effective balances are reported by oracles and used to calculate fair fee distribution through vUnits (virtual units). ETH clusters pay fees proportional to their validators' actual effective balances, while legacy SSV clusters use the traditional validator count method. + ### Epochs & Slots An epoch lasts approximately 6.4 minutes, and includes 32 slots. A slot lasts 12 seconds, during and is the time period in which a randomly selected validator proposes a block. +### ETH Cluster + +A cluster that pays operator and network fees in ETH rather than SSV tokens. ETH clusters are the new standard for SSV Network, enabling ETH revenue to flow to SSV stakers. Key features: + +- Pay fees in native ETH +- Fees calculated using effective balance (EB) and vUnits +- Support variable-balance validators post-Pectra +- Can be created directly or migrated from legacy SSV clusters + ### ETH Staking Services Staking services offer a streamlined way to participate in Ethereum staking. When considering an ETH staking service, it is important to understand how these services manage private user keys. Generally, the more centralized (custodial) the service, the higher the security risks and penalties its users may face, especially if the staking service participates in malicious behaviors or goes offline for an extended period. @@ -93,6 +131,12 @@ Applying secure Multi-Party Computation (MPC) to secret sharing allows for KeySh A service that provides streamlined Ethereum validator set-up and management, but does not hold user private validator keys AND withdrawal keys. Allowing users to maximize staking returns, mitigate security risks and retain complete control over their assets. +### Oracle (SSV Network) + +In SSV Network, oracles are permissioned entities that report validator effective balances from the Beacon Chain to the smart contracts. In v1, there are 4 oracles that require 75% weight consensus to commit balance updates. + +Oracles are supported by SSV stakers, whose staked weight is automatically delegated across all oracles. This oracle system enables fair fee calculation for variable-balance validators post-Pectra. + ### Operator Individuals or institutions that provide the hardware infrastructure, run the SSV protocol, and manage validator KeyShares on behalf of users (stakers). Operators collect fees from stakers in SSV tokens in return for operating their validator(s) on ssv.network. Each operator is ranked on a scale of 0-100% by the DAO based on the overall quality of service they provide. @@ -128,19 +172,26 @@ The SSV Node software maintain peer-to-peer connections with other Nodes to hand ### SSV Token -ssv.network allows access to a decentralized ETH staking infrastructure with SSV token as the protocol’s native token. It has 3 main purposes: +ssv.network allows access to a decentralized ETH staking infrastructure with SSV token as the protocol's native token. It has 4 main purposes: +* **Staking** – Stake SSV to earn ETH rewards from network fees and support oracle infrastructure * **Governance** – Submitting votes and voting on DAO proposals -* **Fees** – Operators receive SSV tokens from Stakers for managing and operating validators on their behalf +* **Fees** – Operators receive fees from managing validators (ETH in new clusters, SSV in legacy clusters) * **Grants** – DAO funding for developers and contributors helping to grow the network +When you stake SSV, you receive cSSV tokens and earn real ETH yield from network activity, making SSV an "ETH Accrual Token." + ### Staker -Services or individual ETH holders that wish to leverage SSV/DVT technology for optimal liveness, security and decentralization of their validator(s). Stakers put 32 ETH “at stake” for each validator they want to run. In the PoS consensus mechanism, validators secure the Ethereum blockchain and earn ETH rewards in return for doing so. +Services or individual ETH holders that wish to leverage SSV/DVT technology for optimal liveness, security and decentralization of their validator(s). Stakers put 32 ETH "at stake" for each validator they want to run. In the PoS consensus mechanism, validators secure the Ethereum blockchain and earn ETH rewards in return for doing so. + +"Staker" can also refer to SSV token holders who stake their SSV to earn ETH rewards from network fees. ### Staking -Staking is the contributory action of running a node in a PoS consensus mechanism blockchain. One must ‘put at stake’ a certain amount of network tokens in order to participate in securing the blockchain by verifying and adding blocks. On Ethereum, the minimum threshold to participate as a validator is 32 ETH. Validators will earn ETH rewards for honestly attesting to and adding blocks. A validator risks decreasing their stake by participating in malicious behaviors or for time spent offline, disconnected from the network. +Staking is the contributory action of running a node in a PoS consensus mechanism blockchain. One must 'put at stake' a certain amount of network tokens in order to participate in securing the blockchain by verifying and adding blocks. On Ethereum, the minimum threshold to participate as a validator is 32 ETH. Validators will earn ETH rewards for honestly attesting to and adding blocks. A validator risks decreasing their stake by participating in malicious behaviors or for time spent offline, disconnected from the network. + +In the context of SSV Network, staking can also refer to staking SSV tokens to earn ETH rewards from network fees. ### Total Value Locked (TVL) @@ -148,6 +199,23 @@ The total amount of ETH in USD (or other currency) that is “locked-up” by st ### Validator -A validator is responsible for confirming transactions and proposing new blocks on the Ethereum blockchain. In order to run a validator, one must put 32 ETH ‘at stake’, which is subject to increase (or decrease) as the validator performs its assigned duties. A validator is different from the comparable concept of a miner on the legacy Ethereum chain, as validators are called upon by the PoS protocol to propose and validate emerging blocks rather than compete for their generation. +A validator is responsible for confirming transactions and proposing new blocks on the Ethereum blockchain. In order to run a validator, one must put 32 ETH 'at stake', which is subject to increase (or decrease) as the validator performs its assigned duties. A validator is different from the comparable concept of a miner on the legacy Ethereum chain, as validators are called upon by the PoS protocol to propose and validate emerging blocks rather than compete for their generation. An SSV validator is one that is run on ssv.network and employs SSV technology to split the validator key into 4 KeyShares for the purposes of distributing the validator over multiple nodes for redundancy and fault-tolerance. + +Post-Pectra, validators can have variable effective balances from 32 to 2048 ETH. + +### vUnits (Virtual Units) + +A measurement unit used in ETH clusters to calculate fees proportional to validator effective balance. Calculated as: + +``` +vUnits = (effectiveBalance / 32 ETH) × 100 +``` + +Examples: +- 32 ETH validator = 100 vUnits +- 64 ETH validator = 200 vUnits +- 2048 ETH validator = 6400 vUnits + +This ensures that validators with higher effective balances pay proportionally higher fees, as they generate more rewards. Legacy SSV clusters do not use vUnits and treat all validators equally regardless of effective balance. diff --git a/docs/learn/introduction/ssv-token.md b/docs/learn/introduction/ssv-token.md index e4b74af..09d0ed7 100644 --- a/docs/learn/introduction/ssv-token.md +++ b/docs/learn/introduction/ssv-token.md @@ -6,12 +6,26 @@ sidebar_position: 3 Secret Shared Validator ($SSV) is the native token of [ssv.network](https://ssv.network/). -$SSV's main use cases are payments and governance. +$SSV's main use cases are payments, staking, and governance. * **Payments** - serve as a way for stakers to compensate operators for managing their validators +* **Staking** - stake SSV tokens to earn ETH rewards from network fees and support oracle infrastructure * **Governance** - a way to participate in ssv.network related decision-making and treasury allocations. -$SSV is playing a pivotal role in the network’s ability to harness a community and motivate the right stakeholders to meaningfully contribute to the network. +$SSV is playing a pivotal role in the network's ability to harness a community and motivate the right stakeholders to meaningfully contribute to the network. + +## SSV as an ETH Accrual Token + +SSV Network has evolved to enable the SSV token to accrue real ETH revenue from network activity. Token holders can now stake their SSV to earn ETH rewards generated from network fees paid by clusters. This creates sustainable yield tied directly to network usage and growth. + +**Key benefits:** +* Earn real ETH yield from actual network activity +* Support the network's oracle infrastructure through staking +* Participate in securing effective balance reporting for validators + +As more validators use SSV Network, more ETH fees flow to SSV stakers, aligning token value with protocol growth. + +Learn more in the [SSV Staking Guide](/stakers/ssv-staking/). ### **Tokenomics** diff --git a/docs/learn/protocol-overview/tokenomics/README.md b/docs/learn/protocol-overview/tokenomics/README.md index 46c7af1..b7b2ce6 100644 --- a/docs/learn/protocol-overview/tokenomics/README.md +++ b/docs/learn/protocol-overview/tokenomics/README.md @@ -5,10 +5,53 @@ sidebar_position: 1 # Tokenomics -The ssv.network utilizes its native SSV token to facilitate payments between stakers and SSV node operators to maintain their validators. Operators maintain validators by reaching a consensus with clusters of other operators to perform network duties on the beacon chain, thereby generating Ethereum staking rewards for stakers. +SSV Network has evolved to include both payment mechanisms and staking utilities, creating a comprehensive economic model that aligns network growth with token holder rewards. -Operators receive SSV payments and generate ETH rewards for stakers. Stakers pay SSV and receive generated ETH rewards in return. +## Network Payments: ETH Clusters +The network uses ETH-based payments for clusters and operators: -![Operators receive SSV payments and generate ETH rewards for stakers. Stakers pay SSV and receive generated ETH rewards in return.](/img/tokenomics-readme-1.avif) -*Operators receive SSV payments and generate ETH rewards for stakers. Stakers pay SSV and receive generated ETH rewards in return.* \ No newline at end of file +* **Clusters pay in ETH** - Deposit ETH to cover operator and network fees +* **Operators earn in ETH** - Receive ETH payments for managing validators +* **Network fees in ETH** - A portion of fees flows to the protocol + +This transition from SSV token payments to ETH enables the network to generate real ETH revenue that can be distributed to SSV stakers. + +### Legacy SSV Clusters + +Existing SSV token-based clusters continue to operate: +* Can migrate to ETH clusters via `migrateClusterToETH()` +* Operators can serve both ETH and SSV clusters during transition +* SSV token balance refunded upon migration + +## SSV as an ETH Accrual Token + +SSV token holders can stake their tokens to earn **real ETH yield** generated from network activity. This makes SSV an **ETH Accrual Token** where network fees flow directly to stakers. + +When clusters pay fees in ETH, a portion flows into the SSV Staking contract and is distributed proportionally to all stakers. As the network grows and more validators use SSV, more ETH fees are generated, increasing rewards for stakers. + +Learn more in the [SSV Staking Guide](/stakers/ssv-staking/). + +## Dual Utility Model + +SSV token serves multiple purposes in the ecosystem: + +| Utility | Description | Benefit | +|---------|-------------|---------| +| **Staking** | Stake SSV to earn ETH from network fees | Real yield for token holders | +| **Governance** | Vote on protocol decisions and treasury allocation | Decentralized control | +| **Oracle Support** | Staked SSV supports oracle consensus | Network security and accuracy | +| **Legacy Payments** | SSV tokens still used in legacy clusters | Backward compatibility | + +## Economic Sustainability + +The new economic model creates sustainable, circular value flow: + +1. **More ETH staked** → More validators using SSV +2. **More validators** → More ETH fees collected +3. **More fees** → Higher rewards for SSV stakers +4. **Higher rewards** → Increased demand for SSV token +5. **More SSV staked** → Stronger oracle infrastructure +6. **Stronger network** → Attracts more ETH validators + +This positive feedback loop ties SSV token value directly to real network usage and revenue. \ No newline at end of file diff --git a/docs/stakers/ssv-staking/README.md b/docs/stakers/ssv-staking/README.md new file mode 100644 index 0000000..3021337 --- /dev/null +++ b/docs/stakers/ssv-staking/README.md @@ -0,0 +1,133 @@ +--- +sidebar_position: 6 +--- + +# SSV Staking + +SSV Staking enables SSV token holders to earn real ETH yield by staking their tokens and supporting the network's oracle infrastructure. When you stake SSV, you receive cSSV (Compound SSV) tokens and earn ETH rewards generated from network fees. + +## Overview + +SSV Network has transitioned to a model where network fees are paid in ETH, creating a sustainable revenue stream that flows directly to SSV stakers. By staking your SSV tokens, you: + +- **Earn ETH rewards** - Receive a proportional share of network fees collected from clusters +- **Support the network** - Your staked weight contributes to oracle consensus for effective balance reporting +- **Maintain liquidity** - Receive transferable cSSV tokens that represent your staked position +- **Retain flexibility** - Claim rewards anytime and unstake with a 7-day cooldown period + + + +## How It Works + +### The Staking Flow + +``` +Stake SSV → Receive cSSV → Earn ETH → Claim Rewards → Unstake (7-day cooldown) +``` + +1. **Stake SSV tokens** - Deposit your SSV tokens into the staking contract +2. **Receive cSSV** - Get cSSV tokens representing your staked position (1:1 initially) +3. **Earn ETH** - Network fees from clusters flow to stakers proportionally +4. **Claim rewards** - Withdraw your accumulated ETH rewards anytime +5. **Unstake** - Initiate unstaking with a 7-day cooldown, then withdraw SSV + remaining rewards + +### ETH Reward Flow + +Network fees flow from clusters to SSV stakers through the following mechanism: + +``` +ETH Clusters pay fees + ↓ +Network fee portion + ↓ +SSV Staking contract + ↓ +Distributed to cSSV holders +``` + +When clusters pay operator fees and network fees in ETH, a portion of these fees flows into the SSV Staking contract. These ETH rewards are distributed proportionally to all cSSV holders based on their share of the total staked SSV. + + + +## cSSV Token Mechanics + +cSSV (Compound SSV) is a **non-rebasing**, **index-based** reward token that represents your staked SSV position. + +### Key Properties + +- **Non-rebasing**: Your cSSV balance stays constant - it doesn't automatically increase +- **Transferable**: cSSV is a standard ERC-20 token that can be transferred or used in DeFi +- **Separate rewards**: ETH rewards accrue separately and can be claimed independently +- **DeFi compatible**: Use cSSV in other protocols while earning staking rewards + +### How Rewards Work + +Unlike rebasing tokens where your balance increases, cSSV uses an **index-based reward model**: + +1. Your cSSV balance remains fixed +2. The reward index increases as network fees flow in +3. Your claimable ETH = (cSSV balance) × (reward index increase) +4. Claim rewards anytime without affecting your cSSV balance + +This model is based on Synthetix's StakingRewards.sol pattern and provides better composability with other DeFi protocols. + +### Example + +- You stake 1,000 SSV → Receive 1,000 cSSV +- Network earns 10 ETH in fees +- If you hold 1% of total cSSV, you can claim 0.1 ETH +- Your cSSV balance stays at 1,000 +- You can claim rewards multiple times as fees continue to flow in + + + +## Oracle Delegation (v1) + +When you stake SSV, your stake weight automatically contributes to the network's oracle system, which reports validator effective balances to the blockchain. + +### Automatic Delegation + +In v1, your staked weight is **automatically split equally** across all 4 permissioned oracles. This means: + +- No manual delegation required +- All stakers participate in oracle consensus +- 75% quorum required for balance commitments +- Your weight remains active during the unstaking cooldown period + +### Future Versions + +Future versions of SSV Staking will introduce: +- Variable number of oracles +- Staker-chosen delegation +- Performance-based oracle rewards +- Entry/exit queues + +## Unstaking Process + +Unstaking SSV involves a **7-day cooldown period** to maintain protocol stability: + +| Step | Duration | Details | +|------|----------|---------| +| **Initiate Unstake** | Immediate | Call unstake function, cooldown begins | +| **Cooldown Period** | 7 days | Your weight remains active for oracle voting | +| **Rewards Stop** | During cooldown | No new rewards accrue after initiating unstake | +| **Withdraw** | After cooldown | Receive SSV + any unclaimed ETH rewards | + +### Why a Cooldown Period? + +The 7-day cooldown serves several purposes: + +1. **Oracle stability** - Prevents rapid weight changes that could affect consensus +2. **Protocol security** - Maintains voting power during critical oracle reporting periods +3. **Future governance** - Prepares for future governance where staked SSV may serve as protocol backstop + +⚠️ **Important**: Rewards stop accruing immediately when you initiate unstaking, even though your oracle voting weight remains active during the cooldown. + +## Getting Started + +Ready to start staking? Follow these guides: + +- [Stake SSV](stake-ssv.md) - Step-by-step guide to stake your SSV tokens +- [Claim Rewards](claim-rewards.md) - How to claim your accumulated ETH rewards +- [Unstake SSV](unstake-ssv.md) - How to unstake your SSV tokens +- [FAQ](faq.md) - Frequently asked questions diff --git a/docs/stakers/ssv-staking/claim-rewards.md b/docs/stakers/ssv-staking/claim-rewards.md new file mode 100644 index 0000000..ce102a1 --- /dev/null +++ b/docs/stakers/ssv-staking/claim-rewards.md @@ -0,0 +1,107 @@ +--- +sidebar_position: 3 +--- + +# Claim Rewards + +Claim your accumulated ETH rewards from SSV staking anytime without unstaking. + +## Overview + +As an SSV staker, you earn ETH rewards proportional to your share of total staked SSV. These rewards: + +- Accrue continuously as clusters pay network fees +- Are tracked separately from your cSSV balance +- Can be claimed anytime without affecting your staking position +- Do not auto-compound (your cSSV balance stays constant) + +## Claiming Process + +### Step 1: Connect Wallet + +Navigate to the SSV Network webapp and connect your wallet holding cSSV tokens. + + + +### Step 2: View Unclaimed Rewards + +Go to the "Staking" section and locate the "Unclaimed Rewards" panel showing total ETH available, reward history, current APY, and last claim timestamp. + + + +### Step 3: Initiate Claim + +Click "Claim Rewards" and review the claim details (ETH amount, estimated gas fees, destination address). + + + +### Step 4: Confirm Transaction + +Your wallet will prompt for confirmation. Review and confirm the transaction, then wait for blockchain confirmation. + + + +### Step 5: Receive ETH + +Once confirmed, ETH is sent to your wallet. Your "Unclaimed Rewards" counter resets to 0, cSSV balance remains unchanged, and new rewards continue accruing immediately. + + + +## How Rewards Are Calculated + +``` +Your Rewards = (Your cSSV / Total cSSV) × Total Network Fees +``` + +**Example:** +- You hold 1,000 cSSV +- Total cSSV supply: 100,000 +- Network collects 10 ETH in fees +- Your share: (1,000 / 100,000) × 10 ETH = 0.1 ETH + +## Factors Affecting Rewards + +1. **Network usage** - More validators = more fees = more rewards +2. **Your stake size** - Larger cSSV balance = larger reward share +3. **Total staked SSV** - More competition = smaller individual share +4. **Network fee rate** - Set by the DAO +5. **Time elapsed** - Longer between claims = more accumulated + +## After Claiming + +- cSSV balance stays the same +- Oracle voting weight unchanged +- Continue earning new rewards immediately +- Can claim again when rewards accumulate + +## Manual Compounding + +cSSV does not auto-compound. To compound rewards: + +1. Claim ETH rewards +2. Swap ETH for SSV tokens +3. Stake the new SSV tokens +4. Receive additional cSSV +5. Earn rewards on larger cSSV balance + +⚠️ **Note**: Requires manual action and incurs transaction costs. + +## Rewards During Unstaking + +⚠️ **Critical**: Rewards stop accruing the MOMENT you initiate unstaking, not after the 7-day cooldown. + +| Stage | Rewards Accruing? | Can Claim? | +|-------|-------------------|------------| +| **Staked** | ✅ Yes | ✅ Yes | +| **Unstaking initiated** | ❌ No | ✅ Yes | +| **During 7-day cooldown** | ❌ No | ✅ Yes | +| **After cooldown** | ❌ No | ✅ During withdrawal | + +## Transfers and Rewards + +If you transfer cSSV tokens to another wallet: + +- **You keep**: All unclaimed ETH rewards accrued up to the transfer +- **Recipient gets**: The cSSV tokens +- **Recipient earns**: New rewards from the transfer moment onward +- **You can still**: Claim your historical rewards diff --git a/docs/stakers/ssv-staking/faq.md b/docs/stakers/ssv-staking/faq.md new file mode 100644 index 0000000..14951b0 --- /dev/null +++ b/docs/stakers/ssv-staking/faq.md @@ -0,0 +1,323 @@ +--- +sidebar_position: 5 +--- + +# SSV Staking FAQ + +Common questions about staking SSV tokens, earning ETH rewards, and the unstaking process. + +## General Staking + +### What is SSV Staking? + +SSV Staking allows SSV token holders to earn real ETH yield from network fees. When you stake SSV, you receive cSSV tokens and earn a proportional share of network fees paid by clusters. + +### How do I start staking? + +1. Connect your wallet to the SSV webapp +2. Navigate to the Staking section +3. Enter the amount of SSV to stake +4. Approve the token (first time only) +5. Confirm the staking transaction + +See the [Stake SSV](stake-ssv.md) guide for detailed steps. + +### What is cSSV? + +cSSV (Compound SSV) is a non-rebasing ERC-20 token you receive when staking SSV. Your cSSV balance stays constant while ETH rewards accrue separately. It's fully transferable and can be used in other DeFi protocols. + +### How much SSV should I stake? + +Consider: +- Keep some SSV unstaked for liquidity needs +- Factor in the 7-day unstaking cooldown +- Larger stakes earn more rewards +- You can always stake more later + +### Is there a minimum staking amount? + +Check the webapp for current minimum requirements. Minimums ensure gas costs are economical relative to potential rewards. + +### Can I stake from multiple wallets? + +Yes! Each wallet can stake independently. Rewards are tracked separately per wallet address. + +## Rewards + +### How are rewards calculated? + +``` +Your Rewards = (Your cSSV / Total cSSV) × Total Network Fees +``` + +Your share is proportional to your percentage of total staked SSV. + +### When do rewards start? + +Rewards begin accruing immediately after your staking transaction is confirmed. + +### What's the current APY? + +APY varies based on: +- Total ETH staked in the network (fee volume) +- Network fee rate set by the DAO +- Total SSV staked + +Check the staking dashboard for current estimates. + +### Do rewards auto-compound? + +No. cSSV is non-rebasing, so rewards don't automatically compound. To compound: +1. Claim ETH rewards +2. Swap ETH for SSV +3. Stake the new SSV +4. Receive additional cSSV + +### Do I need to claim rewards regularly? + +No, rewards can accumulate indefinitely. However, claiming periodically gives you access to ETH and reduces the amount at risk in the contract. + +### Can someone else claim my rewards? + +No. Only the wallet holding the cSSV tokens can claim the associated rewards. + +### Do rewards continue after I claim? + +Yes! Claiming doesn't affect your staking position. Your cSSV balance stays the same and you continue earning immediately. + +### What happens to unclaimed rewards if I never claim? + +They remain in the contract associated with your address indefinitely. You can claim them at any time. + +### Is there a minimum claim amount? + +The contract may have a minimum to prevent spam. Check the webapp for current requirements. + +### Can I claim rewards to a different address? + +Typically, rewards are sent to the wallet holding the cSSV tokens. Check contract documentation for specifics. + +## cSSV Tokens + +### Can I transfer cSSV? + +Yes, cSSV is a standard ERC-20 token and fully transferable. + +### What happens when I transfer cSSV? + +- You keep all unclaimed ETH rewards accrued up to the transfer +- The recipient gets the cSSV tokens +- The recipient starts earning new rewards from that point +- You can still claim your historical rewards + +### Can I use cSSV in other protocols? + +Yes! cSSV has full DeFi composability. You can trade it, use it as collateral, or hold it in any wallet. + +### What happens to cSSV when I unstake? + +The cSSV tokens are burned (permanently destroyed) when you complete the withdrawal. This reduces total cSSV supply. + +## Oracle Delegation + +### What is oracle delegation? + +Your staked SSV weight automatically supports the network's oracle system, which reports validator effective balances to the blockchain. + +### Do I need to choose an oracle? + +No. In v1, your stake weight is automatically split equally across all 4 permissioned oracles. No manual action required. + +### What is the 75% quorum? + +Oracles need 75% of total voting weight to agree before balance updates are accepted. This prevents any single oracle from manipulating data. + +### Will delegation change in the future? + +Yes. Future versions will allow stakers to choose which oracles to delegate to, with performance-based rewards. + +## Unstaking + +### Can I unstake anytime? + +Yes, but there's a mandatory 7-day cooldown period between initiating unstaking and being able to withdraw. + +### Why is there a 7-day cooldown? + +The cooldown maintains: +- Oracle voting stability (prevents rapid weight changes) +- Protocol security (protects against flash-stake attacks) +- Future governance compatibility (prepares for additional use cases) + +### When do rewards stop during unstaking? + +**Critical**: Rewards stop accruing the MOMENT you initiate unstaking, not after the 7-day cooldown. + +### Can I cancel unstaking? + +No. Once you initiate unstaking, the process is irreversible. + +### Can I speed up the cooldown? + +No. The 7-day cooldown is a protocol requirement and cannot be shortened. + +### What happens if I don't withdraw after cooldown ends? + +Nothing urgent. Your SSV remains claimable indefinitely with no deadline. + +### Can I partially unstake? + +Yes! You can unstake a portion of your cSSV while keeping the rest staked and earning rewards. + +### Can I claim rewards during cooldown? + +Yes, you can claim any ETH rewards that accrued before you initiated unstaking. + +### What happens to my oracle weight during cooldown? + +It remains active for the 7-day cooldown period for protocol stability, then is removed upon withdrawal. + +### Can I transfer cSSV during cooldown? + +No. Once unstaking is initiated, the cSSV is locked and cannot be transferred. + +### Can I add more stake during cooldown? + +No. You cannot stake additional SSV while you have an active unstaking cooldown in progress. + +### Do I pay gas twice for unstaking? + +Yes - once to initiate unstaking and once to complete withdrawal after the cooldown period. + +### Can I restake after unstaking? + +Yes! You can restake immediately after withdrawal with no waiting period. However, frequent unstaking and restaking incurs gas costs. + +## Troubleshooting + +### Transaction failed - what should I check? + +1. Sufficient token balance (SSV for staking, ETH for gas) +2. Token approval completed (for first-time staking) +3. Adequate gas limit +4. Contract not paused (rare) +5. No existing unstaking in progress (when trying to unstake) + +### cSSV not showing in wallet + +1. Manually add cSSV token using contract address +2. Check transaction confirmed on block explorer +3. Refresh wallet or try different interface +4. Contact support if issue persists + +### Rewards lower than expected + +- Verify your cSSV balance +- Check total staked SSV (more competition = smaller share) +- Review network usage (fewer validators = lower fees) +- Confirm time since last claim +- Check if DAO fee rate changed + +### Claimed ETH not appearing + +1. Verify transaction confirmed on block explorer +2. Check correct wallet address +3. Refresh wallet interface +4. Allow time for wallet to update +5. Contact support if issue persists + +### Lost wallet access during cooldown + +- Recover wallet using seed phrase +- Import to new wallet software +- Cooldown continues regardless +- Withdrawal still available after 7 days + +## Security + +### How do I verify I'm on the official webapp? + +- Check the URL matches official documentation +- Verify the contract address +- Bookmark the official site +- Never click links from unsolicited messages + +### What should I never share? + +- Private keys +- Seed phrases / recovery phrases +- Never share these with anyone, including "support" + +### Common scam warning signs + +- 🚫 Unsolicited DMs offering staking help +- 🚫 Websites with similar but different URLs +- 🚫 "Instant unstaking" or "cancel cooldown" offers (impossible) +- 🚫 Requests for private keys or seed phrases +- 🚫 Promises of guaranteed or unrealistic returns + +### What should I save for records? + +- Transaction hashes for all operations +- Staking amounts and dates +- Reward claim history +- Unstaking initiation and withdrawal dates + +## Economics + +### Where do staking rewards come from? + +Network fees paid by ETH clusters. A portion of fees flows to the SSV Staking contract and is distributed to cSSV holders. + +### What makes SSV an "ETH Accrual Token"? + +SSV accrues real ETH revenue from network activity. More validators using SSV = more ETH fees = higher rewards for stakers. + +### How does network growth affect rewards? + +More validators → More fees collected → Higher total rewards (but distributed among all stakers) + +### What if there are no validators using SSV? + +If no fees are collected, no rewards accrue. Staking rewards depend on actual network usage. + +## Technical + +### What token standard is cSSV? + +cSSV is a standard ERC-20 token with full compatibility. + +### Is cSSV rebasing? + +No. cSSV is non-rebasing. Your balance stays constant while rewards accrue separately via an index-based model. + +### What is the reward model based on? + +The reward mechanism is based on Synthetix's StakingRewards.sol pattern, providing better DeFi composability than rebasing tokens. + +### Can I interact with the contract directly? + +Yes, advanced users can interact with the smart contract directly. However, using the webapp is recommended for most users. + +## Support + +### Where can I get help? + +- Official SSV documentation +- SSV Discord community +- SSV support channels +- GitHub for technical issues + +### Who should I contact for issues? + +Only contact official SSV support channels. Ignore unsolicited DMs offering help - these are scams. + +## Learn More + +- [SSV Staking Overview](README.md) - Complete staking guide +- [Stake SSV](stake-ssv.md) - Step-by-step staking +- [Claim Rewards](claim-rewards.md) - Claiming process +- [Unstake SSV](unstake-ssv.md) - Unstaking guide +- [Tokenomics](../../learn/protocol-overview/tokenomics/README.md) - Economic model +- [Glossary](../../learn/glossary.md) - Key definitions + diff --git a/docs/stakers/ssv-staking/stake-ssv.md b/docs/stakers/ssv-staking/stake-ssv.md new file mode 100644 index 0000000..89f9e59 --- /dev/null +++ b/docs/stakers/ssv-staking/stake-ssv.md @@ -0,0 +1,114 @@ +--- +sidebar_position: 2 +--- + +# Stake SSV + +Stake SSV tokens to earn ETH rewards from network fees while supporting the network's oracle infrastructure. + +## Prerequisites + +- SSV tokens in your wallet +- Compatible Web3 wallet (MetaMask, WalletConnect, etc.) +- Sufficient ETH for gas fees +- Access to the SSV Network webapp + +## Staking Process + +### Step 1: Connect Your Wallet + +Navigate to the SSV Network webapp, click "Connect Wallet", and approve the connection. + + + +### Step 2: Navigate to Staking + +Go to the "Staking" section to see the staking dashboard with current statistics (total SSV staked, APY, your balance, rewards distributed). + + + +### Step 3: Enter Staking Amount + +Click "Stake SSV" and enter the amount you wish to stake. Review the details including cSSV you'll receive (1:1 ratio initially), estimated APY, and gas fees. + + + +### Step 4: Approve SSV Token (First Time Only) + +If this is your first time staking, approve the staking contract to access your SSV tokens. Click "Approve SSV" and confirm the transaction. + +⚠️ **Note**: You only need to do this once. + + + +### Step 5: Confirm Staking Transaction + +Click "Stake", review the transaction details in your wallet, and confirm. Wait for blockchain confirmation. + + + +### Step 6: Receive cSSV + +Once confirmed, you'll receive cSSV tokens in your wallet and start earning ETH rewards immediately. + + + +## What Happens When You Stake? + +1. **SSV is locked** in the staking contract +2. **You receive cSSV** at a 1:1 ratio initially +3. **Oracle weight** is automatically delegated equally across all 4 oracles +4. **Rewards start accruing** immediately based on network fees +5. **cSSV stays constant** - your balance doesn't auto-compound + +## Understanding Your Position + +After staking, monitor your position on the dashboard: + +- **Staked SSV**: Total SSV tokens staked +- **cSSV Balance**: Your compound SSV token balance +- **Unclaimed Rewards**: ETH rewards available to claim +- **Oracle Weight**: Your contribution to oracle consensus +- **Estimated APY**: Current annual percentage yield + +## Using cSSV Tokens + +cSSV is a standard ERC-20 token with full DeFi composability: + +- ✅ Transfer to another wallet +- ✅ Trade on DEXs (if liquidity exists) +- ✅ Use as collateral in other protocols +- ✅ Hold in cold storage + +**Important**: +- Transferring cSSV transfers the staked position +- Unclaimed ETH rewards stay with the original holder +- The recipient starts earning new rewards from the transfer +- Only the cSSV holder can unstake + +## Adding More Stake + +You can stake additional SSV anytime. Return to the dashboard, click "Stake SSV" again, enter the amount, and confirm (no need to approve again). + +## Transaction Costs + +- **First-time staking**: 2 transactions (Approve + Stake) +- **Additional staking**: 1 transaction (Stake only) +- **Gas costs vary**: Based on network congestion + +## Next Steps + +After staking: + +1. **Monitor your position** - Check the dashboard regularly +2. **Claim rewards** - See [Claim Rewards](claim-rewards.md) when ETH accumulates +3. **Track performance** - Review APY and total rewards earned +4. **Consider adding more** - Stake additional SSV to increase rewards + +## Learn More + +- [SSV Staking Overview](README.md) - Full staking mechanism +- [Claim Rewards](claim-rewards.md) - How to claim ETH rewards +- [Unstake SSV](unstake-ssv.md) - Unstaking process +- [FAQ](faq.md) - Common questions and answers +- [Glossary](../../learn/glossary.md) - Key terms and definitions diff --git a/docs/stakers/ssv-staking/unstake-ssv.md b/docs/stakers/ssv-staking/unstake-ssv.md new file mode 100644 index 0000000..a8dbfb9 --- /dev/null +++ b/docs/stakers/ssv-staking/unstake-ssv.md @@ -0,0 +1,170 @@ +--- +sidebar_position: 4 +--- + +# Unstake SSV + +Unstake your SSV tokens with a mandatory 7-day cooldown period. + +## Overview + +Unstaking SSV withdraws your staked tokens from the staking contract. The process includes: + +- **7-day cooldown period** - Required waiting time after initiating +- **Reward cessation** - Rewards stop accruing immediately +- **Oracle weight retention** - Voting weight remains active during cooldown +- **Full withdrawal** - Receive SSV + any unclaimed ETH after cooldown + +⚠️ **Important**: This process is irreversible. Once initiated, you cannot cancel and rewards stop immediately. + +## Before You Unstake + +### Key Considerations + +| Aspect | Details | +|--------|---------| +| **Cooldown period** | 7 days from initiation to withdrawal | +| **Rewards** | Stop accruing immediately | +| **Oracle weight** | Remains active for voting | +| **Unclaimed ETH** | Should be claimed before or during unstaking | +| **cSSV tokens** | Will be burned upon withdrawal | +| **Irreversible** | Cannot cancel once initiated | + +## Unstaking Process + +### Step 1: Connect Your Wallet + +Navigate to the SSV Network webapp, connect your wallet holding cSSV tokens, and ensure sufficient ETH for gas fees. + + + +### Step 2: Navigate to Unstaking + +Go to the "Staking" section and locate your staking position details (staked SSV, cSSV balance, unclaimed rewards, APY). + + + +### Step 3: Review and Claim Rewards + +Check if you have unclaimed ETH rewards. **Strongly recommended**: Claim them now before proceeding. + +### Step 4: Initiate Unstaking + +Click "Unstake SSV" and choose: +- **Full unstake** (all cSSV) +- **Partial unstake** (specify amount) + +Review the details: SSV amount, cSSV to burn, cooldown end date, and gas fees. + + + +### Step 5: Confirm Transaction + +Read and acknowledge the warnings, click "Confirm Unstake", approve in your wallet, and wait for blockchain confirmation. + + + +### Step 6: Cooldown Period (7 Days) + +Once confirmed: +- Cooldown timer starts +- Rewards stop accruing immediately +- Oracle voting weight remains active +- "Unstaking" status shows on dashboard +- Estimated withdrawal date displayed + + + +### Step 7: Wait for Cooldown + +During the 7-day cooldown: + +- ⏱️ Monitor cooldown timer +- ❌ No new rewards accrue +- ✅ Can still claim previously accumulated rewards +- ✅ Oracle weight still active +- ❌ Cannot cancel unstaking +- ❌ Cannot stake additional SSV + + + +### Step 8: Complete Withdrawal + +After cooldown ends, return to the dashboard, click "Withdraw", review details, and confirm the transaction. + + + +### Step 9: Receive Your SSV + +Once confirmed: +- SSV tokens returned to your wallet +- Any unclaimed ETH rewards sent +- cSSV tokens burned from circulation +- Staking position closed +- Oracle weight removed + + + +## Why 7-Day Cooldown? + +The cooldown period serves three purposes: + +1. **Oracle Stability** - Prevents rapid voting weight changes and maintains consensus reliability +2. **Protocol Security** - Protects against flash-stake attacks and manipulation +3. **Future Governance** - Prepares for governance mechanisms and protocol backstop functionality + +## What Happens During Cooldown + +| Aspect | Status | Details | +|--------|--------|---------| +| **Rewards** | ❌ Stopped | No new ETH rewards accrue | +| **Oracle weight** | ✅ Active | Voting power still counts | +| **Claim rewards** | ✅ Allowed | Can claim accumulated ETH | +| **Transfer cSSV** | ❌ Not allowed | Tokens locked for unstaking | +| **Cancel unstaking** | ❌ Not allowed | Process is irreversible | +| **Add more stake** | ❌ Not allowed | Wait until withdrawal complete | + +## Partial Unstaking + +You can unstake a portion of your cSSV while keeping the rest staked: + +1. Choose partial unstake option +2. Specify amount of cSSV to unstake +3. Remaining cSSV continues earning rewards +4. Only unstaked portion goes through cooldown +5. Can unstake more later if desired + +**Example:** +- You have 1,000 cSSV staked +- Unstake 400 cSSV +- During cooldown: 400 cSSV earns nothing, 600 cSSV still earning +- After cooldown: Withdraw 400 SSV, keep 600 SSV staked + +## Critical: When Rewards Stop + +``` +[Staking] → [Initiate Unstake] → [7-Day Cooldown] → [Withdraw] + ✅ Earning ❌ STOPS HERE ❌ No rewards ❌ No rewards +``` + +⚠️ **Most Important**: Rewards stop the moment you initiate unstaking, NOT after the cooldown period. + +To maximize rewards: +- Let rewards accumulate before unstaking +- Claim all unclaimed ETH +- Consider timing (don't unstake before large fee distributions) +- Remember you lose 7 days of potential rewards + +## After Withdrawal + +Once complete: +- Original SSV tokens returned +- All claimed ETH rewards (if claimed) +- cSSV tokens burned (removed from circulation) +- Oracle weight removed +- Staking position closed + +## Restaking + +You can restake immediately after withdrawal with no waiting period. However, frequent unstaking and restaking incurs gas costs. + From 58615296991a02b89c54724fcb22ca769aad8ff6 Mon Sep 17 00:00:00 2001 From: taylorferran Date: Mon, 12 Jan 2026 17:24:49 +0000 Subject: [PATCH 2/3] Remove helper files --- SSV-Staking-Doc-Updates-Map.md | 393 ------------------------------ SSV-Staking-Doc-Updates-Tasks.csv | 118 --------- SSV-Staking-context.doc | 0 SSV_Staking-design-info.doc | 318 ------------------------ 4 files changed, 829 deletions(-) delete mode 100644 SSV-Staking-Doc-Updates-Map.md delete mode 100644 SSV-Staking-Doc-Updates-Tasks.csv delete mode 100644 SSV-Staking-context.doc delete mode 100644 SSV_Staking-design-info.doc diff --git a/SSV-Staking-Doc-Updates-Map.md b/SSV-Staking-Doc-Updates-Map.md deleted file mode 100644 index c7ad765..0000000 --- a/SSV-Staking-Doc-Updates-Map.md +++ /dev/null @@ -1,393 +0,0 @@ -# SSV Staking Documentation Updates Map - -This document maps all required documentation updates for SSV Staking (ETH clusters, cSSV staking, EB oracle system, etc.) to the specific documentation pages that need to be updated. - ---- - -## 1. ETH Clusters & Migration - -### Update all cluster lifecycle docs to ETH-first (create, fund, run) - -**Pages to Update:** -- [Cluster Management Overview](https://docs.ssv.network/stakers/cluster-management) - `docs/stakers/cluster-management/README.md` -- [Validator Onboarding](https://docs.ssv.network/stakers/validators/validator-onboarding) - `docs/stakers/validators/validator-onboarding.md` -- [Creating a New Validator](https://docs.ssv.network/stakers/validator-management/creating-a-new-validator) - `docs/stakers/validator-management/creating-a-new-validator.md` -- [Distributing a Validator](https://docs.ssv.network/stakers/validator-management/distributing-a-validator) - `docs/stakers/validator-management/distributing-a-validator.md` -- [Cluster Balance](https://docs.ssv.network/stakers/clusters/cluster-balance) - `docs/stakers/clusters/cluster-balance.md` -- [Depositing SSV](https://docs.ssv.network/stakers/cluster-management/depositing-ssv) - `docs/stakers/cluster-management/depositing-ssv.md` -- [Payments](https://docs.ssv.network/learn/protocol-overview/tokenomics/payments) - `docs/learn/protocol-overview/tokenomics/payments.md` - -### Add explicit one-way migration warning (SSV → ETH cannot revert) - -**Pages to Update:** -- [Cluster Management Overview](https://docs.ssv.network/stakers/cluster-management) - `docs/stakers/cluster-management/README.md` -- [Cluster Balance](https://docs.ssv.network/stakers/clusters/cluster-balance) - `docs/stakers/clusters/cluster-balance.md` -- **NEW SECTION NEEDED**: Migration Guide (create new file in `docs/stakers/cluster-management/`) - -### Document migrateClusterToETH() flow step-by-step - -**Pages to Update:** -- **NEW PAGE**: Migration Guide - `docs/stakers/cluster-management/migrating-to-eth-clusters.md` -- [SSVNetwork Smart Contract](https://docs.ssv.network/developers/smart-contracts/ssvnetwork) - `docs/developers/smart-contracts/ssvnetwork.md` -- [Cluster Module SDK](https://docs.ssv.network/developers/SSV-SDK/module-reference/cluster-module) - `docs/developers/SSV-SDK/module-reference/cluster-module.md` - -### Add ETH funding + runway examples (remove SSV-centric assumptions) - -**Pages to Update:** -- [Validator Onboarding](https://docs.ssv.network/stakers/validators/validator-onboarding) - `docs/stakers/validators/validator-onboarding.md` -- [Cluster Balance](https://docs.ssv.network/stakers/clusters/cluster-balance) - `docs/stakers/clusters/cluster-balance.md` -- [Staking Services Integration](https://docs.ssv.network/developers/integration-guides/staking-services) - `docs/developers/integration-guides/staking-services.md` -- [Staking Pools - Initialization](https://docs.ssv.network/developers/integration-guides/staking-pools/initialization-stage) - `docs/developers/integration-guides/staking-pools/initialization-stage.md` - -### Clearly mark SSV clusters as legacy and transitional - -**Pages to Update:** -- [Cluster Management Overview](https://docs.ssv.network/stakers/cluster-management) - `docs/stakers/cluster-management/README.md` -- [Clusters Overview](https://docs.ssv.network/stakers/clusters) - `docs/stakers/clusters/README.md` -- [Validator Onboarding](https://docs.ssv.network/stakers/validators/validator-onboarding) - `docs/stakers/validators/validator-onboarding.md` -- [Payments](https://docs.ssv.network/learn/protocol-overview/tokenomics/payments) - `docs/learn/protocol-overview/tokenomics/payments.md` - ---- - -## 2. Operator ETH Fees & Rules - -### Update operator onboarding docs for ETH-only operators - -**Pages to Update:** -- [Operator Onboarding](https://docs.ssv.network/operators/operator-onboarding) - `docs/operators/operator-onboarding/README.md` -- [Operator Registration](https://docs.ssv.network/operators/operator-management/registration) - `docs/operators/operator-management/registration.md` -- [Operators Overview](https://docs.ssv.network/operators) - `docs/operators/README.md` - -### Document ETH fee defaults and DAO-defined fallback behavior - -**Pages to Update:** -- [Operator Onboarding](https://docs.ssv.network/operators/operator-onboarding) - `docs/operators/operator-onboarding/README.md` -- [Operator Registration](https://docs.ssv.network/operators/operator-management/registration) - `docs/operators/operator-management/registration.md` -- [Fees](https://docs.ssv.network/learn/protocol-overview/tokenomics/fees) - `docs/learn/protocol-overview/tokenomics/fees.md` -- [Governance](https://docs.ssv.network/learn/introduction/governance) - `docs/learn/introduction/governance.md` - -### Explain migration-period fee override (2× default, one-time) - -**Pages to Update:** -- [Update Fee](https://docs.ssv.network/operators/operator-onboarding/update-fee) - `docs/operators/operator-onboarding/update-fee.md` -- [Updating Operator Fees](https://docs.ssv.network/operators/operator-management/updating-operator-fees) - `docs/operators/operator-management/updating-operator-fees.md` -- **NEW SECTION**: Migration-specific fee rules in operator docs - -### Clarify that ETH and SSV earnings are separate balances - -**Pages to Update:** -- [Withdrawing Earnings](https://docs.ssv.network/operators/operator-management/withdrawing-earnings) - `docs/operators/operator-management/withdrawing-earnings.md` -- [Operator Onboarding](https://docs.ssv.network/operators/operator-onboarding) - `docs/operators/operator-onboarding/README.md` -- [Fees](https://docs.ssv.network/learn/protocol-overview/tokenomics/fees) - `docs/learn/protocol-overview/tokenomics/fees.md` - -### Explicitly state that ETH-only operators cannot receive SSV fees - -**Pages to Update:** -- [Operator Onboarding](https://docs.ssv.network/operators/operator-onboarding) - `docs/operators/operator-onboarding/README.md` -- [Operator Registration](https://docs.ssv.network/operators/operator-management/registration) - `docs/operators/operator-management/registration.md` -- [Fees](https://docs.ssv.network/learn/protocol-overview/tokenomics/fees) - `docs/learn/protocol-overview/tokenomics/fees.md` - ---- - -## 3. Effective Balance (vUnits) Accounting - -### Add a new conceptual doc explaining vUnits and EB weighting - -**Pages to Update:** -- **NEW PAGE**: vUnits and Effective Balance - `docs/learn/protocol-overview/tokenomics/effective-balance.md` -- [Tokenomics Overview](https://docs.ssv.network/learn/protocol-overview/tokenomics) - `docs/learn/protocol-overview/tokenomics/README.md` -- [Glossary](https://docs.ssv.network/learn/glossary) - `docs/learn/glossary.md` - -### Document EB vs validatorCount differences (ETH vs SSV clusters) - -**Pages to Update:** -- **NEW PAGE**: vUnits and Effective Balance - `docs/learn/protocol-overview/tokenomics/effective-balance.md` -- [Cluster Balance](https://docs.ssv.network/stakers/clusters/cluster-balance) - `docs/stakers/clusters/cluster-balance.md` -- [Payments](https://docs.ssv.network/learn/protocol-overview/tokenomics/payments) - `docs/learn/protocol-overview/tokenomics/payments.md` - -### Explain fallback behavior when EB data is missing (32 ETH default) - -**Pages to Update:** -- **NEW PAGE**: vUnits and Effective Balance - `docs/learn/protocol-overview/tokenomics/effective-balance.md` -- [Cluster Balance](https://docs.ssv.network/stakers/clusters/cluster-balance) - `docs/stakers/clusters/cluster-balance.md` - -### Add examples showing fee scaling with EB (32 vs 64 vs 2048 ETH) - -**Pages to Update:** -- **NEW PAGE**: vUnits and Effective Balance - `docs/learn/protocol-overview/tokenomics/effective-balance.md` -- [Fees](https://docs.ssv.network/learn/protocol-overview/tokenomics/fees) - `docs/learn/protocol-overview/tokenomics/fees.md` -- [Validator Onboarding](https://docs.ssv.network/stakers/validators/validator-onboarding) - `docs/stakers/validators/validator-onboarding.md` - -### Update any fee math references that assume 1 validator = 32 ETH - -**Pages to Update:** -- [Validator Onboarding](https://docs.ssv.network/stakers/validators/validator-onboarding) - `docs/stakers/validators/validator-onboarding.md` -- [Cluster Balance](https://docs.ssv.network/stakers/clusters/cluster-balance) - `docs/stakers/clusters/cluster-balance.md` -- [Liquidations](https://docs.ssv.network/learn/protocol-overview/tokenomics/liquidations) - `docs/learn/protocol-overview/tokenomics/liquidations.md` -- [Fees](https://docs.ssv.network/learn/protocol-overview/tokenomics/fees) - `docs/learn/protocol-overview/tokenomics/fees.md` -- [Staking Services Integration](https://docs.ssv.network/developers/integration-guides/staking-services) - `docs/developers/integration-guides/staking-services.md` - ---- - -## 4. EB Oracle System (v1) - -### Add EB Oracle architecture overview (why oracles exist at all) - -**Pages to Update:** -- **NEW PAGE**: EB Oracle System - `docs/learn/protocol-overview/eb-oracle-system.md` -- [Protocol Overview](https://docs.ssv.network/learn/protocol-overview) - `docs/learn/protocol-overview/README.md` -- [Tech Overview](https://docs.ssv.network/learn/introduction/tech-overview) - `docs/learn/introduction/tech-overview.md` - -### Document commitRoot → updateClusterBalance lifecycle - -**Pages to Update:** -- **NEW PAGE**: EB Oracle System - `docs/learn/protocol-overview/eb-oracle-system.md` -- [SSVNetwork Smart Contract](https://docs.ssv.network/developers/smart-contracts/ssvnetwork) - `docs/developers/smart-contracts/ssvnetwork.md` -- [Cluster Balance](https://docs.ssv.network/stakers/clusters/cluster-balance) - `docs/stakers/clusters/cluster-balance.md` - -### Explain Merkle root + proof verification in simple terms - -**Pages to Update:** -- **NEW PAGE**: EB Oracle System - `docs/learn/protocol-overview/eb-oracle-system.md` -- [Tech Overview](https://docs.ssv.network/learn/introduction/tech-overview) - `docs/learn/introduction/tech-overview.md` - -### Clearly state v1 constraints: 4 fixed oracles, 75% quorum - -**Pages to Update:** -- **NEW PAGE**: EB Oracle System - `docs/learn/protocol-overview/eb-oracle-system.md` -- [Governance](https://docs.ssv.network/learn/introduction/governance) - `docs/learn/introduction/governance.md` - -### Document oracle update frequency and finality assumptions - -**Pages to Update:** -- **NEW PAGE**: EB Oracle System - `docs/learn/protocol-overview/eb-oracle-system.md` -- [Tech Overview](https://docs.ssv.network/learn/introduction/tech-overview) - `docs/learn/introduction/tech-overview.md` - ---- - -## 5. SSV Staking (cSSV + ETH Rewards) - -### Add full staking user journey (stake → earn → claim → unstake) - -**Pages to Update:** -- **NEW PAGE**: SSV Staking Guide - `docs/stakers/ssv-staking/README.md` -- **NEW PAGE**: Stake SSV - `docs/stakers/ssv-staking/stake-ssv.md` -- **NEW PAGE**: Claim Rewards - `docs/stakers/ssv-staking/claim-rewards.md` -- **NEW PAGE**: Unstake SSV - `docs/stakers/ssv-staking/unstake-ssv.md` -- [SSV Token](https://docs.ssv.network/learn/introduction/ssv-token) - `docs/learn/introduction/ssv-token.md` - -### Explain cSSV non-rebasing, index-based reward model - -**Pages to Update:** -- **NEW PAGE**: SSV Staking Guide - `docs/stakers/ssv-staking/README.md` -- [SSV Token](https://docs.ssv.network/learn/introduction/ssv-token) - `docs/learn/introduction/ssv-token.md` -- [Tokenomics Overview](https://docs.ssv.network/learn/protocol-overview/tokenomics) - `docs/learn/protocol-overview/tokenomics/README.md` -- [Glossary](https://docs.ssv.network/learn/glossary) - `docs/learn/glossary.md` - -### Document ETH reward flow from clusters → staking contract - -**Pages to Update:** -- **NEW PAGE**: SSV Staking Guide - `docs/stakers/ssv-staking/README.md` -- [Validator Rewards](https://docs.ssv.network/stakers/validators/validator-rewards) - `docs/stakers/validators/validator-rewards.md` -- [Tokenomics Overview](https://docs.ssv.network/learn/protocol-overview/tokenomics) - `docs/learn/protocol-overview/tokenomics/README.md` - -### Add unstaking cooldown explanation and its implications - -**Pages to Update:** -- **NEW PAGE**: Unstake SSV - `docs/stakers/ssv-staking/unstake-ssv.md` -- **NEW PAGE**: SSV Staking Guide - `docs/stakers/ssv-staking/README.md` -- [Glossary](https://docs.ssv.network/learn/glossary) - `docs/learn/glossary.md` - -### Clarify that rewards stop accruing during cooldown - -**Pages to Update:** -- **NEW PAGE**: Unstake SSV - `docs/stakers/ssv-staking/unstake-ssv.md` -- **NEW PAGE**: SSV Staking Guide - `docs/stakers/ssv-staking/README.md` - ---- - -## 6. Oracle Delegation (Auto-split v1) - -### Document automatic stake-weight splitting across all oracles - -**Pages to Update:** -- **NEW PAGE**: Oracle Delegation - `docs/learn/protocol-overview/oracle-delegation.md` -- **NEW PAGE**: SSV Staking Guide - `docs/stakers/ssv-staking/README.md` -- [Governance](https://docs.ssv.network/learn/introduction/governance) - `docs/learn/introduction/governance.md` - -### Explicitly state that users do not choose oracles in v1 - -**Pages to Update:** -- **NEW PAGE**: Oracle Delegation - `docs/learn/protocol-overview/oracle-delegation.md` -- **NEW PAGE**: SSV Staking Guide - `docs/stakers/ssv-staking/README.md` - -### Explain voting weight behavior during unstake cooldown - -**Pages to Update:** -- **NEW PAGE**: Oracle Delegation - `docs/learn/protocol-overview/oracle-delegation.md` -- **NEW PAGE**: Unstake SSV - `docs/stakers/ssv-staking/unstake-ssv.md` -- [Governance](https://docs.ssv.network/learn/introduction/governance) - `docs/learn/introduction/governance.md` - -### Set expectations for v2 (manual delegation, variable oracles) - -**Pages to Update:** -- **NEW PAGE**: Oracle Delegation - `docs/learn/protocol-overview/oracle-delegation.md` -- **NEW PAGE**: EB Oracle System - `docs/learn/protocol-overview/eb-oracle-system.md` - ---- - -## 7. Liquidation Behavior - -### Document ETH cluster liquidation (EB-weighted logic) - -**Pages to Update:** -- [Liquidations](https://docs.ssv.network/learn/protocol-overview/tokenomics/liquidations) - `docs/learn/protocol-overview/tokenomics/liquidations.md` -- [Liquidator Bot](https://docs.ssv.network/operators/liquidator-bot) - `docs/operators/liquidator-bot/README.md` -- [Cluster Balance](https://docs.ssv.network/stakers/clusters/cluster-balance) - `docs/stakers/clusters/cluster-balance.md` - -### Document legacy SSV cluster liquidation separately - -**Pages to Update:** -- [Liquidations](https://docs.ssv.network/learn/protocol-overview/tokenomics/liquidations) - `docs/learn/protocol-overview/tokenomics/liquidations.md` -- [Liquidator Bot](https://docs.ssv.network/operators/liquidator-bot) - `docs/operators/liquidator-bot/README.md` - -### Add warnings about calling the wrong liquidation path - -**Pages to Update:** -- [Liquidations](https://docs.ssv.network/learn/protocol-overview/tokenomics/liquidations) - `docs/learn/protocol-overview/tokenomics/liquidations.md` -- [Liquidator Bot](https://docs.ssv.network/operators/liquidator-bot) - `docs/operators/liquidator-bot/README.md` -- [SSVNetwork Smart Contract](https://docs.ssv.network/developers/smart-contracts/ssvnetwork) - `docs/developers/smart-contracts/ssvnetwork.md` - -### Update any liquidation thresholds/examples to be EB-aware - -**Pages to Update:** -- [Liquidations](https://docs.ssv.network/learn/protocol-overview/tokenomics/liquidations) - `docs/learn/protocol-overview/tokenomics/liquidations.md` -- [Cluster Balance](https://docs.ssv.network/stakers/clusters/cluster-balance) - `docs/stakers/clusters/cluster-balance.md` -- [Reactivation](https://docs.ssv.network/stakers/clusters/reactivation) - `docs/stakers/clusters/reactivation.md` -- [Re-activating a Cluster](https://docs.ssv.network/stakers/cluster-management/re-activating-a-cluster) - `docs/stakers/cluster-management/re-activating-a-cluster.md` - ---- - -## 8. Incentivized Mainnet (IM) Alignment - -### Update IM docs to state ETH clusters only are eligible - -**Pages to Update:** -- **NEW PAGE**: Incentivized Mainnet - `docs/learn/protocol-overview/incentivized-mainnet.md` -- [Network Overview](https://docs.ssv.network/learn/introduction/network-overview) - `docs/learn/introduction/network-overview.md` -- [Operators Overview](https://docs.ssv.network/operators) - `docs/operators/README.md` - -### Remove all references to off-chain EB fee deductions - -**Pages to Update:** -- [Fees](https://docs.ssv.network/learn/protocol-overview/tokenomics/fees) - `docs/learn/protocol-overview/tokenomics/fees.md` -- [Operator Onboarding](https://docs.ssv.network/operators/operator-onboarding) - `docs/operators/operator-onboarding/README.md` -- [Payments](https://docs.ssv.network/learn/protocol-overview/tokenomics/payments) - `docs/learn/protocol-overview/tokenomics/payments.md` - -### Document IM as a migration incentive, not a permanent system - -**Pages to Update:** -- **NEW PAGE**: Incentivized Mainnet - `docs/learn/protocol-overview/incentivized-mainnet.md` -- [Governance](https://docs.ssv.network/learn/introduction/governance) - `docs/learn/introduction/governance.md` - -### Add guidance for operators losing IM rewards on SSV clusters - -**Pages to Update:** -- **NEW PAGE**: Incentivized Mainnet - `docs/learn/protocol-overview/incentivized-mainnet.md` -- [Operators Overview](https://docs.ssv.network/operators) - `docs/operators/README.md` -- [Operator Onboarding](https://docs.ssv.network/operators/operator-onboarding) - `docs/operators/operator-onboarding/README.md` - ---- - -## 9. DAO & Governance Parameters - -### Update governance docs with new ETH-related params: DEFAULT_OPERATOR_ETH_FEE, MINIMAL_OPERATOR_ETH_FEE, RewardsPeriod - -**Pages to Update:** -- [Governance](https://docs.ssv.network/learn/introduction/governance) - `docs/learn/introduction/governance.md` -- [SSVNetworkViews Smart Contract](https://docs.ssv.network/developers/smart-contracts/ssvnetworkviews) - `docs/developers/smart-contracts/ssvnetworkviews.md` -- [SSV Subgraph Examples](https://docs.ssv.network/developers/tools/ssv-subgraph/subgraph-examples) - `docs/developers/tools/ssv-subgraph/subgraph-examples.md` - -### Explain how these parameters affect staker APR and operator revenue - -**Pages to Update:** -- [Governance](https://docs.ssv.network/learn/introduction/governance) - `docs/learn/introduction/governance.md` -- [Fees](https://docs.ssv.network/learn/protocol-overview/tokenomics/fees) - `docs/learn/protocol-overview/tokenomics/fees.md` -- **NEW PAGE**: SSV Staking Guide - `docs/stakers/ssv-staking/README.md` - -### Add references to where these values are read on-chain - -**Pages to Update:** -- [SSVNetworkViews Smart Contract](https://docs.ssv.network/developers/smart-contracts/ssvnetworkviews) - `docs/developers/smart-contracts/ssvnetworkviews.md` -- [SSV Subgraph Examples](https://docs.ssv.network/developers/tools/ssv-subgraph/subgraph-examples) - `docs/developers/tools/ssv-subgraph/subgraph-examples.md` -- [Governance](https://docs.ssv.network/learn/introduction/governance) - `docs/learn/introduction/governance.md` - ---- - -## 10. Legacy & Compatibility Notices - -### Add clear "Legacy SSV Mode" labeling across relevant pages - -**Pages to Update:** -- [Cluster Management Overview](https://docs.ssv.network/stakers/cluster-management) - `docs/stakers/cluster-management/README.md` -- [Clusters Overview](https://docs.ssv.network/stakers/clusters) - `docs/stakers/clusters/README.md` -- [Validator Onboarding](https://docs.ssv.network/stakers/validators/validator-onboarding) - `docs/stakers/validators/validator-onboarding.md` -- [Depositing SSV](https://docs.ssv.network/stakers/cluster-management/depositing-ssv) - `docs/stakers/cluster-management/depositing-ssv.md` -- [Payments](https://docs.ssv.network/learn/protocol-overview/tokenomics/payments) - `docs/learn/protocol-overview/tokenomics/payments.md` -- [Fees](https://docs.ssv.network/learn/protocol-overview/tokenomics/fees) - `docs/learn/protocol-overview/tokenomics/fees.md` - -### Add migration FAQ (what still works, what doesn't) - -**Pages to Update:** -- **NEW PAGE**: Migration FAQ - `docs/stakers/cluster-management/migration-faq.md` -- [Stakers Overview](https://docs.ssv.network/stakers) - `docs/stakers/README.md` -- [Quickstart](https://docs.ssv.network/stakers/quickstart) - `docs/stakers/quickstart.md` - -### Update old examples/snippets that assume SSV fees - -**Pages to Update:** -- [Validator Onboarding](https://docs.ssv.network/stakers/validators/validator-onboarding) - `docs/stakers/validators/validator-onboarding.md` -- [Cluster Balance](https://docs.ssv.network/stakers/clusters/cluster-balance) - `docs/stakers/clusters/cluster-balance.md` -- [Liquidations](https://docs.ssv.network/learn/protocol-overview/tokenomics/liquidations) - `docs/learn/protocol-overview/tokenomics/liquidations.md` -- [Staking Services Integration](https://docs.ssv.network/developers/integration-guides/staking-services) - `docs/developers/integration-guides/staking-services.md` -- [Cluster Balance Script](https://docs.ssv.network/developers/code-examples-and-snippets/cluster-balance-script) - `docs/developers/code-examples-and-snippets/cluster-balance-script.md` -- All SDK examples in `docs/developers/SSV-SDK/examples/` - -### Add versioning notes to avoid mixing v0 mental models with v1 - -**Pages to Update:** -- [Stakers Overview](https://docs.ssv.network/stakers) - `docs/stakers/README.md` -- [Operators Overview](https://docs.ssv.network/operators) - `docs/operators/README.md` -- [Developers Overview](https://docs.ssv.network/developers) - `docs/developers/README.md` -- [Protocol Overview](https://docs.ssv.network/learn/protocol-overview) - `docs/learn/protocol-overview/README.md` -- **NEW PAGE**: Version Differences Guide - `docs/learn/protocol-overview/version-differences.md` - ---- - -## Summary of New Pages to Create - -1. **Migration Guide** - `docs/stakers/cluster-management/migrating-to-eth-clusters.md` -2. **vUnits and Effective Balance** - `docs/learn/protocol-overview/tokenomics/effective-balance.md` -3. **EB Oracle System** - `docs/learn/protocol-overview/eb-oracle-system.md` -4. **SSV Staking Guide** (folder) - `docs/stakers/ssv-staking/README.md` -5. **Stake SSV** - `docs/stakers/ssv-staking/stake-ssv.md` -6. **Claim Rewards** - `docs/stakers/ssv-staking/claim-rewards.md` -7. **Unstake SSV** - `docs/stakers/ssv-staking/unstake-ssv.md` -8. **Oracle Delegation** - `docs/learn/protocol-overview/oracle-delegation.md` -9. **Incentivized Mainnet** - `docs/learn/protocol-overview/incentivized-mainnet.md` -10. **Migration FAQ** - `docs/stakers/cluster-management/migration-faq.md` -11. **Version Differences Guide** - `docs/learn/protocol-overview/version-differences.md` - ---- - -## Summary Statistics - -- **Total Tasks**: 62 -- **Existing Pages to Update**: ~50 pages -- **New Pages to Create**: 11 pages -- **Primary Sections Affected**: - - Stakers (30 tasks) - - Learn/Protocol Overview (18 tasks) - - Operators (10 tasks) - - Developers (4 tasks) - diff --git a/SSV-Staking-Doc-Updates-Tasks.csv b/SSV-Staking-Doc-Updates-Tasks.csv deleted file mode 100644 index de32b6c..0000000 --- a/SSV-Staking-Doc-Updates-Tasks.csv +++ /dev/null @@ -1,118 +0,0 @@ -Section Task Page Title Page URL File Path Notes -ETH Clusters & Migration Update all cluster lifecycle docs to ETH-first Cluster Management Overview https://docs.ssv.network/stakers/cluster-management docs/stakers/cluster-management/README.md Update overview to prioritize ETH clusters -ETH Clusters & Migration Update all cluster lifecycle docs to ETH-first Validator Onboarding https://docs.ssv.network/stakers/validators/validator-onboarding docs/stakers/validators/validator-onboarding.md Replace SSV funding examples with ETH examples -ETH Clusters & Migration Update all cluster lifecycle docs to ETH-first Creating a New Validator https://docs.ssv.network/stakers/validator-management/creating-a-new-validator docs/stakers/validator-management/creating-a-new-validator.md Update validator creation flow for ETH clusters -ETH Clusters & Migration Update all cluster lifecycle docs to ETH-first Distributing a Validator https://docs.ssv.network/stakers/validator-management/distributing-a-validator docs/stakers/validator-management/distributing-a-validator.md Update distribution process for ETH clusters -ETH Clusters & Migration Update all cluster lifecycle docs to ETH-first Cluster Balance https://docs.ssv.network/stakers/clusters/cluster-balance docs/stakers/clusters/cluster-balance.md Update balance calculations for ETH-first approach -ETH Clusters & Migration Update all cluster lifecycle docs to ETH-first Depositing SSV https://docs.ssv.network/stakers/cluster-management/depositing-ssv docs/stakers/cluster-management/depositing-ssv.md May need to rename to reflect ETH deposits too -ETH Clusters & Migration Update all cluster lifecycle docs to ETH-first Payments https://docs.ssv.network/learn/protocol-overview/tokenomics/payments docs/learn/protocol-overview/tokenomics/payments.md Update payment mechanisms for ETH clusters -ETH Clusters & Migration Add explicit one-way migration warning (SSV → ETH cannot revert) Cluster Management Overview https://docs.ssv.network/stakers/cluster-management docs/stakers/cluster-management/README.md Add prominent warning banner -ETH Clusters & Migration Add explicit one-way migration warning (SSV → ETH cannot revert) Cluster Balance https://docs.ssv.network/stakers/clusters/cluster-balance docs/stakers/clusters/cluster-balance.md Add warning in relevant sections -ETH Clusters & Migration Add explicit one-way migration warning (SSV → ETH cannot revert) Migration Guide https://docs.ssv.network/stakers/cluster-management/migrating-to-eth-clusters docs/stakers/cluster-management/migrating-to-eth-clusters.md NEW PAGE - Create dedicated migration guide -ETH Clusters & Migration Document migrateClusterToETH() flow step-by-step Migration Guide https://docs.ssv.network/stakers/cluster-management/migrating-to-eth-clusters docs/stakers/cluster-management/migrating-to-eth-clusters.md NEW PAGE - Step-by-step migration process -ETH Clusters & Migration Document migrateClusterToETH() flow step-by-step SSVNetwork Smart Contract https://docs.ssv.network/developers/smart-contracts/ssvnetwork docs/developers/smart-contracts/ssvnetwork.md Add migrateClusterToETH function documentation -ETH Clusters & Migration Document migrateClusterToETH() flow step-by-step Cluster Module SDK https://docs.ssv.network/developers/SSV-SDK/module-reference/cluster-module docs/developers/SSV-SDK/module-reference/cluster-module.md Add SDK method for migration -ETH Clusters & Migration Add ETH funding + runway examples (remove SSV runway /flow ) Validator Onboarding https://docs.ssv.network/stakers/validators/validator-onboarding docs/stakers/validators/validator-onboarding.md Replace funding examples with ETH-based calculations -ETH Clusters & Migration Add ETH funding + runway examples (remove SSV runway /flow ) Cluster Balance https://docs.ssv.network/stakers/clusters/cluster-balance docs/stakers/clusters/cluster-balance.md Add ETH runway calculation examples -ETH Clusters & Migration Add ETH funding + runway examples (remove SSV runway /flow ) Staking Services Integration https://docs.ssv.network/developers/integration-guides/staking-services docs/developers/integration-guides/staking-services.md Update integration examples for ETH funding -ETH Clusters & Migration Add ETH funding + runway examples (remove SSV runway /flow ) Staking Pools - Initialization https://docs.ssv.network/developers/integration-guides/staking-pools/initialization-stage docs/developers/integration-guides/staking-pools/initialization-stage.md Update pool initialization for ETH clusters -ETH Clusters & Migration Clearly mark SSV clusters as legacy and transitional Cluster Management Overview https://docs.ssv.network/stakers/cluster-management docs/stakers/cluster-management/README.md Add legacy label and migration path -ETH Clusters & Migration Clearly mark SSV clusters as legacy and transitional Clusters Overview https://docs.ssv.network/stakers/clusters docs/stakers/clusters/README.md Add legacy label and migration path -ETH Clusters & Migration Clearly mark SSV clusters as legacy and transitional Validator Onboarding https://docs.ssv.network/stakers/validators/validator-onboarding docs/stakers/validators/validator-onboarding.md Distinguish between legacy SSV and new ETH clusters -ETH Clusters & Migration Clearly mark SSV clusters as legacy and transitional Payments https://docs.ssv.network/learn/protocol-overview/tokenomics/payments docs/learn/protocol-overview/tokenomics/payments.md Mark SSV payment model as legacy -Operator ETH Fees & Rules Update operator onboarding docs for ETH-only operators Operator Onboarding https://docs.ssv.network/operators/operator-onboarding docs/operators/operator-onboarding/README.md Add ETH-only operator registration flow -Operator ETH Fees & Rules Update operator onboarding docs for ETH-only operators Operator Registration https://docs.ssv.network/operators/operator-management/registration docs/operators/operator-management/registration.md Update registration for ETH-only operators -Operator ETH Fees & Rules Update operator onboarding docs for ETH-only operators Operators Overview https://docs.ssv.network/operators docs/operators/README.md Introduce ETH-only operator concept -Operator ETH Fees & Rules Clarify that ETH and SSV earnings are separate balances Withdrawing Earnings https://docs.ssv.network/operators/operator-management/withdrawing-earnings docs/operators/operator-management/withdrawing-earnings.md Update to show separate ETH/SSV balance withdrawals -Operator ETH Fees & Rules Clarify that ETH and SSV earnings are separate balances Operator Onboarding https://docs.ssv.network/operators/operator-onboarding docs/operators/operator-onboarding/README.md Explain dual balance system -Operator ETH Fees & Rules Clarify that ETH and SSV earnings are separate balances Fees https://docs.ssv.network/learn/protocol-overview/tokenomics/fees docs/learn/protocol-overview/tokenomics/fees.md Document separate balance tracking -Operator ETH Fees & Rules Explicitly state that ETH-only operators cannot receive SSV fees Operator Onboarding https://docs.ssv.network/operators/operator-onboarding docs/operators/operator-onboarding/README.md Add clear statement about fee limitations -Operator ETH Fees & Rules Explicitly state that ETH-only operators cannot receive SSV fees Operator Registration https://docs.ssv.network/operators/operator-management/registration docs/operators/operator-management/registration.md Clarify ETH-only operator constraints -Operator ETH Fees & Rules Explicitly state that ETH-only operators cannot receive SSV fees Fees https://docs.ssv.network/learn/protocol-overview/tokenomics/fees docs/learn/protocol-overview/tokenomics/fees.md Document operator type fee restrictions -Effective Balance (vUnits) Accounting Add a new conceptual doc explaining vUnits and EB weighting vUnits and Effective Balance https://docs.ssv.network/learn/protocol-overview/tokenomics/effective-balance docs/learn/protocol-overview/tokenomics/effective-balance.md NEW PAGE - Complete EB and vUnits explanation -Effective Balance (vUnits) Accounting Add a new conceptual doc explaining vUnits and EB weighting Tokenomics Overview https://docs.ssv.network/learn/protocol-overview/tokenomics docs/learn/protocol-overview/tokenomics/README.md Add link to new EB page -Effective Balance (vUnits) Accounting Add a new conceptual doc explaining vUnits and EB weighting Glossary https://docs.ssv.network/learn/glossary docs/learn/glossary.md Add vUnits and Effective Balance definitions -Effective Balance (vUnits) Accounting Document EB vs validatorCount differences (ETH vs SSV clusters) vUnits and Effective Balance https://docs.ssv.network/learn/protocol-overview/tokenomics/effective-balance docs/learn/protocol-overview/tokenomics/effective-balance.md NEW PAGE - Explain accounting differences -Effective Balance (vUnits) Accounting Document EB vs validatorCount differences (ETH vs SSV clusters) Cluster Balance https://docs.ssv.network/stakers/clusters/cluster-balance docs/stakers/clusters/cluster-balance.md Update formulas to reflect EB vs validator count -Effective Balance (vUnits) Accounting Document EB vs validatorCount differences (ETH vs SSV clusters) Payments https://docs.ssv.network/learn/protocol-overview/tokenomics/payments docs/learn/protocol-overview/tokenomics/payments.md Update payment calculations for EB -Effective Balance (vUnits) Accounting Explain fallback behavior when EB data is missing (32 ETH default) vUnits and Effective Balance https://docs.ssv.network/learn/protocol-overview/tokenomics/effective-balance docs/learn/protocol-overview/tokenomics/effective-balance.md NEW PAGE - Document fallback mechanism -Effective Balance (vUnits) Accounting Explain fallback behavior when EB data is missing (32 ETH default) Cluster Balance https://docs.ssv.network/stakers/clusters/cluster-balance docs/stakers/clusters/cluster-balance.md Explain default EB assumptions -Effective Balance (vUnits) Accounting Add examples showing fee scaling with EB (32 vs 64 vs 2048 ETH) vUnits and Effective Balance https://docs.ssv.network/learn/protocol-overview/tokenomics/effective-balance docs/learn/protocol-overview/tokenomics/effective-balance.md NEW PAGE - Add comprehensive examples -Effective Balance (vUnits) Accounting Add examples showing fee scaling with EB (32 vs 64 vs 2048 ETH) Fees https://docs.ssv.network/learn/protocol-overview/tokenomics/fees docs/learn/protocol-overview/tokenomics/fees.md Add EB-scaled fee examples -Effective Balance (vUnits) Accounting Add examples showing fee scaling with EB (32 vs 64 vs 2048 ETH) Validator Onboarding https://docs.ssv.network/stakers/validators/validator-onboarding docs/stakers/validators/validator-onboarding.md Update funding examples with EB scaling -Effective Balance (vUnits) Accounting Update any fee math references that assume 1 validator = 32 ETH Validator Onboarding https://docs.ssv.network/stakers/validators/validator-onboarding docs/stakers/validators/validator-onboarding.md Replace fixed 32 ETH assumptions -Effective Balance (vUnits) Accounting Update any fee math references that assume 1 validator = 32 ETH Cluster Balance https://docs.ssv.network/stakers/clusters/cluster-balance docs/stakers/clusters/cluster-balance.md Update formulas to use EB -Effective Balance (vUnits) Accounting Update any fee math references that assume 1 validator = 32 ETH Liquidations https://docs.ssv.network/learn/protocol-overview/tokenomics/liquidations docs/learn/protocol-overview/tokenomics/liquidations.md Update liquidation math for EB -Effective Balance (vUnits) Accounting Update any fee math references that assume 1 validator = 32 ETH Fees https://docs.ssv.network/learn/protocol-overview/tokenomics/fees docs/learn/protocol-overview/tokenomics/fees.md Update fee examples for EB -Effective Balance (vUnits) Accounting Update any fee math references that assume 1 validator = 32 ETH Staking Services Integration https://docs.ssv.network/developers/integration-guides/staking-services docs/developers/integration-guides/staking-services.md Update integration code for EB -EB Oracle System (v1) Add EB Oracle architecture overview EB Oracle System https://docs.ssv.network/learn/protocol-overview/eb-oracle-system docs/learn/protocol-overview/eb-oracle-system.md NEW PAGE - Complete oracle architecture -EB Oracle System (v1) Add EB Oracle architecture overview Protocol Overview https://docs.ssv.network/learn/protocol-overview docs/learn/protocol-overview/README.md Add link to oracle system -EB Oracle System (v1) Add EB Oracle architecture overview Tech Overview https://docs.ssv.network/learn/introduction/tech-overview docs/learn/introduction/tech-overview.md Add oracle system to tech stack -EB Oracle System (v1) Document commitRoot → updateClusterBalance lifecycle EB Oracle System https://docs.ssv.network/learn/protocol-overview/eb-oracle-system docs/learn/protocol-overview/eb-oracle-system.md NEW PAGE - Document oracle lifecycle -EB Oracle System (v1) Document commitRoot → updateClusterBalance lifecycle SSVNetwork Smart Contract https://docs.ssv.network/developers/smart-contracts/ssvnetwork docs/developers/smart-contracts/ssvnetwork.md Add oracle method documentation -EB Oracle System (v1) Document commitRoot → updateClusterBalance lifecycle Cluster Balance https://docs.ssv.network/stakers/clusters/cluster-balance docs/stakers/clusters/cluster-balance.md Explain oracle's role in balance updates -EB Oracle System (v1) Explain Merkle root + proof verification in simple terms EB Oracle System https://docs.ssv.network/learn/protocol-overview/eb-oracle-system docs/learn/protocol-overview/eb-oracle-system.md NEW PAGE - Add simple Merkle explanation -EB Oracle System (v1) Explain Merkle root + proof verification in simple terms Tech Overview https://docs.ssv.network/learn/introduction/tech-overview docs/learn/introduction/tech-overview.md Add Merkle verification overview -EB Oracle System (v1) 4 fixed oracles 75% quorum EB Oracle System https://docs.ssv.network/learn/protocol-overview/eb-oracle-system docs/learn/protocol-overview/eb-oracle-system.md NEW PAGE - Document v1 limitations -EB Oracle System (v1) 4 fixed oracles 75% quorum Governance https://docs.ssv.network/learn/introduction/governance docs/learn/introduction/governance.md Add oracle governance parameters -EB Oracle System (v1) Document oracle update frequency EB Oracle System https://docs.ssv.network/learn/protocol-overview/eb-oracle-system docs/learn/protocol-overview/eb-oracle-system.md NEW PAGE - Document update cadence -EB Oracle System (v1) Document oracle update frequency Tech Overview https://docs.ssv.network/learn/introduction/tech-overview docs/learn/introduction/tech-overview.md Add oracle timing information -SSV Staking (cSSV + ETH Rewards) Add full staking user journey (stake → earn → claim → unstake) SSV Staking Guide https://docs.ssv.network/stakers/ssv-staking docs/stakers/ssv-staking/README.md NEW PAGE - Complete staking overview -SSV Staking (cSSV + ETH Rewards) Add full staking user journey (stake → earn → claim → unstake) Stake SSV https://docs.ssv.network/stakers/ssv-staking/stake-ssv docs/stakers/ssv-staking/stake-ssv.md NEW PAGE - How to stake -SSV Staking (cSSV + ETH Rewards) Add full staking user journey (stake → earn → claim → unstake) Claim Rewards https://docs.ssv.network/stakers/ssv-staking/claim-rewards docs/stakers/ssv-staking/claim-rewards.md NEW PAGE - How to claim rewards -SSV Staking (cSSV + ETH Rewards) Add full staking user journey (stake → earn → claim → unstake) Unstake SSV https://docs.ssv.network/stakers/ssv-staking/unstake-ssv docs/stakers/ssv-staking/unstake-ssv.md NEW PAGE - How to unstake -SSV Staking (cSSV + ETH Rewards) Add full staking user journey (stake → earn → claim → unstake) SSV Token https://docs.ssv.network/learn/introduction/ssv-token docs/learn/introduction/ssv-token.md Add staking as new utility -SSV Staking (cSSV + ETH Rewards) Explain cSSV non-rebasing index-based reward model SSV Staking Guide https://docs.ssv.network/stakers/ssv-staking docs/stakers/ssv-staking/README.md NEW PAGE - Explain cSSV mechanics -SSV Staking (cSSV + ETH Rewards) Explain cSSV non-rebasing index-based reward model SSV Token https://docs.ssv.network/learn/introduction/ssv-token docs/learn/introduction/ssv-token.md Add cSSV explanation -SSV Staking (cSSV + ETH Rewards) Explain cSSV non-rebasing index-based reward model Tokenomics Overview https://docs.ssv.network/learn/protocol-overview/tokenomics docs/learn/protocol-overview/tokenomics/README.md Add staking tokenomics -SSV Staking (cSSV + ETH Rewards) Explain cSSV non-rebasing index-based reward model Glossary https://docs.ssv.network/learn/glossary docs/learn/glossary.md Add cSSV definition -SSV Staking (cSSV + ETH Rewards) Document ETH reward flow from clusters → staking contract SSV Staking Guide https://docs.ssv.network/stakers/ssv-staking docs/stakers/ssv-staking/README.md NEW PAGE - Document reward flow -SSV Staking (cSSV + ETH Rewards) Document ETH reward flow from clusters → staking contract Validator Rewards https://docs.ssv.network/stakers/validators/validator-rewards docs/stakers/validators/validator-rewards.md Add ETH reward distribution info -SSV Staking (cSSV + ETH Rewards) Document ETH reward flow from clusters → staking contract Tokenomics Overview https://docs.ssv.network/learn/protocol-overview/tokenomics docs/learn/protocol-overview/tokenomics/README.md Update reward flow diagram -SSV Staking (cSSV + ETH Rewards) Add unstaking cooldown explanation and its implications Unstake SSV https://docs.ssv.network/stakers/ssv-staking/unstake-ssv docs/stakers/ssv-staking/unstake-ssv.md NEW PAGE - Explain cooldown period -SSV Staking (cSSV + ETH Rewards) Add unstaking cooldown explanation and its implications SSV Staking Guide https://docs.ssv.network/stakers/ssv-staking docs/stakers/ssv-staking/README.md NEW PAGE - Document cooldown implications -SSV Staking (cSSV + ETH Rewards) Add unstaking cooldown explanation and its implications Glossary https://docs.ssv.network/learn/glossary docs/learn/glossary.md Add cooldown definition -SSV Staking (cSSV + ETH Rewards) Clarify that rewards stop accruing during cooldown Unstake SSV https://docs.ssv.network/stakers/ssv-staking/unstake-ssv docs/stakers/ssv-staking/unstake-ssv.md NEW PAGE - Add reward cessation warning -SSV Staking (cSSV + ETH Rewards) Clarify that rewards stop accruing during cooldown SSV Staking Guide https://docs.ssv.network/stakers/ssv-staking docs/stakers/ssv-staking/README.md NEW PAGE - Explain reward behavior -Oracle Delegation (Auto-split v1) Document automatic stake-weight splitting across all oracles Oracle Delegation https://docs.ssv.network/learn/protocol-overview/oracle-delegation docs/learn/protocol-overview/oracle-delegation.md NEW PAGE - Explain auto-delegation -Oracle Delegation (Auto-split v1) Document automatic stake-weight splitting across all oracles SSV Staking Guide https://docs.ssv.network/stakers/ssv-staking docs/stakers/ssv-staking/README.md NEW PAGE - Add delegation info -Oracle Delegation (Auto-split v1) Document automatic stake-weight splitting across all oracles Governance https://docs.ssv.network/learn/introduction/governance docs/learn/introduction/governance.md Add oracle voting mechanism -Oracle Delegation (Auto-split v1) Explicitly state that users do not choose oracles in v1 Oracle Delegation https://docs.ssv.network/learn/protocol-overview/oracle-delegation docs/learn/protocol-overview/oracle-delegation.md NEW PAGE - Clarify v1 constraints -Oracle Delegation (Auto-split v1) Explicitly state that users do not choose oracles in v1 SSV Staking Guide https://docs.ssv.network/stakers/ssv-staking docs/stakers/ssv-staking/README.md NEW PAGE - Set user expectations -Oracle Delegation (Auto-split v1) Explain voting weight behavior during unstake cooldown Oracle Delegation https://docs.ssv.network/learn/protocol-overview/oracle-delegation docs/learn/protocol-overview/oracle-delegation.md NEW PAGE - Document cooldown voting weight -Oracle Delegation (Auto-split v1) Explain voting weight behavior during unstake cooldown Unstake SSV https://docs.ssv.network/stakers/ssv-staking/unstake-ssv docs/stakers/ssv-staking/unstake-ssv.md NEW PAGE - Add voting weight info -Oracle Delegation (Auto-split v1) Explain voting weight behavior during unstake cooldown Governance https://docs.ssv.network/learn/introduction/governance docs/learn/introduction/governance.md Update voting weight rules -Oracle Delegation (Auto-split v1) Set expectations for v2 (manual delegation variable oracles) Oracle Delegation https://docs.ssv.network/learn/protocol-overview/oracle-delegation docs/learn/protocol-overview/oracle-delegation.md NEW PAGE - Roadmap to v2 -Oracle Delegation (Auto-split v1) Set expectations for v2 (manual delegation variable oracles) EB Oracle System https://docs.ssv.network/learn/protocol-overview/eb-oracle-system docs/learn/protocol-overview/eb-oracle-system.md NEW PAGE - Mention v2 improvements -Liquidation Behavior Document ETH cluster liquidation (EB-weighted logic) Liquidations https://docs.ssv.network/learn/protocol-overview/tokenomics/liquidations docs/learn/protocol-overview/tokenomics/liquidations.md Add ETH cluster liquidation section -Liquidation Behavior Document ETH cluster liquidation (EB-weighted logic) Liquidator Bot https://docs.ssv.network/operators/liquidator-bot docs/operators/liquidator-bot/README.md Update for EB-weighted liquidations -Liquidation Behavior Document ETH cluster liquidation (EB-weighted logic) Cluster Balance https://docs.ssv.network/stakers/clusters/cluster-balance docs/stakers/clusters/cluster-balance.md Update liquidation thresholds for EB -Liquidation Behavior Document legacy SSV cluster liquidation separately Liquidations https://docs.ssv.network/learn/protocol-overview/tokenomics/liquidations docs/learn/protocol-overview/tokenomics/liquidations.md Add legacy SSV liquidation section -Liquidation Behavior Document legacy SSV cluster liquidation separately Liquidator Bot https://docs.ssv.network/operators/liquidator-bot docs/operators/liquidator-bot/README.md Separate legacy liquidation logic -Liquidation Behavior Add warnings about calling the wrong liquidation path Liquidations https://docs.ssv.network/learn/protocol-overview/tokenomics/liquidations docs/learn/protocol-overview/tokenomics/liquidations.md Add error prevention warnings -Liquidation Behavior Add warnings about calling the wrong liquidation path Liquidator Bot https://docs.ssv.network/operators/liquidator-bot docs/operators/liquidator-bot/README.md Add path selection guidance -Liquidation Behavior Add warnings about calling the wrong liquidation path SSVNetwork Smart Contract https://docs.ssv.network/developers/smart-contracts/ssvnetwork docs/developers/smart-contracts/ssvnetwork.md Document liquidation method differences -Liquidation Behavior Update any liquidation thresholds/examples to be EB-aware Liquidations https://docs.ssv.network/learn/protocol-overview/tokenomics/liquidations docs/learn/protocol-overview/tokenomics/liquidations.md Replace validator count with EB -Liquidation Behavior Update any liquidation thresholds/examples to be EB-aware Cluster Balance https://docs.ssv.network/stakers/clusters/cluster-balance docs/stakers/clusters/cluster-balance.md Update threshold calculations -Liquidation Behavior Update any liquidation thresholds/examples to be EB-aware Reactivation https://docs.ssv.network/stakers/clusters/reactivation docs/stakers/clusters/reactivation.md Update reactivation math for EB -Liquidation Behavior Update any liquidation thresholds/examples to be EB-aware Re-activating a Cluster https://docs.ssv.network/stakers/cluster-management/re-activating-a-cluster docs/stakers/cluster-management/re-activating-a-cluster.md Update reactivation guide for EB -Incentivized Mainnet (IM) Alignment Update IM docs to state ETH clusters only are eligible Incentivized Mainnet https://docs.ssv.network/learn/protocol-overview/incentivized-mainnet docs/learn/protocol-overview/incentivized-mainnet.md NEW PAGE - IM program overview -Incentivized Mainnet (IM) Alignment Update IM docs to state ETH clusters only are eligible Network Overview https://docs.ssv.network/learn/introduction/network-overview docs/learn/introduction/network-overview.md Add IM program mention -Incentivized Mainnet (IM) Alignment Update IM docs to state ETH clusters only are eligible Operators Overview https://docs.ssv.network/operators docs/operators/README.md Add IM eligibility info -Incentivized Mainnet (IM) Alignment Remove all references to off-chain EB fee deductions Fees https://docs.ssv.network/learn/protocol-overview/tokenomics/fees docs/learn/protocol-overview/tokenomics/fees.md Remove off-chain deduction references -Incentivized Mainnet (IM) Alignment Remove all references to off-chain EB fee deductions Operator Onboarding https://docs.ssv.network/operators/operator-onboarding docs/operators/operator-onboarding/README.md Remove off-chain deduction references -Incentivized Mainnet (IM) Alignment Remove all references to off-chain EB fee deductions Payments https://docs.ssv.network/learn/protocol-overview/tokenomics/payments docs/learn/protocol-overview/tokenomics/payments.md Remove off-chain deduction references -Incentivized Mainnet (IM) Alignment Document IM as a migration incentive not a permanent system Incentivized Mainnet https://docs.ssv.network/learn/protocol-overview/incentivized-mainnet docs/learn/protocol-overview/incentivized-mainnet.md NEW PAGE - Clarify temporary nature -Incentivized Mainnet (IM) Alignment Document IM as a migration incentive not a permanent system Governance https://docs.ssv.network/learn/introduction/governance docs/learn/introduction/governance.md Add IM program context -Incentivized Mainnet (IM) Alignment Add guidance for operators losing IM rewards on SSV clusters Incentivized Mainnet https://docs.ssv.network/learn/protocol-overview/incentivized-mainnet docs/learn/protocol-overview/incentivized-mainnet.md NEW PAGE - Migration guidance for operators -Incentivized Mainnet (IM) Alignment Add guidance for operators losing IM rewards on SSV clusters Operators Overview https://docs.ssv.network/operators docs/operators/README.md Add IM transition guidance -Incentivized Mainnet (IM) Alignment Add guidance for operators losing IM rewards on SSV clusters Operator Onboarding https://docs.ssv.network/operators/operator-onboarding docs/operators/operator-onboarding/README.md Add IM impact on operators -DAO & Governance Parameters Update governance docs with new ETH-related params (DEFAULT_OPERATOR_ETH_FEE MINIMAL_OPERATOR_ETH_FEE RewardsPeriod) Governance https://docs.ssv.network/learn/introduction/governance docs/learn/introduction/governance.md Add all new ETH parameters -DAO & Governance Parameters Update governance docs with new ETH-related params (DEFAULT_OPERATOR_ETH_FEE MINIMAL_OPERATOR_ETH_FEE RewardsPeriod) SSVNetworkViews Smart Contract https://docs.ssv.network/developers/smart-contracts/ssvnetworkviews docs/developers/smart-contracts/ssvnetworkviews.md Add getter methods for new parameters -DAO & Governance Parameters Update governance docs with new ETH-related params (DEFAULT_OPERATOR_ETH_FEE MINIMAL_OPERATOR_ETH_FEE RewardsPeriod) SSV Subgraph Examples https://docs.ssv.network/developers/tools/ssv-subgraph/subgraph-examples docs/developers/tools/ssv-subgraph/subgraph-examples.md Add subgraph queries for new params -DAO & Governance Parameters Explain how these parameters affect staker APR and operator revenue Governance https://docs.ssv.network/learn/introduction/governance docs/learn/introduction/governance.md Add impact analysis -DAO & Governance Parameters Explain how these parameters affect staker APR and operator revenue Fees https://docs.ssv.network/learn/protocol-overview/tokenomics/fees docs/learn/protocol-overview/tokenomics/fees.md Show parameter impact on fees -DAO & Governance Parameters Explain how these parameters affect staker APR and operator revenue SSV Staking Guide https://docs.ssv.network/stakers/ssv-staking docs/stakers/ssv-staking/README.md NEW PAGE - Explain APR calculation -DAO & Governance Parameters Add references to where these values are read on-chain SSVNetworkViews Smart Contract https://docs.ssv.network/developers/smart-contracts/ssvnetworkviews docs/developers/smart-contracts/ssvnetworkviews.md Add code examples for reading params -DAO & Governance Parameters Add references to where these values are read on-chain SSV Subgraph Examples https://docs.ssv.network/developers/tools/ssv-subgraph/subgraph-examples docs/developers/tools/ssv-subgraph/subgraph-examples.md Add GraphQL queries -DAO & Governance Parameters Add references to where these values are read on-chain Governance https://docs.ssv.network/learn/introduction/governance docs/learn/introduction/governance.md Link to on-chain references \ No newline at end of file diff --git a/SSV-Staking-context.doc b/SSV-Staking-context.doc deleted file mode 100644 index e69de29..0000000 diff --git a/SSV_Staking-design-info.doc b/SSV_Staking-design-info.doc deleted file mode 100644 index ab262aa..0000000 --- a/SSV_Staking-design-info.doc +++ /dev/null @@ -1,318 +0,0 @@ -SSV Staking v1: ETH Fees, Effective Balance & Staking Rewards -Summary -SSV Network is transitioning from SSV token-based fees to native ETH fees. This enables SSV to become an ETH Accrual Token - where real ETH revenue from network activity flows directly to SSV stakers. - -Why this matters: - -For stakers: Stake SSV, earn ETH. Network fees flow to SSV stakers proportionally. -For clusters & operators: Pay and earn fees in ETH. Simpler accounting, no SSV token management. -For the protocol: Sustainable economics tied to real usage. As the network grows, more fees flow to stakers. - -Post-Pectra compatibility: Ethereum's Pectra upgrade allows validators to have variable effective balances (32-2048 ETH). The new accounting model ensures fees scale proportionally to actual staked ETH, not just validator count. - - -Overview: Three Core Changes -Change -What -Why -ETH Clusters -Clusters pay fees in ETH instead of SSV -Enables ETH revenue to flow to stakers -Effective Balance Accounting -Fees weighted by actual validator ETH, not validator count -Fair fee distribution for variable-balance validators -SSV Staking -Stake SSV to earn ETH network fees -Creates real yield for SSV holders - - -These changes work together: ETH Clusters generate ETH fees, Effective Balance ensures fair accounting, and SSV Staking distributes the fees to token holders. - - -1. ETH Clusters -What Changes -Before: Clusters deposited SSV tokens to pay operator and network fees. - -After: Clusters deposit ETH to pay fees. SSV clusters can migrate to ETH clusters. -Migration Path -New clusters: Automatically use ETH payments -Existing clusters: Can migrate via migrateClusterToETH() -Deposit ETH to cover fees -Receive refund of SSV balance -One-way migration (cannot revert to SSV) -Impact on Users -Role -Impact -Cluster owners -Deposit ETH instead of SSV. SSV clusters can continue running until liquidated or migrated. -Operators -Can serve both SSV and ETH clusters during transition. Earnings accumulate separately. -DAO -Sets upgrade parameters such as operator migration deadline - -Operator ETH Migration -Operators supporting the new system: - -New operators: Start as ETH-only -Existing operators: ETH fee set to 0 if SSV fee was 0, otherwise set to DAO default -Fee changes: Use `declareOperatorFee()` and `executeOperatorFee()` to adjust fees - - -2. Effective Balance Accounting -The Problem -Currently, all validators are treated equally for fee calculations. But post-Pectra, validators can hold 32-2048 ETH. A validator with 64 ETH generates ~2x the rewards of a 32 ETH validator, so fees should scale accordingly. -The Solution: vUnits -vUnits (virtual units) weight fees by actual staked ETH: - -vUnits = (effectiveBalance / 32 ETH) x 100 - -Validator Balance -vUnits -32 ETH -100 -64 ETH -200 -2048 ETH -6400 - - -Fee calculation by cluster type -ETH Clusters: Fees calculated using vUnits (proportional to actual effective balance) -SSV Clusters: Fees calculated using legacy method (1 validator = 32 ETH, regardless of actual EB) - -EB reporting by oracles happens for all clusters regardless of type. - -How Effective Balance is Reported -Since on-chain contracts cannot read beacon chain state directly, an oracle system reports effective balances. - -Fallback behavior: A cluster's EB is the sum of its validators' EBs (minimum 32 ETH per validator). If no EB data exists, the vUnit amount defaults to validatorCount x 100. -Oracle System (v1) -Aspect -v1 Implementation -Oracle count -4 permissioned oracles -Quorum -75% weight required to accept a commitment -Weight distribution -Equal weight across all oracles -Update frequency -Configurable epoch intervals - - -The oracle commits happen in phases: - -Oracle commits root: Calls commitRoot() with Merkle root. Once 75% threshold reached, emits RootCommitted. -Cluster update: Anyone calls updateClusterBalance() with proof. Updates vUnits and fee accounting. Emits ClusterBalanceUpdated. - - - - -3. SSV Staking -How It Works -Stake SSV -> Receive cSSV (transferable ERC-20 token) -Earn ETH -> Network fees flow to stakers proportionally -Claim anytime -> Withdraw accrued ETH rewards -Unstake -> 7-day cooldown, then withdraw SSV + remaining rewards -Token Mechanics -cSSV is a non-rebasing token using index-based reward tracking: - -Your cSSV balance stays constant -ETH rewards accrue separately and can be claimed anytime -Full DeFi composability (can use cSSV in other protocols) -Based on synthetix StakingRewards.sol -Reward Flow -Cluster pays ETH fees - | - v -Network fee portion - | - v -SSV Staking contract - | - v -Distributed to cSSV holders - -Oracle Delegation (v1) -When you stake SSV, your weight is automatically split equally across all 4 oracles. This simplified model ensures: - -All stakers participate in oracle consensus -75% quorum required for commitments -No manual delegation needed -Unstaking Process -Step -Duration -Notes -Initiate unstake -Immediate -Weight remains active for oracle voting -Cooldown period -7 days -Rewards stop accruing -Withdraw -After cooldown -Receive SSV + unclaimed ETH - - -The cooldown period exists to maintain protocol stability and prepare for future governance mechanisms. - - -v1 Scope & Limitations -This is an MVP release focused on core functionality. Known limitations: - -v1 (Current) -v2 (Future) -4 fixed oracles -Variable number of oracles -Auto-split delegation -Staker-chosen delegation -Equal oracle rewards -Performance-based rewards -Basic stake/unstake -Entry/exit queues -Separate liquidators -Oracles handle liquidations - - - -Key Safety Properties -Migration is one-way: Once converted to ETH, clusters/operators cannot revert to SSV -Backward compatible: Legacy SSV clusters continue working until migrated or liquidated -Default accounting: Clusters without EB data assume 32 ETH per validator -Real yield: Staker rewards come from actual network fees collected -Transfer settlement: When cSSV moves, accrued rewards stay with the original holder - - -Timeline & Migration -Contract upgrade: New functionality deployed -Migration period: Operators can set initial ETH fees -Cluster migration: Owners migrate clusters to ETH -Staking launch: SSV staking activated (requires DAO approval) - - - -FAQ -Q: What happens to my SSV when I migrate my cluster? A: Your SSV balance is automatically refunded to you during the migration to ETH process. - -Q: What happens to a new validator's effective balance before oracles report it? A: New validators default to 32 ETH (100 vUnits) until the oracle updates the cluster's effective balance. - -Q: Can operators earn both SSV and ETH? A: Yes, during the transition period operators can serve both cluster types and withdraw earnings separately. - -Q: How much can I earn staking SSV? A: Rewards depend on: total ETH staked through SSV, network fee rate, and your share of staked SSV. See the SSV Staking Calculator for estimates. - -Q: Why is there a 7-day unstaking cooldown? A: The cooldown maintains oracle voting stability and prepares the system for future governance where staked SSV may serve as protocol backstop. - -Q: What if the oracles report incorrect data? A: Merkle proofs ensure only valid data is accepted. Any submission not matching the committed root is rejected. The 75% quorum prevents any single oracle from manipulating data. - - - - - - - -Appendix: Technical Details -Contract Changes -Dual-Currency Storage Model -Operators and clusters now have parallel storage for SSV and ETH: - -Component -SSV Storage -ETH Storage -Operator fee -fee -ethFee -Operator snapshot -snapshot -ethSnapshot -Validator count -validatorCount -ethValidatorCount -Cluster data -s.clusters[hash] -s.ethClusters[hash] - - -New Functions -Migration: - -migrateClusterToETH() - Requires ETH deposit via msg.value, refunds SSV balance, updates DAO accounting - -Operator Withdrawals: - -withdrawOperatorEarnings() - Withdraw ETH earnings -withdrawOperatorEarningsSSV() - Withdraw SSV earnings -withdrawAllVersionOperatorEarnings() - Withdraw both ETH and SSV in one transaction - -Effective Balance: - -commitRoot(merkleRoot, blockNum) - Oracle commits Merkle root of all cluster EBs -updateClusterBalance(proof) - Anyone can update a cluster's EB with Merkle proof - - - -Liquidation: - -liquidate() - For ETH clusters (uses EB-weighted accounting) -liquidateSSV() - For SSV clusters (legacy behavior) -New Events -Event -Description -ClusterMigratedToETH -Cluster migrated from SSV to ETH -RootCommitted -Oracle Merkle root accepted (75% quorum reached) -ClusterBalanceUpdated -Cluster EB updated via Merkle proof - -Operator Rules -New operators: ETH-only, cannot receive SSV payments -Legacy operators: Must migrate to ETH before changing fees (increase/decrease) -Migration period: Operators can set ETH fee up to 2x default (one-time, bypasses 10% limit) -After migration period: Normal 10% fee increase limit applies -Cluster Operations -ETH clusters use native ETH via msg.value for register, deposit, withdraw, reactivate -Migration updates DAO accounting: decrements SSV validator count, increments ETH validator count - -New DAO parameters -Name -Description -DEFAULT_OPERATOR_ETH_FEE -Default ETH fee for operators -MINIMAL_OPERATOR_ETH_FEE -Minimal ETH fee for operators -RewardsPeriod (SSV Staking) -Rewards distribution period. Regulates the speed of rewards distribution. - - - - -Oracle Client Overview -The oracle client is an off-chain service that periodically publishes effective balances to the contract. -Core Loop -Fetch config - Get startEpoch and epochInterval -Calculate target epoch - Determine current target epoch based on finalized beacon state -Wait for finalization - Ensure target epoch is finalized -Fetch cluster EBs - Get effective balances for all validators, sum per cluster -Build Merkle root - Deterministic encoding and sorting -Submit commit - Call commitRoot(merkleRoot, blockNum) with retry logic -Optional: Update clusters - Call updateClusterBalance() for each cluster after RootCommitted -Key Components -Component -Responsibility -Scheduler -Triggers loop at fixed intervals -Epoch Manager -Tracks finalized epochs from the beacon node -Data Fetcher -Syncs SSV contract events, fetches validator EBs -Merkle Builder -Builds a deterministic root from cluster data -TX Manager -Handles nonces, gas pricing, and retries - -EB Calculation -For each cluster, the oracle: - -Sums effective balances of all validators in the cluster -Validators with EB ≤ 32 ETH are rounded up to 32 ETH -Encodes as (clusterId, totalEffectiveBalance) in the Merkle tree - From 8e32bf1413ef5caad7687e63bc0e8b50855028a9 Mon Sep 17 00:00:00 2001 From: taylorferran Date: Tue, 13 Jan 2026 09:33:31 +0000 Subject: [PATCH 3/3] Massimo comments --- docs/learn/glossary.md | 23 ++++++++----------- docs/learn/introduction/ssv-token.md | 16 ++++++------- .../protocol-overview/tokenomics/README.md | 4 +++- 3 files changed, 20 insertions(+), 23 deletions(-) diff --git a/docs/learn/glossary.md b/docs/learn/glossary.md index b4e4498..5488098 100644 --- a/docs/learn/glossary.md +++ b/docs/learn/glossary.md @@ -15,7 +15,7 @@ The Beacon Chain is a brand-new, proof-of-stake blockchain that stores and manag The group (usually 4, in compliance with [the fault tolerance rule is accepted](../../../stakers/validators/validator-onboarding)) of non-trusting operators that manage a set (one, or multiple) validator(s). Each operator in the cluster holds a share of the complete validator key, for more information, see [Shamir Secret Sharing](glossary.md#shamir-secret-sharing). -Clusters can be **ETH clusters** (pay fees in ETH) or **SSV clusters** (legacy, pay fees in SSV tokens). +Clusters pay fees in ETH, which is the standard payment method. Older clusters may still pay fees in SSV tokens, but can migrate to ETH-based payments via `migrateClusterToETH()`. ### Consensus Client @@ -68,15 +68,6 @@ In SSV Network, effective balances are reported by oracles and used to calculate An epoch lasts approximately 6.4 minutes, and includes 32 slots. A slot lasts 12 seconds, during and is the time period in which a randomly selected validator proposes a block. -### ETH Cluster - -A cluster that pays operator and network fees in ETH rather than SSV tokens. ETH clusters are the new standard for SSV Network, enabling ETH revenue to flow to SSV stakers. Key features: - -- Pay fees in native ETH -- Fees calculated using effective balance (EB) and vUnits -- Support variable-balance validators post-Pectra -- Can be created directly or migrated from legacy SSV clusters - ### ETH Staking Services Staking services offer a streamlined way to participate in Ethereum staking. When considering an ETH staking service, it is important to understand how these services manage private user keys. Generally, the more centralized (custodial) the service, the higher the security risks and penalties its users may face, especially if the staking service participates in malicious behaviors or goes offline for an extended period. @@ -176,23 +167,27 @@ ssv.network allows access to a decentralized ETH staking infrastructure with SSV * **Staking** – Stake SSV to earn ETH rewards from network fees and support oracle infrastructure * **Governance** – Submitting votes and voting on DAO proposals -* **Fees** – Operators receive fees from managing validators (ETH in new clusters, SSV in legacy clusters) +* **Payments** – The network receives fees paid in ETH by clusters, and the accrued ETH is converted into value for SSV stakers through the staking mechanism * **Grants** – DAO funding for developers and contributors helping to grow the network When you stake SSV, you receive cSSV tokens and earn real ETH yield from network activity, making SSV an "ETH Accrual Token." +### SSV Staker + +An SSV token holder who stakes their SSV tokens to earn ETH rewards from network fees. By staking, they also contribute voting weight to the network's oracle system, which reports validator effective balances to the blockchain. + ### Staker Services or individual ETH holders that wish to leverage SSV/DVT technology for optimal liveness, security and decentralization of their validator(s). Stakers put 32 ETH "at stake" for each validator they want to run. In the PoS consensus mechanism, validators secure the Ethereum blockchain and earn ETH rewards in return for doing so. -"Staker" can also refer to SSV token holders who stake their SSV to earn ETH rewards from network fees. +### SSV Staking + +The process of staking SSV tokens to earn ETH rewards from network fees. SSV Staking also contributes to the network's oracle infrastructure by providing voting weight for effective balance reporting. ### Staking Staking is the contributory action of running a node in a PoS consensus mechanism blockchain. One must 'put at stake' a certain amount of network tokens in order to participate in securing the blockchain by verifying and adding blocks. On Ethereum, the minimum threshold to participate as a validator is 32 ETH. Validators will earn ETH rewards for honestly attesting to and adding blocks. A validator risks decreasing their stake by participating in malicious behaviors or for time spent offline, disconnected from the network. -In the context of SSV Network, staking can also refer to staking SSV tokens to earn ETH rewards from network fees. - ### Total Value Locked (TVL) The total amount of ETH in USD (or other currency) that is “locked-up” by stakers running validators on the blockchain. TVL = (# of validators on the network) x (current price of Ethereum). diff --git a/docs/learn/introduction/ssv-token.md b/docs/learn/introduction/ssv-token.md index 09d0ed7..9128750 100644 --- a/docs/learn/introduction/ssv-token.md +++ b/docs/learn/introduction/ssv-token.md @@ -4,24 +4,24 @@ sidebar_position: 3 # SSV Token -Secret Shared Validator ($SSV) is the native token of [ssv.network](https://ssv.network/). +Secret Shared Validator ($SSV) is the native token of [ssv.network](https://ssv.network/). -$SSV's main use cases are payments, staking, and governance. +$SSV's main use cases are payments, staking, and governance. -* **Payments** - serve as a way for stakers to compensate operators for managing their validators -* **Staking** - stake SSV tokens to earn ETH rewards from network fees and support oracle infrastructure -* **Governance** - a way to participate in ssv.network related decision-making and treasury allocations. +* **Payments** - Serve as a way for stakers to compensate operators for managing their validators (Note: this applies to legacy clusters that pay fees in SSV; newer clusters pay fees in ETH) +* **Staking** - Stake SSV tokens to earn ETH rewards from network fees and support oracle infrastructure +* **Governance** - A way to participate in ssv.network related decision-making and treasury allocations $SSV is playing a pivotal role in the network's ability to harness a community and motivate the right stakeholders to meaningfully contribute to the network. ## SSV as an ETH Accrual Token -SSV Network has evolved to enable the SSV token to accrue real ETH revenue from network activity. Token holders can now stake their SSV to earn ETH rewards generated from network fees paid by clusters. This creates sustainable yield tied directly to network usage and growth. +SSV Network has evolved to enable the SSV token to accrue real ETH revenue from network activity. Token holders can now stake their SSV to earn ETH rewards generated from network fees paid by clusters. Staked SSV also supports the network's oracle infrastructure by providing voting weight for effective balance reporting. **Key benefits:** * Earn real ETH yield from actual network activity -* Support the network's oracle infrastructure through staking -* Participate in securing effective balance reporting for validators +* Support the network's oracle system for validator balance reporting +* Participate in securing decentralized oracle consensus As more validators use SSV Network, more ETH fees flow to SSV stakers, aligning token value with protocol growth. diff --git a/docs/learn/protocol-overview/tokenomics/README.md b/docs/learn/protocol-overview/tokenomics/README.md index b7b2ce6..8ad3b24 100644 --- a/docs/learn/protocol-overview/tokenomics/README.md +++ b/docs/learn/protocol-overview/tokenomics/README.md @@ -28,7 +28,9 @@ Existing SSV token-based clusters continue to operate: SSV token holders can stake their tokens to earn **real ETH yield** generated from network activity. This makes SSV an **ETH Accrual Token** where network fees flow directly to stakers. -When clusters pay fees in ETH, a portion flows into the SSV Staking contract and is distributed proportionally to all stakers. As the network grows and more validators use SSV, more ETH fees are generated, increasing rewards for stakers. +When clusters pay fees in ETH, a portion flows into the SSV Staking contract and is distributed proportionally to all stakers. Staked SSV also supports the network's oracle infrastructure by providing voting weight for effective balance reporting. + +As the network grows and more validators use SSV, more ETH fees are generated, increasing rewards for stakers. Learn more in the [SSV Staking Guide](/stakers/ssv-staking/).