Hyperlane from A to Z
Permissionless Interoperability Layer for web3
Table of contents
- What is Hyperlane?
- What is a Hyperlane Mailbox?
- What are Hyperlane Interchain Security Modules?
- What is the Hyperlane Interchain Gas Paymaster?
- What are Hyperlane Agents?
- Example: How to Send a Message from Polygon zkEVM to Ethereum?
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 🚀
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:
Interchain Security Module (ISM)
Interchain Gas Payment (IGP)
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,
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:
It checks whether the message length exceeds the 2KiB length.
It formats the
Message.sol provides an
idfunction that returns a KECCAK256 hash of
This hash becomes the
_idand is saved into an incremental Merkle tree.
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:
_messageargument is the one the
dispatchfunction formatted with
_metadataargument is metadata provided by the ISM relayer to verify
The function checks whether the
_idis in the array of delivered messages. If it is, it reverts with
delivered; if not, it adds it to that array.
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.
It uses the ISM address to verify messages received by the Mailbox.
After verification, it emits the message received event using the
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
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:
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:
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:
How does the
payForGas Function Work?
This function takes four parameters:
When the user sends the above parameters, the following steps happen:
The function gets the gas fee required on the destination chain by calling
quoteGasPayment(). It reverts if the required amount exceeds the
It calculates the overpaid amount; if it exceeds 0, it sends the amount to the
It emits a GasPayment event.
How does the
quoteGasPayment Function Work?
This function takes the following parameters:
_gasAmount. It works like this:
The function gets the token exchange rate and the gas price for the destination chain.
It calculates the gas fee on the destination chain.
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
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:
Observe Mailbox for new messages.
Use Mailbox to get the ISM implemented by the recipient.
Aggregate the metadata for the ISM.
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.
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:
Jim sends the message data, recipient address, and destination chain to the Maibox contract on the Polygon zkEVM chain.
The Mailbox emits an event that gets indexed.
Validators sign the latest checkpoint.
The signature gets stored in the database.
Jim pays the gas fee using IGP during the process.
When the relayer receives the gas fee, it relays the message and metadata on the Ethereum chain.
messageBodyis sent to the ISM for verification.
The message gets delivered to Dwight on the Ethereum chain.
Whoo!!🤩 This was quite a lot of workflow and solidity contracts understanding.
Happy Learning 🙌🏻
Keep Building 🧱🚀