Checkpointz

Checkpointz simplifies the process of running an Ethereum Beacon Chain checkpoint sync endpoint.

⚠️ Checkpointz is still in heavy development. Use with caution. Using with a beacon node that is attached to a validator is currently not recommended.

Features
What is checkpoint sync?
Supported Beacon clients

Usage
- Configuration
- Getting Started

Contributing
- Running locally
  - Backend
  - Frontend
Contact

Features

Operating mode:
- light - The default mode of operation. Provides enough data for users to use your instance to verify the state they got from somewhere else.
- full - Provides all the functionality of light mode, with the additional ability to serve state requests for beacon nodes to checkpoint sync from.
Web UI
- Shows a table of historical epoch boundaries and their corresponding state/block roots for cross referencing.
- Provides an in-built guide for users to get started with checkpoint sync with client-specific information.
- Displays information about the configured upstreams.
Resource reduction
- Adds HTTP cache-control headers depending on the content
DOS protection
- Never routes an incoming request directly to an upstream beacon node
Support for multiple upstream beacon nodes
- Only serves a new finalized epoch once 50%+ of upstream beacon nodes agree
Extensive Prometheus metrics

What is checkpoint sync?

Checkpoint sync is an operation that lets fresh beacon nodes jump to the head of the chain by fetching the state from a trusted & synced beacon node.

More info: https://notes.ethereum.org/sWeLohipS9GdgMugYn9VkQ

Supported Beacon upstreams

	Prysm	Lighthouse	Nimbus	Lodestar	Teku
Light mode	✅	✅	✅	✅	✅
Full mode	✅	✅	✅	✅	with `--data-storage-mode archive`

Note: Teku will require a resync from genesis if you enable --data-storage-mode archive.

Usage

Checkpointz requires a config file. An example file can be found here.

Checkpoint sync provider for Ethereum beacon nodes

Usage:
  checkpointz [flags]

Flags:
      --config string   config file (default is config.yaml) (default "config.yaml")
  -h, --help            help for checkpointz

Configuration

Checkpointz relies entirely on a single yaml config file.

