Update docs #64
Merged
Update docs #64
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
📝 WalkthroughWalkthroughThis pull request adds comprehensive documentation for the cross-chain broadcaster ecosystem, including new documentation files for Broadcaster, Receiver, and StateProvers components, plus chain-specific prover documentation for Arbitrum, Linea, Optimism, Scroll, Taiko, and ZkSync. The old ERC-7888 documentation is removed and the main README is reorganized for improved navigation. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~15 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Fix all issues with AI agents
In `@docs/PROVERS.md`:
- Around line 98-101: The fenced diagram blocks (e.g., the block containing
"Route Address → StateProverPointer → StateProver (fixed) (fixed) (upgradeable)"
and the other ASCII diagrams around the other mentioned sections) lack a
language tag; update each triple-backtick fence to include a language identifier
such as text (e.g., change ``` to ```text) so markdownlint MD040 is satisfied
for all occurrences (including the blocks corresponding to the other diagram
regions noted). Ensure you add the same tag to every matching fenced diagram in
the file.
In `@docs/provers/LINEA.md`:
- Around line 7-38: The fenced ASCII diagram block (the triple-backtick block
that begins with the box-drawing characters "┌────────────────" and contains the
"Ethereum (L1)" / "Linea (L2)" diagram) is missing a language tag; update that
fence to include a language hint (e.g., change ``` to ```text) so the block
becomes a labeled code fence (```text ... ```).
In `@docs/provers/OPTIMISM.md`:
- Around line 7-41: The fenced diagram blocks in OPTIMISM.md are missing
language identifiers, causing markdownlint warnings; update each triple-backtick
fence around the ASCII diagrams (the blocks containing "AnchorStateRegistry",
"FaultDisputeGame", "OutputRootProof", and the "L1Block Predeploy" diagram
including the 0x420000... address) to include a language tag (e.g., ```text or
```ascii) so the linter recognizes them as code blocks and the warnings are
resolved.
In `@docs/provers/TAIKO.md`:
- Around line 12-18: The docs incorrectly show Checkpoint struct storing
blockNumber, blockHash, and stateRoot; update the description and storage layout
to reflect Taiko's actual SignalService where the mapping key (blockNumber) is
not stored in the struct and the struct (CheckpointRecord/Checkpoint) contains
only bytes32 blockHash at slot+0 and bytes32 stateRoot at slot+1; modify all
affected sections (including the examples around the Checkpoint/CheckpointRecord
mapping and the referenced ranges) to remove blockNumber from the struct layout
and clarify that blockNumber is the mapping key used for slot derivation.
Comment on lines
+98
to
+101
| ``` | ||
| Route Address → StateProverPointer → StateProver | ||
| (fixed) (fixed) (upgradeable) | ||
| ``` |
There was a problem hiding this comment.
Add language tags to fenced diagram blocks.
These fenced blocks are missing language identifiers per markdownlint (MD040).
Also applies to: 183-192, 261-290
🤖 Prompt for AI Agents
In `@docs/PROVERS.md` around lines 98 - 101, The fenced diagram blocks (e.g., the
block containing "Route Address → StateProverPointer → StateProver (fixed)
(fixed) (upgradeable)" and the other ASCII diagrams around the other mentioned
sections) lack a language tag; update each triple-backtick fence to include a
language identifier such as text (e.g., change ``` to ```text) so markdownlint
MD040 is satisfied for all occurrences (including the blocks corresponding to
the other diagram regions noted). Ensure you add the same tag to every matching
fenced diagram in the file.
Comment on lines
+7
to
+38
| ``` | ||
| ┌─────────────────────────────────────────────────────────────────────────┐ | ||
| │ Ethereum (L1) │ | ||
| │ ┌───────────────────────────────────────────────────────────────────┐ │ | ||
| │ │ LineaRollup │ │ | ||
| │ │ mapping(uint256 blockNumber => bytes32 stateRootHash) │ │ | ||
| │ │ │ │ | ||
| │ │ • Stores Linea L2 state roots (SMT roots, not block hashes) │ │ | ||
| │ │ • Updated after ZK proof verification │ │ | ||
| │ └───────────────────────────────────────────────────────────────────┘ │ | ||
| └─────────────────────────────────────────────────────────────────────────┘ | ||
| │ | ||
| │ L2 SMT state root | ||
| ▼ | ||
| ┌─────────────────────────────────────────────────────────────────────────┐ | ||
| │ Linea (L2) │ | ||
| │ ┌───────────────────────────────────────────────────────────────────┐ │ | ||
| │ │ Block Hash Buffer │ │ | ||
| │ │ mapping(uint256 blockNumber => bytes32 blockHash) │ │ | ||
| │ │ │ │ | ||
| │ │ • Stores L1 block hashes pushed via the bridge │ │ | ||
| │ │ • Uses standard MPT proofs for L1 state │ │ | ||
| │ └───────────────────────────────────────────────────────────────────┘ │ | ||
| │ │ | ||
| │ ┌───────────────────────────────────────────────────────────────────┐ │ | ||
| │ │ Sparse Merkle Tree State │ │ | ||
| │ │ • 42-level binary tree with MiMC hashing │ │ | ||
| │ │ • Proofs via linea_getProof RPC method │ │ | ||
| │ │ • Different from eth_getProof format │ │ | ||
| │ └───────────────────────────────────────────────────────────────────┘ │ | ||
| └─────────────────────────────────────────────────────────────────────────┘ | ||
| ``` |
There was a problem hiding this comment.
Add a language tag to the fenced diagram block.
Markdownlint flags this fence without a language. Please add a language hint (e.g., text) for consistency.
💡 Suggested fix
-```
+```text
┌─────────────────────────────────────────────────────────────────────────┐
│ Ethereum (L1) │
...
└─────────────────────────────────────────────────────────────────────────┘
-```
+```📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ``` | |
| ┌─────────────────────────────────────────────────────────────────────────┐ | |
| │ Ethereum (L1) │ | |
| │ ┌───────────────────────────────────────────────────────────────────┐ │ | |
| │ │ LineaRollup │ │ | |
| │ │ mapping(uint256 blockNumber => bytes32 stateRootHash) │ │ | |
| │ │ │ │ | |
| │ │ • Stores Linea L2 state roots (SMT roots, not block hashes) │ │ | |
| │ │ • Updated after ZK proof verification │ │ | |
| │ └───────────────────────────────────────────────────────────────────┘ │ | |
| └─────────────────────────────────────────────────────────────────────────┘ | |
| │ | |
| │ L2 SMT state root | |
| ▼ | |
| ┌─────────────────────────────────────────────────────────────────────────┐ | |
| │ Linea (L2) │ | |
| │ ┌───────────────────────────────────────────────────────────────────┐ │ | |
| │ │ Block Hash Buffer │ │ | |
| │ │ mapping(uint256 blockNumber => bytes32 blockHash) │ │ | |
| │ │ │ │ | |
| │ │ • Stores L1 block hashes pushed via the bridge │ │ | |
| │ │ • Uses standard MPT proofs for L1 state │ │ | |
| │ └───────────────────────────────────────────────────────────────────┘ │ | |
| │ │ | |
| │ ┌───────────────────────────────────────────────────────────────────┐ │ | |
| │ │ Sparse Merkle Tree State │ │ | |
| │ │ • 42-level binary tree with MiMC hashing │ │ | |
| │ │ • Proofs via linea_getProof RPC method │ │ | |
| │ │ • Different from eth_getProof format │ │ | |
| │ └───────────────────────────────────────────────────────────────────┘ │ | |
| └─────────────────────────────────────────────────────────────────────────┘ | |
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.20.0)
7-7: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In `@docs/provers/LINEA.md` around lines 7 - 38, The fenced ASCII diagram block
(the triple-backtick block that begins with the box-drawing characters
"┌────────────────" and contains the "Ethereum (L1)" / "Linea (L2)" diagram) is
missing a language tag; update that fence to include a language hint (e.g.,
change ``` to ```text) so the block becomes a labeled code fence (```text ...
```).
Comment on lines
+7
to
+41
| ``` | ||
| ┌─────────────────────────────────────────────────────────────────────────┐ | ||
| │ Ethereum (L1) │ | ||
| │ ┌───────────────────────────────────────────────────────────────────┐ │ | ||
| │ │ AnchorStateRegistry │ │ | ||
| │ │ Storage slot 3: address anchorGame │ │ | ||
| │ │ │ │ | ||
| │ │ • Points to the current valid FaultDisputeGame │ │ | ||
| │ │ • Game contains the L2 output root (rootClaim) │ │ | ||
| │ └───────────────────────────────────────────────────────────────────┘ │ | ||
| │ │ | ||
| │ ┌───────────────────────────────────────────────────────────────────┐ │ | ||
| │ │ FaultDisputeGame (CWIA Proxy) │ │ | ||
| │ │ rootClaim = keccak256(OutputRootProof) │ │ | ||
| │ │ │ │ | ||
| │ │ OutputRootProof { │ │ | ||
| │ │ version, stateRoot, messagePasserStorageRoot, latestBlockhash │ │ | ||
| │ │ } │ │ | ||
| │ └───────────────────────────────────────────────────────────────────┘ │ | ||
| └─────────────────────────────────────────────────────────────────────────┘ | ||
| │ | ||
| │ L2 block hash in OutputRootProof | ||
| ▼ | ||
| ┌─────────────────────────────────────────────────────────────────────────┐ | ||
| │ Optimism (L2) │ | ||
| │ ┌───────────────────────────────────────────────────────────────────┐ │ | ||
| │ │ L1Block Predeploy │ │ | ||
| │ │ Address: 0x4200000000000000000000000000000000000015 │ │ | ||
| │ │ Storage slot 2: bytes32 hash (latest L1 block hash) │ │ | ||
| │ │ │ │ | ||
| │ │ • Updated by the depositor account each L2 block │ │ | ||
| │ │ • Only stores the LATEST L1 block hash (no history) │ │ | ||
| │ └───────────────────────────────────────────────────────────────────┘ │ | ||
| └─────────────────────────────────────────────────────────────────────────┘ | ||
| ``` |
There was a problem hiding this comment.
Add language tags to fenced diagram blocks.
Markdownlint flags these fences as missing language identifiers.
Also applies to: 305-319
🧰 Tools
🪛 markdownlint-cli2 (0.20.0)
7-7: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In `@docs/provers/OPTIMISM.md` around lines 7 - 41, The fenced diagram blocks in
OPTIMISM.md are missing language identifiers, causing markdownlint warnings;
update each triple-backtick fence around the ASCII diagrams (the blocks
containing "AnchorStateRegistry", "FaultDisputeGame", "OutputRootProof", and the
"L1Block Predeploy" diagram including the 0x420000... address) to include a
language tag (e.g., ```text or ```ascii) so the linter recognizes them as code
blocks and the warnings are resolved.
Comment on lines
+12
to
+18
| │ │ mapping(uint48 blockNumber => Checkpoint) checkpoints │ │ | ||
| │ │ │ │ | ||
| │ │ struct Checkpoint { │ │ | ||
| │ │ uint48 blockNumber; │ │ | ||
| │ │ bytes32 blockHash; │ │ | ||
| │ │ bytes32 stateRoot; │ │ | ||
| │ │ } │ │ |
There was a problem hiding this comment.
Correct the checkpoint storage layout (blockNumber is not stored).
The SignalService mapping stores CheckpointRecord with only blockHash and stateRoot; blockNumber is the mapping key and not stored in the struct. The current doc implies blockNumber is stored and packed at slot+0, which would mislead slot derivation and proof construction.
✅ Proposed correction
- │ struct Checkpoint { │ │
- │ uint48 blockNumber; │ │
- │ bytes32 blockHash; │ │
- │ bytes32 stateRoot; │ │
- │ } │ │
+ │ struct CheckpointRecord { │ │
+ │ bytes32 blockHash; │ │
+ │ bytes32 stateRoot; │ │
+ │ } │ │-interface ICheckpointStore {
- struct Checkpoint {
- uint48 blockNumber; // Block number this checkpoint refers to
- bytes32 blockHash; // Block hash of that block
- bytes32 stateRoot; // State root (may not always be populated)
- }
+interface ICheckpointStore {
+ struct Checkpoint {
+ uint48 blockNumber; // ABI/return only (mapping key)
+ bytes32 blockHash; // Stored at base slot
+ bytes32 stateRoot; // Stored at base slot + 1
+ }-// The Checkpoint struct at that slot:
-// slot + 0: blockNumber (packed with other small values)
-// slot + 0: blockHash (first bytes32 of struct)
-// slot + 1: stateRoot
+// The CheckpointRecord struct at that slot:
+// slot + 0: blockHash
+// slot + 1: stateRootBased on learnings: “In Taiko's SignalService, the storage struct CheckpointRecord contains only bytes32 blockHash (slot+0) and bytes32 stateRoot (slot+1). The blockNumber is the mapping key, not stored in the struct.”
Also applies to: 49-61, 326-336
🤖 Prompt for AI Agents
In `@docs/provers/TAIKO.md` around lines 12 - 18, The docs incorrectly show
Checkpoint struct storing blockNumber, blockHash, and stateRoot; update the
description and storage layout to reflect Taiko's actual SignalService where the
mapping key (blockNumber) is not stored in the struct and the struct
(CheckpointRecord/Checkpoint) contains only bytes32 blockHash at slot+0 and
bytes32 stateRoot at slot+1; modify all affected sections (including the
examples around the Checkpoint/CheckpointRecord mapping and the referenced
ranges) to remove blockNumber from the struct layout and clarify that
blockNumber is the mapping key used for slot derivation.
nahimterrazas
approved these changes
Jan 28, 2026
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR updates docs on ERC7888 and its components
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.