From 86b2b0fce9c308cb8ac4214ed678a8146bc9e3cc Mon Sep 17 00:00:00 2001 From: krofax Date: Mon, 28 Oct 2024 18:57:20 +0100 Subject: [PATCH 1/8] Added contents for general message passing on OP Stack --- pages/stack/interop/_meta.json | 3 +- pages/stack/interop/message-passing.mdx | 97 +++++++++++++++++++++++++ words.txt | 1 + 3 files changed, 100 insertions(+), 1 deletion(-) create mode 100644 pages/stack/interop/message-passing.mdx diff --git a/pages/stack/interop/_meta.json b/pages/stack/interop/_meta.json index 0fad31024..fc2575737 100644 --- a/pages/stack/interop/_meta.json +++ b/pages/stack/interop/_meta.json @@ -2,5 +2,6 @@ "explainer": "Interop explainer", "cross-chain-message": "Anatomy of cross-chain message", "supersim": "Supersim Multichain Development Environment", - "superchain-erc20": "SuperchainERC20 token standard" + "superchain-erc20": "SuperchainERC20 token standard", + "general-message-passing": "How to use general message passing on OP Stack" } \ No newline at end of file diff --git a/pages/stack/interop/message-passing.mdx b/pages/stack/interop/message-passing.mdx new file mode 100644 index 000000000..dcf42cd62 --- /dev/null +++ b/pages/stack/interop/message-passing.mdx @@ -0,0 +1,97 @@ +--- +title: How to use general message passing on OP Stack +lang: en-US +description: Learn how to use general message passing on OP Stack using OP Stack cross-chain messaging standards. +--- + +import { Steps } from 'nextra/components' + +# How to use general message passing on OP Stack + +Optimism supports cross-chain message passing, allowing communication between Ethereum and Optimism chains. This guide provides step-by-step instructions for general message passing without using Supersim, following Optimism's cross-chain messaging standards. + +## Overview of cross-chain messaging + +Cross-chain messaging on Optimism allows messages to be sent from one chain (e.g., Ethereum) to another (e.g., Optimism) using specific contracts: + +* **MessagePasser contract** on the source chain. +* **MessageReceiver contract** on the destination chain. + +For more information, refer to the [Optimism Messaging Specification](https://specs.optimism.io/interop/messaging.html) and the [Cross-Chain Message Documentation](https://docs.optimism.io/stack/protocol/interop/cross-chain-message). + +## Step 1: Prepare the cross-chain message + +To send a message from one chain to another, follow these steps to prepare and send a message. + +1. Define the Message Content + +Define the data you want to pass across the chains. This message may include function calls, values, or arbitrary data. + +```typescript +const messageData = "0xYourMessageData"; // Replace with your actual data +``` + +2. Specify the Target Contract and Function + Identify the target contract and function you want to call on the destination chain. Ensure this contract is deployed on both chains if you need bi-directional communication. + +## Step 2: Send the Message + +1. Call the MessagePasser Contract + On the source chain, call the MessagePasser contract with the message data. This contract serves as an entry point for cross-chain messages on Optimism. + +```typescript +import { viem } from 'viem'; + +const tx = await viem.writeContract({ + address: '0xYourMessagePasserAddress', // Replace with the MessagePasser contract address + abi: MessagePasserABI, // The ABI of the MessagePasser contract + functionName: 'sendMessage', + args: [targetAddress, messageData], +}); +``` + +2. Confirm the transaction + Once you send the message, wait for the transaction confirmation. This confirmation ensures that the message has been successfully sent and recorded on the source chain. + +```typescript +await tx.wait(); +console.log('Message sent successfully'); +``` + +## Step 3: Receive the message on the destination chain + +After the message is sent, it will need to be relayed and processed on the destination chain. + +1. Relay the message + Relay the message manually or use an automatic relay solution. To relay manually, use the MessageReceiver contract's function to receive and process the message. + +```typescript +const relayTx = await viem.writeContract({ + address: '0xYourMessageReceiverAddress', // Replace with the MessageReceiver contract address + abi: MessageReceiverABI, // The ABI of the MessageReceiver contract + functionName: 'receiveMessage', + args: [messageData], +}); +``` + +2. Confirm the message reception + Wait for the message reception transaction to confirm. + +```typescript +await relayTx.wait(); +console.log('Message received on destination chain'); +``` + +## Error Handling and troubleshooting + +* Ensure Contract Compatibility: Verify that both MessagePasser and MessageReceiver contracts are compatible and have matching function signatures on each chain. + +* Gas Fees: Check that you have enough funds to cover the gas fees for message passing on both chains. + +* Event Logs: Use event logs to debug and confirm message delivery at each stage. + +## Additional Resources + +For further guidance on interop messaging and cross-chain message handling, see: +* +* diff --git a/words.txt b/words.txt index c4cf76483..990249a5e 100644 --- a/words.txt +++ b/words.txt @@ -65,6 +65,7 @@ computependingblock confs corsdomain counterfactually +Crosschain crosschain Crossmint daserver From e95498fc6336513c64e42e4e0df3ebbae6e117c3 Mon Sep 17 00:00:00 2001 From: krofax Date: Tue, 29 Oct 2024 15:43:52 +0100 Subject: [PATCH 2/8] Cleaned the code --- next-env.d.ts | 2 +- pages/stack/interop/_meta.json | 2 +- pages/stack/interop/message-passing.mdx | 288 +++++++++++++++++++----- 3 files changed, 228 insertions(+), 64 deletions(-) diff --git a/next-env.d.ts b/next-env.d.ts index 4f11a03dc..a4a7b3f5c 100644 --- a/next-env.d.ts +++ b/next-env.d.ts @@ -2,4 +2,4 @@ /// // NOTE: This file should not be edited -// see https://nextjs.org/docs/basic-features/typescript for more information. +// see https://nextjs.org/docs/pages/building-your-application/configuring/typescript for more information. diff --git a/pages/stack/interop/_meta.json b/pages/stack/interop/_meta.json index fc2575737..0b88cd36e 100644 --- a/pages/stack/interop/_meta.json +++ b/pages/stack/interop/_meta.json @@ -3,5 +3,5 @@ "cross-chain-message": "Anatomy of cross-chain message", "supersim": "Supersim Multichain Development Environment", "superchain-erc20": "SuperchainERC20 token standard", - "general-message-passing": "How to use general message passing on OP Stack" + "message-passing": "General message passing with Interop" } \ No newline at end of file diff --git a/pages/stack/interop/message-passing.mdx b/pages/stack/interop/message-passing.mdx index dcf42cd62..97b3cb01c 100644 --- a/pages/stack/interop/message-passing.mdx +++ b/pages/stack/interop/message-passing.mdx @@ -1,97 +1,261 @@ --- -title: How to use general message passing on OP Stack +title: 'Message Passing with Interop' lang: en-US -description: Learn how to use general message passing on OP Stack using OP Stack cross-chain messaging standards. +description: 'Learn how to implement cross-chain message passing using interop messaging.' --- import { Steps } from 'nextra/components' -# How to use general message passing on OP Stack +# Message passing with Interop -Optimism supports cross-chain message passing, allowing communication between Ethereum and Optimism chains. This guide provides step-by-step instructions for general message passing without using Supersim, following Optimism's cross-chain messaging standards. +This guide explains how to implement cross-chain message passing using interop messaging. +You'll learn the core concepts and implementation details independent of specific tooling. -## Overview of cross-chain messaging +## Message passing concepts -Cross-chain messaging on Optimism allows messages to be sent from one chain (e.g., Ethereum) to another (e.g., Optimism) using specific contracts: +Before diving into implementation, it's crucial to understand the core concepts of interop message passing: -* **MessagePasser contract** on the source chain. -* **MessageReceiver contract** on the destination chain. +### Message structure -For more information, refer to the [Optimism Messaging Specification](https://specs.optimism.io/interop/messaging.html) and the [Cross-Chain Message Documentation](https://docs.optimism.io/stack/protocol/interop/cross-chain-message). +A message is a broadcast payload emitted from an identified source. It consists of: -## Step 1: Prepare the cross-chain message +* **Message Payload**: Raw bytes representing a Log, created by concatenating topics and data +* **Unique Identifier**: A structure that points to a specific log emission +* **Execution Context**: Information about where and how the message should be processed -To send a message from one chain to another, follow these steps to prepare and send a message. +### Message payload construction -1. Define the Message Content +```typescript +// Message payload is constructed by concatenating: +// 1. All event topics (each 32 bytes) +// 2. The event data +messagePayload = eventTopics.concat(eventData) +``` -Define the data you want to pass across the chains. This message may include function calls, values, or arbitrary data. +### Message identifier components -```typescript -const messageData = "0xYourMessageData"; // Replace with your actual data +```solidity +struct Identifier { + address origin; // Contract that emitted the log + uint256 blockNumber; // Block number of emission + uint256 logIndex; // Position in block's logs array + uint256 timestamp; // Emission timestamp + uint256 chainId; // Chain identifier where message originated +} ``` -2. Specify the Target Contract and Function - Identify the target contract and function you want to call on the destination chain. Ensure this contract is deployed on both chains if you need bi-directional communication. +## How It works -## Step 2: Send the Message +### Message lifecycle -1. Call the MessagePasser Contract - On the source chain, call the MessagePasser contract with the message data. This contract serves as an entry point for cross-chain messages on Optimism. +The cross-chain messaging process follows a specific lifecycle: -```typescript -import { viem } from 'viem'; - -const tx = await viem.writeContract({ - address: '0xYourMessagePasserAddress', // Replace with the MessagePasser contract address - abi: MessagePasserABI, // The ABI of the MessagePasser contract - functionName: 'sendMessage', - args: [targetAddress, messageData], -}); -``` +1. **Message Creation**: Events on source chain become initiating messages +2. **Message Serialization**: Converting log data into a standardized format +3. **Identifier Creation**: Generating unique identifiers for message tracking +4. **Message Execution**: Processing messages on destination chain -2. Confirm the transaction - Once you send the message, wait for the transaction confirmation. This confirmation ensures that the message has been successfully sent and recorded on the source chain. +### Message processing flow -```typescript -await tx.wait(); -console.log('Message sent successfully'); -``` +1. **Source chain**: + * Event emission triggers message creation + * System generates unique identifier + * Message is serialized and prepared for transmission -## Step 3: Receive the message on the destination chain +2. **Cross-Chain transit**: + * Message payload is prepared for relay + * System validates message structure + * Cross-chain proof is generated -After the message is sent, it will need to be relayed and processed on the destination chain. +3. **Destination chain**: + * Message receipt and validation + * Execution of message content + * Verification of successful processing -1. Relay the message - Relay the message manually or use an automatic relay solution. To relay manually, use the MessageReceiver contract's function to receive and process the message. +## Implementation guide -```typescript -const relayTx = await viem.writeContract({ - address: '0xYourMessageReceiverAddress', // Replace with the MessageReceiver contract address - abi: MessageReceiverABI, // The ABI of the MessageReceiver contract - functionName: 'receiveMessage', - args: [messageData], -}); -``` + + ### Prepare message sending -2. Confirm the message reception - Wait for the message reception transaction to confirm. + The [CrossChainMessenger](https://github.com/ethereum-optimism/optimism/blob/92ed64e171c6eb9c6a080c626640e8836f0653cc/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol) contract serves as the primary interface for cross-chain communication. + It initializes the connection to the L2 messenger contract and provides the base functionality for sending messages across chains. -```typescript -await relayTx.wait(); -console.log('Message received on destination chain'); -``` + Key components: + + * L2\_MESSENGER: The address of the L2 cross-domain messenger contract + * sendCrossChainMessage: Function to initiate cross-chain message sending + + ```solidity + contract CrossChainMessenger { + address public immutable L2_MESSENGER = 0x4200000000000000000000000000000000000023; + + function sendCrossChainMessage( + address _target, // Destination contract address + bytes memory _message, // Message content to be sent + uint32 _gasLimit // Gas limit for execution on destination + ) external { + IL2CrossDomainMessenger(L2_MESSENGER).sendMessage( + _target, + _message, + _gasLimit + ); + } + } + ``` + + ### Send the message + + This function handles the actual transmission of your message to the destination chain. It manages: + + * Contract interaction with the messenger + * Gas limit settings for the transaction + * Error handling during transmission + * Returns the transaction hash for tracking + + ```typescript + async function sendMessage( + messenger: address, // Address of the messenger contract + target: address, // Destination contract address + message: bytes, // Message content to be transmitted + gasLimit: number // Execution gas limit + ): Promise { + // Send the message with appropriate gas settings + const tx = await contract.sendMessage( + target, + message, + gasLimit, + { gasLimit: 200000 } // Transaction gas limit for sending + ); + + return tx.hash; + } + ``` + + ### Create message identifier + + Creates a unique identifier for tracking your message across chains. This function: + + * Retrieves transaction details + * Locates the specific message event + * Constructs the identifier structure with: + * Origin address + * Block information + * Chain details + * Timing data + + ```typescript + async function createMessageIdentifier( + txHash: string, // Transaction hash of the sent message + provider: Provider // Network provider for accessing chain data + ): Promise { + // Get transaction and block information + const receipt = await provider.getTransactionReceipt(txHash); + const block = await provider.getBlock(receipt.blockNumber); + + // Find the message sent event + const sentEvent = receipt.logs.find(log => + log.address === L2_MESSENGER_ADDRESS && + log.topics[0] === SENT_MESSAGE_EVENT_SIGNATURE + ); + + if (!sentEvent) throw new Error("Message event not found"); + + // Construct and return the identifier + return { + origin: L2_MESSENGER_ADDRESS, + blockNumber: receipt.blockNumber, + logIndex: sentEvent.logIndex, + timestamp: block.timestamp, + chainId: provider.network.chainId + }; + } + ``` + + ### Construct message payload + + Assembles the complete message payload for transmission. This function: + + * Concatenates event topics and data + * Formats the payload for cross-chain transmission + * Ensures proper byte alignment + * Maintains data integrity + + ```typescript + function constructMessagePayload( + topics: string[], // Event topics to include + data: string // Additional message data + ): string { + // Combine topics and data into a single payload + return ethers.utils.hexConcat([ + ...topics, + data + ]); + } + ``` + + ### Relay the message + + Executes the message on the destination chain. This function: + + * Creates a messenger contract instance + * Sends the relay transaction + * Handles gas estimation + * Manages transaction confirmation + * Returns the transaction hash + + ```typescript + async function relayMessage( + identifier: Identifier, // Message identifier from source chain + payload: string, // Constructed message payload + provider: Provider // Network provider for destination chain + ): Promise { + // Initialize messenger contract + const messenger = new Contract( + L2_MESSENGER_ADDRESS, + L2_MESSENGER_ABI, + provider.getSigner() + ); + + // Send relay transaction with appropriate gas limit + const tx = await messenger.relayMessage( + identifier, + payload, + { gasLimit: 500000 } + ); + + return tx.hash; + } + ``` -## Error Handling and troubleshooting + ### Verify message receipt -* Ensure Contract Compatibility: Verify that both MessagePasser and MessageReceiver contracts are compatible and have matching function signatures on each chain. + Confirms that your message was successfully processed on the destination chain. This function: -* Gas Fees: Check that you have enough funds to cover the gas fees for message passing on both chains. + * Retrieves the transaction receipt + * Checks for the relay event + * Verifies processing status + * Returns success/failure status -* Event Logs: Use event logs to debug and confirm message delivery at each stage. + ```typescript + async function verifyMessageRelayed( + txHash: string, // Transaction hash of the relay transaction + provider: Provider // Network provider for destination chain + ): Promise { + // Get transaction receipt + const receipt = await provider.getTransactionReceipt(txHash); + + // Check for successful relay event + return receipt.logs.some(log => + log.address === L2_MESSENGER_ADDRESS && + log.topics[0] === RELAYED_MESSAGE_EVENT_SIGNATURE + ); + } + ``` + -## Additional Resources +## Next steps -For further guidance on interop messaging and cross-chain message handling, see: -* -* +* More questions? Read our guide on the anatomy of a [cross-chain message](cross-chain-message) +* Use [Supersim](supersim), a local dev environment that simulates Superchain interop for testing applications against a local version of the Superchain. +* Use [viem bindings/actions](https://supersim.pages.dev/guides/interop/relay-using-viem.html)the guide will show you how to use viem bindings/actions to fetch identifiers and relay messages. +* Read how to manually [relay interop messages](https://supersim.pages.dev/guides/interop/manually-relaying-interop-messages-cast) with cast and `L2ToL2CrossDomainMessenger` From 483c5a6c05c7a2cd64433939df34ccb53a3fc97c Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Wed, 30 Oct 2024 11:54:53 +0100 Subject: [PATCH 3/8] Update pages/stack/interop/message-passing.mdx Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- pages/stack/interop/message-passing.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/stack/interop/message-passing.mdx b/pages/stack/interop/message-passing.mdx index 97b3cb01c..f1ad2b9a3 100644 --- a/pages/stack/interop/message-passing.mdx +++ b/pages/stack/interop/message-passing.mdx @@ -257,5 +257,5 @@ The cross-chain messaging process follows a specific lifecycle: * More questions? Read our guide on the anatomy of a [cross-chain message](cross-chain-message) * Use [Supersim](supersim), a local dev environment that simulates Superchain interop for testing applications against a local version of the Superchain. -* Use [viem bindings/actions](https://supersim.pages.dev/guides/interop/relay-using-viem.html)the guide will show you how to use viem bindings/actions to fetch identifiers and relay messages. +* Use [viem bindings/actions](https://supersim.pages.dev/guides/interop/relay-using-viem.html) - The guide shows how to use viem bindings/actions to fetch identifiers and relay messages. * Read how to manually [relay interop messages](https://supersim.pages.dev/guides/interop/manually-relaying-interop-messages-cast) with cast and `L2ToL2CrossDomainMessenger` From 8b21235a3219c3d3017bbc7aa78992f7d216184c Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Wed, 30 Oct 2024 14:56:42 +0100 Subject: [PATCH 4/8] Update pages/stack/interop/message-passing.mdx Co-authored-by: Skeletor Spaceman <92943766+skeletor-spaceman@users.noreply.github.com> --- pages/stack/interop/message-passing.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/stack/interop/message-passing.mdx b/pages/stack/interop/message-passing.mdx index f1ad2b9a3..d7eb199fc 100644 --- a/pages/stack/interop/message-passing.mdx +++ b/pages/stack/interop/message-passing.mdx @@ -77,7 +77,7 @@ The cross-chain messaging process follows a specific lifecycle: ### Prepare message sending - The [CrossChainMessenger](https://github.com/ethereum-optimism/optimism/blob/92ed64e171c6eb9c6a080c626640e8836f0653cc/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol) contract serves as the primary interface for cross-chain communication. + The [CrossDomainMessenger](https://github.com/ethereum-optimism/optimism/blob/92ed64e171c6eb9c6a080c626640e8836f0653cc/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol) contract serves as the primary interface for cross-chain communication. It initializes the connection to the L2 messenger contract and provides the base functionality for sending messages across chains. Key components: From 9ed470658a241252da29ed40455a25efb98d5fb0 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Thu, 31 Oct 2024 15:31:16 +0100 Subject: [PATCH 5/8] Updated the contents --- pages/stack/interop/message-passing.mdx | 282 ++++-------------------- words.txt | 8 +- 2 files changed, 52 insertions(+), 238 deletions(-) diff --git a/pages/stack/interop/message-passing.mdx b/pages/stack/interop/message-passing.mdx index 4184f309d..cec04983b 100644 --- a/pages/stack/interop/message-passing.mdx +++ b/pages/stack/interop/message-passing.mdx @@ -1,254 +1,66 @@ --- -title: 'Message Passing with Interop' +title: Interop Message Passing Overview lang: en-US -description: 'Learn how to implement cross-chain message passing using interop messaging.' +description: Learn about cross-chain message passing in the Superchain. --- -import { Steps } from 'nextra/components' +import { Callout, Steps } from 'nextra/components' -# Message passing with Interop +# Interop Message Passing Overview -This guide explains how to implement cross-chain message passing using interop messaging. -You'll learn the core concepts and implementation details independent of specific tooling. + + Interop is currently in active development and not yet ready for production use. The information provided here may change. Check back regularly for the most up-to-date information. + -## Message passing concepts +This guide provides an overview of cross-chain message passing in the Superchain. -Before diving into implementation, it's crucial to understand the core concepts of interop message passing: +## Overview -### Message structure +The Superchain uses a pull-based event system for cross-chain communication. Messages are sent through the `L2ToL2CrossDomainMessenger` contract, which provides a secure and standardized way to pass information between chains. -A message is a broadcast payload emitted from an identified source. It consists of: +## How it works -* **Message Payload**: Raw bytes representing a Log, created by concatenating topics and data -* **Unique Identifier**: A structure that points to a specific log emission -* **Execution Context**: Information about where and how the message should be processed +The following diagram illustrates how messages flow between chains through the `L2ToL2CrossDomainMessenger` contract, which acts as a bridge for cross-chain communication. When a contract on the source chain initiates a message, it's processed through several stages before reaching its destination, ensuring secure and reliable message delivery. -### Message payload construction - -```typescript -// Message payload is constructed by concatenating: -// 1. All event topics (each 32 bytes) -// 2. The event data -messagePayload = eventTopics.concat(eventData) +```mermaid +sequenceDiagram + participant Source as Source Chain + participant Messenger as L2ToL2CrossDomainMessenger + participant Dest as Destination Chain + + Note over Source,Dest: Message Creation + Source->>Messenger: Emit message event + Note over Source,Dest: Message Serialization + Messenger-->>Messenger: Convert to standard format + Note over Source,Dest: Identifier Creation + Messenger-->>Messenger: Generate unique ID + Note over Source,Dest: Message Execution + Messenger->>Dest: Process message ``` -### Message identifier components +Cross-chain messaging involves four main phases: -```solidity -struct Identifier { - address origin; // Contract that emitted the log - uint256 blockNumber; // Block number of emission - uint256 logIndex; // Position in block's logs array - uint256 timestamp; // Emission timestamp - uint256 chainId; // Chain identifier where message originated -} -``` +1. **Message Creation**: The source chain contract emits an event containing the message data and destination information. This event serves as the initiating message that will be relayed across chains. -## How It works - -### Message lifecycle - -The cross-chain messaging process follows a specific lifecycle: - -1. **Message Creation**: Events on source chain become initiating messages -2. **Message Serialization**: Converting log data into a standardized format -3. **Identifier Creation**: Generating unique identifiers for message tracking -4. **Message Execution**: Processing messages on destination chain - -### Message processing flow - -1. **Source chain**: - * Event emission triggers message creation - * System generates unique identifier - * Message is serialized and prepared for transmission - -2. **Cross-Chain transit**: - * Message payload is prepared for relay - * System validates message structure - * Cross-chain proof is generated - -3. **Destination chain**: - * Message receipt and validation - * Execution of message content - * Verification of successful processing - -## Implementation guide - - - ### Prepare message sending - - The [CrossDomainMessenger](https://github.com/ethereum-optimism/optimism/blob/92ed64e171c6eb9c6a080c626640e8836f0653cc/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol) contract serves as a standalone sender that emits an event. - - Key components: - - * L2\_MESSENGER: The address of the L2 cross-domain messenger contract - * sendCrossChainMessage: Function to initiate cross-chain message sending - - ```solidity - contract CrossChainMessenger { - address public immutable L2_MESSENGER = 0x4200000000000000000000000000000000000023; - - function sendCrossChainMessage( - address _target, // Destination contract address - bytes memory _message, // Message content to be sent - ) external { - IL2CrossDomainMessenger(L2_MESSENGER).sendMessage( - _target, - _message, - ); - } - } - ``` - - ### Send the message - - This function handles the actual transmission of your message to the destination chain. It manages: - - * Contract interaction with the messenger - * Gas limit settings for the transaction - * Error handling during transmission - * Returns the transaction hash for tracking - - ```typescript - async function sendMessage( - messenger: address, // Address of the messenger contract - target: address, // Destination contract address - message: bytes, // Message content to be transmitted - ): Promise { - // Send the message with appropriate gas settings - const tx = await contract.sendMessage( - target, - message, - ); - - return tx.hash; - } - ``` - - ### Create message identifier - - Creates a unique identifier for tracking your message across chains. This function: - - * Retrieves transaction details - * Locates the specific message event - * Constructs the identifier structure with: - * Origin address - * Block information - * Chain details - * Timing data - - ```typescript - async function createMessageIdentifier( - txHash: string, // Transaction hash of the sent message - provider: Provider // Network provider for accessing chain data - ): Promise { - // Get transaction and block information - const receipt = await provider.getTransactionReceipt(txHash); - const block = await provider.getBlock(receipt.blockNumber); - - // Find the message sent event - const sentEvent = receipt.logs.find(log => - log.address === L2_MESSENGER_ADDRESS && - log.topics[0] === SENT_MESSAGE_EVENT_SIGNATURE - ); - - if (!sentEvent) throw new Error("Message event not found"); - - // Construct and return the identifier - return { - origin: L2_MESSENGER_ADDRESS, - blockNumber: receipt.blockNumber, - logIndex: sentEvent.logIndex, - timestamp: block.timestamp, - chainId: provider.network.chainId - }; - } - ``` - - ### Construct message payload - - Assembles the complete message payload for transmission. This function: - - * Concatenates event topics and data - * Formats the payload for cross-chain transmission - * Ensures proper byte alignment - * Maintains data integrity - - ```typescript - function constructMessagePayload( - topics: string[], // Event topics to include - data: string // Additional message data - ): string { - // Combine topics and data into a single payload - return ethers.utils.hexConcat([ - ...topics, - data - ]); - } - ``` - - ### Relay the message - - Executes the message on the destination chain. This function: - - * Creates a messenger contract instance - * Sends the relay transaction - * Handles gas estimation - * Manages transaction confirmation - * Returns the transaction hash - - ```typescript - async function relayMessage( - identifier: Identifier, // Message identifier from source chain - payload: string, // Constructed message payload - provider: Provider // Network provider for destination chain - ): Promise { - // Initialize messenger contract - const messenger = new Contract( - L2_MESSENGER_ADDRESS, - L2_MESSENGER_ABI, - provider.getSigner() - ); - - // Send relay transaction with appropriate gas limit - const tx = await messenger.relayMessage( - identifier, - payload - ); - - return tx.hash; - } - ``` - - ### Verify message receipt - - Confirms that your message was successfully processed on the destination chain. This function: - - * Retrieves the transaction receipt - * Checks for the relay event - * Verifies processing status - * Returns success/failure status - - ```typescript - async function verifyMessageRelayed( - txHash: string, // Transaction hash of the relay transaction - provider: Provider // Network provider for destination chain - ): Promise { - // Get transaction receipt - const receipt = await provider.getTransactionReceipt(txHash); - - // Check for successful relay event - return receipt.logs.some(log => - log.address === L2_MESSENGER_ADDRESS && - log.topics[0] === RELAYED_MESSAGE_EVENT_SIGNATURE - ); - } - ``` - +2. **Message Serialization**: The messenger contract converts the event data into a standardized format that can be consistently processed across different chains in the Superchain. + +3. **Identifier Creation**: A unique identifier is generated for the message, containing information about its `origin`, `timestamp`, and other `metadata`. This identifier helps track and verify the message. + +4. **Message Execution**: The destination chain receives and processes the message, executing any associated actions or state changes specified in the original message. + +For detailed implementation steps and code examples, see our [message passing implementation guide](https://supersim.pages.dev/guides/interop/relay-using-viem.html). + +## Common Use Cases + +* Simple messages between identical contracts +* Complex multi-contract interactions +* Cross-chain state synchronization +* Token transfers and bridging + +For a practical example, see our [cross-chain ping pong tutorial](https://supersim.pages.dev/guides/interop/cross-chain-contract-via-l2cdm). ## Next steps -* More questions? Read our guide on the anatomy of a [cross-chain message](cross-chain-message) -* Use [Supersim](supersim), a local dev environment that simulates Superchain interop for testing applications against a local version of the Superchain. -* Use [viem bindings/actions](https://supersim.pages.dev/guides/interop/relay-using-viem.html) - The guide shows how to use viem bindings/actions to fetch identifiers and relay messages. -* Read how to manually [relay interop messages](https://supersim.pages.dev/guides/interop/manually-relaying-interop-messages-cast) with cast and `L2ToL2CrossDomainMessenger` +* Read about the [anatomy of a cross-chain message](/stack/interop/cross-chain-message) +* Try [Supersim](supersim) for testing cross-chain messages locally +* Learn about [manually relaying messages](https://supersim.pages.dev/guides/interop/manually-relaying-interop-messages-cast) diff --git a/words.txt b/words.txt index 5ce846b7a..5be79af1c 100644 --- a/words.txt +++ b/words.txt @@ -1,5 +1,5 @@ -accountqueue ACCOUNTQUEUE +accountqueue ACCOUNTSLOTS accountslots ADDI @@ -29,8 +29,8 @@ BLOBPOOL blobpool blobspace blockhash -BLOCKLOGS blocklists +BLOCKLOGS blocklogs BLOCKPROFILERATE blockprofilerate @@ -326,7 +326,9 @@ safedb Schnorr secp SELFDESTRUCT +SEPOLIA Sepolia +sepolia seqnr SEQUENCERHTTP sequencerhttp @@ -404,4 +406,4 @@ xtensibility ZKPs ZKVM Zora -zora \ No newline at end of file +zora From 2df47865b5ecc646c9026da982a3552e363bf125 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Thu, 31 Oct 2024 15:39:47 +0100 Subject: [PATCH 6/8] fix lint issues --- pages/stack/interop/message-passing.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pages/stack/interop/message-passing.mdx b/pages/stack/interop/message-passing.mdx index cec04983b..02c7d8bf2 100644 --- a/pages/stack/interop/message-passing.mdx +++ b/pages/stack/interop/message-passing.mdx @@ -40,13 +40,13 @@ sequenceDiagram Cross-chain messaging involves four main phases: -1. **Message Creation**: The source chain contract emits an event containing the message data and destination information. This event serves as the initiating message that will be relayed across chains. +1. **Message Creation**: The source chain contract emits an event containing the message data and destination information. This event serves as the initiating message that will be relayed across chains. -2. **Message Serialization**: The messenger contract converts the event data into a standardized format that can be consistently processed across different chains in the Superchain. +2. **Message Serialization**: The messenger contract converts the event data into a standardized format that can be consistently processed across different chains in the Superchain. -3. **Identifier Creation**: A unique identifier is generated for the message, containing information about its `origin`, `timestamp`, and other `metadata`. This identifier helps track and verify the message. +3. **Identifier Creation**: A unique identifier is generated for the message, containing information about its `origin`, `timestamp`, and other `metadata`. This identifier helps track and verify the message. -4. **Message Execution**: The destination chain receives and processes the message, executing any associated actions or state changes specified in the original message. +4. **Message Execution**: The destination chain receives and processes the message, executing any associated actions or state changes specified in the original message. For detailed implementation steps and code examples, see our [message passing implementation guide](https://supersim.pages.dev/guides/interop/relay-using-viem.html). From 89e9fb85b8ae82715f2f8c5d8c978e5f16caaf04 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Thu, 31 Oct 2024 16:24:08 +0100 Subject: [PATCH 7/8] update title --- pages/stack/interop/_meta.json | 2 +- pages/stack/interop/message-passing.mdx | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/pages/stack/interop/_meta.json b/pages/stack/interop/_meta.json index 0b88cd36e..d2a17640a 100644 --- a/pages/stack/interop/_meta.json +++ b/pages/stack/interop/_meta.json @@ -3,5 +3,5 @@ "cross-chain-message": "Anatomy of cross-chain message", "supersim": "Supersim Multichain Development Environment", "superchain-erc20": "SuperchainERC20 token standard", - "message-passing": "General message passing with Interop" + "message-passing": "Interop message passing" } \ No newline at end of file diff --git a/pages/stack/interop/message-passing.mdx b/pages/stack/interop/message-passing.mdx index 02c7d8bf2..3be6ed39c 100644 --- a/pages/stack/interop/message-passing.mdx +++ b/pages/stack/interop/message-passing.mdx @@ -1,12 +1,12 @@ --- -title: Interop Message Passing Overview +title: Interop message passing overview lang: en-US description: Learn about cross-chain message passing in the Superchain. --- import { Callout, Steps } from 'nextra/components' -# Interop Message Passing Overview +# Interop message passing overview Interop is currently in active development and not yet ready for production use. The information provided here may change. Check back regularly for the most up-to-date information. From ce9b83601e360f5f14ec0f7018a9076be832a790 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Fri, 1 Nov 2024 10:54:54 +0100 Subject: [PATCH 8/8] Update pages/stack/interop/_meta.json Co-authored-by: cpengilly <29023967+cpengilly@users.noreply.github.com> --- pages/stack/interop/_meta.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/stack/interop/_meta.json b/pages/stack/interop/_meta.json index d2a17640a..fb30169f4 100644 --- a/pages/stack/interop/_meta.json +++ b/pages/stack/interop/_meta.json @@ -2,6 +2,6 @@ "explainer": "Interop explainer", "cross-chain-message": "Anatomy of cross-chain message", "supersim": "Supersim Multichain Development Environment", - "superchain-erc20": "SuperchainERC20 token standard", + "superchain-erc20": "SuperchainERC20", "message-passing": "Interop message passing" } \ No newline at end of file