Guide — running the relayer
Guides · 1 of 3 — operate Spectre. Run your own relayer, or use our hosted service.
The relayer is a single Go binary that runs both directions and contains the prover.
-
Build per-bucket prover artifacts (one-time; re-run only when circuit code changes) — emits the
(r1cs, pk, vk)per bucket and the matchingGroth16Verifier_N{N}.sol:cd relayer # CPU go run ./prover/cmd ./bin ../contracts/verifiers # GPU go run -tags=icicle ./prover/cmd -gpu-prove ./bin ../contracts/verifiers -
Build the relayer:
go build -o relayer ./cmd(add-tags=iciclefor GPU). -
Write the config (
config.json). You fill the endpoints and the deployed ETH contract addresses; the two client ids are left empty — step 4 generates and writes them back:{ "modules": [ { "name": "cosmos_to_eth", "src_chain": "provider", "config": { "tm_rpc_url": "https://rpc.provider-sentry-01.hub-testnet.polypore.xyz", "eth_rpc_url": "https://ethereum-sepolia-rpc.publicnode.com", "eth_ws_url": "wss://ethereum-sepolia-rpc.publicnode.com", "ics26_address": "0x… (ICS26Router)", "membership": "0x… (membership verifier)", "misbehaviour": "0x… (misbehaviour verifier)", "update_client": "0x… (update-client verifier)", "wrapper_verifier": "0x… (WrapperVerifier)", "ics26_client_id": "provider", "fetch_timeout": 15, "cosmos_wasm_client_id": "", "ics07_client": "" } }, { "name": "eth_to_cosmos", "config": { "eth_beacon_api_url": "https://…/eth/v1/beacon" } } ], "batch": { "batch_size": 5, "batch_period_seconds": 3 }, "server": { "address": "127.0.0.1", "port": 3000, "log_level": "info" } }- You fill:
tm_rpc_url(Cosmos RPC),eth_rpc_url/eth_ws_url,eth_beacon_api_url, and the five ETH contract addresses from your contract deploy.ics26_client_idis the client id the ETH router uses for the Cosmos chain (falls back tosrc_chainif omitted). - Generated — leave empty:
cosmos_wasm_client_id(←create-clients-cosmos) andics07_client(←create-clients-eth). - Secrets stay out of this file — signer keys and local toggles live in
relayer/.env:
ETH_PRIVATE_KEY=<eth signer private key> # pays gas + signs on Ethereum COSMOS_PRIVATE_KEY=<cosmos signer private key> # pays fees + signs on Cosmos COSMOS_CHAIN_ID=provider # the Cosmos chain-id you target PROVER_BIN_DIR=./bin # per-bucket artifactsOptional overrides (sane defaults if unset):
COSMOS_GAS_LIMIT,COSMOS_FEE_DENOM,COSMOS_FEE_AMOUNT,ETH_GAS_LIMIT. Never commit real keys. - You fill:
-
Create the light clients on both chains. The simplest path is the one-shot orchestrator — it runs the Cosmos side first (creates the Ethereum light client on Cosmos, so its
08-wasm-Nid is known), then the Ethereum side (deploys the ICS07 client wired to that id), and writes bothcosmos_wasm_client_idandics07_clientback into the config:./relayer create-clients --config config.json --wasm-checksum <hex>For a public testnet you usually want the two split commands instead (same code, run individually) — so each step can be retried on its own and you can inspect the ids between them:
# cosmos first — writes cosmos_wasm_client_id ./relayer create-clients-cosmos --config config.json --wasm-checksum <hex> # then eth — deploys ICS07, writes ics07_client ./relayer create-clients-eth --config config.jsonOrder matters:
create-clients-ethrequirescosmos_wasm_client_idto already be in the config (it wires it as the on-chain counterparty), so runcreate-clients-cosmosfirst.create-clients-ethis idempotent — ifics07_clientalready has deployed code, it skips the deploy. -
Run the bi-directional loop:
# CPU ./relayer start --config config.json # GPU (or set GPU_PROVE=1) ./relayer start --config config.json --gpu-prove
Config knobs: trust_level (default 2/3), proof_type (groth16), batch size/period, and the update epoch. CPU is the default backend; GPU is tuned via GNARK_ICICLE_* env vars. cosmos_wasm_client_id and ics07_client are generated — left empty in the example and filled in by step 4.
Modular by direction. The relayer is a hub of relay services — one per bridge direction (CosmosToEth, EthToCosmos). New directions (e.g. Solana↔Cosmos) or app-specific relays plug in as new services without touching the core.
Build prerequisites: Go ≥ 1.21, Foundry, Bun, Just, and the two gnark forks (vendored as git submodules under third_party/, with a built libgaraga_rs FFI). GPU adds an NVIDIA CUDA driver + ICICLE libs. See the repo README for submodule + ICICLE setup.