Skip to content

Receiving cross chain messages

To receive ISMP messages a contract must implement the IIsmpModule interface, this interface allows the IIsmpHost to dispatch verified cross chain messages to the contract for execution.

IIsmpModule

The required methods for the IIsmpModule is described in detail below:

onAccept

This is the callback method for new POST requests that have been verified by Hyperbridge. After the IHandler verifies the necessary proofs of this request, they are passed on to the host, which in turn calls the onAccept method for the intended modules. The arguments provided IncomingPostRequest holds both the request object itself and the account that initally called the Handler contract, this may be either a 3rd party relayer or a user who is self-relaying.

IIsmpModule's should ensure that is method is only callable by the host or risk critical vulnerabilies from unauthorized calls to this method by malicious actors. A modifier onlyHost is provided as part of the BaseIsmpModule for this.

onPostRequestTimeout

In the event that some initially dispatched request was unable to be delivered. Whether as a result of insufficient fees provided to the relayers, Or a revert during request execution on the destination chain. Then Hyperbridge allows this request to gracefully timeout, and this timeout can be reported back to the sending module on the source chain.

This callback is provided as a way to execute some logic in the event that some request times out. This can be seen as a catch block in a try/catch for cross-chain messages. Typically you'll want to revert any state changes that were made prior to dispatching the request.

onPostResponse

This is the callback method for new POST responses that have been verified by Hyperbridge. After the IHandler verifies the necessary proofs of this response, they are passed on to the host, which in turn calls the onPostResponse method for the intended modules. The arguments provided IncomingPostResponse holds both the resopnse object itself and the account that initally called the Handler contract, this may be either a 3rd party relayer or a user who is self-relaying.

IIsmpModule's should ensure that is method is only callable by the host or risk critical vulnerabilies from unauthorized calls to this method by malicious actors. A modifier onlyHost is provided as part of the BaseIsmpModule for this.

onPostResponseTimeout

In the event that some initially dispatched response was unable to be delivered. Whether as a result of insufficient fees provided to the relayers, Or a revert during response execution on the destination chain. Then Hyperbridge allows this response to gracefully timeout, and this timeout can be reported back to the sending module on the source chain.

This callback is provided as a way to execute some logic in the event that some response times out. This can be seen as a catch block in a try/catch for cross-chain messages. Typically you'll want to revert any state changes that were made prior to dispatching the response.

onGetResponse

This is the callback method for new GET responses that have been verified by Hyperbridge. After the IHandler verifies the necessary proofs of this response, they are passed on to the host, which in turn calls the onGetResponse method for the intended modules. The arguments provided IncomingGetResponse holds both the resopnse object itself and the account that initally called the Handler contract, this may be either a 3rd party relayer or a user who is self-relaying.

IIsmpModule's should ensure that is method is only callable by the host or risk critical vulnerabilies from unauthorized calls to this method by malicious actors. A modifier onlyHost is provided as part of the BaseIsmpModule for this.

onGetTimeout

In the event that some GET request is unable to be processed. Likely as a result of insufficient fees provided. Then Hyperbridge allows this request to gracefully timeout, and this timeout can be reported back to the sending module on the source chain.

This callback is provided as a way to execute some logic in the event that some request times out. This can be seen as a catch block in a try/catch for cross-chain messages. Typically you'll want to revert any state changes that were made prior to dispatching the request.

BaseIsmpModule

To make implementing the IIsmpModule easier, an abstract contract BaseIsmpModule is provided. This allows developers to inherit this contract and only override methods that they intend to use. This module only has one required method implementation, and it is a method that returns the IIsmpHost address.

pragma solidity 0.8.17;
 
import "@polytope-labs/ismp-solidity/interfaces/IIsmpModule.sol";
import "@polytope-labs/ismp-solidity/interfaces/IDispatcher.sol";
import "@polytope-labs/ismp-solidity/interfaces/Message.sol";
import "@polytope-labs/ismp-solidity/interfaces/IDispatcher.sol";
 
contract Example is BaseIsmpModule {
    event PostReceived();
 
    // IIsmpHost Address
    address private _host;
 
    constructor(address ismpHost) {
        _host = ismpHost;
    }
 
    function host() public view override returns (address) {
        return _host
    }
 
    function sendMessage(
        bytes memory message,
        uint64 timeout,
        address to,
        uint256 relayerFee
    ) public payable returns (bytes32) {
        DispatchPost memory post = DispatchPost({
            body: message,
            dest: StateMachine.arbitrum(),
            timeout: timeout,
            to: abi.encodePacked(to),
            fee: relayerFee,
            payer: tx.origin
        });
 
        return IDispatcher(host).dispatch{value: msg.value}(post);
    }
 
    function onAccept(IncomingPostRequest memory incoming)
        external
        override
        onlyHost
    {
        // decode request body
        // make any necessary state changes
        emit PostReceived();
    }
}

Security Considerations

  • Limit the caller of these functions to the IIsmpHost contract only. This prevents unauthorized messages from being executed.