Name	Default	Description
global.listenAddr	`:5555`	The address the main http server will listen on
global.logging	`warn`	Log level (`panic`, `fatal`, `warn`, `info`, `debug`, `trace`)
global.metricsAddr	`:9090`	The address the metrics server will listen on
checkpointz.caches.blocks.max_items	`200`	Controls the amount of "block" items that can be stored by Checkpointz (minimum 3)
checkpointz.caches.states.max_items	`5`	Controls the amount of "state" items that can be stored by Checkpointz (minimum 3). These states are very large and this value will directly relate to memory usage. Anything higher than 10 is not recommended
checkpointz.mode	`light`	Controls the mode to run checkpointz in. `light` mode will only serve `blocks`, allowing users to use your Checkpointz as a cross reference. `full` will server `blocks` and `state`, allowing users to additonal use your Checkpointz as their state provider. When in full mode the upstream beacon should ONLY be tasked with serving checkpoint data (don't validate on this instance.)
checkpointz.historical_epoch_count	`20`	Controls the amount of historical epoch boundaries that Checkpointz will fetch and serve.
checkpointz.frontend.enabled	`true`	if the frontend should be enabled
checkpointz.frontend.brand_image_url		The brand logo to display on the frontend
checkpointz.frontend.brand_name		The name of the brand to display on the frontend
checkpointz.frontend.public_url		The public URL of where the frontend will be served from
beacon.upstreams[].name		Shown in the frontend
beacon.upstreams[].address		The address of your beacon node. Note: NOT shown in the frontend
beacon.upstreams[].dataProvider		If true, Checkpointz will use this instance to fetch beacon blocks/state. If false, will only be used for finality checkpoints

Simple example

# use defaults and add a single beacon upstream node

beacon:
  upstreams:
  - name: remote
    address: http://localhost:5052
    dataProvider: true

Full mode

checkpointz:
  mode: full

beacon:
  upstreams:
  - name: remote
    address: http://localhost:5052 # When in full mode the upstream beacon should ONLY be tasked with serving checkpoint data (don't validate on this instance.)
    dataProvider: true

Disabled frontend

checkpointz:
  frontend:
    enabled: false

beacon:
  upstreams:
  - name: remote
    address: http://localhost:5052
    dataProvider: true

Full example

global:
  # The address the main http server will listen on
  listenAddr: ":5555"
  # Log level (panic, fatal, warn, info, debug, trace)
  logging: "debug"
  # The address the metrics server will listen on
  metricsAddr: ":9090"

checkpointz:
  mode: light
  caches:
    blocks:
      # Controls the amount of "block" items that can be stored by Checkpointz (minimum 3)
      max_items: 200
    states:
      # Controls the amount of "state" items that can be stored by Checkpointz (minimum 3)
      # These starts a very large and this value will directly relate to memory usage. Anything higher than 
      # 10 is not recommended.
      max_items: 5
  historical_epoch_count: 20 # Controls the amount of historical epoch boundaries that Checkpointz will fetch and serve.
  frontend:
    # if the frontend should be enabled
    enabled: true
    # The brand logo to display on the frontend (optional)
    # brand_image_url: https://www.cdn.com/logo.png
    # The name of the brand to display on the frontend (optional)
    # brand_name: Brandname
    # The public URL of where the frontend will be served from (optional)
    # public_url: https://www.domain.com

beacon:
  # Upstreams configures the upstream beacon nodes to use.
  upstreams:
    # Shown in the frontend
  - name: remote
    # The address of your beacon node. Note: NOT shown in the frontend
    address: http://localhost:5052
    # If true, Checkpointz will use this instance to fetch beacon blocks/state. If false, will only be used for finality checkpoints.
    dataProvider: true

Getting Started

Download a release

Download the latest release from the Releases page. Extract and run with:

./checkpointz --config your-config.yaml

Docker

Available as a docker image at ethpandaops/checkpointz

Images

latest - distroless, multiarch
latest-debian - debian, multiarch
$version - distroless, multiarch, pinned to a release (i.e. 0.4.0)
$version-debian - debian, multiarch, pinned to a release (i.e. 0.4.0-debian)

Quick start

docker run -d  --name checkpointz -v $HOST_DIR_CHANGE_ME/config.yaml:/opt/checkpointz/config.yaml -p 9090:9090 -p 5555:5555 -it ethpandaops/checkpointz:latest --config /opt/checkpointz/config.yaml;
docker logs -f checkpointz;

Kubernetes via Helm

helm repo add ethereum-helm-charts https://skylenet.github.io/ethereum-helm-charts

helm install checkpointz ethereum-helm-charts/checkpointz -f your_values.yaml

Grafana

Download the Checkpointz dashboard here

Building yourself (requires Go)

Clone the repo

go get github.com/ethpandaops/checkpointz

Change directories
```
cd ./checkpointz
```
Build the binary
```
 go build -o checkpointz .
```
Run the service
```
 ./checkpointz
```

Contributing

Contributions are greatly appreciated! Pull requests will be reviewed and merged promptly if you're interested in improving the Checkpointz!

Fork the project
Create your feature branch:
- git checkout -b feat/new-feature
Commit your changes:
- git commit -m 'feat(profit): new feature
Push to the branch: -git push origin feat/new-feature
Open a pull request

Running locally

Backend

go run main.go --config your_config.yaml

Frontend

A basic frontend is provided in this project in ./web directory which needs to be built before it can be served by the server, eg. http://localhost:5555.

The frontend can be built with the following command;

# install node modules and build
make build-web

Building frontend requires npm and NodeJS to be installed.

Contact

Sam - @samcmau

Andrew - @savid

chrishobcroft/checkpointz