Warp Routes Walkthrough

A step-by-step guide to understanding and deploying a Warp Route

Published in

Hyperlane

7 min readFeb 17, 2023

This is a walkthrough tutorial on how to deploy Warp Routes, a permissionless bridge that enables anyone to transfer assets between blockchains. You’ll learn how Hyperlane Warp Routes work and we’ll deploy a Warp Route together step-by-step. Whether you are a developer or not, this tutorial is for anyone looking to use Warp Routes.

Let’s get started:

TL;DR of what we cover in this Warp Route Walkthrough:

Learn about Warp Route Architecture
Learn about Collateral vs Synthetic Chain
Warp Route Token Flow and how does gas fees are handled
Deploy Warp Route
Deploy Warp Route UI

Let’s kick off with a quick introduction about Hyperlane since we’ll be using Hyperlane contracts to deploy Warp Routes. Hyperlane is a permissionless modular interoperability layer that enables developers to deploy interchain messaging protocol with its plug-and-play solutions.

Want to learn more about Hyperlane? — check out the docs. Now let’s learn more about Warp Routes.

Warp Routes

Warp Routes are Hyperlane’s permissionless token bridging module, specifically, they are Hyperlane’s unique take on the concept of token bridging. Warp Routes provide developers with customizable interchain security, among other unique features you’ll learn about in this post. Unlike other token wrapping protocols, Warp Routes are secured by Interchain Security Modules (ISM), allowing developers to specify the security model of their interchain token structure. Specifically, Warp Routes are individual instances of a bridge, each one unique from any others, as opposed to traditional token bridges where a single bridge owns and defines the terms for all bridged assets.

That was the intro, now let’s learn the difference between Collateral vs Synthetic chain so you can understand the Warp Route Architecture and token flow better. Don’t worry, I will try to simplify it, if you understand the difference between Collateral and Synthetic feel free to skip this part.

Collateral vs Synthetic chain

TL:DR Collateral chain = the origin chain where you deposit any ERC-20 token to a HypCollateral contract.

Synthetic chain = the destination chains between which HypERC-20 tokens can flow. HypERC-20 tokens are minted 1:1 from tokens locked as collateral.

The Collateral chain is where you deposit the ERC-20 tokens — it is the “origin chain” for your Warp Route — the permissionless token bridge. This chain locks and holds the token value, it can withdraw the token value when the HypERC-20 token which represents the ERC-20 token value is burned. Collateral token — any ERC-20. It does not get burned but its value is reflected 1:1 on the Synthetic chain(s). Users can redeem their HypERC-20 tokens for their origin tokens at any time.

Synthetic chain moves the HypERC-20 token which represents 1:1 value of the initial ERC-20 token from the Collateral chain and reflects it as HypERC-20 on the synthetic chain(s). HypERC-20 token can be minted via a Router in the token flow and used on the Synthetic chain to transfer value. More on this below.

Next up, a deep dive into how Warp Routes — token routes work and dive a little deeper into the architecture of Warp Routes.

Warp Route architecture overview

Warp Route contracts transfer value between chains by locking tokens as collateral on the origin chain (the Collateral chain) and then minting the token as wrapped token (HypERC-20 synthetics) which get transferred to the destination chain (the Synthetic chain referred to earlier). Locked tokens can be returned to the origin chain to reclaim the initial ERC-20 tokens (collateral) at any time. Unlike other bridges, Warp Routes have customizable security; each route can specify a contract (an Interchain Security Module) to be used to enforce rules and constraints the token route must follow.

Warp Routes use Hyperlane Mailbox contracts which enable communication between chains. Mailbox contracts as well as Interchain Security Modules are implemented on any of the mainnet and testnet chains by Hyperlane. You can create routes between any of these mainnet or testnet chains. Better yet, you can even use Warp Routes to bridge assets over to any new chain by deploying Hyperlane there yourself, thanks to Permissionless Interoperability.

So how does token flow through the Warp Route? Let me explain:

Warp Route Token Flow

As a developer, you transfer any ERC-20 contract on the Collateral chain which HypERC20Collateral wraps to mint new HypERC-20 tokens. Then the mailbox contract on the collateral chain passes the data as a message to the relayer. The relayer pass the message data over to Interchain Security Module (ISM) which verifies the message, pass the information back to Mailbox which then send the data over to HypERC20 contract on the synthetic chain that mint and reflect the value 1:1 of the ERC-20 contract on the Collateral (origin) chain.

Warp Routes require gas fees to function. Fees are paid as part of outbound messages.The Router estimates the gas fee for the transfer before transfering the HypERC-20 tokens to destination chains. That’s why you need to have a gas token (like ETH or any other native mainnet or testnet token) on the Collateral (source) chain before deploying or using a Warp Route.

Deploying the Warp Route

This process is pretty simple, as you are going to deploy the set of Warp Route contracts which include HypERC20Collateral and HypERC20.

Full code for deploying Warp Route

# Install dependencies
yarn
# Build source and generate types
$ yarn build:dev

We’re gonna use the following command to deploy Warp Route:

yarn ts-node scripts/deploy.ts — private-key $PRIVATE_KEY — token-config ./configs/warp-route-token-config.json

Looks easy right? Before we deploy, we’re going to need to configure our Warp Route’s JSON file, we’re going to do that now.

You can find code examples of a token config here — this example is between Goerli, Alfajores, Fuji and Moonbasealpha testnets. You can use the same example for configuring your own Warp Route UI. You can find a full list of contract addresses in our docs, that should get you all the information you need to successfully configure and deploy your first Warp Route.

{ 
"goerli": {
"type": "collateral",
"token": "0xb4fbf271143f4fbf7b91a5ded31805e42b2208d6",
"owner": "0x5bA371aeA18734Cb7195650aFdfCa4f9251aa513",
"mailbox": "0xCC737a94FecaeC165AbCf12dED095BB13F037685",
"interchainGasPaymaster": "0xF90cB82a76492614D07B82a7658917f3aC811Ac1"
},
"alfajores": {
"type": "synthetic",
"name": "Weth",
"symbol": "WETH",
"totalSupply": 0,
"owner": "0x5bA371aeA18734Cb7195650aFdfCa4f9251aa513",
"mailbox": "0xCC737a94FecaeC165AbCf12dED095BB13F037685",
"interchainGasPaymaster": "0xF90cB82a76492614D07B82a7658917f3aC811Ac1"
},
"fuji": {
"type": "synthetic",
"name": "Weth",
"symbol": "WETH",
"totalSupply": 0,
"owner": "0x5bA371aeA18734Cb7195650aFdfCa4f9251aa513",
"mailbox": "0xCC737a94FecaeC165AbCf12dED095BB13F037685",
"interchainGasPaymaster": "0xF90cB82a76492614D07B82a7658917f3aC811Ac1"
},
"moonbasealpha": {
"type": "synthetic",
"name": "Weth",
"symbol": "WETH",
"totalSupply": 0,
"owner": "0x5bA371aeA18734Cb7195650aFdfCa4f9251aa513",
"mailbox": "0xCC737a94FecaeC165AbCf12dED095BB13F037685",
"interchainGasPaymaster": "0xF90cB82a76492614D07B82a7658917f3aC811Ac1"
}
}

Optionally you can configure the security in the Interchain Security Module. You can find more information about ISM configuration in the docs. You can play around different ISMs but no need to.

With our Warp Route fully configured, we can now go back to our yarn commands, and get ready to deploy.

yarn ts-node scripts/deploy.ts — private-key $PRIVATE_KEY — token-config ./configs/warp-route-token-config.json

Note that you can create a bridge between any of the existing testnet chains that Hyperlane supports and also between any of existing mainnet chains based on your choice. Warp Routes does not support cross chain testnet to mainnet message exchange, but this can be worked around as well.

Deploy Warp Route UI

With the contracts configured and deployed, we can build our UI! Warp Route’s UI is fully customizable and allows developers to use Warp Route with any ERC-20 token. You can use Vercel to host your Warp Route UI then create a new project, connect it to your Git repository and hit Deploy!

Here is Warp Route UI example, you need to configure the tokens command — example:


 {
  "name": "Hyperlane Default Tokens",
  "timestamp": "2022-12-23T12:00:00.000Z",
  "version": {
    "major": 1,
    "minor": 0,
    "patch": 0
  },
  "tags": {},
  "logoURI": "https://www.hyperlane.xyz/logo-blue.png",
  "keywords": ["hyperlane", "default"],
  "tokens": [
    {
      "chainId": 5,
      "address": "0xb4fbf271143f4fbf7b91a5ded31805e42b2208d6",
      "name": "Weth",
      "symbol": "WETH",
      "decimals": 18,
      "logoURI": "https://raw.githubusercontent.com/trustwallet/assets/master/blockchains/ethereum/assets/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2/logo.png",
      "hypCollateralAddress": "0xff1232787e3791c256e4F4746aF4EE2db353329c"
    }
  ]
}

Now replace the configuration based on your desired ERC-20 token. Use our token customisation documentation to help you customize your tokens.

For more information follow Warp Route UI documentation.

Congratulations on deploying your first Warp Route!

Now go ahead and use the Warp Route to send tokens between chains. If you do run into issues, hop in the Hyperlane Discord to report issues, and ask questions. The Hyperlane team is always ready to assist you. For more information about the Hyperlane protocol, check out the Hyperlane Documentation.

More about Hyperlane

Hyperlane is the first Permissionless Interoperability layer, enabling anyone to connect any blockchain, out-of-the-box. With Hyperlane, developers can build Interchain Applications, apps that abstract away the complexity of interchain interactions and serve users on any connected chain. Additionally, Hyperlane’s modular security stack gives developers the power to customize their interchain security. Hyperlane development is open-source and led by core developers at Abacus Works.

Go Interchain with Hyperlane

Start building with our Docs.

Experiment with Hyperlane in 5 minutes with our Quickstarts.

Join our Discord if you have any questions.

Apply to join our crew Here.

Find us on Twitter.