tools/gasbench: per-opcode EVM gas-vs-execution-time differential microbenchmark (F2 MVP)

AGENTS.md

@@ -14,6 +14,7 @@ progressively the deeper you go. Existing package guides include:
 - `evmrpc/AGENTS.md` — EVM JSON-RPC (`eth_*`, `sei_*`, `sei2_*`, `debug_*`) semantics
 - `x/evm/AGENTS.md` — EVM module: address association, StateDB bridge, precompiles, pointers
 - `sei-tendermint/AGENTS.md` — sei-tendermint module conventions
+- `tools/gasbench/AGENTS.md` — per-opcode gas-vs-time differential microbenchmark harness
 
 ## Code style
 

Makefile

@@ -566,3 +566,7 @@ test-group-%:split-test-packages
 		PARALLEL="-parallel=4"; \
 	fi; \
 	cat $(BUILDDIR)/packages.txt.$* | xargs go test $$PARALLEL -mod=readonly -timeout=10m -race -coverprofile=$*.profile.out -covermode=atomic -coverpkg=./...
+
+.PHONY: gasbench
+gasbench: ## Run the compute-opcode microbench (pin core via GASBENCH_CORE)
+	./tools/gasbench/run.sh

go.mod

@@ -98,6 +98,7 @@ require (
 	golang.org/x/crypto v0.47.0
 	golang.org/x/exp v0.0.0-20260112195511-716be5621a96
 	golang.org/x/net v0.49.0
+	golang.org/x/perf v0.0.0-20230113213139-801c7ef9e5c5
 	golang.org/x/sync v0.19.0
 	golang.org/x/sys v0.40.0
 	golang.org/x/time v0.13.0
@@ -112,6 +113,7 @@ require (
 require (
 	dario.cat/mergo v1.0.0 // indirect
 	github.com/ProtonMail/go-crypto v1.1.6 // indirect
+	github.com/aclements/go-moremath v0.0.0-20210112150236-f10218a38794 // indirect
 	github.com/cloudflare/circl v1.6.3 // indirect
 	github.com/cyphar/filepath-securejoin v0.4.1 // indirect
 	github.com/emirpasic/gods v1.18.1 // indirect

go.sum

@@ -659,6 +659,7 @@ github.com/VictoriaMetrics/fastcache v1.12.2/go.mod h1:AmC+Nzz1+3G2eCPapF6UcsnkT
 github.com/VividCortex/gohistogram v1.0.0/go.mod h1:Pf5mBqqDxYaXu3hDrrU+w6nw50o/4+TcAqDqk/vUH7g=
 github.com/Zilliqa/gozilliqa-sdk v1.2.1-0.20201201074141-dd0ecada1be6/go.mod h1:eSYp2T6f0apnuW8TzhV3f6Aff2SE8Dwio++U4ha4yEM=
 github.com/aclements/go-gg v0.0.0-20170118225347-6dbb4e4fefb0/go.mod h1:55qNq4vcpkIuHowELi5C8e+1yUHtoLoOUR9QU5j7Tes=
+github.com/aclements/go-moremath v0.0.0-20210112150236-f10218a38794 h1:xlwdaKcTNVW4PtpQb8aKA4Pjy0CdJHEqvFbAnvR5m2g=
 github.com/aclements/go-moremath v0.0.0-20210112150236-f10218a38794/go.mod h1:7e+I0LQFUI9AXWxOfsQROs9xPhoJtbsyWcjJqDd4KPY=
 github.com/aclements/go-perfevent v0.0.0-20240301234650-f7843625020f h1:JjxwchlOepwsUWcQwD2mLUAGE9aCp0/ehy6yCHFBOvo=
 github.com/aclements/go-perfevent v0.0.0-20240301234650-f7843625020f/go.mod h1:tMDTce/yLLN/SK8gMOxQfnyeMeCg8KGzp0D1cbECEeo=
@@ -2287,6 +2288,7 @@ golang.org/x/oauth2 v0.0.0-20221014153046-6fdb5e3db783/go.mod h1:h4gKUeWbJ4rQPri
 golang.org/x/oauth2 v0.5.0/go.mod h1:9/XBHVqLaWO3/BRHs5jbpYCnOZVjj5V0ndyaAM7KB4I=
 golang.org/x/oauth2 v0.6.0/go.mod h1:ycmewcwgD4Rpr3eZJLSB4Kyyljb3qDh40vJ8STE5HKw=
 golang.org/x/oauth2 v0.7.0/go.mod h1:hPLQkd9LyjfXTiRohC/41GhcFqxisoUQ99sCUOHO9x4=
+golang.org/x/perf v0.0.0-20230113213139-801c7ef9e5c5 h1:ObuXPmIgI4ZMyQLIz48cJYgSyWdjUXc2SZAdyJMwEAU=
 golang.org/x/perf v0.0.0-20230113213139-801c7ef9e5c5/go.mod h1:UBKtEnL8aqnd+0JHqZ+2qoMDwtuy6cYhhKNoHLBiTQc=
 golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20181108010431-42b317875d0f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=

tools/gasbench/AGENTS.md

@@ -0,0 +1,70 @@
+# gasbench
+
+Differential microbenchmark harness: per-opcode EVM execution time vs gas
+cost, tracer-free. See `README.md` for the full rationale (differential
+construction, acceptance-gate design, active-benchmarking diagnostics); this
+file is the short orientation.
+
+## Rules for changes here
+
+- **Never attach a tracer to a timed run.** `debug=true` in the interpreter
+  dilates per-step time. Whole-program gas needs no tracer, so it's read off
+  the same tracer-free call that's timed — there is no separate gas-only
+  pass. A future per-opcode gas breakdown *would* need a tracer, and that
+  breakdown must come from a separate, untimed call. See README.md.
+- **Correlate against EVM gas, never the Cosmos gas meter.** `Program.Run`
+  deliberately has no ante handler / `GasMeter` in its path.
+- **A new `Case` must terminate cleanly** — every `Case` `BuildCaseWith`
+  builds ends in STOP with a balanced, net-zero-gas stack by construction;
+  `NewProgram` rejects anything that doesn't run clean once, and
+  `bench_test.go`'s self-check will fail loudly if the algebra is wrong. (The
+  general `Program.Run` contract also accepts RETURN — see README.md "Error
+  contract" — but every `Case` built here uses STOP.)
+- **New opcode specs:** hand-verify `Arity` (against the fork's
+  `core/vm/jump_table.go` `minStack`/`maxStack`) and `ConstGas` (against
+  `core/vm/jump_table.go` + `core/vm/eips.go`); the self-check catches a
+  wrong `ConstGas` but not a self-consistent wrong `Arity` — this is the
+  authoritative verification checklist, README.md's mention of it points
+  back here. `ConstGas` must come from the geth constant, not a Sei
+  override — production never reprices a scalar opcode (stock `vm.Config{}`,
+  no custom jump table); the only Sei gas param is `SeiSstoreSetGasEIP2200`,
+  a storage opcode and out of scope here.
+- **Data-dependent ops: verify the operands hit the real kernel.** For a
+  `DataDependent` spec, confirm `seedOperands` exercise the intended path, not
+  a `holiman/uint256` short-circuit — equal or degenerate operands make
+  `DIV(x,x)`/`MOD(x,x)` return without dividing, so the row would time a
+  compare. The gas self-check will NOT catch this (gas is unchanged); it's a
+  timing trap. `seedOperands` is ascending (dividend above divisor, smallest at
+  the modulus slot) for this reason — see README.md "Differential construction".
+- Keep code comments lean (what, not why); put methodology/rationale in
+  README.md instead of growing doc comments.
+
+## Running
+
+```bash
+tools/gasbench/run.sh
+```
+
+End-to-end walkthrough incl. how to interpret the output: README.md
+"Quickstart". Env vars, output schema, and the `-count` semantics caveat:
+README.md "Running it" / "Output schema".
+
+## Files
+
+| File | Contents |
+|---|---|
+| `gasbench.go` | timing core: `Measure`, `Config`, `Series`, rusage snapshot |
+| `diff.go` | `Subtract`: per-pass baseline/target differencing, `Diff` (medians/delta/gas/CoV) |
+| `stats.go` | `Summarize`: median/stddev/CoV over a sample series |
+| `crossrun.go` | `analyzeCrossRun`: cross-run benchmath verdict (paired delta CI gate + advisory Mann-Whitney p) |
+| `program.go` | `Program`: warmed tracer-free EVM environment, one bytecode input |
+| `programs.go` | `OpSpec`/`Specs`/`Case`/`BuildCaseWith`: the differential bytecode construction |
+| `emit.go` | `Run`, the verdict (`distinguishable`/`classifyStatus`), CSV/NDJSON output |
+| `emit_test.go` | pins `Run.Status`/CI as pure functions of the `crossRun` verdict (`classifyStatus`, `distinguishable`), the effect floor, and D-1 null-CI writer safety |
+| `crossrun_test.go` | pins `analyzeCrossRun`: drift-survival (paired beats unpaired), straddles-zero, underpowered |
+| `diff_test.go` | pins `Subtract`'s per-pass contract (delta/gas/per-op) |
+| `programs_test.go` | pins the `BuildCaseWith` arity-0 panic guard |
+| `bench_test.go` | `BenchmarkOpcodes`: wires the above into `go test -bench` |
+| `run.sh` | pinned-core runner + operator checklist for turbo/governor/isolation |
+| `README.md` | operator quickstart + full rationale: construction, acceptance gate, diagnostics |
+| `AGENTS.md` | this file |