Prepare docs version 0.6.0

ObolNetwork · Jun 7, 2022 · 43674d9 · 43674d9
1 parent b139a18
commit 43674d9
Show file tree

Hide file tree

Showing 35 changed files with 1,816 additions and 44 deletions.
diff --git a/README.md b/README.md
@@ -32,7 +32,7 @@ This command generates static content into the `build` directory and can be serv
 
 ### Deployment
 
-This repo is configured with Github Actions to deploy the built site to github pages. Committing or merging to master will update the production documentation site. 
+This repo is configured with Github Actions to deploy the built site to github pages. Committing or merging to master will update the production documentation site.
 
 ### Versioning
 
@@ -42,6 +42,10 @@ Docusaurus can manage multiple versions of your docs.
 
 Release a version v0.5.0 of your project:
 
+First update the sample command in `./docs/dv/01_introducing-charon.md` and update all CLI sample output in `./docs/dv/09_charon_cli_reference.md`.
+
+Now you are ready to create the next version by running the following command.
+
 ```bash
 yarn run version v0.5.0
 ```
@@ -53,6 +57,8 @@ Your docs now have 2 versions:
 - `v0.5.0` at `http://localhost:3000/docs/` for the version v0.5.0 docs
 - `current` at `http://localhost:3000/docs/next/` for the **upcoming, unreleased docs**
 
+Now push this to a branch and merge to main to release this version update publicly.
+
 #### Add a Version Dropdown
 
 To navigate seamlessly across versions, add a version dropdown.
