Integration Guide
Last updated
Last updated
When initiating omni-chain on the source chain contract, it is necessary to introduce the IMOSV3 interface. You can directly import the protocol using the following code, but make sure to install the protocol with 'npm install @butternetwork/omniservice
before usage.
Before initiating a cross-chain transaction, it is necessary to estimate the cross-chain messaging fee. The fee structure for omni-chain message can be referenced here .
The interface for estimating the fee is
toChain
- Target chain id, get here.
feeToken
- Token address that supports payment fee, native token is address(0)
.
Currently, the only supported is native token, and more tokens will be supported in the future.
gasLimit
- The gasLimit allowed to be consumed by an operation performed on the target chain.
When initiating a omni-chain request, in addition to the data you wish to execute across chains, we also provide various applicable scenarios for users to flexibly choose the most suitable method according to their own needs.
Check the structure of MessageData.
relay
indicates whether message processing is required on MAP Relay Chain.
If relay
is false, during the message passing through the relay chain (Mapo), no additional processing is done, and the message is directly sent to the target chain.
msgType
indicates different message
MESSAGE
allows for freely defined omni-chain messages. When they reach the target chain, the cross-chain messages are passed to the mapoExecute
method. You can define your own preferred checking methods and data processing in this method to complete the cross-chain message execution.
CALLDATA
requires the complete calldata
to be prepared on the source chain for execution on the target. OmniService contract should be granted permissions to execute the call.
target
is the contract address where the message will be executed upon reaching the target chain
payload
is the data intended for cross-chain transmission.
gasLimit
is the maximum gas limit allowed for execution on the target chain.
value
should currently be defaulted to 0; further details will be forthcoming.
After understanding the various options available for MessageData
, we can directly encode the assembled MessageData
and then call transferOut
to send the cross-chain request.
When message reaches the target chain, it will be executed according to the choice made during cross-chain initiation, and emit an event upon completion of execution. Depending on the msgType
chosen freely during cross-chain initiation, we will employ different handling methods on the target chain.
The MESSAGE
mode offers greater freedom and broader adaptability, but requires users to implement the following interfaces on the target chain.
If you want to facilitate the implementation of the mapoExecute
method, you can directly install the @butternetwork/omniservice
protocol and import the IMapoExecutor
interface using the following code:
The mapoExecute
method is flexible. We will pass the information from the source chain along with your custom message. You can freely define the validation rules, including decoding the message, among other things. This method is suitable for a wide range of scenarios.
The CALLDATA
mode involves preparing the calldata for execution on the target chain at the time of initiating the cross-chain request. The OmniService
will directly execute the call and then emit an event upon completion.
Of course, we also consider that there are many different chains currently. Because data cannot perfectly intercommunicate between chains, we have created the Butter Omnichain Service to accomplish this great feat. Each chain has its own characteristics, and occasional execution failures are inevitable. But don't worry, even if cross-chain execution fails, we will save the hash of the failed execution. You can retrieve the information for re-execution through the transaction logs, allowing you to correct the execution logic and attempt the cross-chain message execution again. For more details, please see below:
retryMessageIn
is flexible and can be called with any correct data for execution. It does not alter the cross-chain message, as we save the hash at the time of failure and will perform hash validation. It simply provides more opportunities for attempts, making cross-chain communication more free and seamless.
If relay
is true, the message will be processed on relay chain before forwarding to the target chain. Check for more details.
: MESSAGE type is flexible and highly extensible, making it suitable for handling various types of cross-chain messages. We highly recommend using this type.
: Of course, if the source chain cannot perfectly handle cross-chain information, you can set the relay attribute of MessageData to true. This way, during the cross-chain process, the relay chain can perform data processing or enhance the cross-chain data before continuing.
: When you can clearly and effectively determine the execution method on the target chain from the source chain, you can choose the CALLDATA type. This way, the target chain only needs to grant permission, making cross-chain execution straightforward.