Relayer - Cosmos Docs

IBC v2 Relayer is a standalone, production-ready, request-driven relayer service for the IBC v2 Protocol. The relayer supports interoperating between a Cosmos-based chain and major EVM networks (Ethereum, Base, Optimism, Arbitrum, Polygon, and more). The core relayer service has been used in production since 2023 via Skip Go, and is now modularized to be run on-prem by clients who cannot leverage the Skip Go managed service.

Relaying Sequence

Supported Features

Compatible with all major EVM chains (Ethereum, Base, Optimism, Arbitrum, Polygon, and more)
Request-driven design for configurable, on-demand relaying
Transaction failure retry support
- Re-orgs
- Out-of-gas
- Inadequate gas price
- Tx network propagation fails to reach leader
- Invalid by the network, but valid by the submitting node
Transaction Tracking API
Remote signing support
Concurrent packet intake and processing
Configurable packet delivery latency via batching
Ability to blacklist addresses (ex: OFAC)
Transaction cost tracking

Getting Started

Prerequisites

Go 1.24+
Docker and Docker Compose
A running proof API service
RPC endpoints for the chains you want to relay between

Local Development

Start Postgres and run migrations:

docker-compose up -d

Create a local config file (see Configuration Reference below).
Create a local keys file (see Local Signing below).
Run the relayer:

make relayer-local

The relayer will start:

gRPC API server on the address configured in relayer_api.address
Prometheus metrics server on the configured address
Relay dispatcher polling for new transfers

CLI Flags

Flag	Default	Description
`--config`	`./config/local/config.yml`	Path to relayer config file
`--ibcv2-relaying`	`true`	Enable/disable the relay dispatcher

Database Migrations

Database migrations must be run before starting the relayer. The relayer expects the database schema to already exist. Local Development:

docker-compose up -d

This starts PostgreSQL and runs migrations automatically. Using the migrate CLI:

# Install: https://github.com/golang-migrate/migrate
migrate -path ./db/migrations -database "postgres://relayer:relayer@localhost:5432/relayer?sslmode=disable" up

Using the relayer migrations container:

docker run --rm --network host <registry>/relayer-migrate:<version> \
  -database "postgres://relayer:relayer@localhost:5432/relayer?sslmode=disable" \
  up

Design

The relayer has three main components — the gRPC server which clients use to interact with the relayer, a Postgres database, and the core relayer. The gRPC server populates the database with packets, which the core relayer monitors and updates as it progresses in relaying those packets. The relayer is designed as a pipeline composed of a set of asynchronously running processors. Transfers pass through the processors sequentially. Some pipeline steps process transfers individually while others process transfers in batches.

API Interface

The relayer serves a gRPC server which clients use to specify what packets to relay and track packet relaying progress.

service RelayerApiService {
    // Relay is used to specify a source tx hash for packets the relayer should relay.
    // The relayer will identify all packets created by the transaction and attempt to relay them all.
    rpc Relay(RelayRequest) returns (RelayResponse) {}

    // The status endpoint is used to track the progress of packet relaying.
    // It takes a transaction hash and returns the status of any relevant packets the relayer is aware of.
    // The transaction must first have been passed to the relay endpoint.
    rpc Status(StatusRequest) returns (StatusResponse) {}
}

message StatusRequest {
    string tx_hash = 1;
    string chain_id = 2;
}

enum TransferState {
    TRANSFER_STATE_UNKNOWN = 0;
    TRANSFER_STATE_PENDING = 1;
    TRANSFER_STATE_COMPLETE = 2;
    TRANSFER_STATE_FAILED = 3;
}

message TransactionInfo {
    string tx_hash = 1;
    string chain_id = 2;
}

message PacketStatus {
    TransferState state = 1;
    uint64 sequence_number = 2;
    string source_client_id = 3;
    TransactionInfo send_tx = 4;
    TransactionInfo recv_tx = 5;
    TransactionInfo ack_tx = 6;
    TransactionInfo timeout_tx = 7;
}

message StatusResponse {
    repeated PacketStatus packet_statuses = 1;
}

message RelayRequest {
    string tx_hash = 1;
    string chain_id = 2;
}

message RelayResponse {}

Observability

