SpectreGuides

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.

  1. Build per-bucket prover artifacts (one-time; re-run only when circuit code changes) — emits the (r1cs, pk, vk) per bucket and the matching Groth16Verifier_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
  2. Build the relayer: go build -o relayer ./cmd (add -tags=icicle for GPU).

  3. 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_id is the client id the ETH router uses for the Cosmos chain (falls back to src_chain if omitted).
    • Generated — leave empty: cosmos_wasm_client_id (← create-clients-cosmos) and ics07_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 artifacts

    Optional overrides (sane defaults if unset): COSMOS_GAS_LIMIT, COSMOS_FEE_DENOM, COSMOS_FEE_AMOUNT, ETH_GAS_LIMIT. Never commit real keys.

  4. 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-N id is known), then the Ethereum side (deploys the ICS07 client wired to that id), and writes both cosmos_wasm_client_id and ics07_client back 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.json

    Order matters: create-clients-eth requires cosmos_wasm_client_id to already be in the config (it wires it as the on-chain counterparty), so run create-clients-cosmos first. create-clients-eth is idempotent — if ics07_client already has deployed code, it skips the deploy.

  5. 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.