Hyperlane from A to Z

Permissionless Interoperability Layer for web3


8 min read

Hyperlane from A to Z

gm gm gm!!!

Even in a vast blockchain network with countless nodes and layers, users need help utilizing the decentralized network's complete potential because DApps use different chains. Some use Ethereum, some Polygon, some Gnosis, and so on!

In this environment, developers should build chain-agnostic applications—no dependency on one chain and no restriction for any user.

Now, solving this interoperability issue between different chains requires devs to build robust and, more importantly, secure designs, which is a highly technical and resourceful process, and to save devs from going through such pain Hyperlane comes into the picture.

This article will explain almost all about Hyperlane and how it works, so grab a coffee ☕️ and LFG 🚀

D_D Newsletter CTA

What is Hyperlane?

Hyperlane is a permissionless interoperability protocol that helps devs send arbitrary data across chains⛓

Permissionless means no one requires any permission from the Hyperlane team to use Hyperlane SDK, contracts, or even while deploying on new chains as I did👇🏻

Interoperability means sending between different chains. Imagine initiating a transaction on Ethereum to close a position on Polygon.

Hyperlane is a complete modular protocol that helps devs to customize it according to their application requirements.

The following are the key components of Hyperlane:

  • Mailbox

  • Interchain Security Module (ISM)

  • Interchain Gas Payment (IGP)

  • Agents

This article will explain each of them. You can either learn about them in depth one by one or go directly to the example.

What is a Hyperlane Mailbox?

Mailbox is an on-chain API to send and receive interchain messages.

Mailbox is the middleman that helps devs connect different chains and leverage them to build something new.

Hyperlane deployed a Mailbox contract on each of its supported chains. The contract interface defines two functions that must be present in these cross-chain contracts, dispatch and process.

How Does the dispatch Function Work?

This function lets you send data from the origin to the destination chain.

It accepts several params:

  • _destinationDomain (uint32): The domain of the destination chain or the deployer.

  • _recipient Address (bytes32): The recipient's address.

  • _messageBody (bytes): The content of the message as raw bytes.

The function works by following these steps:

  1. It checks whether the message length exceeds the 2KiB length.

  2. It formats the _messageBody using Message.sol.

  3. Message.sol provides an id function that returns a KECCAK256 hash of _message.

  4. This hash becomes the _id and is saved into an incremental Merkle tree.

  5. The function uses the Merkle tree to verify fraud proofs in Hyperlane's staking and slashing protocol.

How Does the process Function Work?

The function is called on the destination chain to receive the message. It accepts the following two params:

It works by following these steps:

  1. The _message argument is the one the dispatch function formatted with Message.sol.

  2. The _metadata argument is metadata provided by the ISM relayer to verify _message.

  3. The function checks whether the _id is in the array of delivered messages. If it is, it reverts with delivered; if not, it adds it to that array.

  4. The function gets the ISM address for the recepientAddress. If the recipient has defined a specific ISM, it uses that; otherwise, it uses the default ISM for the chain.

  5. It uses the ISM address to verify messages received by the Mailbox.

  6. After verification, it emits the message received event using the IMessageRecepient.sol

You can learn more about Mailbox in the Hyperlane docs..

What are Hyperlane Interchain Security Modules?

An ISM verifies that the messages delivered on the destination chain come from the origin chain.

Mailbox uses the ISM to verify the message Mailbox received from a relayer before executing transactions.

Devs can define their own ISM for their application or can use default ISMs provided by the team, using the ISpecifiesInterchainSecurityModule.sol


  • ISM can be configured per the application requirements, with all the additional parameters required by the application.

  • Devs can use more than one ISM in their application to increase security and work according to the chain's consensus.

  • Devs can use IInterfaceSecurityModule.sol and build a custom ISM according to their needs.

Each ISM comes with two main functions:


D_D Newsletter CTA

How Does the verify Function Work?


This function takes two params:

  • message(bytes): Message that needs to be verified.

  • metadata(bytes): Off-chain bytes provided by the relayers.

How Does the moduleType Function Work?

This function signals relayers about the module type to include in the metadata.

How to Implement an Interchain Security Module?

You can use the ISpecifiesInterchainSecurityModule.sol module to implement a custom ISM for your application.


