base/node Administrator & Developer Guide

Operational reference for the base/node repository. Audience: node operators, platform engineers, SRE, and contributors. Covers architecture, system requirements, the full configuration surface, deployment, day-to-day operations, performance tuning, security posture, developer internals, and integration points.

1. Architecture Overview

base/node is not a node implementation. It is a thin orchestration layer — a few Dockerfiles, entrypoint shell scripts, pinned-version manifests, and a small Go dependency-bumping utility — that composes upstream binaries (op-node, base-consensus, geth/op-geth, reth/base-reth-node, nethermind) into a reproducible Base-network node deployment.

1.1 What This Repo Does (And Does Not)

What it does NOT do:

• Does not publish pre-built container images. Every deployment builds the upstream binaries from source.
• Does not include a Base node binary of its own (besides the dependency_updater CI tool).
• Does not provide key management, remote signing, or wallet functionality.
• Does not implement the Base consensus or execution protocol — those live in upstream repos.

1.2 Topology

+--------------------------------------------------------------------+
|                        Your Base Node Host                         |
|                                                                    |
|  +-----------------------------+  +-----------------------------+  |
|  | Container: execution        |  | Container: node             |  |
|  | (built from <CLIENT>/       |  | (same image, different cmd) |  |
|  |  Dockerfile)                |  |                             |  |
|  |                             |  |                             |  |
|  |  supervisord                |  |  supervisord                |  |
|  |   `-- execution-entrypoint  |  |   `-- consensus-entrypoint  |  |
|  |       (geth | reth |        |  |       |- USE_BASE_CONSENSUS |  |
|  |        nethermind)          |  |       |    -> base-consensus|  |
|  |                             |  |       `- else               |  |
|  |                             |  |            -> op-node       |  |
|  |  Ports: 8545, 8546,         |  |  Ports: 8545->7545, 9222,   |  |
|  |         6060->7301,         |  |         7300, 6060          |  |
|  |         30303 (TCP+UDP)     |  |                             |  |
|  +----+------------------------+  +----+------------------------+  |
|       | Engine API (port 8551, JWT)    |                           |
|       |   ws:// or http://             |                           |
|       |    (network-dependent)         |                           |
|       +--------------------------------+                           |
|                                                                    |
|  Shared volume: ${HOST_DATA_DIR} -> /data (execution only)         |
+--------------------------------------------------------------------+
                              ^                 ^
                              |                 |
                              | L1 RPC          | P2P (Base peers)
                              | L1 Beacon       |
                              | L1 Beacon       |
                              |   Archiver      |
                              v                 v
              +----------------------+   +-------------------+
              |  Ethereum L1         |   |  Base network     |
              |  (your provider)     |   |  peers            |
              +----------------------+   +-------------------+

1.3 Component Inventory

1.4 Container Duality

The execution and node services are built from the same Dockerfile — both contain the full set of binaries (geth/reth/nethermind, op-node, and optionally base-consensus). They differ only in the command: field:

• execution runs ./execution-entrypoint.
• node runs ./consensus-entrypoint.

Note

Because both containers carry all binaries, memory overhead is slightly higher than a minimal split, but image management is simpler — a single client build produces the complete stack.

1.5 Engine API Handshake

consensus-entrypoint (or base-consensus-entrypoint)
    |
    | 1. Poll ${OP_NODE_L2_ENGINE_RPC} (ws/http) until HTTP 401 is returned.
    |    The 401 proves the execution client is up and rejecting unauthed calls.
    |
    | 2. get_public_ip() tries four HTTP IP-echo services in sequence
    |    (ifconfig.me -> api.ipify.org -> ipecho.net -> v4.ident.me).
    |
    | 3. Write BASE_NODE_L2_ENGINE_AUTH_RAW hex to BASE_NODE_L2_ENGINE_AUTH
    |    (default: /tmp/engine-auth-jwt).
    |
    | 4. exec ./op-node (or base-consensus node | base-consensus follow).
    v
op-node / base-consensus
    |
    | Opens Engine API connection to the execution container.
    |    (Reads JWT from the same path; both clients share /tmp inside their container.)
    v
execution-entrypoint (geth/reth/nethermind)
    |
    | Reads BASE_NODE_L2_ENGINE_AUTH_RAW and writes the same file
    |    so --authrpc.jwtsecret matches.

1.6 Tech Stack

Note

Coinbase's chosen execution client in production is reth (archive). Reth is built from base/base (the team's hard fork that bundles base-reth-node and base-consensus together), not from paradigmxyz/reth directly.

2. System Requirements

2.1 Hardware

2.2 Software

2.3 External Dependencies

The node operator must supply:

2.4 Network Requirements

Inbound (must be reachable from the public internet):

Outbound:

• Sequencer HTTPS — https://mainnet-sequencer.base.org, https://sepolia-sequencer.base.org (port 443).
• L1 provider (yours).
• L1 beacon and archiver (yours).
• Public-IP echo services on port 80: ifconfig.me, api.ipify.org, ipecho.net, v4.ident.me. The entrypoints require at least one of these to respond.

3. Configuration Reference

3.1 Host-Side .env

Consumed by docker compose itself, not the containers.

Important

The shipped .env sets USE_BASE_CONSENSUS=true which only works with CLIENT=reth. Always set CLIENT explicitly in production. The README claims reth is the default, but the compose file falls back to geth via ${CLIENT:-geth} — see issue #1010.

3.2 Per-Network Env Files

.env.mainnet and .env.sepolia are injected into both containers via env_file:. Differences between them:

Note

The mainnet vs. Sepolia transport swap on OP_NODE_L2_ENGINE_RPC (http ↔ ws) and BASE_NODE_L2_ENGINE_RPC (inverse) is intentional — it exercises both engine transports across networks.

3.3 Mandatory User-Provided Values

3.4 Variable Namespaces

3.5 Optional Feature Toggles

3.6 JWT Engine Auth

BASE_NODE_L2_ENGINE_AUTH=/tmp/engine-auth-jwt
BASE_NODE_L2_ENGINE_AUTH_RAW=688f5d737bad920bdfb2fc2f488d6b6209eebda1dae949a8de91398d932c517a

Caution

The shipped hex (688f5d73...517a) is a public sample in both .env.mainnet and .env.sepolia. Every deployment using the shipped value uses an identical JWT. This is acceptable only because authrpc.port (8551) is not published by the compose file. If a misconfigured firewall ever exposes 8551, that is an immediate elevation path. Generate your own with openssl rand -hex 32 for any internet-facing node.

3.7 Reference — Shipped Variables (Pre-Filled, Change Only If You Know Why)

3.8 Pinned Upstream Versions (versions.json)

{
  "base_reth_node": {
    "tag": "v0.7.6",
    "commit": "5759d44b9384fd2ecde6c3fea6372e7c096e6267",
    "owner": "base",
    "repo": "base",
    "tracking": "release"
  },
  "nethermind": {
    "tag": "1.36.2",
    "commit": "f5507dec1c9c7f5e31dadae445c08622be166054",
    "owner": "NethermindEth",
    "repo": "nethermind",
    "tracking": "release"
  },
  "op_geth": {
    "tag": "v1.101702.0",
    "commit": "d0734fd5f44234cde3b0a7c4beb1256fc6feedef",
    "owner": "ethereum-optimism",
    "repo": "op-geth",
    "tracking": "release"
  },
  "op_node": {
    "tag": "op-node/v1.16.11",
    "commit": "cba7aba0c98aae22720b21c3a023990a486cb6e0",
    "tagPrefix": "op-node",
    "owner": "ethereum-optimism",
    "repo": "optimism",
    "tracking": "release"
  }
}

versions.env is regenerated from this JSON by dependency_updater and consumed by every Dockerfile to clone the upstream repos at exactly these commits. See §8 for the updater internals.

4. Deployment & Scaling

4.1 Single-Host Deployment

git clone https://github.com/base/node.git
cd node

# 1. Pick a client and an env file
echo 'CLIENT=reth'                  >  .env.local
echo 'HOST_DATA_DIR=./reth-data'    >> .env.local
echo 'USE_BASE_CONSENSUS=true'      >> .env.local

# 2. Edit .env.mainnet — set L1 endpoints

# 3. Build + start
CLIENT=reth docker compose up --build -d

# 4. Watch logs
docker compose logs -f

4.2 Multi-Node (Mainnet + Sepolia) On One Host

Use distinct project names to keep container names separate, and distinct host ports + data directories to keep state apart:

# Mainnet
docker compose -p base-mainnet up --build -d

# Sepolia (in a sibling clone or with a different docker-compose port-remap)
NETWORK_ENV=.env.sepolia HOST_DATA_DIR=./reth-data-sepolia \
  docker compose -p base-sepolia -f docker-compose.sepolia.yml up --build -d

4.3 Build Times

Note

Use docker compose build (no --no-cache) to benefit from layer caching across rebuilds. Only fall back to --no-cache when you've changed versions.env or want to re-verify upstream.

4.4 Scaling

This stack is designed for one node per host. To run a fleet:

• One VM per node, all with the same .env.local template.
• Configure your DNS / load balancer to round-robin RPC across host ports 8545.
• For peer reachability, every node needs its own routable public IP and open 30303/9222 ports — they cannot share an IP without aggressive port-remapping.

Tip

A single-node cluster is the typical Base operator deployment. If you need a multi-node RPC pool, prefer running each instance on its own host and load-balancing the JSON-RPC layer rather than trying to share state across containers.

5. Operations

5.1 Graceful Shutdown

docker compose down

Compose sends SIGTERM and then SIGKILL after stop_grace_period (default 10 s). The entrypoints pass signals through because they use exec. However, supervisord.conf declares stopwaitsecs=300 — supervisord itself waits up to 5 min for child shutdown — but compose's 10 s grace period preempts it.

Important

For production, override the grace period in docker-compose.yml so the client can flush its database cleanly:

services:
  execution:
    stop_grace_period: 5m
  node:
    stop_grace_period: 5m

5.2 Data Backup

docker compose down
tar --use-compress-program='zstd -T0' -cf base-data.tar.zst ${HOST_DATA_DIR}
docker compose up -d

Warning

Back up only with the node stopped. Hot-backing-up an open MDBX (reth), LevelDB (geth), or Nethermind store yields an inconsistent and unusable snapshot.

5.3 Upgrade To A New Release

git -C /path/to/node pull
docker compose build --no-cache
docker compose up -d

The Dockerfile's git rev-parse HEAD == $<COMPONENT>_COMMIT assertion guarantees the new binaries match the upstream commit recorded in versions.env.

5.4 Switch Clients

docker compose down
mv ./geth-data /some/archive/path        # or rm -rf, if you don't want it
HOST_DATA_DIR=./reth-data CLIENT=reth docker compose up --build -d

You will need to re-sync from a snapshot (much faster than from genesis).

5.5 Log Rotation

Docker captures all stdout/stderr. Configure the daemon to rotate:

// /etc/docker/daemon.json
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m",
    "max-file": "10"
  }
}

Restart the Docker daemon.

5.6 Health Checks

The compose file does not declare healthchecks. For production, add:

services:
  execution:
    healthcheck:
      test: ["CMD", "curl", "-f", "-s", "-X", "POST",
             "-H", "Content-Type: application/json",
             "-d", '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":1}',
             "http://localhost:8545"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 300s

For nethermind, the binary exposes its own health endpoint (HealthChecks.Enabled=true is set by the nethermind entrypoint). Query at http://<host>:8545/health.

5.7 Startup Checklist

• [ ] L1 endpoints configured in .env.mainnet or .env.sepolia
• [ ] CLIENT chosen and HOST_DATA_DIR set accordingly
• [ ] USE_BASE_CONSENSUS consistent with CLIENT (true only with reth)
• [ ] Firewall allows 30303/tcp+udp and 9222/tcp+udp inbound
• [ ] Host has free disk for 2 × chain size + snapshot + 20 %
• [ ] Snapshot downloaded and extracted (recommended)
• [ ] Logs rotate via Docker daemon config
• [ ] Monitoring scrapes :7301/metrics and :7300/metrics
• [ ] Backup strategy defined for ${HOST_DATA_DIR}

5.8 Routine Operations

Tip

Most operational glitches resolve with docker compose restart of the affected service. Reach for docker compose down && up --build only when you suspect a corrupt image or a Dockerfile/env change wasn't picked up.

Note

The two containers share a single versions.env — both client and consensus images are rebuilt from the same pinned commit set. There is no scenario where they can diverge between compose build and compose up.

6. Performance

6.1 Geth Cache Configuration

Defaults assume a 64 GB+ host:

Scale GETH_CACHE proportionally to host RAM. The percentage-based sub-caches scale with it.

6.2 Geth Network Restriction

OP_GETH_NET_RESTRICT="10.0.0.0/8"

Restricts Geth's admin namespace to the declared CIDR. Production deployments often run nodes inside a VPC on 10.0.0.0/8. If your bastion or peer network is on a different CIDR, update this value.

6.3 Geth Sync And GC Modes

OP_GETH_SYNCMODE=full      # default, safest
OP_GETH_SYNCMODE=snap      # experimental, faster first sync
OP_GETH_GCMODE=full        # archive mode (default)
OP_GETH_GCMODE=archive     # full history retained

6.4 Reth maxperf Build Profile

The reth Dockerfile uses cargo build --profile maxperf, enabling LTO and aggressive optimization. Build time is significantly longer; runtime performance is significantly better than debug or default release.

6.5 Peer Limits

6.6 Disk I/O

• Use NVMe. SATA SSD cannot keep up with Base's block rate for long.
• RAID 0 across all local NVMe drives is what Coinbase uses (/dev/nvme*).
• ext4 is preferred over btrfs/zfs — copy-on-write filesystems impose unnecessary overhead on client databases.

6.7 Reth Pruning

RETH_PRUNING_ARGS (commented-out in shipped env, default value provided):

RETH_PRUNING_ARGS="--prune.senderrecovery.distance=50000 --prune.transactionlookup.distance=50000 --prune.receipts.distance=50000 --prune.accounthistory.distance=50000 --prune.storagehistory.distance=50000 --prune.bodies.distance=50000"

Caution

Pruning distance must exceed 10064. Published pruned snapshots use 1_339_200 (~31 days). A distance below 10064 can break consensus participation. Node type cannot be changed after initial sync — archive ↔ pruned conversions are unsupported by reth.

6.8 Reth Historical Proofs Preflight

When RETH_HISTORICAL_PROOFS=true and RETH_HISTORICAL_PROOFS_STORAGE_PATH is set, the reth entrypoint does a start-wait-stop-init dance before the main boot:

1. Launch base-reth-node node ... with minimal RPC config.
2. Poll eth_getBlockByNumber until the returned block number is non-zero. Timeout: 6 hours (MAX_WAIT=$((60 * 60 * 6))).
3. kill "$PID" and wait for the process to exit.
4. Run base-reth-node proofs init --proofs-history.storage-path=$PATH (idempotent).
5. Proceed to the main exec with --proofs-history arguments appended.

6.9 Build-Time mold Linker (Reth Only)

The reth Dockerfile installs mold v2.40.4 with SHA-256-verified downloads:

Other architectures abort the build with unsupported architecture: <uname -m>.

7. Security

7.1 Threat Model — Chain Operator's View

A Base node operator faces five categories of risk; each maps to a hardening checklist below.

1. RPC exposure — public JSON-RPC reveals chain data and accepts state-mutating calls; some methods (debug_*, admin_*) are abusable.
2. Engine API exposure — Engine API on port 8551 carries the JWT and drives the execution client. Exposing it externally is a direct compromise path because the shipped JWT is a public sample.
3. Peer authentication — Base uses libp2p with discv5; peer auth is cryptographic but the bootnode list is hardcoded.
4. Validator/sequencer slashing — base/node is not a sequencer or validator. There is no slashing risk from operating a follower node.
5. Supply chain — every build clones four upstream repos. A force-pushed tag, a tampered binary, or a compromised CI dependency could ship malicious code.

7.2 Authentication & Exposure

Caution

All published RPC and metrics ports bind 0.0.0.0. On a host with a public IP and no firewall, your RPC is open to the internet. Restrict with iptables/ufw/security-group, or rebind in docker-compose.yml to 127.0.0.1:<port>:<port>.

7.3 Rebinding To Localhost (Recommended Hardening)

services:
  execution:
    ports:
      - "127.0.0.1:8545:8545"
      - "127.0.0.1:8546:8546"
      - "127.0.0.1:7301:6060"
      - "30303:30303"
      - "30303:30303/udp"
  node:
    ports:
      - "127.0.0.1:7545:8545"
      - "127.0.0.1:7300:7300"
      - "127.0.0.1:6060:6060"
      - "9222:9222"
      - "9222:9222/udp"

This keeps RPC and metrics local while still allowing P2P inbound.

7.4 JWT Secret Handling

• Storage: written to /tmp/engine-auth-jwt inside each container at every boot (ephemeral; not on a host volume).
• Source: plaintext hex in BASE_NODE_L2_ENGINE_AUTH_RAW inside .env.mainnet / .env.sepolia.
• Risk: shipped values are public and identical across deployments. Acceptable only because port 8551 is unpublished.

Warning

Generate a per-deployment JWT before exposing port 8551 anywhere — even on an internal LAN:

openssl rand -hex 32 | tr -d '\n' > /tmp/my-jwt
# Set BASE_NODE_L2_ENGINE_AUTH_RAW in .env.* to the generated hex

7.5 pprof Disclosure Surface

Port 6060 (consensus pprof) exposes Go heap, goroutine, and CPU dumps without authentication — useful for diagnostics, dangerous in production. Rebind to 127.0.0.1:6060:6060 or remove the port mapping entirely.

7.6 Privilege Model

• Containers run as root (no USER directive in any Dockerfile).
• Filesystem is read-write everywhere except where Docker bind-mounts (/data).
• No Linux capabilities explicitly dropped.
• No read-only root filesystem.

Recommended hardening:

• Add USER to each Dockerfile's final stage; chown /data accordingly.
• Add read_only: true and a tmpfs for /tmp in compose.
• Use cap_drop: [ALL] and add only what's required (NET_BIND_SERVICE for ports < 1024, not currently needed since all listening ports are >= 6060).

7.7 Supply Chain

Caution

The just install step uses an unchecksummed pipe-to-bash. A compromise of just.systems would inject code into the build. Replace with a versioned download + SHA verification (mirror the mold pattern).

7.8 Bootnode ENRs

.env.mainnet and .env.sepolia embed Coinbase-operated Base bootnode ENRs in OP_NODE_P2P_BOOTNODES and BASE_NODE_P2P_BOOTNODES. If all bootnodes become unreachable, peer discovery breaks until the env files are updated. Not an attack surface — a single point of failure for discovery only.

7.9 Secrets In Version Control

• .env.mainnet and .env.sepolia are committed. They contain the sample JWT and bootnode ENRs.
• .env is committed. It has no secrets.
• L1 RPC URLs (often containing API keys) are not committed — operators fill them in locally.

Important

If you customize an env file with secrets, copy to .env.mainnet.local (or similar), .gitignore it, and reference it via NETWORK_ENV. Never commit your provider API keys.

7.10 Vulnerability Reporting

SECURITY.md: all vulnerabilities go to HackerOne against the Coinbase program (hackerone.com/coinbase). The program covers Base network, bridge contracts, and infrastructure. Do not file security issues on GitHub.

8. Developer Internals

8.1 Repository Layout

node/
|-- README.md                       # User-facing quick start
|-- CONTRIBUTING.md                 # Contribution guidelines
|-- SECURITY.md                     # HackerOne reporting
|-- LICENSE
|-- logo.webp
|-- docker-compose.yml              # Two-service orchestration
|-- .env                            # Host-side defaults (CLIENT, HOST_DATA_DIR)
|-- .env.mainnet                    # Mainnet env file
|-- .env.sepolia                    # Sepolia testnet env file
|-- .dockerignore                   # Excludes *-data directories
|-- .gitignore
|-- versions.env                    # Pinned upstream commits/tags (shell exports)
|-- versions.json                   # Same data in JSON (canonical; updater rewrites)
|-- supervisord.conf                # Supervisor program definitions
|-- consensus-entrypoint            # Dispatcher: base-consensus vs op-node
|-- base-consensus-entrypoint       # Base Rust consensus launcher
|-- op-node-entrypoint              # OP Stack Go consensus launcher
|-- go.mod                          # Root-level (empty module, vestigial)
|
|-- geth/
|   |-- Dockerfile                  # Multi-stage geth build
|   `-- geth-entrypoint             # Geth launch script
|
|-- nethermind/
|   |-- Dockerfile                  # Multi-stage nethermind build
|   `-- nethermind-entrypoint       # Nethermind launch script
|
|-- reth/
|   |-- Dockerfile                  # Multi-stage reth build with mold linker
|   |-- README.md                   # Reth-specific notes (Flashblocks)
|   `-- reth-entrypoint             # Reth launch script
|
`-- dependency_updater/             # Go CI utility (not runtime)
    |-- go.mod
    |-- go.sum
    |-- dependency_updater.go       # Main CLI, updater(), GitHub tag listing
    |-- version.go                  # Semver parsing, RC handling, upgrade validation
    `-- version_test.go             # Unit tests for version.go

