Interop message passing tutorial

Superchain interop is in active development. Some features may be experimental.

Overview

This tutorial demonstrates how to implement cross-chain communication within the Superchain ecosystem. You’ll build a complete message passing system that enables different chains to interact with each other using the L2ToL2CrossDomainMessenger contract.

Show About this tutorial

Prerequisite technical knowledge

Intermediate Solidity programming
Basic TypeScript knowledge
Understanding of smart contract development
Familiarity with blockchain concepts

What you’ll learn

How to deploy contracts across different chains
How to implement cross-chain message passing
How to handle sender verification across chains
How to relay messages manually between chains

Development environment

Unix-like operating system (Linux, macOS, or WSL for Windows)
Node.js version 16 or higher
Git for version control

Required toolsThe tutorial uses these primary tools:

Foundry: For smart contract development
Supersim: For local blockchain simulation (optional)
TypeScript: For offchain code (for relaying messages manually)
Viem: For interactions with the chain from the offchain app

What You’ll Build

A Greeter contract that stores and updates a greeting
A GreetingSender contract that sends cross-chain messages to update the greeting
A TypeScript application to relay messages between chains

This tutorial provides step-by-step instructions for implementing cross-chain messaging. For a conceptual overview, see the Message Passing Explainer.

In this tutorial, you will learn how to use the L2ToL2CrossDomainMessenger contract to pass messages between interoperable blockchains.

Setting up your development environment

Follow the [Installation Guide](/app-developers/tutorials/supersim/getting-started/installation) to install:

Foundry for smart contract development (required in all cases)
Supersim for local blockchain simulation (optional)

Verify your installation:

forge --version
./supersim --version

Implementing onchain message passing (in Solidity)

The implementation consists of three main components:

Greeter Contract: Deployed on Chain B, receives and stores messages.
GreetingSender Contract: Deployed on Chain A, initiates cross-chain messages.

Setting up test networks

If you are using Supersim, go to the directory where Supersim is installed and start it with autorelay.
```
./supersim --interop.autorelay
```
If you are using the devnets, just skip this step.
In a separate shell, store the configuration in environment variables.

Show Sanity check

To verify that the chains are running, check the balance of $USER_ADDRESS.

cast balance --ether $USER_ADDRESS --rpc-url $URL_CHAIN_A
cast balance --ether $USER_ADDRESS --rpc-url $URL_CHAIN_B

Create the contracts

Create a new Foundry project.
```
mkdir onchain-code
cd onchain-code
forge init
```

In src/Greeter.sol put this file. This is a variation on Hardhat’s Greeter contract.

    //SPDX-License-Identifier: MIT
    pragma solidity ^0.8.0;

    contract Greeter {
        string greeting;

        event SetGreeting(
            address indexed sender,     // msg.sender
            string greeting
        );

        function greet() public view returns (string memory) {
            return greeting;
        }

        function setGreeting(string memory _greeting) public {
            greeting = _greeting;
            emit SetGreeting(msg.sender, _greeting);
        }
    }

Deploy the Greeter contract to Chain B and store the resulting contract address in the GREETER_B_ADDRESS environment variable.
```
GREETER_B_ADDRESS=`forge create --rpc-url $URL_CHAIN_B --private-key $PRIVATE_KEY Greeter --broadcast | awk '/Deployed to:/ {print $3}'`
```
Show Explanation
The command that deploys the contract is:
forge create --rpc-url $URL_CHAIN_B --private-key $PRIVATE_KEY Greeter --broadcast
The command output gives us the deployer address, the address of the new contract, and the transaction hash:
Deployer: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 Deployed to: 0x5FC8d32690cc91D4c39d9d3abcBD16989F875707 Transaction hash: 0xf155d360ec70ee10fe0e02d99c16fa5d6dc2a0e79b005fec6cbf7925ff547dbf
The awk command looks for the line that has Deployed to: and writes the third word in that line, which is the address.
awk '/Deployed to:/ {print $3}'
Finally, in UNIX (including Linux and macOS) when the command line includes backticks, the shell executes the code between the backticks and puts the output, in this case the contract address, in the command. So we get.
GREETER_B_ADDRESS=<the address>

Show Sanity check

Run these commands to verify the contract works. The first and third commands retrieve the current greeting, while the second command updates it.

