ERC-5164

EIP-5164 specifies how smart contracts on one chain can message contracts on another. Transport layers, such as bridges, will have their own EIP-5164 implementations. This repository includes implementations for: Ethereum to Polygon, Ethereum to Optimism, and Ethereum to Arbitrum. All three use the 'native' bridge solutions.

The EIP is currently in the Review stage: https://eips.ethereum.org/EIPS/eip-5164

Feedback and PR are welcome!

How to use

To use ERC-5164 to send messages your contract code will need to:

• On the sending chain, send a message to the MessageDispatcher dispatchMessage or dispatchMessageBatch function
• Listen for messages from the corresponding MessageExecutor(s) on the receiving chain.

The listener will need to be able to unpack the original sender address (it's appended to calldata). We recommend inheriting from the included ExecutorAware.sol contract.

Note

For most bridges, you only have to call dispatchMessage or dispatchMessageBatch to have messages executed by the MessageExecutor. However, Arbitrum requires an EOA to process the dispatch. We will review this below.

How it works

1. A smart contract on the sending chain calls dispatchMessage or dispatchMessageBatch on the MessageDispatcher..
2. The corresponding MessageExecutor(s) on the receiving chain will execute the message or batch of Message structs. The address of the original dispatcher on the sending chain is appended to the message data.
3. Any smart contract can receive messages from a MessageExecutor, but they should use the original dispatcher address for authentication.

Note: this specification does not require messages to be executed in order

Dispatching

Dispatch a message

To dispatch a message from Ethereum to the L2 of your choice, you have to interact with the ISingleMessageDispatcher contract and call the following function.

/**
 * @notice Dispatch a message to the receiving chain.
 * @dev Must compute and return an ID uniquely identifying the message.
 * @dev Must emit the `MessageDispatched` event when successfully dispatched.
 * @param toChainId ID of the receiving chain
 * @param to Address on the receiving chain that will receive `data`
 * @param data Data dispatched to the receiving chain
 * @return bytes32 ID uniquely identifying the message
 */
function dispatchMessage(
  uint256 toChainId,
  address to,
  bytes calldata data
) external returns (bytes32);

• toChainId: id of the chain to which you want to dispatch the message
• to: address of the contract that will receive the message
• data: message that you want to be executed on L2

Dispatch a batch messages

To dispatch a batch of messages from Ethereum to the L2 of your choice, you have to interact with the IBatchedMessageDispatcher contract and call the following function.

/**
 * @notice Dispatch `messages` to the receiving chain.
 * @dev Must compute and return an ID uniquely identifying the `messages`.
 * @dev Must emit the `MessageBatchDispatched` event when successfully dispatched.
 * @param toChainId ID of the receiving chain
 * @param messages Array of Message dispatched
 * @return bytes32 ID uniquely identifying the `messages`
 */
function dispatchMessageBatch(uint256 toChainId, MessageLib.Message[] calldata messages)
  external
  returns (bytes32);

• toChainId: id of the chain to which you want to dispatch the message
• messages: array of Message that you want to be executed on L2

/**
 * @notice Message data structure
 * @param to Address that will be dispatched on the receiving chain
 * @param data Data that will be sent to the `to` address
 */
struct Message {
  address to;
  bytes data;
}

Example

MessageDispatcherOptimism _messageDispatcher = 0x3F3623aB84a86410096f53051b82aA41773A4480;
address _greeter = 0x19c8f7B8BA7a151d6825924446A596b6084a36ae;

_messageDispatcher.dispatchMessage(
  420,
  _greeter,
  abi.encodeCall(Greeter.setGreeting, ("Hello from L1"))
);

Code:

• script/bridge/BridgeToOptimismGoerli.s.sol
• script/bridge/BridgeToMumbai.s.sol

Arbitrum Dispatch

Arbitrum requires an EOA to submit a bridge transaction. The Ethereum to Arbitrum ERC-5164 MessageDispatcher dispatchMessage implementation is therefore split into two actions:

1. Message to MessageDispatcher dispatchMessage is fingerprinted and stored along with their messageId.
2. Anyone may call MessageDispatcher processMessage to send a previously fingerprinted dispatched message.

The processMessage function requires the same transaction parameters as the Arbitrum bridge. The Arbitrum SDK is needed to properly estimate the gas required to execute the message on L2.

/**
 * @notice Process message that has been dispatched.
 * @dev The transaction hash must match the one stored in the `dispatched` mapping.
 * @dev `_from` is passed as `callValueRefundAddress` cause this address can cancel the retryably ticket.
 * @dev We store `_message` in memory to avoid a stack too deep error.
 * @param _messageId ID of the message to process
 * @param _from Address who dispatched the `_data`
 * @param _to Address that will receive the message
 * @param _data Data that was dispatched
 * @param _refundAddress Address that will receive the `excessFeeRefund` amount if any
 * @param _gasLimit Maximum amount of gas required for the `_messages` to be executed
 * @param _maxSubmissionCost Max gas deducted from user's L2 balance to cover base submission fee
 * @param _gasPriceBid Gas price bid for L2 execution
 * @return uint256 Id of the retryable ticket that was created
 */
function processMessage(
  bytes32 messageId,
  address from,
  address to,
  bytes calldata data,
  address refundAddress,
  uint256 gasLimit,
  uint256 maxSubmissionCost,
  uint256 gasPriceBid
) external payable returns (uint256);

Arbitrum Dispatch Example

  const greeterAddress = await getContractAddress('Greeter', ARBITRUM_GOERLI_CHAIN_ID, 'Forge');

  const greeting = 'Hello from L1';
  const messageData = new Interface(['function setGreeting(string)']).encodeFunctionData(
    'setGreeting',
    [greeting],
  );

  const nextNonce = (await messageDispatcherArbitrum.nonce()).add(1);

  const encodedMessageId = keccak256(
    defaultAbiCoder.encode(
      ['uint256', 'address', 'address', 'bytes'],
      [nextNonce, deployer, greeterAddress, messageData],
    ),
  );

  const executeMessageData = new Interface([
    'function executeMessage(address,bytes,bytes32,uint256,address)',
  ]).encodeFunctionData('executeMessage', [
    greeterAddress,
    messageData,
    encodedMessageId,
    GOERLI_CHAIN_ID,
    deployer,
  ]);

...

  const { deposit, gasLimit, maxSubmissionCost } = await l1ToL2MessageGasEstimate.estimateAll(
    {
      from: messageDispatcherArbitrumAddress,
      to: messageExecutorAddress,
      l2CallValue: BigNumber.from(0),
      excessFeeRefundAddress: deployer,
      callValueRefundAddress: deployer,
      data: executeMessageData,
    },
    baseFee,
    l1Provider,
  );

  await messageDispatcherArbitrum.dispatchMessage(
    ARBITRUM_GOERLI_CHAIN_ID,
    greeterAddress,
    messageData,
  );

...

await messageDispatcherArbitrum.processMessage(
    messageId,
    deployer,
    greeterAddress,
    messageData,
    deployer,
    gasLimit,
    maxSubmissionCost,
    gasPriceBid,
    {
      value: deposit,
    },
  );

Code: script/bridge/BridgeToArbitrumGoerli.ts

Execution

Execute message

Once the message has been bridged it will be executed by the MessageExecutor contract.

Authenticate messages

To ensure that the messages originate from the MessageExecutor contract, your contracts can inherit from the ExecutorAware abstract contract.

It makes use of EIP-2771 to authenticate the message forwarder (i.e. the MessageExecutor) and has helper functions to extract from the calldata the original sender and the messageId of the dispatched message.

/**
 * @notice Check which executor this contract trust.
 * @param _executor Address to check
 */
function isTrustedExecutor(address _executor) public view returns (bool);

/**
  * @notice Retrieve messageId from message data.
  * @return _msgDataMessageId ID uniquely identifying the message that was executed
  */
function _messageId() internal pure returns (bytes32 _msgDataMessageId)

/**
  * @notice Retrieve fromChainId from message data.
  * @return _msgDataFromChainId ID of the chain that dispatched the messages
  */
function _fromChainId() internal pure returns (uint256 _msgDataFromChainId);

/**
 * @notice Retrieve signer address from message data.
 * @return _signer Address of the signer
 */
function _msgSender() internal view returns (address payable _signer);

Deployed Contracts

Mainnet

Ethereum -> Optimism

Network	Contract	Address
Ethereum	EthereumToOptimismDispatcher.sol	0xa8f85bAB964D7e6bE938B54Bf4b29A247A88CD9d
Optimism	EthereumToOptimismExecutor	0x890a87E71E731342a6d10e7628bd1F0733ce3296

Testnet

Ethereum Goerli -> Arbitrum Goerli

Network	Contract	Address
Ethereum Goerli	EthereumToArbitrumDispatcher.sol	0xBc244773f71a2f897fAB5D5953AA052B8ff68670
Arbitrum Goerli	EthereumToArbitrumExecutor	0xe7Ab52219631882f778120c1f19D6086ED390bE1
Arbitrum Goerli	Greeter	0xA181dE5454daa63115e4A2f626E9268Cc812FcC1

Ethereum Goerli -> Optimism Goerli

Network	Contract	Address
Ethereum Goerli	EthereumToOptimismDispatcher.sol	0x81F4056FFFa1C1fA870de40BC45c752260E3aD13
Optimism Goerli	EthereumToOptimismExecutor	0xc5165406dB791549f0D2423D1483c1EA10A3A206
Optimism Goerli	Greeter	0x50281C11B6a18d0613F507fD2E7a1ADd712De7D8

Ethereum Goerli -> Polygon Mumbai

Network	Contract	Address
Ethereum Goerli	EthereumToPolygonDispatcher	0xBA8d8a0554dFd7F7CCf3cEB47a88d711e6a65F5b
Polygon Mumbai	EthereumToPolygonExecutor	0x784fFd1E27FA32804bD0a170dc7A277399AbD361
Polygon Mumbai	Greeter	0x3b73dCeC4447DDB1303F9b766BbBeB87aFAf22a3

Development

Installation

You may have to install the following tools to use this repository:

• Yarn to handle dependencies
• Foundry to compile and test contracts
• direnv to handle environment variables
• lcov to generate the code coverage report

Install dependencies:

yarn

Env

Copy .envrc.example and write down the env variables needed to run this project.

cp .envrc.example .envrc

Once your env variables are setup, load them with:

direnv allow

Compile

Run the following command to compile the contracts:

yarn compile

Test

We use Hardhat to run Arbitrum fork tests. All other tests are being written in Solidity and make use of Forge Standard Library.

To run Forge unit and fork tests:

yarn test

To run Arbitrum fork tests, use the following commands:

• Fork tests to dispatch messages from Ethereum to Arbitrum:

  yarn fork:startDispatchMessageBatchArbitrumMainnet
  

• Fork tests to execute messages on Arbitrum:

  yarn fork:startExecuteMessageBatchArbitrumMainnet
  

Coverage

Forge is used for coverage, run it with:

yarn coverage

You can then consult the report by opening coverage/index.html:

open coverage/index.html

Deployment

You can use the following commands to deploy on testnet.

Ethereum Goerli to Arbitrum Goerli bridge

yarn deploy:arbitrumGoerli

Ethereum Goerli to Optimism Goerli bridge

yarn deploy:optimismGoerli

Ethereum Goerli to Polygon Mumbai bridge

yarn deploy:mumbai

Bridging

You can use the following commands to bridge from Ethereum to a layer 2 of your choice.

It will set the greeting message in the Greeter contract to Hello from L1 instead of Hello from L2.

Ethereum Goerli to Arbitrum Goerli

yarn bridge:arbitrumGoerli

It takes about 15 minutes for the message to be bridged to Arbitrum Goerli.

Example transaction

Network	Message	Transaction hash
Ethereum Goerli	dispatchMessage	0xfdb983cad74d5d95c2ffdbb38cde50fefbe78280416bbe44de35485c213909d5
Ethereum Goerli	processMessage	0x4effcda5e729a2943a86bd1317a784644123388bb4fd7ea207e70ec3a360ab60
Arbitrum Goerli	executeMessage	0x0883252887d34a4a545a20e252e55c712807d1707438cf6e8503a99a32357024

Ethereum Goerli to Optimism Goerli

yarn bridge:optimismGoerli

It takes about 5 minutes for the message to be bridged to Optimism Goerli.

Example transaction

Network	Message	Transaction hash
Ethereum Goerli	dispatchMessage	0xdaf3b8210294dc2414beefa14e56f47f638510031c4487443c58fd6a92c8f386
Optimism Goerli	executeMessage	https://goerli-optimism.etherscan.io/tx/0xa83813646e7978cea4f27b57688ce30e3622b135ca6c18489d0c8fa3ee297c5b

Ethereum Goerli to Polygon Mumbai

yarn bridge:mumbai

It takes about 30 minutes for the message to be bridged to Mumbai.

Example transaction

Network	Message	Transaction hash
Ethereum Goerli	dispatchMessage	0x856355f3df4f94bae2075abbce57163af95637ae9c65bbe231f170d9cdf251c9
Polygon Mumbai	executeMessage	0x78aff3ff10b43169ce468bf88da79560724ea292290c336cd84a43fdd8441c52

Code quality

Prettier is used to format TypeScript and Solidity code. Use it by running:

yarn format

Solhint is used to lint Solidity files. Run it with:

yarn hint

TypeChain is used to generates types for Hardhat scripts and tests. Generate them by running:

yarn typechain