diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000000..2956e61cd3
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,239 @@
+# AGENTS - Sei Chain (Monorepo)
+
+This document is the primary orientation for automated agents operating in
+`/Users/pdrobnjak/sei/sei-chain`.
+
+It reflects the repository as discovered in this working copy and is intended for
+Go-first workflows.
+
+## Scope and project shape
+
+- This repo is a Go workspace defined in `go.work` with these active modules:
+  - `.` (main `sei-chain` module)
+  - `./sei-cosmos`
+- Additional sibling modules include:
+  - `./sei-tendermint`
+  - `./sei-ibc-go`
+  - `./sei-wasmd`
+  - `./sei-wasmvm`
+  - `./sei-db`
+  - `./oracle/price-feeder`
+  - `./sei-iavl`
+- Do not assume one universal command for all modules; treat each module as having
+  its own `Makefile` contract where noted.
+- Go toolchain expectations are documented in `go.mod`/`go.work` files as
+  `go 1.25.6` for main and workspace modules.
+- This document aligns with the root `CLAUDE.md` guidance and repository-specific
+  operational notes.
+
+## Build / lint / test command matrix
+
+### Root module (`sei-chain`)
+
+- `make install`
+  - Installs `./cmd/seid` using module build tags and `-ldflags` from root
+    `Makefile`.
+- `make build`
+  - Build binary to `./build/seid`.
+- `make install-mock-balances`, `make install-bench`,
+  `make install-with-race-detector`
+  - Alternate build variants used in specific CI/dev workflows.
+- `make lint`
+  - Runs `golangci-lint`, gofmt check (`gofmt -d -s`) and `go mod verify`.
+- `make test-group-<N>`
+  - Uses `NUM_SPLIT` (default 4) and package bucketing.
+  - Example: `make test-group-0` or `NUM_SPLIT=8 make test-group-3`.
+- `make clean`
+  - Removes `./build` artifacts.
+
+### Submodule commands that are routinely used
+
+- `make -C sei-cosmos test` (standard)
+- `make -C sei-cosmos test-all`
+- `make -C sei-cosmos lint`
+- `make -C sei-cosmos test-unit`
+- `make -C sei-cosmos test-race`
+- `make -C sei-cosmos test-cover`
+
+- `make -C sei-ibc-go test`
+- `make -C sei-ibc-go test-all`
+
+- `make -C sei-wasmd test` (this target delegates to `test-unit`)
+- `make -C sei-wasmd lint`
+- `make -C sei-wasmd test-cover`
+
+- `make -C sei-tendermint test`
+- `make -C sei-tendermint test-race`
+
+- `make -C sei-db test-all`
+- `make -C sei-db lint-all`
+
+- `make -C oracle/price-feeder test-unit`
+- `make -C oracle/price-feeder lint`
+
+- `make -C sei-iavl test`
+
+### CI-parity baseline commands
+
+These are the command patterns currently used in GitHub workflows:
+
+- `go test -race -tags='ledger test_ledger_mock' -timeout=30m ./...`
+  (root + sei-cosmos modules in CI).
+- `go test -tags='ledger test_ledger_mock' -timeout=30m -covermode=atomic -coverprofile=coverage.out -coverpkg=./... ./...`
+  (coverage jobs).
+- `go test -mod=readonly` appears throughout module makefiles; prefer this flag for
+  CI-grade test and lint parity.
+- `go mod verify` runs in lint/verification flows and should not be skipped when
+  checking dependency integrity.
+
+### Single-test and focused test commands
+
+Use these patterns for quick iteration:
+
+- Single test in a package:
+  - `go test -mod=readonly ./app -run TestStateMachine -count=1`
+- Single test with tags used by this repo:
+  - `go test -mod=readonly -tags='ledger test_ledger_mock' ./app -run TestStateMachine -count=1`
+- Single package with race detector:
+  - `go test -mod=readonly -race ./app -run TestStateMachine -count=1`
+- Single test file style filter (regexp):
+  - `go test ./x/oracle/... -run '^Test.*Price.*$'`
+- Single module focus example:
+  - `go test -mod=readonly -tags='cgo ledger test_ledger_mock' ./...`
+    (when run from `sei-cosmos` or `sei-ibc-go`).
+
+If your change affects a single module, prefer running the command in that module's
+directory to avoid long cross-module test suites.
+
+## Required formatting and import style
+
+- Always keep code formatted with standard gofmt (simplify mode required).
+- All Go files must be gofmt compliant. After editing any `.go` file:
+  - `gofmt -s -w <file>`
+- Quick check:
+  - `gofmt -s -l .`
+- Before commit, run style checks used by project lint:
+  - `gofmt -w -s` style via make targets, and `goimports` where configured.
+- Use import grouping with stdlib first, a blank line, then third-party/internal.
+- Keep local import aliases consistent and avoid unnecessary aliases unless naming
+  collisions require them.
+- Preserve generated file exemptions noted in make rules (for example proto or statik
+  artifacts) unless the change explicitly regenerates them.
+- For deterministic local formatting in Go files, rely on tooling instead of manual
+  alignment.
+
+## Naming and type conventions
+
+- Exported identifiers:
+  - Use `CamelCase` / `PascalCase`.
+  - Keep acronyms in conventional block style (`ID`, `URL`, `JSON`) unless codebase
+    has a local historical exception.
+- Unexported identifiers:
+  - Use `camelCase`.
+- Types and function names should describe domain intent, not implementation detail.
+- Prefer concrete types over `interface{}` at package boundaries.
+- Use enums / constants for stringly-typed domains when possible.
+- Favor struct field names that mirror domain semantics (`WindowSize`, `MaxItems`, etc.)
+  and are self-documenting without excessive comments.
+- Keep receiver names short and consistent per type (`lg`, `cfg`, `app`, `tm`).
+- Prefer constructor functions (`NewXxx`) that return immutable/configured values and
+  validation errors early.
+
+## Error handling conventions
+
+- Return `error` values instead of panicking for expected runtime failures.
+- Wrap context with `%w` when adding call-site context so call stacks remain
+  inspectable with `errors.Is`/`errors.As`.
+- Check and branch on sentinel errors where needed (for example `errors.Is(err,
+  ErrX)`).
+- Use `errors.New` for static messages and `fmt.Errorf("...: %w", err)` for
+  wrapped propagation.
+- Keep early returns readable:
+  - validate inputs first, then execute happy path.
+- Do not suppress errors in deferred blocks unless explicitly documented and
+  intentionally transformed.
+
+## Testing conventions
+
+- Table-driven tests are preferred for behavior matrices.
+- Use helpers marked with `t.Helper()`.
+- For one-off deterministic failures, use `t.Fatalf` / `t.Errorf` with concise
+  context.
+- The codebase commonly uses `require` and `assert` from Testify; use them
+  consistently in new tests.
+- Add focused `-run` regex coverage for single regression checks during development.
+- Include race coverage on concurrent code paths when feasible (`-race`).
+- Avoid flaky wall-clock-based assertions; use deterministic clocks or fake time
+  helpers where available.
+
+## Test and benchmark hygiene
+
+- Prefer running test suites with short timeouts for focused local runs,
+  and increase for simulation/integration paths.
+- For long-running or expensive suites, mark with package-appropriate tags and
+  document why.
+- Keep benchmark changes isolated; use dedicated `benchmark` targets where present.
+- Treat integration/e2e commands as higher-cost and run sparingly in local
+  developer flow unless specifically touching integration surfaces.
+
+## Linting details and practical guidance
+
+- `golangci-lint` is the primary static checker.
+- `line length`, `complexity`, and deep lints are intentionally controlled by
+  repo config; follow existing file patterns if introducing logic that might trigger
+  `prealloc`, `ineffassign`, `errcheck`, `govet`, `staticcheck` and `gosec`.
+- If lint reports style-only import order/formatting drift, run the formatter and
+  rerun lint before pushing.
+- `make lint` in module makefiles often includes both tool install/run and format
+  validation; if it fails on newly modified files, re-run just formatting first
+  then rerun lint.
+
+## Dependency and module hygiene
+
+- Keep module boundaries explicit and run module-local checks with `-mod=readonly`.
+- Use `go mod verify` to validate module cache integrity when touching
+  dependency-sensitive code paths.
+- Do not edit dependency files casually; rely on standard `go` workflows.
+
+## Files and directories commonly edited with caution
+
+- Avoid manual edits in generated/compiled output directories
+  (protobuf, statik, vendored-like generated assets) unless regeneration is the
+  explicit change request.
+- Favor minimal diff footprints in ABI/codec-related files.
+- Keep test fixtures deterministic and preferably immutable once committed.
+
+## Cursor/Copilot rules
+
+- No `.cursor/rules/`, `.cursorrules`, or `.github/copilot-instructions.md`
+  files were found in this repository.
+- If that changes in the future, update this document before large agentic runs.
+
+## AGENTS.md and CLAUDE.md convention
+
+- All agent-facing instructions must live in `AGENTS.md` files, never in `CLAUDE.md`.
+- Each `CLAUDE.md` must contain only a reference to its co-located `AGENTS.md` (e.g., `See [AGENTS.md](AGENTS.md)`).
+- When adding new agent instructions for a directory, create or update the `AGENTS.md` in that directory and ensure a corresponding `CLAUDE.md` exists that points to it.
+- Do not put instructional content directly in `CLAUDE.md` files.
+
+## Quick pre-change checklist for agents
+
+1. Identify target module(s) from changed paths.
+2. Run module-appropriate format/lint commands after edits.
+3. Run focused tests first; then expand to module-wide `test`/`test-all` as needed.
+4. Add/adjust single-test run commands when narrowing regressions.
+5. Re-check `go mod`/dependency integrity if modules are changed.
+
+## File references used for this guide
+
+- `Makefile`
+- `sei-cosmos/Makefile`
+- `sei-ibc-go/Makefile`
+- `sei-wasmd/Makefile`
+- `sei-db/Makefile`
+- `oracle/price-feeder/Makefile`
+- `.golangci.yml`
+- `go.mod`, `go.work`
+- `.github/workflows/go-test.yml`
+- `.github/workflows/go-test-coverage.yml`
+- `README.md`
diff --git a/CLAUDE.md b/CLAUDE.md
index 6a19a87161..971eee93cb 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,23 +1 @@
-# Sei Chain
-
-## Code Style
-
-### Go Formatting
-
-All Go files must be `gofmt` compliant. After modifying any `.go` files, run:
-
-```bash
-gofmt -s -w <file>
-```
-
-Or verify compliance with:
-
-```bash
-gofmt -s -l .
-```
-
-This command should produce no output if all files are properly formatted.
-
-## Benchmarking
-
-See [benchmark/CLAUDE.md](benchmark/CLAUDE.md) for benchmark usage, environment variables, and comparison workflows.
+See [AGENTS.md](AGENTS.md) for agent instructions.
diff --git a/benchmark/AGENTS.md b/benchmark/AGENTS.md
new file mode 100644
index 0000000000..a4da4358be
--- /dev/null
+++ b/benchmark/AGENTS.md
@@ -0,0 +1,188 @@
+# Benchmark
+
+## Single scenario
+
+```bash
+GIGA_EXECUTOR=true GIGA_OCC=true benchmark/benchmark.sh
+```
+
+By default, the benchmark runs for `DURATION=120` seconds, auto-captures all 6 profile types, extracts TPS stats, and exits. Profiles are saved to `/tmp/sei-bench/pprof/`, TPS data to `/tmp/sei-bench/tps.txt`, and the full log to `/tmp/sei-bench/output.log`.
+
+Use `DURATION=0` to run forever (manual capture, original behavior).
+
+TPS is logged every 5s as `tps=<value>` (with ANSI color codes). For manual extraction:
+
+```bash
+sed 's/\x1b\[[0-9;]*m//g' /tmp/sei-bench/output.log | sed -n 's/.*tps=\([0-9.]*\).*/\1/p'
+```
+
+Available scenarios in `benchmark/scenarios/`: `evm.json` (default), `erc20.json`, `mixed.json`, `default.json`.
+
+```bash
+# Use a different scenario
+BENCHMARK_CONFIG=benchmark/scenarios/erc20.json benchmark/benchmark.sh
+```
+
+## Environment variables
+
+### benchmark.sh
+
+| Var | Default | Purpose |
+|-----|---------|---------|
+| `BENCHMARK_PHASE` | `all` | `init` (build+init+configure), `start` (run node), `all` (both) |
+| `SEI_HOME` | `$HOME/.sei` | Final chain data dir. If != ~/.sei, init in ~/.sei then `mv` |
+| `PORT_OFFSET` | `0` | Added to all ports (RPC, P2P, pprof, gRPC, etc.) |
+| `SEID_BIN` | `""` | Pre-built binary path. If set, skip build + copy to ~/go/bin/seid |
+| `LOG_FILE` | `""` | Redirect seid output to file |
+| `BENCHMARK_CONFIG` | `$SCRIPT_DIR/scenarios/evm.json` | Scenario config file (absolute path resolved from script location) |
+| `BENCHMARK_TXS_PER_BATCH` | `1000` | Transactions per batch |
+| `GIGA_EXECUTOR` | `false` | Enable evmone-based EVM executor |
+| `GIGA_OCC` | `false` | Enable OCC for Giga Executor |
+| `DB_BACKEND` | `goleveldb` | Database backend (goleveldb, memdb, cleveldb, rocksdb) |
+| `MOCK_BALANCES` | `true` | Use mock balances during benchmark |
+| `DISABLE_INDEXER` | `true` | Disable indexer for benchmark (reduces I/O overhead) |
+| `DEBUG` | `false` | Print all log output without filtering |
+| `DURATION` | `120` | Auto-stop after N seconds (0 = run forever) |
+
+### benchmark-compare.sh
+
+Inherits all benchmark.sh vars via delegation. Additionally:
+
+| Var | Default | Purpose |
+|-----|---------|---------|
+| `DURATION` | `120` | How long (seconds) to run each node before stopping |
+| `GIGA_EXECUTOR` | **`true`** | Overrides benchmark.sh default (false) |
+| `GIGA_OCC` | **`true`** | Overrides benchmark.sh default (false) |
+| `DB_BACKEND` | `goleveldb` | Forwarded to build and init phases |
+
+**Note:** `GIGA_EXECUTOR` and `GIGA_OCC` default to `true` in the compare script but `false` in benchmark.sh. The compare script is designed for performance comparison where Giga Executor is typically enabled.
+
+## Parallel multi-scenario comparison
+
+Use `benchmark/benchmark-compare.sh` to run multiple git commits side-by-side (minimum 2 scenarios required):
+
+```bash
+benchmark/benchmark-compare.sh \
+  pre-opt=fd2e28d74 \
+  lazy-cms=82acf458d \
+  lazy-cms-fix=37a17fd02
+```
+
+Each scenario gets its own binary, home dir, and port set (offset by 100). Results are printed at the end with median/avg/min/max TPS. Raw data in `/tmp/sei-bench/<label>/tps.txt`.
+
+## Comparing results across sessions
+
+**Important:** Cross-session benchmark numbers (TPS, total allocs) are not directly comparable. Only comparisons within the same `benchmark-compare.sh` run are valid, since all scenarios share identical conditions.
+
+## Profiling
+
+### Available profile types
+
+Both `benchmark.sh` (when `DURATION > 0`) and `benchmark-compare.sh` automatically capture all profile types midway through the run. Profiles are saved to `/tmp/sei-bench/pprof/` (single-scenario) or `/tmp/sei-bench/<label>/pprof/` (compare).
+
+| Profile | File | What it shows |
+|---------|------|---------------|
+| CPU | `cpu.pb.gz` | On-CPU time only (computation, hashing, EVM execution) |
+| fgprof | `fgprof.pb.gz` | Wall-clock time: on-CPU + off-CPU (I/O, blocking, GC pauses) |
+| Heap | `heap.pb.gz` | Memory allocations (analyzable with multiple metrics, see below) |
+| Goroutine | `goroutine.pb.gz` | Goroutine stacks (find pileups and leaks) |
+| Block | `block.pb.gz` | Time waiting on channel ops and mutex locks |
+| Mutex | `mutex.pb.gz` | Mutex contention (where goroutines fight over locks) |
+
+**CPU vs fgprof:** Go's built-in CPU profiler uses OS-level `SIGPROF` signals delivered only to running threads — goroutines waiting on I/O, channels, or locks are invisible. fgprof samples all goroutines via `runtime.GoroutineProfile` regardless of scheduling state, showing the full wall-clock picture. Use CPU when you suspect pure computation is the bottleneck; use fgprof when TPS is low but CPU utilization is also low (points to I/O or contention).
+
+**Block and mutex profiles** require `runtime.SetBlockProfileRate` and `runtime.SetMutexProfileFraction` to be enabled. Both are automatically enabled when seid is built with the `benchmark` build tag (`make install-bench`). They are disabled in production builds.
+
+### Capturing profiles during single-scenario runs
+
+When `DURATION > 0` (default), `benchmark.sh` automatically captures all 6 profile types midway through the run. Profiles are saved to `/tmp/sei-bench/pprof/`.
+
+When `DURATION=0` (run-forever mode), capture manually in another terminal:
+
+```bash
+PPROF_PORT=6060  # adjust with PORT_OFFSET if set
+
+# 30-second CPU profile
+go tool pprof -http=:8080 "http://localhost:$PPROF_PORT/debug/pprof/profile?seconds=30"
+
+# 30-second fgprof (wall-clock)
+go tool pprof -http=:8080 "http://localhost:$PPROF_PORT/debug/fgprof?seconds=30"
+
+# Heap snapshot
+go tool pprof -http=:8080 "http://localhost:$PPROF_PORT/debug/pprof/heap"
+
+# Goroutine dump
+go tool pprof -http=:8080 "http://localhost:$PPROF_PORT/debug/pprof/goroutine"
+
+# Block profile
+go tool pprof -http=:8080 "http://localhost:$PPROF_PORT/debug/pprof/block"
+
+# Mutex contention
+go tool pprof -http=:8080 "http://localhost:$PPROF_PORT/debug/pprof/mutex"
+```
+
+### Comparing profiles (diff)
+
+Always use `pprof -diff_base` to compare profiles between benchmark runs. Never compare profiles side-by-side manually.
+
+```bash
+# CPU diff (positive = regression, negative = improvement)
+go tool pprof -top -diff_base /tmp/sei-bench/<baseline>/pprof/cpu.pb.gz /tmp/sei-bench/<candidate>/pprof/cpu.pb.gz
+
+# Wall-clock diff (fgprof)
+go tool pprof -top -diff_base /tmp/sei-bench/<baseline>/pprof/fgprof.pb.gz /tmp/sei-bench/<candidate>/pprof/fgprof.pb.gz
+
+# Allocation diff (total bytes allocated over time)
+go tool pprof -alloc_space -top -diff_base /tmp/sei-bench/<baseline>/pprof/heap.pb.gz /tmp/sei-bench/<candidate>/pprof/heap.pb.gz
+
+# Heap escape diff (objects that should be stack-allocated)
+go tool pprof -alloc_objects -top -diff_base /tmp/sei-bench/<baseline>/pprof/heap.pb.gz /tmp/sei-bench/<candidate>/pprof/heap.pb.gz
+```
+
+### Heap profile metrics
+
+The heap profile contains multiple metrics. Choose the right one for your question:
+
+| Metric | Flag | Use when |
+|--------|------|----------|
+| Active memory | `-inuse_space` | Finding memory leaks or high RSS |
+| Active objects | `-inuse_objects` | Finding what's holding memory right now |
+| Total allocated bytes | `-alloc_space` | Finding hot allocation paths (GC pressure) |
+| Total allocated objects | `-alloc_objects` | Finding heap escapes (objects that should live on the stack) |
+
+### Interactive analysis and flamegraphs
+
+Text output (`-top`) is useful for quick comparisons, but the web UI with flamegraphs is far more effective for navigating large profiles.
+
+```bash
+# Interactive web UI with flamegraphs
+go tool pprof -http=:8080 /tmp/sei-bench/<label>/pprof/cpu.pb.gz
+
+# Diff flamegraph (red = regression, blue = improvement)
+go tool pprof -http=:8080 -diff_base /tmp/sei-bench/<baseline>/pprof/cpu.pb.gz /tmp/sei-bench/<candidate>/pprof/cpu.pb.gz
+```
+
+For drilling into specific functions, use the interactive CLI:
+
+```bash
+go tool pprof /tmp/sei-bench/<label>/pprof/cpu.pb.gz
+(pprof) top20 --cum          # sort by cumulative time (default flat hides expensive callees)
+(pprof) list DeliverTx       # line-by-line source attribution
+(pprof) web DeliverTx        # SVG graph focused on one function's callers/callees
+```
+
+Run `go tool pprof` from the sei-chain repo root so that `list` and `web` commands can resolve source file paths.
+
+## Optimization loop
+
+Full iteration cycle for profiling, optimizing, and validating performance changes:
+
+1. **Profile:** Run `benchmark/benchmark.sh` (auto-captures all 6 profile types, extracts TPS, exits)
+2. **Analyze:** Inspect profiles with `go tool pprof -top -cum /tmp/sei-bench/pprof/cpu.pb.gz` (repeat for fgprof, heap with `-alloc_space`, goroutine, block, mutex)
+3. **Flamegraphs:** Open interactive UIs for cpu, fgprof, and heap on separate ports: `go tool pprof -http=:8080 /tmp/sei-bench/pprof/cpu.pb.gz &`, `go tool pprof -http=:8081 /tmp/sei-bench/pprof/fgprof.pb.gz &`, `go tool pprof -http=:8082 /tmp/sei-bench/pprof/heap.pb.gz &`
+4. **Summarize:** Present findings to user — biggest bottleneck, candidate optimizations, expected impact, and trade-offs
+5. **Discuss:** Ask the user which optimization direction to pursue before writing any code. The user picks the approach or suggests an alternative
+6. **Implement:** Make the optimization, commit
+7. **Compare:** Run `benchmark/benchmark-compare.sh baseline=<before-commit> candidate=<after-commit>`
+8. **Validate:** Open diff flamegraphs for the user (`go tool pprof -http=:808X -diff_base <baseline> <candidate> &` for cpu, fgprof, heap). Present a CLI summary of TPS delta and profile regressions/improvements. Ask the user whether to open a PR
+9. **PR** if user approves
diff --git a/benchmark/CLAUDE.md b/benchmark/CLAUDE.md
index a4da4358be..249447dcc1 100644
--- a/benchmark/CLAUDE.md
+++ b/benchmark/CLAUDE.md
@@ -1,188 +1 @@
-# Benchmark
-
-## Single scenario
-
-```bash
-GIGA_EXECUTOR=true GIGA_OCC=true benchmark/benchmark.sh
-```
-
-By default, the benchmark runs for `DURATION=120` seconds, auto-captures all 6 profile types, extracts TPS stats, and exits. Profiles are saved to `/tmp/sei-bench/pprof/`, TPS data to `/tmp/sei-bench/tps.txt`, and the full log to `/tmp/sei-bench/output.log`.
-
-Use `DURATION=0` to run forever (manual capture, original behavior).
-
-TPS is logged every 5s as `tps=<value>` (with ANSI color codes). For manual extraction:
-
-```bash
-sed 's/\x1b\[[0-9;]*m//g' /tmp/sei-bench/output.log | sed -n 's/.*tps=\([0-9.]*\).*/\1/p'
-```
-
-Available scenarios in `benchmark/scenarios/`: `evm.json` (default), `erc20.json`, `mixed.json`, `default.json`.
-
-```bash
-# Use a different scenario
-BENCHMARK_CONFIG=benchmark/scenarios/erc20.json benchmark/benchmark.sh
-```
-
-## Environment variables
-
-### benchmark.sh
-
-| Var | Default | Purpose |
-|-----|---------|---------|
-| `BENCHMARK_PHASE` | `all` | `init` (build+init+configure), `start` (run node), `all` (both) |
-| `SEI_HOME` | `$HOME/.sei` | Final chain data dir. If != ~/.sei, init in ~/.sei then `mv` |
-| `PORT_OFFSET` | `0` | Added to all ports (RPC, P2P, pprof, gRPC, etc.) |
-| `SEID_BIN` | `""` | Pre-built binary path. If set, skip build + copy to ~/go/bin/seid |
-| `LOG_FILE` | `""` | Redirect seid output to file |
-| `BENCHMARK_CONFIG` | `$SCRIPT_DIR/scenarios/evm.json` | Scenario config file (absolute path resolved from script location) |
-| `BENCHMARK_TXS_PER_BATCH` | `1000` | Transactions per batch |
-| `GIGA_EXECUTOR` | `false` | Enable evmone-based EVM executor |
-| `GIGA_OCC` | `false` | Enable OCC for Giga Executor |
-| `DB_BACKEND` | `goleveldb` | Database backend (goleveldb, memdb, cleveldb, rocksdb) |
-| `MOCK_BALANCES` | `true` | Use mock balances during benchmark |
-| `DISABLE_INDEXER` | `true` | Disable indexer for benchmark (reduces I/O overhead) |
-| `DEBUG` | `false` | Print all log output without filtering |
-| `DURATION` | `120` | Auto-stop after N seconds (0 = run forever) |
-
-### benchmark-compare.sh
-
-Inherits all benchmark.sh vars via delegation. Additionally:
-
-| Var | Default | Purpose |
-|-----|---------|---------|
-| `DURATION` | `120` | How long (seconds) to run each node before stopping |
-| `GIGA_EXECUTOR` | **`true`** | Overrides benchmark.sh default (false) |
-| `GIGA_OCC` | **`true`** | Overrides benchmark.sh default (false) |
-| `DB_BACKEND` | `goleveldb` | Forwarded to build and init phases |
-
-**Note:** `GIGA_EXECUTOR` and `GIGA_OCC` default to `true` in the compare script but `false` in benchmark.sh. The compare script is designed for performance comparison where Giga Executor is typically enabled.
-
-## Parallel multi-scenario comparison
-
-Use `benchmark/benchmark-compare.sh` to run multiple git commits side-by-side (minimum 2 scenarios required):
-
-```bash
-benchmark/benchmark-compare.sh \
-  pre-opt=fd2e28d74 \
-  lazy-cms=82acf458d \
-  lazy-cms-fix=37a17fd02
-```
-
-Each scenario gets its own binary, home dir, and port set (offset by 100). Results are printed at the end with median/avg/min/max TPS. Raw data in `/tmp/sei-bench/<label>/tps.txt`.
-
-## Comparing results across sessions
-
-**Important:** Cross-session benchmark numbers (TPS, total allocs) are not directly comparable. Only comparisons within the same `benchmark-compare.sh` run are valid, since all scenarios share identical conditions.
-
-## Profiling
-
-### Available profile types
-
-Both `benchmark.sh` (when `DURATION > 0`) and `benchmark-compare.sh` automatically capture all profile types midway through the run. Profiles are saved to `/tmp/sei-bench/pprof/` (single-scenario) or `/tmp/sei-bench/<label>/pprof/` (compare).
-
-| Profile | File | What it shows |
-|---------|------|---------------|
-| CPU | `cpu.pb.gz` | On-CPU time only (computation, hashing, EVM execution) |
-| fgprof | `fgprof.pb.gz` | Wall-clock time: on-CPU + off-CPU (I/O, blocking, GC pauses) |
-| Heap | `heap.pb.gz` | Memory allocations (analyzable with multiple metrics, see below) |
-| Goroutine | `goroutine.pb.gz` | Goroutine stacks (find pileups and leaks) |
-| Block | `block.pb.gz` | Time waiting on channel ops and mutex locks |
-| Mutex | `mutex.pb.gz` | Mutex contention (where goroutines fight over locks) |
-
-**CPU vs fgprof:** Go's built-in CPU profiler uses OS-level `SIGPROF` signals delivered only to running threads — goroutines waiting on I/O, channels, or locks are invisible. fgprof samples all goroutines via `runtime.GoroutineProfile` regardless of scheduling state, showing the full wall-clock picture. Use CPU when you suspect pure computation is the bottleneck; use fgprof when TPS is low but CPU utilization is also low (points to I/O or contention).
-
-**Block and mutex profiles** require `runtime.SetBlockProfileRate` and `runtime.SetMutexProfileFraction` to be enabled. Both are automatically enabled when seid is built with the `benchmark` build tag (`make install-bench`). They are disabled in production builds.
-
-### Capturing profiles during single-scenario runs
-
-When `DURATION > 0` (default), `benchmark.sh` automatically captures all 6 profile types midway through the run. Profiles are saved to `/tmp/sei-bench/pprof/`.
-
-When `DURATION=0` (run-forever mode), capture manually in another terminal:
-
-```bash
-PPROF_PORT=6060  # adjust with PORT_OFFSET if set
-
-# 30-second CPU profile
-go tool pprof -http=:8080 "http://localhost:$PPROF_PORT/debug/pprof/profile?seconds=30"
-
-# 30-second fgprof (wall-clock)
-go tool pprof -http=:8080 "http://localhost:$PPROF_PORT/debug/fgprof?seconds=30"
-
-# Heap snapshot
-go tool pprof -http=:8080 "http://localhost:$PPROF_PORT/debug/pprof/heap"
-
-# Goroutine dump
-go tool pprof -http=:8080 "http://localhost:$PPROF_PORT/debug/pprof/goroutine"
-
-# Block profile
-go tool pprof -http=:8080 "http://localhost:$PPROF_PORT/debug/pprof/block"
-
-# Mutex contention
-go tool pprof -http=:8080 "http://localhost:$PPROF_PORT/debug/pprof/mutex"
-```
-
-### Comparing profiles (diff)
-
-Always use `pprof -diff_base` to compare profiles between benchmark runs. Never compare profiles side-by-side manually.
-
-```bash
-# CPU diff (positive = regression, negative = improvement)
-go tool pprof -top -diff_base /tmp/sei-bench/<baseline>/pprof/cpu.pb.gz /tmp/sei-bench/<candidate>/pprof/cpu.pb.gz
-
-# Wall-clock diff (fgprof)
-go tool pprof -top -diff_base /tmp/sei-bench/<baseline>/pprof/fgprof.pb.gz /tmp/sei-bench/<candidate>/pprof/fgprof.pb.gz
-
-# Allocation diff (total bytes allocated over time)
-go tool pprof -alloc_space -top -diff_base /tmp/sei-bench/<baseline>/pprof/heap.pb.gz /tmp/sei-bench/<candidate>/pprof/heap.pb.gz
-
-# Heap escape diff (objects that should be stack-allocated)
-go tool pprof -alloc_objects -top -diff_base /tmp/sei-bench/<baseline>/pprof/heap.pb.gz /tmp/sei-bench/<candidate>/pprof/heap.pb.gz
-```
-
-### Heap profile metrics
-
-The heap profile contains multiple metrics. Choose the right one for your question:
-
-| Metric | Flag | Use when |
-|--------|------|----------|
-| Active memory | `-inuse_space` | Finding memory leaks or high RSS |
-| Active objects | `-inuse_objects` | Finding what's holding memory right now |
-| Total allocated bytes | `-alloc_space` | Finding hot allocation paths (GC pressure) |
-| Total allocated objects | `-alloc_objects` | Finding heap escapes (objects that should live on the stack) |
-
-### Interactive analysis and flamegraphs
-
-Text output (`-top`) is useful for quick comparisons, but the web UI with flamegraphs is far more effective for navigating large profiles.
-
-```bash
-# Interactive web UI with flamegraphs
-go tool pprof -http=:8080 /tmp/sei-bench/<label>/pprof/cpu.pb.gz
-
-# Diff flamegraph (red = regression, blue = improvement)
-go tool pprof -http=:8080 -diff_base /tmp/sei-bench/<baseline>/pprof/cpu.pb.gz /tmp/sei-bench/<candidate>/pprof/cpu.pb.gz
-```
-
-For drilling into specific functions, use the interactive CLI:
-
-```bash
-go tool pprof /tmp/sei-bench/<label>/pprof/cpu.pb.gz
-(pprof) top20 --cum          # sort by cumulative time (default flat hides expensive callees)
-(pprof) list DeliverTx       # line-by-line source attribution
-(pprof) web DeliverTx        # SVG graph focused on one function's callers/callees
-```
-
-Run `go tool pprof` from the sei-chain repo root so that `list` and `web` commands can resolve source file paths.
-
-## Optimization loop
-
-Full iteration cycle for profiling, optimizing, and validating performance changes:
-
-1. **Profile:** Run `benchmark/benchmark.sh` (auto-captures all 6 profile types, extracts TPS, exits)
-2. **Analyze:** Inspect profiles with `go tool pprof -top -cum /tmp/sei-bench/pprof/cpu.pb.gz` (repeat for fgprof, heap with `-alloc_space`, goroutine, block, mutex)
-3. **Flamegraphs:** Open interactive UIs for cpu, fgprof, and heap on separate ports: `go tool pprof -http=:8080 /tmp/sei-bench/pprof/cpu.pb.gz &`, `go tool pprof -http=:8081 /tmp/sei-bench/pprof/fgprof.pb.gz &`, `go tool pprof -http=:8082 /tmp/sei-bench/pprof/heap.pb.gz &`
-4. **Summarize:** Present findings to user — biggest bottleneck, candidate optimizations, expected impact, and trade-offs
-5. **Discuss:** Ask the user which optimization direction to pursue before writing any code. The user picks the approach or suggests an alternative
-6. **Implement:** Make the optimization, commit
-7. **Compare:** Run `benchmark/benchmark-compare.sh baseline=<before-commit> candidate=<after-commit>`
-8. **Validate:** Open diff flamegraphs for the user (`go tool pprof -http=:808X -diff_base <baseline> <candidate> &` for cpu, fgprof, heap). Present a CLI summary of TPS delta and profile regressions/improvements. Ask the user whether to open a PR
-9. **PR** if user approves
+See [AGENTS.md](AGENTS.md) for benchmark instructions.
diff --git a/benchmark/analysis/executeEVMTxWithGigaExecutor.md b/benchmark/analysis/executeEVMTxWithGigaExecutor.md
new file mode 100644
index 0000000000..c8f8700ec6
--- /dev/null
+++ b/benchmark/analysis/executeEVMTxWithGigaExecutor.md
@@ -0,0 +1,157 @@
+# Profiling Analysis: executeEVMTxWithGigaExecutor
+
+**Date:** 2026-02-13
+**Branch:** pd/benchmark-profiling-improvements (commit dcbfd5a02)
+**Scenario:** benchmark/scenarios/evm.json
+**Config:** GIGA_EXECUTOR=true GIGA_OCC=true DURATION=120
+
+## Baseline
+
+| Metric | Value |
+|--------|-------|
+| Median TPS | 8600 |
+| Avg TPS | 8495 |
+| Min TPS | 7800 |
+| Max TPS | 9000 |
+| Readings | 21 |
+| Block Height | 995 |
+
+## Function Hot Path
+
+```
+executeEVMTxWithGigaExecutor (app/app.go:1714)
+  ├─ msg.AsTransaction()
+  ├─ RecoverSenderFromEthTx()          — ECDSA recovery
+  ├─ GetEVMAddress() / AssociateAddresses()
+  ├─ NewDBImpl()                       — allocates state DB + initial Snapshot
+  │   └─ Snapshot()                    — clones entire CacheMultiStore
+  ├─ GetVMBlockContext()
+  ├─ GetParams() + ChainID() (x2)     — redundant: ChainID called at lines 1721 and 1764
+  ├─ NewGethExecutor() → vm.NewEVM()  — new EVM per tx
+  ├─ ExecuteTransaction()
+  │   └─ ApplyMessage() → StateTransition.Execute()
+  │       └─ EVM.Call() — may trigger additional Snapshot() calls
+  ├─ stateDB.Finalize()               — flushCtxs → cachekv.Store.Write
+  ├─ WriteReceipt()
+  └─ Marshal response (protobuf)
+```
+
+## CPU Profile (30s sample, 120.21s total across 4 cores)
+
+`executeEVMTxWithGigaExecutor`: **25.95s cumulative (21.6%)**
+
+| Component | Cumulative | % of total | Notes |
+|-----------|-----------|------------|-------|
+| runtime.lock2 (spinlock) | 36.87s | 30.7% | OCC goroutines fighting for locks |
+| runtime.usleep (lock backoff) | 30.00s | 25.0% | Spinning on contended locks |
+| ExecuteTransaction → ApplyMessage | 15.31s | 12.7% | Actual EVM execution |
+| GC (gcDrain + scanobject) | 17.15s + 11.49s | 23.8% | Driven by allocation pressure |
+| mallocgc | 11.42s | 9.5% | Object allocation |
+| runtime.kevent | 10.38s | 8.6% | I/O polling |
+
+### CPU Focused on executeEVMTxWithGigaExecutor
+
+Top flat contributors within the function's call tree:
+
+| Function | Flat | Notes |
+|----------|------|-------|
+| runtime.usleep | 4.95s | Lock spinning inside store operations |
+| runtime.cgocall | 3.09s | CGo boundary (likely crypto) |
+| runtime.mallocgc | 6.31s | Allocation pressure from stores |
+| runtime.newobject | 3.72s | Heap allocations |
+| memiavl.MemNode.Get | 1.00s | IAVL tree reads |
+| cachekv.Store.Write | 1.03s | Flushing cache stores |
+| cachemulti.newCacheMultiStoreFromCMS | 1.22s | CMS creation during Snapshot |
+
+## Heap Profile (alloc_space)
+
+`executeEVMTxWithGigaExecutor`: **56.2 GB cumulative (54% of 104 GB total)**
+
+| Hotspot | Allocated | % of function | What |
+|---------|----------|--------------|------|
+| DBImpl.Snapshot → CacheMultiStore | 15.1 GB | 27% | Full cache store clone per snapshot |
+| cachekv.NewStore | 9.0 GB | 16% | Individual KV store objects (sync.Map x2-3) |
+| sync.newIndirectNode (sync.Map internals) | 7.8 GB | 14% | sync.Map internal trie nodes |
+| cachekv.Store.Write | 8.4 GB | 15% | Flushing stores (map iteration + write) |
+| DBImpl.Finalize → flushCtxs | 9.7 GB | 17% | Writing state changes back through layers |
+| GetBalance → LockedCoins | 9.0 GB | 16% | Balance lookups triggering deep store reads |
+| AccountKeeper.GetAccount | 7.2 GB | 13% | Account deserialization (protobuf UnpackAny) |
+| scheduler.prepareTask | 8.8 GB | 16% | OCC task preparation (VersionIndexedStore) |
+
+### Allocation Objects
+
+| Hotspot | Objects | % of total | Notes |
+|---------|---------|------------|-------|
+| cachekv.NewStore | 157M | 10.2% | Largest single flat allocator |
+| cachekv.Store.Write | 83M | 5.4% | Map iteration during flush |
+| codec/types.UnpackAny | 134M | 8.7% | Protobuf deserialization |
+| DBImpl.Snapshot | 137M | 8.9% | CMS + maps + sync primitives |
+
+## Mutex/Contention Profile (196s total)
+
+| Source | Time | % | What |
+|--------|------|---|------|
+| runtime.unlock | 159s | 81% | Runtime-level lock contention |
+| sync.Mutex.Unlock | 29s | 15% | Application mutex contention |
+| sync.RWMutex.Unlock | 19s | 10% | Reader-writer lock contention |
+| AccAddress.String | 10.6s | 5% | Bech32 encoding under lock |
+| EventManager.EmitEvents | 9.9s | 5% | Event emission contention |
+| sync.Map.Store (HashTrieMap.Swap) | 6.9s | 4% | sync.Map write contention |
+
+## Block Profile (7.26 hrs total)
+
+Dominated by `runtime.selectgo` (6.97 hrs / 96%) — the OCC scheduler's `select` loop waiting for tasks. Not actionable for this function.
+
+## Key Findings
+
+### 1. CacheMultiStore allocation is the #1 optimization target
+
+Each `Snapshot()` call triggers `CacheMultiStore()` which:
+- Materializes ALL lazy module stores (not just ones the tx touches)
+- Creates `cachekv.NewStore` with 2-3 `sync.Map` objects per module store
+- Creates `gigacachekv.NewStore` with 2 `sync.Map` objects per giga store
+- Allocates map copies, sync.RWMutex, sync.Once per CMS
+
+This happens at minimum once per tx (NewDBImpl's initial Snapshot), plus additional times for nested EVM calls. OCC re-executions create entirely fresh chains.
+
+### 2. GC overhead is a direct consequence of allocation pressure
+
+17s of CPU on `gcDrain` + 11.5s on `scanobject` = ~24% of CPU spent on GC. The 104 GB of total allocations over 30s creates enormous GC pressure. Reducing allocations in the Snapshot path would have a compounding effect.
+
+### 3. Lock contention is high but may be secondary
+
+`runtime.lock2` at 30.7% is the #1 CPU consumer. Much of this is runtime-internal (GC, scheduler) and would decrease naturally if allocation pressure drops. Some is from `sync.Map` operations and store-level mutexes.
+
+### 4. ChainID() and DefaultChainConfig() called redundantly
+
+`ChainID()` is called at lines 1721 and 1764. `DefaultChainConfig()` is called inside `RecoverSenderFromEthTx` and again implicitly at line 1764. Minor but free to fix.
+
+## Candidate Optimizations
+
+### A. Pool/reuse cachekv.Store objects (high impact)
+
+Replace fresh `cachekv.NewStore` allocations with `sync.Pool` recycling. On return to pool, call `sync.Map.Clear()` (Go 1.23+) to reset state. Eliminates ~9 GB of allocations + reduces GC.
+
+**Expected impact:** 10-20% TPS improvement
+**Risk:** Low — mechanical change, clear lifecycle boundaries
+
+### B. Lazy per-store creation in snapshots (high impact)
+
+Currently `materializeOnce.Do` creates cachekv.Store for ALL module stores when any snapshot is taken. Instead, create wrappers only for stores actually accessed via GetKVStore.
+
+**Expected impact:** 10-15% TPS improvement (depends on how many stores are unused per tx)
+**Risk:** Medium — changes cachemulti.Store threading model
+
+### C. Replace sync.Map with regular map in giga cachekv (medium impact)
+
+The giga `cachekv.Store` uses `sync.Map` but within OCC, each store belongs to a single goroutine's execution. Regular maps are ~10x cheaper to allocate and access.
+
+**Expected impact:** 5-10% TPS improvement
+**Risk:** Low — need to verify no concurrent access in OCC path
+
+### D. Cache block-level constants per-tx (low impact)
+
+Cache `ChainID()`, `DefaultChainConfig()`, `GetParams()`, `EthereumConfigWithSstore()` at block level instead of computing per-tx.
+
+**Expected impact:** 2-5% TPS improvement
+**Risk:** Minimal
diff --git a/giga/tests/AGENTS.md b/giga/tests/AGENTS.md
new file mode 100644
index 0000000000..6159c8310b
--- /dev/null
+++ b/giga/tests/AGENTS.md
@@ -0,0 +1,190 @@
+# State Tests Documentation
+
+## Overview
+
+This directory contains state tests that compare Giga vs V2 EVM execution.
+
+- **Test data location:** `giga/tests/data/`
+- **Skip list:** `giga/tests/data/skip_list.json`
+
+## Running Tests
+
+### Basic Commands
+
+```bash
+# Run all non-skipped tests
+go test -v -run TestGigaVsV2_StateTests ./giga/tests/...
+
+# Run specific category
+STATE_TEST_DIR=stExample go test -v -run TestGigaVsV2_StateTests ./giga/tests/...
+
+# Run specific test within category
+STATE_TEST_DIR=stExample STATE_TEST_NAME=add11 go test -v -run TestGigaVsV2_StateTests ./giga/tests/...
+
+# Ignore skip list (run skipped tests)
+IGNORE_SKIP_LIST=true STATE_TEST_DIR=stCreate2 go test -v -run TestGigaVsV2_StateTests ./giga/tests/...
+
+# Use regular KVStore (for debugging)
+USE_REGULAR_STORE=true STATE_TEST_DIR=stChainId go test -v -run TestGigaVsV2_StateTests ./giga/tests/...
+```
+
+## Running Tests in Parallel (Best Practices)
+
+### Critical Learnings
+
+- Running too many parallel test processes causes PebbleDB panics
+- Limit to **2-4 parallel test processes** maximum
+- Use `-timeout 20m` or longer for large categories
+- Categories that timeout at 20min: stPreCompiledContracts, stStaticCall, stBadOpcode, stEIP1559, stQuadraticComplexityTest, stTimeConsuming
+
+### Recommended Approach
+
+```bash
+# Run 2-3 categories in parallel with timeouts
+STATE_TEST_DIR=stCategory1 go test -v -run TestGigaVsV2_StateTests ./giga/tests/... -timeout 30m 2>&1 | tee /tmp/results_stCategory1.log &
+STATE_TEST_DIR=stCategory2 go test -v -run TestGigaVsV2_StateTests ./giga/tests/... -timeout 30m 2>&1 | tee /tmp/results_stCategory2.log &
+wait
+```
+
+## Extracting Failing Test Names
+
+### From test output logs
+
+```bash
+# Count passes and failures
+grep -e "PASS:" results.log | grep "stCategory" | wc -l
+grep -e "FAIL:" results.log | grep "stCategory" | wc -l
+
+# List specific failing tests (shows test name)
+grep -e "FAIL:" results.log | grep "stCategory"
+
+# Check for specific failure types in output
+grep "gas_mismatch\|result_code\|state_mismatch\|balance_mismatch" results.log
+```
+
+## Skip List Format
+
+**File:** `giga/tests/data/skip_list.json`
+
+```json
+{
+  "skipped_tests": {
+    "category/relPath.json/FullTestNameFromJSON/index": "reason"
+  },
+  "skipped_categories": [
+    "stTimeConsuming"
+  ],
+  "skipped_category_reasons": {
+    "stCategory": "ANALYZED: X/Y tests pass. N failures: type1(count), type2(count)"
+  }
+}
+```
+
+### Test Name Format for `skipped_tests`
+
+The test name key must match the exact format used internally. Get the correct format from the test summary output:
+
+```bash
+# Run tests and look for failure summary lines starting with "- category/..."
+grep -E "^\s+- category/" /tmp/results.log
+```
+
+**Format:** `category/relPath/FullJSONKey/index`
+
+- `category` - The STATE_TEST_DIR value (e.g., `Shanghai`, `stTransactionTest`)
+- `relPath` - Relative path from category dir to the .json file (e.g., `subdir/test.json` or just `test.json`)
+- `FullJSONKey` - The full key from inside the JSON file (includes `GeneralStateTests/...`)
+- `index` - Optional subtest index (e.g., `/5`) if the test has multiple post states
+
+**Examples:**
+
+```json
+{
+  "skipped_tests": {
+    "Shanghai/stEIP3651-warmcoinbase/coinbaseWarmAccountCallGas.json/GeneralStateTests/Shanghai/stEIP3651-warmcoinbase/coinbaseWarmAccountCallGas.json::coinbaseWarmAccountCallGas-fork_[Cancun-Prague]-d[0-7]g0v0/5": "gas_mismatch",
+    "stTransactionTest/HighGasPriceParis.json/GeneralStateTests/stTransactionTest/HighGasPriceParis.json::HighGasPriceParis-fork_[Cancun-Prague]-d0g0v0": "fee_out_of_bound"
+  }
+}
+```
+
+### Per-test vs Per-category skipping
+
+- Use `skipped_tests` for specific failing tests (allows passing tests to run)
+- Use `skipped_categories` only for categories not yet analyzed or with extensive failures
+- `skipped_category_reasons` tracks analysis status (use "ENABLED:" prefix for categories with individual test skips)
+
+## Failure Types
+
+| Type | Description |
+|------|-------------|
+| `result_code` | Transaction success/failure mismatch |
+| `gas_mismatch` | Gas calculation differences |
+| `state_mismatch` | Storage value differences |
+| `balance_mismatch` | Balance differences |
+| `code_mismatch` | Contract code differences |
+| `nonce_mismatch` | Account nonce differences |
+| `v2_error` | V2 execution error |
+| `giga_error` | Giga execution error |
+
+## Test Categories Status
+
+### Categories with 100% pass rate (removed from skip list)
+
+- stExample, stSLoadTest, stChainId, stCodeCopyTest, stExpectSection, stEIP158Specific
+- stLogTests, stShift, stHomesteadSpecific, stAttackTest, stRecursiveCreate
+
+### Categories enabled with individual test skips
+
+- Shanghai (26/27 passing, 1 skipped)
+- stArgsZeroOneBalance (91/96 passing, 5 skipped)
+- stTransactionTest (248/259 passing, 11 skipped)
+- stSpecialTest (21/22 passing, 1 skipped)
+- stSolidityTest (21/23 passing, 2 skipped)
+- stNonZeroCallsTest (21/24 passing, 3 skipped)
+- stRefundTest (23/26 passing, 3 skipped)
+- stWalletTest (41/46 passing, 5 skipped)
+- stEIP150singleCodeGasPrices (422/450 passing, 28 skipped)
+
+### Categories needing longer timeout (>20min)
+
+- stPreCompiledContracts, stStaticCall, stBadOpcode, stEIP1559
+- stQuadraticComplexityTest, stTimeConsuming
+
+## Workflow for Analyzing New Categories
+
+1. **Run test with `IGNORE_SKIP_LIST=true`:**
+   ```bash
+   IGNORE_SKIP_LIST=true STATE_TEST_DIR=stNewCategory go test -v -run TestGigaVsV2_StateTests ./giga/tests/... -timeout 30m 2>&1 | tee /tmp/results.log
+   ```
+
+2. **Extract results:**
+   ```bash
+   PASSES=$(grep -e "PASS:" /tmp/results.log | grep "stNewCategory" | wc -l)
+   FAILS=$(grep -e "FAIL:" /tmp/results.log | grep "stNewCategory" | wc -l)
+   echo "Pass: $PASSES, Fail: $FAILS"
+   ```
+
+3. **If 100% pass:** Remove from `skipped_categories`
+
+4. **If failures:** Extract failing test names from summary output and add to `skipped_tests`:
+   ```bash
+   # Get exact test names from the summary section
+   grep -E "^\s+- stNewCategory/" /tmp/results.log
+   ```
+
+5. **Update skip_list.json:**
+   - Add failing tests to `skipped_tests` with failure reason
+   - Remove category from `skipped_categories`
+   - Update `skipped_category_reasons` with "ENABLED:" prefix and summary
+
+6. **Verify tests pass:**
+   ```bash
+   STATE_TEST_DIR=stNewCategory go test -v -run TestGigaVsV2_StateTests ./giga/tests/... -timeout 10m
+   ```
+
+7. **Commit and push after each batch:**
+   ```bash
+   git add giga/tests/data/skip_list.json
+   git commit -m "Enable stNewCategory state tests (X/Y passing)"
+   git push
+   ```
diff --git a/giga/tests/CLAUDE.md b/giga/tests/CLAUDE.md
index 6159c8310b..1462647389 100644
--- a/giga/tests/CLAUDE.md
+++ b/giga/tests/CLAUDE.md
@@ -1,190 +1 @@
-# State Tests Documentation
-
-## Overview
-
-This directory contains state tests that compare Giga vs V2 EVM execution.
-
-- **Test data location:** `giga/tests/data/`
-- **Skip list:** `giga/tests/data/skip_list.json`
-
-## Running Tests
-
-### Basic Commands
-
-```bash
-# Run all non-skipped tests
-go test -v -run TestGigaVsV2_StateTests ./giga/tests/...
-
-# Run specific category
-STATE_TEST_DIR=stExample go test -v -run TestGigaVsV2_StateTests ./giga/tests/...
-
-# Run specific test within category
-STATE_TEST_DIR=stExample STATE_TEST_NAME=add11 go test -v -run TestGigaVsV2_StateTests ./giga/tests/...
-
-# Ignore skip list (run skipped tests)
-IGNORE_SKIP_LIST=true STATE_TEST_DIR=stCreate2 go test -v -run TestGigaVsV2_StateTests ./giga/tests/...
-
-# Use regular KVStore (for debugging)
-USE_REGULAR_STORE=true STATE_TEST_DIR=stChainId go test -v -run TestGigaVsV2_StateTests ./giga/tests/...
-```
-
-## Running Tests in Parallel (Best Practices)
-
-### Critical Learnings
-
-- Running too many parallel test processes causes PebbleDB panics
-- Limit to **2-4 parallel test processes** maximum
-- Use `-timeout 20m` or longer for large categories
-- Categories that timeout at 20min: stPreCompiledContracts, stStaticCall, stBadOpcode, stEIP1559, stQuadraticComplexityTest, stTimeConsuming
-
-### Recommended Approach
-
-```bash
-# Run 2-3 categories in parallel with timeouts
-STATE_TEST_DIR=stCategory1 go test -v -run TestGigaVsV2_StateTests ./giga/tests/... -timeout 30m 2>&1 | tee /tmp/results_stCategory1.log &
-STATE_TEST_DIR=stCategory2 go test -v -run TestGigaVsV2_StateTests ./giga/tests/... -timeout 30m 2>&1 | tee /tmp/results_stCategory2.log &
-wait
-```
-
-## Extracting Failing Test Names
-
-### From test output logs
-
-```bash
-# Count passes and failures
-grep -e "PASS:" results.log | grep "stCategory" | wc -l
-grep -e "FAIL:" results.log | grep "stCategory" | wc -l
-
-# List specific failing tests (shows test name)
-grep -e "FAIL:" results.log | grep "stCategory"
-
-# Check for specific failure types in output
-grep "gas_mismatch\|result_code\|state_mismatch\|balance_mismatch" results.log
-```
-
-## Skip List Format
-
-**File:** `giga/tests/data/skip_list.json`
-
-```json
-{
-  "skipped_tests": {
-    "category/relPath.json/FullTestNameFromJSON/index": "reason"
-  },
-  "skipped_categories": [
-    "stTimeConsuming"
-  ],
-  "skipped_category_reasons": {
-    "stCategory": "ANALYZED: X/Y tests pass. N failures: type1(count), type2(count)"
-  }
-}
-```
-
-### Test Name Format for `skipped_tests`
-
-The test name key must match the exact format used internally. Get the correct format from the test summary output:
-
-```bash
-# Run tests and look for failure summary lines starting with "- category/..."
-grep -E "^\s+- category/" /tmp/results.log
-```
-
-**Format:** `category/relPath/FullJSONKey/index`
-
-- `category` - The STATE_TEST_DIR value (e.g., `Shanghai`, `stTransactionTest`)
-- `relPath` - Relative path from category dir to the .json file (e.g., `subdir/test.json` or just `test.json`)
-- `FullJSONKey` - The full key from inside the JSON file (includes `GeneralStateTests/...`)
-- `index` - Optional subtest index (e.g., `/5`) if the test has multiple post states
-
-**Examples:**
-
-```json
-{
-  "skipped_tests": {
-    "Shanghai/stEIP3651-warmcoinbase/coinbaseWarmAccountCallGas.json/GeneralStateTests/Shanghai/stEIP3651-warmcoinbase/coinbaseWarmAccountCallGas.json::coinbaseWarmAccountCallGas-fork_[Cancun-Prague]-d[0-7]g0v0/5": "gas_mismatch",
-    "stTransactionTest/HighGasPriceParis.json/GeneralStateTests/stTransactionTest/HighGasPriceParis.json::HighGasPriceParis-fork_[Cancun-Prague]-d0g0v0": "fee_out_of_bound"
-  }
-}
-```
-
-### Per-test vs Per-category skipping
-
-- Use `skipped_tests` for specific failing tests (allows passing tests to run)
-- Use `skipped_categories` only for categories not yet analyzed or with extensive failures
-- `skipped_category_reasons` tracks analysis status (use "ENABLED:" prefix for categories with individual test skips)
-
-## Failure Types
-
-| Type | Description |
-|------|-------------|
-| `result_code` | Transaction success/failure mismatch |
-| `gas_mismatch` | Gas calculation differences |
-| `state_mismatch` | Storage value differences |
-| `balance_mismatch` | Balance differences |
-| `code_mismatch` | Contract code differences |
-| `nonce_mismatch` | Account nonce differences |
-| `v2_error` | V2 execution error |
-| `giga_error` | Giga execution error |
-
-## Test Categories Status
-
-### Categories with 100% pass rate (removed from skip list)
-
-- stExample, stSLoadTest, stChainId, stCodeCopyTest, stExpectSection, stEIP158Specific
-- stLogTests, stShift, stHomesteadSpecific, stAttackTest, stRecursiveCreate
-
-### Categories enabled with individual test skips
-
-- Shanghai (26/27 passing, 1 skipped)
-- stArgsZeroOneBalance (91/96 passing, 5 skipped)
-- stTransactionTest (248/259 passing, 11 skipped)
-- stSpecialTest (21/22 passing, 1 skipped)
-- stSolidityTest (21/23 passing, 2 skipped)
-- stNonZeroCallsTest (21/24 passing, 3 skipped)
-- stRefundTest (23/26 passing, 3 skipped)
-- stWalletTest (41/46 passing, 5 skipped)
-- stEIP150singleCodeGasPrices (422/450 passing, 28 skipped)
-
-### Categories needing longer timeout (>20min)
-
-- stPreCompiledContracts, stStaticCall, stBadOpcode, stEIP1559
-- stQuadraticComplexityTest, stTimeConsuming
-
-## Workflow for Analyzing New Categories
-
-1. **Run test with `IGNORE_SKIP_LIST=true`:**
-   ```bash
-   IGNORE_SKIP_LIST=true STATE_TEST_DIR=stNewCategory go test -v -run TestGigaVsV2_StateTests ./giga/tests/... -timeout 30m 2>&1 | tee /tmp/results.log
-   ```
-
-2. **Extract results:**
-   ```bash
-   PASSES=$(grep -e "PASS:" /tmp/results.log | grep "stNewCategory" | wc -l)
-   FAILS=$(grep -e "FAIL:" /tmp/results.log | grep "stNewCategory" | wc -l)
-   echo "Pass: $PASSES, Fail: $FAILS"
-   ```
-
-3. **If 100% pass:** Remove from `skipped_categories`
-
-4. **If failures:** Extract failing test names from summary output and add to `skipped_tests`:
-   ```bash
-   # Get exact test names from the summary section
-   grep -E "^\s+- stNewCategory/" /tmp/results.log
-   ```
-
-5. **Update skip_list.json:**
-   - Add failing tests to `skipped_tests` with failure reason
-   - Remove category from `skipped_categories`
-   - Update `skipped_category_reasons` with "ENABLED:" prefix and summary
-
-6. **Verify tests pass:**
-   ```bash
-   STATE_TEST_DIR=stNewCategory go test -v -run TestGigaVsV2_StateTests ./giga/tests/... -timeout 10m
-   ```
-
-7. **Commit and push after each batch:**
-   ```bash
-   git add giga/tests/data/skip_list.json
-   git commit -m "Enable stNewCategory state tests (X/Y passing)"
-   git push
-   ```
+See [AGENTS.md](AGENTS.md) for state test instructions.