Deploy Hyperlane to a new chain
This guide will help you deploy Hyperlane to your new chain as quickly as possible for testing. This includes the core mailbox and ISM contracts as well as warp route contracts for assets you’re bridging.
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 chain name, e.g.
- 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
- 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
$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 #explorer you're using, also supporting routescan or blockscout
name: Chainscan
url: https://explorer.yourchain.com
2) Core
Next, let’s configure, deploy and test your custom chain’s core contracts.
Initialize configuration
- 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>'
- From the same terminal instance, run:
hyperlane core init
The deployment config will be written to ./configs/core-config.yaml
./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
$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 Holesky to your custom chain. When dispatch is successful, you should see that the message was self-relayed!
Support in the CLI for other origin chains is being added, chains that are not supported will output Error: No fallback hook config found
? Use holesky
.
🎉 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.
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 🫡
Next Steps
If you want deploy a Relayer to relay messages to your chain, continue on to Deploy Hyperlane with Local Agents