Skip to main content
  • This guide is for Cosmos SDK chains with the Hyperlane module integrated. For CosmWasm-based chains, see the CosmWasm implementation.
  • It will walk you through deploying Hyperlane to your new chain as quickly as possible for testing, not production. This includes the core Mailbox and ISM components as well as Hyperlane Warp Route components for asset bridging.
  • To see which chains are already supported, visit the Registry.
  • If you need any help, reach out on GitHub Discussions or get in touch.

​
Prerequisites

Anyone can begin this quickstart guide once they have the following artifacts & assets available:
  • A Cosmos SDK chain with the Hyperlane module integrated (including the x/core and x/warp modules)
  • A new, custom, or pre-existing Cosmos SDK network of your choice, including the following metadata:
    • The chain name, e.g. hyp1
    • The chain ID, e.g. hyperlane-local-1
    • The bech32 prefix, e.g. hyp
    • RPC, REST, and gRPC URLs
    • Native token denomination and gas price
  • A deployer wallet hex private key (64 hex characters, with or without 0x prefix)
    • This wallet should be funded on your custom chain and any chain you will be passing messages to & from
    • If you use a mnemonic wallet, export/derive the raw hex private key before running CLI commands
  • Hyperlane CLI

​
1. Registry

The hyperlane registry init command is currently designed for EVM chains and does not support Cosmos SDK chains. Instead, create your chain metadata file manually. Create the directory and file: 
mkdir -p $HOME/.hyperlane/chains/yourchain
Then create $HOME/.hyperlane/chains/yourchain/metadata.yaml with the following content, replacing values with your chain’s details: 
# yaml-language-server: $schema=../schema.json
# Metadata for your custom Cosmos chain

bech32Prefix: hyp
chainId: hyperlane-local-1
displayName: My Cosmos Chain
domainId: 758986691 # Must be globally unique; generate with: python3 -c 'print(int("NAME".encode().hex(), 16) % 4_294_967_295)'
name: yourchain
protocol: cosmosnative
slip44: 118
nativeToken:
  decimals: 6
  denom: uhyp
  name: TEST
  symbol: TEST
gasPrice:
  amount: '0.2'
  denom: uhyp
rpcUrls:
  - http: http://127.0.0.1:26657
restUrls:
  - http: http://127.0.0.1:1317
grpcUrls:
  - http: http://127.0.0.1:9090
blockExplorers:
  - name: My Chain Explorer
    url: https://mychain.com/explorer
    apiUrl: https://mychain.com/explorer/api
Key Cosmos-specific fields:
  • protocol: cosmosnative — Must be exactly cosmosnative (not cosmos or ethereum)
  • bech32Prefix — Your chain’s address prefix (e.g. cosmos, osmo, hyp)
  • slip44 — SLIP-44 coin type (use 118 for standard Cosmos chains)
  • grpcUrls — Required for Cosmos SDK chains
  • gasPrice — Must include both amount and denom
  • nativeToken.denom — The on-chain denomination (e.g. uatom, uosmo)
  • domainId — Must be unique across the Hyperlane network (do not reuse another chain’s domain)

​
2. Core

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

​
Create Configuration

  1. Set the hex private key of your funded deployer address for Cosmos-native operations:
    • export HYP_KEY_COSMOSNATIVE='<YOUR_PRIVATE_KEY>' (64 hex characters, with or without 0x prefix)
    • Or pass --key.cosmosnative directly to deploy commands
  2. Create ./configs/core-config.yaml using the template below.
HYP_KEY is treated as the legacy Ethereum shared key in the current CLI. For Cosmos SDK chains, use HYP_KEY_COSMOSNATIVE (or --key.cosmosnative) to avoid key prompts.

​
Deploy

To deploy, run: 
hyperlane core deploy
Use the arrows and enter to select your custom chain from the bottom of the list. It will take a few minutes for all components to deploy.
Aggregation ISMs are currently not supported on Cosmos SDK chains due to AltVM limitations. Use messageIdMultisigIsm or merkleRootMultisigIsm instead.

​
Verify Deployment

After deployment, verify your core components are configured correctly: 
hyperlane core read --chain yourchain
hyperlane send message does not currently support Cosmos SDK chains. To test message delivery, deploy a Warp Route and use a relayer to process transfers.

​
Update Core Configuration (Day 2)

Use core read output as your editable config for updates such as validator rotation, default ISM changes, or gas oracle updates: 
hyperlane core read --chain yourchain --config ./yourchain-core.yaml
# Edit ./yourchain-core.yaml
hyperlane core apply --chain yourchain --config ./yourchain-core.yaml
Once ownership has been transferred away from the deployer, core apply will no longer work with the deployer key alone. Use the --strategy flag with a file submitter to submit transactions through the new owner (e.g. a multisig).
For production hardening, see:
🎉 Congrats! You have successfully deployed Hyperlane core to your custom Cosmos chain

​
3. Hyperlane Warp Route

Now that you have a Hyperlane Mailbox and core components on your chain, it’s time to set up token bridging between your chain and any other Hyperlane chain. Continue with one of the following guides:

​
4. Submit to Registry

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

​
Ensure complete info

Make sure your metadata is complete:
  • add a logo.svg file inside the folder
  • include Deployer information identifying the team deploying
  • indicate isTestnet true if the chain is testnet
  • lint the YAML files and order alphabetically

​
Commit to GitHub

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 Cosmos chain and added your work to the Hyperlane registry