cast call --rpc-url $URL_CHAIN_B $GREETER_B_ADDRESS "greet()" | cast --to-ascii
cast send --private-key $PRIVATE_KEY --rpc-url $URL_CHAIN_B $GREETER_B_ADDRESS "setGreeting(string)" Hello$$
cast call --rpc-url $URL_CHAIN_B $GREETER_B_ADDRESS "greet()" | cast --to-ascii

Install the Optimism Solidity libraries into the project.

cd lib
npm install @eth-optimism/contracts-bedrock
cd ..
echo @eth-optimism/=lib/node_modules/@eth-optimism/ >> remappings.txt

Create src/GreetingSender.sol.

    //SPDX-License-Identifier: MIT
    pragma solidity ^0.8.0;

    import { Predeploys } from "@eth-optimism/contracts-bedrock/src/libraries/Predeploys.sol";
    import { IL2ToL2CrossDomainMessenger } from "@eth-optimism/contracts-bedrock/src/L2/IL2ToL2CrossDomainMessenger.sol";

    import { Greeter } from "src/Greeter.sol";

    contract GreetingSender {
        IL2ToL2CrossDomainMessenger public immutable messenger =
            IL2ToL2CrossDomainMessenger(Predeploys.L2_TO_L2_CROSS_DOMAIN_MESSENGER);

        address immutable greeterAddress;
        uint256 immutable greeterChainId;

        constructor(address _greeterAddress, uint256 _greeterChainId) {
            greeterAddress = _greeterAddress;
            greeterChainId = _greeterChainId;
        }

        function setGreeting(string calldata greeting) public {
            bytes memory message = abi.encodeCall(
                Greeter.setGreeting,
                (greeting)
            );
            messenger.sendMessage(greeterChainId, greeterAddress, message);
        }
    }

Show Explanation

     function setGreeting(string calldata greeting) public {
         bytes memory message = abi.encodeCall(
             Greeter.setGreeting,
             (greeting)
         );
         messenger.sendMessage(greeterChainId, greeterAddress, message);
     }

This function encodes a call to setGreeting and sends it to a contract on another chain. abi.encodeCall(Greeter.setGreeting, (greeting)) constructs the calldata by encoding the function selector and parameters. The encoded message is then passed to messenger.sendMessage, which forwards it to the destination contract (greeterAddress) on the specified chain (greeterChainId).This ensures that setGreeting is executed remotely with the provided greeting value (as long as there is an executing message to relay it).

Deploy GreetingSender to chain A.

CHAIN_ID_B=`cast chain-id --rpc-url $URL_CHAIN_B`
GREETER_A_ADDRESS=`forge create --rpc-url $URL_CHAIN_A --private-key $PRIVATE_KEY --broadcast GreetingSender --constructor-args $GREETER_B_ADDRESS $CHAIN_ID_B | awk '/Deployed to:/ {print $3}'`

Send a message

Send a greeting from chain A to chain B.

cast call --rpc-url $URL_CHAIN_B $GREETER_B_ADDRESS "greet()" | cast --to-ascii
cast send --private-key $PRIVATE_KEY --rpc-url $URL_CHAIN_A $GREETER_A_ADDRESS "setGreeting(string)" "Hello from chain A"
sleep 4
cast call --rpc-url $URL_CHAIN_B $GREETER_B_ADDRESS "greet()" | cast --to-ascii

The sleep call is because it can take up to two seconds until the transaction is included in chain A, and then up to two seconds until the relay transaction is included in chain B.

Sender information

Run this command to view the events to see who called setGreeting.

cast logs --rpc-url $URL_CHAIN_B 'SetGreeting(address,string)'

The sender information is stored in the second event topic. However, for cross-chain messages, this value corresponds to the local L2ToL2CrossDomainMessenger contract address (4200000000000000000000000000000000000023), making it ineffective for identifying the original sender. In this section we change Greeter.sol to emit a separate event in it receives a cross domain message, with the sender’s identity (address and chain ID).

Modify the Greeter contract

