Skip to content

docs: sync README and tooling docs#50

Merged
panos-xyz merged 2 commits intomainfrom
docs/cleanup-stale-docs
Mar 16, 2026
Merged

docs: sync README and tooling docs#50
panos-xyz merged 2 commits intomainfrom
docs/cleanup-stale-docs

Conversation

@panos-xyz
Copy link
Contributor

@panos-xyz panos-xyz commented Mar 13, 2026

Summary

  • remove stale --morph.geth-rpc-url documentation and local-test script remnants
  • align README.md and CONTRIBUTING.md with the current CLI, Engine API, hardfork behavior, bootstrap guidance, and stable-toolchain checks
  • clarify MorphTx versioning and pre-Jade/Jade state-root validation semantics in the public docs

Test plan

  • cargo test --all
  • bash -n local-test/common.sh local-test/reth-start.sh

Summary by CodeRabbit

  • Documentation

    • Updated transaction specs to versioned V0/V1 semantics and clarified fee/reference/memo behavior
    • Expanded Jade-era hardfork details, state-root notes, and L2 Engine API behavior and new method coverage
    • Refined node operation and bootstrap guidance for production
  • Chores

    • Switched development formatting and test guidance to stable toolchain commands
    • Replaced doc-generation step with doc-test workflow
    • Removed a default local RPC configuration used by test scripts

Remove stale geth-rpc-url references and align the repository docs with the current CLI, Engine API, hardfork semantics, bootstrap guidance, and stable-toolchain checks.
@coderabbitai
Copy link

coderabbitai bot commented Mar 13, 2026

📝 Walkthrough

Walkthrough

Replaces nightly-specific Rust formatting/docs instructions with stable toolchain commands, updates README protocol docs (transaction versions, Jade-era hardforks, L2 Engine API), and removes the default MORPH_GETH_RPC_URL and its conditional use in local test startup scripts.

Changes

Cohort / File(s) Summary
Toolchain & Formatting
CONTRIBUTING.md, README.md
Remove +nightly formatting commands; replace cargo +nightly fmt --all with cargo fmt --all; change doc build step to run doc tests (cargo test --doc --all --verbose) and update Code Style guidance to reference stable toolchain.
Protocol Documentation
README.md
Revise Morph transaction model to versioned V0/V1 semantics, update hardfork descriptions (Jade-era behavior, state-root notes, Emerald scheduling), expand L2 Engine API docs (executable block data, engine_setBlockTags), and align running-node/consensus notes.
Local test scripts
local-test/common.sh, local-test/reth-start.sh
Remove default MORPH_GETH_RPC_URL environment variable declaration and delete conditional inclusion of --morph.geth-rpc-url "${MORPH_GETH_RPC_URL}" from reth startup arguments.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

Suggested reviewers

  • chengwenxi
  • anylots

Poem

🐰 In code and docs the carrots gleam,
From nightly dreams to stable stream,
Scripts trimmed neat, the README sings,
Jade-era tales and tidy things —
Hoppity hops for clearer dreams! 🥕✨

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'docs: sync README and tooling docs' accurately reflects the main objectives: updating documentation files (README.md, CONTRIBUTING.md) and removing stale tooling script references.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch docs/cleanup-stale-docs
📝 Coding Plan
  • Generate coding plan for human review comments

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Tip

Migrating from UI to YAML configuration.

Use the @coderabbitai configuration command in a PR comment to get a dump of all your UI settings in YAML format. You can then edit this YAML file and upload it to the root of your repository to configure CodeRabbit programmatically.

