Skip to main content

Deploy Hyperlane to a new chain

info

This guide will help you deploy Hyperlane to your new chain as quickly as possible. This includes the core mailbox and ISM contracts as well as warp route contracts for assets you’re bridging

The guide is intended for testing - by the end you’ll be able to pass messages between your custom chain and any other in the Hyperlane network.

Prerequisites​

Anyone can begin this quickstart guide once they have the following artifacts & assets available:

  • A new, custom, or pre-existing network of your choice, including the following metadata:
    • A chain name, e.g. ethereum
    • A chain ID, e.g. 1
    • A RPC URL, e.g. https://eth.llamarpc.com
  • A deployer wallet/EOA private key or seed phrase
    • This EOA should be funded on your custom chain and any chain you will be passing messages to & from
  • The Hyperlane CLI

1) Registry​

Let’s create a custom chain config, run:

hyperlane registry init

Follow the prompts to set up your chain metadata. Setting up block or gas properties is optional.

Now, under $HOME/.hyperlane/chains you will find a new folder named with your custom chain’s name, and a file named metadata.yaml within that folder.

Example content of this config at $HOME/.hyperlane/chains/yourchain/metadata.yaml

 # yaml-language-server: $schema=../schema.json
 name: yourchain
 chainId: 171717
 domainId: 171717
 protocol: ethereum
 rpcUrls:
   - http: https://hyper-lane-docs.rpc.caldera.xyz/http
 nativeToken:
   name: Ether
   symbol: ETH
   decimals: 18

In addition to the CLI generated config above, you should also edit in the block explorer url.

blockExplorers:
  - apiUrl: https://explorer.yourchain.com/api
    family: etherscan
    name: Chainscan
    url: https://explorer.yourchain.com

3) Core: configure & deploy your custom chain’s core contracts​

Next, let’s configure, deploy and test your custom chain’s core contracts.

Initialize configuration​

  1. From your local environment, set the private key or seed phrase of your funded deployer address to HYP_KEY. For example: export HYP_KEY='<YOUR_PRIVATE_KEY>'
  2. From the same terminal instance, run:
hyperlane core init

The deployment config will be written to ./configs/core-config.yaml

owner: "0x16F4898F47c085C41d7Cc6b1dc72B91EA617dcBb"
defaultIsm:
  type: trustedRelayerIsm
  relayer: "0x16F4898F47c085C41d7Cc6b1dc72B91EA617dcBb"
defaultHook:
  type: merkleTreeHook
requiredHook:
  owner: "0x16F4898F47c085C41d7Cc6b1dc72B91EA617dcBb"
  type: protocolFee
  beneficiary: "0x16F4898F47c085C41d7Cc6b1dc72B91EA617dcBb"
  maxProtocolFee: "100000000000000000"
  protocolFee: "0"

Deploy contracts​

To deploy contracts, run:

hyperlane core deploy

Use the arrows and enter to select your custom chain from the bottom of the mainnet list. It will take a few minutes for all contracts to deploy.

Under $HOME/.hyperlane/chains you will find a new folder named with your custom chain’s name, and a file named addresses.yaml within that folder

  staticMerkleRootMultisigIsmFactory: "0x6906cb4741d3E2322E9f9aA645DfC8AB6F122c47"
  staticMessageIdMultisigIsmFactory: "0x3CE97a32d9C8294691cBd2baC09B078EDa75c429"
  staticAggregationIsmFactory: "0x81f969fDBF48278Ce09685Ce48e03388B6785aF4"
  staticAggregationHookFactory: "0x3d864A3c25F61E3c3A7d02e980453A6E1f0a92A6"
  domainRoutingIsmFactory: "0xC4c01f7B03f0fFa77A0265C600dEF7Ad28BCa5A2"
  proxyAdmin: "0xABb7175d5F123172E7B7Fa467CC9fE4C2FEdb942"
  mailbox: "0x5F58d75A9caDE4e2b191313223978dF049f93b81"
  interchainAccountRouter: "0x43c0745b0dE9Cb780816a24ddE63d79Ca99B5dE8"
  interchainAccountIsm: "0x9C96dC8f4257413225d6B5C47d1afbafc39B269F"
  validatorAnnounce: "0xE3bd39BF92DB385dE6313D6070b035bD934378CB"
  testRecipient: "0xa58462b1943Be1469Ed58db690C78583BA34Fd2E"

Send test message​

To send a test message, run:

hyperlane send message --relay

Currently core self-relay only works from an existing origin chain (if a testnet, holesky is best) to your custom chain. When dispatch is successful, you should see that the message was self-relayed!

tip

Sending from a testnet and getting Error: No fallback hook config found? Use holesky, which has a newer contract configuration that the CLI handles more gracefully. Other testnets will soon be supported.

note

🎉 Congrats! You have successfully sent a message to your custom chain

3) Warp Route​

Now that you have a Hyperlane mailbox and core contracts on your chain, it’s time to set up token bridging between your chain and any other Hyperlane chain.

Continue on to the Deploy a Warp Route docs for more details.

4) Submit to Registry​

If you want other chains to connect with you as well as to take this to production with Abacus Works, make a registry PR.

Before doing so, make sure you lint the yaml file as well as add a logo.svg file inside the folder.

First, navigate to your local instance of the registry and commit changes

cd ~/.hyperlane && git init && git add . && git commit

Then, sync local registry with canonical registry

git remote add canonical git@github.com:hyperlane-xyz/hyperlane-registry.git
git pull canonical main --rebase

Finally, push local registry to github fork and submit a PR. Please include a changeset in your PR.

note

Congrats! You have successfully deployed Hyperlane to your chain and added your work to the Hyperlane registry

Thank you for contributing to the future of permissionless interop 🫡