Multi-Bridge Message and Asset Transfers

Multi-Bridge Module: Cross-Chain Messaging and Asset Transfers

The Multi-Bridge module in Lucid enables users to perform cross-chain messaging for various purposes, including contract updates and governance proposals. Additionally, it offers the ability to transfer assets, specifically governance tokens, across chains using multiple bridges.

Developer related information about Message Bridging

Introduction

Projects can send messages across chains by deploying via Lucid their own Message Controllers in every chain they want to send or receive a message. These controllers contracts are deployed and controlled exclusively by the Project, and Lucid has no control over them.

Message Controllers are bridge-agnostic, meaning they leverage Adapter contracts to relay or receive messages across chains using a single or multiple bridges. As new Adapter contracts are created and deployed by Lucid to support new chains and new bridges, existing Message Controllers can use these new Adapters to access new ecosystems.

Message Controller contracts also incorporate several security features, such as whitelisted message originators, a consensus mechanism for received messages, timelock and veto functionality before message execution, pausability, amongst others.

Security model on message receipt

When a message is received by a Message Controller on the destination chain, the sender (or msg.sender ) of the message needs to be verified, as only a bridge Adapter is allowed to call the receiveMessage function and register a message. There are two ways for projects to specify the Adapter contracts that are allowed to call this function.

Roles and Permissions

Message Controllers utilise an access control system, with different roles. This ensures that only authorized accounts can perform specific actions within the contract, enhancing security.

Admin Role (DEFAULT_ADMIN_ROLE)

This is the highest authority within the contract. Accounts with this role can grant and revoke any role, including the default admin role itself. Admins have the following privileges:

• Grant or revoke accounts with the Message Originator role

• Pause/Unpause the contract (temporarily stop sending and resending messages, executing received messages)

• Update the timeock delay for message execution

• Update the vetoer address that can cancel message execution while on timelock

• Add/remove message controller contract addresses in other chains, hence allow the sending and receipt of messages from & to this new chain

• Update the local Registry address (TODO: Link)

• Update the local Adapters.

For more details on how to call each function please check: Admin Functions

Message Originator Role (MESSAGE_ORIGINATOR_ROLE)

Accounts with this role can initiate the sending of messages from the Message Controller which are then relayed to other chains.

Vetoer

An account with the vetoer role can block the execution of a message received in the destination chain, while the message is within the timelock period. There can only exist a single vetoer per Message Controller contract in a chain.

Upgradeability

Message Controller contracts are designed to be upgradeable. It uses the OpenZeppelin's Proxy Upgrade pattern, allowing the contract to be upgraded over time without compromising its state. The initial implementation contract was created and deployed by Lucid, however the Proxy Admin which is set and controlled by the Project, can choose to upgrade to a newer version as these are released by Lucid in the future.

Follow these steps to use this module effectively:

Step 1: Select an Organisation

1. Navigate to the Organisations menu from the sidebar.

2. Choose your desired organisation and click the View button under the Multi-Bridge module.

Step 2: Add Transaction

1. After selecting the Multi-Bridge module, you will be directed to the Transaction History screen. Here, you can view all past transactions.

2. To initiate a new transaction, click the Add Transaction button on the top-right corner of the screen.

Step 3: Add Action

What are Actions and Sub-Actions?

The Actions and Sub-Actions feature in Lucid is designed to facilitate cross-chain operations, such as interacting with smart contracts deployed on multiple chains, within a single transaction. This process is particularly useful for tasks like contract updates or governance actions across chains.

1. Actions: Represent a single high-level process. For example, targeting a smart contract across multiple chains. Actions are ideal when you want to configure or change the chains/bridges involved in cross-chain messaging or token transfers.

2. Sub-Actions: Nested under Actions, these define the specific tasks to be executed, such as targeting a particular contract on a specific chain. Each Sub-Action shares the same chain and bridge configurations defined by its parent Action.

Custom Action and Transfer Action

When you click Add Action, you are presented with two options: Custom and Transfer.

1. Custom Action

• Custom Actions are designed for cross-chain messaging and contract interactions, such as:

• Upgrading contracts.

• Making governance-related updates or proposals.

• These actions allow you to target contracts deployed on multiple chains, ensuring consistent updates using the configured chains and bridges.

2. Transfer Action

• Transfer Actions are used to transfer the organisation’s governance token or other supported assets across chains.

• These actions are part of the multi-bridge transaction flow and are ideal for transferring assets when specific chain and bridge configurations are required.

• This provides a secondary way to transfer assets besides the Bridge Portals module.

Step-by-Step Guide

Step 1: Initiating an Action

• Begin by creating an Action to define the operation you want to perform.

• For instance, if you want to interact with a smart contract deployed across multiple chains, start by creating an Action that specifies this purpose.

Step 2: Adding Sub-Actions

• Within the Action, add one or more Sub-Actions.

• Sub-Actions allow you to target specific contracts on individual chains.

• Example: You can upload an ABI file for the contract to define the functions you want to call.

• Add the contract addresses (e.g., for Arbitrum or other chains). Ensure the address corresponds to the deployed contract on the respective chain.

Step 3: Setting Chains and Bridges

• For each Sub-Action, specify the target chain (e.g., Ethereum, Arbitrum) and the bridge you want to use for the interaction.

• Bridges enable cross-chain communication to execute your defined Sub-Actions.

Step 4: Customising Sub-Action Details

For updates or messaging:

• Enter any necessary parameters or data in the text fields (e.g., function inputs).

For transfers:

• Provide details like sender/receiver addresses and the token value.

Step 5: Exporting the Action

• Once all Sub-Actions are configured, click Export.

• This generates the transaction data.

Final Step: Executing the Safe Transaction

• After exporting the data, you need to execute the transaction in a Safe:

1. Create a new Safe: If no Safe exists, you can create one.

2. Import an existing Safe: Alternatively, import an already configured Safe.

1. On the next screen, click the Add Action button.

2. You will be presented with two options:

• Custom: Select the Custom option to enable cross-chain messaging for purposes like updating contracts or governance proposals.

• Transfer: Select the Transfer option if you want to transfer the organisation’s governance tokens across chains.

Custom Option (to enable cross-chain messaging for purposes like updating contracts or governance proposals)

1. Select the Custom option to enable cross-chain messaging for purposes like updating contracts or governance proposals.

2. In the Custom setup:

• Enter the Target Contract Address.

• Upload the contract’s ABI file.

• Select the chains and bridges you want to use for the message transfer.

• Set the Consensus Threshold (e.g., 2 out of 2 for bridge approvals).

1. Once all required fields are completed, you can proceed to the next step.

Transfer Option (to transfer the organisation’s governance tokens across chains)

1. Select the Transfer option if you want to transfer the organisation’s governance tokens across chains.

2. In the Transfer setup:

• Enter the Sender Address.

• Specify the Receiver Address.

• Input the Value of tokens to transfer.

1. Choose the chain and bridge for the transfer under the Choose Chains and Bridges section.

Export

1. After completing the configuration for either the Custom or Transfer option, click on the Export button.

2. This will prepare the transaction for further processing and submission.

Copy the following information shown (These will be pasted in the Transaction Builder of Safe, see the final steps below)

• Target Address

• Value

• Data

Final Step: Executing the Safe Transaction

• After exporting the data, you need to execute the transaction in a Safe. Visit app.safe.global

1. Create a new Safe: If no Safe exists, you can create one.

2. Import an existing Safe: Alternatively, import an already configured Safe.

Paste the following information that you have copied during Step 6.

• Target Address

• Value

• Data