@@ -66,7 +72,7 @@ module.exports = {
       items: [
         // highlight-start
         {
-          type: 'docsVersionDropdown',
+          type: "docsVersionDropdown",
         },
         // highlight-end
       ],
@@ -97,8 +103,8 @@ Modify `docusaurus.config.js` to add support for the `fr` locale:
 ```js title="docusaurus.config.js"
 module.exports = {
   i18n: {
-    defaultLocale: 'en',
-    locales: ['en', 'fr'],
+    defaultLocale: "en",
+    locales: ["en", "fr"],
   },
 };
 ```
@@ -144,7 +150,7 @@ module.exports = {
       items: [
         // highlight-start
         {
-          type: 'localeDropdown',
+          type: "localeDropdown",
         },
         // highlight-end
       ],

diff --git a/docs/dv/01_introducing-charon.md b/docs/dv/01_introducing-charon.md
@@ -22,7 +22,7 @@ The below graphic visually outlines the internal functionalies of Charon.
 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.4.0 --help
+docker run ghcr.io/obolnetwork/charon:v0.6.0 --help
 ```
 
 For more information on running charon, take a look at our [quickstart guide](../int/quickstart.md). 
diff --git a/docs/dv/09_charon_cli_reference.md b/docs/dv/09_charon_cli_reference.md
@@ -10,7 +10,7 @@ The `charon` client is under heavy development, interfaces are subject to change
 
 :::
 
-The following is a reference for charon version [`v0.4.0`](https://github.com/ObolNetwork/charon/releases/tag/v0.4.0). Find the latest release on [our Github](https://github.com/ObolNetwork/charon/releases).
+The following is a reference for charon version [`v0.6.0`](https://github.com/ObolNetwork/charon/releases/tag/v0.6.0). Find the latest release on [our Github](https://github.com/ObolNetwork/charon/releases).
 
 ### Available Commands
 
@@ -24,14 +24,14 @@ Usage:
   charon [command]
 
 Available Commands:
-  bootnode       Start a discv5 bootnode server
-  completion     Generate the autocompletion script for the specified shell
-  create         Create artifacts for a distributed validator cluster
-  dkg            Participate in a Distributed Key Generation ceremony
-  enr            Print this client's Ethereum Node Record
-  help           Help about any command
-  run            Run the charon middleware client
-  version        Print version and exit
+  bootnode    Start a discv5 bootnode server
+  completion  Generate the autocompletion script for the specified shell
+  create      Create artifacts for a distributed validator cluster
+  dkg         Participate in a Distributed Key Generation ceremony
+  enr         Print this client's Ethereum Node Record
+  help        Help about any command
+  run         Run the charon middleware client
+  version     Print version and exit
 
 Flags:
   -h, --help   Help for charon
@@ -77,13 +77,12 @@ Flags:
       --data-dir string                The directory where charon will store all its internal data (default ".charon/data")
   -h, --help                           Help for enr
       --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://<hex node id>@10.3.58.6:30303?discport=30301.
+      --p2p-bootnodes strings          Comma-separated list of discv5 bootnode URLs or ENRs. (default [http://bootnode.gcp.obol.tech:16000/enr])
+      --p2p-bootnodes-from-lockfile    Enables using cluster lock ENRs as discv5 bootnodes. Allows skipping explicit bootnodes if key generation ceremony included correct IPs.
       --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")
 ```
@@ -100,17 +99,15 @@ 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 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)
+      --clean                       Delete the cluster directory before generating it.
+      --cluster-dir string          The target folder to create the cluster in. (default ".charon/cluster")
+  -h, --help                        Help for cluster
+      --network string              Ethereum network to create validators for. Options: mainnet, prater, kintsugi, kiln, gnosis. (default "prater")
+  -n, --nodes int                   The number of charon nodes in the cluster. (default 4)
+      --split-existing-keys         Split an existing validator's private key into a set of distributed validator private key shares. Does not re-create deposit data for this key.
+      --split-keys-dir string       Directory containing keys to split. Expects keys in keystore-*.json and passwords in keystore-*.txt. Requires --split-existing-keys.
+  -t, --threshold int               The threshold required for signature reconstruction. Minimum is n-(ceil(n/3)-1). (default 3)
+      --withdrawal-address string   Ethereum address to receive the returned stake and accrued rewards. (default "0x0000000000000000000000000000000000000000")
 ```
 
 #### Creating the configuration for a DKG Ceremony
@@ -125,15 +122,16 @@ Usage:
   charon create dkg [flags]
 
 Flags:
-      --fee_recipient_address string   Optional Ethereum address of the fee recipient
-      --fork_version string            Optional hex fork version identifying the target network/chain
+      --dkg-algorithm string           DKG algorithm to use; default, keycast, frost (default "default")
+      --fee-recipient-address string   Optional Ethereum address of the fee recipient
   -h, --help                           Help for dkg
       --name string                    Optional cosmetic cluster name
+      --network string                 Ethereum network to create validators for. Options: mainnet, prater, kintsugi, kiln, gnosis. (default "prater")
       --num-validators int             The number of distributed validators the cluster will manage (32ETH staked for each). (default 1)
-      --operator_enrs strings          Comma-separated list of each operator's Charon ENR address
-      --output-dir string              The folder to write the output cluster_definition.json file to. (default ".")
+      --operator-enrs strings          Comma-separated list of each operator's Charon ENR address
+      --output-dir string              The folder to write the output cluster-definition.json file to. (default ".")
   -t, --threshold int                  The threshold required for signature reconstruction. Minimum is n-(ceil(n/3)-1). (default 3)
-      --withdrawal_address string      Withdrawal Ethereum address
+      --withdrawal-address string      Withdrawal Ethereum address (default "0x0000000000000000000000000000000000000000")
 ```
 
 ### Performing a DKG Ceremony
@@ -151,18 +149,17 @@ Usage:
 
 Flags:
       --data-dir string                The directory where charon will store all its internal data (default ".charon/data")
-      --definition-file string         The path to the cluster definition file. (default ".charon/cluster_definition.json")
+      --definition-file string         The path to the cluster definition file. (default ".charon/cluster-definition.json")
   -h, --help                           Help for dkg
       --log-format string              Log format; console, logfmt or json (default "console")
       --log-level string               Log level; debug, info, warn or error (default "info")
       --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://<hex node id>@10.3.58.6:30303?discport=30301.
+      --p2p-bootnodes strings          Comma-separated list of discv5 bootnode URLs or ENRs. (default [http://bootnode.gcp.obol.tech:16000/enr])
+      --p2p-bootnodes-from-lockfile    Enables using cluster lock ENRs as discv5 bootnodes. Allows skipping explicit bootnodes if key generation ceremony included correct IPs.
       --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")
 ```
@@ -180,22 +177,24 @@ Usage:
 
 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")
+      --data-dir string                The directory where charon will store all its internal data (default ".charon/data")
+      --feature-set string             Minimum feature set to enable by default: alpha, beta, or stable. Warning: modify at own risk. (default "stable")
+      --feature-set-disable strings    Comma-separated list of features to disable, overriding the default minimum feature set.
+      --feature-set-enable strings     Comma-separated list of features to enable, overriding the default minimum feature set.
   -h, --help                           Help for run
       --jaeger-address string          Listening address for jaeger tracing
       --jaeger-service string          Service name used for jaeger tracing (default "charon")
+      --lock-file string               The path to the cluster lock file defining distributed validator cluster (default ".charon/cluster-lock.json")
       --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://<hex node id>@10.3.58.6:30303?discport=30301.
+      --p2p-bootnodes strings          Comma-separated list of discv5 bootnode URLs or ENRs. (default [http://bootnode.gcp.obol.tech:16000/enr])
+      --p2p-bootnodes-from-lockfile    Enables using cluster lock ENRs as discv5 bootnodes. Allows skipping explicit bootnodes if key generation ceremony included correct IPs.
       --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.

diff --git a/docs/int/quickstart.md b/docs/int/quickstart.md
@@ -72,7 +72,7 @@ Don't forget to be a good testnet steward and exit your validator when you are f
 
 ## Run a cluster with others
 
-This section will be completed alongside version `v0.6.0`. Sit tight.
+This section will be completed alongside version `v0.7.0`. Sit tight.
 <!--
 
 Subsections for run as a group:

diff --git a/versioned_docs/version-v0.6.0/cg/_category_.json b/versioned_docs/version-v0.6.0/cg/_category_.json
@@ -0,0 +1,5 @@
+{
+  "label": "Contribution guidelines",
+  "position": 10,
+  "collapsed": true
+}
diff --git a/versioned_docs/version-v0.6.0/cg/bug-report.md b/versioned_docs/version-v0.6.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
+<!--- Provide a general summary of the issue in the Title above -->
+
+## Expected Behaviour
+<!--- What should be happening? -->
+
+## Current Behaviour
+<!--- What happens instead? -->
+
+## Steps to Reproduce
+<!--- Provide a concise set of steps to reproduce this bug.  -->
+1.
+2.
+3.
+4.
+5.
+
+## Detailed Description
+<!--- Provide some context for the issue you are experiencing. -->
+
+## Specifications
+<!--- Provide some information regarding your local system. --->
+Operating system:
+Version(s) used:
+
+## Possible Solution
+<!--- (Optional) Suggest a fix, reason or implementation for the bug. -->
+
+## Further Information
+<!--- Anything else to add?
+```
+