Skip to main content

Deploy a Warp Route

Create an interchain route for your token

A Warp Route is a type of router application, requiring a HypERC20 or HypERC721 token contract to be deployed on each chain you wish to support.

info

Check out the Warp Route reference page for more information on the interface and security implications of a Warp Route.

Prerequisites​

1. Configuration​

Warp Route deployment config​

To deploy the route, you will need a Warp Route deployment config file. A valid config will specify:

  • Which token, on which chain, is this Warp Route being created for?
  • Optional: Hyperlane connection details including contract addresses for the mailbox, interchain gas, and interchain security modules.
  • Optional: The token standard - this includes fungible tokens using ERC20 or NFTs using ERC721, as well as ERC4626 yield-bearing tokens. Note ERC721 support is experimental and some Hyperlane tooling won't work for NFTs yet.

The easiest way to create one is with the CLI's config command:

hyperlane warp init
tip

If your config looks correct, you can now skip to Step 2: Deployment. Or see below for details on how to define your config manually.

Deployment config schema​

Your config consist of a map of chain names to deployment configs. Each config sets details about the token for which you are creating a Warp Route.

  • type:
    • Set this to collateral to create a basic Warp Route for an ERC20/ERC721 token
    • Set this to collateralVault to create a yield-bearing Warp Route for an ERC20 token that deposits into an existing ERC4626 vault
    • Set this to native to create a Warp Route for a native token (e.g. ether)
  • address:
    • If using collateral, the address of the ERC20/ERC721 contract for which to create a route
    • If using collateralVault, the address of the existing ERC4626 vault to deposit collateral into
  • isNft: If using collateral for an ERC721 contract, set to true.

Optional fields​

You may specify the following optional values in your config entries. If no values are provided, the deployer will attempt to pull these values from elsewhere. In the case of metadata (symbol, name decimals), it will query the contract. For addresses (mailbox, ISM) it will check the registry, either yours (if provided) or the default.

  • symbol: The token symbol
  • name: The token name
  • decimals: The number of decimal places for the token
  • mailbox: The address of the the mailbox contract to use to send and receive messages
  • interchainSecurityModule: The address of an interchain security modules to verify interchain messages

Example​

For a minimal Warp deployment config example using local anvil chains, see warp-route-deployment.yaml.

Chain configs​

The deployment will require basic information about any chains it will be interacting with. If the target chains are not already in the Hyperlane Registry, you must specify chain metadata for them. See the CLI reference for details.

To see what chains are in the currently known, run the following command:

hyperlane registry list

To create a chain metadata config for any other chains, run the following command:

hyperlane registry init

Or you can define the config manually. See the ChainMetadata type for its schema. See chain-config.yaml for an example.

2. Deployment​

Dry Run a Warp Deployment (Optional)​

Prior to executing a warp deployment, you can perform a dry-run via --dry-run <CHAIN_NAME> or -d <CHAIN_NAME> to ensure that the warp deployment will be successful as well as provide analytics on the gas costs of deployment. This will not trigger any real transactions but will simulate a deployment to display a list of required contracts and their respective gas costs.

In addition to validating your upcoming warp deployment, you can optionally provide the address of the EOA you intend to deploy with via --from-address or -f. This will ensure you have approximately enough funds to complete the warp deployment.

note

In order to execute a dry-run, you will need an Anvil node running in a separate terminal instance. To spin up an Anvil node, run anvil. For more on Anvil and installation, checkout Foundry's Anvil docs.

hyperlane warp deploy --dry-run chain1 \
    --from-address $YOUR_DEPLOYER_ADDRESS \ # (optional) your account address to be impersonated via Anvil; defaults to the HYP_KEY env variable
    --overrides # (optional) path to a override registry; defaults to the local ./ path

Deploy​

Run the following command to initiate the Warp Route deployment:

hyperlane warp deploy

Once finished, the CLI will create two new artifact files: otherchain-yourchain-addresses.yaml and otherchain-yourchain-config.yaml under $HOME/.hyperlane/deployments/warp_routes/.

The first file contains addresses for the newly deployed Warp Route contracts. The second is a config file which can be used with the CLI and Warp UI to interact with the new Warp Route.

3. Testing​

You can initiate a test transfer of a single wei with the following command:

hyperlane warp send --relay --warp $HOME/.hyperlane/deployments/warp_routes/TOKEN/corechain-yourchain-config.yaml

You can test in either direction between where you have the warp route set. However, if you deployed native and synthetic warp routes, you must select the origin with the native route deployed. By default, the amount sent is 1 of the smallest unit of the token.

tip

Next Steps

  • If you are following the Deploy Warp Route guide, and want other chains to connect with you as well as to take this to production with Abacus Works, follow the Submit to Registry guide.

  • If you want interact with Warp Routes using a UI. Continue on to the Warp UI docs for details on how to set it up.