Type	Name	Description
Metric	Relayer api request count	Paginated by method and response code
Metric	Relayer api request latency	Paginated by method
Metric	Transfer count	Paginated by source, destination chain, and transfer state
Metric	Relayer gas balance	Paginated by chain and gas token
Metric	Relayer gas balance state	A gauge where each value represents a gas balance state. 0 = ok, 1 = warning, 2 = critical. Paginated by chain
Metric	External request count	Paginated by endpoint, method and response code
Metric	External request latency	Paginated by endpoint and method
Metric	Transactions submitted counter	Paginated by node response success status and chain
Metric	Transaction retry counter	Paginated by source and destination chain
Metric	Transactions confirmed counter	Paginated by execution success and chain
Metric	Transaction gas cost counter	Paginated by chain
Metric	Relay latency	Time between send tx and ack/timeout tx. Paginated by source and destination chain
Metric	Detected client update required counter	Paginated by chain
Metric	Client updated counter	Paginated by chain
Metric	Excessive relay latency counter	Incremented anytime a transfer is pending longer than a configured threshold. Paginated by source and destination chain
Alert	Excessive relay latency	Should alert whenever the excessive relay latency counter increases
Alert	Excessive gas usage	Should alert whenever the gas cost counter increases faster than some threshold
Alert	Low gas balance	Should alert whenever the relayer gas balance state metric is in the warning or critical state

Configuration Reference

The relayer is configured via a YAML file. Below is the complete configuration schema with all available options.

Full Example

postgres:
  hostname: localhost
  port: "5432"
  database: relayer

metrics:
  prometheus_address: "0.0.0.0:8888"

relayer_api:
  address: "0.0.0.0:9000"

ibcv2_proof_api:
  grpc_address: "localhost:50051"
  grpc_tls_enabled: false

signing:
  # Local signing — set keys_path to use local key file
  keys_path: "./config/local/ibcv2keys.json"
  # Remote signing — set grpc_address to use remote signer (takes precedence over keys_path)
  # grpc_address: "localhost:50052"
  # cosmos_wallet_key: "cosmos-wallet-id"
  # evm_wallet_key: "evm-wallet-id"
  # svm_wallet_key: "svm-wallet-id"

coingecko:
  base_url: "https://pro-api.coingecko.com/api/v3"
  api_key: "your-api-key"
  requests_per_minute: 30
  cache_refresh_interval: 5m

chains:
  cosmoshub:
    chain_name: "cosmoshub"
    chain_id: "cosmoshub-4"
    type: "cosmos"
    environment: "mainnet"
    gas_token_symbol: "ATOM"
    gas_token_coingecko_id: "cosmos"
    gas_token_decimals: 6
    supported_bridges:
      - ibcv2
    cosmos:
      ibcv2_tx_fee_denom: "uatom"
      ibcv2_tx_fee_amount: 5000
      rpc: "https://cosmos-rpc.example.com"
      rpc_basic_auth_var: "COSMOS_RPC_AUTH"
      grpc: "cosmos-grpc.example.com:9090"
      grpc_tls_enabled: true
      address_prefix: "cosmos"
    ibcv2:
      counterparty_chains:
        "08-wasm-0": "1"   # client ID on cosmoshub → ethereum chain ID
      finality_offset: 10
      recv_batch_size: 50
      recv_batch_timeout: 10s
      recv_batch_concurrency: 3
      ack_batch_size: 50
      ack_batch_timeout: 10s
      ack_batch_concurrency: 3
      timeout_batch_size: 50
      timeout_batch_timeout: 10s
      timeout_batch_concurrency: 3
      should_relay_success_acks: true
      should_relay_error_acks: true
    signer_gas_alert_thresholds:
      ibcv2:
        warning_threshold: "5000000"    # in smallest denom units (uatom)
        critical_threshold: "1000000"

  ethereum:
    chain_name: "ethereum"
    chain_id: "1"
    type: "evm"
    environment: "mainnet"
    gas_token_symbol: "ETH"
    gas_token_coingecko_id: "ethereum"
    gas_token_decimals: 18
    supported_bridges:
      - ibcv2
    evm:
      rpc: "https://eth-mainnet.g.alchemy.com/v2/your-key"
      rpc_basic_auth_var: "ETH_RPC_AUTH"
      contracts:
        ics_26_router_address: "0x..."
        ics_20_transfer_address: "0x..."
      gas_fee_cap_multiplier: 1.5
      gas_tip_cap_multiplier: 1.2
    ibcv2:
      counterparty_chains:
        "tendermint-0": "cosmoshub-4"   # client ID on ethereum → cosmoshub chain ID
      recv_batch_size: 100
      recv_batch_timeout: 10s
      recv_batch_concurrency: 3
      ack_batch_size: 100
      ack_batch_timeout: 10s
      ack_batch_concurrency: 3
      timeout_batch_size: 100
      timeout_batch_timeout: 10s
      timeout_batch_concurrency: 3
      should_relay_success_acks: true
      should_relay_error_acks: true
    signer_gas_alert_thresholds:
      ibcv2:
        warning_threshold: "1000000000000000000"   # 1 ETH
        critical_threshold: "500000000000000000"   # 0.5 ETH

