# 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_<HEIGHT>.tar.lz4
```

Replace `<HEIGHT>` 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).