feat(l1): tokamak proven execution — phase 0-1.3 foundation

.claude/commands/bench.md

@@ -0,0 +1,34 @@
+# Benchmark Runner
+
+`perf_opcode_timings` 기반 벤치마크를 실행하고 결과를 분석한다.
+
+## 실행 순서
+
+1. `cargo build --release --features perf_opcode_timings` 빌드
+2. 빌드 성공 확인
+3. 벤치마크 실행 (가능한 경우):
+   - 테스트넷(Holesky) 블록 실행으로 타이밍 수집
+   - 또는 EF 테스트 벡터로 opcode 타이밍 수집
+4. `RUST_LOG=info` 환경에서 출력 파싱
+5. 결과 분석:
+   - 가장 느린 opcode Top 10
+   - 이전 실행 대비 회귀(regression) 감지
+   - SSTORE/SLOAD/CALL 등 핵심 opcode 타이밍 변화
+
+## 회귀 감지 기준
+
+- 개별 opcode 평균 시간이 이전 대비 20%+ 증가: WARNING
+- 개별 opcode 평균 시간이 이전 대비 50%+ 증가: REGRESSION
+- 전체 블록 실행 시간이 이전 대비 10%+ 증가: REGRESSION
+
+## 보고 형식
+
+```
+[BENCH] {STABLE|WARNING|REGRESSION}
+- build: perf_opcode_timings={success|failed}
+- top 10 slowest opcodes:
+  1. {OPCODE}  {avg_time}  ({call_count} calls)
+  ...
+- regressions: {none | list with % change}
+- total block time: {duration}
+```

.claude/commands/debugger.md

@@ -0,0 +1,77 @@
+# Time-Travel Debugger Developer
+
+Time-Travel Debugger 전문 개발자 모드. opcode별 state snapshot, 트랜잭션 리플레이, RPC endpoint에 특화.
+
+## 역할
+
+ethrex의 LevmCallTracer를 확장하여 opcode 단위 Time-Travel Debugging을 구현한다.
+
+## 기존 인프라
+
+```rust
+// crates/vm/levm/src/tracing.rs
+pub struct LevmCallTracer {
+    // 현재: call-level 트레이싱
+    // 확장: opcode-level state snapshot 추가
+}
+```
+
+## 구현 설계
+
+### 1. State Snapshot 구조
+
+```rust
+pub struct OpcodeSnapshot {
+    pub pc: usize,
+    pub opcode: Opcode,
+    pub stack: Vec<U256>,     // 스택 상태
+    pub memory: Vec<u8>,      // 메모리 상태 (선택적, 큰 데이터)
+    pub storage_changes: Vec<(Address, U256, U256)>,  // (addr, key, value)
+    pub gas_remaining: u64,
+    pub gas_used: u64,
+}
+
+pub struct TxTimeline {
+    pub tx_hash: B256,
+    pub snapshots: Vec<OpcodeSnapshot>,
+    pub total_opcodes: usize,
+}
+```
+
+### 2. 확장 포인트
+
+```rust
+// vm.rs — run_execution() 루프 내
+loop {
+    let opcode = self.current_call_frame.next_opcode();
+    // ← snapshot 캡처 포인트
+    let op_result = match opcode { ... };
+    // ← post-execution snapshot
+}
+```
+
+### 3. RPC Endpoint
+
+```
+debug_timeTravel(tx_hash, opcode_index) → OpcodeSnapshot
+debug_timeTravelRange(tx_hash, start, end) → Vec<OpcodeSnapshot>
+debug_timeTravelSearch(tx_hash, condition) → Vec<OpcodeSnapshot>
+```
+
+## 작업 흐름
+
+1. LevmCallTracer 분석 → 확장 포인트 식별
+2. OpcodeSnapshot 구조체 구현
+3. run_execution() 루프에 snapshot 캡처 통합
+4. RPC endpoint 구현
+5. CLI 디버거 인터페이스
+6. 메모리 사용량 최적화 (lazy snapshot, COW)
+
+## 주의사항
+
+- Phase 2 (Month 3-4)에 착수
+- snapshot 캡처는 성능 오버헤드 → feature flag로 격리
+- 메모리 사용량 주의: 대형 트랜잭션은 수천 개 opcode → snapshot 압축 필요
+- 기존 `debug_traceTransaction` RPC와 호환성 유지
+
+$ARGUMENTS

