This guide walks you through deploying an xERC20 Hyperlane Warp Route (HWR) between two networks of your choice. We’ll use Ethereum as an example for the origin chain; however, you can select any supported network as the origin and destination.

​
Prerequisites

To complete this walkthrough, you should have:

  1. An origin and destination network of choice, between which you’d like to deploy the xERC20 HWR.
  2. The address of an xERC20 or xERC20Lockbox on the origin and destination chain.
  3. Hyperlane CLI installed and a wallet private key set as the HYP_KEY environment variable, funded on both origin and destination networks.

​
Step 1: Initialize a New HWR

Run the following command to generate a HWR configuration:

hyperlane warp init
  1. Select Ethereum (origin) and YourChain (destination) using space, then hit enter.
  2. For Ethereum (origin), choose xERC20 or xERC20Lockbox, and enter the contract address.
  3. For YourChain (destination), choose xERC20 or xERC20Lockbox, and enter the contract address.

Choosing Between xERC20 and xERC20Lockbox:

  • xERC20Lockbox: Use this if your token is already deployed on the origin chain and requires a wrapped version for cross-chain transfers.
  • xERC20: Use this if your token natively implements xERC20 and does not require a lockbox.

If you’re unsure, review your token’s contract structure or deployment history to determine the correct choice.

​
Step 2: Deploy the xERC20 HWR

Run the following command to deploy the HWR:

hyperlane warp deploy

This deploys the *Hyperlane adapter contracts**, either:

  • HypXERC20Lockbox (if using xERC20Lockbox)
  • HypXERC20 (if using xERC20)

The CLI does not deploy non-Hyperlane contracts (e.g., existing xERC20 contracts). Those should already be deployed.

​
Step 3: Configure Minting Permissions

Once the xERC20 HWR contracts are deployed, you must configure minting permissions for the destination token.

Set the mint limit for the newly deployed HWR using the setLimits function in your xERC20 contract. By default, these limits are found in the Registry, located at ~/.hyperlane locally.

​
Step 4: Test Cross-Chain Transfers

Test transferring tokens across chains using:

hyperlane warp send --symbol <token_symbol> --amount <amount>
  • Replace <token_symbol> with your token.
  • Replace <amount> with the number of tokens to transfer.

​

🎉 Congrats! You have successfully created an xERC20 HWR. Your xERC20 tokens can now move across chains!

Please note that cross-chain operations rely on Interchain Security Modules (ISMs), and there are inherent risks, such as ISM trust assumptions.

​
Resources

For more resources on deploying xERC20 HWRs, check out: