Checkpointz

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

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

Contents

• Features
• What is checkpoint sync?
• Supported Beacon clients
• Usage
  • Configuration
  • Simple example
  • Full mode
  • Disabled frontend
  • Full example
  • Getting Started
  • Download a release
  • Docker
    • Images
  • Kubernetes via Helm
  • Grafana
• 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

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.

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

Read more

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)

1. Clone the repo

   go get github.com/ethpandaops/checkpointz

2. Change directories

   cd ./checkpointz

3. Build the binary

   go build -o checkpointz .

4. 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!

1. Fork the project
2. Create your feature branch:
   • git checkout -b feat/new-feature
3. Commit your changes:
   • git commit -m 'feat(profit): new feature
4. Push to the branch: -git push origin feat/new-feature
5. 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