diff --git a/cmd/markdown_internal_test.go b/cmd/markdown_internal_test.go index 98815d0e39..bc8626bf0e 100644 --- a/cmd/markdown_internal_test.go +++ b/cmd/markdown_internal_test.go @@ -84,7 +84,7 @@ This document contains all the prometheus metrics exposed by a charon node. All metrics contain the following labels, so they are omitted from the table below: - 'cluster_hash': The cluster lock hash uniquely identifying the cluster. -- 'clustter_name': The cluster lock name. +- 'cluster_name': The cluster lock name. - 'cluster_network': The cluster network name; goerli, mainnet, etc. - 'cluster_peer': The name of this node in the cluster. It is determined from the operator ENR. diff --git a/docs/branching.md b/docs/branching.md index 56a8ce7444..8138026e75 100644 --- a/docs/branching.md +++ b/docs/branching.md @@ -19,11 +19,11 @@ We follow [Trunk Based Development](https://trunkbaseddevelopment.com/) as a bra ## Controlled introduction of change: -- Since a feature cannot be added as a single big merge of a big feature branch, tools and patterns are required that allow gradual controlled introduction of increment changes without breaking. +- Since a feature cannot be added as a single big merge of a big feature branch, tools and patterns are required that allow gradual controlled introduction of incremental changes without breaking. - New code can be added as “dead code”. So, it has not been integrated into the actual program yet. Once it is properly complete, it can be integrated in a single PR. - Some features should however not be enabled straight into prod/mainnet, but should be rolled-out slowly being first tested in `alpha` (internal devnet only), then `beta` (internal and external testnet), and then only `stable` (enabled everywhere). This can be achieved by simple [feature switches](https://trunkbaseddevelopment.com/feature-flags/) (if statements) that enable features based on their `feature_set` status. - Another powerful pattern to gradually introduce change is [branching by abstraction](https://trunkbaseddevelopment.com/branch-by-abstraction/). This basically introduces an abstraction layer at the point where a new feature has to replace an old feature (like an interface). Using dependency injection, the new feature can be integrated during testing/staging while the old feature is still being used in production. -- Note that both feature switches and/or abstraction layers used to roll out a feature should be removed once released to prod/main-net. +- Note that both feature switches and/or abstraction layers used to roll out a feature should be removed once released to prod/mainnet. ### Release Process @@ -44,7 +44,7 @@ The process to follow for the next v0.16.0 release is the following: 5. When all relevant changes have been included in main, a new “release branch”. It must be called `main-v0.16`. - Release branches are called `main-v0.X` - Release branches are high-risk branches, and must be treated with the same security mindset as the `main` branch. - - Note that github branch matching doesn’t support OR logic, so we chose a common `main*` prefix to identify all protected branches. + - Note that Github branch matching doesn’t support OR logic, so we chose a common `main*` prefix to identify all protected branches. 6. After the release branch has been created, the `main` branch app/version is manually updated to `v0.17-dev` and add `v0.17` to `version.Supported()` versions. - `v0.X-dev` indicates that the code is in the main branch. - It also indicates this is development only code not an official release. @@ -57,7 +57,7 @@ The process to follow for the next v0.16.0 release is the following: - Note that the `build-push-release` action should dynamically update the app/version to the value of the git tag when building the docker image. 9. Before a `v0.16.X` release is created, a `v0.16.X-rc[1-99]` release candidate needs to be created and thoroughly tested both internally and externally. 10. After a `v0.16.X` release was created, the release notes need to be created. - - The release github action does auto-generate release notes. + - The release Github action does auto-generate release notes. - If they are incorrect, manual release notes can be created via: `go run testutil/genchangelog/main.go --range=v0.15.0..v0.16.0`. Note that images are built and tagged for each commit on the main and release branch using the app/version tag, e.g. `v0.X-dev` for `main`, and `v0.X-rc` for release branches. Main branch commits are also tagged with `latest`. diff --git a/docs/contributing.md b/docs/contributing.md index 2ea143c1c2..4b5d6a1774 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -18,12 +18,12 @@ instead of opening a public issue or PR on GitHub. - If you have found a bug... - Check for existing bug reports of the same issue in GitHub. - Do not post about it publicly if it is a suspected vulnerability to protect Obol's users; - instead use `security@obol.tech`. + instead, use `security@obol.tech`. - Maybe send a message in relevant community channels if you are unsure whether you are seeing a technical issue. - Open a GitHub issue if everything else checks out 🤓 - Are you thinking of a small change that just makes sense? Feel free to submit a PR. - If you're envisioning a larger feature or are just looking for a discussion, - let's chat in the [Obol Discord](https://discord.com/invite/n6ebKsX46w)under `#dev-community`. + let's chat in the [Obol Discord](https://discord.com/invite/n6ebKsX46w) under `#dev-community`. - A quick sync before coding avoids conflicting work and makes large PRs much more likely to be accepted. - 👀 The Discord channel is currently _invite-only_ to prevent spam. Please ping a team member to get access. @@ -42,7 +42,7 @@ an associated issue with a design discussed and decided upon. Small bug fixes an improvements don't need issues. New features and bug fixes must have tests. Documentation may need to be updated. If you're -unsure what to update, open the PR, and we'll discuss during review. +unsure what to update, open the PR and we'll discuss during review. Note that PRs updating dependencies and new Go versions are not accepted. Please file an issue instead. @@ -75,7 +75,7 @@ Note: PRs can only be merged by obol-bulldozer bot. It is author's responsibilit - The PR title and body are used as the final squash-merged git commit message. - The PR's original git commits are therefore lost (so naming isn't specified) - **PR title format** is defined as: - - Following the [go team's commit format](https://github.com/golang/go/commits/master): `package[/path]: concise overview of change` + - Following the [Go team's commit format](https://github.com/golang/go/commits/master): `package[/path]: concise overview of change` - Prefix identifies the primary package affected by the change. - Prefix can be a single or double hierarchical package name, but not three or more. E.g. `app` , or `app/tracer`. - The rest of the title must be a concise high-level overview in the present tense and starting with lower case. @@ -90,7 +90,7 @@ Note: PRs can only be merged by obol-bulldozer bot. It is author's responsibilit ``` runner/tracer: add jaeger otel exporter -Adds the jaeger exporter to our opentelemetery infra. +Adds the jaeger exporter to our opentelemetry infra. category: feature ticket: #206 @@ -113,7 +113,7 @@ for each PR commit. But it is highly recommended running the githooks locally wh To install githooks: - Follow installation instructions [here](https://pre-commit.com/#installation) to install the `pre-commit` tool. -- Once installed, run `pre-commit install` in the project's root directory. This will setup the hooks. +- Once installed, run `pre-commit install` in the project's root directory. This will set up the hooks. - Note you can skip the hooks by committing with `-n`: `git commit -n -m "look mom no githooks"` To update githooks: diff --git a/docs/dkg.md b/docs/dkg.md index 60f0fbdead..2a2053a8f7 100644 --- a/docs/dkg.md +++ b/docs/dkg.md @@ -20,7 +20,7 @@ The charon client has the responsibility of securely completing a distributed ke A distributed key generation ceremony involves `Operators` and their `Charon clients`. -- An `Operator` is identified by their Ethereum address. They will sign with this address's private key to authenticate their charon client ahead of the ceremony. The signature will be of; a hash of the charon clients ENR public key, the `cluster_definition_hash`, and an incrementing `nonce`, allowing for a direct linkage between a user, their charon client, and the cluster this client is intended to service, while retaining the ability to update the charon client by incrementing the nonce value and re-signing like the standard ENR spec. +- An `Operator` is identified by their Ethereum address. They will sign with this address's private key to authenticate their charon client ahead of the ceremony. The signature will be of a hash of the charon client’s ENR public key, the `cluster_definition_hash`, and an incrementing `nonce`, allowing for a direct linkage between a user, their charon client, and the cluster this client is intended to service, while retaining the ability to update the charon client by incrementing the nonce value and re-signing like the standard ENR spec. - A `Charon client` is also identified by a public/private key pair, in this instance, the public key is represented as an [Ethereum Node Record](https://eips.ethereum.org/EIPS/eip-778) (ENR). This is a standard identity format for both EL and CL clients. These ENRs are used by each charon node to identify its cluster peers over the internet, and to communicate with one another in an [end to end encrypted manner](https://github.com/libp2p/go-libp2p-noise). These keys need to be created by each operator before they can participate in a cluster creation. @@ -37,7 +37,7 @@ This cluster-definition file is created with the help of the [Distributed Valida - The threshold of fault tolerance required (if not choosing the safe default) - The network (fork_version/chainId) that this cluster will validate on - These key pieces of information form the basis of the cluster configuration. These fields (and some technical fields like DKG algorithm to use) are serialised and merklised to produce the manifests `cluster_definition_hash`. This merkle root will be used to confirm that there is no ambiguity or deviation between manifests when they are provided to charon nodes. -- Once the leader is satisfied with the configuration they publish it to the launchpad's data availability layer for the other participants to access. (For early development the launchpad will use a centralised backend db to store the cluster configuration. Near production, solutions like IPFS or arweave may be more suitable for the long term decentralisation of the launchpad.) +- Once the leader is satisfied with the configuration, they publish it to the launchpad's data availability layer for the other participants to access. (For early development the launchpad will use a centralised backend db to store the cluster configuration. Near production, solutions like IPFS or arweave may be more suitable for the long term decentralisation of the launchpad.) - The leader will then share the URL to this ceremony with their intended participants. - Anyone that clicks the ceremony url, or inputs the `config_hash` when prompted on the landing page will be brought to the ceremony status page. (After completing all disclaimers and advisories) - A "Connect Wallet" button will be visible beneath the ceremony status container, a participant can click on it to connect their wallet to the site @@ -53,7 +53,7 @@ This cluster-definition file is created with the help of the [Distributed Valida ## Carrying out the DKG ceremony -Once participant has their cluster-definition file prepared, they will pass the file to charon's `dkg` command. Charon will read the ENRs in the cluster-definition, confirm that its ENR is present, and then will reach out to bootnodes that are deployed to find the other ENRs on the network. (Fresh ENRs just have a public key and an IP address of 0.0.0.0 until they are loaded into a live charon client, which will update the IP address and increment the ENRs nonce and resign with the clients private key. If an ENR with a higher nonce is seen to be a charon client, they will update the IP address of that ENR in their address book.) +Once participants has their cluster-definition file prepared, they will pass the file to charon's `dkg` command. Charon will read the ENRs in the cluster-definition, confirm that its ENR is present, and then will reach out to bootnodes that are deployed to find the other ENRs on the network. (Fresh ENRs just have a public key and an IP address of 0.0.0.0 until they are loaded into a live charon client, which will update the IP address and increment the ENRs nonce and resign with the clients private key. If an ENR with a higher nonce is seen to be a charon client, they will update the IP address of that ENR in their address book.) Once all clients in the cluster can establish a connection with one another and they each complete a handshake (confirm everyone has a matching `cluster_definition_hash`), the ceremony begins. @@ -74,7 +74,7 @@ Once the ceremony is complete, all participants should take a backup of the crea ## Preparing for validator activation -Once the ceremony is complete, and secure backups of key shares have been made by each operator. They must now load these key shares into their validator clients, and run the `charon run` command to turn it into operational mode. +Once the ceremony is complete and secure backups of key shares have been made by each operator. They must now load these key shares into their validator clients, and run the `charon run` command to turn it into operational mode. All operators should confirm that their charon client logs indicate all nodes are online and connected. They should also verify the readiness of their beacon clients and validator clients. Charon's grafana dashboard is a good way to see the readiness of the full cluster from its perspective. diff --git a/docs/metrics.md b/docs/metrics.md index e91751ef6b..ef8173f061 100644 --- a/docs/metrics.md +++ b/docs/metrics.md @@ -4,7 +4,7 @@ This document contains all the prometheus metrics exposed by a charon node. All metrics contain the following labels, so they are omitted from the table below: - `cluster_hash`: The cluster lock hash uniquely identifying the cluster. -- `clustter_name`: The cluster lock name. +- `cluster_name`: The cluster lock name. - `cluster_network`: The cluster network name; goerli, mainnet, etc. - `cluster_peer`: The name of this node in the cluster. It is determined from the operator ENR.