diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 20c383a9f..06c144250 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -91,7 +91,7 @@ having trouble. As always, jump on [discord](https://discord.gg/cyAszAh) if you get stuck. Additionally, -the ["Contributing to Anchor" section](https://anchor-book.sigmaprime.io/contributing.html#contributing-to-anchor) +the ["Contributing" section](https://anchor.sigmaprime.io/contributing) of the Anchor Book provides more details on the setup. ## FAQs diff --git a/README.md b/README.md index 709f799b7..df797f2cd 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ Anchor maintains two permanent branches: Anchor welcomes contributors. If you are looking to contribute, please head to the -[Contributing](https://anchor-book.sigmaprime.io/contributing.html) section +[Contributing](https://anchor.sigmaprime.io/contributing) section of the Anchor book. ## Contact diff --git a/anchor/common/bls_lagrange/src/blsful.rs b/anchor/common/bls_lagrange/src/blsful.rs index 656c5326e..0e6365155 100644 --- a/anchor/common/bls_lagrange/src/blsful.rs +++ b/anchor/common/bls_lagrange/src/blsful.rs @@ -10,7 +10,7 @@ use zeroize::Zeroizing; use crate::Error; -#[derive(Debug, Clone)] +#[derive(Debug, Clone, PartialEq, Eq)] pub struct KeyId { num: u64, identifier: IdentifierPrimeField, diff --git a/anchor/common/bls_lagrange/src/blst.rs b/anchor/common/bls_lagrange/src/blst.rs index ebc2e4f93..52b27ee9a 100644 --- a/anchor/common/bls_lagrange/src/blst.rs +++ b/anchor/common/bls_lagrange/src/blst.rs @@ -12,7 +12,7 @@ use rand::prelude::*; use crate::{Error, random_key}; -#[derive(Debug, Clone)] +#[derive(Debug, Clone, PartialEq, Eq)] pub struct KeyId { num: u64, // note: while blst_scalar is also used for bls keys, the scalars used in key ids are NOT diff --git a/anchor/validator_store/src/lib.rs b/anchor/validator_store/src/lib.rs index d7dead80c..680d45436 100644 --- a/anchor/validator_store/src/lib.rs +++ b/anchor/validator_store/src/lib.rs @@ -166,6 +166,9 @@ impl AnchorValidatorStore { // First, attempt to get the cluster normally if let Some(cluster) = state.clusters().get_by(&validator.cluster_id) { + if cluster.liquidated { + return Err(Error::SpecificError(SpecificError::ClusterLiquidated)); + } return Ok((validator, cluster.clone())); } @@ -745,6 +748,7 @@ pub enum SpecificError { cluster_id: ClusterId, }, KeyShareDecryptionFailed, + ClusterLiquidated, } impl From for SpecificError { @@ -792,12 +796,19 @@ impl ValidatorStore for AnchorValidatorStore { I: FromIterator, F: Fn(DoppelgangerStatus) -> Option, { + let state = self.database.state(); + // Treat all shares as `SigningEnabled` - self.database - .state() + state .shares() .values() .filter_map(|v| filter_func(DoppelgangerStatus::SigningEnabled(v.validator_pubkey))) + .filter(|public_key| { + if let Some(clusters) = state.clusters().get_by(public_key) { + return !clusters.liquidated; + } + false + }) .collect() } diff --git a/docs/docs/pages/cli-keygen.mdx b/docs/docs/pages/cli-keygen.mdx index 5b7354c9a..e2a2da63a 100644 --- a/docs/docs/pages/cli-keygen.mdx +++ b/docs/docs/pages/cli-keygen.mdx @@ -35,5 +35,4 @@ Anchor. anchor keygen --encrypt --output-path /path/to/keys ``` -Anchor will look for the key file inside the directory specific by `--datadir`, unless you -specify it via `--key-file`. +Anchor will look for the key file in the default directory `~/.anchor/{network}`, or the directory specified by `--datadir`. \ No newline at end of file diff --git a/docs/docs/pages/cli-node.mdx b/docs/docs/pages/cli-node.mdx index be8d81162..db7aa9ecc 100644 --- a/docs/docs/pages/cli-node.mdx +++ b/docs/docs/pages/cli-node.mdx @@ -34,7 +34,7 @@ anchor node [OPTIONS] | --- | --- | ---| | `--metrics` | Enable metrics server | Disabled | | `--metrics-address
` | Listen address for metrics server | `127.0.0.1` if `--metrics` is set | -| `--metrics-port ` | Listen port for metrics server | `15000` if `--metrics` is set | +| `--metrics-port ` | Listen port for metrics server | `5164` if `--metrics` is set | #### Network Options diff --git a/docs/docs/pages/development_environment.mdx b/docs/docs/pages/development_environment.mdx index 48d9fff2f..9b20fbd31 100644 --- a/docs/docs/pages/development_environment.mdx +++ b/docs/docs/pages/development_environment.mdx @@ -28,7 +28,7 @@ As with most other Rust projects, Anchor uses `cargo test` for unit and integration tests. For example, to test the `qbft` crate run: ```bash -cd src/qbft +cd anchor/common/qbft cargo test ``` diff --git a/docs/docs/pages/installation.mdx b/docs/docs/pages/installation.mdx index 113166862..fdc168942 100644 --- a/docs/docs/pages/installation.mdx +++ b/docs/docs/pages/installation.mdx @@ -1,9 +1,19 @@ # Anchor Installation Guide -This guide provides step-by-step instructions for installing **Anchor**. +This guide provides step-by-step instructions for installing Anchor. ---- +## Recommended System Requirements + +Anchor itself is a light-weight client when run alone. +However, as Anchor needs to connect to a beacon node and an execution client, this implies that a complete setup will require +the hardware specifications equivalent to running an Ethereum node. + +| Hardware | Hoodi testnet | +|--------|---------| +| CPU | AMD Ryzen, Intel Broadwell, ARMv8 or newer | +| Memory | 16 GB RAM | +| Storage | 200 GB | ## 1. Download the Latest Release from GitHub @@ -14,11 +24,14 @@ This guide provides step-by-step instructions for installing **Anchor**. ### Example ```bash -wget https://github.com/sigp/anchor/releases/download//anchor-.tar.gz - +# General download link format # Replace and with the appropriate values. +wget https://github.com/sigp/anchor/releases/download//anchor--.tar.gz +tar -xvf anchor--.tar.gz -tar -xvf anchor-.tar.gz +# Specific version example +https://github.com/sigp/anchor/releases/download/v0.3.1/anchor-v0.3.1-x86_64-unknown-linux-gnu.tar.gz +tar -xvf anchor-v0.3.1-x86_64-unknown-linux-gnu.tar.gz sudo mv anchor /usr/local/bin/ ``` @@ -38,10 +51,10 @@ anchor node --version docker pull sigp/anchor:latest ``` -2. Run the Anchor container: +2. Verify the installation: ```bash - docker run --rm -it sigp/anchor:latest --help + docker run --rm -it sigp/anchor:latest node --version ``` ## 3. Clone and Build Locally diff --git a/docs/docs/pages/introduction.mdx b/docs/docs/pages/introduction.mdx index 48f549a25..6de230fe0 100644 --- a/docs/docs/pages/introduction.mdx +++ b/docs/docs/pages/introduction.mdx @@ -10,7 +10,8 @@ production setting. ## What is SSV? -Secret Shared Validators (SSV) is a protocol that splits a validator key into multiple shares, distributed across different operators. This approach provides: +Secret Shared Validators (SSV) is a protocol that splits a validator key into multiple shares, distributed across different operators. +Instead of running a validator on a single machine, SSV splits the validator's duties across multiple operators, creating a more resilient and decentralized staking infrastructure. This approach provides: - **Fault Tolerance**: Your validator remains online even if some operators go offline - **No Single Point of Failure**: No single operator can compromise your validator @@ -19,74 +20,14 @@ Secret Shared Validators (SSV) is a protocol that splits a validator key into mu ## Why Choose Anchor? -Anchor stands out as an SSV client with several key advantages: - -### 🔒 **Security First** -- Written in Rust for memory safety and security -- Comprehensive fuzzing and security testing -- Built by Sigma Prime, trusted Ethereum infrastructure experts - -### ⚡ **High Performance** -- Optimized for efficiency and low resource usage -- Fast consensus and networking implementation -- Minimal latency for time-sensitive validator duties - -### 🛠️ **Developer Friendly** -- Clean, well-documented codebase -- Extensive CLI tools for key management and operations -- Active open-source development +Written in Rust, Anchor focuses on memory safety and security. As an independent implementation of the SSV protocol, +Anchor promotes client diversity in the SSV space, reducing the risk of network-wide failures. Anchor is optimized for +efficiency, fast consensus and networking implementation. ## Who Should Use Anchor? -### Staking Pool Operators -Run distributed validators with enhanced security and fault tolerance for your staking infrastructure. - -### Solo Stakers -Increase the reliability of your validator setup by distributing risk across multiple operators. - -### SSV Network Operators -Operate as part of the SSV network, providing validator services to other users. - -## Quick Start Paths - -Choose your path based on your role: - -:::code-group - -```bash [🎯 New to SSV] -# Start here to understand the basics -→ Read: What is SSV? -→ Next: Installation Guide -``` - -```bash [⚙️ Run an Operator] -# Become an SSV network operator -→ Next: Installation → Running an Operator -→ Then: Operator Configuration -``` - -```bash [🔑 Manage Keys] -# Generate and split validator keys -→ Next: Installation → CLI Reference -→ Focus: Keygen and KeySplit tools -``` - -```bash [🧑‍💻 Developer] -# Contribute or integrate -→ Next: Development Environment -→ Then: Architecture Overview -``` - -::: - -## Prerequisites - -Before getting started, ensure you have: - -- **System Requirements**: Linux, macOS, or Windows -- **Rust** (if building from source): Version 1.88.0 or later -- **Ethereum Knowledge**: Basic understanding of validators and staking -- **Command Line**: Comfort with terminal/command prompt usage +Anyone with a running staking infrastructure can opt to additionally run Anchor and become part of the SSV network. +This includes staking pool operators, node operators and solo stakers. ## What's Next? @@ -94,20 +35,18 @@ Before getting started, ensure you have: 2. **[Running an Operator](/running_an_operator)** - Start operating in the SSV network 3. **[CLI Reference](/cli)** - Master the command-line tools 4. **[Architecture](/architecture)** - Understand Anchor's technical design +5. **[SSV documentation](https://docs.ssv.network/learn/introduction)** - read more about the SSV network + ## About This Documentation -This documentation is open source and community-driven. We welcome contributions to help improve the experience for all users. - -- **Contribute**: [github.com/sigp/anchor/docs](https://github.com/sigp/anchor/tree/unstable/docs) -- **Community Support**: [GitHub Discussions](https://github.com/sigp/anchor/discussions) -- **Professional Support**: [Sigma Prime](https://sigmaprime.io) +This documentation is open source and community-driven. We welcome [contributions](https://github.com/sigp/anchor/tree/unstable/docs) to help improve the experience for all users. --- :::tip Need Help? - Check our [FAQ](/faq) for common questions -- Join the community on [GitHub](https://github.com/sigp/anchor) +- Join the community on [Discord](https://discord.com/invite/cyAszAh) - Report issues or request features in our [issue tracker](https://github.com/sigp/anchor/issues) ::: diff --git a/docs/docs/pages/metrics.mdx b/docs/docs/pages/metrics.mdx index 1c7e256a1..880ab23eb 100644 --- a/docs/docs/pages/metrics.mdx +++ b/docs/docs/pages/metrics.mdx @@ -1,7 +1,7 @@ # Metrics Anchor comes pre-built with a suite of metrics for developers or users to monitor the health -and performance of their node. +and performance of the node. They must be enabled at runtime using the `--metrics` CLI flag. diff --git a/docs/docs/pages/running_an_operator.mdx b/docs/docs/pages/running_an_operator.mdx index bdb19efff..14ce7bf90 100644 --- a/docs/docs/pages/running_an_operator.mdx +++ b/docs/docs/pages/running_an_operator.mdx @@ -27,7 +27,7 @@ Save your public key as you'll need it for on-chain registration. **Back up your **Step 2: Register as an Operator on the SSV Network** -To register an operator, follow the instructions for the official +To register an operator, follow the instructions in the official [ssv docs](https://docs.ssv.network/operators/operator-management/registration). **Step 3: Configure and run your Anchor node** diff --git a/docs/docs/pages/what_is_ssv.mdx b/docs/docs/pages/what_is_ssv.mdx deleted file mode 100644 index 6f8635f52..000000000 --- a/docs/docs/pages/what_is_ssv.mdx +++ /dev/null @@ -1,103 +0,0 @@ -# What is SSV? - -**Secret Shared Validators (SSV)** is a protocol that enables distributed validator technology for Ethereum staking. Instead of running a validator on a single machine, SSV splits the validator's duties across multiple operators, creating a more resilient and decentralized staking infrastructure. - -## How SSV Works - -### Key Splitting Technology - -SSV uses **threshold cryptography** to split a validator's private key into multiple shares: - -- **Key Generation**: A validator key is split into `n` shares using Shamir's Secret Sharing -- **Threshold Security**: Only `t` out of `n` shares are needed to sign (typically 3 out of 4) -- **No Single Point of Failure**: No single operator holds the complete key - -### Distributed Consensus - -Operators coordinate using a **Byzantine Fault Tolerant (BFT) consensus** mechanism: - -1. **Duty Assignment**: The beacon chain assigns duties to the validator -2. **Consensus Process**: Operators agree on what to sign using QBFT consensus -3. **Threshold Signing**: Once consensus is reached, operators create signature shares -4. **Signature Reconstruction**: Shares are combined to create the final signature - -## Benefits of SSV - -### 🛡️ **Enhanced Security** -- **No Single Key**: Private keys never exist in full on any single machine -- **Fault Tolerance**: Validator continues operating even if some operators fail -- **Slashing Protection**: Distributed consensus prevents conflicting signatures - -### 🌐 **Decentralization** -- **Operator Diversity**: Choose operators across different geographical locations -- **Infrastructure Independence**: Reduce reliance on single hosting providers -- **Censorship Resistance**: Harder to censor when distributed across operators - -### 💪 **Improved Uptime** -- **Redundancy**: Multiple operators ensure continuous operation -- **Maintenance Windows**: Individual operators can go offline for maintenance -- **Network Resilience**: Resistant to localized outages - -### 💰 **Economic Efficiency** -- **Shared Costs**: Distribute infrastructure costs across operators -- **Professional Management**: Leverage specialized operator expertise -- **Reduced Hardware Requirements**: Lower individual hardware requirements - -## SSV vs Traditional Staking - -| Aspect | Traditional Staking | SSV Staking | -|--------|-------------------|-------------| -| **Key Security** | Single point of failure | Distributed across operators | -| **Uptime** | Depends on single setup | Fault-tolerant across operators | -| **Maintenance** | Full responsibility | Shared responsibility | -| **Decentralization** | Limited | High (multiple operators) | -| **Setup Complexity** | Moderate | Higher initial setup | -| **Ongoing Management** | Full control needed | Operators handle day-to-day | - -## SSV Ecosystem - -### Official Resources -- **[SSV Network Documentation](https://docs.ssv.network/learn/introduction)** - Complete learning resources -- **[SSV Specification](https://github.com/ssvlabs/ssv-spec)** - Technical protocol specification -- **[SSV Labs Website](https://ssv.network/)** - Main project website - -### Client Implementations -- **[ssv (Go)](https://github.com/ssvlabs/ssv)** - Reference implementation by SSV Labs -- **[Anchor (Rust)](https://github.com/sigp/anchor)** - High-performance implementation by Sigma Prime - -### Tools and Services -- **[SSV Explorer](https://explorer.ssv.network/)**: Monitor network activity and operators -- **[SSV Scan](https://ssvscan.io/)**: Network monitoring dashboard and analytics -- **[SSV Web App](https://app.ssv.network/connect)**: Main application for key generation, operator management, and validator deployment - -## Getting Started with SSV - -### For Stakers -1. **Learn the Basics**: Understand SSV concepts and benefits -2. **Choose Operators**: Select trusted operators for your setup -3. **Generate Keys**: Create and split your validator keys -4. **Deploy Validator**: Distribute shares to chosen operators - -### For Operators -1. **Run SSV Client**: Deploy Anchor or another SSV client -2. **Register on Network**: Become a registered network operator -3. **Manage Validators**: Handle assigned validator duties -4. **Monitor Performance**: Ensure high uptime and performance - - ---- - -:::tip -Ready to Start? - -Now that you understand SSV, you can proceed to: -- **[Installation](/installation)** - Set up Anchor SSV client -- **[Running an Operator](/running_an_operator)** - Become an SSV operator -- **[CLI Reference](/cli)** - Learn Anchor's key management tools -::: - -:::info -Learn More - -For deeper technical details, visit the [SSV Network Documentation](https://docs.ssv.network/learn/introduction) and review the [official specification](https://github.com/ssvlabs/ssv-spec). -::: diff --git a/docs/vocs.config.ts b/docs/vocs.config.ts index a78e703e3..0f2166db3 100644 --- a/docs/vocs.config.ts +++ b/docs/vocs.config.ts @@ -10,10 +10,12 @@ export default defineConfig({ // Community-focused aiCta: false, + // Enable theme toggle + themeToggle: true, + // Open source theme - matching design3 background and theming theme: { accentColor: '#00d4aa', - colorScheme: 'dark', variables: { color: { background: { light: '#ffffff', dark: '#0a0a0a' }, @@ -52,7 +54,6 @@ export default defineConfig({ text: 'Getting Started', items: [ { text: 'Introduction', link: '/introduction' }, - { text: 'What is SSV?', link: '/what_is_ssv' }, { text: 'Installation', link: '/installation' }, { text: 'Running an Operator', link: '/running_an_operator' }, ] @@ -60,12 +61,13 @@ export default defineConfig({ { text: 'Usage & Configuration', items: [ - { text: 'CLI Reference', link: '/cli', collapsed: true, + { + text: 'CLI Reference', link: '/cli', collapsed: true, items: [ - { text: 'Node', link: '/cli-node' }, - { text: 'Keygen', link: '/cli-keygen' }, - { text: 'KeySplit', link: '/cli-keysplit' }, - ] + { text: 'Node', link: '/cli-node' }, + { text: 'Keygen', link: '/cli-keygen' }, + { text: 'KeySplit', link: '/cli-keysplit' }, + ] }, { text: 'Metrics', link: '/metrics' }, { text: 'Advanced Networking', link: '/advanced_networking' }, @@ -76,8 +78,10 @@ export default defineConfig({ text: 'Development', items: [ { text: 'Development Environment', link: '/development_environment' }, - { text: 'Protocol Developers', link: '/protocol_developers', collapsed: true, - items: [ {text: 'SSV Handshake Protocol', link: '/handshake' } ] }, + { + text: 'Protocol Developers', link: '/protocol_developers', collapsed: true, + items: [{ text: 'SSV Handshake Protocol', link: '/handshake' }] + }, { text: 'Architecture', link: '/architecture' }, { text: 'Contributing', link: '/contributing' }, ] diff --git a/metrics/README.md b/metrics/README.md index 97ddd5b26..895a74fe0 100644 --- a/metrics/README.md +++ b/metrics/README.md @@ -6,7 +6,7 @@ Here we provides a `docker-compose` environment which scrapes metrics from Ancho nodes using Prometheus and presents them in a browser-based Grafana GUI. For in-depth details on running metrics, please see the [anchor -book](https://anchor-book.sigmaprime.io). +book](https://anchor.sigmaprime.io). ## Basic Usage