diff --git a/docs/adv/_category_.json b/docs/adv/_category_.json new file mode 100644 index 0000000000..55aa8078c3 --- /dev/null +++ b/docs/adv/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "ADVANCED & TROUBLESHOOTING", + "position": 3, + "collapsed": false, + "collapsible": false, + "className": "menuSection" +} \ No newline at end of file diff --git a/docs/advanced/_category_.json b/docs/adv/advanced/_category_.json similarity index 71% rename from docs/advanced/_category_.json rename to docs/adv/advanced/_category_.json index 09a5dd1dd1..65479986d0 100644 --- a/docs/advanced/_category_.json +++ b/docs/adv/advanced/_category_.json @@ -1,5 +1,5 @@ { "label": "Advanced Guides", - "position": 3, + "position": 1, "collapsed": true - } \ No newline at end of file +} \ No newline at end of file diff --git a/docs/advanced/adv-docker-configs.md b/docs/adv/advanced/adv-docker-configs.md similarity index 99% rename from docs/advanced/adv-docker-configs.md rename to docs/adv/advanced/adv-docker-configs.md index 2c5a0ebd63..826b224b39 100644 --- a/docs/advanced/adv-docker-configs.md +++ b/docs/adv/advanced/adv-docker-configs.md @@ -1,5 +1,5 @@ --- -sidebar_position: 12 +sidebar_position: 6 description: Use advanced docker-compose features to have more flexibility and power to change the default configuration. --- diff --git a/docs/advanced/quickstart-combine.md b/docs/adv/advanced/quickstart-combine.md similarity index 99% rename from docs/advanced/quickstart-combine.md rename to docs/adv/advanced/quickstart-combine.md index a571ab8a5f..1a3e8da04a 100644 --- a/docs/advanced/quickstart-combine.md +++ b/docs/adv/advanced/quickstart-combine.md @@ -1,5 +1,5 @@ --- -sidebar_position: 8 +sidebar_position: 4 description: Combine distributed validator private key shares to recover the validator private key. --- diff --git a/docs/advanced/quickstart-sdk.mdx b/docs/adv/advanced/quickstart-sdk.mdx similarity index 95% rename from docs/advanced/quickstart-sdk.mdx rename to docs/adv/advanced/quickstart-sdk.mdx index a216fd7534..1c3f4e1114 100644 --- a/docs/advanced/quickstart-sdk.mdx +++ b/docs/adv/advanced/quickstart-sdk.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 2 description: Create a DV cluster using the Obol Typescript SDK --- @@ -8,7 +8,7 @@ import TabItem from '@theme/TabItem'; # Create a DV using the SDK -This is a walkthrough of using the [Obol-SDK](https://www.npmjs.com/package/@obolnetwork/obol-sdk) to propose a four-node distributed validator cluster for creation using the [DV Launchpad](../dvl/intro.md). +This is a walkthrough of using the [Obol-SDK](https://www.npmjs.com/package/@obolnetwork/obol-sdk) to propose a four-node distributed validator cluster for creation using the [DV Launchpad](../../learn/intro/launchpad.md). ## Pre-requisites @@ -81,9 +81,9 @@ console.log( ## Invite the Operators to complete the DKG -Once the Obol-API returns a `configHash` string from the `createClusterDefinition` method, you can use this identifier to invite the operators to the [Launchpad](../dvl/intro.md) to complete the process +Once the Obol-API returns a `configHash` string from the `createClusterDefinition` method, you can use this identifier to invite the operators to the [Launchpad](../../learn/intro/launchpad.md) to complete the process -1. Operators navigate to `https://.launchpad.obol.org/dv?configHash=` and complete the [run a DV with others](../start/quickstart_group.mdx) flow. +1. Operators navigate to `https://.launchpad.obol.org/dv?configHash=` and complete the [run a DV with others](../../run/start/quickstart_group.mdx) flow. 1. Once the DKG is complete, and operators are using the `--publish` flag, the created cluster details will be posted to the Obol API. 1. The creator will be able to retrieve this data with `obol.getClusterLock(configHash)`, to use for activating the newly created validator. diff --git a/docs/advanced/quickstart-split.md b/docs/adv/advanced/quickstart-split.md similarity index 88% rename from docs/advanced/quickstart-split.md rename to docs/adv/advanced/quickstart-split.md index 592c03de5b..8b74810da8 100644 --- a/docs/advanced/quickstart-split.md +++ b/docs/adv/advanced/quickstart-split.md @@ -1,17 +1,17 @@ --- -sidebar_position: 7 +sidebar_position: 3 description: Migrate an existing validator by splitting its private key into shares --- -# Migrate a validator +# Migrate an existing validator :::warning This process should only be used if you want to split an *existing validator private key* into multiple private key shares for use in a Distributed Validator Cluster. **If your existing validator is not properly shut down before the Distributed Validator starts, your validator may be slashed**. -If you are starting a new validator, you should follow a [quickstart guide](../start/quickstart_overview.md) instead. +If you are starting a new validator, you should follow a [quickstart guide](../../run/start/quickstart_overview.md) instead. ::: -Split an existing Ethereum validator key into multiple key shares for use in an [Obol Distributed Validator Cluster](../int/key-concepts.md#distributed-validator-cluster). +Split an existing Ethereum validator key into multiple key shares for use in an [Obol Distributed Validator Cluster](../../learn/intro/key-concepts.md#distributed-validator-cluster). ## Pre-requisites @@ -94,7 +94,7 @@ These split keys can now be used to start a Charon cluster. ## Step 3. (Optional) Encrypt artifacts for distribution -Within each folder are the encrypted [private key shares](../int/key-concepts.md#distributed-validator-key-share), along with the decryption passwords. To transmit these folders to the operators/machines where they will run, it might be prudent to encrypt the folder as a `.zip` to transport them. +Within each folder are the encrypted [private key shares](../../learn/intro/key-concepts.md#distributed-validator-key-share), along with the decryption passwords. To transmit these folders to the operators/machines where they will run, it might be prudent to encrypt the folder as a `.zip` to transport them. ```shell # For each folder in ./cluster/ encrypt it with a different password diff --git a/docs/advanced/self-relay.md b/docs/adv/advanced/self-relay.md similarity index 96% rename from docs/advanced/self-relay.md rename to docs/adv/advanced/self-relay.md index cf54a173b5..05000327ca 100644 --- a/docs/advanced/self-relay.md +++ b/docs/adv/advanced/self-relay.md @@ -1,5 +1,5 @@ --- -sidebar_position: 9 +sidebar_position: 5 description: Self-host a relay --- @@ -35,4 +35,4 @@ Configure **ALL** charon nodes in your cluster to use this relay: Note that a local `relay/.charon/charon-enr-private-key` file will be created next to `relay/docker-compose.yml` to ensure a persisted relay ENR across restarts. -A list of publicly available relays that can be used is maintained [here](../faq/risks.md). +A list of publicly available relays that can be used is maintained [here](../../adv/security/risks.md). \ No newline at end of file diff --git a/docs/sec/_category_.json b/docs/adv/security/_category_.json similarity index 100% rename from docs/sec/_category_.json rename to docs/adv/security/_category_.json diff --git a/docs/sec/bug-bounty.md b/docs/adv/security/bug-bounty.md similarity index 99% rename from docs/sec/bug-bounty.md rename to docs/adv/security/bug-bounty.md index eff2d0c29d..accdc2d72e 100644 --- a/docs/sec/bug-bounty.md +++ b/docs/adv/security/bug-bounty.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 3 description: Bug Bounty Policy --- @@ -34,7 +34,7 @@ Submissions related to the following are considered out of scope: - Physical security breaches - Non-security related UX/UI issues - Third-party application vulnerabilities -- The [Obol](https://obol.tech) static website or the Obol infrastructure +- The [Obol](https://obol.org) static website or the Obol infrastructure - The operational security of node operators running or using Obol software ## Program Rules diff --git a/docs/sec/contact.md b/docs/adv/security/contact.md similarity index 93% rename from docs/sec/contact.md rename to docs/adv/security/contact.md index e66e1663e2..29a07ec23f 100644 --- a/docs/sec/contact.md +++ b/docs/adv/security/contact.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 7 description: Security details for the Obol Network --- diff --git a/docs/sec/ev-assessment.md b/docs/adv/security/ev-assessment.md similarity index 98% rename from docs/sec/ev-assessment.md rename to docs/adv/security/ev-assessment.md index 37a25600bd..dee3538934 100644 --- a/docs/sec/ev-assessment.md +++ b/docs/adv/security/ev-assessment.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 5 description: Software Development Security Assessment --- @@ -64,9 +64,9 @@ Obol’s business model is to eventually capture a portion of the revenue genera Obol’s product consists of three main components, each run by its own team: a webapp, a client, and smart contracts. -- [DV Launchpad](../dvl/intro.md): A webapp to create and manage distributed validators. -- [Charon](../charon/intro.md): A middleware client that enables operators to run distributed validators. -- [Solidity](../sc/introducing-obol-splits.mdx): Withdrawal and fee recipient contracts for use with distributed validators. +- [DV Launchpad](../../learn/intro/launchpad.md): A webapp to create and manage distributed validators. +- [Charon](../../learn/charon/intro.md): A middleware client that enables operators to run distributed validators. +- [Solidity](../../learn/intro/obol-splits.mdx): Withdrawal and fee recipient contracts for use with distributed validators. ## Analysis - Cluster Setup and DKG diff --git a/docs/sec/overview.md b/docs/adv/security/overview.md similarity index 100% rename from docs/sec/overview.md rename to docs/adv/security/overview.md diff --git a/docs/faq/risks.md b/docs/adv/security/risks.md similarity index 51% rename from docs/faq/risks.md rename to docs/adv/security/risks.md index ded284c98c..c09ad700a1 100644 --- a/docs/faq/risks.md +++ b/docs/adv/security/risks.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 2 description: Centralization Risks and mitigation --- @@ -9,9 +9,10 @@ description: Centralization Risks and mitigation **Mitigation**: Self-host a relay. -One of the risks associated with Obol hosting the [LibP2P relays](../charon/networking.mdx) infrastructure allowing peer discovery is that if Obol-hosted relays go down, peers won't be able to discover each other and perform the DKG. To mitigate this risk, external organizations and node operators can consider self-hosting a relay. This way, if Obol's relays go down, the clusters can still operate through other relays in the network. Ensure that all nodes in the cluster use the same relays, or they will not be able to find each other if they are connected to different relays. +One of the risks associated with Obol hosting the [LibP2P relays](../../learn/charon/networking.mdx) infrastructure allowing peer discovery is that if Obol-hosted relays go down, peers won't be able to discover each other and perform the DKG. To mitigate this risk, external organizations and node operators can consider self-hosting a relay. This way, if Obol's relays go down, the clusters can still operate through other relays in the network. Ensure that all nodes in the cluster use the same relays, or they will not be able to find each other if they are connected to different relays. + +The following non-Obol entities run relays that you can consider adding to your cluster (you can have more than one per cluster, see the `--p2p-relays` flag of [`charon run`](../../learn/charon/charon-cli-reference.md#the-run-command)): -The following non-Obol entities run relays that you can consider adding to your cluster (you can have more than one per cluster, see the `--p2p-relays` flag of [`charon run`](../charon/charon-cli-reference.md#the-run-command)): | Entity | Relay URL | |-----------|---------------------------------------| @@ -25,13 +26,13 @@ The following non-Obol entities run relays that you can consider adding to your **Mitigation**: Pin specific docker versions or compile from source on a trusted commit. -Another risk associated with Obol is the Labs team having the ability to update the [Charon code](https://github.com/ObolNetwork/charon) used by node operators within DV clusters, which could introduce vulnerabilities or malicious code. To mitigate this risk, operators can consider pinning specific versions of the Docker image or git repo that have been [thoroughly tested](../sec/overview.md#list-of-security-audits-and-assessments) and accepted by the network. This would ensure that any updates are carefully vetted and reviewed by the community, and only introduced into a running cluster gradually. The labs team will strive to communicate the security or operational impact any Charon update entails, giving operators the chance to decide whether they want potential performance or quality of experience improvements, or whether they remain on a trusted version for longer. +Another risk associated with Obol is the Labs team having the ability to update the [Charon code](https://github.com/ObolNetwork/charon) used by node operators within DV clusters, which could introduce vulnerabilities or malicious code. To mitigate this risk, operators can consider pinning specific versions of the Docker image or git repo that have been [thoroughly tested](../security/overview.md#list-of-security-audits-and-assessments) and accepted by the network. This would ensure that any updates are carefully vetted and reviewed by the community, and only introduced into a running cluster gradually. The labs team will strive to communicate the security or operational impact any Charon update entails, giving operators the chance to decide whether they want potential performance or quality of experience improvements, or whether they remain on a trusted version for longer. ## Risk: Obol hosting the DV Launchpad -**Mitigation**: Use [`create cluster`](../charon/charon-cli-reference.md#the-create-command) or [`create dkg`](../charon/charon-cli-reference.md#creating-the-configuration-for-a-dkg-ceremony) locally and distribute the files manually. +**Mitigation**: Use [`create cluster`](../../learn/charon/charon-cli-reference.md#the-create-command) or [`create dkg`](../../learn/charon/charon-cli-reference.md#creating-the-configuration-for-a-dkg-ceremony) locally and distribute the files manually. -Hosting the first Charon frontend, the [DV Launchpad](../dvl/intro.md), on a centralized server could create a single point of failure, as users would have to rely on Obol's server to access the protocol. This could limit the decentralization of the protocol and could make it vulnerable to attacks or downtime. Obol hosting the launchpad on a decentralized network, such as IPFS is a first step but not enough. This is why the Charon code is open-source and contains a CLI interface to interact with the protocol locally. +Hosting the first Charon frontend, the [DV Launchpad](../../learn/intro/launchpad.md), on a centralized server could create a single point of failure, as users would have to rely on Obol's server to access the protocol. This could limit the decentralization of the protocol and could make it vulnerable to attacks or downtime. Obol hosting the launchpad on a decentralized network, such as IPFS is a first step but not enough. This is why the Charon code is open-source and contains a CLI interface to interact with the protocol locally. To mitigate the risk of launchpad failure, consider using the `create cluster` or `create dkg` commands locally and distributing the key shares files manually. diff --git a/docs/sec/smart_contract_audit.mdx b/docs/adv/security/smart_contract_audit.mdx similarity index 99% rename from docs/sec/smart_contract_audit.mdx rename to docs/adv/security/smart_contract_audit.mdx index 0d94ada792..bfb14b3427 100644 --- a/docs/sec/smart_contract_audit.mdx +++ b/docs/adv/security/smart_contract_audit.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 4 description: Smart Contract Audit --- diff --git a/docs/sec/threat_model.md b/docs/adv/security/threat_model.md similarity index 99% rename from docs/sec/threat_model.md rename to docs/adv/security/threat_model.md index f739b1dfa3..27932fd62e 100644 --- a/docs/sec/threat_model.md +++ b/docs/adv/security/threat_model.md @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 5 description: Threat model for a Distributed Validator --- diff --git a/docs/start/_category_.json b/docs/adv/troubleshooting/_category_.json similarity index 57% rename from docs/start/_category_.json rename to docs/adv/troubleshooting/_category_.json index 0d0d566773..9b64570467 100644 --- a/docs/start/_category_.json +++ b/docs/adv/troubleshooting/_category_.json @@ -1,5 +1,5 @@ { - "label": "Getting started", + "label": "Troubleshooting", "position": 2, "collapsed": true } diff --git a/docs/faq/client_configurations.md b/docs/adv/troubleshooting/client_configurations.md similarity index 88% rename from docs/faq/client_configurations.md rename to docs/adv/troubleshooting/client_configurations.md index 6c7e0026cd..b0416404af 100644 --- a/docs/faq/client_configurations.md +++ b/docs/adv/troubleshooting/client_configurations.md @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 3 description: A reference for extra configuration of Ethereum Clients when running in DVs. --- @@ -14,7 +14,7 @@ Many execution, consensus, and validator clients need custom flags or parameters ### Consensus Client -Nothing specific for distributed validators is required. If you are configuring MEV-boost, consult the settings you need [here](../advanced/quickstart-builder-api.mdx#consensus-clients). +Nothing specific for distributed validators is required. If you are configuring MEV-boost, consult the settings you need [here](../../run/start/quickstart-builder-api.mdx#consensus-clients). ### Validator Client @@ -27,7 +27,7 @@ Required flags: ### Consensus Client -Nothing specific for distributed validators is required. If you are configuring MEV-boost, consult the settings you need [here](../advanced/quickstart-builder-api.mdx#consensus-clients). +Nothing specific for distributed validators is required. If you are configuring MEV-boost, consult the settings you need [here](../../run/start/quickstart-builder-api.mdx#consensus-clients). ### Validator Client @@ -56,7 +56,7 @@ Required flags: ### Consensus Client -Nothing specific for distributed validators is required. If you are configuring MEV-boost, consult the settings you need [here](../advanced/quickstart-builder-api.mdx#consensus-clients). +Nothing specific for distributed validators is required. If you are configuring MEV-boost, consult the settings you need [here](../../run/start/quickstart-builder-api.mdx#consensus-clients). ### Validator Client diff --git a/docs/faq/dkg_failure.md b/docs/adv/troubleshooting/dkg_failure.md similarity index 99% rename from docs/faq/dkg_failure.md rename to docs/adv/troubleshooting/dkg_failure.md index 822fa10c51..97b0725aa9 100644 --- a/docs/faq/dkg_failure.md +++ b/docs/adv/troubleshooting/dkg_failure.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 2 description: Handling DKG failure --- diff --git a/docs/faq/errors.mdx b/docs/adv/troubleshooting/errors.mdx similarity index 99% rename from docs/faq/errors.mdx rename to docs/adv/troubleshooting/errors.mdx index f4dbdc125e..f83ad697bf 100644 --- a/docs/faq/errors.mdx +++ b/docs/adv/troubleshooting/errors.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 1 description: Errors & Resolutions --- diff --git a/docs/dvl/_category_.json b/docs/dvl/_category_.json deleted file mode 100644 index 5a7bdd3db8..0000000000 --- a/docs/dvl/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "DV Launchpad", - "position": 6, - "collapsed": true -} \ No newline at end of file diff --git a/docs/gov/_category_.json b/docs/gov/_category_.json new file mode 100644 index 0000000000..3e0c2c3cce --- /dev/null +++ b/docs/gov/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "COMMUNITY & GOVERNANCE", + "position": 4, + "collapsed": false, + "collapsible": false, + "className": "menuSection" +} \ No newline at end of file diff --git a/docs/gov/community/_category_.json b/docs/gov/community/_category_.json new file mode 100644 index 0000000000..f3dffd1ffe --- /dev/null +++ b/docs/gov/community/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Community", + "position": 2, + "collapsed": true +} \ No newline at end of file diff --git a/docs/gov/community/staking-masters.md b/docs/gov/community/staking-masters.md new file mode 100644 index 0000000000..5f8a822fd4 --- /dev/null +++ b/docs/gov/community/staking-masters.md @@ -0,0 +1,8 @@ +--- +description: Information about the Staking Mastery Program +sidebar_position: 1 +--- + +# Staking Mastery Program + +Information about the Staking Mastery Program can be found at https://squadstaking.com/mastery. \ No newline at end of file diff --git a/docs/gov/community/techne.md b/docs/gov/community/techne.md new file mode 100644 index 0000000000..a39c5adcdf --- /dev/null +++ b/docs/gov/community/techne.md @@ -0,0 +1,116 @@ +--- +description: Information about the Techne Credential Program. +sidebar_position: 1 +--- + +# Techne + +Information about the Techne Credential Program can be found at https://squadstaking.com/techne. + +## Welcome to the Obol Network Techne Credential 👋 + +At Obol Network, we believe in empowering our community by providing them with the tools, knowledge, and recognition they deserve. The credential is designed to provide an on-chain attestation that identifies, acknowledges, and elevates individuals who demonstrate proven experience, knowledge, and commitment within the Distributed Validators domain. + +Drawing inspiration from the rich heritage of Ancient Greece, the name "Techne" reflects ideas of art, skill, or craft, representing technical mastery. Today, Techne embodies our vision to empower and uplift individuals who not only showcase technical expertise but also actively contribute to strengthening the staking ecosystem. + +## Why Earn the Credential? + +Each Obol Techne Credential is a verifiable, non-transferable NFT credential from Obol that proves your knowledge and experience operating Obol DVs. This on-chain attestation can then be used to showcase your experience, whether it’s to the Obol Core Team, other Obol community members, or the broader staking ecosystem. The credentials are defined in different tiers to ensure a progression path towards deeper expertise while offering an accessible entry point. + +![Obol vs others table](/img/Technes.png) + +### Techne Credential Benefits + +The goal of the Obol Techne Credential is to give community validators more opportunities to become node operators. Today, many liquid staking protocols and other staking services are looking to build community-focused, permissionless, and more decentralized node operator sets. However, to be considered in those programs, validators must have proven experience and demonstrated ability to run high-performing nodes. The key benefit of the Obol Techne Credential is to give every validator to prove their knowledge and experience with Obol DVs. + +- Recognition: Receive a verifiable non-transferable NFT to prove and showcase your knowledge and experience running distributed validators. +- Opportunities: Credentialed individuals will have proven experience running distributed validators, which can be shared to gain a higher likelihood of future inclusion in opportunities such as EtherFi’s Operation Solo Staker and Lido’s SimpleDVT Module. + +## Program Overview + +### Eligibility +The Obol Techne Credential is open to all community members interested in gaining knowledge and experience in running distributed validators. + +### Credentialing Journey + +Our credentialing journey current takes place in waves. Each wave will last around 7 weeks and will consist of a preparation period called *Learning Phase*, followed by a hands-on experience period, called *Experience*, during which we will monitor your performance. Before the start of a wave, you will already have the opportunity to build your cluster. Credentials will be awarded at the end of the wave based on a snapshot we will have taken of your average performance during the Practical Experience phase. + +Also, we are now introducing the concept of Credential Tiers. Currently, there are three: the Base Credential, the Bronze Credential and the Silver Credential. To be allowed to compete for the Bronze Credential, you must be in a squad / cluster with the leader holding a Base credential. + +### Learning Phase & Knowledge Assessment + +During each wave of our program, you will have the opportunity to join live training sessions on our Discord. We will teach the basics of Ethereum Proof of Stake, and Distributed Validators (DVs) and we will do demonstrations on how to run your own DV. There will also be a training session that will allow you allow you to ask questions and receive answers directly from our team. Head to Discord to see the full agenda of the current wave. + +Also, don’t forget to thoroughly read our [comprehensive documentation](https://docs.obol.tech/docs/int/Overview)! + +### Practical Experience + +To obtain your Obol Techne Credential, you will need to demonstrate your abilities to **set up, run, and maintain a DV cluster for 3 weeks**. This is the essence of this credential, to allow you to showcase your experience in an honest and verifiable manner on-chain. + +:::warning All aspiring applicants need to fill out the [Techne Credential Application](https://docs.google.com/forms/d/e/1FAIpQLSf1uBizXDLxhYLnN5rTbmXTzdjBpd4B12tSWGQFzsi5BnXkZQ/viewform). If you forget to do this, you will not be eligible for a Credential. After you filled the form, we will send you periodic updates throughout the wave, but be sure to stay tuned to Discord as well. +::: + +### Performance Requirements + +To be eligible to claim your Credential, we also require you to **run with high performance for 3 weeks.** Distributed Validators have been shown to outperform traditional validators, while providing much more [benefits and advantages](https://blog.obol.tech/what-is-dvt-and-how-does-it-improve-staking-on-ethereum/). + +The performance requirements are different depending on the different tiers. + +- For the **Base Credential**, you will need to run a DV cluster for 3 weeks with a performance near or above the [network average](https://grafana.monitoring.gcp.obol.tech/d/adgym07d8ak1sf/techne-credentials?orgId=6) (open it in incognito mode if the link does not work). We will take into account the overall performance of the cluster, not the individual performances of the operators. +- For the **Bronze Credential** , we will need to create and manage 50 validators for 3 weeks with a performance equal to or above the [average of the Liquid Staking Providers](https://grafana.monitoring.gcp.obol.tech/d/adgym07d8ak1sf/techne-credentials?orgId=6) (index composed of Lido, RocketPool, Coinbase Cloud, StakeWise and EtherFi). We will also take into account the individual performance of the operators (the exact requirements will be announced soon). +- For the **Silver Credential,** you will need to create and manage 1 or more validators for 2 months on mainnet, with performance at near or above the network average. We will take into account the overall performance of the cluster as well as the individual performance of the operators. + +:::For Base + Bronze (testnet), if you require delegate hETH, we ask you to set the address 0x17E6F6270A101dc7687Cc9899889819EeAF8253f as the withdrawal recipient. We will not activate validators that have not done this. At the end of the wave, you will only be eligible for the Credentials after we receive the Holesky ETH back. +::: + +### Performance Monitoring + +To track your performance, we will send a monitoring credential after you’ve filled the Cluster Registration Form. This will be sent to the email address you used to fill the form and will arrive from this email address: techne@obol.tech. + +We are proud to share with you our [Techne Public Dashboard](https://grafana.monitoring.gcp.obol.tech/d/adgym07d8ak1sf/techne-credentials?orgId=6) (*open it in incognito mode if the link does not work*) which will allow you to track your performance and compare it to the requirements throughout your adventure. If the link does not work, open it in private browsing. + +**Finally, all cluster/squad members will need to implement it** by following these [steps in the quickstart guide](https://docs.obol.tech/docs/start/quickstart_group). Please note that **if you do not complete these steps, you will not be eligible for the Credentials**. + +### Claim your Credentials + +After a wave has ended and if you have *created*, *ran*, and successfully exited your cluster, you will be able to claim your Techne Credential on an Galxe page we will later share with you. + +We will make an announcement on our Discord and Twitter when the credentials are available to claim. + +## Get Started* + +Start your journey without further delay. Please find here the various documents and information you will need to get started in the program: + +### [👉 Get Started Now](https://discord.com/invite/n6ebKsX46w) + +Additional Resources + +> [Quickstart Guide](https://docs.obol.tech/docs/start/quickstart_overview) +> +> +>  [Support Channel on Discord](https://discord.gg/obolnetwork) +> +> [Get Started Monitoring your Node](https://docs.obol.tech/docs/advanced/monitoring) +> + +## **Disclaimer** + +*Obol Network does not assume responsibility for any financial losses that may be incurred by individuals who choose to run on the Mainnet. Participants are advised to exercise due diligence and assess all risks associated with running on the Mainnet. Obol Network shall not be held liable for any damages, financial or otherwise, that may arise from participating in Mainnet operations.* + +## FAQ + +**It has been 24 hours since I filled out the form to receive my Holesky ETH, but I haven't received anything yet. Is this normal?** + +This is probably due to an unusually high number of requests. Please wait for up to 48 hours and reach out to us on Discord. Also, please note that we do not distribute any Holseky ETH on weekends. + +**Can I qualify for the program if I run all the nodes on a single machine?** + +This is not aligned with the principle of distributed validators (DVs). You must form your cluster (squad) with other humans using other machines. + +**Can I take part in the program if I’m running on Mainnet?** + +Yes, those running a DV on mainnet have the opportunity to earn the Silver Techne Credential. + +**I don’t have the Base Credential but I have enough Holesky ETH to run 50 validators, can I aim for the Bronze Techne?** + +Yes, you can. Please send a message on Discord in the #techne-applicants channel explaining your desire to run for Bronze using your own Holesky ETH. \ No newline at end of file diff --git a/docs/cf/_category_.json b/docs/gov/contribution/_category_.json similarity index 75% rename from docs/cf/_category_.json rename to docs/gov/contribution/_category_.json index 0c3c0c0431..fdeb0483e4 100644 --- a/docs/cf/_category_.json +++ b/docs/gov/contribution/_category_.json @@ -1,5 +1,5 @@ { "label": "Contribution & Feedback", - "position": 9, + "position": 3, "collapsed": true -} +} \ No newline at end of file diff --git a/docs/cf/bug-report.md b/docs/gov/contribution/bug-report.md similarity index 97% rename from docs/cf/bug-report.md rename to docs/gov/contribution/bug-report.md index 00afb3a516..2420855f2e 100644 --- a/docs/cf/bug-report.md +++ b/docs/gov/contribution/bug-report.md @@ -1,3 +1,8 @@ +--- +description: Filing a bug report +sidebar_position: 1 +--- + # Filing a bug report Bug reports are critical to the rapid development of Obol. In order to make the process quick and efficient for all parties, it is best to follow some common reporting etiquette when filing to avoid double issues or miscommunications. diff --git a/docs/cf/docs.md b/docs/gov/contribution/docs.md similarity index 99% rename from docs/cf/docs.md rename to docs/gov/contribution/docs.md index 13f3ddab65..5e57ed3b18 100644 --- a/docs/cf/docs.md +++ b/docs/gov/contribution/docs.md @@ -1,3 +1,9 @@ +--- +description: Documentation Standards +sidebar_position: 2 +--- + + # Documentation standards This section outlines the formatting standards presented within this documentation. In order to maintain continuity and quality, all pull requests must conform to the specifics below. diff --git a/docs/cf/feedback.md b/docs/gov/contribution/feedback.md similarity index 87% rename from docs/cf/feedback.md rename to docs/gov/contribution/feedback.md index 01e4657078..4ee477e502 100644 --- a/docs/cf/feedback.md +++ b/docs/gov/contribution/feedback.md @@ -1,3 +1,9 @@ +--- +description: Feedback for us +sidebar_position: 3 +--- + + # Feedback If you have followed our quickstart guides, and whether you succeeded or failed at running the distributed validator successfully, we would like to hear your feedback on the process and where you encountered difficulties. diff --git a/docs/gov/governance/_category_.json b/docs/gov/governance/_category_.json new file mode 100644 index 0000000000..bcc42463e7 --- /dev/null +++ b/docs/gov/governance/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Governance", + "position": 1, + "collapsed": true +} \ No newline at end of file diff --git a/docs/faq/contributions.md b/docs/gov/governance/contributions.md similarity index 99% rename from docs/faq/contributions.md rename to docs/gov/governance/contributions.md index f6605a7c62..a455eb33f3 100644 --- a/docs/faq/contributions.md +++ b/docs/gov/governance/contributions.md @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 2 description: Earning Obol Contributions --- diff --git a/docs/guides/_category_.json b/docs/guides/_category_.json new file mode 100644 index 0000000000..a3633cebdd --- /dev/null +++ b/docs/guides/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "BEGINNER GUIDES", + "position": 5, + "collapsed": false, + "collapsible": false, + "className": "menuSection" +} \ No newline at end of file diff --git a/docs/guides/walkthroughs/CSM-walkthrough.md b/docs/guides/walkthroughs/CSM-walkthrough.md new file mode 100644 index 0000000000..ca2be63737 --- /dev/null +++ b/docs/guides/walkthroughs/CSM-walkthrough.md @@ -0,0 +1,232 @@ +--- +sidebar_position: 5 +description: Setup and run a DV within the Lido Community Staking Module +--- +# Create a Lido CSM DV + +This is a guide on taking part in Lido's [Community Staking Module](https://operatorportal.lido.fi/modules/community-staking-module) (CSM) with a squad as part of a [Distributed Validator Cluster](../../learn/intro/key-concepts.md#distributed-validator-cluster). + +To start, this guide makes a couple assumptions: + +1. You're running a Linux distribution and you've installed [Git](https://git-scm.com/downloads) and [Docker](https://docs.docker.com/engine/install/) (as a [non-root user](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user)). +2. You will be deploying on Ethereum mainnet. Some screenshots in this guide are from Holesky just for demonstration purposes, so please verify you are using the correct [mainnet addresses](https://operatorportal.lido.fi/modules/community-staking-module#block-d8e94f551b2e47029a54e6cedea914a7). + +## Getting started + +This guide is broken down into 3 parts: + +Part 1: Creating a shared [SAFE](https://safe.global/) wallet for the cluster, and a [Splits.org](https://splits.org) reward splitting contract + +Part 2: Using the [Obol DV Launchpad](https://launchpad.obol.org/) + CLI to create the cluster + +Part 3: Deploying the validator to Lido's CSM using their UI. + +:::info +In this guide we'll be using CSM UI in advanced mode, using the `extendedManagerPermissions` to set the `managerAddress` to the cluster multi-sig (SAFE) and the `rewardAddress` to the Splits.org splitting contract. +::: + +## Part 1: Creating the Cluster SAFE + Splitter Contract +### Deploy the SAFE + +Detailed instructions on how to create a SAFE Wallet can be found [here](https://help.safe.global/en/articles/40868-creating-a-safe-on-a-web-browser). + +The squad leader should obtain signing addresses for all the cluster members, to create a new SAFE with the operators all as owners. + +![SAFE UI Login Screen](/img/CSM_walkthrough1.png) + +After giving the Safe a name and selecting the appropriate network, continue by clicking the **Next** button. + +![Create SAFE UI](/img/CSM_walkthrough2.png) + +Add all the signer addresses of the cluster members, select a threshold, and proceed to the final step by clicking the **Next** button. + +:::tip +Don't require 100% of signers to approve transactions, in case someone loses access to their address. Using the same [threshold](../../learn/intro/key-concepts.md#distributed-validator-threshold) as your cluster will use is a reasonable starting point. +::: + +![Setting SAFE Threshold](/img/CSM_walkthrough3.png) + +Finally, submit the transaction to create the Safe by clicking on the **Create** button. + +![Creating the SAFE](/img/CSM_walkthrough4.png) + +### Deploy the Splitter Contract + +The squad leader should obtain the reward addresses from all the cluster members (if members want to use a distinct address to the one they sign with for receiving rewards). Open https://app.splits.org and create a `New contract`. Make sure to select the appropriate network. + +![Choosing Network](/img/CSM_walkthrough5.png) + +Select `Split` for the contract type. + +![Selecting Split Contract](/img/CSM_walkthrough6.png) + +Add the reward addresses of all cluster members. Choose whether the contract is immutable (reccommended option), whether to sponsor the maintainers of [splits.org](https://splits.org), and optionally whether to set a distribution bounty such that third parties could pay the gas costs of distributing the accrued rewards in exchange for a small fee. + +:::tip +If your cluster would like to contribute a portion of its rewards to Obol’s '[1% for Decentralisation](https://blog.obol.org/1-percent-for-decentralisation/)' Retroactive Fund, thereby earning [Obol Contributions](https://obol.org/contributions) as part of Lido's [integration of CSM](https://research.lido.fi/t/integrate-csm-into-the-decentralized-validator-vault/8621) into the DV Vault, you must add [retroactivefunding.obol.eth](https://etherscan.io/address/0xDe5aE4De36c966747Ea7DF13BD9589642e2B1D0d) as a recipient of 0.1% of the splitter contract. This will contribute 0.1% of rewards **and your CSM bond** to Obol's RAF. Future versions of CSM integrations will enable contributing exactly 1% of accruing CSM rewards. +::: + +![Adding recipients](/img/CSM_walkthrough7.png) + +Finally, click the **Create Split** button, execute the transaction and share the created split contract with all cluster members for review. + + +## Part 2: Use the DV Launchpad + CLI to create the cluster keys + +`Charon` is the middleware client that enables validators to be run by a group of independent node operators - a cluster or squad. A complete multi-container `Docker` setup including execution client, consensus client, validator client, MEV-Boost, the `Charon` client and monitoring tools can be found in [this repository](https://github.com/ObolNetwork/charon-distributed-validator-node). + + +### Step 1: Clone the repo + +```sh +git clone https://github.com/ObolNetwork/charon-distributed-validator-node.git +``` + +### Step 2: Create ENR and Backup your Private Key + +Enter the CDVN directory: + +```sh +cd charon-distributed-validator-node +``` + +Use docker to create an ENR + +```sh +docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:v1.1.2 create enr +``` + +### Back up the private key located in `.charon/charon-enr-private-key` + +![Creating a charon ENR key pair](/img/CSM_walkthrough8.png) + +:::caution +What you see in the console starting with `enr:-` is the **public key** for your Charon node (known as an ENR). The **private key** is in the file `.charon/charon-enr-private-key`, be sure to back it up securely. +::: + + +### Step 3: Create the DV cluster configuration using the Launchpad + +Obol has integrated a CSM details into the DV Launchpad. Choosing the "Lido CSM" withdrawal configuration allows you to create up to 12 validator keys (CSM's Early Access limit) with Lido's required withdrawal and fee recipient addresses. + +To start, the squad leader opens the [DV Launchpad](https://launchpad.obol.org), then connects their wallet and chooses **Create a cluster with a group**. + +![DV Launchpad Home Page](/img/CSM_walkthrough9.png) + +Then click **Get Started**. + +![Creation Summary Screen](/img/CSM_walkthrough10.png) + +Accept all the necessary advisories and sign to confirm. + +![Obol Warnings, Terms, and Advisories](/img/CSM_walkthrough11.png) + +Cluster configuration begins next. First, select the cluster name and size, then enter all cluster members signer addresses. + +![Configure Cluster Page](/img/CSM_walkthrough12.png) + +- Select the number of validators to create (CSM's Early Access phase is capped at a maximum 12 validators). +- (If the cluster creator is taking part in the cluster) Enter your Charon node's ENR which was generated during [step 2](#step-2-create-enr-and-backup-your-private-key) above. +- In the **Withdrawal Configuration** field, select `LIDO CSM`. This will automatically fill the required Withdrawal Address and Fee Recipient Addresss per [Lido's Documentation](https://operatorportal.lido.fi/modules/community-staking-module#block-d8e94f551b2e47029a54e6cedea914a7). +- Finally, click on the **Create Cluster Configuration** button. + +![Further Cluster Configuration](/img/CSM_walkthrough13.png) + +Lastly, share the cluster invite link with the other cluster members. + +![Cluster Invitation Page](/img/CSM_walkthrough14.png) + + +### Step 4: Distributed Key Generation (DKG) + +All squad members need to open the cluster invitation link, connect their wallet, accept all necessary advisories, and to verify the cluster configuration is correct with a signature. Each squad member will also need to upload and sign an ENR to represent their charon client, so see [steps 1](#step-1-clone-the-repo) and [2](#step-2-create-enr-and-backup-your-private-key) above. + +![Cluster Invitation Acceptance Page](/img/CSM_walkthrough15.png) + +Once all members confirm the configuration they will see the **Continue** button. + +![Prepare for DKG Page](/img/CSM_walkthrough16.png) + +On the next page, they will find a CLI command which is used to begin the Distributed Key Generation (DKG) ceremony. All members need to synchronously complete this step. + +![DKG Command to Run](/img/CSM_walkthrough17.png) + +:::tip +Go back to the terminal and make sure you're in the `charon-distributed-validator-node` directory before running the DKG command: + +```sh +pwd +``` + +If you are not, navigate to it using the `cd` command. +::: + +Paste the DKG command into your terminal and wait for all the other squad members to connect and complete the DKG ceremony. + +![Completed DKG CLI Output](/img/CSM_walkthrough18.png) + +New files were generated: `cluster-lock.json`, `deposit-data.json`, `validator_keys` are all found in the `.charon` folder (hidden by default). This contains each operator's partial key signatures for the validators. + +:::danger +At this point, **each operator must make a backup of the `.charon` folder and keep it safe, as validator keys cannot be recreated if lost**. +::: + +### Step 5: Create a `.env` file for Mainnet + +Copy and rename the `.env.sample.mainnet` file to `.env` + +```sh +cp .env.sample.mainnet .env +``` + +Open the `.env` file using you favourite editor: + +```sh +nano .env +``` + +Uncomment and set `BUILDER_API_ENABLED=true`. + +Uncomment `MEVBOOST_RELAYS=` and set it to the URL of at least one of Lido's approved MEV relays [here](https://enchanted-direction-844.notion.site/6d369eb33f664487800b0dedfe32171e?v=8e5d1f1276b0493caea8a2aa1517ed65). Multiple relays must be separated by a comma. Consult our [deployment best practices](../../run/prepare/deployment-best-practices.md#mev-boost-relays) for further info on MEV relay selection. + + +### Step 6: Starting the Node + +Each cluster member should start the node with the following command: + +```sh +docker compose up -d +``` + +At this point, execution and consensus clients should start syncing. Charon and the validator client should start waiting for the consensus client to be synced and the validator to be activated. + + +## Part 3: Upload the public keys and deposit to Lido CSM + +CSM is launching with a whitelisted set of approved operators (Early Access). The squad member with EA should be the one to create the node through the CSM widget. + +The EA member will head to [CSM Extended Mode](https://csm.lido.fi/?mode=extended) and connect their wallet. (Note the `mode=extended` parameter.) This allows the Lido CSM reward address to be set to the split contract created earlier. + +![CSM Connect Wallet Modal](/img/CSM_walkthrough19.png) + +The EA member clicks on the **Create Node Operator** button. + +![CSM Create Node Operator Modal](/img/CSM_walkthrough20.png) + +- The EA member pastes the contents of the `deposit-data.json` file into the `Upload deposit data` field. The EA member should have enough ETH/stETH/wstETH to cover the bond. + +- Expand the **Specify custom addresses** section. + + - Set the **Reward Address** field to the `Split` contract address and the **Manager Address** field to the `Safe` wallet address. (These were created previously in [part 1](#part-1-creating-the-cluster-safe--splitter-contract)) + + - Verify that the **Extended** box is outlined. This ensures that the `Safe` address has the ability to change the reward address if necessary. + +- Check that the correct addresses are set and click the **Create Node Operator** button. + +![CSM Extended Mode Settings](/img/CSM_walkthrough21.png) + +Sign the transaction. The cluster is ready for deposit from Lido CSM. At this point, your job is finished. + +:::warning +When claiming your cluster's rewards, **be sure to claim in wstETH only** (Wrapped Staked Ether). Ether withdrawal gives you an NFT that is not compatible with a splitter, while a rebasing token like stETH may not receive the incremental yield you’re expecting. More information can be found in the [splits.org documentation](https://docs.splits.org/core/split#how-it-works). +::: diff --git a/docs/guides/walkthroughs/_category_.json b/docs/guides/walkthroughs/_category_.json new file mode 100644 index 0000000000..826aab8320 --- /dev/null +++ b/docs/guides/walkthroughs/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Walkthroughs", + "position": 1, + "collapsed": true +} diff --git a/docs/guides/walkthroughs/walkthrough-guides.md b/docs/guides/walkthroughs/walkthrough-guides.md new file mode 100644 index 0000000000..0352127778 --- /dev/null +++ b/docs/guides/walkthroughs/walkthrough-guides.md @@ -0,0 +1,10 @@ +--- +sidebar_position: 1 +description: Walkthrough guides. +--- + +# Walkthrough guides + +This section contains walkthrough guides for beginner users. Some of these guides are specific to particular hardware or operating systems, and may not replace more general documentation. These guides contain more detailed step-by-step information which may be useful for beginner users with limited experience with Linux, validators, and other topics which the primary guides assume some prior familiarity of. + +Some of these guides are community-created, and may contain issues or omissions. diff --git a/docs/learn/_category_.json b/docs/learn/_category_.json new file mode 100644 index 0000000000..e2c3c6e4e0 --- /dev/null +++ b/docs/learn/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "LEARN", + "position": 1, + "collapsed": false, + "collapsible": false, + "className": "menuSection" +} \ No newline at end of file diff --git a/docs/charon/_category_.json b/docs/learn/charon/_category_.json similarity index 72% rename from docs/charon/_category_.json rename to docs/learn/charon/_category_.json index 08dc9cc73c..08cbf7c7eb 100644 --- a/docs/charon/_category_.json +++ b/docs/learn/charon/_category_.json @@ -1,5 +1,5 @@ { "label": "Charon", - "position": 5, + "position": 2, "collapsed": true } diff --git a/docs/charon/charon-cli-reference.md b/docs/learn/charon/charon-cli-reference.md similarity index 97% rename from docs/charon/charon-cli-reference.md rename to docs/learn/charon/charon-cli-reference.md index 339d6c834a..61e41c02a2 100644 --- a/docs/charon/charon-cli-reference.md +++ b/docs/learn/charon/charon-cli-reference.md @@ -75,7 +75,7 @@ Flags: ### Create a full cluster locally -The `charon create cluster` command creates a set of distributed validators locally; including the private keys, a `cluster-lock.json` file, and deposit data. This command should only be used for solo-operation of distributed validators. To run a distributed validator cluster with a group of operators, it is preferable to create these artifacts using the [DV Launchpad](../dvl/intro.md) and the `charon dkg` command. That way, no single operator custodies all of the private keys to a distributed validator. +The `charon create cluster` command creates a set of distributed validators locally; including the private keys, a `cluster-lock.json` file, and deposit data. This command should only be used for solo-operation of distributed validators. To run a distributed validator cluster with a group of operators, it is preferable to create these artifacts using the [DV Launchpad](../../learn/intro/launchpad.md) and the `charon dkg` command. That way, no single operator custodies all of the private keys to a distributed validator. :::warning This command produces new distributed validator private keys or handles and splits pre-existing traditional validator private keys, please use caution and keep these private keys securely backed up and secret. @@ -235,7 +235,7 @@ Flags: ## The `exit` command -A running Charon client will [aggregate and broadcast](../start/quickstart-exit.mdx) signed exit messages it receives from its valdiator client immediately. These `exit` commands are instead used to *pre-sign* exit messages for an active distributed validator, to save to disk, or to broadcast; once enough of the operators of the cluster have submitted their partial exit signatures. Fully signed exit messages give a user or protocol a guarantee that they can exit an active validator at any point in future without the further assistance of the cluster's operators. In future, [execution-layer initiated exits](https://eips.ethereum.org/EIPS/eip-7002) will provide an even stronger guarantee that a validator can be exited by the withdrawal address it belongs to. +A running Charon client will [aggregate and broadcast](../../run/running/quickstart-exit.mdx) signed exit messages it receives from its valdiator client immediately. These `exit` commands are instead used to *pre-sign* exit messages for an active distributed validator, to save to disk, or to broadcast; once enough of the operators of the cluster have submitted their partial exit signatures. Fully signed exit messages give a user or protocol a guarantee that they can exit an active validator at any point in future without the further assistance of the cluster's operators. In future, [execution-layer initiated exits](https://eips.ethereum.org/EIPS/eip-7002) will provide an even stronger guarantee that a validator can be exited by the withdrawal address it belongs to. ```markdown charon exit --help @@ -485,7 +485,7 @@ Flags: --p2p-tcp-address strings Comma-separated list of listening TCP addresses (ip and port) for libP2P traffic. Empty default doesn't bind to local port therefore only supports outgoing connections. ``` -You can also consider adding [alternative public relays](../faq/risks.md) to your cluster by specifying a list of `p2p-relays` in [`charon run`](#run-the-charon-middleware). +You can also consider adding [alternative public relays](../../adv/security/risks.md) to your cluster by specifying a list of `p2p-relays` in [`charon run`](#run-the-charon-middleware). ## Experimental commands diff --git a/docs/charon/cluster-configuration.md b/docs/learn/charon/cluster-configuration.md similarity index 100% rename from docs/charon/cluster-configuration.md rename to docs/learn/charon/cluster-configuration.md diff --git a/docs/charon/dkg.md b/docs/learn/charon/dkg.md similarity index 95% rename from docs/charon/dkg.md rename to docs/learn/charon/dkg.md index fa06e69cd9..322a0016a4 100644 --- a/docs/charon/dkg.md +++ b/docs/learn/charon/dkg.md @@ -7,11 +7,11 @@ sidebar_position: 2 ## Overview -A [**distributed validator key**](../int/key-concepts.md#distributed-validator-key) is a group of BLS private keys that together operate as a threshold key for participating in proof-of-stake consensus. +A [**distributed validator key**](../../learn/intro/key-concepts.md#distributed-validator-key) is a group of BLS private keys that together operate as a threshold key for participating in proof-of-stake consensus. -To make a distributed validator with no fault-tolerance (i.e. all nodes need to be online to sign every message), due to the BLS signature scheme used by Proof of Stake Ethereum, each key share could be chosen by operators independently. However, to create a distributed validator that can stay online despite a subset of its nodes going offline, the key shares need to be generated together (4 randomly chosen points on a graph don't all necessarily sit on the same order three curve). To do this in a secure manner with no one party being trusted to distribute the keys requires what is known as a [**distributed key generation ceremony**](../int/key-concepts.md#distributed-validator-key-generation-ceremony). +To make a distributed validator with no fault-tolerance (i.e. all nodes need to be online to sign every message), due to the BLS signature scheme used by Proof of Stake Ethereum, each key share could be chosen by operators independently. However, to create a distributed validator that can stay online despite a subset of its nodes going offline, the key shares need to be generated together (4 randomly chosen points on a graph don't all necessarily sit on the same order three curve). To do this in a secure manner with no one party being trusted to distribute the keys requires what is known as a [**distributed key generation ceremony**](../../learn/intro/key-concepts.md#distributed-validator-key-generation-ceremony). -The Charon client has the responsibility of securely completing a distributed key generation ceremony with its counterparty nodes. The ceremony configuration is outlined in a [cluster definition](../charon/cluster-configuration.md). +The Charon client has the responsibility of securely completing a distributed key generation ceremony with its counterparty nodes. The ceremony configuration is outlined in a [cluster definition](../../learn/charon/cluster-configuration.md). ## Actors Involved diff --git a/docs/charon/intro.md b/docs/learn/charon/intro.md similarity index 97% rename from docs/charon/intro.md rename to docs/learn/charon/intro.md index 03e30a5574..cedf4b913b 100644 --- a/docs/charon/intro.md +++ b/docs/learn/charon/intro.md @@ -3,9 +3,9 @@ description: Charon - The Distributed Validator Client sidebar_position: 1 --- -# Introduction +# Introduction to Charon -This section introduces and outlines the Charon *[kharon]* middleware, Obol's implementation of DVT. Please see the [key concepts](../int/key-concepts.md) section as background and context. +This section introduces and outlines the Charon *[kharon]* middleware, Obol's implementation of DVT. Please see the [key concepts](../../learn/intro/key-concepts.md) section as background and context. ## What is Charon? @@ -86,4 +86,4 @@ The following is an outline of the services that can be exposed by Charon. ## Getting started -For more information on running Charon, take a look at our [Quickstart Guides](../start/quickstart_overview.md). +For more information on running Charon, take a look at our [Quickstart Guides](../../run/start/quickstart_overview.md). diff --git a/docs/charon/networking.mdx b/docs/learn/charon/networking.mdx similarity index 98% rename from docs/charon/networking.mdx rename to docs/learn/charon/networking.mdx index c2cbb5acf4..16eb429cac 100644 --- a/docs/charon/networking.mdx +++ b/docs/learn/charon/networking.mdx @@ -29,7 +29,7 @@ The Charon clients in a DV cluster are connected to each other via a small p2p n discovered via an external "relay" server. The p2p connections are over the public internet so the Charon p2p port must be publicly accessible. Charon leverages the popular [libp2p](https://libp2p.io/) protocol. -Related [Charon configuration flags](docs/charon/charon-cli-reference.md): +Related [Charon configuration flags](../../learn/charon/charon-cli-reference.md): - `--p2p-tcp-addresses`: Addresses for Charon to listen on and serve p2p requests. - `--p2p-relays`: Connect Charon to one or more relay servers. diff --git a/docs/fr/_category_.json b/docs/learn/futher-reading/_category_.json similarity index 75% rename from docs/fr/_category_.json rename to docs/learn/futher-reading/_category_.json index 427bf9a141..c2df0de9cb 100644 --- a/docs/fr/_category_.json +++ b/docs/learn/futher-reading/_category_.json @@ -1,5 +1,5 @@ { "label": "Further reading", - "position": 10, + "position": 3, "collapsed": true } diff --git a/docs/fr/ethereum_and_dvt.md b/docs/learn/futher-reading/ethereum_and_dvt.md similarity index 99% rename from docs/fr/ethereum_and_dvt.md rename to docs/learn/futher-reading/ethereum_and_dvt.md index c2458e84b8..61c8b1ccdf 100644 --- a/docs/fr/ethereum_and_dvt.md +++ b/docs/learn/futher-reading/ethereum_and_dvt.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 1 description: Ethereum and its relationship with DVT --- diff --git a/docs/faq/peer_score.md b/docs/learn/futher-reading/peer_score.md similarity index 99% rename from docs/faq/peer_score.md rename to docs/learn/futher-reading/peer_score.md index b12e9782d0..8cde00e6d1 100644 --- a/docs/faq/peer_score.md +++ b/docs/learn/futher-reading/peer_score.md @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 3 description: Measuring Individual Performance in Distributed Validators --- diff --git a/docs/fr/resources.md b/docs/learn/futher-reading/resources.md similarity index 82% rename from docs/fr/resources.md rename to docs/learn/futher-reading/resources.md index 851b126b11..c0e1487097 100644 --- a/docs/fr/resources.md +++ b/docs/learn/futher-reading/resources.md @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 4 description: A collection of links to products and content relating to Distributed Validators. --- @@ -26,22 +26,22 @@ The following is a curated list of the best internal and external resources for - [Terraform Grafana Charon dashboards](https://github.com/ObolNetwork/terraform-grafana-dashboards) ## Quickstart Guides -- [Run a DV alone](https://docs.obol.org/docs/start/quickstart_alone) -- [Run a DV as a group](https://docs.obol.org/docs/start/quickstart_group) -- [Run a DV using the SDK](https://docs.obol.org/docs/advanced/quickstart-sdk) +- [Run a DV alone](../../../docs/run/start/quickstart_alone.mdx) +- [Run a DV as a group](../../../docs/run/start/quickstart_group.mdx) +- [Run a DV using the SDK](../../../docs/adv/advanced/quickstart-sdk.mdx) ## Security and Best Practices - [Audits](https://github.com/ObolNetwork/obol-security/tree/main/audits) - [Security repo](https://github.com/ObolNetwork/obol-security) -- [Security Docs Page](https://docs.obol.org/docs/sec/overview) -- [Best practices doc](https://docs.obol.org/docs/advanced/deployment-best-practices) +- [Security Docs Page](../../../docs/adv/security/overview.md) +- [Best practices doc](../../../docs/run/prepare/deployment-best-practices.md) - [Status Page](https://status.obol.org/) ## Security Audits and Assessments -- A [review](https://docs.obol.tech/docs/sec/ev-assessment) of Obol Labs development processes by Ethereal Ventures +- A [review](../../../docs/adv/security/ev-assessment.md) of Obol Labs development processes by Ethereal Ventures - A [security assessment](https://github.com/ObolNetwork/obol-security/blob/f9d7b0ad0bb8897f74ccb34cd4bd83012ad1d2b5/audits/Sigma_Prime_Obol_Network_Charon_Security_Assessment_Report_v2_1.pdf) of Charon by [Sigma Prime](https://sigmaprime.io/). -- A [solidity audit](https://docs.obol.tech/docs/sec/smart_contract_audit) of the Obol Splits contracts by [Zach Obront](https://zachobront.com/). -- [Charon Threat model](https://docs.obol.org/docs/sec/threat_model) +- A [solidity audit](../../../docs/adv/security/smart_contract_audit.mdx) of the Obol Splits contracts by [Zach Obront](https://zachobront.com/). +- [Charon Threat model](../../../docs/adv/security/threat_model.md) - [QuantStamp Charon audit Q4 2023](https://obol.tech/charon_quantstamp_assessment.pdf) ## Research and Development diff --git a/docs/fr/testnet.md b/docs/learn/futher-reading/testnet.md similarity index 99% rename from docs/fr/testnet.md rename to docs/learn/futher-reading/testnet.md index 7b2c01d40c..c763618420 100644 --- a/docs/fr/testnet.md +++ b/docs/learn/futher-reading/testnet.md @@ -1,12 +1,12 @@ --- -sidebar_position: 5 +sidebar_position: 2 description: Community testing efforts --- # Community Testing :::tip -This page looks at the community testing efforts organised by Obol to test Distributed Validators at scale. If you are looking for guides to run a Distributed Validator on testnet you can do so [here](../start/quickstart_overview.md). +This page looks at the community testing efforts organised by Obol to test Distributed Validators at scale. If you are looking for guides to run a Distributed Validator on testnet you can do so [here](../../run/start/quickstart_overview.md). ::: Over the last number of years, DV Labs has coordinated and hosted progressively larger testing efforts to help harden the Charon client and iterate on the key generation tooling. diff --git a/docs/int/_category_.json b/docs/learn/intro/_category_.json similarity index 69% rename from docs/int/_category_.json rename to docs/learn/intro/_category_.json index 096f399e09..baa4b331b2 100644 --- a/docs/int/_category_.json +++ b/docs/learn/intro/_category_.json @@ -1,5 +1,5 @@ { "label": "Introduction", "position": 1, - "collapsed": false + "collapsed": true } diff --git a/docs/faq/general.mdx b/docs/learn/intro/faq.mdx similarity index 92% rename from docs/faq/general.mdx rename to docs/learn/intro/faq.mdx index 9114c78994..233a6d1694 100644 --- a/docs/faq/general.mdx +++ b/docs/learn/intro/faq.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +sidebar_position: 6 description: Frequently asked questions --- @@ -120,7 +120,7 @@ Charon alone uses negligible disk space of not more than a few MBs. However, if For more hardware considerations, check out the [ethereum.org guides](https://ethereum.org/en/developers/docs/nodes-and-clients/run-a-node/#environment-and-hardware) which explores various setups and trade-offs, such as running the node locally or in the cloud. -For now, Geth, Teku & Lighthouse clients are packaged within the docker compose file provided in the [quickstart guides](../start/quickstart_overview.md), so you don't have to install anything else to run a cluster. Just make sure you give them some time to sync once you start running your node. +For now, Geth, Teku & Lighthouse clients are packaged within the docker compose file provided in the [quickstart guides](../../run/start/quickstart_overview.md), so you don't have to install anything else to run a cluster. Just make sure you give them some time to sync once you start running your node. ### What is the difference between a node, a validator and a cluster? @@ -140,7 +140,7 @@ It is possible to migrate your Charon node to another machine running the same c Currently, the minimum is 4 operators with a threshold of 3. -The threshold (aka quorum) corresponds to the minimum numbers of operators that need to be active for the validator(s) to be able to perform its duties. It is defined by the following formula `n-(ceil(n/3)-1)`. We strongly recommend using this default threshold in your DKG as it maximises liveness while maintaining BFT safety. Setting a 4 out of 4 cluster for example, would make your validator more vulnerable to going offline instead of less vulnerable. You can check the recommended threshold values for a cluster [here](../int/key-concepts.md#distributed-validator-threshold). +The threshold (aka quorum) corresponds to the minimum numbers of operators that need to be active for the validator(s) to be able to perform its duties. It is defined by the following formula `n-(ceil(n/3)-1)`. We strongly recommend using this default threshold in your DKG as it maximises liveness while maintaining BFT safety. Setting a 4 out of 4 cluster for example, would make your validator more vulnerable to going offline instead of less vulnerable. You can check the recommended threshold values for a cluster [here](../../learn/intro/key-concepts.md#distributed-validator-threshold). ## Obol Splits @@ -158,7 +158,7 @@ Generally Obol Splits are deployed in an immutable fashion, meaning you cannot e ### How do Obol Splits work? -You can read more about how Obol Splits work [here](../sc/introducing-obol-splits.mdx). +You can read more about how Obol Splits work [here](../../learn/intro/obol-splits.mdx). ### Are Obol Splits open source? @@ -166,7 +166,7 @@ Yes, Obol Splits are licensed under GPLv3 and the source code is available [here ### Are Obol Splits audited? -The Obol Splits contracts have been audited, though further development has continued on the contracts since. Consult the audit results [here](../sec/smart_contract_audit.mdx). +The Obol Splits contracts have been audited, though further development has continued on the contracts since. Consult the audit results [here](../../adv/security/smart_contract_audit.mdx). ### Are the Obol Splits contracts verified on Etherscan? @@ -180,10 +180,10 @@ No. Any address can trigger the contracts to move the funds, they do not need to The most important decision is to be aware of whether or not the Split contract you are using has been set up with editability. If a splitter is editable, you should understand what the address that can edit the split does. Is the editor an EOA? Who controls that address? How secure is their seed phrase? Is it a smart contract? What can that contract do? Can the controller contract be upgraded? etc. Generally, the safest thing in Obol's perspective is not to have an editable splitter, and if in future you are unhappy with the configuration, that you exit the validator and create a fresh cluster with new settings that fit your needs. -Another aspect to be aware of is how the splitting of principal from rewards works using the Optimistic Withdrawal Recipient contract. There are edge cases relating to not calling the contracts periodically or ahead of a withdrawal, activating more validators than the contract was configured for, and a worst case mass slashing on the network. Consult the documentation on the contract [here](../sc/introducing-obol-splits.mdx#optimistic-withdrawal-recipient), its audit [here](../sec/smart_contract_audit.mdx), and follow up with the core team if you have further questions. +Another aspect to be aware of is how the splitting of principal from rewards works using the Optimistic Withdrawal Recipient contract. There are edge cases relating to not calling the contracts periodically or ahead of a withdrawal, activating more validators than the contract was configured for, and a worst case mass slashing on the network. Consult the documentation on the contract [here](../../learn/intro/obol-splits.mdx#optimistic-withdrawal-recipient), its audit [here](../../adv/security/smart_contract_audit.mdx), and follow up with the core team if you have further questions. ## Debugging Errors in Logs You can check if the containers on your node are outputting errors by running `docker compose logs` on a machine with a running cluster. -Diagnose some common errors and view their resolutions [here](../faq/errors.mdx). +Diagnose some common errors and view their resolutions [here](../../adv/troubleshooting/errors.mdx). diff --git a/docs/int/key-concepts.md b/docs/learn/intro/key-concepts.md similarity index 99% rename from docs/int/key-concepts.md rename to docs/learn/intro/key-concepts.md index 0c0e84039b..fabc99d298 100644 --- a/docs/int/key-concepts.md +++ b/docs/learn/intro/key-concepts.md @@ -3,7 +3,7 @@ sidebar_position: 2 description: Some of the key terms in the field of Distributed Validator Technology --- -# Key concepts +# Key staking concepts This page outlines a number of the key concepts behind the various technologies that Obol is developing. @@ -14,7 +14,6 @@ This page outlines a number of the key concepts behind the various technologies A distributed validator is an Ethereum proof-of-stake validator that runs on more than one node/machine. This functionality is possible with the use of **Distributed Validator Technology** (DVT). Distributed validator technology removes some of the single points of failure in validation. Should <33% of the participating nodes in a DV cluster go offline, the remaining active nodes can still come to consensus on what to sign and can produce valid signatures for their staking duties. This is known as Active/Active redundancy, a common pattern for minimizing downtime in mission critical systems. -​ ## Distributed Validator Node diff --git a/docs/dvl/intro.md b/docs/learn/intro/launchpad.md similarity index 96% rename from docs/dvl/intro.md rename to docs/learn/intro/launchpad.md index 9ad7bcba07..92e2a9c246 100644 --- a/docs/dvl/intro.md +++ b/docs/learn/intro/launchpad.md @@ -1,6 +1,6 @@ --- description: A dapp to securely create Distributed Validators alone or with a group. -sidebar_position: 6 +sidebar_position: 5 --- # DV Launchpad @@ -15,7 +15,7 @@ To facilitate the generation of distributed validator keys amongst remote users ## Getting started -For more information on running Charon in a UI friendly way through the DV Launchpad, take a look at our [Quickstart Guides](../start/quickstart_overview.md). +For more information on running Charon in a UI friendly way through the DV Launchpad, take a look at our [Quickstart Guides](../../run/start/quickstart_overview.md). ## DV Launchpad Links diff --git a/docs/int/Overview.md b/docs/learn/intro/obol-collective.md similarity index 60% rename from docs/int/Overview.md rename to docs/learn/intro/obol-collective.md index dba72f3dec..78bbaf126d 100644 --- a/docs/int/Overview.md +++ b/docs/learn/intro/obol-collective.md @@ -1,9 +1,9 @@ --- sidebar_position: 1 -description: An overview of the Obol network +description: The Obol Collective --- -# Overview of Obol +# Obol Collective ## What is the Obol Collective? @@ -26,27 +26,9 @@ Similar to how roll-up technology laid the foundation for L2 scaling implementat Obol is inspired by previous work on Ethereum public goods and experimenting with circular economics. We believe that to unlock innovation in staking use cases, a [credibly neutral](https://blog.obol.org/why-we-built-charon-as-a-middleware/) layer must exist for innovation to flow and evolve vertically. The Obol staking stack consists of four core public goods: The Obol Network consists of four core public goods: -- [Charon](../charon/intro.md), a middleware client that enables validators to run in a fault-tolerant, distributed manner; -- The [Distributed Validator Launchpad](../dvl/intro.md), a user interface for configuring Distributed Validators; -- [Obol Splits](../sc/introducing-obol-splits.mdx), a set of solidity smart contracts for the distribution of rewards from Distributed Validators; -- Obol [SDK](../sdk/index.md) & [API](https://docs.obol.org/api), allowing Distributed Validator clusters to be configured and run at scale, for example within staking protocols. +- [Charon](../../learn/charon/intro.md), a middleware client that enables validators to run in a fault-tolerant, distributed manner; +- The [Distributed Validator Launchpad](../../learn/intro/launchpad.md), a user interface for configuring Distributed Validators; +- [Obol Splits](../../learn/intro/obol-splits.mdx), a set of solidity smart contracts for the distribution of rewards from Distributed Validators; +- Obol [SDK](../../sdk/index.md) & [API](https://docs.obol.org/api), allowing Distributed Validator clusters to be configured and run at scale, for example within staking protocols. The [launch of the Obol Collective](https://blog.obol.org/announcing-the-obol-collective/) began the journey to becoming an open, community governed, self-sustaining project. Together we will incentivize, build, and maintain distributed validator technology that makes public networks a more secure and resilient foundation to build on top of. Read more about our economic model in our [One Percent For Decentralisation](https://blog.obol.tech/1-percent-for-decentralisation/) announcement. - -## The Vision - -The road to decentralizing stake is a long one. At Obol we have divided our vision into two key versions of distributed validators. - -### V1 - Trusted Distributed Validators - -![Multi Operator DV Cluster](/img/MultiOperator7.png) - -The first version of distributed validators will have dispute resolution out of band. Meaning you need to know and communicate with your other operators if there is an issue with your shared cluster. - -A DV without in-band dispute resolution/incentivisation is still extremely valuable. Individuals and staking as a service providers can deploy DVs on their own to make their validators fault tolerant. Groups can run DVs together, but need to bring their own dispute resolution to the table, whether that be a smart contract of their own, a traditional legal service agreement, or simply high trust between the group. - -### V2 - Trustless Distributed Validators - -As described in our [roadmap blog article](https://blog.obol.org/roadmap-the-distributed-validator-protocol/) published in February 2024, Version 2 of Charon will layer in a (dis)incentivisation scheme to solve the “lazy operator” problem, whereby an offline operator within a DV cluster does not earn any rewards. Further incentivisation alignment can be achieved with operator bonding requirements that can be slashed for unacceptable performance. - -To add an un-gameable incentivisation layer to threshold validation requires complex interactive cryptography schemes, secure off-chain dispute resolution, and EVM support for proofs of the consensus layer state, as a result, this will be a longer and more complex undertaking than V1, hence the delineation between the two. Some of the published R&D material is available in the [further reading](https://docs.obol.org/docs/next/fr/resources#research-and-development) section of the docs. \ No newline at end of file diff --git a/docs/sc/introducing-obol-splits.mdx b/docs/learn/intro/obol-splits.mdx similarity index 99% rename from docs/sc/introducing-obol-splits.mdx rename to docs/learn/intro/obol-splits.mdx index 901d59c8ea..685931d6aa 100644 --- a/docs/sc/introducing-obol-splits.mdx +++ b/docs/learn/intro/obol-splits.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +sidebar_position: 4 description: Smart contracts for managing Distributed Validators --- diff --git a/docs/learn/intro/obol-vs-others.md b/docs/learn/intro/obol-vs-others.md new file mode 100644 index 0000000000..cc070a4769 --- /dev/null +++ b/docs/learn/intro/obol-vs-others.md @@ -0,0 +1,62 @@ +--- +sidebar_position: 2 +description: Some of the key terms in the field of Distributed Validator Technology +--- + +# Obol vs Other DV Implementations + +This page outlines the unique features of Obol's DV implemenation, constrasting with other DV implementations. We built Obol’s DVT as a middleware to keep Ethereum secure, resilient, and composable. See also the blog article [Why We Built Charon as a Middleware](https://blog.obol.org/why-we-built-charon-as-a-middleware/). + +![Obol vs others table](/img/ObolvsOthers.png) + +## No private keys put on chain + +Obol's distributed key generation (DKG) event generates key shares for each node within the DV cluster. The entire validator key NEVER exists in one place. Keys are generated locally on the nodes, and can be backed up. The private keys of Obol DVs are NEVER uploaded to the internet or published on-chain. + +An alternative approach to doing this is to split it into shares, encrypt each share with the public key of a node operator, and publish the encrypted private key on chain. The operators’ node key could then decrypt the validator private key. In our opinion, this is not secure. We believe that the safest approach is to avoid the existence of a singular private key, and certainly never to post any private key to a public blockchain network. + +## Cluster independance: Clusters can upgrade independently + +In an Obol DV cluster, nodes use LibP2P to communicate directly with each other, and communications are end-to-end encrypted with TLS. Clusters are independent from one another, can run different versions of Charon, and don't need to upgrade together. This means that when a new version of Obol’s Charon is released, Obol DV clusters can upgrade on their own time, individually from other DV clusters. Charon will NEVER require a hard fork or simultaneous updates across clusters for any upgrades. + +![Cluster Independence](/img/ClusterIndependence.png) + +## Cluster independance: No reliance on a common P2P gossip network + +In an Obol DV cluster, nodes use LibP2P to communicate directly with each other, and communications are end-to-end encrypted with TSL. This direct communication of nodes within a cluster improves latency, and makes cluster communications harder to attack with a denial of service (DOS) attack. It also allows an Obol DV cluster to be run within a private network. This may allow cost savings on data egress costs, for operators running cluster nodes across multiple locations of a single cloud provider, for example. + +For other DVT implementations, each DV cluster communicates with every other cluster, creating a large, cumbersome gossip network. This limits scaling and requires the nodes of every DV cluster to run the same version. A drawback: the public gossip network relies on nodes to voluntarily open their ports and participate in peering and gossip, resulting in higher data egress costs, since each node is relaying many more messages than only the ones related to that node’s cluster. This may require some type of artificial incentivization to encourage nodes to participate in gossip messaging. In the event that nodes don’t broadly participate in peering, it may be necessary for the network developers to run a central messaging relayer in order to support the gossip network and ensure continued performance between all gossip nodes. (The costs associated with this central relaying would somehow need to be passed onto the network operators and users.) + +![Gossip Network](/img/GossipNetwork.png) + +## Works with existing validator clients and PKI + +We built Obol’s DV implementation as a secure and trust-minimised middleware architecture. Our middleware client, Charon, doesn’t replace anything in the client stack, instead it sits between the consensus and validator clients. Node operators integrating the Charon DVT middleware into their stack can continue to use the same clients and private key infrastructure as before, albeit with a different key generation method. + +The alternative approach to DV design is to replace the validator client with a DV-native client, which has custody of the private keys and the capability to sign arbitrary data. However, in our opinion a full validator client capable of signing and exfiltrating arbitrary data without the oversight of a second software implementation has much higher risk of causing correlated slashing. + +![Standard VC](/img/StandardVC.png) + +This gives the benefit of having both Charon and the existing validator client as failsafes, greatly reducing the odds of unintended slashing. Even in the worst case scenario where Charon is compromised by a supply chain attack or a remote code execution attack, or the Obol team become bad actors and push a malicious release, Charon cannot do a lot of damage as a middleware. If a compromised Charon client proposes a potential double vote or surround vote for a validator to sign, the validator client will check its anti-slashing database, see that it has already signed something conflicting, and simply refuse to return a signature. Charon could propose that a validator should sign an invalid block, but the chain would reject this and simply consider the proposal missed - a much better outcome than slashing. + +## No non-ETH token risk + +Obol makes no changes to Ethereum’s standard bonding and reward mechanism, and does not require nodes to post any bonds additional to the 32 ETH required for a validator. To pay out rewards to operators, splitter contracts like [Obol Splits](../intro/obol-splits.mdx) can be used to withdraw and share rewards on a continuous basis. This allows products like liquid staking protocols to be built on top of Obol, implementing a bond or unique token into their protocol, should they choose to do so. + +![ETH only](/img/ETHonly.png) + +The alternative approach is to create a token and require stakers to pay operators in that token. This would require stakers to keep a balance of the network token ready for fee paying, in order to continue using the staking service. This mechanism would be informed by oracles, which decide when to post rewards and punish operators. This alternative model has some drawbacks. Namely, the varying price of the network’s unique token will change relative to the price of ETH: operators are not able to determine their commission as a percentage of ETH staked, and stakers likewise must consider the additional initial cost of purchasing the token to determine their long-term rate of return on their staked ETH. + +![ETH and Fee Token](/img/ETHandFee.png) + + +## Non-custodial reward splits + +(see also the [docs page on Splits](../../learn/intro/obol-splits.mdx), and the [Splits.org blog article](https://splits.org/blog/obol-ethereum-resilience/).) + +To pay out rewards to operators, splitter contracts like Obol Splits can be used to withdraw and share rewards on a continuous basis. Two key goals of validator reward management are: + 1. To be able to differentiate reward ether from principal ether such that node operators can be paid a percentage of the *reward* they accrue for the principal provider, rather than a percentage of *principal and reward*. + 2. To be able to withdraw the rewards in an ongoing manner without exiting the validator. +This allows products like liquid staking protocols to be built on top of Obol, implementing a bond or unique token into their protocol, should they choose to do so. + +![Splits OWR](/img/ObolSplits.png) diff --git a/docs/learn/intro/staking-stack.md b/docs/learn/intro/staking-stack.md new file mode 100644 index 0000000000..94b0027941 --- /dev/null +++ b/docs/learn/intro/staking-stack.md @@ -0,0 +1,31 @@ +--- +sidebar_position: 3 +description: The Obol Modular Staking Stack +--- + +# Obol's Modular Staking Stack + +## The Components + +[Charon](../charon/intro.md) - Obol's DV Middleware client. +[Obol Splits](../intro/obol-splits.mdx) - A suite of smart contracts for use with distributed validators. +[DV Launchpad](../intro/launchpad.md) - A website interface for configuring and activating distributed validators. +[Obol SDK](../../adv/advanced/quickstart-sdk.mdx) - for creating Distributed Validators with the help of the Obol API. + +## The Vision + +The road to decentralizing stake is a long one. At Obol we have divided our vision into two key versions of distributed validators. + +### V1 - Trusted Distributed Validators + +![Multi Operator DV Cluster](/img/MultiOperator7.png) + +The first version of distributed validators will have dispute resolution out of band. Meaning you need to know and communicate with your other operators if there is an issue with your shared cluster. + +A DV without in-band dispute resolution/incentivisation is still extremely valuable. Individuals and staking as a service providers can deploy DVs on their own to make their validators fault tolerant. Groups can run DVs together, but need to bring their own dispute resolution to the table, whether that be a smart contract of their own, a traditional legal service agreement, or simply high trust between the group. + +### V2 - Trustless Distributed Validators + +As described in our [roadmap blog article](https://blog.obol.org/roadmap-the-distributed-validator-protocol/) published in February 2024, Version 2 of Charon will layer in a (dis)incentivisation scheme to solve the “lazy operator” problem, whereby an offline operator within a DV cluster does not earn any rewards. Further incentivisation alignment can be achieved with operator bonding requirements that can be slashed for unacceptable performance. + +To add an un-gameable incentivisation layer to threshold validation requires complex interactive cryptography schemes, secure off-chain dispute resolution, and EVM support for proofs of the consensus layer state, as a result, this will be a longer and more complex undertaking than V1, hence the delineation between the two. Some of the published R&D material is available in the [further reading](https://docs.obol.org/next/fr/resources#research-and-development) section of the docs. \ No newline at end of file diff --git a/docs/run/_category_.json b/docs/run/_category_.json new file mode 100644 index 0000000000..a92ca5ffd7 --- /dev/null +++ b/docs/run/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "RUN A DV", + "position": 2, + "collapsed": false, + "collapsible": false, + "className": "menuSection" +} \ No newline at end of file diff --git a/docs/faq/Dappnode.mdx b/docs/run/integrations/Dappnode.mdx similarity index 98% rename from docs/faq/Dappnode.mdx rename to docs/run/integrations/Dappnode.mdx index 0eb8a8dc9f..dfa3f8d211 100644 --- a/docs/faq/Dappnode.mdx +++ b/docs/run/integrations/Dappnode.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 8 +sidebar_position: 3 description: Dappnode Frequently asked questions --- diff --git a/docs/faq/_category_.json b/docs/run/integrations/_category_.json similarity index 53% rename from docs/faq/_category_.json rename to docs/run/integrations/_category_.json index 09bd234f76..4ef344ed5e 100644 --- a/docs/faq/_category_.json +++ b/docs/run/integrations/_category_.json @@ -1,5 +1,5 @@ { - "label": "FAQ", + "label": "Partner Integrations", "position": 4, "collapsed": true } \ No newline at end of file diff --git a/docs/advanced/lido-csm.md b/docs/run/integrations/lido-csm.md similarity index 94% rename from docs/advanced/lido-csm.md rename to docs/run/integrations/lido-csm.md index 4e81b0fd79..04f094d6df 100644 --- a/docs/advanced/lido-csm.md +++ b/docs/run/integrations/lido-csm.md @@ -1,10 +1,10 @@ --- -sidebar_position: 5 +sidebar_position: 2 description: Setup and run a DV within the Lido Community Staking Module --- # Create a Lido CSM DV -This is a guide on taking part in Lido's [Community Staking Module](https://operatorportal.lido.fi/modules/community-staking-module) (CSM) with a squad as part of a [Distributed Validator Cluster](../int/key-concepts.md#distributed-validator-cluster). +This is a guide on taking part in Lido's [Community Staking Module](https://operatorportal.lido.fi/modules/community-staking-module) (CSM) with a squad as part of a [Distributed Validator Cluster](../../learn/intro/key-concepts.md#distributed-validator-cluster). To start, this guide makes a couple assumptions: @@ -41,7 +41,7 @@ After giving the Safe a name and selecting the appropriate network, continue by Add all the signer addresses of the cluster members, select a threshold, and proceed to the final step by clicking the **Next** button. :::tip -Don't require 100% of signers to approve transactions, in case someone loses access to their address. Using the same [threshold](../int/key-concepts.md#distributed-validator-threshold) as your cluster will use is a reasonable starting point. +Don't require 100% of signers to approve transactions, in case someone loses access to their address. Using the same [threshold](../../learn/intro/key-concepts.md#distributed-validator-threshold) as your cluster will use is a reasonable starting point. ::: ![Setting SAFE Threshold](/img/CSM_walkthrough3.png) @@ -187,7 +187,7 @@ nano .env Uncomment and set `BUILDER_API_ENABLED=true`. -Uncomment `MEVBOOST_RELAYS=` and set it to the URL of at least one of Lido's approved MEV relays [here](https://enchanted-direction-844.notion.site/6d369eb33f664487800b0dedfe32171e?v=8e5d1f1276b0493caea8a2aa1517ed65). Multiple relays must be separated by a comma. Consult our [deployment best practices](./deployment-best-practices.md#mev-boost-relays) for further info on MEV relay selection. +Uncomment `MEVBOOST_RELAYS=` and set it to the URL of at least one of Lido's approved MEV relays [here](https://enchanted-direction-844.notion.site/6d369eb33f664487800b0dedfe32171e?v=8e5d1f1276b0493caea8a2aa1517ed65). Multiple relays must be separated by a comma. Consult our [deployment best practices](../prepare/deployment-best-practices.md#mev-boost-relays) for further info on MEV relay selection. ### Step 6: Starting the Node @@ -228,5 +228,5 @@ The EA member clicks on the **Create Node Operator** button. Sign the transaction. The cluster is ready for deposit from Lido CSM. At this point, your job is finished. :::warning -When claiming your cluster's rewards, **be sure to claim in wstETH only** (Wrapped Staked Ether). Ether withdrawal gives you an NFT that is not compatible with a splitter, while a rebasing token like stETH may not receive the incremental yield you’re expecting. More information can be found in the [splits.org documentation](https://docs.splits.org/core/split#how-it-works). +When claiming your cluster's rewards, **be sure to claim in wstETH**. Claiming native ETH will result in loss of funds. Rebasing tokens like stETH may not receive the incremental yield you’re expecting. More information can be found in the [splits.org documentation](https://docs.splits.org/core/split#how-it-works). ::: diff --git a/docs/advanced/quickstart-eigenpod.mdx b/docs/run/integrations/quickstart-eigenpod.mdx similarity index 93% rename from docs/advanced/quickstart-eigenpod.mdx rename to docs/run/integrations/quickstart-eigenpod.mdx index f4085a55ff..64f825b7a4 100644 --- a/docs/advanced/quickstart-eigenpod.mdx +++ b/docs/run/integrations/quickstart-eigenpod.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 1 description: Create an EigenLayer Distributed Validator to enable distributed restaking. --- @@ -12,12 +12,12 @@ import TabItem from '@theme/TabItem'; The Obol-SDK is in a beta state and should be used with caution. Ensure you validate all important data. ::: -This is a walkthrough of creating a distributed validator cluster pointing to an [EigenLayer](https://eigenlayer.xyz/) [EigenPod](https://docs.eigenlayer.xyz/eigenlayer/restaking-guides/restaking-user-guide/native-restaking/create-eigenpod-and-set-withdrawal-credentials/), using the [DV Launchpad](../dvl/intro.md) and other applications. +This is a walkthrough of creating a distributed validator cluster pointing to an [EigenLayer](https://eigenlayer.xyz/) [EigenPod](https://docs.eigenlayer.xyz/eigenlayer/restaking-guides/restaking-user-guide/native-restaking/create-eigenpod-and-set-withdrawal-credentials/), using the [DV Launchpad](../../learn/intro/launchpad.md) and other applications. ## Pre-requisites - The Ethereum addresses or ENS names for the node operators in the cluster. (Currently the DV Launchpad only supports Metamask or equivalent injected web3 browser wallets.) -- If creating more than one validator, the ability to use the [obol-sdk](./quickstart-sdk.mdx) is required. +- If creating more than one validator, the ability to use the [obol-sdk](../../adv/advanced/quickstart-sdk.mdx) is required. ## Create a SAFE to own the EigenPod @@ -42,7 +42,7 @@ With these contracts deployed, you can now create the DV cluster invitation to s
    -
  • Use the "Create a cluster with a group" flow on the DV Launchpad.
    • +
  • Use the "Create a cluster with a group" flow on the DV Launchpad.
  • Choose a cluster name and invite your operator's addresses.
  • When setting the withdrawal credentials, select "Custom".
  • For "Withdrawal Address", set the EigenPod contract address.
    • diff --git a/docs/run/prepare/_category_.json b/docs/run/prepare/_category_.json new file mode 100644 index 0000000000..6d4ce7e1b0 --- /dev/null +++ b/docs/run/prepare/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Prepare to run a DV", + "position": 2, + "collapsed": true +} \ No newline at end of file diff --git a/docs/advanced/deployment-best-practices.md b/docs/run/prepare/deployment-best-practices.md similarity index 76% rename from docs/advanced/deployment-best-practices.md rename to docs/run/prepare/deployment-best-practices.md index 6d33277c43..be41e6aaa6 100644 --- a/docs/advanced/deployment-best-practices.md +++ b/docs/run/prepare/deployment-best-practices.md @@ -1,5 +1,5 @@ --- -sidebar_position: 11 +sidebar_position: 2 description: DV Deployment best practices, for running an optimal Distributed Validator setup at scale. --- @@ -48,7 +48,7 @@ For optimal performance and high availability, it is recommended to provision ma ## Peer Connections -Charon clients can establish connections with one another in two ways: either through a third publicly accessible server known as [a relay](../charon/charon-cli-reference.md#host-a-relay) or directly with one another if they can establish a connection. The former is known as a relay connection and the latter is known as a direct connection. +Charon clients can establish connections with one another in two ways: either through a third publicly accessible server known as [a relay](../../learn/charon/charon-cli-reference.md#host-a-relay) or directly with one another if they can establish a connection. The former is known as a relay connection and the latter is known as a direct connection. It is important that all nodes in a cluster be directly connected to one another - this can halve the latency between them and reduces bandwidth constraints significantly. Opening Charon’s p2p port (the default is `3610`) to the Internet, or configuring your routers NAT gateway to permit connections to your Charon client, are what are required to facilitate a direct connection between clients. @@ -62,13 +62,13 @@ If you wish to divide a Distributed Validator node across multiple physical or v ## Node Configuration -Cluster sizes that allow for Byzantine Fault Tolerance are recommended as they are safer than clusters with simply Crash Fault Tolerance (See this guide for reference - [Cluster Size and Resilience](../charon/cluster-configuration#cluster-size-and-resilience)). +Cluster sizes that allow for Byzantine Fault Tolerance are recommended as they are safer than clusters with simply Crash Fault Tolerance (See this guide for reference - [Cluster Size and Resilience](../../learn/charon/cluster-configuration#cluster-size-and-resilience)). ## MEV-Boost Relays -MEV relays are configured at the Consensus Layer or MEV-boost client level. Refer to our [guide](./quickstart-builder-api.mdx) to ensure all necessary configuration has been applied to your clients. As with all validators, low latency during proposal opportunities is extremely important. By default, MEV-Boost waits for all configured relays to return a bid, or will timeout if any have not returned a bid within 950ms. This default timeout is generally too slow for a distributed cluster (think of this time as additive to the time it takes the cluster to come to consensus, both of which need to happen within a 2 second window for optimal proposal broadcasting). It is likely better to only list relays that are located geographically near your node, so that once all relays respond (e.g. in < 50ms) your cluster will move forward with the proposal. +MEV relays are configured at the Consensus Layer or MEV-boost client level. Refer to our [guide](../../run/start/quickstart-builder-api.mdx) to ensure all necessary configuration has been applied to your clients. As with all validators, low latency during proposal opportunities is extremely important. By default, MEV-Boost waits for all configured relays to return a bid, or will timeout if any have not returned a bid within 950ms. This default timeout is generally too slow for a distributed cluster (think of this time as additive to the time it takes the cluster to come to consensus, both of which need to happen within a 2 second window for optimal proposal broadcasting). It is likely better to only list relays that are located geographically near your node, so that once all relays respond (e.g. in < 50ms) your cluster will move forward with the proposal. -Use Charon's [`test mev` command](./test-command.md#test-mev-relay) to test a number of your preferred relays, and select the two or three relays with the lowest latency to your node(s), you do not need to have the same relays on each node in a cluster. +Use Charon's [`test mev` command](../../run/prepare/test-command.md#test-mev-relay) to test a number of your preferred relays, and select the two or three relays with the lowest latency to your node(s), you do not need to have the same relays on each node in a cluster. ## Client Diversity @@ -80,11 +80,11 @@ Tested client combinations can be found in the [release notes](https://github.co ## Metrics Monitoring -As requested by Obol Labs, node operators can push [standard monitoring](./obol-monitoring.md) (Prometheus) and logging (Loki) data to Obol Labs' core team's cloud infrastructure for in-depth analysis of performance data and to assist during potential issues that may arise. Our recommendation for operators is to independently store information on their node health over the course of the validator lifecycle as well as any information on validator performance that they collect during the normal life cycle of a validator. +As requested by Obol Labs, node operators can push [standard monitoring](../../run/start/obol-monitoring.md) (Prometheus) and logging (Loki) data to Obol Labs' core team's cloud infrastructure for in-depth analysis of performance data and to assist during potential issues that may arise. Our recommendation for operators is to independently store information on their node health over the course of the validator lifecycle as well as any information on validator performance that they collect during the normal life cycle of a validator. ## Obol Splits -Leveraging [Obol Splits](../sc/introducing-obol-splits.mdx) smart contracts allows for non-custodial fund handling and allows for net customer payouts in an ongoing manner. Obol Splits ensure no commingling of funds across customers, and maintain full non-custodial integrity. Read more about Obol Splits [here](../faq/general.mdx#obol-splits). +Leveraging [Obol Splits](../../learn/intro/obol-splits.mdx) smart contracts allows for non-custodial fund handling and allows for net customer payouts in an ongoing manner. Obol Splits ensure no commingling of funds across customers, and maintain full non-custodial integrity. Read more about Obol Splits [here](../../learn/intro/faq.mdx#obol-splits). ## Deposit Process diff --git a/docs/int/how_where_DVs.md b/docs/run/prepare/how_where_DVs.md similarity index 94% rename from docs/int/how_where_DVs.md rename to docs/run/prepare/how_where_DVs.md index a85948b3f4..40be2cf443 100644 --- a/docs/int/how_where_DVs.md +++ b/docs/run/prepare/how_where_DVs.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 1 description: How and where to run DVs --- @@ -18,9 +18,9 @@ description: How and where to run DVs - [Terraform Grafana Charon dashboards](https://github.com/ObolNetwork/terraform-grafana-dashboards) ## Quickstart Guides -- [Run a DV alone](https://docs.obol.org/docs/start/quickstart_alone) -- [Run a DV as a group](https://docs.obol.org/docs/start/quickstart_group) -- [Run a DV using the SDK](https://docs.obol.org/docs/advanced/quickstart-sdk) +- [Run a DV alone](../start/quickstart_alone.mdx) +- [Run a DV as a group](../start/quickstart_group.mdx) +- [Run a DV using the SDK](../../adv/advanced/quickstart-sdk.mdx) ## CL+VC Combinations: diff --git a/docs/advanced/test-command.md b/docs/run/prepare/test-command.md similarity index 98% rename from docs/advanced/test-command.md rename to docs/run/prepare/test-command.md index 6ee5eeaeef..5ba71bf363 100644 --- a/docs/advanced/test-command.md +++ b/docs/run/prepare/test-command.md @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 3 description: Test the performance of a candidate Distributed Validator Cluster setup. --- @@ -30,7 +30,7 @@ At least 1 ENR is required to be supplied to the `--enrs` flag. ### Pre-requisites -- [Create an ENR](../charon/charon-cli-reference#creating-an-enr-for-charon). +- [Create an ENR](../../learn/charon/charon-cli-reference#creating-an-enr-for-charon). - Share your ENR with the other peers which will test with you. - Obtain the ENRs of the other peers with which you will test. diff --git a/docs/run/running/_category_.json b/docs/run/running/_category_.json new file mode 100644 index 0000000000..bf519c3b35 --- /dev/null +++ b/docs/run/running/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Running your DV", + "position": 3, + "collapsed": true +} \ No newline at end of file diff --git a/docs/start/activate-dv.mdx b/docs/run/running/activate-dv.mdx similarity index 99% rename from docs/start/activate-dv.mdx rename to docs/run/running/activate-dv.mdx index 18e9e9d1b0..f1627775fd 100644 --- a/docs/start/activate-dv.mdx +++ b/docs/run/running/activate-dv.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 1 description: Activate the Distributed Validator using the deposit contract --- diff --git a/docs/run/running/claiming-rewards.md b/docs/run/running/claiming-rewards.md new file mode 100644 index 0000000000..c04d9eb962 --- /dev/null +++ b/docs/run/running/claiming-rewards.md @@ -0,0 +1,9 @@ +--- +sidebar_position: 5 +description: Claiming rewards from your DV using the Launchpad. +--- +# Claiming DV rewards + +## Claim rewards using the Launchpad. + +This page is currently just a placeholder. Content coming soon. \ No newline at end of file diff --git a/docs/advanced/monitoring.md b/docs/run/running/monitoring.md similarity index 97% rename from docs/advanced/monitoring.md rename to docs/run/running/monitoring.md index 1ad9cc06ec..ffdc9cb405 100644 --- a/docs/advanced/monitoring.md +++ b/docs/run/running/monitoring.md @@ -1,10 +1,10 @@ --- -sidebar_position: 2 +sidebar_position: 4 description: Add monitoring credentials to help the Obol Team monitor the health of your cluster --- # Monitoring your Node -This comprehensive guide will assist you in effectively monitoring your Charon clusters and setting up alerts by running your own Prometheus and Grafana server. If you want to use Obol’s [public dashboard](https://grafana.monitoring.gcp.obol.tech/d/d895e47a-3c2d-46b7-9b15-8f31202681af/clusters-aggregate-view?orgId=6) instead of running your servers, refer to [this section](./obol-monitoring.md) in Obol docs that teaches you how to push Prometheus metrics to Obol. +This comprehensive guide will assist you in effectively monitoring your Charon clusters and setting up alerts by running your own Prometheus and Grafana server. If you want to use Obol’s [public dashboard](https://grafana.monitoring.gcp.obol.tech/d/d895e47a-3c2d-46b7-9b15-8f31202681af/clusters-aggregate-view?orgId=6) instead of running your servers, refer to [this section](../../run/start/obol-monitoring.md) in Obol docs that teaches you how to push Prometheus metrics to Obol. To explain quickly, Prometheus generates the metrics and Grafana visualizes them. To learn more about Prometheus and Grafana, visit [here](https://grafana.com/docs/grafana/latest/getting-started/get-started-grafana-prometheus/). If you are using **[CDVN repository](https://github.com/ObolNetwork/charon-distributed-validator-node)** or **[CDVC repository](https://github.com/ObolNetwork/charon-distributed-validator-cluster)**, then Prometheus and Grafana are part of docker compose file and will be installed when you run `docker compose up`. @@ -20,7 +20,7 @@ The local Grafana server will have a few pre-built dashboards: 3. Charon Log Dashboard - This dashboard can be used to query the logs emitted while running your Charon node. It utilises [Grafana Loki](https://grafana.com/oss/loki/). This dashboard is not active by default and should only be used in debug mode. Refer to [advanced docker config](./adv-docker-configs) section on how to set up a debug mode. + This dashboard can be used to query the logs emitted while running your Charon node. It utilises [Grafana Loki](https://grafana.com/oss/loki/). This dashboard is not active by default and should only be used in debug mode. Refer to [advanced docker config](../../adv/advanced/adv-docker-configs.md) section on how to set up a debug mode. | Alert Name | Description | Troubleshoot | | --- | --- | --- | diff --git a/docs/start/quickstart-exit.mdx b/docs/run/running/quickstart-exit.mdx similarity index 99% rename from docs/start/quickstart-exit.mdx rename to docs/run/running/quickstart-exit.mdx index 9b7c5a228d..6ded736083 100644 --- a/docs/start/quickstart-exit.mdx +++ b/docs/run/running/quickstart-exit.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 3 description: Exit a validator --- diff --git a/docs/start/update.mdx b/docs/run/running/update.mdx similarity index 99% rename from docs/start/update.mdx rename to docs/run/running/update.mdx index b8f1e913e8..dfa59547f9 100644 --- a/docs/start/update.mdx +++ b/docs/run/running/update.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 2 description: Update your DV cluster with the latest Charon release --- import Tabs from '@theme/Tabs'; diff --git a/docs/run/start/_category_.json b/docs/run/start/_category_.json new file mode 100644 index 0000000000..f020212956 --- /dev/null +++ b/docs/run/start/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Quickstart", + "position": 1, + "collapsed": true +} diff --git a/docs/run/start/existing_node.md b/docs/run/start/existing_node.md new file mode 100644 index 0000000000..e355e041c5 --- /dev/null +++ b/docs/run/start/existing_node.md @@ -0,0 +1,8 @@ +--- +sidebar_position: 6 +description: Create a DV using an existing beacon node. +--- + +# Use an existing beacon node + +You may have an existing beacon node and wish to use it to run as part of a DV cluster. diff --git a/docs/advanced/obol-monitoring.md b/docs/run/start/obol-monitoring.md similarity index 99% rename from docs/advanced/obol-monitoring.md rename to docs/run/start/obol-monitoring.md index 11c2d53257..dd027ac85f 100644 --- a/docs/advanced/obol-monitoring.md +++ b/docs/run/start/obol-monitoring.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 4 description: Add monitoring credentials to help the Obol Team monitor the health of your cluster --- import Tabs from "@theme/Tabs"; diff --git a/docs/advanced/quickstart-builder-api.mdx b/docs/run/start/quickstart-builder-api.mdx similarity index 94% rename from docs/advanced/quickstart-builder-api.mdx rename to docs/run/start/quickstart-builder-api.mdx index 93fb135eb0..860431b7cc 100644 --- a/docs/advanced/quickstart-builder-api.mdx +++ b/docs/run/start/quickstart-builder-api.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +sidebar_position: 4 description: Run a distributed validator cluster with the builder API (MEV-Boost) --- @@ -43,7 +43,7 @@ charon run --builder-api ### Consensus Clients -The following flags need to be configured on your chosen consensus client. A Flashbots relay URL is provided for example purposes, you should use the [charon test mev command](./test-command.md#test-mev-relay) and select the two or three relays with the lowest latency to your node that also conform to your block building preferences. A public list of MEV relays is available [here](https://github.com/eth-educators/ethstaker-guides/blob/main/MEV-relay-list.md#mev-relay-list-for-mainnet). +The following flags need to be configured on your chosen consensus client. A Flashbots relay URL is provided for example purposes, you should use the [charon test mev command](../../run/prepare/test-command.md#test-mev-relay) and select the two or three relays with the lowest latency to your node that also conform to your block building preferences. A public list of MEV relays is available [here](https://github.com/eth-educators/ethstaker-guides/blob/main/MEV-relay-list.md#mev-relay-list-for-mainnet). diff --git a/docs/start/quickstart_alone.mdx b/docs/run/start/quickstart_alone.mdx similarity index 91% rename from docs/start/quickstart_alone.mdx rename to docs/run/start/quickstart_alone.mdx index 5da1196d79..1069049a9b 100644 --- a/docs/start/quickstart_alone.mdx +++ b/docs/run/start/quickstart_alone.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 2 description: Create a DV alone --- import Tabs from '@theme/Tabs'; @@ -10,7 +10,7 @@ import TabItem from '@theme/TabItem'; :::info It is possible for a single operator to manage all of the nodes of a DV cluster. The nodes can be run on a single machine, which is only suitable for testing, or the nodes can be run on multiple machines, which is expected for a production setup. -The private key shares can be created centrally and distributed securely to each node. Alternatively, the private key shares can be created in a lower-trust manner with a [Distributed Key Generation](../int/key-concepts.md#distributed-validator-key-generation-ceremony) process, which avoids the validator private key being stored in full anywhere, at any point in its lifecycle. Follow the [group quickstart](./quickstart_group.mdx) instead for this latter case. +The private key shares can be created centrally and distributed securely to each node. Alternatively, the private key shares can be created in a lower-trust manner with a [Distributed Key Generation](../../learn/intro/key-concepts.md#distributed-validator-key-generation-ceremony) process, which avoids the validator private key being stored in full anywhere, at any point in its lifecycle. Follow the [group quickstart](./quickstart_group.mdx) instead for this latter case. ::: ## Pre-requisites @@ -55,7 +55,7 @@ The private key shares can be created centrally and distributed securely to each 2. Run the cluster creation command, setting required flag values. Run the below command to create the validator private key shares and cluster artifacts locally, replacing the example values for `nodes`, `network`, `num-validators`, `fee-recipient-addresses`, and `withdrawal-addresses`. - Check the [Charon CLI reference](../charon/charon-cli-reference.md#create-a-full-cluster-locally) for additional, optional flags to set. + Check the [Charon CLI reference](../../learn/charon/charon-cli-reference.md#create-a-full-cluster-locally) for additional, optional flags to set. ```shell docker run --rm -v "$(pwd):/opt/charon" obolnetwork/charon:v1.1.2 create cluster \ @@ -69,7 +69,7 @@ The private key shares can be created centrally and distributed securely to each ``` :::tip -If you would like your cluster to appear on the [DV Launchpad](../dvl/intro), add the `--publish` flag to the command. +If you would like your cluster to appear on the [DV Launchpad](../../learn/intro/launchpad.md), add the `--publish` flag to the command. ::: @@ -186,7 +186,7 @@ cluster `.env.sample` is a sample environment file that allows overriding default configuration defined in `docker-compose.yml`. Uncomment and set any variable to override its value. - Setup the desired inputs for the DV, including the network you wish to operate on. Check the [Charon CLI reference](../charon/charon-cli-reference.md) for additional optional flags to set. Once you have set the values you wish to use. Make a copy of this file called `.env`. + Setup the desired inputs for the DV, including the network you wish to operate on. Check the [Charon CLI reference](../../learn/charon/charon-cli-reference.md) for additional optional flags to set. Once you have set the values you wish to use. Make a copy of this file called `.env`. ```shell # Copy ".env.sample", renaming it ".env" diff --git a/docs/start/quickstart_group.mdx b/docs/run/start/quickstart_group.mdx similarity index 97% rename from docs/start/quickstart_group.mdx rename to docs/run/start/quickstart_group.mdx index 19c2339dd4..72c77393ca 100644 --- a/docs/start/quickstart_group.mdx +++ b/docs/run/start/quickstart_group.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 3 description: Create a DV with a group --- @@ -49,7 +49,7 @@ Please make sure to create a backup of the private key at `.charon/charon-enr-pr ::: :::tip -If instead of being shown your `enr` you see an error saying `permission denied` then you may need to [update your docker permissions](../faq/errors.mdx#docker-permission-denied-error) to allow the command to run successfully. +If instead of being shown your `enr` you see an error saying `permission denied` then you may need to [update your docker permissions](../../adv/troubleshooting/errors.mdx#docker-permission-denied-error) to allow the command to run successfully. ::: @@ -147,7 +147,7 @@ For Step 2, select the "Creator" tab if you are coordinating the creation of the

    You will use the Launchpad to create an invitation, and share it with - the operators. This video shows the flow within the [DV Launchpad](../dvl/intro.md) + the operators. This video shows the flow within the [DV Launchpad](../../learn/intro/launchpad.md)