The team provides different prebuilt ISMs:

  • MultisigISM

  • RoutingISM

  • AggregationISM

  • OptimisticISM

  • WormholeISM

  • HookISM

You can find more details about ISMs in the Hyperlane docs.

What is the Hyperlane Interchain Gas Paymaster?

The IGP is an on-chain API to pay relayers that deliver the message on the destination chain.

An interchain message requires two transactions: one on the origin chain to send the message and one on the destination chain to receive it.


When users send the message via a Mailbox contract on the origin chain to a relayer, they must include the gas fee to cover the gas fee on the destination chain. The IGP calculates the gas fee and sends the amount to the relayer.


IGP provides two functions:


  • payGasFor()

  • quoteGasPayment()

How does the payForGas Function Work?


This function takes four parameters:

  • _messageId

  • destinationDomain

  • gasAmount

  • refundAddress

When the user sends the above parameters, the following steps happen:


  1. The function gets the gas fee required on the destination chain by calling quoteGasPayment(). It reverts if the required amount exceeds the msg.value.

  2. It calculates the overpaid amount; if it exceeds 0, it sends the amount to the refundAddress.

  3. It emits a GasPayment event.

How does the quoteGasPayment Function Work?


This function takes the following parameters: _destinationDomain and _gasAmount. It works like this:


  1. The function gets the token exchange rate and the gas price for the destination chain.

  2. It calculates the gas fee on the destination chain.

  3. It calculates the number of native tokens required on the origin chain and returns it.

The IGP Workflow

Let's look at a complete workflow of IGP on the origin chain to deliver the message on the destination chain:

The Hyperlane docs have additional details if you want to learn more about IGP.

What are Hyperlane Agents?

Agents are the off-chain actors that power Hyperlane.

There are three agents in the Hyperlane protocol: Validators, relayers, and watchtowers.


Since Hyperlane is a permissionless interoperability protocol, you can take the role of any agent and contribute to the network's security.

What are Hyperlane Validators?

They sign the current Merkle root, which they receive from the Mailbox.latestCheckpoint().


Validators are supposed to sign the checkpoint after it reaches the finality to maintain the network's security.

After signing the checkpoint, validators post signatures on the available storage so that the Relayers can aggregate them.

What are Hyperlane Relayers?

Relayers are responsible for delivering messages to the recipient.


It works as follows:

  1. Observe Mailbox for new messages.

  2. Use Mailbox to get the ISM implemented by the recipient.

  3. Aggregate the metadata for the ISM.

  4. Deliver the message.

Relayers can also have configurations for the messages they want to deliver:

  • A sender/recipient allowlist.

  • A sender/recipient denylist

  • Getting paid on-chain after delivering.

The relayers get rewarded when they process the message with the gas fee.

D_D Newsletter CTA

What are Hyperlane Watchtowers?

They are the police of the Hyperlane protocol. They look for fraudulent validators in the network and slash their stake. Watchtowers get rewarded when they submit the correct report of fraud.

You can learn more about agents in the Hyperlane docs.

Example: How to Send a Message from Polygon zkEVM to Ethereum?

Let's use an example to understand how Hyperlane's components work together.

Jim wants to send a message data to Dwight from Polygon zkEVM to Ethereum with Hyperlane.


The following steps are required to transfer the message:


  1. Jim sends the message data, recipient address, and destination chain to the Maibox contract on the Polygon zkEVM chain.

  2. The Mailbox emits an event that gets indexed.

  3. Validators sign the latest checkpoint.

  4. The signature gets stored in the database.

  5. Jim pays the gas fee using IGP during the process.

  6. When the relayer receives the gas fee, it relays the message and metadata on the Ethereum chain.

  7. The messageBody is sent to the ISM for verification.

  8. The message gets delivered to Dwight on the Ethereum chain.

D_D Newsletter CTA

Whoo!!🤩 This was quite a lot of workflow and solidity contracts understanding.

If you wanna explore more check out the Hyperlane Docs, and if you have any queries get them resolved in Hyperlane India Telegram Channel.

You can connect with me on Twitter, Lenster or LinkedIn.

Happy Learning 🙌🏻

Keep Building 🧱🚀