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.