aztecprotocol/aztec-packages/benchmark-avm

Benchmark AVM (local full proving)

Run the AVM full-proving benchmark — the same one CI tracks on the benchmark dashboard — locally, and read its per-stage proving breakdown. This is the AVM analogue of /benchmark-chonk.

The benchmark is a jest test, yarn-project/bb-prover/src/avm_proving_tests/avm_bulk.test.ts. It does full AVM proving (not check-circuit — see the comment at the top of the test): it runs bulkTest() against the AvmTest contract through the real prover and records per-stage timings into a TestExecutorMetrics.

Setup — do this once per merge-train sync (minutes, not hours)

The bulk test drives a real public-tx flow: it simulates the AvmTest contract against a live world-state DB, then proves with bb-avm. Since the world-state runs as a separate IPC process (aztec-wsdb) reached through two top-level components, wsdb/ and ipc-runtime/, that are portal:-linked into yarn-project. A plain ./bootstrap.sh build yarn-project does not wire these up (it serves cached artifacts), and the pinned AvmTest artifact and several dest/ trees might go stale. The archaeology to discover all this is what turns a "quick bench" into hours; the recipe below is the distilled fast path. Run it from the repo root:

# 1. C++ binaries: AVM prover + IPC world-state DB
(cd barretenberg/cpp && cmake --preset default -DAVM=ON \
  && cmake --build build --target bb-avm aztec-wsdb)
 
# 2. IPC world-state stack (portal deps; NOT set up by a yarn-project build).
#    wsdb/bootstrap.sh copies the aztec-wsdb binary built in step 1 into wsdb/ts/build/<arch>/.
(cd ipc-runtime && ./bootstrap.sh)
(cd wsdb && ./bootstrap.sh)
 
# 3. Refresh the AVM test contract artifact. Merge-train changes to constants.nr / AVM opcodes make the
#    pinned AvmTest bytecode revert immediately (see "reverts with 0 instructions" below). nargo + the
#    avm-transpiler must already be built (they are after any recent noir/noir-projects build).
(cd labs/noir-projects/noir-contracts && ./bootstrap.sh build avm_test_contract)
 
# 4. Link portals, regenerate the AvmTest TS wrapper from the fresh artifact, compile TS.
(cd yarn-project && yarn install \
  && yarn workspace @aztec/noir-test-contracts.js generate \
  && yarn build)

On an already-provisioned machine this is ~5–8 min (the C++ relink and yarn build are the long poles); on a cold machine the C++ build dominates. Steps you can skip once done: 1 only needs re-running when C++ changes; 2 only after a wsdb/ipc-runtime change; 3 only after an AVM/contract/constants change; 4's yarn build after any TS change.

Symptoms → fixes

Fast triage when the bulk test fails during setup:

Note: Total instructions executed: 0 prints even on a healthy passing run — that counter is a cosmetic metrics quirk, not a signal. The real health check is revertCode (OK vs Reverted) and a non-trivial Proving (all) time (a real bulk trace proves in ~4–5s; a truly empty one would be near-instant).

Legacy vs new Pippenger is a runtime toggle — build once

The MSM implementation is selected at runtime by the BB_MSM_LEGACY env var, read once per process in bb::scalar_multiplication::use_legacy_msm() (barretenberg/cpp/src/barretenberg/ecc/scalar_multiplication/scalar_multiplication.cpp):

• unset → new MSM (pippenger_fast)
• `BB_MSM_LEGACY=1` → legacy::pippenger

So you do not build two binaries. Build bb-avm once, then run the benchmark twice — once with and once without BB_MSM_LEGACY=1. The test spawns bb-avm as a subprocess (BB_PATH in avm_proving_tester.ts), so the env var set on the jest process propagates to the prover.

Run it the way CI runs it

CI's invocation (one line in yarn-project/bootstrap.sh):

ISOLATE=1:CPUS=16:MEM=16g BENCH_OUTPUT=bench-out/avm_bulk_test.bench.json \
  yarn-project/scripts/run_test.sh bb-prover/src/avm_proving_tests/avm_bulk.test.ts

