LogoLogo
  • ⏩Introduction
    • Hyperlane Introduction
    • Getting started
    • Why Should You Use Hyperlane?
  • Permissionless Interoperability
    • Overview
    • Deploy Hyperlane
    • Warp Routes
      • Deploy a Warp Route
      • Deploy a UI for your Warp Route
    • Modular Rollup Interoperability
  • Build With Hyperlane
    • Quickstarts
      • Messaging
      • Accounts
      • Queries
      • hyperlane-quickstart repo
    • Guides
      • Finding my messages
      • Automatically pay for interchain gas
      • Manually pay for interchain gas
      • Choosing an interchain gas paymaster contract
      • Unit testing
      • Specifying an ISM
      • V2 migration guide
    • Explorer
      • Debugging messages
      • Configuring PI Chains
      • REST API
      • GraphQL API
    • Troubleshooting/Developer FAQ
    • Example apps
  • APIs and SDKs
    • Messaging API
      • Send
      • Receive
    • Accounts API
    • Queries API
    • Warp Route API
    • Interchain gas paymaster API
    • Hyperlane App Framework
      • Example usage
        • HelloWorld
        • Interchain Token
      • Solidity SDK
        • HyperlaneConnectionClient
        • Router
      • NodeJS SDK
        • RPC Providers
        • Deployment
        • Interchain testing
        • Quoting gas payments
        • App Abstraction
    • Hooks API
      • Contract addresses
  • Protocol
    • Overview
    • Mailbox
    • Interchain security modules
      • Interface
      • Multisig ISM
      • Routing ISM
      • Aggregation ISM
      • Optimistic ISM
      • Wormhole ISM
      • Hook ISM
      • CCIP-Read ISM
    • Interchain gas payments
    • Staking and slashing
    • Agents
      • Validators
      • Relayers
      • Watchtowers
    • Warp Routes
    • Implementation Guide
  • Operators
    • Validators
      • Guide
      • AWS setup
      • Monitoring and alerting
    • Relayers
      • Guide
      • Message filtering
    • Agent keys
      • Hexadecimal keys
      • AWS KMS keys
    • Agent configuration
      • Configuration reference
    • Running with docker compose
  • Resources
    • FAQ
    • Glossary
    • Contract addresses
      • Permissionless Deployment Contract Addresses
    • Domain identifiers
      • Permissionless Domain Identifiers
    • Default ISM settings
    • Coming Soon: Hyperlane v3
    • Token sources & faucets
    • Latencies
    • Github
    • Discord
    • Website
Powered by GitBook
On this page
  • Configuration
  • Hexadecimal keys
  • AWS KMS keys
  • Reference
  • Setup-specific configuration
  • Installation
  • Start Relaying
  • Running the binary
  1. Operators
  2. Relayers

Guide

Required setup instructions

PreviousRelayersNextMessage filtering

Last updated 1 year ago

Configuration

The relayer is responsible for watching for new messages on the origin chain(s) and delivering them to their destination chains. This involves being able to submit transactions to many destination chains, and therefore requires access to a key for signing transactions. There are two supported key types: hexadecimal private keys (for in-memory signing), and AWS KMS based keys (best practice for production environments).

Hexadecimal keys

A hexadecimal private key used for in-memory signing can be used by your relayer to sign transactions. This is the recommended setup for testing or development purposes.

AWS KMS keys

An AWS KMS key can be used by your relayer to sign transactions. This is the recommended setup for production relayers.

Reference

Also take a look at the Agent configuration page and the Configuration reference for a full list of configuration possibilities. The list below is not complete, however it should be enough to get started.

Your relayer takes as configuration the following:

Argument
Description

--relayChains

--chains.[chain_name].connection.url

An RPC url for chain_name. Example: --chains.ethereum.connection.url='http://localhost:8545' Relayers must set multiple connection URLs, one for each chain it interacts with.

--whitelist

--blacklist

--db

--allowLocalCheckpointSyncers

Environment variable
Description

CONFIG_FILES

Setup-specific configuration

These configurations requirements differ depending on which Guide instructions you followed.

If you created Hexadecimal keys, use these configs.

Argument
Description

--defaultSigner.key

