Skip to main content

Implementation Guide

A Hyperlane implementation for a new chain architecture is comprised of the following:

  1. Contracts: expose the interface for application developers to send and receive messages with
  2. Agents: operate the protocol by adding security and relaying messages
  3. Applications: applications that use the protocol and demonstrate its capabilities

Before getting started here, it is recommended to review the protocol documentation.

info

If you would like to dive deeper, check out some of the Hyperlane implementations that are currently available:

1. Contracts​

Below describes the onchain contract spec for the Hyperlane protocol. It uses solidity types for familiarity but everything should be generalizable to other languages.

  • address should be interpreted as the local chain's address type.
  • payable describes a function that allows callers to pass native tokens.
  • Ensure events are properly emitted for all important state changes.
  • Clearly document any deviations from the reference implementation and their rationale.

Some things to consider​

Byte representation:

  • Be aware that different chains may have different native types for representing bytes. For example, StarkNet uses felt252 for contract addresses, which may not fully accommodate 32-byte addresses used in other chains.
  • Implement proper conversion and validation mechanisms when dealing with cross-chain addresses.

Serialization:

  • Pay close attention to how message fields are serialized, especially for variable-length data like the message body.
  • Ensure that the serialization method used (e.g., abi.encodePacked equivalent) behaves consistently across different chain implementations.

Message​

The message is the core data structure used by the Hyperlane protocol. It is a packed data structure that contains all the information needed to route a message from one domain to another.

struct Message {
    // The version of the origin and destination Mailboxes
    uint8 version,
    // A nonce to uniquely identify the message on its origin Mailbox
    uint32 nonce,
    // Domain of origin chain
    uint32 origin,
    // Address of sender on origin chain
    bytes32 sender,
    // Domain of destination chain
    uint32 destination,
    // Address of recipient on destination chain
    bytes32 recipient,
    // Raw bytes of message body
    bytes body
}

Mailbox​

The mailbox is the entrypoint for developers to send and receive messages from. Make sure that localDomain is immutable to prevent unauthorized changes that could compromise cross-chain security.

Implementations:

info

In addition to default and custom hooks, Hyperlane introduces the concept of a Required Hook that is used for post processing of ALL dispatches. Make sure to call the required hook before the default or custom hook.

dispatch​

Dispatches a message to the destination domain and recipient.

function dispatch(
    // Domain of destination chain
    uint32 destination,
    // Address of recipient on destination chain as bytes32
    bytes32 recipient,
    // Raw bytes content of message body
    bytes body
) returns (
    // The message ID inserted into the Mailbox's merkle tree
    bytes32 messageId
);

Dispatches a message to the destination domain and recipient, and provides metadata for the default hook.

function dispatch(
    // Domain of destination chain
    uint32 destination,
    // Address of recipient on destination chain as bytes32
    bytes32 recipient,
    // Raw bytes content of message body
    bytes body,
    // Metadata used by the default post dispatch hook
    bytes defaultHookMetadata
) returns (
    // The message ID inserted into the Mailbox's merkle tree
    bytes32 messageId
);

Dispatches a message to the destination domain and recipient, and provides metadata for a custom hook to use instead of the default.

function dispatch(
    // Domain of destination chain
    uint32 destination,
    // Address of recipient on destination chain as bytes32
    bytes32 recipient,
    // Raw bytes content of message body
    bytes body,
    // Metadata used by the custom post dispatch hook
    bytes customHookMetadata,
    // Custom hook to use instead of the default
    IPostDispatchHook customHook
) returns (
    // The message ID inserted into the Mailbox's merkle tree
    bytes32 messageId
);

process​

Attempts to deliver message to its recipient. Verifies message via the recipient's ISM using the provided metadata.

function process(
    // Metadata used by the ISM to verify message.
    bytes metadata,
    // Byte packed message
    bytes message
);

latestDispatchedId​

Returns the latest dispatched message ID used for auth in post-dispatch hooks.

function latestDispatchedId() public view returns (bytes32);

Message Recipient​

A contract that wants to receive a message must expose the following handler.

function handle(
    // Domain of origin chain
    uint32 origin,
    // Address of sender on origin chain
    bytes32 sender,
    // Raw bytes content of message body
    bytes body
);

