From 42b25224ca3e453874b9ee8760d82154a6efabaa Mon Sep 17 00:00:00 2001 From: Claude Agent Date: Tue, 7 Jul 2026 13:13:06 +0000 Subject: [PATCH] cosmos: document Polkachu FULL snapshot bootstrap for gaiad --- cosmos/scripts/README.cometbft.md | 39 +++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 cosmos/scripts/README.cometbft.md diff --git a/cosmos/scripts/README.cometbft.md b/cosmos/scripts/README.cometbft.md new file mode 100644 index 00000000..8887cd0e --- /dev/null +++ b/cosmos/scripts/README.cometbft.md @@ -0,0 +1,39 @@ +# Cosmos Hub (gaiad) — CometBFT bootstrap notes + +Operator guidance for fresh provisioning of the cosmos-hub gaiad node. See also the shared +family-C reference at `rpc/scripts/README.cometbft.md`. + +## Fresh bootstrap: use a Polkachu FULL snapshot + +For a wasm chain like cosmos-hub, prefer seeding from a **Polkachu FULL snapshot** over +state-sync. The full archive includes everything on disk — application state, `wasm/`, and +`data/08-light-client/` (IBC 08-wasm bytecode) — so gaia does not panic with +`wasmlckeeper failed initialize pinned codes / Error opening Wasm file` on first start. + +Snapshot URL pattern: + +``` +https://snapshots.polkachu.com/snapshots/cosmos/cosmos_.tar.lz4 +``` + +Replace `` with the height published on the Polkachu cosmos snapshot page. Extract +into the node data volume (`/root/.gaia`) before `docker compose up`. + +## CL_VERSION must match the live chain + +Cosmos chains upgrade via governance; an old binary halts at the upgrade height or panics +`upgrade handler is missing for vX.Y.Z`. Before pinning `CL_VERSION` / `COSMOS_MAINNET_GAIAD_VERSION`, +check the live app version on Polkachu RPC: + +```sh +curl -s https://cosmos-rpc.polkachu.com/abci_info | jq .result.response.version +``` + +The Docker image tag must match that version (verify pullability with a manifest HEAD, not +only the ghcr tags list — it can lag). + +## Traefik WebSocket routing + +The split-WS router uses `HeadersRegexp('Upgrade','(?i)websocket')` (case-insensitive). Clients +sending `Upgrade: WebSocket` (e.g. python websocket-client) require this — a case-sensitive +`Headers('Upgrade','websocket')` matcher falls through to the RPC router (400/200 instead of 101).