Skip to content

Commit 2009f49

Browse files
krofaxkrofax
authored
Merge pull request #1501 from ethereum-optimism/read-logs
Reading logs in superchain interop
2 parents 94328dc + d2832ee commit 2009f49

File tree

3 files changed

+227
-0
lines changed

3 files changed

+227
-0
lines changed

Diff for: ‎pages/stack/interop.mdx

+2
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@ Documentation covering explainers and tutorials for using Superchain interop.
1717

1818
<Card title="Superchain interop message passing" href="/stack/interop/message-passing" icon={<img src="/img/icons/shapes.svg" />} />
1919

20+
<Card title="Superchain interop logs" href="/stack/interop/reading-logs" icon={<img src="/img/icons/shapes.svg" />} />
21+
2022
<Card title="Superchain interop compatible tokens" href="/stack/interop/compatible-tokens" icon={<img src="/img/icons/shapes.svg" />} />
2123

2224
<Card title="OP Supervisor" href="/stack/interop/op-supervisor" icon={<img src="/img/icons/shapes.svg" />} />

Diff for: ‎pages/stack/interop/_meta.json

+1
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
"explainer": "Superchain interop explainer",
33
"predeploy": "Superchain interop predeploys",
44
"message-passing": "Superchain interop message passing",
5+
"reading-logs": "Superchain interop logs",
56
"op-supervisor": "OP Supervisor",
67
"superchain-weth": "Superchain ETH",
78
"superchain-erc20": "SuperchainERC20",

Diff for: ‎pages/stack/interop/reading-logs.mdx