8.2 The Compose Stack — Wiring

docker-compose.yml declares two services built from the same per-client Dockerfile. In short:

• Both services have build: { context: ., dockerfile: ${CLIENT:-geth}/Dockerfile }.
• Both services share env_file: [${NETWORK_ENV:-.env.mainnet}].
• Both services pass USE_BASE_CONSENSUS from the shell into the container via environment:.
• The execution service mounts ${HOST_DATA_DIR}:/data for chain state.
• The node service overrides command: ./consensus-entrypoint (vs. the Dockerfile's default).
• The node service depends on the execution service via depends_on: (so the Engine API poll doesn't run before the execution container starts).

8.3 Multi-Stage Build Pattern

Every client Dockerfile follows a consistent recipe:

1. op stage (golang:1.24): install just, copy versions.env, clone $OP_NODE_REPO at $OP_NODE_TAG, verify HEAD == $OP_NODE_COMMIT, build op-node.
2. Client builder stage: clone the client repo at its pinned tag and commit, verify, build the binary.
3. Final stage: copy op-node, the client binary, supervisord.conf, and entrypoint scripts. Set CMD ["/usr/bin/supervisord"].

COPY versions.env /tmp/versions.env

RUN . /tmp/versions.env && \
    git clone $<COMPONENT>_REPO --branch $<COMPONENT>_TAG --single-branch . && \
    git switch -c branch-$<COMPONENT>_TAG && \
    bash -c '[ "$(git rev-parse HEAD)" = "$<COMPONENT>_COMMIT" ]'

The final assertion protects against:

• Tag force-push by upstream maintainers.
• Tag re-pointing to a different commit.
• Man-in-the-middle on git clone (HTTPS + git's certificate validation).

8.4 Build Tool Per Client

Note

Only the nethermind Dockerfile uses just to build op-node. Geth and reth use make, despite both installing just in the op stage. This is a cosmetic inconsistency, not a bug — both Makefile and justfile exist upstream in ethereum-optimism/optimism.

8.5 supervisord And The Entrypoints

Every client image uses supervisord as PID 1:

[supervisord]
nodaemon=true
logfile=/dev/null
logfile_maxbytes=0

[program:base-consensus]
command=/app/consensus-entrypoint
stdout_logfile=/dev/fd/1
stdout_logfile_maxbytes=0
redirect_stderr=true
stopwaitsecs=300

[program:op-execution]
command=/app/execution-entrypoint
stdout_logfile=/dev/fd/1
stdout_logfile_maxbytes=0
redirect_stderr=true
stopwaitsecs=300

Note

Both programs are declared, but each container invokes only one: execution-entrypoint for the execution container, consensus-entrypoint for the node container. The dual declaration is a remnant of an earlier single-container model — visually confusing, but harmless.

stopwaitsecs=300 gives each child up to 5 minutes to flush; compose's stop_grace_period overrides this externally (default 10 s — hence the recommendation in §5.1 to override it to 5m).

8.6 op-node-entrypoint Flow

1. Validate $OP_NODE_NETWORK or $OP_NODE_ROLLUP_CONFIG.
2. Poll ${OP_NODE_L2_ENGINE_RPC} until it returns HTTP 401 (execution ready).
3. get_public_ip() — try four IP providers in sequence; fail with exit code 8 if all fail.
4. export OP_NODE_P2P_ADVERTISE_IP=$PUBLIC_IP.
5. Write $BASE_NODE_L2_ENGINE_AUTH_RAW to $BASE_NODE_L2_ENGINE_AUTH (default /tmp/engine-auth-jwt).
6. export OP_NODE_L2_ENGINE_AUTH=$BASE_NODE_L2_ENGINE_AUTH.
7. exec ./op-node.

8.7 base-consensus-entrypoint Flow

1. Validate $BASE_NODE_NETWORK.
2. Same engine-readiness poll.
3. Same public-IP detection → BASE_NODE_P2P_ADVERTISE_IP.
4. Write JWT.
5. Conditional dispatch:
   • $BASE_NODE_SOURCE_L2_RPC set → exec ./base-consensus follow (follow-mode).
   • Otherwise → exec ./base-consensus node.

8.8 Execution Entrypoints

Geth

exec ./geth \
    --datadir="$GETH_DATA_DIR" \
    --verbosity="$VERBOSITY" \
    --http --http.addr=0.0.0.0 --http.port="$RPC_PORT" \
    --http.api=web3,debug,eth,net,engine \
    --authrpc.addr=0.0.0.0 --authrpc.port="$AUTHRPC_PORT" \
    --authrpc.jwtsecret="$BASE_NODE_L2_ENGINE_AUTH" \
    --ws --ws.addr=0.0.0.0 --ws.port="$WS_PORT" \
    --ws.api=debug,eth,net,engine \
    --metrics --metrics.addr=0.0.0.0 --metrics.port="$METRICS_PORT" \
    --syncmode="$OP_GETH_SYNCMODE" --gcmode="$OP_GETH_GCMODE" \
    --maxpeers=100 \
    --rollup.sequencerhttp="$OP_GETH_SEQUENCER_HTTP" \
    --rollup.halt=major --op-network="$OP_NODE_NETWORK" \
    --discovery.port="$DISCOVERY_PORT" --port="$P2P_PORT" \
    --rollup.disabletxpoolgossip=true \
    --cache="$GETH_CACHE" \
    --cache.database="$GETH_CACHE_DATABASE" \
    --cache.gc="$GETH_CACHE_GC" \
    --cache.snapshot="$GETH_CACHE_SNAPSHOT" \
    --cache.trie="$GETH_CACHE_TRIE" \
    $ADDITIONAL_ARGS

$ADDITIONAL_ARGS is intentionally unquoted so shell word-splitting applies — this is how optional flags (--ethstats, --bootnodes, --state.scheme, --rpc.allow-unprotected-txs, --nat=extip:) get appended.

Reth

exec ./base-reth-node node \
  -$LOG_LEVEL \
  --datadir="$RETH_DATA_DIR" \
  --log.stdout.format json \
  --ws --ws.origins="*" --ws.addr=0.0.0.0 --ws.port="$WS_PORT" \
  --ws.api=web3,debug,eth,net,txpool \
  --http --http.corsdomain="*" --http.addr=0.0.0.0 --http.port="$RPC_PORT" \
  --http.api=web3,debug,eth,net,txpool,miner \
  --ipcpath="$IPC_PATH" \
  --authrpc.addr=0.0.0.0 --authrpc.port="$AUTHRPC_PORT" \
  --authrpc.jwtsecret="$BASE_NODE_L2_ENGINE_AUTH" \
  --metrics=0.0.0.0:"$METRICS_PORT" \
  --max-outbound-peers=100 \
  --chain "$RETH_CHAIN" \
  --rollup.sequencer-http="$RETH_SEQUENCER_HTTP" \
  --rollup.disable-tx-pool-gossip \
  --discovery.port="$DISCOVERY_PORT" --port="$P2P_PORT" \
  $ADDITIONAL_ARGS

Reth-specific extensions:

• IPC path: $IPC_PATH (default /data/reth.ipc).
• Flashblocks: --websocket-url=$RETH_FB_WEBSOCKET_URL (when set).
• Historical proofs: --proofs-history --proofs-history.storage-path=$RETH_HISTORICAL_PROOFS_STORAGE_PATH (when enabled).
• Log level mapping: error/warn/info/debug/trace → -v/-vv/-vvv/-vvvv/-vvvvv.

Nethermind

exec ./nethermind \
    --config="$OP_NODE_NETWORK" \
    --datadir="$NETHERMIND_DATA_DIR" \
    --Optimism.SequencerUrl=$OP_SEQUENCER_HTTP \
    --log="$NETHERMIND_LOG_LEVEL" \
    --JsonRpc.Enabled=true --JsonRpc.Host=0.0.0.0 \
    --JsonRpc.WebSocketsPort="$WS_PORT" --JsonRpc.Port="$RPC_PORT" \
    --JsonRpc.JwtSecretFile="$BASE_NODE_L2_ENGINE_AUTH" \
    --JsonRpc.EngineHost=0.0.0.0 --JsonRpc.EnginePort="$AUTHRPC_PORT" \
    --HealthChecks.Enabled=true \
    --Metrics.Enabled=true --Metrics.ExposePort="$METRICS_PORT" \
    --Network.P2PPort="$P2P_PORT" --Network.DiscoveryPort="$DISCOVERY_PORT" \
    $ADDITIONAL_ARGS

8.9 The dependency_updater Go CLI

The dependency_updater/ Go package is a CI-only utility that bumps the pinned upstream versions automatically. It does not run at node startup.

8.9.1 Purpose

• Query GitHub for the latest valid tag on each upstream repo (op-node, op-geth, nethermind, base-reth-node).
• Filter candidate tags by a tracking mode (release, tag, or branch).
• Pick the highest semver among valid candidates.
• Rewrite versions.json.
• Regenerate versions.env (JSON → shell exports).
• Optionally create a git commit and write TITLE/DESC to $GITHUB_OUTPUT.

8.9.2 CLI Surface (urfave/cli/v3)

updater --token <GITHUB_TOKEN> --repo <path> [--commit] [--github-action]

Implementation: dependency_updater/dependency_updater.go:42-79 — urfave/cli/v3 command construction. The Action calls updater(token, repo, commit, githubAction) and wraps any error as failed to run updater: %s.

8.9.3 Tracking Modes (declared per-dependency in versions.json)

8.9.4 Version Semantics (version.go)

The updater parses tags into semver via Masterminds/semver/v3, with three preprocessing steps:

1. Tag prefix stripping — e.g. op-node/v1.16.2 → v1.16.2 when tagPrefix=op-node.
2. RC format normalization — -rc1, -rc-1, -RC1 → -rc.1 (regex (?i)-rc[.-]?(\d+) in rcPattern).
3. Parse with semver.

Predicate functions (all in version.go):

ValidateVersionUpgrade(currentTag, newTag, tagPrefix) rejects downgrades:

• If currentTag is empty (first-time setup), any parseable newTag is valid.
• If currentTag is unparseable, validation ignores the current version and only checks that newTag is parseable.
• Stable (v0.3.0) → RC (v0.3.0-rc2) is a downgrade (semver-correct: RCs sort before releases).

8.9.5 Upgrade Algorithm Per Dependency

ListTags(owner, repo, page=1..N):
  for each tag:
    strip tagPrefix if set
    filter by tracking mode (release | tag)
    try ValidateVersionUpgrade(current, tag) -> skip on error
    accumulate valid candidates
  pick max via CompareVersions()
  if max != current:
    fetch commit SHA
    diffUrl = github.com/owner/repo/compare/<current>...<selected>
    rewrite versions.json

For tracking="branch": no tag filtering; call ListCommits(SHA=branch) and take the first result.

8.9.6 Commit Construction

createCommitMessage(updatedDependencies, repoPath, githubAction) produces:

### Dependency Updates
**<repo>** - <newTag>:  [diff](<diffUrl>)
**<repo>** - <newTag>:  [diff](<diffUrl>)
...

Title: chore: updated <repo>, <repo>, ....

If --github-action is set: writes to $GITHUB_OUTPUT with this schema:

TITLE=<title>
DESC<<EOF
<description>
EOF

If --commit is set: runs git commit -am <title> -m <description>.

8.9.7 createVersionsEnv — JSON → Shell Regeneration

for dependency in dependencies:
    dependencyPrefix = strings.ToUpper(dependency)   // "op_node" -> "OP_NODE"
    if tracking == "branch": tag = branch            // branch name acts as "tag"
    emit: export <PREFIX>_TAG=<tag>
          export <PREFIX>_COMMIT=<commit>
          export <PREFIX>_REPO=https://github.com/<owner>/<repo>.git
sort lines
write to versions.env

Note

Keys in versions.json use snake_case (op_node, base_reth_node). After ToUpper, they become OP_NODE, BASE_RETH_NODE — exactly the prefixes the Dockerfiles expect.

8.9.8 Retry Logic

retry.Do0(ctx, 3, retry.Fixed(1*time.Second), func() error { ... })

Each dependency update is wrapped in 3 attempts with 1-second fixed delay, using ethereum-optimism/optimism/op-service/retry.

8.9.9 Running Locally

cd dependency_updater
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
go build -o updater .
./updater --repo /path/to/node --commit

Without --commit / --github-action, the tool writes updated versions.json + versions.env but doesn't create a commit.

8.9.10 Manual Version Bump

If you need to pin to a version the updater wouldn't pick (e.g. an -rc tag with tracking=release):

1. Edit versions.json directly.
2. Run ./updater --repo . (no --commit) to regenerate versions.env.
3. Commit both files.
4. docker compose build --no-cache to rebuild.

8.10 Where State Lives

The bind mount is the only persistent state. Loss of ${HOST_DATA_DIR} triggers a fresh sync.

8.11 Upgrade Story

The contract between the platform and operators:

1. CI runs dependency_updater against each upstream repo (release tracking by default).
2. The updater opens a PR that bumps versions.json + versions.env.
3. Operators git pull and docker compose build --no-cache.
4. Each Dockerfile re-clones the upstream repos at the new pinned commits and rebuilds the binaries.
5. The commit-hash assertion ensures the new binaries are byte-for-byte what the updater pinned.

There is no in-place upgrade — the model is "rebuild from source at the pinned commit". This trades cold-start time for trust.

8.12 Testing Strategy

8.12.1 Unit Tests

Only the dependency_updater package has tests. Location: dependency_updater/version_test.go.

cd dependency_updater
go test -v ./...

8.12.2 No Integration Tests

The repository ships no integration tests for the Docker stack. Verification is implicit:

• Build-time commit hash verification.
• Entrypoint engine-readiness polling at runtime.
• Manual checks of peer count, sync status, and RPC responses.

8.13 Known Issues & Behaviors

8.14 Potential Improvements

Source-derived improvement candidates:

1. Allow OP_NODE_P2P_ADVERTISE_IP override. get_public_ip() is currently authoritative; add if [[ -n "$OP_NODE_P2P_ADVERTISE_IP_OVERRIDE" ]]; then ... for CGNAT or air-gapped operators.
2. Run containers as non-root. Add a USER directive in each Dockerfile's final stage.
3. Rebind pprof to localhost. Drop 6060:6060 from compose or comment it out by default.
4. Drop deprecated docker-compose references in repo docs.
5. Ship base-consensus in every client image (or remove the dispatcher branch from geth/nethermind). Current state is an avoidable runtime failure mode.
6. Add versions.json schema validation in CI (reject malformed entries — missing commit, bad tracking).
7. Tests for dependency_updater.go. Only version.go is tested; the main updater flow (getAndUpdateDependency, createCommitMessage, createVersionsEnv) is untested.
8. Checksum the just installer. Replace curl … | bash with a versioned download + SHA check (mirror the mold pattern).
9. Healthchecks in docker-compose.yml. Declare per-service healthchecks; compose will auto-restart unhealthy containers.
10. Remove vestigial root go.mod. It declares module dependency_updater with no purpose.
11. Sensible default for HOST_IP in geth-entrypoint. Currently HOST_IP="" placeholder with a comment; promote to a real env override.
12. Remove unused op-execution program from supervisord.conf (or split into two configs to match the current two-container layout).

8.15 Contributing

See CONTRIBUTING.md. Highlights:

• Open an issue first for non-trivial changes.
• Every PR touching dependency_updater/ should add tests.
• Follow the Coinbase code of conduct.
• Security issues → HackerOne, never GitHub issues.
• Support requests → Coinbase support, not GitHub issues.

Local development loop:

git switch -c my-fix
CLIENT=reth docker compose build --no-cache execution node
NETWORK_ENV=.env.sepolia CLIENT=reth docker compose up

dependency_updater development loop:

cd dependency_updater
go test -v ./...
go build .
./dependency_updater --token $GITHUB_TOKEN --repo /path/to/another-node-checkout

9. Integration Points

9.1 Upstream Source Repositories

9.2 Network Endpoints The Stack Calls

9.3 GitHub API (Used by dependency_updater Only)

github.com/google/go-github/v72:

• client.Repositories.ListTags(ctx, owner, repo, options) — paginated tag listing.
• client.Repositories.ListCommits(ctx, owner, repo, &CommitsListOptions{SHA: branch}) — for tracking="branch".

Authentication via GITHUB_TOKEN env var (or --token flag).

9.4 GitHub Actions Output Contract

When the updater runs with --github-action, it writes to $GITHUB_OUTPUT:

TITLE=chore: updated <repo>, <repo>, ...
DESC<<EOF
### Dependency Updates
**<repo>** - <newTag>:  [diff](<diffUrl>)
...
EOF

Downstream workflow steps consume ${{ steps.<id>.outputs.TITLE }} and ${{ steps.<id>.outputs.DESC }} to open a PR.

9.5 Prometheus Scrape Targets

9.6 Engine API (Internal)

Container-to-container only. The execution client exposes --authrpc on 8551 (HTTP and/or WS depending on network); the consensus client polls until HTTP 401 then connects with the JWT.

9.7 StatsD (base-consensus only)

STATSD_ADDRESS="172.17.0.1" assumes a StatsD receiver on the Docker host's bridge IP. Best-effort — base-consensus does not require StatsD.

9.8 Public Ports → Purpose Quick Reference

9.9 Useful Links

• Base docs: docs.base.org
• Run-a-node docs: docs.base.org/chain/run-a-base-node
• Chain stats: base.org/stats
• Snapshots: basechaindata.vercel.app
• Flashblocks docs: docs.base.org/chain/flashblocks
• OP Stack docs: docs.optimism.io
• Reth docs: reth.rs
• Bug bounty: hackerone.com/coinbase
• Discord: discord.gg/buildonbase
• Source: github.com/base/node