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`)
```dockerfile
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)
```sh
#!/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
```yaml
# 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
```
```yaml
# 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.