feat(l1): tokamak proven execution — phase 0-1.3 foundation#2
Open
feat(l1): tokamak proven execution — phase 0-1.3 foundation#2
Conversation
Complete Phase 0 analysis: evaluate ethrex, Reth, from-scratch, and revm-only options via weighted decision matrix. ethrex fork selected (score 4.85/5) for its custom LEVM, ZK-native architecture, Hook system, and manageable 133K-line codebase. Includes vision, competitive landscape, feature specs, team discussion summaries, Volkov review history, and branch strategy.
- Rebalance decision matrix to ethrex vs Reth binary comparison; move "from scratch" and "revm only" to appendix - Adjust Reth scores: ZK 1→2 (Zeth exists), manageability 2→3 (modular arch acknowledged), sync 5→4 for ethrex (less battle-tested) - Add EXIT criteria with 4 elements: metric, deadline, action, owner - Add Tier S PoC section: perf_opcode_timings build verification and code path analysis - Add JIT technical barriers (dynamic jumps, revmc reference) - Fix weighted sum arithmetic (Reth 2.85→2.80)
Record completed work: DECISION.md creation, Volkov R6 review (6.5/10), three mandatory fixes (matrix rebalance, EXIT criteria, Tier S PoC), Reth/Zeth/ExEx research findings, and next steps for Phase 1.1.
- DECISION.md: DRAFT → FINAL - Replace human staffing model with AI Agent development model - Add bus factor policy (Kevin as interim decision-maker) - Replace staffing risks with agent-specific risks - Remove Senior Rust 2명 EXIT criterion - Add 11 custom commands (.claude/commands/): - Development: /rust, /evm, /jit, /debugger, /l2 - Verification: /quality-gate, /safety-review, /diff-test - Operations: /rebase-upstream, /phase, /bench - Volkov R8: 7.5/10 PROCEED achieved
Architecture analysis documents: - OVERVIEW.md: 25+2 crate dependency graph, node startup flow, CI inventory - LEVM.md: VM struct, execution flow, dual-dispatch loop, hook system - MODIFICATION-POINTS.md: 5 modification points, hybrid isolation strategy - PHASE-1-1.md: Phase 1.1 execution plan with success criteria Phase 1.1 infrastructure: - Skeleton crates: tokamak-jit, tokamak-bench, tokamak-debugger - Feature flag: `tokamak` propagation chain (cmd → vm → levm) - Workspace registration for 3 new crates
- Fix OpcodeTimings: remove false min/max claim, document 4 actual fields - Fix CallFrame: caller→msg_sender, Bytes→Code, return_data→output/sub_return_data - Fix opcode table: describe const fn chaining pattern accurately - Label all pseudocode snippets consistently (JIT, debugger, L2 hook) - Plan feature flag split: tokamak → tokamak-jit/debugger/l2 - Add JIT-VM interface complexity analysis (5 challenges) - Add failure scenarios & mitigations table (5 scenarios) - Record build results: 5m53s clean, 718 tests passed - Fix line count ~133K → ~103K (verified via wc -l) - Add tokamak feature to OVERVIEW.md feature tables
Split monolithic `tokamak` feature into 3 independent features (tokamak-jit, tokamak-debugger, tokamak-l2) with umbrella re-export. Add pr-tokamak.yaml CI workflow for quality-gate and format checks. Update snapsync action default image to tokamak-network/ethrex. Document sync architecture, Hive test matrix, and success criteria.
Add structured benchmark infrastructure to tokamak-bench crate: - timings.rs: reset(), raw_totals(), raw_counts() accessors - tokamak-bench: types, runner, report, regression modules + CLI binary - CI workflow: pr-tokamak-bench.yaml (bench PR vs base, post comparison) - 11 unit tests covering regression detection, JSON roundtrip, reporting
Feature unification causes these modules to be compiled during L2 workspace clippy. Add targeted allows for arithmetic_side_effects, as_conversions, expect_used, and unsafe_code lints.
Add the core JIT tiered compilation modules that were missing from the branch: execution counter, code cache dispatch, types, and module declaration. These provide the lightweight in-process infrastructure gated behind the tokamak-jit feature flag.
- tokamak-jit: compiler, backend, adapter, validation, error modules - JIT backend CI job with LLVM 18 in pr-tokamak.yaml - jit_bench module in tokamak-bench for interpreter vs JIT comparison - Phase 2 architecture documentation - Updated HANDOFF with current status
🤖 Kimi Code ReviewAutomated review by Kimi (Moonshot AI) |
Summary of ChangesHello @cd4761, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! 이 풀 리퀘스트는 Tokamak 이더리움 클라이언트의 기반을 다지는 중요한 진전을 나타냅니다. JIT EVM, 연속 벤치마킹, 타임-트래블 디버거와 같은 핵심 기능을 위한 아키텍처적 토대를 마련하는 데 중점을 두었습니다. 이를 위해 새로운 크레이트와 CI 워크플로우를 도입하고, 기존 LEVM(Lambda EVM)에 JIT 관련 인프라를 통합하며, 프로젝트의 방향과 구현 세부 사항을 명확히 하는 광범위한 문서를 추가했습니다. 이 작업은 향후 Tokamak 클라이언트의 성능, 검증 가능성 및 디버깅 용이성을 향상시키기 위한 초석이 될 것입니다. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Changelog
Ignored Files
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
이 PR은 Tokamak Ethereum 클라이언트의 기반을 마련하는 중요한 작업입니다. JIT 컴파일, 벤치마킹, 디버깅을 위한 새로운 크레이트(tokamak-jit, tokamak-bench, tokamak-debugger)를 도입하고, 기존 ethrex-levm에 JIT 인프라와 벤치마킹을 위한 접근자 메소드를 추가했습니다. 또한, 기능별로 분리된 tokamak-* 피처 플래그와 CI 워크플로우를 설정하여 프로젝트의 구조를 체계적으로 잡았습니다. 전반적으로 코드 품질이 높고, 아키텍처에 대한 깊은 고민이 엿보입니다. 몇 가지 유지보수성 및 잠재적 메모리 누수와 관련된 개선점을 제안했지만, 이는 이 훌륭한 기반 작업의 가치를 훼손하지 않습니다.
Comment on lines
42
to
50
| // SAFETY: The compiled function pointer is stored in CompiledCode | ||
| // which is kept alive in the CodeCache. The LLVM JIT memory backing | ||
| // the function is not freed (no `free_function` call in PoC). | ||
| #[expect(unsafe_code)] | ||
| let f: EvmCompilerFn = unsafe { | ||
| compiler | ||
| .jit(&hash_hex, bytecode, SpecId::CANCUN) | ||
| .map_err(|e| JitError::CompilationFailed(format!("{e}")))? | ||
| }; |
There was a problem hiding this comment.
안전성 주석에 "no free_function call in PoC"라고 언급되어 있는데, 이는 컴파일된 코드가 메모리에서 해제되지 않아 메모리 누수가 발생할 수 있음을 시사합니다. PoC 단계에서는 괜찮을 수 있지만, 프로덕션 환경에서는 반드시 해결해야 할 문제입니다. 향후 JIT 코드 캐시에서 엔트리가 제거될 때 (예: LRU 정책에 의해) 컴파일된 함수 메모리도 함께 해제하는 메커니즘을 설계해야 합니다. revmc가 컴파일된 함수를 해제하는 API를 제공하는지 확인하고, 이를 CodeCache의 invalidate나 Drop 구현과 연동하는 것을 고려해야 합니다.
Comment on lines
+1
to
+5
| #![allow( | ||
| clippy::arithmetic_side_effects, | ||
| clippy::as_conversions, | ||
| clippy::type_complexity | ||
| )] |
There was a problem hiding this comment.
파일 전체에 대해 중요한 clippy lint(특히 arithmetic_side_effects와 as_conversions)를 비활성화하는 것은 잠재적인 버그를 숨길 수 있어 위험합니다. 이 PR에서 추가된 코드는 이 lint들을 발생시키지 않는 것으로 보입니다. 기존 코드의 특정 부분에서 lint가 발생한다면, 해당 라인이나 함수에만 #[allow(...)]를 적용하여 범위를 좁히는 것이 더 안전합니다. 예를 들어, info 함수 내의 count as f64 변환이 원인이라면 해당 표현식에만 lint를 허용하는 것이 좋습니다.
Tokamak Benchmark Results: BaselineNo baseline benchmark found on the base branch. |
Benchmark Results ComparisonNo significant difference was registered for any benchmark run. Detailed ResultsBenchmark Results: BubbleSort
Benchmark Results: ERC20Approval
Benchmark Results: ERC20Mint
Benchmark Results: ERC20Transfer
Benchmark Results: Factorial
Benchmark Results: FactorialRecursive
Benchmark Results: Fibonacci
Benchmark Results: FibonacciRecursive
Benchmark Results: ManyHashes
Benchmark Results: MstoreBench
Benchmark Results: Push
Benchmark Results: SstoreBench_no_opt
|
Add Phase 3 JIT execution wiring so JIT-compiled bytecode actually runs through the VM dispatch instead of only being compiled. Key changes: - JitBackend trait in dispatch.rs for dependency inversion (LEVM defines interface, tokamak-jit implements) - LevmHost: revm Host v14.0 implementation backed by LEVM state (GeneralizedDatabase, Substate, Environment) - Execution bridge: builds revm Interpreter, wraps state in LevmHost, transmutes CompiledCode to EvmCompilerFn, maps result to JitOutcome - vm.rs wiring: try_jit_dispatch() && execute_jit() before interpreter loop, with fallback on failure - register_jit_backend() for startup registration - E2E tests: fibonacci JIT execution + JIT vs interpreter validation (behind revmc-backend feature, requires LLVM 21)
Close 7 gaps preventing production use of the JIT system: - 4A: Propagate is_static from CallFrame to revm Interpreter - 4B: Sync gas refunds after JIT execution, pass storage_original_values through JIT chain for correct SSTORE original vs present value - 4C: Add LRU eviction to CodeCache (VecDeque + max_entries) - 4D: Auto-compile when execution counter hits threshold, add compile() to JitBackend trait and backend() accessor to JitState - 4E: Detect CALL/CREATE/DELEGATECALL/STATICCALL opcodes in analyzer, skip JIT compilation for contracts with external calls - 4F: Skip JIT when tracer is active, add JitMetrics with atomic counters, log fallback events via eprintln
…compilation, and validation Phase 5 addresses three remaining JIT gaps: 5A — Multi-fork support: Cache key changed from H256 to (H256, Fork) so the same bytecode compiled at different forks gets separate cache entries. fork_to_spec_id() adapter added. Hardcoded SpecId::CANCUN removed from compiler, execution, and host — all now use the environment's fork. 5B — Background async compilation: New CompilerThread with std::sync::mpsc channel and a single background thread. On threshold hit, vm.rs tries request_compilation() first (non-blocking); falls back to synchronous compile if no thread is registered. register_jit_backend() now also starts the background compiler thread. 5C — Validation mode wiring: JitConfig.max_validation_runs (default 3) gates logging to first N executions per (hash, fork). JitState tracks validation_counts and logs [JIT-VALIDATE] with gas_used and output_len for offline comparison. Full dual-execution deferred to Phase 6.
M1: CompilerThread now implements Drop — drops sender to signal
shutdown, then joins the background thread. Panics are caught
and logged (no silent swallowing). Fields changed to Option
for take-on-drop pattern.
M2: SELFDESTRUCT (0xFF) added to has_external_calls detection in
analyzer.rs. Bytecodes containing SELFDESTRUCT are now skipped
by the JIT compiler, preventing the incomplete Host::selfdestruct
(missing balance transfer) from being exercised.
M3: Negative gas refund cast fixed in execution.rs. Previously
`refunded as u64` would wrap negative i64 (EIP-3529) to a huge
u64. Now uses `u64::try_from(refunded)` — negative values are
silently ignored (already reflected in gas remaining).
M4: Documented fork assumption in counter.rs and vm.rs. Counter is
keyed by bytecode hash only (not fork). Safe because forks don't
change during a node's runtime; cache miss on new fork falls back
to interpreter.
Update roadmap and status to reflect B-1 completion: negative refund bug fix, 11 gas alignment tests, upstream revmc constant documented. Advance execution order to Week 3 (C-1 + C-2 → B-3).
Add compare_jit() for detecting JIT speedup regressions between PR and base branch (20% threshold). New JitCompare CLI subcommand, JIT regression report types, and markdown output. Add 3 CI jobs to pr-tokamak-bench.yaml: jit-bench-pr, jit-bench-main, compare-jit-results with PR comment integration. LLVM 21 jobs use continue-on-error until C-2 provisioning is complete. 10 new tests covering regression/improvement detection, edge cases (missing scenario, None speedup, multi-scenario), and report output.
Update roadmap, status, and execution order. Phase 9 now ~50% complete. Feature lambdaclass#10 Continuous Benchmarking advances to ~50%. Next: C-2 (LLVM provisioning) and B-3 (EIP-7928 BAL recording).
Extract inline LLVM 21 installation into .github/actions/install-llvm/ composite action. Includes llvm-dev and libpolly-dev packages (fixes Polly linking issue). Update pr-tokamak.yaml and pr-tokamak-bench.yaml to use the new action, removing continue-on-error workaround.
…hs (B-3) Implement Block Access List (BAL) recording in the JIT execution path so that storage reads/writes are tracked identically to the interpreter. - Record storage reads in sload_skip_cold_load() via bal_recorder - Record implicit reads + conditional writes in sstore_skip_cold_load() - Remove 4 TODO comments, replace with architectural notes - Add 5 differential tests (JIT vs interpreter BAL comparison) - Apply cargo fmt to tokamak-jit crate
…fallback (D-2) Add explicit handling for oversized bytecodes (> 24576 bytes, EIP-170) that cannot be JIT-compiled by revmc/LLVM. Previously, compilation would fail silently with repeated cache lookups on every call frame. Changes: - Add negative cache (oversized_hashes FxHashSet) to JitState for O(1) skip of known-oversized bytecodes - Add early size gate in VM dispatch at compilation threshold, preventing compilation attempts before they reach the backend - Add belt-and-suspenders size check in background compiler thread - Return interpreter-only benchmark results instead of silently dropping oversized scenarios (Push/MstoreBench/SstoreBench) - 4 unit tests for oversized cache + 3 integration tests (revmc-gated)
…:is_bytecode_oversized() Replace 4 inline `len > max_bytecode_size` comparisons with a single method on JitConfig. Also update STATUS.md with D-2 completion details.
… pipeline (D-3) Same-length PUSH+PUSH+OP → single wider PUSH replacement preserving bytecode offsets (JUMP targets, basic blocks unchanged). Supports ADD, SUB, MUL, AND, OR, XOR with SUB wrapping edge case handling. - optimizer.rs: detect_patterns() scan + optimize() constant folding - Pipeline integration between analyze_bytecode() and compile() - 37 unit tests + 5 integration tests (42 total for D-3)
… sync verification
- Replace hardcoded lambdaclass/ethrex with ${GITHUB_REPOSITORY} in
snapsync-run action so assertoor can fetch the syncing-check config
from the correct fork (tokamak-network/ethrex)
- Change default build_profile from release to release-with-debug-assertions
so state trie validation (debug_assert!) fires during sync verification
ethrex-sync self-hosted runner is not available on tokamak-network fork. Use GitHub-hosted ubuntu-latest runner with Kurtosis installed via apt. Remove engine-restart job (only needed for persistent self-hosted runner).
Hoodi snap sync on GitHub-hosted runner did not complete within 1h. Both EL and CL remained unsynced for the entire duration (run #22395022810).
…etion - Overall completion 45-50% → 55-60% - JIT feature 75% → 80%, test count 58 → 104 - Remove "Opcode fusion, constant folding" from Remaining - Add D-3 to Recently Completed (Phase D) section - Update codebase line counts (8,743 → 9,657) - Update In Progress: next is E-1 or A-2
…level recording (E-1) LEVM hook infrastructure: - OpcodeRecorder trait in debugger_hook.rs (feature-gated tokamak-debugger) - Stack::peek() for non-destructive stack inspection - Per-opcode callback in interpreter_loop (before advance_pc) tokamak-debugger crate: - DebugRecorder captures opcode, PC, gas, depth, stack top-N, memory size - ReplayEngine with record(), forward(), backward(), goto() navigation - ReplayTrace + StepRecord + ReplayConfig data types - DebuggerError with VM and StepOutOfRange variants 14 tests: basic replay (4), navigation (5), gas tracking (3), nested calls (2)
Member
Author
E-1: Time-Travel TX Replay Engine — CompleteCommit: Added
Verification
Next: E-2 (Debugger CLI) |
Hoodi snap sync passed in 1h48m35s (run 22404315946): - assertoor synced-check: EL + CL both synced - release-with-debug-assertions profile (state trie debug_assert enabled) - ubuntu-latest runner with Kurtosis + Lighthouse v8.0.1 Phase A (Production Foundation) is now 100% complete (A-1 through A-4). Phase 1.2 criteria 9/9 ALL PASS.
… debugger (E-2) Add a REPL-based debugger CLI on top of the E-1 replay engine, gated behind the `cli` feature flag. Supports 13 commands: step, step-back, continue, reverse-continue, break, delete, goto, info, stack, list, breakpoints, help, quit. New files: - src/bin/debugger.rs — binary entry point (clap) - src/cli/mod.rs — Args, InputMode, run(), DB setup - src/cli/commands.rs — Command enum, parse(), execute() - src/cli/formatter.rs — step/info/stack/breakpoints display - src/cli/repl.rs — rustyline REPL loop - src/tests/cli_tests.rs — 27 tests (parsing, formatter, execution) Usage: cargo run -p tokamak-debugger --features cli -- bytecode --code 600360040100
Add `debug_timeTravel` RPC method that replays a transaction at opcode granularity and returns a window of execution steps for time-travel debugging over JSON-RPC. - Extract `prepare_state_for_tx()` from `trace_transaction_calls()` in blockchain/tracing.rs for reuse by the debugger endpoint - Add `Evm::setup_env_for_tx()` wrapper in vm/tracing.rs - Change `LEVM::setup_env` visibility to pub(crate) - Add serde Serialize derives to StepRecord, ReplayTrace, ReplayConfig - Add `opcode_name()` method to StepRecord - Feature-gate behind `tokamak-debugger` in ethrex-rpc - 10 tests: 6 RPC handler + 4 serde round-trip
Add `cross-client` CLI subcommand that compares ethrex execution performance against Geth and Reth using eth_call with state overrides. - ethrex runs in-process (reuses existing runner), external clients via JSON-RPC eth_call with bytecode injected at state override address - New cross_client module: types.rs, runner.rs, report.rs - Markdown report with ethrex as 1.00x baseline, ratio per client - Feature-gated behind `cross-client` (reqwest, tokio, url deps) - 18 tests covering serialization, parsing, reporting
…on (F-4) Add cargo-fuzz harnesses, property-based tests, and unsafe code audit documentation for the JIT compiler. - 3 fuzz targets: analyzer, optimizer, differential (standalone crate) - 4 proptest property tests: never-panics, bounds, length-preserving, convergence (optimizer is NOT single-pass idempotent) - SAFETY_AUDIT.md cataloging all 9 unsafe blocks with risk assessment - Update ROADMAP and STATUS docs to reflect E-3, F-1, F-4 completion
- Rewrite fuzz_differential.rs for actual JIT vs interpreter comparison: generate random EVM bytecode, execute on both paths, compare status/gas/output - Add tokamak-jit as optional dep, wire revmc-backend feature properly - Fallback to interpreter determinism check when LLVM unavailable - Add DASHBOARD-SPEC.md for F-2 public dashboard (clients.tokamak.network): no-backend architecture, 6 pages, 4-phase implementation plan
Astro + React islands + Recharts + Tailwind static site at dashboard/. Fetches benchmark JSON from CI artifacts and displays: - Landing page with metric cards and benchmark table - Historical trends page with scenario selector and CI error bands Includes: - 16 TypeScript interfaces mirroring Rust bench types - Zod schemas with commit hash, timestamp, and path validation - Path traversal protection in fetch layer - 11 React components (MetricCard, StatusBadge, BenchTable, TrendChart, etc.) - rebuild-index.py script for CI data pipeline - publish-dashboard CI job in pr-tokamak-bench.yaml - 62 JS/TS tests (Vitest) + 9 Python tests (unittest)
… flag (F-3) - TokamakFeeConfig + JitPolicy types (crates/common) - TokamakL2Hook wrapping L2Hook via composition (crates/vm/levm) - VMType::TokamakL2 variant + hook dispatch + Evm constructors - BlockchainType::TokamakL2 + 5 match arm updates (blockchain.rs) - --tokamak-l2 CLI flag with env var support - Feature propagation across 6 Cargo.toml files - P256Verify precompile extended via is_l2_type() helper - 7 unit tests (4 fee config serde + 3 hook)
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
8 participants
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.
Summary
Tokamak Ethereum Client의 Phase 0 ~ Phase 1.3 + Phase 2 기반 작업입니다.
tokamak-jit,tokamak-debugger), feature flags, Volkov R8-R10 리뷰(8.25 PROCEED)tokamak-jit/debugger/l2),pr-tokamak.yamlCI 워크플로우, fork CI 조정OpcodeTimingsaccessor methods(reset,raw_totals,raw_counts),tokamak-benchcrate(runner/report/regression),pr-tokamak-bench.yamlCI주요 변경
tokamak-bench,tokamak-jit,tokamak-debugger(skeleton)pr-tokamak.yaml,pr-tokamak-bench.yamltimings.rs— reset/raw accessor methodscrates/vm/levm/src/jit/— types, analyzer, counter, cache, dispatchdocs/tokamak/전체 (DECISION, architecture, features, vision)검증 결과 (로컬)
cargo build --release -p tokamak-bench— OKcargo test -p tokamak-bench— 11 tests passcargo test -p tokamak-jit— 7 tests passcargo check --features tokamak— OKcargo clippy --features tokamak -- -D warnings— OKcargo clippy --workspace --features l2,l2-sql -- -D warnings— OKTest plan
pr-tokamak.yamlQuality Gate 통과pr-tokamak-bench.yamlBenchmark PR 통과cargo check --features tokamak통과cargo test -p tokamak-bench -p tokamak-jit전체 통과