Section Reference

`postgres`

Field	Type	Description
`hostname`	string	Postgres host
`port`	string	Postgres port
`database`	string	Database name

Database credentials are read from environment variables POSTGRES_USER and POSTGRES_PASSWORD (default: relayer/relayer).

`metrics`

Field	Type	Description
`prometheus_address`	string	Address to serve Prometheus metrics (e.g. `0.0.0.0:8888`)

`relayer_api`

Field	Type	Description
`address`	string	Address for the gRPC API server to listen on (e.g. `0.0.0.0:9000`)

`ibcv2_proof_api`

Connection to the proof API service that generates relay transactions.

Field	Type	Description
`grpc_address`	string	gRPC address of the proof API
`grpc_tls_enabled`	bool	Enable TLS for the proof API connection

`signing`

Signing configuration. The mode is inferred from which fields are set:

If grpc_address is set → remote signing (ignores keys_path)
Else if keys_path is set → local signing from key file
Else → fatal error at startup

Field	Type	Description
`keys_path`	string	Path to local signing keys JSON file
`grpc_address`	string	gRPC address of the remote signer service. If set, takes precedence over `keys_path`
`cosmos_wallet_key`	string	Wallet ID for Cosmos chain signing (remote signer only)
`evm_wallet_key`	string	Wallet ID for EVM chain signing (remote signer only)
`svm_wallet_key`	string	Wallet ID for Solana chain signing (remote signer only)

`coingecko` (optional)

Used for tracking transaction gas costs in USD. If omitted, gas cost tracking is disabled.

Field	Type	Description
`base_url`	string	Coingecko API base URL
`api_key`	string	API key
`requests_per_minute`	int	Rate limit
`cache_refresh_interval`	duration	How often to refresh cached prices

`chains.<chain_key>`

Each entry under chains defines a chain the relayer can interact with.

Field	Type	Description
`chain_name`	string	Human-readable chain name. Used primarily in metrics.
`chain_id`	string	Chain identifier (numeric for EVM, string for Cosmos)
`type`	string	`cosmos`, `evm`, or `svm`
`environment`	string	`mainnet` or `testnet`
`gas_token_symbol`	string	Gas token ticker symbol
`gas_token_coingecko_id`	string	Coingecko ID for gas cost tracking (optional)
`gas_token_decimals`	uint8	Decimal places for the gas token
`supported_bridges`	[]string	List of bridge types (currently only `ibcv2`)

`chains.<chain_key>.cosmos`

Required when type: cosmos.

Field	Type	Description
`gas_price`	float64	Gas price for fee estimation. Mutually exclusive with `ibcv2_tx_fee_amount`
`ibcv2_tx_fee_denom`	string	Fee denom for ibcv2 txs (required if `ibcv2_tx_fee_amount` is set)
`ibcv2_tx_fee_amount`	uint64	Fixed fee amount for ibcv2 txs. Mutually exclusive with `gas_price`
`rpc`	string	Tendermint RPC endpoint
`rpc_basic_auth_var`	string	Environment variable name containing basic auth credentials for RPC
`grpc`	string	gRPC endpoint
`grpc_tls_enabled`	bool	Enable TLS for gRPC
`address_prefix`	string	Bech32 address prefix (e.g. `cosmos`, `osmo`)

`chains.<chain_key>.evm`

Required when type: evm.

Field	Type	Description
`rpc`	string	Ethereum JSON-RPC endpoint
`rpc_basic_auth_var`	string	Environment variable name containing basic auth credentials for RPC
`contracts.ics_26_router_address`	string	ICS26 Router contract address
`contracts.ics_20_transfer_address`	string	ICS20 Transfer contract address
`gas_fee_cap_multiplier`	float64	Multiplier applied to the estimated gas fee cap (optional)
`gas_tip_cap_multiplier`	float64	Multiplier applied to the estimated gas tip cap (optional)

