cometbft: add reusable family-C bootstrap library + docs

Generalizes the berachain beacon-kit init pattern into cometbft-common.sh (sourced helper lib) so morph-node, gaiad/cosmos batch, shibarium and the EVM-cosmos chains (haqq/sei/zero-gravity) become thin init.sh overrides. Validated against the real init flows of beacon-kit, haqq, sei, zero-gravity. README.cometbft.md documents the pattern (per-chain Dockerfile + thin init.sh + context). berachain stays on its own beacon-kit.yml (untouched). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-15 11:26:06 +00:00
parent fa3f96382c
commit 535f51bda2
2 changed files with 284 additions and 0 deletions
--- a/scripts/README.cometbft.md
+++ b/scripts/README.cometbft.md
@@ -0,0 +1,97 @@
+# 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.
--- a/scripts/cometbft-common.sh
+++ b/scripts/cometbft-common.sh
@@ -0,0 +1,187 @@
+#!/bin/sh
+# cometbft-common.sh — reusable CometBFT-node bootstrap helpers (family C).
+#
+# Source this from a chain-specific init.sh. It encapsulates the operations every
+# CometBFT-consensus node needs (init, fetch config artifacts, patch config.toml /
+# app.toml, seed priv_validator_state), extracted verbatim from the proven berachain
+# beacon-kit entrypoint so callers inherit known-good behavior.
+#
+# Each function takes explicit arguments (paths/values) — it is binary-agnostic. The
+# caller owns the binary name, the `<binary> init` invocation, the artifact URLs, and
+# the final `exec <binary> start ...`. EL-driven chains (beacon-kit, morph) also call
+# the JWT / engine-dial helpers; pure-consensus chains (gaiad) skip them.
+#
+# Conventions: POSIX sh (alpine). Config dir is conventionally $HOME_DIR/config.
+# Used by: morph-node, gaiad (cosmos batch), and any future family-C chain.
+# beacon-kit (berachain) keeps its own bespoke init.sh on purpose — do not retrofit it.
+
+set -e
+
+ct_log() { echo "[cometbft-init] $*"; }
+
+# Ensure curl exists (alpine base images often omit it). Idempotent.
+ct_require_curl() {
+  if ! command -v curl >/dev/null 2>&1; then
+    ct_log "installing curl"
+    apk add --no-cache curl
+  fi
+}
+
+# ct_fetch URL DEST [required]
+#   Download URL -> DEST. If the 3rd arg is "required", a failure is fatal;
+#   otherwise a missing/failed fetch is logged and skipped (returns 0).
+ct_fetch() {
+  _url="$1"; _dest="$2"; _req="${3:-optional}"
+  [ -n "$_url" ] || { [ "$_req" = required ] && { ct_log "FATAL: empty URL for $_dest"; exit 1; }; return 0; }
+  if curl -fsSL "$_url" -o "$_dest"; then
+    ct_log "fetched $_url -> $_dest"
+  else
+    if [ "$_req" = required ]; then
+      ct_log "FATAL: failed to fetch required $_url"; exit 1
+    fi
+    ct_log "skip: could not fetch optional $_url"
+  fi
+}
+
+# ct_patch_p2p CONFIG_TOML IP P2P_PORT
+#   Bind p2p to 0.0.0.0:PORT and advertise IP:PORT (only within the [p2p] section).
+ct_patch_p2p() {
+  _cfg="$1"; _ip="$2"; _port="$3"
+  [ -f "$_cfg" ] || { ct_log "patch_p2p: $_cfg missing, skipping"; return 0; }
+  _laddr="tcp:\\/\\/0\\.0\\.0\\.0\\:${_port}"
+  sed -i "/^\[p2p\]/,/^\[/{s|^laddr = .*|laddr = \"$_laddr\"|}" "$_cfg"
+  sed -i "/^\[p2p\]/,/^\[/{s|^external_address = .*|external_address = \"${_ip}:${_port}\"|}" "$_cfg"
+}
+
+# ct_merge_seeds CONFIG_TOML CONFIGURED_SEEDS [SEEDS_URL]
+#   Merge operator-configured seeds with an optional official seed list (1 entry per
+#   line, first line skipped like the berachain cl-seeds.txt header), dedupe, write.
+ct_merge_seeds() {
+  _cfg="$1"; _seeds="$2"; _url="$3"
+  [ -f "$_cfg" ] || return 0
+  if [ -n "$_url" ]; then
+    _official=$(curl -f -s "$_url" | tail -n +2 | tr '\n' ',' | sed 's/,$//' || true)
+    if [ -n "$_official" ]; then
+      ct_log "merging official seeds from $_url"
+      _seeds=$(echo "${_seeds},${_official}" | tr ',' '\n' | sed '/^$/d' | sort -u | paste -sd,)
+    else
+      ct_log "no official seeds fetched from $_url (continuing with configured)"
+    fi
+  fi
+  if [ -n "$_seeds" ]; then
+    sed -i "s/^seeds = \".*\"/seeds = \"${_seeds}\"/" "$_cfg"
+  fi
+}
+
+# ct_set_persistent_peers CONFIG_TOML PEERS
+#   Handles both cometbft-classic `persistent_peers` (underscore) and forks that use
+#   `persistent-peers` (hyphen, e.g. sei) — patches whichever key is present.
+ct_set_persistent_peers() {
+  _cfg="$1"; _peers="$2"
+  [ -f "$_cfg" ] || return 0
+  [ -n "$_peers" ] || return 0
+  sed -i "s/^persistent_peers = \".*\"/persistent_peers = \"${_peers}\"/" "$_cfg"
+  sed -i "s/^persistent-peers = \".*\"/persistent-peers = \"${_peers}\"/" "$_cfg"
+  return 0
+}
+
+# ct_set_moniker CONFIG_TOML MONIKER
+ct_set_moniker() {
+  _cfg="$1"; _mon="$2"
+  [ -f "$_cfg" ] || return 0
+  [ -n "$_mon" ] && sed -i "s/^moniker = \".*\"/moniker = \"$_mon\"/" "$_cfg"
+  return 0
+}
+
+# ct_set_addrbook CONFIG_DIR ADDRBOOK_URL
+#   Optional: cosmos chains often seed an addrbook.json for faster peer discovery.
+ct_set_addrbook() {
+  _dir="$1"; _url="$2"
+  [ -n "$_url" ] || return 0
+  ct_fetch "$_url" "$_dir/addrbook.json" optional
+}
+
+# ct_write_jwt CONFIG_DIR  [JWT_SRC]
+#   EL-driven chains: copy the shared engine JWT (default /jwtsecret) into the config
+#   dir as jwt.hex so the CL can authenticate to the EL engine API.
+ct_write_jwt() {
+  _dir="$1"; _src="${2:-/jwtsecret}"
+  [ -f "$_src" ] || { ct_log "write_jwt: $_src missing, skipping"; return 0; }
+  cat "$_src" > "$_dir/jwt.hex"
+}
+
+# ct_set_rpc_dial_url APP_TOML AUTH_RPC
+#   beacon-kit / app.toml-style EL engine endpoint (e.g. http://<el>:8551).
+ct_set_rpc_dial_url() {
+  _app="$1"; _rpc="$2"
+  [ -f "$_app" ] || return 0
+  [ -n "$_rpc" ] && sed -i "s|^rpc-dial-url = \".*\"|rpc-dial-url = \"$_rpc\"|" "$_app"
+  return 0
+}
+
+# ct_seed_priv_validator_state HOME_DIR
+#   Ensure data/priv_validator_state.json exists (cometbft refuses to start without it
+#   when one is present in config/). Mirrors the berachain init.sh behavior.
+ct_seed_priv_validator_state() {
+  _home="$1"
+  if [ -e "$_home/config/priv_validator_state.json" ] && [ ! -e "$_home/data/priv_validator_state.json" ]; then
+    mkdir -p "$_home/data"
+    cp "$_home/config/priv_validator_state.json" "$_home/data/priv_validator_state.json"
+  fi
+  return 0
+}
+
+# ct_apk PKG...
+#   Install alpine packages idempotently (most cosmos init scripts need curl, some jq).
+ct_apk() {
+  apk add --no-cache "$@"
+}
+
+# ct_localize_home CONFIG_DIR
+#   Rewrite `~/` to `/root/` in config.toml + app.toml. Cosmos `init` writes home-relative
+#   paths; the container runs as root with a static home, so make paths absolute.
+ct_localize_home() {
+  _dir="$1"
+  [ -f "$_dir/config.toml" ] && sed -i 's|~/|/root/|g' "$_dir/config.toml"
+  [ -f "$_dir/app.toml" ]    && sed -i 's|~/|/root/|g' "$_dir/app.toml"
+  return 0
+}
+
+# ct_set_min_gas_prices APP_TOML PRICE
+#   Cosmos chains reject txs (and sometimes refuse to start) with an empty
+#   minimum-gas-prices. PRICE e.g. "0.01usei", "0.0025uatom", "0.01hqq".
+ct_set_min_gas_prices() {
+  _app="$1"; _price="$2"
+  [ -f "$_app" ] || return 0
+  [ -n "$_price" ] || return 0
+  sed -i "s/minimum-gas-prices = \"\"/minimum-gas-prices = \"${_price}\"/g" "$_app"
+  return 0
+}
+
+# ct_configure_statesync CONFIG_TOML RPC_SERVERS [TRUST_OFFSET]
+#   Enable cometbft state-sync so a fresh node bootstraps near chainhead instead of
+#   replaying from genesis — the single biggest lever for "can't keep it at chainhead"
+#   chains. RPC_SERVERS = comma list of trusted RPC endpoints (>=2 recommended; a single
+#   endpoint is duplicated). TRUST_OFFSET = blocks below head to trust (default 2000).
+#   Requires jq + curl. No-op (logged) if head height can't be fetched.
+ct_configure_statesync() {
+  _cfg="$1"; _rpc="$2"; _offset="${3:-2000}"
+  [ -f "$_cfg" ] || return 0
+  [ -n "$_rpc" ] || { ct_log "statesync: no RPC servers given, skipping"; return 0; }
+  _primary=$(echo "$_rpc" | cut -d, -f1)
+  _latest=$(curl -s "$_primary/block" | jq -r .block.header.height 2>/dev/null || true)
+  if [ -z "$_latest" ] || [ "$_latest" = null ]; then
+    ct_log "statesync: could not read head height from $_primary, skipping"; return 0
+  fi
+  _trust_h=$((_latest - _offset))
+  _trust_hash=$(curl -s "$_primary/block?height=$_trust_h" | jq -r .block_id.hash 2>/dev/null || true)
+  [ -n "$_trust_hash" ] && [ "$_trust_hash" != null ] || { ct_log "statesync: no trust hash, skipping"; return 0; }
+  # second server defaults to the first (cometbft wants >=2 for light-client cross-check)
+  echo "$_rpc" | grep -q ',' || _rpc="$_rpc,$_rpc"
+  ct_log "statesync: enable trust_height=$_trust_h trust_hash=$_trust_hash"
+  sed -i.bak -E "s|^(enable[[:space:]]*=[[:space:]]*).*$|\1true| ; \
+    s|^(rpc-servers[[:space:]]*=[[:space:]]*).*$|\1\"$_rpc\"| ; \
+    s|^(trust-height[[:space:]]*=[[:space:]]*).*$|\1$_trust_h| ; \
+    s|^(trust-hash[[:space:]]*=[[:space:]]*).*$|\1\"$_trust_hash\"|" "$_cfg"
+  return 0
+}