.claude/commands/diff-test.md

@@ -0,0 +1,40 @@
+# Differential Testing
+
+ethrex와 Geth의 실행 결과를 비교하여 불일치를 탐지한다.
+Continuous Benchmarking(Tier S #10)의 핵심 검증 메커니즘이자
+Agent 생성 코드의 최종 안전장치.
+
+## 목적
+
+- Agent가 수정한 EVM 코드가 합의를 위반하지 않는지 검증
+- Geth/Reth와의 state root 불일치 탐지
+- Agent ↔ Agent 리뷰의 순환 참조 방지 (외부 기준점으로 Geth 사용)
+
+## 실행 순서
+
+1. `crates/vm/levm/` 하위 파일이 변경되었는지 확인
+   - 변경 없으면 "EVM 미변경 — diff test 생략" 출력 후 종료
+2. `cargo build --release` (ethrex 빌드)
+3. Ethereum execution-spec-tests 또는 Hive 테스트 중 subset 실행:
+   - `cargo test -p levm` — LEVM 유닛 테스트
+   - EF 테스트 벡터가 있으면 실행하여 state root 비교
+4. 결과 비교:
+   - state root 일치: PASS
+   - state root 불일치: FAIL — 불일치 트랜잭션/블록 식별
+
+## 불일치 발견 시
+
+1. 불일치 트랜잭션의 opcode trace 비교
+2. 어디서 분기하는지 식별 (opcode 단위)
+3. 원인 분석: Tokamak 수정 vs upstream 버그 vs 테스트 오류
+4. upstream 버그 발견 시 → 이슈 리포트 준비 (Sahil의 R4 전략)
+
+## 보고 형식
+
+```
+[DIFF TEST] {PASS|FAIL|SKIP}
+- EVM changed: {yes|no}
+- tests run: {N}
+- state root matches: {N/N}
+- mismatches: {0 | details}
+```

.claude/commands/evm.md

@@ -0,0 +1,60 @@
+# EVM Specialist
+
+LEVM(ethrex 자체 EVM) 전문 개발자 모드. opcode 구현, 실행 루프 수정, 가스 계산, state 관리에 특화.
+
+## 역할
+
+LEVM의 EVM 실행 로직을 수정하거나 확장한다.
+
+## LEVM 아키텍처
+
+```
+crates/vm/levm/src/
+  vm.rs          — VM 구조체 + run_execution() 메인 루프 (line 528-663)
+  opcodes.rs     — build_opcode_table() (line 385), fork별 opcode 테이블
+  opcode_handlers/
+    *.rs         — opcode별 핸들러 구현
+  gas_cost.rs    — 가스 비용 계산
+  call_frame.rs  — CallFrame (스택, 메모리, PC)
+  hooks/
+    hook.rs      — Hook trait 정의
+    l1_hook.rs   — L1 Hook
+    l2_hook.rs   — L2 Hook (844줄, 참조 구현)
+  tracing.rs     — LevmCallTracer
+  timings.rs     — OpcodeTimings (perf_opcode_timings feature)
+```
+
+## 메인 실행 루프 구조
+
+```rust
+// vm.rs:528-663 (run_execution)
+loop {
+    let opcode = self.current_call_frame.next_opcode();
+    // ... gas 체크 ...
+    let op_result = match opcode {
+        Opcode::STOP => { /* ... */ }
+        Opcode::ADD => { /* ... */ }
+        // ... 모든 opcode ...
+    };
+    // ... 결과 처리 ...
+}
+```
+
+## 작업 흐름
+
+1. 수정 대상 opcode/로직 파악
+2. 관련 핸들러 파일과 테스트 확인
+3. 구현 (기존 핸들러 패턴 준수)
+4. `cargo test -p levm` 통과
+5. 가스 비용이 변경되었으면 EIP 스펙과 대조
+6. `/diff-test` 실행 권장 (state root 비교)
+
+## 주의사항
+
+- opcode 핸들러는 반드시 EIP 스펙에 따라 구현
+- fork별 분기는 `build_opcode_table()`에서 관리
+- 가스 계산 변경은 합의에 직접 영향 — 반드시 테스트
+- `perf_opcode_timings` feature와의 호환성 확인
+- 스택 오버플로우/언더플로우 경계 케이스 처리
+
+$ARGUMENTS

.claude/commands/jit.md

@@ -0,0 +1,59 @@
+# JIT Compiler Developer
+
+EVM JIT 컴파일러 전문 개발자 모드. Cranelift 기반 JIT, tiered execution, opcode fusion에 특화.
+
+## 역할
+
+LEVM의 인터프리터 위에 JIT 컴파일 계층을 구현한다.
+
+## Tiered Execution 설계
+
+```
+Tier 0 (Interpreter): 현재 run_execution() — 수정 없이 사용
+Tier 1 (Baseline JIT): opcode → 네이티브 코드 1:1 변환
+Tier 2 (Optimizing JIT): opcode fusion + 최적화
+```
+
+## 삽입 포인트
+
+```rust
+// vm.rs — run_execution() 메인 루프
+loop {
+    let opcode = self.current_call_frame.next_opcode();
+    // ← Tier 1: 여기서 JIT 캐시 확인 → 있으면 네이티브 코드 실행
+    let op_result = match opcode { ... };
+}
+
+// opcodes.rs:385 — build_opcode_table()
+// ← Tier 2: fork별 테이블을 JIT 캐시로 대체
+```
+
+## 핵심 기술적 장벽
+
+1. **동적 점프 (JUMP, JUMPI)**: 점프 대상이 런타임에 결정됨 → basic block 경계 사전 확정 불가
+2. **합의 보장**: JIT 결과가 인터프리터와 100% 일치해야 함
+3. **revmc 참조**: revm JIT 프로젝트의 선행 연구 참조 필수
+
+## Validation Mode
+
+모든 JIT 실행 결과를 인터프리터와 비교:
+- 일치: JIT 결과 사용 (성능 이득)
+- 불일치: 인터프리터 결과 사용 + 불일치 로깅 + JIT 캐시 무효화
+
+## 작업 흐름
+
+1. 대상 opcode/basic block 식별
+2. Cranelift IR로 변환 로직 구현
+3. 네이티브 코드 생성 + 캐시
+4. validation mode에서 인터프리터 결과와 비교
+5. EF 테스트 스위트 100% 통과 확인
+6. `/bench`로 성능 측정
+
+## 주의사항
+
+- Phase 3 (Month 5-7)에 착수. 그 전에는 설계/연구만
+- 합의 위반은 CRITICAL — validation mode 없이 메인넷 배포 금지
+- `unsafe` 사용 불가피 — 모든 unsafe에 `// SAFETY:` 필수
+- `/diff-test` 통과가 최종 게이트
+
+$ARGUMENTS

.claude/commands/l2.md

@@ -0,0 +1,55 @@
+# L2 Hook Developer
+
+Tokamak L2 Hook 시스템 전문 개발자 모드. VMType 확장, Hook 구현, fee 구조에 특화.
+
+## 역할
+
+ethrex의 Hook 시스템을 확장하여 Tokamak L2 기능을 구현한다.
+
+## Hook 아키텍처
+
+```rust
+// vm.rs:38-44
+pub enum VMType {
+    L1,
+    L2(FeeConfig),
+    // 추가 예정: TokamakL2(TokamakFeeConfig)
+}
+
+// hooks/hook.rs — Hook trait
+pub trait Hook {
+    fn prepare_execution(&self, ...) -> ...;
+    fn finalize_execution(&self, ...) -> ...;
+}
+
+// hooks/hook.rs:19-24
+pub fn get_hooks(vm_type: &VMType) -> Vec<Rc<RefCell<dyn Hook + 'static>>> {
+    match vm_type {
+        VMType::L1 => l1_hooks(),
+        VMType::L2(fee_config) => l2_hooks(*fee_config),
+    }
+}
+```
+
+## 참조 구현
+
+`crates/vm/levm/src/hooks/l2_hook.rs` (844줄)이 완전한 L2 Hook 구현.
+이것을 기반으로 TokamakL2Hook을 구현한다.
+
+## 구현 로드맵 (Phase 4)
+
+1. `TokamakFeeConfig` 구조체 정의
+2. `VMType::TokamakL2(TokamakFeeConfig)` 추가
+3. `TokamakL2Hook` — `Hook` trait 구현
+4. `get_hooks()`에 매핑 추가
+5. `--tokamak-l2` CLI 플래그
+6. 테스트: L2 트랜잭션 실행 + fee 계산 검증
+
+## 주의사항
+
+- 기존 L1/L2 Hook은 수정하지 않는다 (upstream 호환성)
+- Tokamak 전용 코드는 `tokamak` feature flag 또는 별도 모듈
+- fee 구조 변경은 경제 모델 검증 필요
+- `prepare_execution()`과 `finalize_execution()` 양쪽 모두 구현
+
+$ARGUMENTS

.claude/commands/phase.md

@@ -0,0 +1,45 @@
+# Phase Management
+
+현재 Phase 상태를 확인하고, 다음 Phase 진입 조건을 검증한다.
+
+## Phase 정의
+
+| Phase | 내용 | 기간 | 진입 조건 |
+|-------|------|------|-----------|
+| 1.1 | Fork & 환경 구축 | Week 1-2 | DECISION.md FINAL |
+| 1.2 | 메인넷 동기화 + Hive | Week 3-6 | Phase 1.1 완료, 빌드 성공 |
+| 1.3 | Continuous Benchmarking MVP | Week 7-10 | 메인넷 싱크 완료, Hive 95%+ |
+| 2 | Time-Travel Debugger | Month 3-4 | Phase 1.3 완료 |
+| 3 | JIT EVM | Month 5-7 | Phase 2 완료, diff-test PASS |
+| 4 | Tokamak L2 통합 | Month 8-10 | Phase 3 완료 |
+
+## 실행 순서
+
+1. `docs/tokamak/scaffold/HANDOFF.md` 읽어서 현재 Phase 파악
+2. 현재 Phase의 완료 조건 체크:
+   - Phase 1.1: `cargo build --workspace` 성공 + CI 파이프라인 존재
+   - Phase 1.2: 메인넷 싱크 로그 + Hive 통과율 95%+
+   - Phase 1.3: 벤치마크 러너 동작 + Geth 대비 비교 데이터
+   - Phase 2: `debug_timeTravel` RPC 구현 + 테스트
+   - Phase 3: JIT Tier 0+1 + EF 테스트 100% + `/diff-test` PASS
+   - Phase 4: `--tokamak-l2` 플래그 동작 + L2 Hook 테스트
+3. 다음 Phase 진입 조건 충족 여부 판정
+4. HANDOFF.md 업데이트
+
+## EXIT 기준 체크 (Phase와 무관하게 항상 확인)
+
+| 수치 | 기한 | 현재 상태 |
+|------|------|-----------|
+| 메인넷 풀 싱크 | 4개월 | {확인} |
+| Hive 95%+ | 6개월 | {확인} |
+| 30일 업타임 | 6개월 | {확인} |
+
+## 보고 형식
+
+```
+[PHASE] Current: {N.N} — {상태}
+- completion: {X/Y criteria met}
+- next phase ready: {yes|no}
+- EXIT criteria: {all clear | WARNING: ...}
+- blockers: {none | list}
+```