`chains.<chain_key>.ibcv2`

IBC v2 relay configuration for this chain.

Field	Type	Description
`counterparty_chains`	map[string]string	Maps client IDs on this chain to their counterparty chain IDs. Only connections listed here will be relayed
`finality_offset`	uint64	Number of blocks to wait after a tx before considering it finalized. If omitted, uses the chain’s native finality
`recv_batch_size`	int	Max packets to accumulate before flushing a recv batch
`recv_batch_timeout`	duration	Max time to wait for recv packets to accumulate before flushing
`recv_batch_concurrency`	int	Max concurrent recv batches being processed
`ack_batch_size`	int	Max packets to accumulate before flushing an ack batch
`ack_batch_timeout`	duration	Max time to wait for ack packets to accumulate before flushing
`ack_batch_concurrency`	int	Max concurrent ack batches being processed
`timeout_batch_size`	int	Max packets to accumulate before flushing a timeout batch
`timeout_batch_timeout`	duration	Max time to wait for timeout packets to accumulate before flushing
`timeout_batch_concurrency`	int	Max concurrent timeout batches being processed
`should_relay_success_acks`	bool	Whether to relay acknowledgements for successful packet deliveries
`should_relay_error_acks`	bool	Whether to relay acknowledgements for failed packet deliveries

`chains.<chain_key>.signer_gas_alert_thresholds`

Field	Type	Description
`ibcv2.warning_threshold`	string	Gas balance (in smallest denom) at which the metric reports warning state
`ibcv2.critical_threshold`	string	Gas balance (in smallest denom) at which the metric reports critical state

Signing

The relayer supports two signing modes, configured via the signing block in the YAML config. The mode is inferred from which fields are populated:

If grpc_address is set → remote signing (ignores keys_path)
Else if keys_path is set → local signing from key file
Else → fatal error at startup

Local Signing

Set signing.keys_path to point to a JSON file containing private keys. The format is a map of chain IDs to key objects:

signing:
  keys_path: "./config/local/ibcv2keys.json"

{
  "1": {
    "private_key": "0xabc123..."
  },
  "cosmoshub-4": {
    "private_key": "abc123..."
  }
}

For EVM chains, the private key is a hex-encoded ECDSA private key. For Cosmos chains, it is a hex-encoded secp256k1 private key.

Remote Signing

For production deployments, the relayer can delegate signing to an external gRPC service. This keeps private keys isolated from the relayer process.

signing:
  grpc_address: "signer.internal:50052"
  cosmos_wallet_key: "my-cosmos-wallet"
  evm_wallet_key: "my-evm-wallet"
  svm_wallet_key: "my-svm-wallet"

The remote signer connection uses the SERVICE_ACCOUNT_TOKEN environment variable as a bearer token in gRPC metadata for authenticating requests to the signing service. The remote signer must implement the following gRPC service:

service SignerService {
    rpc GetChains(GetChainsRequest) returns (GetChainsResponse) {}
    rpc GetWallet(GetWalletRequest) returns (GetWalletResponse) {}
    rpc GetWallets(GetWalletsRequest) returns (GetWalletsResponse) {}
    rpc Sign(SignRequest) returns (SignResponse) {}
}

The Sign RPC accepts transaction payloads for EVM, Cosmos, and Solana chains and returns the appropriate signature format:

EVM: Accepts serialized tx bytes + chain ID, returns (r, s, v) signature components
Cosmos: Accepts sign doc bytes, returns a raw signature
Solana: Accepts a base64-encoded transaction, returns a raw signature

Upcoming Features

Solana support

Unsupported Features

Charging end users fees to relay IBC transactions
Relaying IBC v1 packets

​Relaying Sequence

​Supported Features

​Getting Started

​Prerequisites

​Local Development

​CLI Flags

​Database Migrations

​Design

​API Interface

​Observability

​Configuration Reference

​Full Example

​Section Reference

​postgres

​metrics

​relayer_api

​ibcv2_proof_api

​signing

​coingecko (optional)

​chains.<chain_key>

​chains.<chain_key>.cosmos

​chains.<chain_key>.evm

​chains.<chain_key>.ibcv2

​chains.<chain_key>.signer_gas_alert_thresholds

​Signing

​Local Signing

​Remote Signing

​Upcoming Features

​Unsupported Features