Hyperlane Validators Setup-guide

Introduction

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.

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 "syncer" inside your work directory.
A private key of the account that you want to set up the validator with. (Follow this guide to generate one: https://docs.hyperlane.xyz/docs/operators/agent-keys/hexadecimal-key-setup).

Setup

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.

CONFIG_FILES=/validatorConfig.json
HYP_BASE_VALIDATOR_TYPE=hexKey
HYP_BASE_CHAINS_{CHAIN_NAME}_SIGNER_TYPE=hexKey
HYP_BASE_CHAINS_${CHAIN_NAME}_SIGNER_KEY=PUT_KEY_HERE
HYP_BASE_CHAINS_${CHAIN_NAME}_CONNECTION_URL=CONNECTION_URL
HYP_VALIDATOR_REORGPERIOD=3
HYP_BASE_INTERVAL=5
HYP_BASE_ORIGINCHAINNAME={YOUR_CHAIN_NAME}
HYP_BASE_VALIDATOR_TYPE=hexKey
HYP_BASE_VALIDATOR_KEY=PUT_KEY_HERE
HYP_BASE_CHECKPOINTSYNCER_TYPE=localStorage
HYP_BASE_CHECKPOINTSYNCER_PATH="MAKE_A_FOLDER_AND_PUT_PATH_HERE"
HYP_BASE_ALLOWLOCALCHECKPOINTSYNCERS=false
HYP_BASE_METRICS=9090
HYP_BASE_TRACING_FMT=pretty
HYP_BASE_TRACING_LEVEL=info

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_IMAGE=gcr.io/abacus-labs-dev/hyperlane-agent:8127fa5-20230823-161309
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).

Conclusion

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.

Hyperlane Academy