ethereum-rpc-docker/scripts/README.cometbft.md

Family-C CometBFT node base

Reusable scaffolding for chains whose node is CometBFT/Tendermint consensus, optionally driving a separate Engine-API execution layer (geth/reth fork). Generalized from the berachain beacon-kit pattern. Validated against the real init flows of beacon-kit, haqq, sei and zero-gravity.

Sub-shapes (all "family C")

• C1 — CL drives a separate EL (engine API + JWT): beacon-kit, morph, zero-gravity (0gchaind). Set cometbft_el: true in context → template emits AUTH_RPC=http://<el>:8551; init.sh calls ct_write_jwt + (beacon-kit-style) ct_set_rpc_dial_url.
• C2 — cosmos app with built-in EVM JSON-RPC (no separate EL): haqq, sei. Serve :8545 from the app itself; tune app.toml json-rpc + pruning in init.sh.
• C3 — pure cosmos (CometBFT RPC :26657 only): gaiad / cosmos-hub and the cosmos batch.

The pieces

1. rpc/scripts/cometbft-common.sh (master, this dir) — sourced helper library. update.sh syncs a copy next to every chain init.sh that sources it, so each per-chain Docker build context has it. Helpers: ct_require_curl/ct_apk, ct_fetch, ct_localize_home, ct_patch_p2p, ct_merge_seeds, ct_set_persistent_peers (handles _/- forms), ct_set_moniker, ct_set_addrbook, ct_set_min_gas_prices, ct_configure_statesync, ct_write_jwt, ct_set_rpc_dial_url, ct_seed_priv_validator_state.
2. templates/nodes/cometbft-node.yml — base compose template ({% extends "rpc-node.yml" %}). Knobs: cometbft_home (default /root/.beacond), cometbft_dockerfile (default cometbft.Dockerfile), cometbft_el (truthy ⇒ emit AUTH_RPC).
3. Per chain: a thin rpc/<base>/scripts/init.sh + a ~7-line rpc/<base>/cometbft.Dockerfile.

Per-chain Dockerfile (build context = the chain dir, e.g. ./cosmos)

ARG CL_IMAGE
ARG CL_VERSION
FROM ${CL_IMAGE}:${CL_VERSION}
COPY ./scripts/cometbft-common.sh /usr/local/bin/cometbft-common.sh
COPY ./scripts/init.sh            /usr/local/bin/init.sh
RUN chmod +x /usr/local/bin/init.sh
ENTRYPOINT ["init.sh"]

Example thin init.sh — cosmos-hub / gaiad (C3, no EL)

#!/bin/sh
set -e
. /usr/local/bin/cometbft-common.sh

HOME_DIR="/root/.gaia"; CONFIG_DIR="$HOME_DIR/config"
CHAIN_ID="${CHAIN_ID:-cosmoshub-4}"
GENESIS_URL="${GENESIS_URL:-https://github.com/cosmos/mainnet/raw/master/genesis/genesis.cosmoshub-4.json.gz}"

ct_apk curl jq
if gaiad init "$MONIKER" --chain-id "$CHAIN_ID" --home "$HOME_DIR"; then
  ct_fetch "$GENESIS_URL" "$CONFIG_DIR/genesis.json" required   # (gunzip if needed)
  ct_localize_home "$CONFIG_DIR"
  ct_set_min_gas_prices "$CONFIG_DIR/app.toml" "0.0025uatom"
fi
ct_patch_p2p              "$CONFIG_DIR/config.toml" "$IP" "${P2P_PORT:-26656}"
ct_merge_seeds           "$CONFIG_DIR/config.toml" "$SEEDS" "$SEEDS_URL"
ct_set_persistent_peers  "$CONFIG_DIR/config.toml" "$PERSISTENT_PEERS"
ct_set_addrbook          "$CONFIG_DIR" "$ADDRBOOK_URL"
ct_set_moniker           "$CONFIG_DIR/config.toml" "$MONIKER"
ct_configure_statesync   "$CONFIG_DIR/config.toml" "$STATESYNC_RPC"   # optional: bootstrap near head
ct_seed_priv_validator_state "$HOME_DIR"
exec gaiad start --home "$HOME_DIR" "$@"

EL-driven chains (C1) additionally: ct_write_jwt "$CONFIG_DIR" and, beacon-kit-style, ct_set_rpc_dial_url "$CONFIG_DIR/app.toml" "$AUTH_RPC" — then exec <binary> start ... with the engine flags.

context.yml + config.yml

# context.yml
cosmos:
  nodes:
    gaiad:
      node_build: true
      node_image: ghcr.io/cosmos/gaia
      node_version: v25.0.0
      node_datadir: /root/.gaia/data
  chains:
    mainnet:
      chainid: cosmoshub-4
      cometbft_home: /root/.gaia
      # cometbft_el: true   # only for C1 (EL-driven) chains

# config.yml
cosmos:
  - node: gaiad
    chains: [mainnet]

Reliability notes (these are historically flaky chains)

• statesync is the main lever for "can't keep it at chainhead" — wire STATESYNC_RPC and call ct_configure_statesync so a fresh/reset node bootstraps near head instead of replaying genesis.
• init is guarded (if <binary> init ...; then <fetch>; else "already initialized") so restarts are idempotent and don't clobber a synced datadir.
• Migrating an existing problem chain (haqq/sei/zero-gravity/berachain) onto this base is a deliberate, separate step — diff the rendered compose + re-test live before trusting it.

CosmWasm / version gotchas (learned on cosmos-hub, 2026-06-16)

• Match the binary version to the live chain. Cosmos chains hard-fork via governance; an old binary panics upgrade handler is missing for vX.Y.Z (or halts at the upgrade height). Check the live version: curl <rpc>/abci_info | jq .result.response.version. NOTE ghcr tags/list can LAG / omit the newest tag — verify pullability with a direct manifest HEAD, not the tag list.
• state-sync does NOT restore CosmWasm + IBC 08-wasm files. A wasm chain then panics at startup (wasmlckeeper failed initialize pinned codes / Error opening Wasm file). Two fixes, both wired into the lib: ct_configure_statesync skips if data/application.db already exists (idempotent restart), and ct_ensure_wasm <home> <url> seeds a wasm-only snapshot (polkachu *_wasmonly.tar.lz4) when the wasm dir is empty. Set wasm_snapshot_url in context for any CosmWasm chain.
• Fresh bootstrap of a wasm chain: prefer the FULL polkachu snapshot over state-sync — https://snapshots.polkachu.com/snapshots/<chain>/<chain>_<HEIGHT>.tar.lz4 includes everything (state + wasm/ + data/08-light-client/). state-sync + ct_ensure_wasm is the lighter path but the wasm extract paths/timing are best-effort.
• Traefik WS rule must be case-insensitive: use HeadersRegexp('Upgrade','(?i)websocket'), NOT Headers('Upgrade','websocket') — the latter is case-sensitive and clients sending Upgrade: WebSocket (e.g. python websocket-client) fall through to the RPC router (200/400 instead of a 101 upgrade). Driven by client_ws_path; the shared rpc-client.yml emits the regexp form for all split-WS chains.