README
¶
Charon
The Distributed Validator middleware client
This repo contains the source code for the distributed validator client Charon (pronounced 'kharon'); a HTTP middleware client for Ethereum Staking that enables you to safely run a single validator across a group of independent nodes.
Charon is accompanied by a webapp called the Distributed Validator Launchpad for distributed validator key creation.
Charon is used by Enterprises and DAOs to distribute the responsibility of running Ethereum Validators across a number of different instances and client implementations.
A Distributed Validator Cluster that uses the Charon client to hedge client and hardware failure risks
QuickstartThe easiest way to test out charon is with the charon-distributed-validator-cluster repo which contains a docker compose setup for running a full charon cluster on your local machine.
DocumentationThe Obol Docs website is the best place to get started. The important sections are intro, key concepts and charon.
For detailed documentation on this repo, see the docs folder:
- Configuration: Configuring a charon node
- Architecture: Overview of charon cluster and node architecture
- Project Structure: Project folder structure
- Branching and Release Model: Git branching and release model
- Go Guidelines: Guidelines and principals relating to go development
- Contributing: How to contribute to charon; githooks, PR templates, etc.
There is always the charon godocs for the source code documentation.
Supported Consensus Layer ClientsCharon integrates into the Ethereum consensus stack as a middleware between the validator client and the beacon node via the official Eth Beacon Node REST API. Charon supports any upstream beacon node that serves the Beacon API. Charon aims to support any downstream standalone validator client that consumes the Beacon API.
| Client | Beacon Node | Validator Client | Notes |
|---|---|---|---|
| Teku | ✅ | ✅ | Fully supported |
| Lighthouse | ✅ | ✅ | Fully supported |
| Lodestar | ✅ | *️⃣ | DVT compatibility issue |
| Vouch | *️⃣ | ✅ | Only validator client provided |
| Prysm | ✅ | 🛑 | Validator client requires gRPC API |
| Nimbus | ✅ | *️⃣ | No standalone validator client provided |
It is still early days for the Obol Network and things are under active development. We are moving fast so check back in regularly to track the progress.
Charon is a distributed validator, so its main responsibility is performing validation duties. The following table outlines which clients have produced which duties on a public testnet, and which are still under construction (🚧 )
| Duty \ Client | Teku | Lighthouse | Lodestar | Nimbus | Vouch | Prysm |
|---|---|---|---|---|---|---|
| Attestation | ✅ | ✅ | 🚧 | 🚧 | ✅ | 🚧 |
| Attestation Aggregation | 🚧 | 🚧 | 🚧 | 🚧 | 🚧 | 🚧 |
| Block Proposal | ✅ | ✅ | 🚧 | 🚧 | 🚧 | 🚧 |
| Blinded Block Proposal (mev-boost) | ✅ | ✅ | 🚧 | 🚧 | 🚧 | 🚧 |
| Sync Committee Message | ✅ | ✅ | 🚧 | 🚧 | 🚧 | 🚧 |
| Sync Committee Contribution | 🚧 | 🚧 | 🚧 | 🚧 | 🚧 | 🚧 |
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package app provides the top app-level abstraction and entrypoint for a charon DVC instance.
|
Package app provides the top app-level abstraction and entrypoint for a charon DVC instance. |
|
errors
Package errors provides errors with structured fields and stack traces.
|
Package errors provides errors with structured fields and stack traces. |
|
eth2wrap
Package eth2wrap provides a wrapper for eth2http.Service adding prometheus metrics and error wrapping.
|
Package eth2wrap provides a wrapper for eth2http.Service adding prometheus metrics and error wrapping. |
|
eth2wrap/genwrap
Command genwrap provides a code generator for eth2client provider methods implemented by eth2multi.Service.
|
Command genwrap provides a code generator for eth2client provider methods implemented by eth2multi.Service. |
|
expbackoff
Package expbackoff implements exponential backoff.
|
Package expbackoff implements exponential backoff. |
|
featureset
Package featureset defines a set of global features and their rollout status.
|
Package featureset defines a set of global features and their rollout status. |
|
forkjoin
Package forkjoin provides an API for "doing work concurrently (fork) and then waiting for the results (join)".
|
Package forkjoin provides an API for "doing work concurrently (fork) and then waiting for the results (join)". |
|
lifecycle
Package lifecycle provides a life cycle manager abstracting the starting and stopping of processes by registered start or stop hooks.
|
Package lifecycle provides a life cycle manager abstracting the starting and stopping of processes by registered start or stop hooks. |
|
log
Package log provides global logging functions to be used throughout the charon app.
|
Package log provides global logging functions to be used throughout the charon app. |
|
log/loki
Package loki provides a simple best-effort loki log ingestion client supporting batch sends.
|
Package loki provides a simple best-effort loki log ingestion client supporting batch sends. |
|
promauto
Package promauto is a drop-in replacement of github.com/prometheus/client_golang/prometheus/promauto and adds support for wrapping all metrics with runtime labels.
|
Package promauto is a drop-in replacement of github.com/prometheus/client_golang/prometheus/promauto and adds support for wrapping all metrics with runtime labels. |
|
retry
Package retry provides a generic async function executor with retries for robustness against network failures.
|
Package retry provides a generic async function executor with retries for robustness against network failures. |
|
tracer
Package tracer provides a global OpenTelemetry tracer.
|
Package tracer provides a global OpenTelemetry tracer. |
|
z
Package z provides an API for structured logging fields by wrapping zap.Field.
|
Package z provides an API for structured logging fields by wrapping zap.Field. |
|
Package cluster provides the cluster configuration API.
|
Package cluster provides the cluster configuration API. |
|
Package cmd implements Charon's command-line interface.
|
Package cmd implements Charon's command-line interface. |
|
bcast
Package bcast provides the core workflow's broadcaster component that broadcasts/submits aggregated signed duty data to the beacon node.
|
Package bcast provides the core workflow's broadcaster component that broadcasts/submits aggregated signed duty data to the beacon node. |
|
infosync
Package infosync provides a simple use-case of the priority protocol that prioritises cluster supported versions.
|
Package infosync provides a simple use-case of the priority protocol that prioritises cluster supported versions. |
|
priority
Package priority implements the priority protocol that resolves arbitrary cluster wide priorities.
|
Package priority implements the priority protocol that resolves arbitrary cluster wide priorities. |
|
qbft
Package qbft is an implementation of the https://arxiv.org/pdf/2002.03613.pdf paper referenced by the QBFT spec https://github.com/ConsenSys/qbft-formal-spec-and-verification.
|
Package qbft is an implementation of the https://arxiv.org/pdf/2002.03613.pdf paper referenced by the QBFT spec https://github.com/ConsenSys/qbft-formal-spec-and-verification. |
|
sigagg
Package sigagg provides the sigagg core workflow component that aggregates *threshold* partial signed duty data objects into an aggregated signed duty data object ready to be broadcasted to the beacon chain.
|
Package sigagg provides the sigagg core workflow component that aggregates *threshold* partial signed duty data objects into an aggregated signed duty data object ready to be broadcasted to the beacon chain. |
|
validatorapi
Package validatorapi defines validator facing API that serves the subset of endpoints related to distributed validation and reverse-proxies the rest to the upstream beacon client.
|
Package validatorapi defines validator facing API that serves the subset of endpoints related to distributed validation and reverse-proxies the rest to the upstream beacon client. |
|
sync
Package sync provides Client and Server APIs that ensures robust network connectivity between all peers in the DKG.
|
Package sync provides Client and Server APIs that ensures robust network connectivity between all peers in the DKG. |
|
Package eth2util contains packages and logic relating to eth2 functionality.
|
Package eth2util contains packages and logic relating to eth2 functionality. |
|
deposit
Package deposit provides functions to create deposit data files.
|
Package deposit provides functions to create deposit data files. |
|
enr
Package enr provides a minimal implementation of Ethereum Node Records (ENR).
|
Package enr provides a minimal implementation of Ethereum Node Records (ENR). |
|
keystore
Package keystore provides functions to store and load private keys to/from EIP 2335 (https://eips.ethereum.org/EIPS/eip-2335) compatible keystore files.
|
Package keystore provides functions to store and load private keys to/from EIP 2335 (https://eips.ethereum.org/EIPS/eip-2335) compatible keystore files. |
|
rlp
Package rlp implements the simple byte slice and lists of byte slices encoding/decoding using recursive length prefix encoding scheme as per spec https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/.
|
Package rlp implements the simple byte slice and lists of byte slices encoding/decoding using recursive length prefix encoding scheme as per spec https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/. |
|
tblsconv
Package tblsconv provides functions to convert into and from kryptology bls_sig types.
|
Package tblsconv provides functions to convert into and from kryptology bls_sig types. |
|
Package testutil provides test utilities.
|
Package testutil provides test utilities. |
|
beaconmock
Package beaconmock provides a mock beacon node server and client primarily for testing.
|
Package beaconmock provides a mock beacon node server and client primarily for testing. |
|
combine
Command combine combines threshold BLS secret shares into the group/root BLS secret.
|
Command combine combines threshold BLS secret shares into the group/root BLS secret. |
|
compose/compose
Command compose provides a tool to run, test, debug local charon clusters using docker-compose.
|
Command compose provides a tool to run, test, debug local charon clusters using docker-compose. |
|
genchangelog
Command genchangelog provides a tool to generate a changelog.md file from a git commit range.
|
Command genchangelog provides a tool to generate a changelog.md file from a git commit range. |
|
trackpr
Command trackpr tracks a PR without a ticket and adds it to GitHub project board.
|
Command trackpr tracks a PR without a ticket and adds it to GitHub project board. |
|
validatormock
Package validatormock provides mock validator client functionality.
|
Package validatormock provides mock validator client functionality. |
|
verifypr
Command verifypr provides a tool to verify charon PRs against the template defined in docs/contibuting.md.
|
Command verifypr provides a tool to verify charon PRs against the template defined in docs/contibuting.md. |
Click to show internal directories.
Click to hide internal directories.