Hyperlane Relayers Setup-guide

Introduction

Hyperlane, as a cross-chain messaging protocol, has to ensure that the necessary data is relayed to specified destinations and then verify its consistency with the original data.

To enable this, Hyperlane has relayers that securely relay the data across two chains.

Hyperlane Relayers deliver interchain messages to their recipients.

Every Hyperlane message requires two transactions to be delivered: one on the origin chain to send the message, and one on the destination chain to receive the messages. Relayers are responsible for sending the second transaction.

Now, let's understand how to set up relayers on a local machine for your permissionless deployments.

Prerequisites

Clone/fork the Setup template or you have an option to open it on gitpod.
Docker is installed on your device. (If not, go ahead and use the gitpod instance from the template repository and make changes there).
Addresses of the hyperlane deployment (which you will find when you deploy an instance).
Create a folder called "relayer_data" inside your work directory.
A private key of the account that you want to set up the relayer with. (Follow this guide to generate one: https://docs.hyperlane.xyz/docs/operators/agent-keys/hexadecimal-key-setup).

Setup

Now that you have your relayer private key, we will configure a relayer for a chain.

Create a JSON file named config.json( or if created for validator, use the same) and an environment variables file named relayer.env.

The config.json file will contain details regarding the chain configuration and contracts deployed on it.

The following parameters must be specified in the config.json as shown in this example.


{
    "chains": {
    "sepolia": {
        "name": "sepolia",
        "domain": 11155111,
        "addresses": {
        "mailbox": "0xCC737a94FecaeC165AbCf12dED095BB13F037685",
        "interchainGasPaymaster": "0x9Ad09E9C3fC8094361bc3CA7500AFEe1aFA26b6C",
        "validatorAnnounce": "0x3Fc742696D5dc9846e04f7A1823D92cb51695f9a"
        },
        "protocol": "ethereum",
        "finalityBlocks": 1,
        "connection": {
        "type": "http"
        },
        "index": {
        "from": 3082913
        }
    },
    "zkevm": {
        "name": "zkevm",
        "domain": 1442,
        "addresses": {
        "mailbox": "0x2F37bE37c1c8b58d105DFbf6DC30c91e7C805Abf",
        "interchainGasPaymaster": "0x41A637313655ec7A92D4E06551E73aC767CB053f",
        "validatorAnnounce": "0x59191A4Df9A5DAEFA53006FcE5065B94febeEdE8"
        },
        "protocol": "ethereum",
        "finalityBlocks": 1,
        "connection": {
        "type": "http"
        },
        "index": {
        "from": 624309
        }
    }
  }
}

If this configuration is for a new Hyperlane deployment, then it will be readily available in the hyperlane-deploy/artifacts/agent_config.json file of your forked/cloned repository.

Now that we have all the information regarding the deployment, we will be defining the signer private key, RPC URLs, and other parameters inside our relayer.env file.

CONFIG_FILES=/relayerConfig.json
HYP_BASE_CHAINS_{CHAIN_NAME}_SIGNER_TYPE=hexkey
HYP_BASE_CHAINS_{CHAIN_NAME_2}_SIGNER_TYPE=hexkey
HYP_BASE_CHAINS_${CHAIN_NAME}_SIGNER_KEY=PUT_KEY_HERE
HYP_BASE_CHAINS_${CHAIN_NAME_2}_SIGNER_KEY=PUT_SAME_KEY_HERE
HYP_BASE_CHAINS_${CHAIN_NAME}_CONNECTION_URL=CONNECTION_URL
HYP_BASE_CHAINS_${CHAIN_NAME_2}_CONNECTION_URL=CONNECTION_URL
HYP_BASE_RELAYCHAINS=CHAIN_1,CHAIN_2
HYP_BASE_INTERVAL=5
HYP_BASE_ALLOWLOCALCHECKPOINTSYNCERS=false
HYP_BASE_DB=/hyperlane_db
HYP_BASE_METRICS=9090
HYP_BASE_TRACING_FMT=pretty
HYP_BASE_TRACING_LEVEL=info

The connection URL is nothing but the RPC URL for the chain you want to deploy it to. You can use public RPCs or obtain providers like QuickNode or Alchemy. The signer key and validator key are the same keys.

Relayers need both origin and destination chain URLs

Most of these can be included in the config file instead of env, but I suggest that these variables are best placed in env.

Now let us get the latest Docker image of Hyperlane relayers. We will need Docker configured and available in the terminal for this.

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

Now we run the relayer with our configuration and environment variables.

Before running this, fund a small amount of native token to your relayer address, as it is used to announce itself to the contracts.

DOCKER_IMAGE=gcr.io/abacus-labs-dev/hyperlane-agent:8127fa5-20230823-161309
docker run   -it   --env-file relayer.env   --mount type=bind,source={ABSOLUTE__PATH_OF_relayer_data_FOLDER},target=/hyperlane_db   --mount type=bind,source={ABSOLUTE_PATH_FOR_config.json},target= /relayerConfig.json   $DOCKER_IMAGE   ./relayer

Replace {absolute_path_of_json} with the path to the config.json file on your machine.

and replace {ABSOLUTE__PATH_OF_relayer_data_FOLDER} with the path to the relayer_data folder on your machine.

This configuration does not take fees from the contract interaction for relaying. To setup fee model refer the guide

Now the relayer starts getting logs from the contracts and starts dispatching to the destination chains.

All the relayer data is stored under folder relayer_data which has logs of all the blocks that were polled. Awesome! You have successfully set up the relayer end-to-end for your chain pairs. With both relayers and validators deployed for your chains, Hyperlane is now active and running!

Alright, what's next?

Your instance of Hyperlane can now be used for interchain message transfers as per your design. You can now use the messaging API in your contracts on both chains. If you were just a relayer or a validator for a pre-deployed Hyperlane instance, you would benefit from the fee payments made by the users on each chain. You will also contribute to the decentralized cross-chain ecosystem of Hyperlane.

To test these validators and relayers for your permissionless deployment, run the test script in hyperlane-deploy repository(cloned/forked). Refer this Permissionless deployment guide to know more

Conclusion

In conclusion, setting up Hyperlane relayers on a local machine for your permissionless deployments requires configuring the relayer with the necessary parameters and environment variables. By following the provided setup guide, you can establish relayers that securely relay data across different chains.

It is important to note that for production environments, additional considerations and deployment methods may be necessary. Stay tuned for further guides on deploying with Terraform for ECS or Helm charts for GCP kubernetes.

Stay Flashy 💫.

For queries, contact us on Discord (tag @muskbuster).

Hyperlane Academy