Message Bridging
Last updated
Last updated
Projects can send messages across chains by deploying their own Message Controllers on each chain where they want to send or receive messages, using Lucid. These controller contracts are deployed and managed exclusively by the project; Lucid has no control over them.
Message Controllers are bridge-agnostic — they use Adapter contracts to send and receive messages across chains via one or more bridges. As Lucid adds support for new bridges, your existing Controllers automatically gain access to new ecosystems — without requiring any contract changes.
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
Among others
When a message is received by a Message Controller on the destination chain, the sender (i.e., msg.sender) must be verified — only a Bridge Adapter is allowed to call the receiveMessage function and register a message.
There are two ways for projects to specify which contracts are allowed to call this function:
The Registry is a contract deployed and maintained by Lucid on every chain. It serves two primary purposes:
It acts as a registry of local adapters on the same chain.
It aggregates available chains and adapters accessible from the current chain.
Message Controllers can be configured to use a Registry to validate whether a calling contract is a local bridge adapter. This is a simple option for projects that want to accept messages from any Bridge Adapter deployed by Lucid.
For a more advanced setup, projects can whitelist specific Bridge Adapters they trust to deliver messages to the Controller contracts. An account with the Admin Role (see below) can set and update the local adapters of the Controller contract at any time.
Message Controllers utilize an access control system with distinct roles. This ensures that only authorized accounts can perform specific actions within the contract, enhancing overall security.
This is the highest authority within the contract. Accounts with this role can grant or revoke any role — including the admin role itself. Admins have the following privileges:
Grant or revoke the Message Originator role
Pause or unpause the contract (i.e., temporarily stop sending, resending, or executing received messages)
Update the timelock delay for message execution
Update the vetoer address, which can cancel message execution while it's in the timelock period
Add or remove Message Controller contract addresses on other chains — enabling or disabling cross-chain messaging with those chains
Update the local Registry address
Update the list of local Adapters
Accounts with this role can initiate the sending of messages from the Message Controller, which are then relayed to other chains.
An account with the Vetoer role can block the execution of a received message during the timelock period. Only one vetoer can exist per Message Controller contract per chain.
Message Controller contracts are designed to be upgradeable using OpenZeppelin’s Proxy Upgrade pattern. This enables upgrades to the contract logic without compromising its stored state.
The initial implementation contract is created and deployed by Lucid. However, the Proxy Admin — set and controlled by the Project — has full authority to upgrade the contract to newer versions as they are released by Lucid in the future.
For detailed instructions on how to call each function, please refer to the relevant documentation .
When a Message Controller is deployed using the Lucid App, a Pausable role is automatically assigned to , — Lucid’s on-chain smart contract monitoring partner. Hypernative is responsible for pausing contracts in case of detected malicious activity or potential hacks.