@panos-xyz panos-xyz requested a review from chengwenxi March 13, 2026 09:29
Copy link

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@README.md`:
- Around line 169-173: Update the V1 table row to explicitly state the
validation rule that when fee_token_id == 0 (ETH fee path) fee_limit must be
unset or zero; in other words, extend the V1 description to mention that
fee_limit MUST be zero/omitted for the ETH-fee case and that non-zero fee_limit
is only allowed when fee_token_id > 0 (registry token) to match validation
behavior.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c10dd832-fedc-4d8c-bd04-2ff41b11034f

📥 Commits

Reviewing files that changed from the base of the PR and between 5843ee6 and be7efd8.

📒 Files selected for processing (4)
  • CONTRIBUTING.md
  • README.md
  • local-test/common.sh
  • local-test/reth-start.sh
💤 Files with no reviewable changes (2)
  • local-test/reth-start.sh
  • local-test/common.sh

@chengwenxi
Copy link
Contributor

Code review

Found 1 issue:

  1. engine_assembleL2Block description incorrectly claims "normal L2 txs are typically pulled from the txpool." The AssembleL2BlockParams struct takes a single transactions: Vec<Bytes> field where the caller must supply all transactions. The morph-reth engine API has no txpool interaction in this code path — the sequencer provides both L1-message and L2 transactions in that field. This will mislead anyone implementing a sequencer client.

morph-reth/README.md

Lines 196 to 198 in be7efd8

|--------|-------------|
| `engine_assembleL2Block` | Build executable L2 block data for the next height from the supplied transaction list; sequencers are expected to provide L1-message txs here, while normal L2 txs are typically pulled from the txpool |
| `engine_validateL2Block` | Validate executable block data without importing it |

See also AssembleL2BlockParams definition (crates/payload/types/src/params.rs) and the engine API handler (crates/engine-api/src/rpc.rs) which forwards the caller-supplied transactions directly with no txpool involvement.

🤖 Generated with Claude Code

- If this code review was useful, please react with 👍. Otherwise, react with 👎.

The sequencer supplies L1-message transactions via the `transactions`
parameter, while L2 transactions are pulled from the txpool. This
matches go-ethereum's fillTransactions behavior.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@panos-xyz
Copy link
Contributor Author

Checked both implementations:

  • go-ethereum fillTransactions (miner/worker.go:402-461): executes caller-supplied L1 messages first, then calls miner.txpool.PendingWithMax() to pull L2 transactions from the txpool.
  • morph-reth MorphPayloadBuilder (crates/payload/builder/src/builder.rs:636-642): same pattern — execute_l1_messages first, then execute_pool_transactions from the txpool.

The AssembleL2BlockParams.transactions field carries L1 messages from the sequencer. L2 transactions are pulled from the txpool in both implementations.

Updated the description to be more precise in 2a56d6d:

Build executable L2 block data for the next height; the sequencer supplies L1-message transactions via the transactions parameter, and L2 transactions are pulled from the txpool

Copy link

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@README.md`:
- Line 197: Update the `engine_assembleL2Block` description to state that the
sequencer supplies all transactions (both L1 messages and L2 transactions) via
the AssembleL2BlockParams.transactions: Vec<Bytes> field and that the handler
uses these caller-supplied transactions directly with no txpool interaction;
replace the current phrasing that implies only L1 messages are provided and
remove any mention of txpool usage so implementers understand the sequencer must
provide every transaction.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5b2efff4-3f26-4a79-8ef3-776fe300defd

📥 Commits

Reviewing files that changed from the base of the PR and between be7efd8 and 2a56d6d.

📒 Files selected for processing (1)
  • README.md

| `engine_validateL2Block` | Validate a block without importing |
| `engine_newL2Block` | Import and finalize a block |
| `engine_newSafeL2Block` | Import a safe block from derivation |
| `engine_assembleL2Block` | Build executable L2 block data for the next height; the sequencer supplies L1-message transactions via the `transactions` parameter, and L2 transactions are pulled from the txpool |
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Verify AssembleL2BlockParams structure and engine API handler implementation

# Check AssembleL2BlockParams structure
echo "=== AssembleL2BlockParams structure ==="
ast-grep --pattern 'struct AssembleL2BlockParams {
  $$$
}'

