Claude Agent
535f51bda2
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>
98 lines
4.4 KiB
Markdown
98 lines
4.4 KiB
Markdown
# 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.
|