megabytemegabyte

A-Z of Hyperlane

•8 min read
Cover Image for A-Z of Hyperlane

gm gm gm!!!

Even with the vast network of blockchain, with 1000s of nodes and 100s of chains (L1, L2, L3....) the users are getting restricted in utilizing the complete potential of the decentralized network. Reason? Some application works on ETH, some on Polygon, some on Gnosis, and so on and on!

In the ever-growing network of Blockchain Networks, or different blockchain networks developers are required to 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.

In this article, we are going to learn almost all about Hyperlane and 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⛓

Read in short here:

https://twitter.com/megabyte0x/status/1686628441888804864

"Permissionless" means no one requires any sort of permission from the Hyperlane Team to use Hyperlane SDK, Contracts, or even while deploying on new chains as I did👇🏻

https://twitter.com/megabyte0x/status/1651938319570456577

"Interoperability" means sending between different chains. Imagine initiating a transaction on ETH on certain 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

You can either learn about all of them in deep one by one or go directly to the last section for a quick view with examples.

Mailbox

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

You can also check this out:

https://twitter.com/megabyte0x/status/1686979539291762688

Mailbox is the middle-man [but CODE] which helps devs to connect between different chains and leverage it to build something out of the box.

Their contracts are required to be present on every chain supported by Hyperlane.

Mailbox Interface has two functions that are required to be present in the cross-chain contracts, those are the following:

  • dispatch

  • process

dispatch

This is used to send the data from the origin chain to the destination chain.

It accepts several params:

  • _destinationDomain (uint32): domain for the destination chain as per the Hyperlane Docs or the deployer.

  • _recipient Address (bytes32): address of the recipient.

  • _messageBody (bytes): Raw bytes content of message body

It works by following these steps:

  • First, check whether the message length exceeds the 2KiB length.

  • It formats the _messageBody using Message.sol according to the needs.

  • Message.sol provides a function .id() that returns keccak256(_message). This _id is saved into the "incremental" Merkle Tree.

  • The Merkle Tree is used to verify fraud proofs in Hyperlane's Staking and Slashing Protocol.

process

This is used on the destination chain to receive the message.

It accepts the following two params:

It works by following these steps:

  • _message is the formatted message from the Message.sol

  • _metadata is the specific Arbitrary metadata provided by the relayer used by ISM to verify _message

  • Then it checks whether this _id is in the array of delivered messages or not. If it is, then it reverts with "delivered" else add it to the array of delivered messages.

  • Then it gets the ISM Address for the recepientAddress.

  • If the recipient has defined a specific ISM it returns that else uses the default ISM for the chain.

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

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

Learn more about Mailbox here.

Interchain Security Modules

ISM verifies the particular messages delivered on the destination chain are actually sent from the origin chain.

You can also check this out:

https://twitter.com/megabyte0x/status/1687471625724383232

ISM is used in the Mailbox, to verify the message Mailbox received from the relayer before executing txns.

Developers can define specific ISM for their applications or can use pre-built ISMs provided by the team, using the ISpecifiesInterchainSecurityModule.sol

ISMs are:

Image

Configurable
ISM can be configured as per the application requirements, with all the additional parameters required by the application.
Composable
Devs can use more than one ISM in their application to increase security and work according to the consensus of the chain.
Customizable
Devs can use IInterfaceSecurityModule.sol and can build the whole ISM according to their needs.

Each ISM has two main components:

Image

verify

Image

It takes two params:

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

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

moduleType

It signals relayers about the type of module to be included in the metadata.

Implementation

Implementation of a specific ISM in an application is done by using the ISpecifiesInterchainSecurityModule.sol

Image

There are different prebuilt ISMs provided by the team:

  • MultisigISM

  • RoutingISM

  • AggregationISM

  • OptimisticISM

  • WormholeISM

  • HookISM

Learn more about ISM here.

Interchain Gas Paymaster

On-chain API to pay Relayer(s) to deliver the message on the destination chain.

You can also refer to this:

https://twitter.com/megabyte0x/status/1687818750635261954

An interchain message requires two transactions:

Image

  1. Txn on the origin chain to send the message.

  2. Txn on the destination chain to receive the message.

When users send the message from The Mailbox on the Origin Chain to the Relayer, they also need to send the gas fee amount to the Relayer to cover the fee on the Destination Chain. This gas fee is calculated with IGP and paid to the Relayer simultaneously.

Image

IGP Provides us with two functions:

Image

  • payGasFor()

  • quoteGasPayment()

payForGas

Image

It takes these params:

  • _messageId

  • destinationDomain

  • gasAmount

  • refundAddress

When the user sends the above parameters, the following are the next steps:

Image

  • It first gets the gas fee required on Destination Chain by calling quoteGasPayment()

  • If the required amount is less than the msg.value, then go forward else revert.

  • It calculates the overpaid amount.

  • If the overpaid amount is more than 0, then send the amount to the refundAddress, else move forward.

  • Emits Event of GasPayment.

quoteGasPayment

Image

It takes the following parameters:

  • _destinationDomain

  • _gasAmount

When it receives the above parameters, it follows like this:

Image

  • It first gets the token exchange rate and the gas price for the Destination Chain.

  • Then it calculates the gas fee on the Destination Chain.

  • At last, calculates the number of native tokens required on the Origin Chain and returns it.

Complete Workflow

This is the complete workflow of Interchain Gas Payment on the Origin Chain to deliver the message on the Destination Chain:

Learn more about Interchain Gas Payment here.

Agents

Off-chain actors that power Hyperlane.

You can also refer to this:

https://twitter.com/megabyte0x/status/1688514083287678977

There are three Agents in Hyperlane Protocol:

Image

Since Hyperlane is a Permissionless Interoperability protocol, you can take the role of any agent and contribute to the security of the network.

Validators

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

Image

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

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

Relayers

Relayers are responsible for delivering messages to the recipient.

Image

It works as follows:

  1. observe Mailbox for the 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 make configurations for the messages they want to deliver:

  • A sender/recipient whitelist.

  • A sender/recipient blacklist

  • Getting paid on-chain after delivering.

The relayers get incentivized during the time they process the message with the gas fee.

Watchtowers

They are the snipers in the Hyperlane protocol. They look for frauds and convicts (malicious validators) happening in the validator network and kill them by slashing the validator stake. Watchtowers are incentivized when they submit the correct report of fraud.

Learn more about Agents here.

Story Time

Jim wants to send an arbitrary message (data) to Dwight from Polygon zkEVM to Ethereum with Hyperlane.

Image

You can also refer to this:

https://twitter.com/megabyte0x/status/1688875226745253888?s=20

The following steps will be required to transfer the data:

Image

  1. Jim sends the message data, recipient address, and chain where the recipient is to the Polygon zkEVM Mailbox contract.

  2. Mailbox emits an event that gets indexed.

  3. Validators sign the latest checkpoint.

  4. The signature gets stored in the database.

  5. During the above process, Jim pays the gas fee using IGP.

  6. When the gas fee is transferred to the Relayer.

  7. The relayer sends the message and metadata on the ETH Mainnet.

  8. The messageBody sent to ISM to get verified.

  9. The message gets delivered to Dwight on the ETH Mainnet.

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 🧱🚀