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 validator deployment that uses the Charon client to hedge client and hardware failure risks
QuickstartThe easiest way to get started is with the charon-docker-compose repo which contains a docker compose setup for running a charon cluster on your local machine.
If however, you want to build from source with this repo directly, you can get started with:
# Install go 1.18 or later (on mac with homebrew installed)
brew install go
# Build the charon binary
go build -o charon
# Use charon's create-cluster command to generate a local simnet cluster.
./charon --help
./charon create-cluster --cluster-dir=/tmp/charon-simnet --config=true --config-simnet
/tmp/charon-simnet/run_cluster.sh
The 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 supports any downstream standalone validator client that consumes the Beacon API.
| Client | Beacon Node | Validator Client | Notes |
|---|---|---|---|
| Teku | ✅ | ✅ | Fully supported |
| Lighthouse | ✅ | ✅ | Fully supported |
| Lodestar | ✅ | ✅ | Fully supported |
| 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 status of supported duties are (🚧 means "under construction"):
| Duty | Teku VC | Lighthouse VC |
|---|---|---|
| Attestation | ✅ | ✅ |
| Attestation Aggregation | 🚧 | 🚧 |
| Block Proposal | 🚧 | 🚧 |
| Blinded Block Proposal (mev-boost) | 🚧 | 🚧 |
| Sync Committee Attestation | 🚧 | 🚧 |
| Sync Committee Aggregation | 🚧 | 🚧 |
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 eth2http.Service.
|
Command genwrap provides a code generator for eth2client provider methods implemented by eth2http.Service. |
|
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. |
|
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. |
|
retry
Package retry provides a generic async slot function executor with retries for robustness against network failures.
|
Package retry provides a generic async slot 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 singed duty data to the beacon-node.
|
Package bcast provides the core workflow's broadcaster component that broadcasts/submits aggregated singed duty data to the beacon-node. |
|
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. |
|
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. |
|
keystore
Package keystore provides functions to store and load private keys to/from EIP 2335 compatible keystore files.
|
Package keystore provides functions to store and load private keys to/from EIP 2335 compatible keystore files. |
|
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. |
|
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. |
|
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.