Skip to content

Commit caece86

Browse files
siburusiburu
committed
add DESIGN.md
Signed-off-by: Masanori Yoshida <masanori.yoshida@datachain.jp>
1 parent 2155000 commit caece86

File tree

1 file changed

+247
-0
lines changed

1 file changed

+247
-0
lines changed

‎DESIGN.md‎

Lines changed: 247 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,247 @@
1+
# Optimism Enclave Light Client (ELC) Specification
2+
3+
## 1. Introduction
4+
5+
This document defines the **Enclave Light Client (ELC)** protocol for tracking the state of an Optimism-based L2 chain in a secure and deterministic manner. Unlike traditional light clients that verify state using block headers and Merkle proofs, this client performs full **execution-based verification** of the L2 chain derivation (replay of L2 chain execution) from L1 data, closely resembling full node behavior while remaining stateless.
6+
7+
## 2. Overview
8+
9+
This section describes an overview of the Optimism ELC (hereafter referred to as "OP ELC").
10+
11+
The first is the purpose of the OP ELC. When an OP ELC instance is initialized, a specific Optimism-based L2 chain and a specific smart contract (address) deployed on it are designated. These two parameters remain constant within the OP ELC instance. Based on this configuration, the OP ELC aims to verify whether a given data exists or does not exist in a specified storage slot of the specified smart contract at a particular block height on the designated L2 chain.
12+
13+
Functionally, OP ELC provides two types of verification operations, which together fulfill the stated objective:
14+
15+
- Verification of the storage root of the target smart contract at a given block height (`update_client`)
16+
- Verification of the presence or absence of slot data under the given storage root (`verify_membership`)
17+
18+
The latter one is a simple Merkle proof against the storage root. The former is implemented through the following three-step verification procedure:
19+
20+
1. Verifies the finality of an L1 head via Ethereum’s ***Sync Committee Protocol***
21+
2. Verifies the finality of an L2 head via Optimism’s ***L2 Chain Derivation***
22+
- Recursively applies a ***Preimage Oracle*** to the verified L1 head to deterministically reconstruct required L1/L2 data
23+
- Executes **L2 derivation logic** using the reconstructed L1/L2 data up to the target L2 head
24+
3. Verifies the existence of the storage root of a target smart contract in the verified L2 head
25+
26+
### Sync Committee Protocol
27+
28+
The Sync Committee Protocol is a Light Client Protocol used to verify the existence and finality of Ethereum blocks. Its details are beyond the scope of this document.
29+
30+
### L2 Chain Derivation
31+
32+
L2 chain derivation is the process used to obtain a new L2 head.
33+
This process begins with a previously verified L2 block and replays the L2 history up to the target L2 block.
34+
To do so, it starts from a given L1 head and traverses the L1 history backward to reconstruct the necessary L1 data.
35+
From this L1 data, it extracts both L2 deposit transactions and batch data.
36+
Using these L2 inputs, the derivation process re-executes the L2 chain logic to deterministically reconstruct the target L2 head.
37+
38+
To carry out this process, the ability to retrieve preimages for various cryptographic commitments (e.g., hash value) is required.
39+
Examples include:
40+
41+
- Retrieving the previous L1 block header from a given L1 block hash
42+
- Extracting individual contract storage entries from a state root of an L2 block
43+
44+
Such capabilities rely on a **preimage oracle** that provides the necessary preimages on demand.
45+
46+
### Preimage Oracle
47+
48+
"Preimage oracle" is a conceptual component that returns a preimage for a given cryptographic commitment.
49+
50+
Cryptographic commitments have a property known as the hiding property, which ensures that it is computationally infeasible to derive the preimage from the commitment value alone.
51+
Nevertheless, there are limited ways to realize the functionality of a preimage oracle in practice.
52+
For example, a block header corresponding to a given block hash can be obtained by querying a blockchain node.
53+
Alternatively, if some commitment–preimage pairs are preloaded and stored, the oracle can return the correct preimage for those specific commitments.
54+
55+
In addition, cryptographic commitments also possess the binding property.
56+
This means that, regardless of how the preimage oracle is implemented, its behavior is cryptographically guaranteed to be deterministic --- i.e., a specific commitment corresponds to a unique preimage.
57+
58+
- Online Preimage Oracle
59+
- A preimage oracle that accepts various types of commitments as input and queries L1/L2 blockchain nodes to retrieve the corresponding preimages.
60+
- By using this type of oracle to execute L2 chain derivation, all commitment–preimage pairs required during the derivation process can be cached in a key-value store.
61+
- This oracle is used for generating the input data passed to the Enclave Light Client (ELC).
62+
- Offline Preimage Oracle
63+
- A preimage oracle based on a key-value store, where commitments are used as keys and their corresponding preimages as values.
64+
- This oracle is constructed from the cache generated by the aforementioned Online Preimage Oracle. By using it, L2 chain derivation can be executed again without accessing any blockchain node
65+
- This type of oracle is used during the verification process of the Enclave Light Client (ELC).
66+
67+
## 3. Architecture
68+
69+
This section describes the basic architecture of the Optimism Enclave Light Client (OP ELC).
70+
71+
### Operations
72+
73+
The OP ELC runs within a Trusted Execution Environment (TEE) via the Light Client Proxy (LCP). It receives inputs through the LCP and performs one of the following four operations:
74+
75+
- `create_client`: Initializes a new OP ELC instance.
76+
- `update_client`: Updates the internal state of an existing OP ELC instance.
77+
- `verify_membership`: Verifies that specified data exists in the target smart contract at a given block height.
78+
- `verify_non_membership`: Verifies that specified data does not exist in the target smart contract at a given block height.
79+
80+
For all of these operations, the OP ELC first verifies the input. If the verification is successful, it returns a signed response proving the result.
81+
82+
For `create_client` and `update_client`, if and only if verification succeeds, the ELC also writes certain pieces of internal state into the key-value store provided by the LCP.
83+
84+
### Internal State
85+
86+
The internal state of each OP ELC instance is created via `create_client` and updated via `update_client`.
87+
88+
This state consists of two components: `ClientState` and `ConsensusState`.
89+
90+
- **`ClientState`**
91+
- Created by `create_client`and stored persistently for each OP ELC instance.
92+
- Most fields in this structure are immutable configuration parameters, such as identifiers for the L1/L2 chains being verified or the address of the target smart contract.
93+
- Mutable fields include, for example, the latest verified L2 block height.
94+
- **`ConsensusState`**
95+
- Created by `create_client` and `update_client`, and stored per L2 block height.
96+
- Contains:
97+
- The storage root of the target smart contract at the corresponding L2 block
98+
- Sync committee data (current and next) used to verify future L1 heads
99+
(This data enables the client to verify the validity of the L1 head during the next `update_client` operation)
100+
101+
### Inputs
102+
103+
- **`Header`**
104+
- Used as the input to the `update_client` operation
105+
- Contains both:
106+
- The data to be stored in the new `ConsensusState`
107+
- The proofs required to verify a new L1 head via **the Sync Committee Protocol**
108+
- The preimages required to verify a new L2 head via **the L2 Chain Derivation**
109+
110+
## 4. Data Structures
111+
112+
This section outlines the key data structures used in the Optimism Enclave Light Client (ELC).
113+
114+
- `optimism_elc::ClientState`
115+
- L1/L2 immutable configuration
116+
- latest L2 height
117+
- flag that specifies whether this client is frozen or not
118+
- `optimism_elc::ConsensusState` (for each L2 height)
119+
- storage root (of the target smart contract)
120+
- L2 output root
121+
- L1 origin
122+
- sync committee information
123+
- `optimism_elc::Header`
124+
- newly claimed L1/L2 block information
125+
- proof data that support the above claims
126+
- proof required for sync committee protocol
127+
- preimages required for L2 chain derivation
128+
- `optimism_derivation::MemoryOracleClient`
129+
- an implementation of the offline preimage oracle
130+
131+
## 5. Functions
132+
133+
This section describes the core functions that make up the Optimism Enclave Light Client (ELC) behavior.
134+
135+
- `optimism_elc::ClientState::check_header_and_update_state`
136+
- Overview
137+
- core logic of ELC’s `update_client`
138+
- verifies a `Header` and stores the storage root in it into `ConsensusState`
139+
- Details
140+
1. `optimism_elc::Header::verify_l1`
141+
- verifies that the newly claimed L1 head is finalized in L1 using the Ethereum’s sync committee protocol
142+
2. `optimism_elc::Header::verify_l2`
143+
- executes L2 chain derivation using the offline preimage oracle
144+
- logic: `optimism_derivation::run` (≒ `kona_client::single::run`)
145+
- oracle: `optimism_derivation::MemoryOracleClient`
146+
- verifies that the derived L2 head is identical to the claimed L2 head
147+
3. `optimism_elc::AccountUpdateInfo::verify_account_proof`
148+
- verifies that the storage root of the target smart contract is included in the claimed L2 head’s state trie
149+
4. `optimism_elc::validate_state_timestamp_within_trusting_period`
150+
- verifies that the claimed L2 head has not expired the trusting period
151+
- `optimism_elc::ClientState::verify_membership`
152+
- verifies that a state (e.g. IBC packet) exists in the verified storage trie (`ConsensusState::storage_root`)
153+
- `optimism_elc::ClientState::verify_non_membership`
154+
- verify that a state (e.g. IBC packet) does NOT exist in the verified storage trie (`ConsensusState::storage_root`)
155+
- `optimism_preimage_maker::derivation`
156+
- performs L2 chain derivation starting from the already verified L2 head to the newly claimed L2 head using the online preimage oracle
157+
- caches all commitment-preimage pairs required during a L2 state derivation
158+
159+
> Note: `optimism_preimage_maker` is not part of the enclave light client itself, but is a reference implementation to prepare inputs. It performs L2 chain derivation starting from the given L2 head and target block number, populating the required preimage oracle by querying the L1/L2 nodes and caching the results.
160+
161+
## 6. Security Assumptions
162+
163+
This section outlines the security assumptions under which the Optimism Enclave Light Client (ELC) is designed to operate. These assumptions are necessary to ensure the correctness and finality of the data verified by the ELC.
164+
165+
### L1 Assumptions
166+
167+
- For each block height, there is a **unique finalized L1 block** that cannot be reverted.
168+
- The **Sync Committee protocol** is correctly implemented and secure, allowing light clients to verify the existence and finality of any L1 block.
169+
170+
### L2 Assumptions
171+
172+
- The system assumes the **at least one honest validator** property: any invalid proposal will eventually be rejected via the dispute game (fault proof mechanism).
173+
- All valid L2 state updates are **eventually reflected on L1** through a canonical proposal process.
174+
175+
### Preimage Oracle / Cryptographic Commitment Assumptions
176+
177+
- **Hiding Property**:
178+
- It is computationally infeasible to recover a preimage from a cryptographic commitment.
179+
180+
- **Binding Property**:
181+
- Each commitment corresponds to a **unique** preimage.
182+
- This ensures that the behavior of the preimage oracle is deterministic, regardless of how it is implemented (e.g., online vs. offline oracle).
183+
184+
### LC Security under These Assumptions above
185+
186+
- The Optimism ELC
187+
- uses the **Sync Committee protocol** to verify the finality of the L1 head.
188+
- performs L2 chain derivation using the (offline)preimage oracle starting from the verified L1 head.
189+
- Due to the uniqueness of the behavior of the preimage oracle, the L2 head obtained by L2 chain derivation is correct and unique.
190+
- Because valid L2 states are guaranteed to be reflected on L1, the derived L2 head is canonically correct.
191+
192+
## 7. Misbehaviour Detection
193+
194+
Among the Security Assumptions described above, the OP ELC can detect occurrences of misbehaviour that violate the assumptions related to either L1 or L2, using the procedures outlined below.
195+
196+
### Misbehaviour Detection for L1 Assumptions
197+
198+
If a Sync Committee acts in violation of the Sync Committee Protocol, the OP ELC will be unable to correctly verify the provided L1 head. Such misbehaviour is defined and the detection procedure is described in the following document. The OP ELC can detect it using the same method:
199+
200+
[https://github.com/datachainlab/ethereum-ibc-rs/blob/v0.1.0/README.md#misbehaviour-detection](https://github.com/datachainlab/ethereum-ibc-rs/blob/v0.1.0/README.md#misbehaviour-detection)
201+
202+
### Misbehaviour Detection for L2 Assumptions
203+
204+
In this section, we assume that the L1 assumptions hold --- that is, the OP ELC is provided with a finalized L1 head --- and we describe scenarios in which misbehaviour related to the L2 assumptions can occur, as well as how such misbehaviour can be handled.
205+
206+
The L2 head, derived from the L1 head via L2 state derivation, is cryptographically unique. The OP ELC also derives the L2 head from the L1 head using this derivation logic. Therefore, a conflicting L2 state can only be reflected on L1 in the case where an invalid proposal --- one that is inconsistent with the L1 data (e.g., deposit or batch data) bound to the L1 head --- remains unchallenged until the end of the challenge period. We refer to this type of misbehaviour as `NoHonestValidatorMisbehaviour`.
207+
208+
`NoHonestValidatorMisbehaviour` can be detected if the OP ELC instance possesses a `ConsensusState` containing an L2 block hash, along with a conflicting proposal and the necessary proofs to trace from the height of the former to that of the latter. The pseudocode for this detection is as follows.
209+
210+
```rust
211+
// This function returns true if a misbehaviour is detected
212+
fn check_misbehaviour(
213+
agreed_l1_origin_hash: H256,
214+
agreed_l2_block_hash: H256,
215+
dispute_game_address: H160,
216+
oracle: &PreimageOracle,
217+
) -> bool {
218+
// agreed L1Origin + L2Block
219+
let agreed_l1_origin = oracle.get_block_by_hash(agreed_l1_origin_hash);
220+
let agreed_l2_block = oracle.get_block_by_hash(agreed_l2_block_hash);
221+
222+
// fields of the target dispute game
223+
let dispute_game_root = oracle.get_storage_root(agreed_l1_origin.state_root, dispute_game_address);
224+
let dispute_l1_head_hash = oracle.get_storage_entry(dispute_game_root, L1_HEAD_SLOT);
225+
let dispute_l1_head = oracle.get_block_by_hash(dispute_l1_head_hash);
226+
let dispute_status = oracle.get_storage_entry(dispute_game_root, STATUS_SLOT);
227+
let dispute_root_claim = oracle.get_storage_entry(dispute_game_root, ROOT_CLAIM_SLOT);
228+
let dispute_l2_block = oracle.get_block_from_output_root(dispute_root_claim);
229+
230+
// prerequisites
231+
if dispute_l1_head.slot >= agreed_l1_origin.slot {
232+
return false;
233+
}
234+
if dispute_status != DEFENDER_WINS {
235+
return false;
236+
}
237+
238+
// MISBEHAVIOUR1: The target proposal claims a future (non-existent) L2 output root
239+
if dispute_l2_block.height > agreed_l2_block.height {
240+
return true;
241+
}
242+
243+
// MISBEHAVIOUR2: The target proposal claims an inconsistent L2 output root
244+
let contradict_l2_block = oracle.get_block_by_height_diff(agreed_l2_block, (agreed_l2_block.height - dispute_l2_block.height));
245+
return calc_output_root(contradict_l2_block) != dispute_root_claim;
246+
}
247+
```

0 commit comments

Comments
 (0)