From fd42ab9cde04f3ae48faf1064774ea8a285694a0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ois=C3=ADn=20Kyne?= Date: Mon, 9 May 2022 23:51:27 +0100 Subject: [PATCH] Beginning to version docs to start making it apparent when things change --- .github/workflows/release.yml | 50 ++++ docusaurus.config.js | 4 + package.json | 3 +- static/img/CharonLogo.svg | 12 +- .../version-v0.3.0/cg/_category_.json | 5 + .../version-v0.3.0/cg/bug-report.md | 57 ++++ versioned_docs/version-v0.3.0/cg/docs.md | 248 ++++++++++++++++++ .../dv/01_introducing-charon.md | 26 ++ .../dv/02_validator-creation.md | 32 +++ .../version-v0.3.0/dv/04_middleware-daemon.md | 34 +++ .../version-v0.3.0/dv/06_peer-discovery.md | 39 +++ .../version-v0.3.0/dv/07_p2p-interface.md | 11 + ..._distributed-validator-cluster-manifest.md | 60 +++++ .../dv/09_charon_cli_reference.md | 90 +++++++ .../version-v0.3.0/dv/_category_.json | 5 + .../dvk/01_distributed-validator-keys.md | 16 ++ .../dvk/02_distributed_validator_launchpad.md | 14 + .../dvk/03_dkg_cli_reference.md | 88 +++++++ .../version-v0.3.0/dvk/_category_.json | 5 + .../version-v0.3.0/fr/_category_.json | 5 + versioned_docs/version-v0.3.0/fr/eth.md | 131 +++++++++ versioned_docs/version-v0.3.0/fr/golang.md | 9 + versioned_docs/version-v0.3.0/glossary.md | 9 + versioned_docs/version-v0.3.0/int/Overview.md | 48 ++++ .../version-v0.3.0/int/_category_.json | 5 + versioned_docs/version-v0.3.0/int/faq.md | 24 ++ .../version-v0.3.0/int/key-concepts.md | 86 ++++++ .../version-v0.3.0/int/working-groups.md | 146 +++++++++++ versioned_docs/version-v0.3.0/intro.md | 20 ++ .../sc/01_introducing-obol-managers.md | 59 +++++ .../version-v0.3.0/sc/_category_.json | 5 + versioned_docs/version-v0.3.0/testnet.md | 187 +++++++++++++ .../version-v0.3.0-sidebars.json | 8 + versions.json | 3 + 34 files changed, 1537 insertions(+), 7 deletions(-) create mode 100644 .github/workflows/release.yml create mode 100644 versioned_docs/version-v0.3.0/cg/_category_.json create mode 100644 versioned_docs/version-v0.3.0/cg/bug-report.md create mode 100644 versioned_docs/version-v0.3.0/cg/docs.md create mode 100644 versioned_docs/version-v0.3.0/dv/01_introducing-charon.md create mode 100644 versioned_docs/version-v0.3.0/dv/02_validator-creation.md create mode 100644 versioned_docs/version-v0.3.0/dv/04_middleware-daemon.md create mode 100644 versioned_docs/version-v0.3.0/dv/06_peer-discovery.md create mode 100644 versioned_docs/version-v0.3.0/dv/07_p2p-interface.md create mode 100644 versioned_docs/version-v0.3.0/dv/08_distributed-validator-cluster-manifest.md create mode 100644 versioned_docs/version-v0.3.0/dv/09_charon_cli_reference.md create mode 100644 versioned_docs/version-v0.3.0/dv/_category_.json create mode 100644 versioned_docs/version-v0.3.0/dvk/01_distributed-validator-keys.md create mode 100644 versioned_docs/version-v0.3.0/dvk/02_distributed_validator_launchpad.md create mode 100644 versioned_docs/version-v0.3.0/dvk/03_dkg_cli_reference.md create mode 100644 versioned_docs/version-v0.3.0/dvk/_category_.json create mode 100644 versioned_docs/version-v0.3.0/fr/_category_.json create mode 100644 versioned_docs/version-v0.3.0/fr/eth.md create mode 100644 versioned_docs/version-v0.3.0/fr/golang.md create mode 100644 versioned_docs/version-v0.3.0/glossary.md create mode 100644 versioned_docs/version-v0.3.0/int/Overview.md create mode 100644 versioned_docs/version-v0.3.0/int/_category_.json create mode 100644 versioned_docs/version-v0.3.0/int/faq.md create mode 100644 versioned_docs/version-v0.3.0/int/key-concepts.md create mode 100644 versioned_docs/version-v0.3.0/int/working-groups.md create mode 100644 versioned_docs/version-v0.3.0/intro.md create mode 100644 versioned_docs/version-v0.3.0/sc/01_introducing-obol-managers.md create mode 100644 versioned_docs/version-v0.3.0/sc/_category_.json create mode 100644 versioned_docs/version-v0.3.0/testnet.md create mode 100644 versioned_sidebars/version-v0.3.0-sidebars.json create mode 100644 versions.json diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000000..d014b99ffd --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,50 @@ + +on: + push: + tags: + - 'v*' +name: Publish Release +jobs: + deploy: + runs-on: ubuntu-20.04 + concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + steps: + - uses: actions/checkout@v2 + + - name: Setup Node + uses: actions/setup-node@v2 + with: + node-version: "14" + + - name: Get yarn cache + id: yarn-cache + run: echo "::set-output name=dir::$(yarn cache dir)" + + - name: Cache dependencies + uses: actions/cache@v2 + with: + path: ${{ steps.yarn-cache.outputs.dir }} + key: ${{ runner.os }}-website-${{ hashFiles('**/yarn.lock') }} + restore-keys: | + ${{ runner.os }}-website- + + - run: yarn install --frozen-lockfile + + - name: Get version tag from git + id: get-tag + run: | + tag=$(echo "${{ github.ref }}" | cut -d / -f 3) + echo "::set-output name=tag::$tag" + + - name: Create a new versioned history of the docs + run: yarn run version ${{steps.get-tag.outputs.tag}} + + - run: yarn build + + - name: Deploy + uses: peaceiris/actions-gh-pages@v3 + if: ${{ github.ref == 'refs/heads/main' }} + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./build \ No newline at end of file diff --git a/docusaurus.config.js b/docusaurus.config.js index 77ca1b688e..1cf5dd18cd 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -78,6 +78,10 @@ const config = { label: 'GitHub', position: 'right', }, + { + type: 'docsVersionDropdown', + position: 'right' + }, ], }, footer: { diff --git a/package.json b/package.json index 17404ff71e..76b8537569 100644 --- a/package.json +++ b/package.json @@ -12,7 +12,8 @@ "serve": "docusaurus serve", "write-translations": "docusaurus write-translations", "write-heading-ids": "docusaurus write-heading-ids", - "typecheck": "tsc" + "typecheck": "tsc", + "version": "docusaurus docs:version" }, "dependencies": { "@docusaurus/core": "2.0.0-beta.9", diff --git a/static/img/CharonLogo.svg b/static/img/CharonLogo.svg index 54bb4135eb..368f79c9dd 100644 --- a/static/img/CharonLogo.svg +++ b/static/img/CharonLogo.svg @@ -1,11 +1,11 @@ - - - - - - + + + + + + diff --git a/versioned_docs/version-v0.3.0/cg/_category_.json b/versioned_docs/version-v0.3.0/cg/_category_.json new file mode 100644 index 0000000000..50881747b9 --- /dev/null +++ b/versioned_docs/version-v0.3.0/cg/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Contribution guidelines", + "position": 10, + "collapsed": true +} diff --git a/versioned_docs/version-v0.3.0/cg/bug-report.md b/versioned_docs/version-v0.3.0/cg/bug-report.md new file mode 100644 index 0000000000..eda3693761 --- /dev/null +++ b/versioned_docs/version-v0.3.0/cg/bug-report.md @@ -0,0 +1,57 @@ +# 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. + +## Checking if your issue exists + +Duplicate tickets are a hinderance to the development process and, as such, it is crucial to first check through Charon's existing issues to see if what you are experiencing has already been indexed. + +To do so, head over to the [issue page](https://github.com/ObolNetwork/charon/issues) and enter some related keywords into the search bar. This may include a sample from the output or specific components it affects. + +If searches have shown the issue in question has not been reported yet, feel free to open up a new issue ticket. + +## Writing quality bug reports + +A good bug report is structured to help the developers and contributors visualise the issue in the clearest way possible. It's important to be concise and use comprehensive language, while also providing all relevant information on-hand. Use short and accurate sentences without any unnecessary additions, and include all existing specifications with a list of steps to reproduce the expected problem. Issues that cannot be reproduced **cannot be solved**. + +If you are experiencing multiple issues, it is best to open each as a separate ticket. This allows them to be closed individually as they are resolved. + +An original bug report will very likely be preserved and used as a record and sounding board for users that have similar experiences in the future. Because of this, it is a great service to the community to ensure that reports meet these standards and follow the template closely. + + +## The bug report template + +Below is the standard bug report template used by all of Obol's official repositories. + +```sh + + +## Expected Behaviour + + +## Current Behaviour + + +## Steps to Reproduce + +1. +2. +3. +4. +5. + +## Detailed Description + + +## Specifications + +Operating system: +Version(s) used: + +## Possible Solution + + +## Further Information + + + ## What is Charon? + + + + ## Charon explained + ``` + +#### Bold text + +Double asterisks `**` are used to define **boldface** text. Use bold text when the reader must interact with something displayed as text: buttons, hyperlinks, images with text in them, window names, and icons. + +```markdown +In the **Login** window, enter your email into the **Username** field and click **Sign in**. +``` + +#### Italics + +Underscores `_` are used to define _italic_ text. Style the names of things in italics, except input fields or buttons: + +```markdown +Here are some American things: + +- The _Spirit of St Louis_. +- The _White House_. +- The United States _Declaration of Independence_. + +``` + +Quotes or sections of quoted text are styled in italics and surrounded by double quotes `"`: + +```markdown +In the wise words of Winnie the Pooh _"People say nothing is impossible, but I do nothing every day."_ +``` + +#### Code blocks + +Tag code blocks with the syntax of the core they are presenting: + +````markdown + ```javascript + console.log(error); + ``` +```` + +#### List items + +All list items follow sentence structure. Only _names_ and _places_ are capitalized, along with the first letter of the list item. All other letters are lowercase: + +1. Never leave Nottingham without a sandwich. +2. Brian May played guitar for Queen. +3. Oranges. + +List items end with a period `.`, or a colon `:` if the list item has a sub-list: + +1. Charles Dickens novels: + 1. Oliver Twist. + 2. Nicholas Nickelby. + 3. David Copperfield. +2. J.R.R Tolkien non-fiction books: + 1. The Hobbit. + 2. Silmarillion. + 3. Letters from Father Christmas. + +##### Unordered lists + +Use the dash character `-` for un-numbered list items: + +```markdown +- An apple. +- Three oranges. +- As many lemons as you can carry. +- Half a lime. +``` + +#### Special characters + +Whenever possible, spell out the name of the special character, followed by an example of the character itself within a code block. + +```markdown +Use the dollar sign `$` to enter debug-mode. +``` + +#### Keyboard shortcuts + +When instructing the reader to use a keyboard shortcut, surround individual keys in code tags: + +```bash +Press `ctrl` + `c` to copy the highlighted text. +``` + +The plus symbol `+` stays outside of the code tags. + +### Images + +The following rules and guidelines define how to use and store images. + +#### Storage location + +All images must be placed in the `/website/static/img` folder. For multiple images attributed to a single topic, a new folder within `/img/ the may be needed. + +#### File names + +All file names are lower-case with dashes `-` between words, including image files: + +```text +concepts/ +├── content-addressed-data.md +├── images +│   └── proof-of-spacetime +│   └── post-diagram.png +└── proof-of-replication.md +└── proof-of-spacetime.md +``` + +_The framework and some information for this was forked from the original found on the [Filecoin documentation portal](https://docs.filecoin.io)_ + diff --git a/versioned_docs/version-v0.3.0/dv/01_introducing-charon.md b/versioned_docs/version-v0.3.0/dv/01_introducing-charon.md new file mode 100644 index 0000000000..e59ff43a48 --- /dev/null +++ b/versioned_docs/version-v0.3.0/dv/01_introducing-charon.md @@ -0,0 +1,26 @@ +--- +description: Charon - The Distributed Validator Client +--- + +# Introducing Charon + +This section introduces and outlines the Charon DVT middleware. For additional context regarding distributed validator technology, see [this section](http://localhost:3000/docs/int/key-concepts#distributed-validator) of the key concept page. + +### What is Charon? + +Charon is a GoLang-based, HTTP middleware built by Obol to enable any existing Ethereum validator clients to operate together as part of a distributed validator. + +Charon sits as a middleware between a normal validating client and it's connected beacon node, intercepting and proxying API traffic. Multiple Charon clients are configured to communicate together to come to consensus on validator duties and behave as a single unified proof-of-stake validator together. The nodes form a cluster that is _byzantine-fault tolerant_ and continues to progress assuming a supermajority of working/honest nodes is met. + +### Charon architecture +The below graphic visually outlines the internal functionalies of Charon. + +![Charon Internals Slide](/img/CharonInternals.png) + +### Get started + +The `charon` client is in an early alpha state, and is not ready for mainnet, see [here](https://github.com/ObolNetwork/charon#supported-consensus-layer-clients) for the latest on charon's readiness. + +``` +docker run ghcr.io/obolnetwork/charon:v0.3.0 --help +``` diff --git a/versioned_docs/version-v0.3.0/dv/02_validator-creation.md b/versioned_docs/version-v0.3.0/dv/02_validator-creation.md new file mode 100644 index 0000000000..2f47858f3d --- /dev/null +++ b/versioned_docs/version-v0.3.0/dv/02_validator-creation.md @@ -0,0 +1,32 @@ +--- +description: Creating a Distributed Validator cluster from scratch +--- + +# Distributed validator creation + +![A sample Distributed Validator cluster](/img/ObolCluster.png) + +### Stages of creating a distributed validator + +To create a distributed validator cluster, you and your group of operators need to complete the following steps: + +1. One operator begins the cluster setup on the [Distributed Validator Launchpad](../dvk/02_distributed_validator_launchpad.md). + - This involves setting all of the terms for the cluster, including; withdrawal address, fee recipient, validator count, operator addresses, etc. This information is known as a `cluster configuration`. + - This operator also sets their charon client's Ethereum Node Record (ENR). + - This operator signs both the hash of the cluster config and the ENR to prove custody of their address. + - This data is stored in the DV Launchpad data layer and a URL is generated. This is a link for the other operators to join and complete the ceremony. +2. The other operators in the cluster follow this URL to the launchpad. + - They review the terms of the cluster configuration. + - The submit the ENR of their charon client. + - They sign both the hash of the cluster config and their charon ENR to indicate acceptance of the terms +3. Once all operators have submitted signatures for the cluster configuration and ENRs, they can all download the cluster manifest file. +4. Every operator loads this cluster manifest file into `charon dkg`. The manifest provides the charon process with the information it needs to complete the DKG ceremony with the other charon clients. +5. Once all charon clients can communicate with one another, the DKG process completes. All operators end up with: + - A manifest lockfile, which contains the original cluster configuration data, combined with the newly generated group public keys and their associated threshold verifiers. This file is needed by the `charon run` command. + - Validator deposit data + - Validator exit data + - Validator private key shares +6. Operators can now take backups of the generated private key shares and manifest.lock file. +7. All operators load the keys and manifests generated in the ceremony, into their staking deployments. +8. Operators can run a performance test of the configured cluster to ensure connectivity between all operators at a reasonable latency is observed. +9. Once all readiness tests have passed, one operator activates the distributed validator(s) with an on-chain deposit. diff --git a/versioned_docs/version-v0.3.0/dv/04_middleware-daemon.md b/versioned_docs/version-v0.3.0/dv/04_middleware-daemon.md new file mode 100644 index 0000000000..4b20142a74 --- /dev/null +++ b/versioned_docs/version-v0.3.0/dv/04_middleware-daemon.md @@ -0,0 +1,34 @@ +--- +description: Deployment Architecture for a Distributed Validator Client +--- + +# Middleware daemon + +The Charon daemon serves as a consensus layer API middleware and connects to the Obol peer-to-peer network to discover it's counterpart Charon nodes. + +### Operation + +The middleware strives to be stateless and statically configured through 777 file systems. The lack of a control-plane API for online reconfiguration is deliberate to keep operations simple and secure by default. + +A single instance of the middleware can participate in multiple distributed validator clusters. The amount of validators per middleware is bound by risk management and hardware limits (CPU, memory, bandwidth), but there is no hardcoded limit. + +The daemon offers a config reload instruction through Unix signals which is useful to join or leave Obol clusters on-the-fly without interruption. + +The `charon` package will initially be available as a Docker image and through binary builds. An APT package with a systemd integration is planned. + +### Initialization + +An instance of Charon requires the following pieces of information at minimum in order to operate. + +- A DV cluster manifest file in the to be confirmed EIP format. This file contains the required information a DV client needs for joining a Distributed Validator Cluster. This file includes: + - The total number of shares of the key and the required threshold for reconstruction. + - An SECP256K1 key pair in an ENR format for Obol consensus messages, this key is signed by the corresponding operators validator key share to legitimise it. + - A list of all ENR public keys of other operators participating in the cluster. + - The group public keys representing each distributed validator in the cluster to the Ethereum network. +- Access to an Ethereum Consensus API + - It is recommended to run at least one Ethereum Consensus client for each Charon middleware client. + - Any [compliant](https://ethereum.github.io/beacon-APIs/) Beacon node implementation should work – try to establish client diversity. + - These consensus clients need to be connected to at least one Ethereum Execution clients for block production. +- The public IP address and port the charon client will operate on + - For now, we make the (naive) assumption that the address will be static. + - Charon will attempt to auto-discover its address on first use by enumerating network interfaces and using [STUN](https://datatracker.ietf.org/doc/html/rfc5389). diff --git a/versioned_docs/version-v0.3.0/dv/06_peer-discovery.md b/versioned_docs/version-v0.3.0/dv/06_peer-discovery.md new file mode 100644 index 0000000000..702eb982f8 --- /dev/null +++ b/versioned_docs/version-v0.3.0/dv/06_peer-discovery.md @@ -0,0 +1,39 @@ +--- +description: How do distributed validator clients communicate with one another securely? +--- + +# Peer discovery + +In order to maintain security, middleware clients need to be able to authenticate one another. We achieve this by giving each middleware client something they can use that other clients in the cluster will be able to recognise as legitimate. + +At the end of a [DVK generation ceremony](./02_validator-creation.md#stages-of-creating-a-distributed-validator), each operator will have a number of files outputted by their CLI program/browser based on how many distributed validators the group chose to generate together. + +These files are: + +- **Validator keystore(s):** These files will be loaded into the operator's validator client and each file represents one share of a distributed validator. +- **A distributed validator cluster manifest:** This file contains the configuration a distributed validator client like charon needs to join a cluster capable of operating a number of distributed validators. + +### Authenticating a distributed validator client + +During the final stage of the DVK ceremony, after the validator key shares are generated for each operator, the ceremony program will generate a random SECP256K1 key pair to be used by a Charon client for its ENR. The program will sign this ENR public key with every keystore this validator will service, to indicate to all other operators that this randomly generated key is directly authorised by the current operator to communicate at the consensus layer for their distributed validator key shares. + +This sensitive ENR private key, and the general configuration of the distributed validator cluster will be the outputs of a DVK ceremony known shorthand as a `cluster manifest`. + +This manifest file will be made available to a charon client, and the validator key stores will be made available to the configured validator client. When charon starts up and ingests its configuration from the manifest file, it will use the provided keypair for its ENR. If it's configured IP address is different from what is embedded in the ENR to begin with, it reissues the ENR as needed and begins to establish connections with the other operators in the cluster as recorded in the manifest file. + +#### Node database + +Obol DV clusters are permissioned networks with a fully meshed topology. Each node will permanently store the ENRs of all other known Obol nodes in their node database. + +Unlike with node databases of public permissionless networks (such as [Go-Ethereum](https://pkg.go.dev/github.com/ethereum/go-ethereum@v1.10.13/p2p/enode#DB)), there is no inbuilt eviction logic – the database will keep growing indefinitely. + +#### Node discovery + +In early versions of Charon, operator nodes will be seeded in the node database from cluster manifest files. Updates to the node database can be made in realtime as a Charon client receives messages from these authorised ENRs containing a higher nonce value than present in our node database, usually representing an IP address update. + +In the future, Charon is intended to discover counterparty nodes using the [discv5](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md) protocol. All DVCs connecting to the Obol Network will join a public node discovery peer-to-peer network to find the latest ENR records for their DV peers. + +This dynamic discovery serves two purposes: + +- Bootstrapping a node database in the event of data loss when peers no longer listen on the IP addresseses specified in the manifest and need to be located. +- Periodically refreshing ENRs to follow IP address changes, e.g. AWS EC2 IPs or NAT on residential broadband. diff --git a/versioned_docs/version-v0.3.0/dv/07_p2p-interface.md b/versioned_docs/version-v0.3.0/dv/07_p2p-interface.md new file mode 100644 index 0000000000..1120ca4f97 --- /dev/null +++ b/versioned_docs/version-v0.3.0/dv/07_p2p-interface.md @@ -0,0 +1,11 @@ +--- +description: Connectivity between Charon instances +--- + +# P2P interface + +The Charon P2P interface loosely follows the [Eth2 beacon P2P interface](https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/p2p-interface.md). + +- Transport: TCP over IPv4/IPv6. +- Handshake: [noise-libp2p](https://github.com/libp2p/specs/tree/master/noise) with `secp256k1` keys. + - Nodes must have their keys authorized in a [cluster manifest](./08_distributed-validator-cluster-manifest.md) in order for the handshake to succeed. diff --git a/versioned_docs/version-v0.3.0/dv/08_distributed-validator-cluster-manifest.md b/versioned_docs/version-v0.3.0/dv/08_distributed-validator-cluster-manifest.md new file mode 100644 index 0000000000..cbf997969a --- /dev/null +++ b/versioned_docs/version-v0.3.0/dv/08_distributed-validator-cluster-manifest.md @@ -0,0 +1,60 @@ +--- +description: Documenting a Distributed Validator Cluster in a standardised file format +--- + +# Distributed validator cluster manifest + +:::caution +This manifest file is a work in progress, and intends to be standardised for operating distributed validators via the [EIP process](../dvk/01_distributed-validator-keys.md#standardising-the-format-of-dvks) when appropriate. +::: + +The manifest file captures the public, read-only info required to take part in a distributed validator cluster. + +One manifest can contain a number of distributed validators being operated by the same group of nodes. + +The manifest provides at least the following info: + +- ENRs for each participating operator + - SECP256K1 public keys + - Used to identify a DVC client across the internet + - Forms the basis of identity between charon nodes +- Signature(s) from each key share(s) authorising their respective operator ENRs as acting on their behalf + - Used to link validator key shares to DVC ENRs, includes a nonce to allow for ENR key rotation +- An array of distributed validators operated by this cluster + - The BLS public key of the Distributed Validator + - The TSS verifiers for the group key, from which BLS public keys can be inferred + +## Example manifest + +```json5 title="manifest.yaml" +{ + "version": "obol/charon/manifest/0.0.1", + "description": "dv/2/threshold/3/peer/5", + "distributed_validators": [ + { + "root_pubkey": "0xaf7e10e176ad2cd634009fed0e906e95866d47ec16808cc4df32b3bcfcaffbad9158f52531a086f6d9c54152dc4250da", + "threshold_verifiers": [ + "r34Q4XatLNY0AJ/tDpBulYZtR+wWgIzE3zKzvPyv+62RWPUlMaCG9tnFQVLcQlDa", + "jRadEC0L5vp+sYPUvRgp9b4x/nzN1qGkiFA+lgpwNjq3BiJjhhikMKY8HQ1PJ0R2", + "uQHdtolDJjjXXwnQikhBx9T9Hp20fPXqOS4hP3nZORhtPlVCCvP8IggANkq9o7hF" + ] + }, + { + "root_pubkey": "0x82313d1fc1b7e2e361935b977068434226a0bc1ec3680a35669b63378f0154e419b1daba3531b0068a7af3159e0f56d7", + "threshold_verifiers": [ + "gjE9H8G34uNhk1uXcGhDQiagvB7DaAo1ZptjN48BVOQZsdq6NTGwBop68xWeD1bX", + "ud3X5IV2KqOkBMWRLGpWsuyRQkK0shUKp8pascNEQE3Vo2ujVfs0O+3dPPbi8CYm", + "hQl8KQo8usksZjaE04L6vJRPXrv2k7h542adcK8Ibwhvci1hWwppBc54VvKG9VfL" + ] + } + ], + "peers": [ + "enr:-Ie4QFdd7auMcA6Sht4fD5alWeChra30HTW0eIOr6XkYQtivD2Ev1HNdkyhFnT5LcVKB-2aROv2wAW5EJW5NKLx_fUiAgmlkgnY0gmlwhH8AAAGJc2VjcDI1NmsxoQK1OEYKGHj2rkQflwpMENJhr9_AAVIMdgRjp-D7dPVUVIN0Y3ABg3VkcAI=", + "enr:-Ie4QP4mbZPiuYMGJxpbV1bb5KwYz69pONum1XLQWJNscrABMZMaR8-mco4vZRwHpJfLV-Xq-2MMmGPcWvKGurzoV8SAgmlkgnY0gmlwhH8AAAGJc2VjcDI1NmsxoQPXTrrbopT8F81z6nd9BP6OMaiXdU4hovsGz4alw74JkIN0Y3ADg3VkcAQ=", + "enr:-Ie4QCvui6MrHdcZmCmpenVBzfJ7kylTt2gHBvG-C5Hy7fZCXeM2Ct0NUBcuQZUQgKwiRpIza1qVUFUttaWO7RHwDx6AgmlkgnY0gmlwhH8AAAGJc2VjcDI1NmsxoQLmzL1T7YS3su4_059MUAQD3Dk8PM8Jh_1qq8jUzeaRWoN0Y3AFg3VkcAY=", + "enr:-Ie4QCok_dUP2L9mVUPpLdVl_VLcTwESD7Xd4WYRSbPq__srFVsJT4MPxsQOP68BPXw2IMWvThA6SfBs-PMne__srdSAgmlkgnY0gmlwhH8AAAGJc2VjcDI1NmsxoQLITI6sd1v-A1ArY0oBvIjGPsJWjc1XvbIxjWr1jvRSA4N0Y3AHg3VkcAg=", + "enr:-Ie4QAaRwPBsUloA1AlLmgjRx-zIHipzM06ioU2hH9Uv-mKRNUfScDInXlPGomDslz3QbAu0gxR-Jgq7d3SKHohjI7SAgmlkgnY0gmlwhH8AAAGJc2VjcDI1NmsxoQNfEIdLwYgnPux1pXBg5enZ8jlIsPzMtHAJH1tnRfeMiYN0Y3AJg3VkcAo=" + ] +} + +``` diff --git a/versioned_docs/version-v0.3.0/dv/09_charon_cli_reference.md b/versioned_docs/version-v0.3.0/dv/09_charon_cli_reference.md new file mode 100644 index 0000000000..ceccdf72ec --- /dev/null +++ b/versioned_docs/version-v0.3.0/dv/09_charon_cli_reference.md @@ -0,0 +1,90 @@ +--- +description: A go-based middleware client for taking part in Distributed Validator clusters. +--- + +# Charon CLI reference + +:::caution + +The `charon` client is under heavy development, interfaces are subject to change until a first major version is published. + +::: + +The following is a reference for charon version [`0.3.0`](https://github.com/ObolNetwork/charon/releases/tag/v0.3.0). Find the latest release on [our Github](https://github.com/ObolNetwork/charon/releases). + +```markdown +charon --help +Charon enables the operation of Ethereum validators in a fault tolerant manner by splitting the validating keys across a group of trusted parties using threshold cryptography. + +Usage: + charon [command] + +Available Commands: + bootnode Starts a p2p-udp discv5 bootnode + completion Generate the autocompletion script for the specified shell + create-cluster Create a local charon cluster + enr Return this node's ENR + gen-p2pkey Generates a new p2p key + help Help about any command + run Runs the Charon middleware + version Print version and exit + +Flags: + -h, --help Help for charon + +Use "charon [command] --help" for more information about a command. +``` + +```markdown +charon create-cluster --help +Create a local charon cluster including validator keys, charon p2p keys, and a cluster manifest. See flags for supported features. + +Usage: + charon create-cluster [flags] + +Flags: + --clean Delete the cluster directory before generating it. + --cluster-dir string The target folder to create the cluster in. (default "./charon/cluster") + --config Enables creation of local non-docker config files. + --config-binary string Path of the charon binary to use in the config files. Defaults to this binary if empty. Requires --config. + --config-port-start int Starting port number used in config files. Requires --config. (default 16000) + --config-simnet Configures a simulated network cluster with mock beacon node and mock validator clients. It showcases a running charon in isolation. Requires --config. (default true) + -h, --help Help for create-cluster + -n, --nodes int The number of charon nodes in the cluster. (default 4) + --split-existing-keys Enables splitting of existing non-dvt validator keys into distributed threshold private shares (instead of creating new random keys). + --split-keys-dir string Directory containing keys to split. Expects keys in keystore-*.json and passwords in keystore-*.txt. Requires --split-validator-keys. + -t, --threshold int The threshold required for signature reconstruction. Minimum is n-(ceil(n/3)-1). (default 3) + +``` + +```markdown +charon run --help +Starts the long-running Charon middleware process to perform distributed validator duties. + +Usage: + charon run [flags] + +Flags: + --beacon-node-endpoint string Beacon node endpoint URL (default "http://localhost/") + --data-dir string The directory where charon will store all its internal data (default "./charon/data") + -h, --help Help for run + --jaeger-address string Listening address for jaeger tracing + --jaeger-service string Service name used for jaeger tracing (default "charon") + --log-format string Log format; console, logfmt or json (default "console") + --log-level string Log level; debug, info, warn or error (default "info") + --manifest-file string The path to the manifest file defining distributed validator cluster (default "./charon/manifest.json") + --monitoring-address string Listening address (ip and port) for the monitoring API (prometheus, pprof) (default "127.0.0.1:16001") + --p2p-allowlist string Comma-separated list of CIDR subnets for allowing only certain peer connections. Example: 192.168.0.0/16 would permit connections to peers on your local network only. The default is to accept all connections. + --p2p-bootmanifest Enables using manifest ENRs as discv5 bootnodes. Allows skipping explicit bootnodes if key generation ceremony included correct IPs. + --p2p-bootnode-relay Enables using bootnodes as libp2p circuit relays. Useful if some charon nodes are not have publicly accessible. + --p2p-bootnodes strings Comma-separated list of discv5 bootnode URLs or ENRs. Example: enode://@10.3.58.6:30303?discport=30301. + --p2p-denylist string Comma-separated list of CIDR subnets for disallowing certain peer connections. Example: 192.168.0.0/16 would disallow connections to peers on your local network. The default is to accept all connections. + --p2p-external-hostname string The DNS hostname advertised by libp2p. This may be used to advertise an external DNS. + --p2p-external-ip string The IP address advertised by libp2p. This may be used to advertise an external IP. + --p2p-peerdb string Path to store a discv5 peer database. Empty default results in in-memory database. + --p2p-tcp-address strings Comma-separated list of listening TCP addresses (ip and port) for libP2P traffic. (default [127.0.0.1:16003]) + --p2p-udp-address string Listening UDP address (ip and port) for discv5 discovery. (default "127.0.0.1:16004") + --simnet-beacon-mock Enables an internal mock beacon node for running a simnet. + --simnet-validator-mock Enables an internal mock validator client when running a simnet. Requires simnet-beacon-mock. + --validator-api-address string Listening address (ip and port) for validator-facing traffic proxying the beacon-node API (default "127.0.0.1:16002") +``` diff --git a/versioned_docs/version-v0.3.0/dv/_category_.json b/versioned_docs/version-v0.3.0/dv/_category_.json new file mode 100644 index 0000000000..ebca9af0e2 --- /dev/null +++ b/versioned_docs/version-v0.3.0/dv/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Distributed validators", + "position": 3, + "collapsed": false +} diff --git a/versioned_docs/version-v0.3.0/dvk/01_distributed-validator-keys.md b/versioned_docs/version-v0.3.0/dvk/01_distributed-validator-keys.md new file mode 100644 index 0000000000..ae776429e4 --- /dev/null +++ b/versioned_docs/version-v0.3.0/dvk/01_distributed-validator-keys.md @@ -0,0 +1,16 @@ +--- +Description: >- + An Effort to Accelerate and Standardise the Generation of Distributed + Validators +--- + +# Distributed validator keys + +A 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 achieve fault tolerance in a distributed validator, the individual private key shares need to be generated together. Rather than have a trusted dealer produce a private key, split it and distribute it, the preferred approach is to never construct the full private key at any point, by having each operator in the distributed validator cluster participate in what is known as a **distributed key generation ceremony**. + +A distributed validator key generation ceremony is a type of DKG ceremony. A DVK ceremony produces signed validator deposit and exit data, along with all of the validator key shares and their associated metadata. + +**There is currently an active working group developing DKG.** Further information can be seen on the [working groups](../int/working-groups.md) page. + diff --git a/versioned_docs/version-v0.3.0/dvk/02_distributed_validator_launchpad.md b/versioned_docs/version-v0.3.0/dvk/02_distributed_validator_launchpad.md new file mode 100644 index 0000000000..529f25ad97 --- /dev/null +++ b/versioned_docs/version-v0.3.0/dvk/02_distributed_validator_launchpad.md @@ -0,0 +1,14 @@ +--- +Description: >- + A dapp to securely create Distributed Validator keys alone or with a group. +--- + +# Distributed validator launchpad + +In order to activate an Ethereum validator, 32 ETH must be deposited into the official deposit contract. + +The vast majority of users that created validators to date have used the **[~~Eth2~~ Staking Launchpad](https://launchpad.ethereum.org/)**, a public good open source website built by the Ethereum Foundation alongside participants that later went on to found Obol. This tool has been wildly successful in the safe and educational creation of a significant number of validators on the Ethereum mainnet. + +To facilitate the generation of distributed validator keys amongst remote users with high trust, the Obol Network intends to develop and maintain a website that enables a group of users to come together and create these threshold keys. + +The DV Launchpad is being developed over a number of phases, coordinated by our [DV launchpad working group](../int/working-groups), To participate in this effort, read through the page and sign up at the appropriate link. diff --git a/versioned_docs/version-v0.3.0/dvk/03_dkg_cli_reference.md b/versioned_docs/version-v0.3.0/dvk/03_dkg_cli_reference.md new file mode 100644 index 0000000000..3d4f1dddeb --- /dev/null +++ b/versioned_docs/version-v0.3.0/dvk/03_dkg_cli_reference.md @@ -0,0 +1,88 @@ +--- +Description: >- + A rust-based CLI client for hosting and participating in Distributed Validator key generation ceremonies. +--- + +# DKG CLI reference + + +:::warning + +The `dkg-poc` client is a prototype implementation for generating Distributed Validator Keys. Keys generated with this tool will not work with Charon, and they are not suitable for use. + +::: + +The following is a reference for `dkg-poc` at commit [`6181fea`](https://github.com/ObolNetwork/dkg-poc/commit/6181feaab2f60bdaaec954f11c04ef49c0b3366a). Find the latest release on our [Github](https://github.com/ObolNetwork/dkg-poc). + +`dkg-poc` is implemented as a rust-based webserver for performing a distributed key generation ceremony. This deployment model ended up raising many user experience and security concerns, for example it is both hard and likely insecure to setup a TLS protected webserver at home if you are not a specialist in this area. Further, the PoC is based on an [Aggregatable DKG](https://github.com/kobigurk/aggregatable-dkg) library which is built on sharing a group element rather than a field element, which makes the threshold signing scheme more complex as a result. These factors resulted in a deprecation of this approach, with many valuable insights gained from this client. Currently a DV launchpad and charon based DKG flow serves as the intended [DKG architecture](https://github.com/ObolNetwork/charon/blob/main/docs/dkg.md) for creating Distributed Validator Clusters. + +``` +$ dkg-poc --help + +dkg-poc 0.1.0 +A Distributed Validator Key Generation client for the Obol Network. + +USAGE: + dkg-poc + +FLAGS: + -h, --help Prints help information + -V, --version Prints version information + +SUBCOMMANDS: + help Prints this message or the help of the given subcommand(s) + lead Lead a new DKG ceremony + participate Participate in a DKG ceremony + +``` + +``` +$ dkg-poc lead --help + +dkg-poc-lead 0.1.0 +Lead a new DKG ceremony + +USAGE: + dkg-poc lead [OPTIONS] --num-participants --threshold + +FLAGS: + -h, --help Prints help information + -V, --version Prints version information + +OPTIONS: + -a, --address + The address to bind this client to, to participate in the DKG ceremony (Default: 127.0.0.1:8081) + + -e, --enr + Provide existing charon ENR for this participant instead of generating a new private key to import + + -n, --num-participants The number of participants taking part in the DKG ceremony + -p, --password + Password to join the ceremony (Default is to randomly generate a password) + + -t, --threshold + Sets the threshold at which point a group of shareholders can create valid signatures + +``` + +``` +$ dkg-poc participate --help + +dkg-poc-participate 0.1.0 +Participate in a DKG ceremony + +USAGE: + dkg-poc participate [OPTIONS] --leader-address + +FLAGS: + -h, --help Prints help information + -V, --version Prints version information + +OPTIONS: + -a, --address The address to bind this client to, to participate in the DKG ceremony + (Default: 127.0.0.1:8081) + -e, --enr Provide existing charon ENR for this participant instead of generating a new + private key to import + -l, --leader-address The address of the webserver leading the DKG ceremony + -p, --password Password to join the ceremony (Default is to randomly generate a password) +``` diff --git a/versioned_docs/version-v0.3.0/dvk/_category_.json b/versioned_docs/version-v0.3.0/dvk/_category_.json new file mode 100644 index 0000000000..8ce5d2ebf0 --- /dev/null +++ b/versioned_docs/version-v0.3.0/dvk/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Key generation", + "position": 4, + "collapsed": false +} diff --git a/versioned_docs/version-v0.3.0/fr/_category_.json b/versioned_docs/version-v0.3.0/fr/_category_.json new file mode 100644 index 0000000000..72d8434c21 --- /dev/null +++ b/versioned_docs/version-v0.3.0/fr/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Further reading", + "position": 11, + "collapsed": true +} diff --git a/versioned_docs/version-v0.3.0/fr/eth.md b/versioned_docs/version-v0.3.0/fr/eth.md new file mode 100644 index 0000000000..71bbced763 --- /dev/null +++ b/versioned_docs/version-v0.3.0/fr/eth.md @@ -0,0 +1,131 @@ +# Ethereum resources + +This page serves material necessary to catch up with the current state of Ethereum proof-of-stake development and provides readers with the base knowledge required to assist with the growth of Obol. Whether you are an expert on all things Ethereum or are new to the blockchain world entirely, there are appropriate resources here that will help you get up to speed. + +## **Ethereum fundamentals** + +### Introduction + +* [What is Ethereum?](http://ethdocs.org/en/latest/introduction/what-is-ethereum.html) +* [How Does Ethereum Work Anyway?](https://medium.com/@preethikasireddy/how-does-ethereum-work-anyway-22d1df506369) +* [Ethereum Introduction](https://ethereum.org/en/what-is-ethereum/) +* [Ethereum Foundation](https://ethereum.org/en/foundation/) +* [Ethereum Wiki](https://eth.wiki/) +* [Ethereum Research](https://ethresear.ch/) +* [Ethereum White Paper](https://github.com/ethereum/wiki/wiki/White-Paper) +* [What is Hashing?](https://blockgeeks.com/guides/what-is-hashing/) +* [Hashing Algorithms and Security](https://www.youtube.com/watch?v=b4b8ktEV4Bg) +* [Understanding Merkle Trees](https://www.codeproject.com/Articles/1176140/Understanding-Merkle-Trees-Why-use-them-who-uses-t) +* [Ethereum Block Architecture](https://ethereum.stackexchange.com/questions/268/ethereum-block-architecture/6413#6413) +* [What is an Ethereum Token?](https://blockgeeks.com/guides/ethereum-token/) +* [What is Ethereum Gas?](https://blockgeeks.com/guides/ethereum-gas-step-by-step-guide/) +* [Client Implementations](https://eth.wiki/eth1/clients) + +## **ETH2 fundamentals** + +*Disclaimer: Because some parts of Ethereum consensus are still an active area of research and/or development, some resources may be outdated.* + +### Introduction and specifications + +* [The Explainer You Need to Read First](https://ethos.dev/beacon-chain/) +* [Official Specifications](https://github.com/ethereum/eth2.0-specs) +* [Annotated Spec](https://benjaminion.xyz/eth2-annotated-spec/) +* [Another Annotated Spec](https://notes.ethereum.org/@djrtwo/Bkn3zpwxB) +* [Rollup-Centric Roadmap](https://ethereum-magicians.org/t/a-rollup-centric-ethereum-roadmap/4698) + +### Sharding + +* [Blockchain Scalability: Why?](https://blockgeeks.com/guides/blockchain-scalability/) +* [What Are Ethereum Nodes and Sharding](https://blockgeeks.com/guides/what-are-ethereum-nodes-and-sharding/) +* [How to Scale Ethereum: Sharding Explained](https://medium.com/prysmatic-labs/how-to-scale-ethereum-sharding-explained-ba2e283b7fce) +* [Sharding FAQ](https://eth.wiki/sharding/Sharding-FAQs) +* [Sharding Introduction: R&D Compendium](https://eth.wiki/en/sharding/sharding-introduction-r-d-compendium) + +### Peer-to-peer networking + +* [Ethereum Peer to Peer Networking](https://geth.ethereum.org/docs/interface/peer-to-peer) +* [P2P Library](https://libp2p.io/) +* [Discovery Protocol](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md) + +### Latest News + +* [Ethereum Blog](https://blog.ethereum.org/) +* [News from Ben Edgington](https://hackmd.io/@benjaminion/eth2_news) + +### Prater Testnet Blockchain + +* [Launchpad](https://prater.launchpad.ethereum.org/en/) +* [Beacon Chain Explorer](https://prater.beaconcha.in/) + +### Mainnet Blockchain + +* [Launchpad](https://launchpad.ethereum.org/en/) +* [Beacon Chain Explorer](https://beaconcha.in/) +* [Another Beacon Chain Explorer](https://explorer.bitquery.io/eth2) +* [Validator Queue Statistics](https://eth2-validator-queue.web.app/index.html) +* [Slashing Detector](https://twitter.com/eth2slasher) + +### Client Implementations + +* [Prysm](https://github.com/prysmaticlabs/prysm) developed in Golang and maintained by [Prysmatic Labs](https://prysmaticlabs.com/) +* [Lighthouse](https://github.com/sigp/lighthouse) developed in Rust and maintained by [Sigma Prime](https://sigmaprime.io/) +* [Lodestar](https://github.com/ChainSafe/lodestar) developed in TypeScript and maintained by [ChainSafe Systems](https://chainsafe.io/) +* [Nimbus](https://github.com/status-im/nimbus-eth2) developed in Nim and maintained by [status](https://status.im/) +* [Teku](https://github.com/ConsenSys/teku) developed in Java and maintained by [ConsenSys](https://consensys.net/) + +## Other + +### Serenity concepts + +* [Sharding Concepts Mental Map](https://www.mindomo.com/zh/mindmap/sharding-d7cf8b6dee714d01a77388cb5d9d2a01) +* [Taiwan Sharding Workshop Notes](https://hackmd.io/s/HJ_BbgCFz#%E2%9F%A0-General-Introduction) +* [Sharding Research Compendium](http://notes.ethereum.org/s/BJc_eGVFM) +* [Torus Shaped Sharding Network](https://ethresear.ch/t/torus-shaped-sharding-network/1720/8) +* [General Theory of Sharding](https://ethresear.ch/t/a-general-theory-of-what-quadratically-sharded-validation-is/1730/10) +* [Sharding Design Compendium](https://ethresear.ch/t/sharding-designs-compendium/1888/25) + +### Serenity research posts + +* [Sharding v2.1 Spec](https://notes.ethereum.org/SCIg8AH5SA-O4C1G1LYZHQ) +* [Casper/Sharding/Beacon Chain FAQs](https://notes.ethereum.org/9MMuzWeFTTSg-3Tz_YeiBA?view) +* [RETIRED! Sharding Phase 1 Spec](https://ethresear.ch/t/sharding-phase-1-spec-retired/1407/92) +* [Exploring the Proposer/Collator Spec and Why it Was Retired](https://ethresear.ch/t/exploring-the-proposer-collator-split/1632/24) +* [The Stateless Client Concept](https://ethresear.ch/t/the-stateless-client-concept/172/4) +* [Shard Chain Blocks vs. Collators](https://ethresear.ch/t/shard-chain-blocks-vs-collators/429) +* [Ethereum Concurrency Actors and Per Contract Sharding](https://ethresear.ch/t/ethereum-concurrency-actors-and-per-contract-sharding/375) +* [Future Compatibility for Sharding](https://ethresear.ch/t/future-compatibility-for-sharding/386) +* [Fork Choice Rule for Collation Proposal Mechanisms](https://ethresear.ch/t/fork-choice-rule-for-collation-proposal-mechanisms/922/8) +* [State Execution](https://ethresear.ch/t/state-execution-scalability-and-cost-under-dos-attacks/1048) +* [Fast Shard Chains With Notarization](https://ethresear.ch/t/as-fast-as-possible-shard-chains-with-notarization/1806/2) +* [RANDAO Notary Committees](https://ethresear.ch/t/fork-free-randao/1835/3) +* [Safe Notary Pool Size](https://ethresear.ch/t/safe-notary-pool-size/1728/3) +* [Cross Links Between Main and Shard Chains](https://ethresear.ch/t/cross-links-between-main-chain-and-shards/1860/2) + +### Serenity-related conference talks + +* [Sharding Presentation by Vitalik from IC3-ETH Bootcamp](https://vod.video.cornell.edu/media/Sharding+-+Vitalik+Buterin/1_1xezsfb4/97851101) +* [Latest Research and Sharding by Justin Drake from Tech Crunch](https://www.youtube.com/watch?v=J6xO7DH20Js) +* [Beacon Casper Chain by Vitalik and Justin Drake](https://www.youtube.com/watch?v=GAywmwGToUI) +* [Proofs of Custody by Vitalik and Justin Drake](https://www.youtube.com/watch?v=jRcS9D_gw_o) +* [So You Want To Be a Casper Validator by Vitalik](https://www.youtube.com/watch?v=rl63S6kCKbA) +* [Ethereum Sharding from EDCon by Justin Drake](https://www.youtube.com/watch?v=J4rylD6w2S4) +* [Casper CBC and Sharding by Vlad Zamfir](https://www.youtube.com/watch?v=qDa4xjQq1RE&t=1951s) +* [Casper FFG in Depth by Carl](https://www.youtube.com/watch?v=uQ3IqLDf-oo) +* [Ethereum & Scalability Technology from Asia Pacific ETH meet up by Hsiao Wei](https://www.youtube.com/watch?v=GhuWWShfqBI) + +### Ethereum Virtual Machine + +* [What is the Ethereum Virtual Machine?](https://themerkle.com/what-is-the-ethereum-virtual-machine/) +* [Ethereum VM](https://medium.com/@jeff.ethereum/go-ethereums-jit-evm-27ef88277520) +* [Ethereum Protocol Subtleties](https://github.com/ethereum/wiki/wiki/Subtleties) +* [Awesome Ethereum Virtual Machine](https://github.com/ethereum/wiki/wiki/Ethereum-Virtual-Machine-%28EVM%29-Awesome-List) + +### Ethereum-flavoured WebAssembly + +* [eWASM background, motivation, goals, and design](https://github.com/ewasm/design) +* [The current eWASM spec](https://github.com/ewasm/design/blob/master/eth_interface.md) +* [Latest eWASM community call including live demo of the testnet](https://www.youtube.com/watch?v=apIHpBSdBio) +* [Why eWASM? by Alex Beregszaszi](https://www.youtube.com/watch?v=VF7f_s2P3U0) +* [Panel: entire eWASM team discussion and Q&A](https://youtu.be/ThvForkdPyc?t=119) +* [Ewasm community meetup at ETHBuenosAires](https://www.youtube.com/watch?v=qDzrbj7dtyU) + diff --git a/versioned_docs/version-v0.3.0/fr/golang.md b/versioned_docs/version-v0.3.0/fr/golang.md new file mode 100644 index 0000000000..5bc5686805 --- /dev/null +++ b/versioned_docs/version-v0.3.0/fr/golang.md @@ -0,0 +1,9 @@ +# Golang resources + +* [The Go Programming Language](https://www.amazon.com/Programming-Language-Addison-Wesley-Professional-Computing/dp/0134190440) \(Only recommended book\) +* [Ethereum Development with Go](https://goethereumbook.org) +* [How to Write Go Code](http://golang.org/doc/code.html) +* [The Go Programming Language Tour](http://tour.golang.org/) +* [Getting Started With Go](http://www.youtube.com/watch?v=2KmHtgtEZ1s) +* [Go Official Website](https://golang.org/) + diff --git a/versioned_docs/version-v0.3.0/glossary.md b/versioned_docs/version-v0.3.0/glossary.md new file mode 100644 index 0000000000..87fbace906 --- /dev/null +++ b/versioned_docs/version-v0.3.0/glossary.md @@ -0,0 +1,9 @@ +# Glossary +This page elaborates on the various technical terminology featured throughout this manual. See a word or phrase that should be added? Let us know! + + +### Consensus +A collection of machines coming to agreement on what to sign together + +### Threshold signing +Being able to sign a message with only a subset of key holders taking part - giving the collection of machines a level of fault tolerance. diff --git a/versioned_docs/version-v0.3.0/int/Overview.md b/versioned_docs/version-v0.3.0/int/Overview.md new file mode 100644 index 0000000000..8077159e5a --- /dev/null +++ b/versioned_docs/version-v0.3.0/int/Overview.md @@ -0,0 +1,48 @@ +--- +sidebar_position: 2 +description: An overview of the Obol network +--- + + +## The Network + +The network can be best visualized as a work layer that sits directly on top of base layer consensus. This work layer is designed to provide the base layer with more resiliency and promote decentralization as it scales. As the current chapter of Ethereum matures over the coming years, the community will move onto the next great scaling challenge, which is stake centralization. To effectively mititgate these risks, community building and credible neutrality must be used as a primary design principals. + +Obol as a layer is focused on scaling main chain staking by providing permissionless access to Distributed Validators (DV's). We believe that DV's will and should make up a large portion of mainnet validator configurations. In preparation for the first wave of adoption the network currently utilizes a middleware implementation of Distributed Validator Technology (DVT), to enable the operation of distributed validator clusters that can preserve validators current client and remote signing configurations. + +Similar to how roll up technology laid the foundation for L2 scaling implementations, we believe DVT will do the same for scaling main chain staking while preserving decentralization. Staking infrastructure is entering its protocol phase of evolution, which must include trust-minimized staking networks that can be plugged into at scale. Layers like Obol are critical to the long term viability and resiliency of public networks, especially networks like Ethereum. We believe DVT will evolve into a widely used primitive and will ensure the security, resiliency, and decentralization of the public blockchain networks that adopt it. + +The Obol Network consists of four core public goods: + +- The [Distributed Validator Launchpad](./dvk/01_distributed-validator-keys.md), a CLI tool and dApp for bootstrapping Distributed Validators +- [Charon](./dv/01_introducing-charon.md), a middleware client that enables validators to run in a fault-tolerant, distributed manner +- [Obol Managers](./sc/01_introducing-obol-managers.md), a set of solidity smart contracts for the formation of Distributed Validators +- [Obol Testnets](./testnet.md), a set of on-going public incentivised testnets that enable any sized operator to test their deployment before serving for the mainnet Obol Network + +### Sustainable Public Goods + +The Obol Ecosystem 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 layer must exist for innovation to flow and evolve vertically. Without this layer highly available uptime will continue to be a moat and stake will accumulate amongst a few products. + +The Obol Network will become an open, community governed, self-sustaining project over the coming months and years. 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. + +![](/img/DVT4.png) + +## The Vision + +The road to decentralising stake is a long one. At Obol we have divided our vision into two key versions of distributed validators. + +### V1 - Trusted Distributed Validators + +The first version of distibuted validators will have dispute resolution out of band. Meaning you need to know and communicate with your counterparty 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. + +Obol V1 will utilize retroactive public goods principals to lay the foundation of its economic ecosystem. The Obol Community will responsibly allocate the collected ETH as grants to projects in the staking ecosystem for the entirety of V1. + +### V2 - Trustless Distributed Validators + +V1 of charon serves a small by count, large by stake-weight group of individuals. The long tail of home and small stakers also deserve to have access to fault tolerant validation, but they may not know enough other operators personally to a sufficient level of trust to run a DV cluster together. + +Version 2 of charon will layer in an incentivisation scheme to ensure any operator not online and taking part in validation is not earning 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 deliniation between the two. diff --git a/versioned_docs/version-v0.3.0/int/_category_.json b/versioned_docs/version-v0.3.0/int/_category_.json new file mode 100644 index 0000000000..f23f9bc2d0 --- /dev/null +++ b/versioned_docs/version-v0.3.0/int/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Getting started", + "position": 2, + "collapsed": false +} diff --git a/versioned_docs/version-v0.3.0/int/faq.md b/versioned_docs/version-v0.3.0/int/faq.md new file mode 100644 index 0000000000..ca366842bc --- /dev/null +++ b/versioned_docs/version-v0.3.0/int/faq.md @@ -0,0 +1,24 @@ +--- +sidebar_position: 10 +description: Frequently asked questions +--- + +# Frequently asked questions + +### Does Obol have a token? + +No. Distributed validators use only ether. + +### Can I keep my existing validator client? + +Yes. Charon sits as a middleware between a validator client and it's beacon node. All validators that implement the standard REST API will be supported, along with all popular client delivery software such as DAppNode [packages](https://dappnode.github.io/explorer/#/), Rocket Pool's [smart node](https://github.com/rocket-pool/smartnode), StakeHouse's [wagyu](https://github.com/stake-house/wagyu), and Stereum's [node launcher](https://stereum.net/development/#roadmap). + +### Can I migrate my existing validator into a distributed validator? + +It will be possible to split an existing validator keystore into a set of key shares suitable for a distributed validator, but it is a trusted distribution process, and if the old staking system is not safely shut down, it could pose a risk of double signing alongside the new distributed validator. + +In an ideal scenario, a distributed validator's private key should never exist in full in a single location. + +### Where can I learn more about Distributed Validators? + +Have you checked out our [blog site](https://blog.obol.tech) and [twitter](https://twitter.com/ObolNetwork) yet? Maybe join our [discord](https://discord.gg/obol) too. diff --git a/versioned_docs/version-v0.3.0/int/key-concepts.md b/versioned_docs/version-v0.3.0/int/key-concepts.md new file mode 100644 index 0000000000..7d90bdc291 --- /dev/null +++ b/versioned_docs/version-v0.3.0/int/key-concepts.md @@ -0,0 +1,86 @@ +--- +sidebar_position: 3 +description: Some of the key terms in the field of Distributed Validator Technology +--- + +# Key concepts +This page outlines a number of the key concepts behind the various technologies that Obol is developing. + +## Distributed validator + +![A Distributed Validator](/img/WhatIsADistributedValidator.png) + +A distributed validator is an Ethereum proof-of-stake validator that runs on more than one node/machine. This functionality is provided by **Distributed Validator Technology** (DVT). + +Distributed validator technology removes the problem of single-point failure. Should <33% of the participating nodes in the DVT cluster go offline, the remaining active nodes are still able to come to consensus on what to sign and 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 + +![A Distributed Validator Node](/img/WhatIsADistributedValidatorNode.png) + +A distributed validator node is the set of clients an operator needs to configure and run to fulfil the duties of a Distributed Validator Operator. An operator may also run redundant execution and consensus clients, an execution payload relayer like [mev-boost](https://github.com/flashbots/mev-boost), or other monitoring or telemetry services on the same hardware to ensure optimal performance. + +In the above example, the stack includes geth, lighthouse, charon and lodestar. + +### Execution Client + +An execution client (formerly known as an Eth1 client) specialises in running the EVM and managing the transaction pool for the Ethereum network. These clients provide execution payloads to consensus clients for inclusion into blocks. + +Examples of execution clients include: + +- [Go-Ethereum](https://geth.ethereum.org/) +- [Nethermind](https://docs.nethermind.io/nethermind/) +- [Erigon](https://github.com/ledgerwatch/erigon) + +### Consensus Client + +A consensus client's duty is to run the proof of stake consensus layer of Ethereum, often referred to as the beacon chain. + +Examples of Consensus clients include: + +- [Prysm](https://docs.prylabs.network/docs/how-prysm-works/beacon-node) +- [Teku](https://docs.teku.consensys.net/en/stable/) +- [Lighthouse](https://lighthouse-book.sigmaprime.io/api-bn.html) +- [Nimbus](https://nimbus.guide/) +- [Lodestar](https://github.com/ChainSafe/lodestar) + +### Distributed Validator Client + +A distributed validator client intercepts the validator client ↔ consensus client communication flow over the [standardised REST API](https://ethereum.github.io/beacon-APIs/#/ValidatorRequiredApi), and focuses on two core duties. + +- Coming to consensus on a candidate duty for all validators to sign +- Combining signatures from all validators into a distributed validator signature + +The only example of a distributed validator client built with a non-custodial middleware architecture to date is [charon](./dv/01_introducing-charon.md). + +### Validator Client + +A validator client is a piece of code that operates one or more Ethereum validators. + +Examples of validator clients include: + +- [Vouch](https://www.attestant.io/posts/introducing-vouch/) +- [Prysm](https://docs.prylabs.network/docs/how-prysm-works/prysm-validator-client/) +- [Teku](https://docs.teku.consensys.net/en/stable/) +- [Lighthouse](https://lighthouse-book.sigmaprime.io/api-bn.html) + +## Distributed Validator Cluster + +![A Distributed Validator Cluster](/img/WhatIsADistributedValidatorCluster.png) + +A distributed validator cluster is a collection of distributed validator nodes connected together to service a set of distributed validators generated during a DVK ceremony. + +### Distributed Validator Key + +A distributed validator key is a group of BLS private keys, that together operate as a threshold key for participating in proof of stake consensus with. + +### Distributed Validator Key Share + +One piece of the distributed validator private key. + +### Distributed Validator Key Generation Ceremony + +To achieve fault tolerance in a distributed validator, the individual private key shares need to be generated together. Rather than have a trusted dealer produce a private key, split it and distribute it, the preferred approach is to never construct the full private key at any point, by having each operator in the distributed validator cluster participate in what is known as a Distributed Key Generation ceremony. + +A distributed validator key generation ceremony is a type of DKG ceremony. A DVK ceremony produces signed validator deposit and exit data, along with all of the validator key shares and their associated metadata. diff --git a/versioned_docs/version-v0.3.0/int/working-groups.md b/versioned_docs/version-v0.3.0/int/working-groups.md new file mode 100644 index 0000000000..a644adb3c1 --- /dev/null +++ b/versioned_docs/version-v0.3.0/int/working-groups.md @@ -0,0 +1,146 @@ +--- +sidebar_position: 3 +description: Obol Network's working group structure. +--- + +# Working groups + +The Obol Network is a distributed consensus protocol and ecosystem with a mission to eliminate single points of technical failure risks on Ethereum via Distributed Validator Technology (DVT). The project has reached the point where increasing the community coordination, participation, and ownership will drive significant impact on the growth of the core technology. As a result, the Obol Labs team will open workstreams and incentives to the community, with the first working group being dedicated to the creation process of distributed validators. + +This document intends to outline what Obol is, how the ecosystem is structured, how it plans to evolve, and what the first working group will consist. + +## The Obol ecosystem + +The Obol Network consists of four core public goods: + +- **The DVK Launchpad** - a CLI tool and user interface for bootstrapping Distributed Validators + +- **Charon** - a middleware client that enables validators to run in a fault-tolerant, distributed manner + +- **Obol Managers** - a set of solidity smart contracts for the formation of Distributed Validators + +- **Obol Testnets** - a set of on-going public incentivised testnets that enable any sized operator to test their deployment before serving for the mainnet Obol Network + +## Working group formation + +Obol Labs aims to enable contributor diversity by opening the project to external participation. The contributors are then sorted into structured working groups early on, allowing many voices to collaborate on the standardisation and building of open source components. + +Each public good component will have a dedicated working group open to participation by members of the Obol community. The first working group is dedicated to the development of distributed validator keys and the DV Launchpad. This will allow participants to experiment with the Obol ecosystem and look for mutual long-term alignment with the project. + +The second working group will be focused on testnets after the first is completed. + +## The DVK working group + +The first working group that Obol will launch for participation is focused on the distributed validator key generation component of the Obol technology stack. This is an effort to standardize the creation of a distributed validator through EIPs and build a community launchpad tool, similar to the Eth2 Launchpad today (previously built by Obol core team members). + +The distributed validator key (DVK) generation is a critical core capability of the protocol and more broadly an important public good for a variety of extended use cases. As a result, the goal of the working group is to take a community-led approach in defining, developing, and standardizing an open source distributed validator key generation tool and community launchpad. + +This effort can be broadly broken down into three phases: +- Phase 0: POC testing, POC feedback, DKG implementation, EIP specification & submission +- Phase 1: Launchpad specification and user feedback +- Phase 1.5: Complimentary research (Multi-operator validation) + + +## Phases +DVK WG members will have different responsibilities depending on their participation phase. + +### Phase 0 participation + +Phase 0 is focused on applied cryptography and security. The expected output of this phase is a CLI program for taking part in DVK ceremonies. + +Obol will specify and build an interactive CLI tool capable of generating distributed validator keys given a standardised configuration file and network access to coordinate with other participant nodes. This tool can be used by a single entity (synchronous) or a group of participants (semi-asynchronous). + +The Phase 0 group is in the process of submitting EIPs for a Distributed Validator Key encoding scheme in line with EIP-2335, and a new EIP for encoding the configuration and secrets needed for a DKG process as the working group outlines. + +**Participant responsibilities:** +- Implementation testing and feedback +- DKG Algorithm feedback +- Ceremony security feedback +- Experience in Go, Rust, Solidity, or applied cryptography + +### Phase 1 participation + +Phase 1 is focused on the development of the DV LaunchPad, an open source SPA web interface for facilitating DVK ceremonies with authenticated counterparties. + +To facilitate the generation of distributed validator keys amongst remote users with high trust, Obol Labs intends to develop and maintain a website that enables a group of users to generate the configuration required for a DVK generation ceremony. + +The Obol Labs team is collaborating with Deep Work Studio on a multi-week design and user feedback session that began on April 1st. The collaborative design and prototyping sessions include the Obol core team and genesis community members. All sessions will be recorded and published publicly. + +**Participant responsibilities:** +- DV LaunchPad architecture feedback +- Participate in 2 rounds of syncronous user testing with the Deep Work team (April 6-10 & April 18-22) +- Testnet Validator creation + +### Phase 1.5 participation + +Phase 1.5 is focused on formal research on the demand and understanding of multi-operator validation. This will be a separate research effort that will be taken place by Georgia Rakusen. This research will be turned into a formal report and distributed for free to the ethereum community. Participation in Phase 1.5 is user interview based and involves psychology based testing. This effort began in early April. + +**Participant responsibilities:** +- Complete asyncronous survey +- Pass the survery to profile users to enhance the depth of the research effort +- Produce design assets for the final resarch artifact + +## Phase progress + +The Obol core team has begun work on all three phases of the effort, and will present draft versions as well as launch Discord channels for each phase when relevant. Below is a status update of where the core team is with each phase as of today. + +**Progress:** + +- Phase 0: 60% +- Phase 1: 25% +- Phase 1.5: 30% + +The core team plans to release the different phases for proto community feedback as they approach 75% completion. + +## Working group key objectives + +The deliverables of this working group are: + +### 1. Standardize the format of DVKs through EIPs + +One of the many successes in the Ethereum development community is the high levels of support from all client teams around standardised file formats. It is critical that we all work together as a working group on this specific front. + +Two examples of such standards in the consensus client space include: + +- EIP-2335: A JSON format for the storage and interchange of BLS12-381 private keys +- EIP-3076: Slashing Protection Interchange Format +distributed validator key encoding scheme in line with EIP-2335, and a new EIP for encoding the configuration and secrets needed for a DV Cluster that has outputs based on the working groups feedback. Outputs from the DVK ceremony may include: + +- Signed validator deposit data files +- Signed exit validator messages +- Private key shares for each operator's validator client +- Distributed Validator Cluster manifests to bind each node together + +### 2. A CLI program for distributed validator key (DVK) ceremonies + +One of the key successes of Proof of Stake Ethereum's launch was the availability of high quality CLI tools for generating Ethereum validator keys including eth2.0-deposit-cli and ethdo. + +The working group will ship a similar CLI tool capable of generating distributed validator keys given a standardised configuration and network access to coordinate with other participant nodes. + +As of March 1st, the WG is testing a POC DKG CLI based on Kobi Gurkan's previous work. In the coming weeks we will submit EIPs and begin to implement our DKG CLI in line with our V0.5 specs and the WG's feedback. + +### 3. A Distributed validator launchpad + +To activate an Ethereum validator you need to deposit 32 ether into the official deposit contract. The vast majority of users that created validators to date have used the **[~~Eth2~~ Staking Launchpad](https://launchpad.ethereum.org/)**, a public good open source website built by the Ethereum Foundation and participants that later went on to found Obol. This tool has been wildly successful in the safe and educational creation of a significant number of validators on the Ethereum mainnet. + +To facilitate the generation of distributed validator keys amongst remote users with high trust, Obol Labs will host and maintain a website that enables a group of users to generate distributed validator keys together using a DKG ceremony in-browser. + +Over time, the DV LaunchPads features will primarily extended the spectrum of trustless key generation. The V1 featues of the launchpad can be user tested and commented on by anyone in the Obol Proto Community! + +## Working group participants + +The members of the Phase 0 working group are: + +- The Obol genesis community +- Ethereum Foundation (Carl, Dankrad, Aditya) +- Ben Edgington +- Jim McDonald +- Prysmatic Labs +- Sourav Das +- Mamy Ratsimbazafy +- Kobi Gurkan +- Coinbase Cloud + +The intended universe of Phase 1 & Phase 1.5 will launch with no initial members, though they will immediately be available for submission by participants that have joined the Obol Proto community right [here](https://pwxy2mff03w.typeform.com/to/Kk0TfaYF). Everyone can join the proto community; however, working group participation will be based on relevance and skill set. + + diff --git a/versioned_docs/version-v0.3.0/intro.md b/versioned_docs/version-v0.3.0/intro.md new file mode 100644 index 0000000000..93c3f09525 --- /dev/null +++ b/versioned_docs/version-v0.3.0/intro.md @@ -0,0 +1,20 @@ +--- +sidebar_position: 1 +description: Welcome to the Multi-Operator Validator Network +--- + +# Introduction + +## What is Obol? + +Obol Labs is a research and software development team focused on proof-of-stake infrastructure for public blockchain networks. Specific topics of focus are Internet Bonds, Distributed Validator Technology and Multi-Operator Validation. The team currently includes 10 members that are spread across the world. + +The core team is building the Obol Network, a protocol to foster trust minimized staking through multi-operator validation. This will enable low-trust access to Ethereum staking yield, which can be used as a core building block in a variety of Web3 products. + +## About this documentation + +This manual is aimed at developers and stakers looking to utilize the Obol Network for multi-party staking. To contribute to this documentation, head over to our [Github repository](https://github.com/ObolNetwork/obol-docs) and file a pull request. + +## Need assistance? + +If you have any questions about this documentation or are experiencing technical problems with any Obol-related projects, head on over to our [Discord](https://discord.gg/n6ebKsX46w) where a member of our team or the community will be happy to assist you. diff --git a/versioned_docs/version-v0.3.0/sc/01_introducing-obol-managers.md b/versioned_docs/version-v0.3.0/sc/01_introducing-obol-managers.md new file mode 100644 index 0000000000..c1a650d6da --- /dev/null +++ b/versioned_docs/version-v0.3.0/sc/01_introducing-obol-managers.md @@ -0,0 +1,59 @@ +--- +description: How does the Obol Network look on-chain? +--- + +# Obol Manager Contracts + +Obol develops and maintains a suite of smart contracts for use with Distributed Validators. + +## Withdrawal Recipients + +The key to a distributed validator is understanding how a withdrawal is processed. The most common way to handle a withdrawal of a validator operated by a number of different people is to use an immutable withdrawal recipient contract, with the distribution rules hardcoded into it. + +For the time being Obol uses `0x01` withdrawal credentials, and intends to upgrade to [0x03 withdrawal credentials](https://www.dropbox.com/s/z8kpyl5r2lh1ixe/Screenshot%202021-12-26%20at%2013.53.48.png?dl=0) when smart contract initiated exits are enabled. + +### Ownable Withdrawal Recipient + +```solidity title="WithdrawalRecipientOwnable.sol" +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.0; + +import "@openzeppelin/contracts/access/Ownable.sol"; + +contract WithdrawalRecipientOwnable is Ownable { + receive() external payable {} + + function withdraw(address payable recipient) public onlyOwner { + recipient.transfer(address(this).balance); + } +} + +``` + +An Ownable Withdrawal Recipient is the most basic type of withdrawal recipient contract. It implements Open Zeppelin's `Ownable` interface and allows one address to call the `withdraw()` function, which pulls all ether from the address into the owners address (or another address specified). Calling withdraw could also fund a fee split to the Obol Network, and/or the protocol that has deployed and instantiated this DV. + +### Immutable Withdrawal Recipient + +An immutable withdrawal recipient is similar to an ownable recipient except the owner is hardcoded during construction and the ability to change ownership is removed. This contract should only be used as part of a larger smart contract system, for example a yearn vault strategy might use an immutable recipient contract as its vault address should never change. + +## Registries + +### Deposit Registry + +The Deposit Registry is a way for the deposit and activation of distributed validators to be two separate processes. In the simple case for DVs, a registry of deposits is not required. However when the person depositing the ether is not the same entity as the operators producing the deposits, a coordination mechanism is needed to make sure only one 32 eth deposit is submitted per DV. A deposit registry can prevent double deposits by ordering the allocation of ether to validator deposits. + +### Operator Registry + +If the submission of deposits to a deposit registry needs to be gated to only whitelisted addresses, a simple operator registry may serve as a way to control who can submit deposits to the deposit registry. + +### Validator Registry + +If validators need to be managed on chain programatically rather than manually with humans triggering exits, a validator registry can be used. Deposits getting activated get an entry into the validator registry, and validators using 0x03 exits get staged for removal from the registry. This registry can be used to coordinate many validators with similar operators and configuration. + +:::note + +Validator registries depend on the as of yet unimplemented `0x03` validator exit feature. + +::: + diff --git a/versioned_docs/version-v0.3.0/sc/_category_.json b/versioned_docs/version-v0.3.0/sc/_category_.json new file mode 100644 index 0000000000..c740383c52 --- /dev/null +++ b/versioned_docs/version-v0.3.0/sc/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Smart contracts", + "position": 5, + "collapsed": true +} diff --git a/versioned_docs/version-v0.3.0/testnet.md b/versioned_docs/version-v0.3.0/testnet.md new file mode 100644 index 0000000000..c1d499ee4d --- /dev/null +++ b/versioned_docs/version-v0.3.0/testnet.md @@ -0,0 +1,187 @@ +--- +sidebar_position: 13 +--- + +# Testnets + +![Testnet Roadmap](/img/ObolTestnetRoadmap.png) + +Over the coming quarters, Obol Labs will be coordinating and hosting a number of progressively larger test nets to help harden the charon client and iterate on the key generation tooling. + +The following is a break down of the intended testnet roadmap, the features that are to be complete by each testnet, and their target start date and durations. + +# Testnets + +- [ ] Dev Net 1 +- [ ] Dev Net 2 +- [ ] Athena Public Testnet 1 +- [ ] Bia Attack net +- [ ] Circe Public Testnet 2 +- [ ] Demeter Red/Blue net + +## Devnet 1 + +The first devnet aim will be to have a number of trusted operators test out our earliest tutorial flows. The aim will be for a single user to complete these tutorials alone, using docker compose to spin up 4 charon clients and 4 different validator clients (lighthouse, teku, lodestar and vouch) on a single machine, with the option of adding a single consensus layer client from a weak subjectivity checkpoint (the default will be to connect to our Kiln RPC server, we shouldn't get too much load for this phase). The keys will be created locally in charon, and activated with the existing launchpad or ethdo. + +**Participants:** Obol Dev Team, Client team advisors. + +**State:** Pre-product + +**Network:** Kiln + +**Target start date:** May 2022 + +**Duration:** 1 week + +**Goals:** + +- User test a first tutorial flow to get the kinks out of it. Devnet 2 will be a group flow, so we need to get the solo flow right first +- Prove the distributed validator paradigm with 4 separate VC implementations together operating as one logical validator works +- Get the basics of monitoring in place, for the following testnet where accurate monitoring will be important due to charon running across a newtwork. + +**Test Artifacts:** + +- Responding to a typeform, an operator will list: + - The public key of the distributed validator + - Any difficulties they incurred in the cluster instantiation + - Any deployment variations they would like to see early support for (e.g. windows, cloud, dappnode etc.) + +## Devnet 2 + +The second devnet aim will be to have a number of trusted operators test out our earliest tutorial flows _together_ for the first time. + +The aim will be for groups of 4 testers to complete a group onboarding tutorial, using docker compose to spin up 4 charon clients and 4 different validator clients (lighthouse, teku, lodestar and vouch), each on their own machine at each operators home or their place of choosing, running at least a kiln consensus client. + +As part of this testnet, operators will need to expose charon to the public internet on a static IP address. + +This devnet will also be the first time `charon dkg` is tested with users. The launchpad is not anticipated to be complete, and this dkg will be triggered by a manifest config file created locally by a single operator using the `charon create dkg` command. + +A core focus of this devnet will be to collect network performance data. This will be the first time we will have charon run in variable, non-virtual networks (i.e. the real internet). Focusing on effective collection of performance data in this devnet will be a core focus, to enable gathering even higher signal performance data at scale during public testnets. + +**Participants:** Obol Dev Team, Client team advisors. + +**State:** Pre-product + +**Network:** Kiln + +**Target start date:** May 2022 + +**Duration:** 2 weeks + +**Goals:** + +- User test a first dkg flow +- User test the complexity of exposing charon to the public internet +- Have block proposals in place +- Build up the analytics plumbing to injest network traces from dump files or distributed tracing endpoints + +## Athena Public Testnet 1 + +With tutorials for solo and group flows having been developed and refined. The goal for public testnet 1 is to get distributed validators into the hands of the wider Proto Community for the first time. + +This testnet would be intended to include the Distributed Validator Launchpad. + +The core focus of this testnet is the onboarding experience. This is the first time we would need to provide comprehensive instructions for as many platforms (Unix, Mac, Windows) in as many languages as possible (need to engage language moderators on discord). + +The core output from this testnet is a large number of typeform submissions, for a feedback form we have refined since devnets 1 and 2. + +This will be an unincentivised testnet, and will form as the basis for us figuring out a sybil resistance mechanism for later incentivised testnets. + +**Participants:** Obol Proto Community + +**State:** Bare Minimum + +**Network:** Kiln or a Merged Test Network (e.g. Görli) + +**Target start date:** June 2022 + +**Duration:** 2 week setup, 4 weeks operation + +**Goals:** + +- Engage Obol Proto Community +- Make deploying Ethereum validator nodes accessible +- Generate a huge backlog of bugs, feature requests, platform requests and integration requests + +## Bia Attack Net + +At this point, we have tested best-effort, happy-path validation with supportive participants. The next step towards a mainnet ready client is to begin to disrupt and undermine it as much as possible. + +This testnet needs a consensus implementation as a hard requirement, where it may have been optional for Athena. The intention is to create a number of testing tools to facilitate the disruption of charon, including releasing a p2p network abuser, a fuzz testing client, k6 scripts for load testing/hammering an RPC endpoints and more. + +The aim is to find as many memory leaks, DoS vulnerable endpoints and operations, missing signature verifications and more. This testnet may be centered around a hackathon if suitable. + +**Participants:** Obol Proto Community, Immunefi Bug Bounty searchers + +**State:** Client Hardening + +**Network:** Kiln or a Merged Test Network (e.g. Görli) + +**Target start date:** August 2022 + +**Duration:** 2-4 weeks operation, depending on how resilient the clients are + +**Network:** Merged Test Network (e.g. Görli) + +**Goals:** + +- Break charon in multiple ways +- Improve DoS resistance + +## Cerce Public Testnet II + +After working through the vulnerabilities hopefully surfaced during the attack net, it becomes time to take the stakes up a notch. The second public testnet for Obol will be in partnership with the Gnosis Chain, and will use validators with real skin in the game. + +This is intended to be the first time that Distributed Validator tokenisation comes into play. Obol intends to let candidate operators form groups, create keys that point to pre-defined Obol controlled withdrawal addresses, and submit a typeform application to our testnet team including their created deposit data and manifest lockfile and exit data. (So we can verify the validator pubkey they are submitting is a DV) + +Once the testnet team has verified the operators as real humans not sybil attacking the testnet that have created legitimate DV keys, their validator will be activated with Obol GNO. + +At the end of the testnet period, all validators will be exited, and their performance will be judged to decide the incentivisation they will recieve. + +**Participants:** Obol Proto Community, Gnosis Community, Ethereum Staking Community + +**State:** MVP + +**Network:** Merged Gnosis Chain + +**Target start date:** September 2022 ([Dappcon](https://www.dappcon.io/) runs 12th-14th of Sept. ) + +**Duration:** 6 weeks + +**Network:** Merged Gnosis Chain + +**Goals:** + +- Broad community participation +- First Obol Incentivised Testnet +- Distributed Validator returns competetive versus single validator clients +- Run an unreasonably large percentage of an incentivised test network to see the network performance at scale if a majority of validators moved to DV architectures + +## Demeter Red/Blue Net + +The final planned testnet before a prospective look at mainnet deployment is a testnet that takes inspiration for the Cyber Security industry and makes use of Red Teams and Blue Teams. + +In Cyber Security, Red team are on offense, Blue team are on defence. In Obol's case, Operators will be grouped into clusters based on application and are assigned to either red team or blue team in secret. Once the validators are active, it will be the red teamers goal to disrupt the cluster to the best of their ability, and their rewards will be based on how much worse the cluster performs than optimal. + +The blue team members will aim to keep their cluster online and signing. If they can keep their distributed validator online for the majority of time despite the red teams best efforts, they will recieve an outsized reward versus the red team reward. + +The aim of this testnet is to show that even with directly incentivised byzantine actors, that a distributed validator client can remain online and timely in it's validation, further cementing trust in the clients mainnet readiness. + +**Participants:** Obol Proto Community, Gnosis Community, Ethereum Staking Community, Immunefi Bug Bounty searchers + +**State:** Mainnet ready + +**Network:** Merged Gnosis Chain + +**Target start date:** October 2022 ([Devcon 6](https://devcon.org/en/#road-to-devcon) runs 7th-16th of October. ) + +**Duration:** 4 weeks + +**Network:** Merged Gnosis Chain + +**Goals:** + +- Even with incentivised byzantine actors, distributed validators can reliably stay online +- Charon nodes cannot be DoS'd +- Demonstrate that fault tolerant validation is real, safe and cost competetive. +- Charon is feature complete and ready for audit diff --git a/versioned_sidebars/version-v0.3.0-sidebars.json b/versioned_sidebars/version-v0.3.0-sidebars.json new file mode 100644 index 0000000000..f3436b5d44 --- /dev/null +++ b/versioned_sidebars/version-v0.3.0-sidebars.json @@ -0,0 +1,8 @@ +{ + "version-v0.3.0/tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/versions.json b/versions.json new file mode 100644 index 0000000000..d170c0ad4f --- /dev/null +++ b/versions.json @@ -0,0 +1,3 @@ +[ + "v0.3.0" +]