# Check the transactions field specifically
echo -e "\n=== Searching for transactions field in AssembleL2BlockParams ==="
rg -nP -A10 'struct AssembleL2BlockParams' --type=rust crates/payload/types/src/params.rs

# Check engine API handler for assembleL2Block
echo -e "\n=== engine_assembleL2Block handler implementation ==="
rg -nP -B5 -A20 'engine_assembleL2Block|assembleL2Block' --type=rust crates/engine-api/src/rpc.rs

# Search for any txpool interaction in the assemble code path
echo -e "\n=== Checking for txpool usage in payload building ==="
rg -nP 'txpool|pool.*transaction|best_transaction' --type=rust crates/payload/builder/src/

Repository: morph-l2/morph-reth

Length of output: 3932


🏁 Script executed:

#!/bin/bash
# Find the implementation of MorphL2EngineRpc trait
echo "=== Searching for MorphL2EngineRpc implementation ==="
rg -nP 'impl.*MorphL2EngineRpc|fn assemble_l2_block' --type=rust -A15 crates/

# Search for handler implementations in engine-api
echo -e "\n=== Checking engine API handler files ==="
fd -type f -name "*.rs" crates/engine-api/ | head -20

# Look for any struct that implements the RPC trait
echo -e "\n=== Looking for concrete implementations ==="
rg -nP 'struct.*Handler|impl MorphL2EngineRpc' --type=rust crates/engine-api/src/

Repository: morph-l2/morph-reth

Length of output: 6412


🏁 Script executed:

#!/bin/bash
# Find build_l2_payload implementation
echo "=== Searching for build_l2_payload implementation ==="
rg -nP 'fn build_l2_payload' --type=rust -A30 crates/engine-api/src/builder.rs

# Check if transactions from params are used directly
echo -e "\n=== Checking how params.transactions are used ==="
rg -nP 'params\.transactions' --type=rust crates/engine-api/src/builder.rs

Repository: morph-l2/morph-reth

Length of output: 1518


🏁 Script executed:

#!/bin/bash
# Get more context around line 557
echo "=== Context around params.transactions usage (line 557) ==="
sed -n '545,570p' crates/engine-api/src/builder.rs

# Check if MorphPayloadBuilder is called and if it uses txpool
echo -e "\n=== Checking MorphPayloadBuilder usage in build_l2_payload ==="
sed -n '527,600p' crates/engine-api/src/builder.rs | head -80

Repository: morph-l2/morph-reth

Length of output: 3933


🏁 Script executed:

#!/bin/bash
# Check if send_new_payload or best_payload access txpool
echo "=== Checking payload builder methods ==="
rg -nP 'fn send_new_payload|fn best_payload' --type=rust -B2 -A10 crates/payload/builder/src/

# Verify the payload builder is using the supplied transactions
echo -e "\n=== Checking MorphPayloadBuilder build logic ==="
rg -nP 'pub async fn build.*attributes' --type=rust -B2 -A15 crates/payload/builder/src/builder.rs | head -50

Repository: morph-l2/morph-reth

Length of output: 153


Correct the engine_assembleL2Block description — the sequencer supplies all transactions, not just L1 messages.

The AssembleL2BlockParams struct has a single transactions: Vec<Bytes> field where the caller must supply all transactions (both L1 messages and L2 transactions). The handler uses these caller-supplied transactions directly with no txpool interaction. The current description misleads sequencer implementers about how this API works.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@README.md` at line 197, Update the `engine_assembleL2Block` description to
state that the sequencer supplies all transactions (both L1 messages and L2
transactions) via the AssembleL2BlockParams.transactions: Vec<Bytes> field and
that the handler uses these caller-supplied transactions directly with no txpool
interaction; replace the current phrasing that implies only L1 messages are
provided and remove any mention of txpool usage so implementers understand the
sequencer must provide every transaction.

@panos-xyz panos-xyz merged commit 4719acb into main Mar 16, 2026
9 checks passed
@panos-xyz panos-xyz deleted the docs/cleanup-stale-docs branch March 16, 2026 03:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants