Hyperlane Validators Setup-guide

Hyperlane Validators Setup-guide


4 min read


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

To enable this, Hyperlane has a set of contracts called ISMs (interchain security modules) to verify the consistency. One of these ISMs is the Multisig ISM. To understand the Multisig ISM in simple terms, a set of validators attest to the message that is being written to the destination chain. These ISMs verify that m out of n validators have attested to the validity of a particular interchain message and only then allow the message to be written onto the destination chain.

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



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

Create a JSON file named config.json and an environment variables file named validator.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 validator.env file.


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.

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 validators. 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 validator with our configuration and environment variables.

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

docker run -it --env-file validator.env --mount type=bind,source={absolute_path_of_json},target=./validatorConfig.json,readonly $DOCKER_IMAGE ./validator

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

Now the validator checks if it has been announced and starts retrieving the logs from your contracts.

As these are done, it will start validating all transactions and store them in your local path in this format, while keeping a log of new transactions as they show up.

  "value": {
    "validator": "0x5c690e1ba18c92c2b92b89e096db93d3dec0faa0",
    "mailbox_address": "0x0000000000000000000000000282ee93886e62627c863d9ec88f1408ea7aeb3b",
    "mailbox_domain": 1442,
    "storage_location": "s3://hyperlane-validator-signatures-sudeep-zk-testnet/us-east-1"
  "signature": {
    "r": "0xe30c0ec859b24c16ece3fd81829b75d89dc3ffce4e90d004e4e55fb016f6a178",
    "s": "0x476f9c301f6040298de3f1d66ff48693637b93e5b4549ae1305434e3b9d08219",
    "v": 27
  "serialized_signature": "0xe30c0ec859b24c16ece3fd81829b75d89dc3ffce4e90d004e4e55fb016f6a178476f9c301f6040298de3f1d66ff48693637b93e5b4549ae1305434e3b9d082191b"

Awesome !! You have successfully set up the validator for one of your chain pairs.

Follow the same for your other chain as well(if not already existing).

Alright, what's next?

Validators allow you to verify if the relayed data is correct. If you are deploying your validator for an existing deployment, you need not run your own relayer as it has its own pre-existing relayers. However, if you have deployed between two chains that were not previously connected, you will have to run your own relayers, which you will understand how to set up in the next guide.

For those who are willing to run this in a production environment, a different approach might be required. However, the parameters and the setup will remain the same. You will have the option to deploy using Terraform for ECS or Helm charts for GCP (Guides coming soon).


In conclusion, setting up validators for Hyperlane deployments is essential to ensure the consistency and reliability of data relayed between chains. By configuring the necessary parameters and environment variables, you can deploy validators for different chains and start validating transactions. Running your own relayers may be required for new chain pairs, but existing deployments already have pre-existing relayers in place.

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) or twitter.