ismp-solidity-v0

This is the SDK for cross-chain messaging. Requests are sent to the Hyperbridge coprocessor, which then routes the request to the appropriate destination chain. Hyperbridge also performs request aggregation, allowing for a batch of requests to be sent to a destination chain with a shorter proof. As a client of the bridge network, you don't need to worry about any of this, as it is completely invisible to you. When making requests, you simply specify your destination chain, and Hyperbridge takes care of everything else.
To dispatch requests, you will use the IsmpHost contract, which exists on this chain. This host contract provides the IIsmp interface. It's important to note that Hyperbridge is a general message passing bridge, which means it allows for passing arbitrary bytes in the request.body field, which is delivered unmodified to the destination module.

Sending Requests

To dispatch POST requests, use the IIsmp.dispatch method. This method commits your request to storage and emits a PostRequestEvent, allowing it to be picked up by a relayer and routed to Hyperbridge. In version 0, we are relaying requests for all applications that are trying out Hyperbridge. However, in future versions, applications will need to run their own relayers or make an additional call to our relayer contract to pay for gas on the destination chain. In subsequent releases, there will be a market for relayers who wish to relay on behalf of applications and get paid for their services.
Here’s an example call that uses ismp for arbitrary message passing.
solidity
DispatchPost memory post = DispatchPost({ body: params.message, dest: params.dest, timeout: params.timeout, to: abi.encodePacked(address(params.destination)), // unused for now gaslimit: params.gaslimit }); IIsmp(hostAddress).dispatch(post);
Body
From the perspective of the ISMP protocol & hyperbridge, an opaque sequence of bytes to be delivered, unmodified to the destination module, on the destination chain.
Dest
4-byte Identifier for the destination chain. The StateMachine library, can be used to generate this identifier the desired destination chain. You can find the library and its methods here.
Timeout
This value represents the duration in seconds for which this request is valid. The validity period starts from the moment the transaction is made on-chain and is evaluated from the perspective of the sending chain. If the timeout elapses, the request can no longer be delivered and will be rejected by the IIsmpHost on the destination chain.
To
Destination module identifier in bytes. This would be the smart contract address. This contract should be an instance of the IIsmpModule on the destination state machine, otherwise the request will fail.
Gaslimit
Maximum gas for the request to be executed on the destination chain, this will be used in concert with an on-chain relayer marketplace for applications that do not want to self-relay. Where applications can pay to any relayer contract for execution on the sending chain with the provided gaslimit. If this limit is insufficient for execution, the request will fail, and needs to be resent with a higher limit.

Receiving Requests & Responses

The IIsmpHost serves as an entry point for incoming requests and responses. For now it’s contract addresses are different depending on what chain you’re on. We’re working on making this the same across all chains.
To receive responses, you need to implement the IIsmpModule interface. Unfortunately, this is a requirement. Without it, the IsmpHost will not be able to callback your contract with the incoming requests & responses. It’s important that only the IIsmpHost is allowed to call these methods otherwise anyone can call them!
solidity
pragma solidity 0.8.17; contract YourModule is IIsmpModule { address private ISMP_HOST; modifier onlyIsmpHost() { require(msg.sender == ISMP_HOST, "Only the host should be able to call these methods"); } function onAccept(PostRequest memory request) external onlyIsmpHost {} function onPostResponse(PostResponse memory response) external onlyIsmpHost {} function onGetResponse(GetResponse memory response) external onlyIsmpHost {} function onPostTimeout(PostRequest memory request) external onlyIsmpHost {} function onGetTimeout(GetRequest memory request) external onlyIsmpHost {} }
For v0, only POST request & responses are supported. The next release will enable GET requests & responses as well as cross-chain view function calls.

What can you build with this?

Here are examples of a few potential applications that can be built with this: