Cross-chain Actions Integration Guide
This guide provides technical instructions for bundling a bridge with user actions. The integration process is simple and consists of three steps:
Craft the message that is the set of transactions to execute on the destination
Request quotes from Across GET /suggested-fees API, passing in the
message
parameter defined aboveInitiate a deposit by using data returned from Across API to call functions on Across smart contracts, specifying a
message
(set of transactions to execute on the destination) and appending your integration ID in calldata.
Executing Destination Actions
At a high level, the system works as follows:
End-user (or intermediate contract) includes a message field in the deposit transaction.
To be repaid for the fill, the relayer is required to include the same message field in their fill.
When this message field is non-empty and the recipient is a contract, the
SpokePool
calls a special handler function on the recipient handler contract with the message (and a few other fields).This function can do anything, meaning application-specific actions can be executed atomically
This integration requires a handler contract on the destination to "handle" (execute) the transactions specified in the message
. There are two approaches to implementing this functionality with respect to handler contract.
(recommended) Use our already-deployed and audited generic "multicall" handler contract
Build and implement your own custom handler contract
Each of the below guides provide instruction and examples for the 3 integration steps above.
Using the Generic Multicaller Handler ContractThe recommended way is to use our already-deployed and audited generic "multicall" handler contract. When this contract is set as the recipient address, this contract will atomically execute all contract calls specified in the deposit's message
.
If your use case requires additional customization or complexity, you can build your own custom handler contract to execute the contents provided in the deposit's message
.
How to Decide
The tradeoff of using the generic multicall handler contract is that the complexity is encountered when crafting the message, which must be a correctly-encoded Instructions
object. Once the message is formed correctly, you don't need to write any more code.
On the other hand, when using a custom handler contract, you'll need to implement a custom handleV3AcrossMessage
function and deploy a new contract, but creating the deposit message
is trivial.
If you have further questions or suggestions for this guide, please send a message to the #developer-questions
channel in the Across Discord.
Append Unique Identifier to CallData
In order to track the origination source for deposits for analytics, debugging and support purposes we request all integrators to append a delimiter of 1dc0de
and a unique identifier provided by our team to the deposit transaction call data.
Here is an example of depositV3
call data with 1dc0de
delimiter and f001
unique identifier appended.
Do NOT pass delimiter + identifier to any depositV3
param, including the message
param. Only append to call data of the transaction.
Do NOT use f001
identifier in your implementation, see below on how to request your unique ID.
Request your unique identifier in our shared communication channel (TG, Slack, etc), if already set up, or reach out to [email protected]. Please do not use any other identifier other than the one provided to you.
UI Guide
See Cross-chain Actions Integration Guide for recommended UI and UX patterns.
Last updated