docs: add CLAUDE.md and update README structure #6
There are no files selected for viewing
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,67 @@ | ||
| # CLAUDE.md | ||
|
|
||
| This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. | ||
|
|
||
| ## Common Development Commands | ||
|
|
||
| ### Building | ||
| - **Release build**: `make build` | ||
| - **Debug build**: `make build-dev` | ||
| - **Build all workspace members**: `make build-all` | ||
|
|
||
| ### Testing | ||
| - **Run all tests**: `make test` | ||
| - **Run tests with output**: `make test-verbose` | ||
| - **Unit tests only**: `make test-unit` | ||
| - **Integration tests**: `make test-integration` | ||
| - **Test specific crate**: `make test-node`, `make test-rollkit`, `make test-common` | ||
|
|
||
| ### Code Quality | ||
| - **Format code**: `make fmt` | ||
| - **Check formatting**: `make fmt-check` | ||
| - **Run linter**: `make lint` | ||
| - **Run all checks**: `make check-all` | ||
|
|
||
| ### Running the Node | ||
| - **Run with defaults**: `make run` | ||
| - **Run with debug logs**: `make run-dev` | ||
| - **Direct execution**: `./target/release/lumen node --chain <CHAIN_SPEC> --datadir <DATA_DIR> --http --ws` | ||
|
|
||
| ## High-Level Architecture | ||
|
|
||
| Lumen is a specialized Ethereum execution client built on Reth that integrates with Rollkit. The key architectural innovation is accepting transactions directly through the Engine API instead of the traditional mempool. | ||
|
|
||
| ### Core Components | ||
|
|
||
| 1. **RollkitPayloadBuilder** (`crates/node/src/builder.rs`) | ||
| - Accepts transactions from Engine API payload attributes | ||
| - Executes transactions and builds blocks | ||
| - Manages state transitions | ||
|
|
||
| 2. **RollkitEngineTypes** (`bin/lumen/src/main.rs`) | ||
| - Custom Engine API types supporting transaction submission | ||
| - Handles payload attribute validation and processing | ||
|
|
||
| 3. **RollkitEngineValidator** (`bin/lumen/src/main.rs`) | ||
| - Modified validator that bypasses certain checks for Rollkit compatibility | ||
| - Maintains security while allowing flexible block production | ||
|
|
||
| ### Transaction Flow | ||
| 1. Rollkit submits transactions via `engine_forkchoiceUpdatedV3` with transactions in payload attributes | ||
| 2. Transactions are decoded from RLP format and validated | ||
| 3. Payload builder executes transactions against current state | ||
| 4. Block is constructed and returned via Engine API | ||
|
|
||
| ### Key Design Decisions | ||
| - Transactions bypass the mempool entirely, submitted directly via Engine API | ||
| - Block validation is relaxed for Rollkit-produced blocks (hash validation bypassed) | ||
| - Custom gas limits can be specified per payload | ||
| - Modular workspace structure separates concerns between general node logic and Rollkit-specific features | ||
|
|
||
| ### Testing Strategy | ||
| - Unit tests for individual components | ||
| - Integration tests in `crates/tests/` covering: | ||
| - Engine API interactions | ||
| - Payload building with transactions | ||
| - State execution validation | ||
| - Rollkit-specific scenarios | ||
|
Contributor
There was a problem hiding this comment. It's a good practice to end files with a newline character. This can prevent issues with file concatenation and diffs. |
||
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
Oops, something went wrong.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The
Makefiledefines several useful Docker-related commands (docker-build,docker-build-push, etc.). It would be valuable to document these under a new### Dockersubsection within the "Common Development Commands" section.