Modify src/Greeter.sol to this code.

    //SPDX-License-Identifier: MIT
    pragma solidity ^0.8.0;

    import { Predeploys } from "@eth-optimism/contracts-bedrock/src/libraries/Predeploys.sol";

    interface IL2ToL2CrossDomainMessenger {
        function crossDomainMessageContext() external view returns (address sender_, uint256 source_);
    }

    contract Greeter {

        IL2ToL2CrossDomainMessenger public immutable messenger =
            IL2ToL2CrossDomainMessenger(Predeploys.L2_TO_L2_CROSS_DOMAIN_MESSENGER);

        string greeting;

        event SetGreeting(
            address indexed sender,     // msg.sender
            string greeting
        );

        event CrossDomainSetGreeting(
            address indexed sender,   // Sender on the other side
            uint256 indexed chainId,  // ChainID of the other side
            string greeting
        );

        function greet() public view returns (string memory) {
            return greeting;
        }

        function setGreeting(string memory _greeting) public {
            greeting = _greeting;
            emit SetGreeting(msg.sender, _greeting);

            if (msg.sender == Predeploys.L2_TO_L2_CROSS_DOMAIN_MESSENGER) {
                (address sender, uint256 chainId) =
                    messenger.crossDomainMessageContext();
                emit CrossDomainSetGreeting(sender, chainId, _greeting);
            }
        }
    }

Show Explanation

interface IL2ToL2CrossDomainMessenger {
  function crossDomainMessageContext() external view returns (address sender_, uint256 source_);
}

This definition isn’t part of the npmjs package at writing, so we just add it here.

        if (msg.sender == Predeploys.L2_TO_L2_CROSS_DOMAIN_MESSENGER) {
            (address sender, uint256 chainId) =
                messenger.crossDomainMessageContext();
            emit CrossDomainSetGreeting(sender, chainId, _greeting);
        }

If we see that we got a message from L2ToL2CrossDomainMessenger, we call L2ToL2CrossDomainMessenger.crossDomainMessageContext.

Redeploy the contracts. Because the address of Greeter is immutable in GreetingSender, we need to redeploy both contracts.

GREETER_B_ADDRESS=`forge create --rpc-url $URL_CHAIN_B --private-key $PRIVATE_KEY Greeter --broadcast | awk '/Deployed to:/ {print $3}'`
GREETER_A_ADDRESS=`forge create --rpc-url $URL_CHAIN_A --private-key $PRIVATE_KEY --broadcast GreetingSender --constructor-args $GREETER_B_ADDRESS $CHAIN_ID_B | awk '/Deployed to:/ {print $3}'`

Verify you can see cross chain sender information

Set the greeting through GreetingSender.

cast call --rpc-url $URL_CHAIN_B $GREETER_B_ADDRESS "greet()" | cast --to-ascii
cast send --private-key $PRIVATE_KEY --rpc-url $URL_CHAIN_A $GREETER_A_ADDRESS "setGreeting(string)" "Hello from chain A, with a CrossDomainSetGreeting event"
sleep 4
cast call --rpc-url $URL_CHAIN_B $GREETER_B_ADDRESS "greet()" | cast --to-ascii

Read the log entries.
```
cast logs --rpc-url $URL_CHAIN_B 'CrossDomainSetGreeting(address,uint256,string)'
echo $GREETER_A_ADDRESS
echo 0x385=`echo 0x385 | cast --to-dec`
echo 0x190a85c0=`echo 0x190a85c0 | cast --to-dec`
```
See that the second topic (the first indexed log parameter) is the same as $GREETER_A_ADDRESS. The third topic can be either 0x385=901, which is the chain ID for supersim chain A, or 0x190a85c0=420120000, which is the chain ID for devnet alpha 0.

Next steps

Review the Superchain Interop Explainer for answers to common questions about interoperability.
Read the Message Passing Explainer to understand what happens “under the hood”.
Write a revolutionary app that uses multiple blockchains within the Superchain.

Get started

Superchain interoperability

Tools

Tutorials

Overview

What You’ll Build

Setting up your development environment

Implementing onchain message passing (in Solidity)

Sender information

Next steps

Get started

Superchain interoperability

Tools

Tutorials

​Overview

​What You’ll Build

​Setting up your development environment

​Implementing onchain message passing (in Solidity)

​Sender information

​Next steps

Overview

What You’ll Build

Setting up your development environment

Implementing onchain message passing (in Solidity)

Sender information

Next steps