fiftysix/base-consensus repository overview

⁠Fiftysix Base-Consensus Docker Image

Maintainer: [email protected]⁠

⁠Overview

This Docker image provides the rollup/consensus half of a Base node, built on top of Base's own published ghcr.io/base/node image⁠ rather than compiled from source, the same call made for fiftysix/nitro⁠. Base is an Optimistic Rollup Layer 2 built on Ethereum, incubated by Coinbase and built on the OP Stack. The code can be viewed on the Fiftysix Github⁠.

⁠Tags

• latest: Points to the latest version of base-consensus.
• <version>: Points to a specific Base release, for example 1.4.2.

⁠Why built on the official image, and why a separate image

See fiftysix/base-reth⁠ - the same official-image rationale and execution/consensus split applies here. This image runs Base's own consensus-entrypoint script standalone, pairing with a fiftysix/base-reth container the same way fiftysix/lighthouse pairs with fiftysix/geth.

⁠What is base-consensus?

base-consensus is Base's rollup node, in the lineage of the OP Stack's op-node. It derives the L2 chain from Ethereum L1 and hands new blocks to a paired execution client (fiftysix/base-reth) over the Engine API, rather than maintaining a full chain database of its own.

⁠Usage

⁠Prerequisites

An Ethereum L1 execution RPC endpoint and an L1 beacon endpoint that can serve blob sidecars are required (a default beacon client can't, post-Fusaka - see fiftysix/reth⁠'s blob-serving support), along with a paired fiftysix/base-reth container.

⁠Basic Usage

To run a base-consensus node:

docker pull fiftysix/base-consensus
docker run --name base-consensus -d \
  -e BASE_NODE_L1_ETH_RPC=<your-l1-execution-rpc-url> \
  -e BASE_NODE_L1_BEACON=<your-l1-beacon-url> \
  -e BASE_NODE_L2_ENGINE_RPC=http://base-reth:8551 \
  -e BASE_NODE_L2_ENGINE_AUTH_RAW=<same value given to fiftysix/base-reth> \
  fiftysix/base-consensus

This command will start the base-consensus container, exposing the default RPC and P2P ports.

Note: like fiftysix/base-reth, this image is configured entirely through environment variables, not CLI flags - Base's own upstream consensus-entrypoint script never reads its arguments. All four variables above are required with no default.

⁠Directory Structure

In this Docker image, the following directory is used:

• Data Directory (/data): Unlike base-reth-node, base-consensus has no --datadir/state-directory flag at all - it's a largely stateless derivation pipeline, not a chain database. This directory only persists the optional P2P private key and admin-state file, so a restart keeps the same peer identity instead of announcing as a new one each time.

⁠Mounting Directories

Mounting the Data Directory:

docker run --name base-consensus -v /path/to/local/data:/data -d \
  -e BASE_NODE_L1_ETH_RPC=<your-l1-execution-rpc-url> \
  -e BASE_NODE_L1_BEACON=<your-l1-beacon-url> \
  -e BASE_NODE_L2_ENGINE_RPC=http://base-reth:8551 \
  -e BASE_NODE_L2_ENGINE_AUTH_RAW=<same value given to fiftysix/base-reth> \
  fiftysix/base-consensus

⁠JWT Secret

Unlike every other execution/consensus pairing in this account, the JWT secret here is shared as a value, not a file: give this container the exact same BASE_NODE_L2_ENGINE_AUTH_RAW used for fiftysix/base-reth, and each side writes its own local copy on startup. No shared volume is needed for the secret itself.

⁠Startup Ordering

This image polls the paired execution container's authrpc endpoint until it's ready before starting - no manual wait/retry logic is needed in your own orchestration.

⁠Using base-consensus

⁠Choosing a network

BASE_NODE_NETWORK selects the L2 chain: base (mainnet, the default) or base-sepolia (testnet) - match whatever fiftysix/base-reth's RETH_CHAIN is set to.

docker run --name base-consensus -d \
  -p 9545:9545 -p 9222:9222 -p 9222:9222/udp -p 9223:9223/udp \
  -e BASE_NODE_NETWORK=base-sepolia \
  -e BASE_NODE_L1_ETH_RPC=<your-l1-execution-rpc-url> \
  -e BASE_NODE_L1_BEACON=<your-l1-beacon-url> \
  -e BASE_NODE_L2_ENGINE_RPC=http://base-reth:8551 \
  -e BASE_NODE_L2_ENGINE_AUTH_RAW=<same value given to fiftysix/base-reth> \
  fiftysix/base-consensus

Note: on every start, this image looks up the host's public IP from a short list of public IP-echo services to advertise itself correctly to P2P peers. This happens unconditionally - worth knowing if running in a network with restricted outbound access.

⁠Logging base-consensus

docker logs base-consensus --tail 100

⁠Exposing Ports

The following ports are commonly used by base-consensus and are exposed in this Docker image:

• 9545: RPC server
• 9222: P2P communication (libp2p, TCP)
• 9223/udp: P2P discovery (discv5)
• 9090: Prometheus metrics

⁠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⁠.