A hexadecimal private key used to sign transactions for all chains. Example: --defaultSigner.key=123...def

If you created AWS KMS keys, use these configs.

Argument
Description

--defaultSigner.type

Set to aws.

Example: --defaultSigner.type=aws

--defaultSigner.id

The alias of your validator's AWS KMS key, prefixed with alias/.

Example: --defaultSigner.id=alias/hyperlane-validator-signer-polygon

--defaultSigner.region

The region of your AWS KMS key. --defaultSigner.region=us-east-1

Environment variable
Description

AWS_ACCESS_KEY_ID

The access key ID of your relayer's AWS IAM user.

AWS_SECRET_ACCESS_KEY

The secret access key of your relayer's AWS IAM user.

For chain-specific signers take a look at the Configuration reference

Installation

The recommended installation method for a production environment is using a Docker image.

Docker image

To download the docker image, run:

docker pull gcr.io/abacus-labs-dev/hyperlane-agent:8127fa5-20230823-161309

Building from source

First, clone the repo

git clone git@github.com:hyperlane-xyz/hyperlane-monorepo.git

Start Relaying

Running the binary

Refer to the Installation instructions to access the relayer binary.

Configuration can be placed in a relayer.env file, for example:

relayer.env
# These are example values to roughly illustrate
# what a .env file should look like

HYP_BASE_RELAYCHAINS=ethereum,polygon,avalanche
HYP_BASE_DB="/hyperlane_db"
# ...
# ...

To run the relayer binary with the environment variables specified in relayer.env:

Find the latest Docker image and set it to the environment variable $DOCKER_IMAGE.

Using the --env-file flag, we can pass in the environment variables to the relayer:

docker run \
  -it \
  --env-file relayer.env \
  --mount type=bind,source="$(pwd)"/hyperlane_db,target=/hyperlane_db \
  $DOCKER_IMAGE \
  ./relayer

For example, if your local validator is writing signatures to /tmp/hyperlane-validator-signatures-ethereum, you should mount a directory for the Docker container:

docker run \
  -it \
  --env-file relayer.env \
  --mount type=bind,source="$(pwd)"/hyperlane-validator-signatures-ethereum,target=/tmp/hyperlane-validator-signatures-ethereum,readonly \
  --mount type=bind,source="$(pwd)"/hyperlane_db,target=/hyperlane_db \
  $DOCKER_IMAGE \
  ./relayer

See these instructions for Building from source.

We can run the built binary from within the hyperlane-monorepo/rust directory with the environment variables found in relayer.env:

env $(cat relayer.env | grep -v "#" | xargs) ./target/release/relayer

Relayers needs to index all historic messages for the origin chain(s). This information is stored in a local database on disk (set with db in the config). This means running a relayer for the first time may take some extra time to catch up with the current state.

Comma separated names of the origin and destination chains to relay messages between. Example: ethereum,polygon,avalanche (See also the for how to specify origin and destination chains independently)

An optional whitelist. The relayer will only relay messages that match this whitelist. See for more info.

An optional blacklist. The relayer will not relay messages that match this blacklist. See for more info.

The path to where the validator should write persistent data to disk. Ensure this path to be persistent when using cloud setups. When using Docker, make sure to mount the persistent path/volume into the container. See for more info

If true, this will allow the relayer to look for validator signatures on the relayer's local filesystem. In a production environment, this should be false. If you're running a validator on the same machine by following the validator instructions, set this to true so that your relayer can access the local validator signatures.

If you want to add additional configuration files you can add additional paths here as a comma separated list. These files must be accessible within the filesystem your agent has access to. If you're running in Docker, see for tips on mounting your config files into your Docker container.

And then follow the in the rust directory

If you have followed the instructions to Deploy Hyperlane and are specifying a path to your own config file in the CONFIG_FILES environment variable, check out .

If you're running validator with on the same machine and want the relayer to access these validator signatures, be sure to your local validator's signature directory into your relayer at the same path that you used when

Hexadecimal keys
AWS KMS keys
setup instructions
Configuration reference
Message filtering
Message filtering
Configuration reference
mount
Config files with Docker
Config files with Docker
Local Setup
Announcing your validator
Local Setup