Locally (set CPUS to your real core count; do not oversubscribe):

# New Pippenger (default)
CPUS=15 BENCH_OUTPUT=/tmp/avm_new.bench.json \
  yarn-project/scripts/run_test.sh bb-prover/src/avm_proving_tests/avm_bulk.test.ts
 
# Legacy Pippenger
BB_MSM_LEGACY=1 CPUS=15 BENCH_OUTPUT=/tmp/avm_legacy.bench.json \
  yarn-project/scripts/run_test.sh bb-prover/src/avm_proving_tests/avm_bulk.test.ts

run_test.sh pins RAYON_NUM_THREADS=1 and TOKIO_WORKER_THREADS=1, and maps CPUS → HARDWARE_CONCURRENCY (what bb's prover pool actually reads). MEM=16g is a container cgroup limit — a no-op locally as long as you keep ~16 GB+ free; the AVM bulk prove is memory-hungry. On macOS run_test.sh warns it can't reach docker/redis (log cache disabled) — harmless.

To just watch the pretty table without writing the GitHub-action JSON, drop BENCH_OUTPUT (the test always prints metrics.toPrettyString() in afterAll), or use BENCH_OUTPUT_MD=<file> for a markdown table.

The per-stage breakdown

Stage timings come from bb-avm's AvmStat[] output (generateAvmProof), mapped in avm_proving_tester.ts::recordProverMetrics and rendered under Proving: by TestExecutorMetrics:

For a legacy-vs-new Pippenger comparison, the signal lives in the commitment stages — Wire commitments, PCS, and Log-derivative-inverse commitments. Sumcheck and trace generation should be unchanged across the toggle and act as a sanity check that the two runs are otherwise comparable.

A/B: legacy vs new

1. Set up once (Setup) and build bb-avm.
2. Run twice — default and BB_MSM_LEGACY=1 — writing distinct BENCH_OUTPUT files.
3. Diff the commitment-stage entries between /tmp/avm_new.bench.json and /tmp/avm_legacy.bench.json. Each entry is {name, value, unit}; the proving stages above appear under their pretty names.

The GitHub-action JSON is a flat array of {name, value, unit} — easy to diff with jq:

jq -r '.[] | "\(.name)\t\(.value)"' /tmp/avm_new.bench.json | sort > /tmp/new.tsv
jq -r '.[] | "\(.name)\t\(.value)"' /tmp/avm_legacy.bench.json | sort > /tmp/legacy.tsv
diff -y /tmp/legacy.tsv /tmp/new.tsv

Comparing across commits (e.g. before/after a merge-train merge)

To attribute a regression to a specific commit, rebuild only bb-avm at each commit and run the same test — the TS harness, artifacts, and world-state stack stay put, so only the prover binary varies:

git checkout <commit>
(cd barretenberg/cpp && cmake --build build --target bb-avm)   # incremental relink
CPUS=15 BENCH_OUTPUT=/tmp/avm_<commit>.bench.json \
  yarn-project/scripts/run_test.sh bb-prover/src/avm_proving_tests/avm_bulk.test.ts

Caveat: if the commit you check out also changes AVM opcodes/constants or the AvmTest contract, the artifact from Setup step 3 may no longer match that binary and the tx can revert — recompile the contract (step 3) at that commit too, or the comparison is invalid.

Local runs are noisy — average 3+ runs

Non-dedicated machines have variable load. Run each side at least 3× and average (5 is better and cheap — one run is ~6s). Watch for thermal drift: on a laptop, back-to-back runs creep slower as the machine warms, so interleave the two sides (A/B/A/B…) rather than all-A-then-all-B, and report medians. Relative (legacy-vs-new on the same box, close together) deltas are valid even when absolute numbers won't match the dashboard:

• CPUS=15 ≠ CI's 16 → expect single-digit-% higher wall times.
• No ISOLATE=1 container locally → whatever else the box is doing leaks in.
• Different CPU than the dashboard machine.
• Low-power / battery mode flattens everything (throttles frequency, parks high-perf cores) — check it's off before benchmarking.

So treat the output as before/after deltas on this box, not dashboard-absolute matches.

Tips