They may optionally specify a security module to verify messages before they are handled.

function interchainSecurityModule() returns (address);
info

After implementing these three contracts, you can reach your first milestone to test, mocking a message transfer, by calling a Mailbox's dispatch function to send a message to a recipient and assert that the recipient received the message. See a Foundry test case here.

Interchain Security Module​

Interchain security modules are used to verify messages before they are processed.

moduleType​

Returns an enum that represents the type of security model encoded by this ISM.

enum ModuleType {
    UNUSED,
    ROUTING,
    AGGREGATION,
    LEGACY_MULTISIG,
    MERKLE_ROOT_MULTISIG,
    MESSAGE_ID_MULTISIG,
    NULL, // used with relayer carrying no metadata
    CCIP_READ
}

function moduleType() returns (ModuleType);

Relayers infer how to fetch and format metadata from this type.

verify​

Defines a security model responsible for verifying interchain messages based on the provided metadata.

function verify(
    // Off-chain metadata provided by a relayer, specific
    // to the security model encoded by the module
    // (e.g. validator signatures)
    bytes metadata,
    // Hyperlane encoded interchain message
    bytes message
) returns (
    // True if the message was verified
    bool success
);
info

Static module management - Our Solidity implementation defines MultisigISMs as static and part of the bytecode which might not be possible in other chains. You may need to implement dynamic modules for the ISM instead.

Validator Announce​

Validators announce their signature storage location so that the relayer can fetch and verify their signatures.

announce​

Announces a validator signature storage location

function announce(
    address validator,      // The address of the validator
    string storageLocation, // Information encoding the location of signed checkpoints
    bytes signature         // The signed validator announcement
) external returns (bool);

getAnnouncedStorageLocations​

Returns a list of all announced storage locations

function getAnnouncedStorageLocations(
    address[] _validators   // The list of validators to get storage locations for
) external view returns (
    string[][]              // A list of registered storage metadata
);

Multisig ISM​

Implements a security module that checks if the metadata provided to verify satisfies a quorum of signatures from a set of configured validators.

Metadata​

To be used with the MESSAGE_ID_MULTISIG module type implementation in the relayer.

The metadata must be formatted as follows:

struct MultisigMetadata {
    // The address of the origin mailbox
    bytes32 originMailbox;
    // The signed checkpoint root
    bytes32 signedCheckpointRoot;
    // The concatenated signatures of the validators
    bytes signatures;
}

validatorsAndThreshold​

Returns the set of validators responsible for verifying message and the number of signatures required.

Can change based on the content of _message

function validatorsAndThreshold(
    // Hyperlane formatted interchain message
    bytes message
) returns (
    // The array of validator addresses
    address[] validators,
    // The number of validator signatures needed
    uint8 threshold
);
info

After implementing the MultisigISM, you reach the second milestone to test that your Mailbox only processes after a recipient's ISM returns true. You can test that with a TestISM that you can statically set to accept or reject any message. See a Foundry test case here.

Interchain Gas Paymaster​

The gas paymaster is used to pay for the gas required in message processing on the destination chain. This is not strictly required if the relayer is willing to subsidize message processing.

warning

Implement robust checks for sufficient gas payment, considering chain-specific token handling. Our solidity implementation charges native message value but for other chains, you may need to charge a specific token and scale the gas overhead and tokenExchangeRate accordingly.

payForGas​

Deposits msg.value as a payment for the relaying of a message to its destination chain.

warning

Although you can specify a refundAddress, overpayment may not be refunded to the message sender if you are composing hooks together.

function payForGas(
    // The ID of the message to pay for.
    bytes32 messageId,
    // The domain of the message's destination chain.
    uint32 destination,
    // The amount of destination gas to pay for.
    uint256 gasAmount,
    // The local address to refund any overpayment to.
    address refundAddress
) payable;

GasPayment​

Emitted when a payment is made for a message's gas costs.

event GasPayment(
    bytes32 messageId,
    uint32 destinationDomain,
    uint256 gasAmount,
    uint256 payment
);

DestinationGasConfigSet​

Emitted when the gas oracle for a remote domain is set.

