charon

README

Charon - The Obol SSV middleware client

This repo contains the source code for the Obol Client, charon, a middleware HTTP client and server for Ethereum Staking that enables HA validation through the use of the Shared Secret Validator staking model.

Obol is used by Enterprises and DAOs to distribute the responsibility of running Ethereum Validators.

Quickstart

This repo contains the GoLang source code for the middleware, a docker-compose file for deploying the client in a local dev environment, and deployment files for deploying this client to a test cluster. To get started:

# Setup env vars, copy .env.template and then manually enter the correct secrets for the likes of Eth1 nodes etc.
cp .env.template .env

# Local development
make up

Compile and Test Locally

First you need to have Go 1.17 installed, then you need to run Go build:

# On mac with homebrew installed
brew install go

# Used for building from source
go build

# Run the charon client
./charon --help

Configuration

In descending order, the Charon client checks the following places for client configuration info:

• As environment variables beginning with CHARON_, with hyphens substituted for underscores. e.g. CHARON_BEACON_NODE=http://....
• Declared in a yaml file in ~/.charon.yaml, e.g. beacon-node: http://...
• Passed in as CLI params to the binary, e.g. --beacon-node http://...

Repo Overview

Charon is built in GoLang, with Cobra managing its command line interfaces, and using Viper for it's configuration management.

Folder Organisation

api

Contains files relating to charon's HTTP client and server API

cmd

Contains files relating to the command line commands and argument management. Uses Cobra.

config

Handles the separation of argument parsing from external sources to parameter passing to internal processes. Allows charon processes to declare what parameters they need using the Golang Functional Options Pattern. Uses Cobra's companion package Viper.

internal

Internal structs and services for the charon client, not intended to be interacted with directly by external consumers.

local

Config and data storage mount point for local developement of the charon client with docker-compose.

logging

Helper file for setting log level and overriding zerolog config

nginx

Temporary middleman between validator and beacon clients for testing purposes

Deployment workflow

• Checkout a branch and commit your work
• Open a PR
• Once CI passes it can be merged to master
• Commits on master can be tagged for public release with a command like; git tag -a v0.0.1 -m "Charon v0.0.1: Hello Acheron"

To Do List

• Beacon client syncing
• Validator client connected
• Weak Subjectivity Working for faster syncs
• Nginx pass through proxy server
• GoLang Process
• CI/CD to build and test GoLang process
• Dockerised GoLang Process
• GoLang process operating as a passthrough HTTP server
• GoLang pass through proxy server
• Multiple Validators and Proxy Servers
• Test suite for DKG
• Docker Compose file for running an SSV
• Github CI for GoLang build of source
• Github CI for Docker build

Lessons Learned

• I don't want to wait to sync a full testnet, what can I do?
  • You can use what's called wak subjectivity sync, which basically accepts a checkpoint from another node and starts from there. You can get a checkpoint from infura by calling (with the appropriate env vars set):

  curl https://${INFURA_PROJECT_ID}:${INFURA_PROJECT_SECRET}@eth2-beacon-prater.infura.io/eth/v1/beacon/states/finalized/finality_checkpoints
  

  • Then take the state root from this response + the epoch and set them in the TEKU_WS_CHECKPOINT env var and restart your docker-compose. Teku should start a sync from the checkpoint epoch you've given it instead of from the start.

Bugs encountered / gotchas

• Teku fails to start on a new chain if there is data in the temporary db stored in ./local/.data/teku/. Error is like:

  beacon  | Supplied deposit contract (0x77f7bed277449f51505a4c54550b074030d989bc) does not match the stored database (). Check that the existing database matches the current network settings.
  

  • Fixed by rm -rf ./local/.data/teku

• charon test beacon errors with an error something like: panic: parse 192.168.2.2:5051: first path segment in URL cannot contain colon.

  • The issue is beacon-node URIs need to specify a scheme, prepend IP addresses with http://.

Documentation

Overview

Copyright © 2021 Obol Technologies Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.