fiftysix/lodestar repository overview

⁠Fiftysix Lodestar Docker Image

Maintainer: [email protected]⁠

⁠Overview

This Docker image provides a fully functional Lodestar client built using the Fiftysix base image. Lodestar is a TypeScript implementation of the Ethereum Consensus specification, developed by ChainSafe Systems. It connects to the Ethereum P2P network, tracks the beacon chain, and works together with a paired execution client to keep a full Ethereum node in sync. The code can be viewed on the Fiftysix Github⁠.

⁠Tags

• latest: Points to the latest version of Lodestar.
• <version>: Points to a specific version of Lodestar. For example, 1.48.0.

⁠What is Lodestar?

Lodestar is an Ethereum consensus client implemented in TypeScript, built and maintained by ChainSafe Systems. It operates as a beacon node in Ethereum's Proof of Stake (PoS) network, implementing the consensus protocol, tracking validator duties, and communicating with a paired execution client over the authenticated Engine API. Following the merge⁠, a consensus client like Lodestar is required alongside an execution client (such as Reth, Geth, Erigon, Besu, or Nethermind) to run a complete Ethereum node.

⁠Usage

⁠Prerequisites

Lodestar cannot run standalone. To run Lodestar effectively, you'll need a paired Ethereum execution client (such as Reth, Geth, Erigon, Besu, or Nethermind) already running, and the exact same JWT secret the execution client generated (at <execution client's data dir>/jwt.hex) shared into the Lodestar container - Lodestar must never generate its own. See the execution/consensus pairing notes⁠ for the full mechanism.

⁠Basic Usage

To run a Lodestar node paired with an execution client already running on the same Docker network as reth-node:

docker pull fiftysix/lodestar
docker run --name lodestar -d \
  -v /path/to/execution-client/data:/node/lodestar/exec-jwt:ro \
  fiftysix/lodestar \
  beacon --execution.urls http://reth-node:8551 --jwtSecret /node/lodestar/exec-jwt/jwt.hex

This command starts the Lodestar container, pointed at the paired execution client's Engine API and shared JWT secret, exposing the default REST API and P2P ports. Note: the first docker run after pulling a fresh image may take a few seconds longer than subsequent starts, one time only, as the image unpacks its bundled runtime.

⁠Directory Structure

In this Docker image, the following directories are used:

• Data Directory (/node/lodestar/data): This is where Lodestar stores the beacon chain database and other related files. This directory is specified in the Dockerfile and should be mounted if you want to persist data across container restarts.
• Scripts Directory (/node/lodestar/scripts): This directory contains the entrypoint script (lodestar-entrypoint.sh) and any other scripts that may be needed for starting or managing Lodestar.

⁠Mounting Directories

You can mount host directories to the container's data and scripts directories to customize the behavior of the Lodestar software.

Mounting the Data Directory: To persist Lodestar data across container restarts, you can mount a host directory to the container's data directory:

docker run --name lodestar -v /path/to/local/data:/node/lodestar/data -d fiftysix/lodestar ...

Mounting the Scripts Directory: If you have custom scripts you want to include, you can mount them to the scripts directory. For example, to replace the entrypoint script:

docker run --name lodestar -v /path/to/local/scripts:/node/lodestar/scripts -d fiftysix/lodestar ...

⁠Logging Lodestar

docker logs lodestar --tail 100

⁠Using Lodestar

⁠Starting Lodestar with Custom Options

To start Lodestar with custom options, such as a different REST port, pass additional flags after beacon:

docker run --name lodestar -d \
  -p 9596:9596 -p 9000:9000 -p 9000:9000/udp \
  -v /path/to/execution-client/data:/node/lodestar/exec-jwt:ro \
  fiftysix/lodestar \
  beacon --execution.urls http://reth-node:8551 --jwtSecret /node/lodestar/exec-jwt/jwt.hex \
  --rest.port 9596

⁠Exposing Ports

The following ports are commonly used by Lodestar and are exposed in this Docker image:

• 9596: REST (Beacon) API server
• 9000: P2P communication (TCP and UDP)

⁠Docker Compose

Lodestar can also be run using Docker Compose, paired with any Fiftysix Ethereum execution client (Reth, Geth, Erigon, Besu, or Nethermind) to form a complete Ethereum node, with Lodestar handling consensus. Examples of these Docker Compose files can be found on the Fiftysix Github⁠.

⁠Support

For support, please contact [email protected]⁠.

⁠About Fiftysix

Fiftysix is committed to making blockchain technology accessible, efficient, and reliable through robust decentralization. Learn more at fiftysix.tech⁠.