event DestinationGasConfigSet(
    uint32 remoteDomain, // remote domain
    address gasOracle,   // gas oracle
    uint96 gasOverhead   // destination gas overhead
);

2. Agents​

Below describes the agent spec for a new chain implementation. The rust implementations hope to support all chains, but the spec is intended to be chain agnostic.

Message Indexing​

All agents must index messages from the origin mailbox. In the solidity mailbox, we emit an event for each message dispatched. Other chains may have different ways of surfacing this information, but the agent must be able to get message content reliably and with consistent ordering -- see the message indexer trait.

Validator​

In addition to indexing messages dispatched from the mailbox, validators produce attestations for the messages they observe to be used on the destination chain for security.

Checkpoint​

Validators produce attestations called checkpoints from the Mailbox which commit via merkle root to all dispatched message IDs.

pub struct Checkpoint {
    /// The mailbox address
    pub mailbox_address: H256,
    /// The mailbox chain
    pub mailbox_domain: u32,
    /// The checkpointed root
    pub root: H256,
    /// The index of the checkpoint
    pub index: u32,
}

Validators use the latest checkpoint method on the mailbox trait to get the latest checkpoint from the mailbox and submit signatures to some highly available storage using the checkpoint syncer trait.

Checkpoint with Message ID​

Validators use indexed messages to join the checkpoint with the corresponding message ID emitted from the mailbox.

pub struct CheckpointWithMessageId {
    /// existing Hyperlane checkpoint struct
    #[deref]
    pub checkpoint: Checkpoint,
    /// hash of message emitted from mailbox checkpoint.index
    pub message_id: H256,
}

They also publish these augmented checkpoints on their syncer.

tip

You can test your validator by configuring it with a chain with the above contracts and observe that it creates valid signatures.

Relayer​

In addition to indexing messages dispatched from the mailbox, a relayer processes messages on the destination chain. This requires building metadata that satisfies the message recipient's ISM verification requirements, and signing transactions that process the message on the destination mailbox.

Metadata Builders​

Each module type implies a different metadata format for message verification to succeed. A Relayer will need each module trait (eg multisig) to be implemented.

Message Processor​

The relayer will attempt to process messages on the destination mailbox (see message processor). If

  • the message recipient ISM returns an unknown module type
  • module type is known but metadata fails to verify
  • metadata verifies but dry running (gas estimation) message processing fails

then the message will be kicked to an exponential backoff retry queue. The relayer relies on implementations of the mailbox and ism traits for these checks.

Gas Payment Enforcement​

The Relayer may also require gas payment for a specific message ID on the origin chain before processing the message on the destination chain. To do this, they must have an IGP deployed with their address set as beneficiary and index gas payment events. See gas payment enforcement trait. We recommend to start with no gas payment enforcement policy and then gradually support more restrictive ones.

Testing​

Once you have implemented an MVP of the relayer, you should create an end-to-end test that:

  1. Spins up local origin and destination chains.
  2. Deploys your contracts onto both chains.
  3. Run validators for the origin chain.
  4. Run a relayer between both chains.
  5. Observe that upon dispatch of a message of the origin chain, the validator observes the message, creates a signature and the relayer appropriately processes your message via the ISM that specifies the validator on the destination chain.

See this end-to-end test on the Rust codebase for inspiration.

tip

After validating the agents with local end-to-end tests, it is recommended that you also run end-to-end tests with real testnets.

3. Applications​

Warp Routes​

Token router application that routes tokens between domains on demand.

transferRemote​

Transfers amountOrId token to recipient on destination domain.

function transferRemote(
    // The Domain of the destination chain.
    uint32  destination,
    // The address of the recipient on the destination chain.
    bytes32 recipient,
    // The amount or identifier of tokens to be sent to the remote recipient.
    uint256 amountOrId
) returns (
    // The identifier of the dispatched message.
    bytes32 messageId
);

Transfer Message​

To be interoperable with Warp Routes on other chains, the body of a transfer message must be a byte packed TransferMessage struct.

struct TransferMessage {
    // The recipient of the remote transfer
    bytes32 recipient;
    // An amount of tokens or a token identifier to be transferred
    uint256 amountOrId;
    // Optional metadata e.g. NFT URI information
    bytes   metadata;
}