+224
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
---
2+
title: Reading Logs with Superchain Interop
3+
lang: en-US
4+
description: Learn how to reference logs from one chain on another within the Superchain.
5+
topic: Cross-Chain Log Verification
6+
personas: [ "Developer" ]
7+
categories: [ "Documentation", "Interop" ]
8+
content_type: documentation
9+
---
10+
11+
import { Callout } from 'nextra/components'
12+
import { InteropCallout } from '@/components/WipCallout'
13+
14+
<InteropCallout />
15+
16+
# Reading Logs with Superchain Interop
17+
18+
Superchain interop enables developers to leverage current and historical logs from other blockchains within the [Superchain interop cluster](/stack/interop/explainer#superchain-interop-cluster) directly on their local chain.
19+
This allows smart contracts to consume local and cross-chain logs with low latency in a trust-minimized way.
20+
21+
## Overview
22+
23+
Instead of relying solely on [`L2ToL2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol), developers can use [`CrossL2Inbox#validateMessage`](https://github.com/ethereum-optimism/optimism/blob/af091753917c1d7101314cbfe8ac5cbc2efe0e5e/packages/contracts-bedrock/src/L2/CrossL2Inbox.sol#L49) and treat `CrossL2Inbox` as an oracle for logs that occurred on different chains or even their local chain.
24+
25+
This enables developers to:
26+
27+
* Build cross-chain applications that react to events happening across the Superchain.
28+
* Create novel applications that leverage data from multiple chains.
29+
30+
## Why use `CrossL2Inbox`?
31+
32+
* **Reference existing logs**: Allows contracts to verify and use logs that were already emitted, without requiring those logs to have been sent as cross-chain messages.
33+
* **Trust-minimized security**: Leverages the existing Superchain security model with no additional trust assumptions.
34+
* **Flexibility**: Can be used to validate events from another chain or even the local chain.
35+
36+
## How it works
37+
38+
### Architecture
39+
40+
The process works through the [`CrossL2Inbox`](https://github.com/ethereum-optimism/optimism/blob/af091753917c1d7101314cbfe8ac5cbc2efe0e5e/packages/contracts-bedrock/src/L2/CrossL2Inbox.sol#L33) contract, which serves as an oracle for logs from other chains in the Superchain:
41+
42+
1. A smart contract on `Chain A` emits a log (event)
43+
2. Your contract on `Chain B` calls `CrossL2Inbox#validateMessage` with the log's identifier
44+
3. The `CrossL2Inbox` contract verifies the log's authenticity
45+
4. Your contract can then use the validated log data
46+
47+
### Key components
48+
49+
* **[Identifier](/stack/interop/tutorials/relay-messages-cast#message-identifier)**: A struct containing information about the log, including `chainId`, `origin` (contract address), and other log metadata
50+
* **[validateMessage](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/CrossL2Inbox.sol#L79)**: Function that verifies a log's authenticity before allowing its use
51+
52+
## Example: cross-chain attestation verification
53+
54+
Let's walk through a conceptual example of verifying an Ethereum Attestation Service (EAS) attestation across chains.
55+
EAS is a [predeploy](/stack/interop/predeploy) in the OP Stack for making attestations on or off-chain about anything.
56+
57+
### Source chain: creating an attestation
58+
59+
On the source chain (e.g., OP Mainnet), a user creates an attestation using EAS:
60+
61+
```mermaid
62+
sequenceDiagram
63+
participant User
64+
participant App as Application
65+
participant EAS as EAS Contract
66+
participant Log as Event Log
67+
68+
User->>App: Request attestation
69+
App->>EAS: createAttestation()
70+
EAS->>Log: Emit AttestationCreated event
71+
Note over Log: Event contains attestation data
72+
```
73+
74+
1. The user initiates a request for an attestation through an application.
75+
76+
2. The application calls the `createAttestation()` function on the EAS (Ethereum Attestation Service) contract on the source chain.
77+
78+
3. The EAS contract processes the attestation request and emits an `AttestationCreated` event.
79+
80+
4. The event is recorded in the chain's log, containing all necessary attestation data.
81+
82+
### Destination chain: verifying the attestation
83+
84+
On the destination chain (e.g., Unichain), a DeFi application wants to verify this attestation:
85+
86+
```mermaid
87+
sequenceDiagram
88+
participant User
89+
participant DeFi as DeFi Application
90+
participant Verifier as AttestationVerifier
91+
participant CrossL2 as CrossL2Inbox
92+
participant OP as OP-Supervisor Service
93+
94+
User->>DeFi: Request access using attestation
95+
DeFi->>Verifier: verifyAttestation(id, attestationEvent)
96+
Verifier->>CrossL2: validateMessage(id, keccak256(attestationEvent))
97+
CrossL2->>OP: Check if log exists
98+
OP-->>CrossL2: Confirm log validity
99+
CrossL2-->>Verifier: Return validation result
100+
Verifier-->>DeFi: Return verification status
101+
DeFi-->>User: Grant access based on attestation
102+
```
103+
104+
1. The user requests access to a DeFi application on the destination chain, referencing an attestation created on the source chain.
105+
106+
2. The DeFi application calls a verification function on an attestation verifier contract, passing the attestation's identifier and event data.
107+
108+
3. The attestation verifier calls `validateMessage()` on the `CrossL2Inbox` contract, passing the attestation identifier and a hash of the event data.
109+
110+
4. The [`CrossL2Inbox`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/CrossL2Inbox.sol) contract interacts with the [`OP-Supervisor`](/stack/interop/op-supervisor) service to check if the specified log exists on the source chain.
111+
112+
5. The `OP-Supervisor` confirms the validity of the log to the `CrossL2Inbox` contract.
113+
114+
6. The `CrossL2Inbox` returns the validation result to the attestation verifier.
115+
116+
7. The attestation verifier returns the verification status to the DeFi application.
117+
118+
8. If validation is successful, the DeFi application grants the user access based on the verified attestation.
119+
120+
The primary benefit of this approach is that it allows your contract to verify attestations that already exist on another chain without requiring those attestations to have been explicitly sent as cross-chain messages.
121+
122+
## Overview of the process
123+
124+
To implement cross-chain log reading:
125+
126+
```mermaid
127+
flowchart TD
128+
A[1. Identify log to consume] --> B[2. Create Identifier struct]
129+
B --> C[3. Call validateMessage]
130+
C --> D[4. Process validated log data]
131+
132+
subgraph "Conceptual Approach"
133+
E["Define an Identifier struct with:
134+
- chainId: The source chain ID
135+
- origin: The source contract address
136+
- Other required identifier parameters"]
137+
138+
F["Call validateMessage on CrossL2Inbox
139+
Pass the identifier and hash of log data"]
140+
end
141+
142+
B --> E
143+
C --> F
144+
```
145+
146+
1. First, identify which log from another chain you want to consume in your application.
147+
148+
2. Create an Identifier struct that contains all necessary information about the log, including the chain ID and the contract address that emitted the log.
149+
150+
3. Call the `validateMessage()` function on the `CrossL2Inbox` contract, passing the identifier and a hash of the log data.
151+
152+
4. After validation, process the log data according to your application's requirements.
153+
154+
## Important considerations
155+
156+
* This feature works between chains within the [Superchain interop cluster](/stack/interop/explainer#superchain-interop-cluster).
157+
* The same functionality can be used on a single chain (for example, to maintain a consistent architecture).
158+
159+
### Handling validation failures
160+
161+
* The `validateMessage` call will revert the entire transaction if validation fails.
162+
* Consider implementing a try-catch pattern in your application's frontend to handle these failures.
163+
* Design your contract to allow for retry mechanisms where appropriate.
164+
165+
## Comparison with `L2ToL2CrossDomainMessenger`
166+
167+
| Feature | L2ToL2CrossDomainMessenger | CrossL2Inbox#validateMessage |
168+
| ---------- | ---------------------------------------------- | ------------------------------------------------- |
169+
| Purpose | Send messages between chains | Verify logs from other chains or local chain |
170+
| Initiation | Source explicitly sends message to destination | Destination queries for existing logs from source |
171+
| Use Case | Transfer tokens, trigger actions | Verify attestations, reference events |
172+
| Flow | Push model | Pull model |
173+
174+
## End-to-End flow comparison
175+
176+
```mermaid
177+
flowchart LR
178+
subgraph "L2ToL2CrossDomainMessenger (Push Model)"
179+
A[Source Contract] -->|sendMessage| B[Source L2ToL2CrossDomainMessenger]
180+
B -->|emit event| C[Event Log]
181+
C -.->|relayed by| D[Autorelayer]
182+
D -->|relayMessage| E[Destination L2ToL2CrossDomainMessenger]
183+
E -->|execute| F[Destination Contract]
184+
end
185+
186+
subgraph "CrossL2Inbox (Pull Model)"
187+
G[Source Contract] -->|emit event| H[Event Log]
188+
H -.->|monitored by| I[OP-Supervisor]
189+
J[Destination Contract] -->|validateMessage| K[CrossL2Inbox]
190+
K <--->|verify log| I
191+
end
192+
```
193+
194+
This diagram compares the two approaches for cross-chain communication:
195+
196+
### L2ToL2CrossDomainMessenger (Push Model):
197+
198+
1. A source contract calls `sendMessage()` on the `L2ToL2CrossDomainMessenger`.
199+
200+
2. The messenger emits an event to the event log.
201+
202+
3. An autorelayer detects the event and relays it to the destination chain.
203+
204+
4. The destination `L2ToL2CrossDomainMessenger` receives the relayed message.
205+
206+
5. The destination messenger executes the message on the target contract.
207+
208+
### CrossL2Inbox (Pull Model):
209+
210+
1. A source contract emits an event to the event log.
211+
212+
2. The `OP-Supervisor` service monitors events across chains.
213+
214+
3. A destination contract calls `validateMessage()` on the `CrossL2Inbox`.
215+
216+
4. The `CrossL2Inbox` verifies the log's existence by communicating with the `OP-Supervisor`.
217+
218+
5. The destination contract receives verification and proceeds with its logic.
219+
220+
## Next steps
221+
222+
* [Build a revolutionary app](/app-developers/get-started) that uses multiple blockchains within the Superchain
223+
* Learn how to [pass messages between blockchains](/stack/interop/tutorials/message-passing)
224+
* Deploy a [SuperchainERC20](/stack/interop/tutorials/deploy-superchain-erc20) to the Superchain

0 commit comments

Comments
 (0)