@aztec/simulator 3.0.0-rc.5 → 4.0.0-nightly.20260107

package/dest/public/fixtures/opcode_spammer.js

@@ -0,0 +1,1681 @@
+/**
+ * Opcode Spammer - A minimal, data-driven opcode spammer for AVM gas benchmarking.
+ *
+ * Design principles:
+ * 1. Data over code: Opcode behavior is configuration, not control flow
+ * 2. Derive, don't declare: Categories and strategies follow from the data
+ * 3. Maximize coverage: Fill bytecode to the limit for accurate gas measurement
+ * 4. Smallest wire format: Use _8 variants over _16 to fit more instructions per loop
+ * 5. Single file: Everything in one module
+ *
+ * ## Architecture
+ *
+ * ```
+ * ┌─────────────────────────────────────────────────────────────────┐
+ * │                        SPAM_CONFIGS                             │
+ * │  Record<Opcode, SpamConfig[]>                                   │
+ * │                                                                 │
+ * │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
+ * │  │   ADD_8     │  │  POSEIDON2  │  │EMITNULLIFIER│  ...         │
+ * │  │ [7 configs] │  │ [1 config]  │  │ [1 config]  │              │
+ * │  │ (per type)  │  │             │  │ (limit=63)  │              │
+ * │  └─────────────┘  └─────────────┘  └─────────────┘              │
+ * └─────────────────────────────────────────────────────────────────┘
+ *                               │
+ *                               ▼
+ * ┌─────────────────────────────────────────────────────────────────┐
+ * │                   getSpamConfigsPerOpcode()                     │
+ * │  Returns { opcodes, config[] } for test iteration               │
+ * └─────────────────────────────────────────────────────────────────┘
+ *                               │
+ *                               ▼
+ * ┌─────────────────────────────────────────────────────────────────┐
+ * │                    testOpcodeSpamCase()                         │
+ * │  Routes to appropriate bytecode generator & executes test       │
+ * │                                                                 │
+ * │  config.limit === undefined?                                    │
+ * │      YES → testStandardOpcodeSpam()                             │
+ * │      NO  → testSideEffectOpcodeSpam()                           │
+ * └─────────────────────────────────────────────────────────────────┘
+ * ```
+ *
+ * ## Two Execution Strategies
+ *
+ * ### Strategy 1: Standard Opcodes (Gas-Limited)
+ *
+ * For opcodes without per-TX limits (arithmetic, comparisons, memory ops, etc.), we create a single contract with an infinite loop:
+ *
+ * ```
+ * ┌────────────────────────────────────────────────────────────────┐
+ * │                    SINGLE CONTRACT                             │
+ * │                                                                │
+ * │  ┌──────────────────────────────────────────────────────────┐  │
+ * │  │ SETUP PHASE                                              │  │
+ * │  │  SET mem[0] = initial_value                              │  │
+ * │  │  SET mem[1] = operand                                    │  │
+ * │  │  ...                                                     │  │
+ * │  └──────────────────────────────────────────────────────────┘  │
+ * │                           │                                    │
+ * │                           ▼                                    │
+ * │  ┌──────────────────────────────────────────────────────────┐  │
+ * │  │ LOOP (fills remaining bytecode space)          ◄─────┐   │  │
+ * │  │  TARGET_OPCODE  ─┐                                   │   │  │
+ * │  │  TARGET_OPCODE   │ unrolled N times                  │   │  │
+ * │  │  TARGET_OPCODE   │ (N = available_bytes / instr_size)│   │  │
+ * │  │  ...            ─┘                                   │   │  │
+ * │  │  JUMP back ──────────────────────────────────────────┘   │  │
+ * │  └──────────────────────────────────────────────────────────┘  │
+ * │                                                                │
+ * │  Executes until: OUT OF GAS                                    │
+ * └────────────────────────────────────────────────────────────────┘
+ * ```
+ *
+ * **Bytecode Layout:**
+ * ```
+ * ┌─────────────────────────────────────────────────────────────────┐
+ * │ 0x00: SET instructions (setup)                                  │
+ * │ ...                                                             │
+ * │ 0xNN: ┌─── LOOP START ◄──────────────────────────────────────┐  │
+ * │       │ TARGET_OPCODE                                        │  │
+ * │       │ TARGET_OPCODE  (unrolled to fill max bytecode size)  │  │
+ * │       │ TARGET_OPCODE                                        │  │
+ * │       │ ...                                                  │  │
+ * │       └─► JUMP 0xNN ─────────────────────────────────────────┘  │
+ * │ MAX_BYTECODE_BYTES                                              │
+ * └─────────────────────────────────────────────────────────────────┘
+ * ```
+ *
+ * ### Strategy 2: Side-Effect Limited Opcodes (Nested Call Pattern)
+ *
+ * For opcodes with per-TX limits (EMITNOTEHASH, EMITNULLIFIER, SENDL2TOL1MSG, etc.), we use a two-contract pattern where the inner contract executes side effects up to the limit, then REVERTs to discard them:
+ *
+ * ```
+ * ┌─────────────────────────────────────────────────────────────────┐
+ * │                      OUTER CONTRACT                             │
+ * │                                                                 │
+ * │  ┌───────────────────────────────────────────────────────────┐  │
+ * │  │ SETUP                                                     │  │
+ * │  │  CALLDATACOPY inner_address from calldata[0]              │  │
+ * │  │  SET l2Gas = MAX_UINT32                                   │  │
+ * │  │  SET daGas = MAX_UINT32                                   │  │
+ * │  └───────────────────────────────────────────────────────────┘  │
+ * │                           │                                     │
+ * │                           ▼                                     │
+ * │  ┌───────────────────────────────────────────────────────────┐  │
+ * │  │ LOOP                                               ◄────┐ │  │
+ * │  │  CALL inner_contract ──────────────────────┐            │ │  │
+ * │  │  JUMP back ─────────────────────────────────────────────┘ │  │
+ * │  └───────────────────────────────────────────────────────────┘  │
+ * │                                               │                 │
+ * │  Executes until: OUT OF GAS                   │                 │
+ * └───────────────────────────────────────────────│─────────────────┘
+ *                                                 │
+ *                                                 ▼
+ * ┌─────────────────────────────────────────────────────────────────┐
+ * │                      INNER CONTRACT                             │
+ * │                                                                 │
+ * │  ┌───────────────────────────────────────────────────────────┐  │
+ * │  │ SETUP                                                     │  │
+ * │  │  SET initial values for side-effect opcode                │  │
+ * │  └───────────────────────────────────────────────────────────┘  │
+ * │                           │                                     │
+ * │                           ▼                                     │
+ * │  ┌───────────────────────────────────────────────────────────┐  │
+ * │  │ BODY (unrolled, NOT a loop)                               │  │
+ * │  │  SIDE_EFFECT_OPCODE  ─┐                                   │  │
+ * │  │  SIDE_EFFECT_OPCODE   │ repeated `limit` times            │  │
+ * │  │  SIDE_EFFECT_OPCODE   │ (e.g., 64 for EMITNOTEHASH)       │  │
+ * │  │  ...                 ─┘                                   │  │
+ * │  └───────────────────────────────────────────────────────────┘  │
+ * │                           │                                     │
+ * │                           ▼                                     │
+ * │  ┌───────────────────────────────────────────────────────────┐  │
+ * │  │ CLEANUP                                                   │  │
+ * │  │  REVERT (discards all side effects from this call)        │  │
+ * │  └───────────────────────────────────────────────────────────┘  │
+ * │                                                                 │
+ * └─────────────────────────────────────────────────────────────────┘
+ * ```
+ *
+ * **Why this pattern?**
+ *
+ * Side-effect opcodes have per-TX limits:
+ * - `EMITNOTEHASH`: max 64 per TX
+ * - `EMITNULLIFIER`: max 63 per TX (one reserved for TX nullifier)
+ * - `SENDL2TOL1MSG`: max 8 per TX
+ * - `EMITUNENCRYPTEDLOG`: limited by total log payload size
+ *
+ * By having the inner contract REVERT after emitting side effects, those effects are discarded, allowing the outer contract to call it again. This enables thousands of opcode executions per TX instead of just the limit.
+ *
+ */ import { FLAT_PUBLIC_LOGS_PAYLOAD_LENGTH, MAX_L2_TO_L1_MSGS_PER_TX, MAX_NOTE_HASHES_PER_TX, MAX_NULLIFIERS_PER_TX, MAX_PACKED_PUBLIC_BYTECODE_SIZE_IN_FIELDS, MAX_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX, MAX_PUBLIC_LOG_SIZE_IN_FIELDS, PUBLIC_LOG_HEADER_LENGTH } from '@aztec/constants';
+import { Grumpkin } from '@aztec/foundation/crypto/grumpkin';
+import { randomBigInt } from '@aztec/foundation/crypto/random';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { PublicDataWrite } from '@aztec/stdlib/avm';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { computePublicDataTreeLeafSlot, siloNullifier } from '@aztec/stdlib/hash';
+import { MerkleTreeId } from '@aztec/stdlib/trees';
+import assert from 'assert';
+import { Field, TaggedMemory, TypeTag, Uint1, Uint32, Uint64 } from '../avm/avm_memory_types.js';
+import { Add, And, Call, CalldataCopy, Cast, DebugLog, Div, EcAdd, EmitNoteHash, EmitNullifier, EmitUnencryptedLog, Eq, FieldDiv, GetContractInstance, GetEnvVar, InternalCall, InternalReturn, Jump, JumpI, KeccakF1600, L1ToL2MessageExists, Lt, Lte, Mov, Mul, Not, NoteHashExists, NullifierExists, Or, Poseidon2, Return, ReturndataCopy, ReturndataSize, Revert, SLoad, SStore, SendL2ToL1Message, Set, Sha256Compression, Shl, Shr, StaticCall, Sub, SuccessCopy, ToRadixBE, Xor } from '../avm/opcodes/index.js';
+import { encodeToBytecode } from '../avm/serialization/bytecode_serialization.js';
+import { Opcode } from '../avm/serialization/instruction_serialization.js';
+import { deployCustomBytecode, executeCustomBytecode } from './custom_bytecode_tester.js';
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Constants for "warm" tree reads - these values are inserted into the trees
+ * before running the spammer so that existence checks can find them.
+ */ export const WARM_NOTE_HASH = new Fr(0xdeadbeefn);
+export const WARM_L1_TO_L2_MSG = new Fr(0xcafebabedeadbeefn);
+/** Warm nullifier constants - uses a fixed address since NULLIFIEREXISTS takes address as parameter */ export const WARM_NULLIFIER = new Fr(0xdeadbeef0001n);
+export const WARM_NULLIFIER_ADDRESS = AztecAddress.fromNumber(0xbeef);
+/** Warm storage constants - storage is inserted for the deployed contract's address */ export const WARM_STORAGE_SLOT = new Fr(0xdeadbeef0002n);
+export const WARM_STORAGE_VALUE = new Fr(0xcafebabe0003n);
+/**
+ * Leaf indices inserted to by insertWarmTreeEntries().
+ * Ideally we'd getTreeInfo and set dynamically, but that doesn't
+ * work easily with static spam configs, so we assume intial index 0.
+ */ export const WARM_NOTE_HASH_LEAF_INDEX = 0n;
+export const WARM_L1_TO_L2_MSG_LEAF_INDEX = 0n;
+/**
+ * Insert entries into the trees so that "warm" configs can find them with existence checks.
+ * Call this before running the opcode spammer to enable warm tree reads.
+ *
+ * Inserts:
+ * - Note hash into NOTE_HASH_TREE
+ * - L1 to L2 message into L1_TO_L2_MESSAGE_TREE
+ * - Siloed nullifier into NULLIFIER_TREE (for NULLIFIEREXISTS warm check)
+ * - Storage value into PUBLIC_DATA_TREE (for SLOAD warm check)
+ */ export async function insertWarmTreeEntries(merkleTrees, contractAddress) {
+    // Insert into note hash tree
+    await merkleTrees.appendLeaves(MerkleTreeId.NOTE_HASH_TREE, [
+        WARM_NOTE_HASH
+    ]);
+    // Insert into L1 to L2 message tree
+    await merkleTrees.appendLeaves(MerkleTreeId.L1_TO_L2_MESSAGE_TREE, [
+        WARM_L1_TO_L2_MSG
+    ]);
+    // Insert siloed nullifier into nullifier tree
+    const siloedNullifier = await siloNullifier(WARM_NULLIFIER_ADDRESS, WARM_NULLIFIER);
+    await merkleTrees.sequentialInsert(MerkleTreeId.NULLIFIER_TREE, [
+        siloedNullifier.toBuffer()
+    ]);
+    // Insert storage value into public data tree
+    const leafSlot = await computePublicDataTreeLeafSlot(contractAddress, WARM_STORAGE_SLOT);
+    const publicDataWrite = new PublicDataWrite(leafSlot, WARM_STORAGE_VALUE);
+    await merkleTrees.sequentialInsert(MerkleTreeId.PUBLIC_DATA_TREE, [
+        publicDataWrite.toBuffer()
+    ]);
+}
+/**
+ * Maximum bytecode size in bytes.
+ *
+ * Bytecode is encoded as fields using bufferAsFields():
+ *   - 1 field for the byte length
+ *   - ceil(byteLength / 31) fields for the data (31 bytes per field)
+ *
+ * So: 1 + ceil(byteLength / 31) <= MAX_PACKED_PUBLIC_BYTECODE_SIZE_IN_FIELDS
+ *     ceil(byteLength / 31) <= MAX_PACKED_PUBLIC_BYTECODE_SIZE_IN_FIELDS - 1
+ *     byteLength <= (MAX_PACKED_PUBLIC_BYTECODE_SIZE_IN_FIELDS - 1) * 31
+ */ const BYTES_PER_FIELD = Fr.SIZE_IN_BYTES - 1; // 31 bytes of data per field
+const MAX_BYTECODE_BYTES = (MAX_PACKED_PUBLIC_BYTECODE_SIZE_IN_FIELDS - 1) * BYTES_PER_FIELD;
+const JUMP_SIZE = encodeToBytecode([
+    new Jump(0)
+]).length; // JUMP_32
+const INTERNALCALL_SIZE = encodeToBytecode([
+    new InternalCall(0)
+]).length;
+// ============================================================================
+// Type Variant Helpers (for generating multiple configs per opcode)
+// ============================================================================
+// Not using these sets directly because we want to control order
+//const ALL_TAGS = Array.from(VALID_TAGS);
+//const INT_TAGS = Array.from(INTEGRAL_TAGS);
+// Ordered so that limiting #configs per opcode still tests max size (Field)
+const ALL_TAGS = [
+    TypeTag.FIELD,
+    TypeTag.UINT1,
+    TypeTag.UINT8,
+    TypeTag.UINT16,
+    TypeTag.UINT32,
+    TypeTag.UINT64,
+    TypeTag.UINT128
+];
+// ordered so that limiting #configs per opcode still tests max size
+const INT_TAGS = [
+    TypeTag.UINT128,
+    TypeTag.UINT1,
+    TypeTag.UINT8,
+    TypeTag.UINT16,
+    TypeTag.UINT32,
+    TypeTag.UINT64
+];
+/** Build from tag truncating - shorter name */ function withTag(v, tag) {
+    return TaggedMemory.buildFromTagTruncating(v, tag);
+}
+// ============================================================================
+// Random Value Helpers (seeded via SEED env var for reproducibility)
+// ============================================================================
+/** Modulus (really just max+1) for each integer type tag */ const TAG_MODULI = {
+    [TypeTag.UINT1]: 2n,
+    [TypeTag.UINT8]: 256n,
+    [TypeTag.UINT16]: 65536n,
+    [TypeTag.UINT32]: 0x1_0000_0000n,
+    [TypeTag.UINT64]: 0x1_0000_0000_0000_0000n,
+    [TypeTag.UINT128]: 0x1_0000_0000_0000_0000_0000_0000_0000_0000n,
+    [TypeTag.FIELD]: Fr.MODULUS
+};
+/** Generate a random value with the given type tag. Uses SEED env var if set. */ function randomWithTag(tag) {
+    const modulus = TAG_MODULI[tag];
+    if (modulus === undefined) {
+        throw new Error(`Unsupported tag for random generation: ${TypeTag[tag]}`);
+    }
+    const value = randomBigInt(modulus);
+    return TaggedMemory.buildFromTagTruncating(value, tag);
+}
+/** Generate a random non-zero value with the given type tag (for division). */ function randomNonZeroWithTag(tag) {
+    const modulus = TAG_MODULI[tag];
+    if (modulus === undefined) {
+        throw new Error(`Unsupported tag for random generation: ${TypeTag[tag]}`);
+    }
+    // Generate random in range [1, max) by generating [0, max-1) and adding 1
+    const value = randomBigInt(modulus - 1n) + 1n;
+    return TaggedMemory.buildFromTagTruncating(value, tag);
+}
+/** Generate a random non-zero Field value (for field division). */ function randomNonZeroField() {
+    return new Field(randomBigInt(Fr.MODULUS - 1n) + 1n);
+}
+/** Reserved memory offsets for external call loop (used by CALL spam and side-effect opcodes) */ const CONST_0_OFFSET = 0; // Uint32(0)
+const CONST_1_OFFSET = 1; // Uint32(1)
+const CONST_MAX_U32_OFFSET = 2; // Uint32(MAX_U32)
+const CALL_ADDR_OFFSET = 3; // copy addr from calldata to here, and then use this addr for CALL
+const CALL_ARGS_OFFSET = CALL_ADDR_OFFSET; // address is the arg to send to CALL
+const CALL_COPY_SIZE_OFFSET = CONST_1_OFFSET; // copy size = 1 (forward calldata[0])
+const CALL_CALLDATA_INDEX_OFFSET = CONST_0_OFFSET; // calldata[0]
+const CALL_L2_GAS_OFFSET = CONST_MAX_U32_OFFSET; // MAX_U32 gets capped to remaining gas by AVM
+const CALL_DA_GAS_OFFSET = CONST_MAX_U32_OFFSET; // MAX_U32 gets capped to remaining gas by AVM
+const CALL_ARGS_SIZE_OFFSET = CONST_1_OFFSET; // argsSize = 1 (forward calldata[0] - might contain contract address)
+const MAX_U32 = 0xffffffffn;
+/**
+ * A SpamConfig for to make external CALLs to an address specified in calldata[0].
+ */ export const EXTERNAL_CALL_CONFIG = {
+    setup: [
+        // calldata will contain 1 item: the external call address
+        {
+            offset: CONST_0_OFFSET,
+            value: new Uint32(0)
+        },
+        {
+            offset: CONST_1_OFFSET,
+            value: new Uint32(1)
+        },
+        {
+            offset: CONST_MAX_U32_OFFSET,
+            value: new Uint32(MAX_U32)
+        },
+        ()=>[
+                new CalldataCopy(/*indirect=*/ 0, /*copySizeOffset=*/ CALL_COPY_SIZE_OFFSET, /*cdStartOffset=*/ CALL_CALLDATA_INDEX_OFFSET, /*dstOffset=*/ CALL_ADDR_OFFSET)
+            ]
+    ],
+    targetInstructions: ()=>[
+            new Call(/*indirect=*/ 0, /*l2GasOffset=*/ CALL_L2_GAS_OFFSET, /*daGasOffset=*/ CALL_DA_GAS_OFFSET, /*addrOffset=*/ CALL_ADDR_OFFSET, /*argsSizeOffset=*/ CALL_ARGS_SIZE_OFFSET, /*argsOffset=*/ CALL_ARGS_OFFSET)
+        ],
+    addressAsCalldata: true
+};
+const STATIC_CALL_CONFIG = {
+    setup: [
+        // calldata will contain 1 item: the external call address
+        {
+            offset: CONST_0_OFFSET,
+            value: new Uint32(0)
+        },
+        {
+            offset: CONST_1_OFFSET,
+            value: new Uint32(1)
+        },
+        {
+            offset: CONST_MAX_U32_OFFSET,
+            value: new Uint32(MAX_U32)
+        },
+        ()=>[
+                new CalldataCopy(/*indirect=*/ 0, /*copySizeOffset=*/ CALL_COPY_SIZE_OFFSET, /*cdStartOffset=*/ CALL_CALLDATA_INDEX_OFFSET, /*dstOffset=*/ CALL_ADDR_OFFSET)
+            ]
+    ],
+    targetInstructions: ()=>[
+            new StaticCall(/*indirect=*/ 0, /*l2GasOffset=*/ CALL_L2_GAS_OFFSET, /*daGasOffset=*/ CALL_DA_GAS_OFFSET, /*addrOffset=*/ CALL_ADDR_OFFSET, /*argsSizeOffset=*/ CALL_ARGS_SIZE_OFFSET, /*argsOffset=*/ CALL_ARGS_OFFSET)
+        ],
+    addressAsCalldata: true
+};
+// ============================================================================
+// Configuration Map
+// ============================================================================
+/**
+ * Opcode spammer configs for ~all opcodes.
+ * Each opcode maps to an array of configs (usually one, but can be multiple for type variants, etc.)
+ * Uses smallest wire format (_8) for maximum instruction density.
+ */ export const SPAM_CONFIGS = {
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ARITHMETIC - Test with all type variants (random values, seeded via SEED env var)
+    // ═══════════════════════════════════════════════════════════════════════════
+    [Opcode.ADD_8]: ALL_TAGS.map((tag)=>({
+            label: TypeTag[tag],
+            setup: [
+                {
+                    offset: 0,
+                    value: randomWithTag(tag)
+                },
+                {
+                    offset: 1,
+                    value: randomWithTag(tag)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new Add(/*indirect=*/ 0, /*aOffset=*/ 0, /*bOffset=*/ 1, /*dstOffset=*/ 0).as(Opcode.ADD_8, Add.wireFormat8)
+                ]
+        })),
+    [Opcode.SUB_8]: ALL_TAGS.map((tag)=>({
+            label: TypeTag[tag],
+            setup: [
+                {
+                    offset: 0,
+                    value: randomWithTag(tag)
+                },
+                {
+                    offset: 1,
+                    value: randomWithTag(tag)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new Sub(/*indirect=*/ 0, /*aOffset=*/ 0, /*bOffset=*/ 1, /*dstOffset=*/ 0).as(Opcode.SUB_8, Sub.wireFormat8)
+                ]
+        })),
+    [Opcode.MUL_8]: ALL_TAGS.map((tag)=>({
+            label: TypeTag[tag],
+            setup: [
+                {
+                    offset: 0,
+                    value: randomWithTag(tag)
+                },
+                {
+                    offset: 1,
+                    value: randomWithTag(tag)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new Mul(/*indirect=*/ 0, /*aOffset=*/ 0, /*bOffset=*/ 1, /*dstOffset=*/ 0).as(Opcode.MUL_8, Mul.wireFormat8)
+                ]
+        })),
+    // DIV doesn't support FIELD type
+    [Opcode.DIV_8]: INT_TAGS.map((tag)=>({
+            label: TypeTag[tag],
+            setup: [
+                {
+                    offset: 0,
+                    value: randomWithTag(tag)
+                },
+                {
+                    offset: 1,
+                    value: randomNonZeroWithTag(tag)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new Div(/*indirect=*/ 0, /*aOffset=*/ 0, /*bOffset=*/ 1, /*dstOffset=*/ 0).as(Opcode.DIV_8, Div.wireFormat8)
+                ]
+        })),
+    // Field-only
+    [Opcode.FDIV_8]: [
+        {
+            setup: [
+                {
+                    offset: 0,
+                    value: new Field(Fr.random())
+                },
+                {
+                    offset: 1,
+                    value: randomNonZeroField()
+                }
+            ],
+            targetInstructions: ()=>[
+                    new FieldDiv(/*indirect=*/ 0, /*aOffset=*/ 0, /*bOffset=*/ 1, /*dstOffset=*/ 0).as(Opcode.FDIV_8, FieldDiv.wireFormat8)
+                ]
+        }
+    ],
+    // ═══════════════════════════════════════════════════════════════════════════
+    // COMPARATORS - Test with all type variants (random values)
+    // ═══════════════════════════════════════════════════════════════════════════
+    [Opcode.EQ_8]: ALL_TAGS.map((tag)=>({
+            label: TypeTag[tag],
+            setup: [
+                {
+                    offset: 0,
+                    value: randomWithTag(tag)
+                },
+                {
+                    offset: 1,
+                    value: randomWithTag(tag)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new Eq(/*indirect=*/ 0, /*aOffset=*/ 0, /*bOffset=*/ 1, /*dstOffset=*/ 2).as(Opcode.EQ_8, Eq.wireFormat8)
+                ]
+        })),
+    [Opcode.LT_8]: ALL_TAGS.map((tag)=>({
+            label: TypeTag[tag],
+            setup: [
+                {
+                    offset: 0,
+                    value: randomWithTag(tag)
+                },
+                {
+                    offset: 1,
+                    value: randomWithTag(tag)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new Lt(/*indirect=*/ 0, /*aOffset=*/ 0, /*bOffset=*/ 1, /*dstOffset=*/ 2).as(Opcode.LT_8, Lt.wireFormat8)
+                ]
+        })),
+    [Opcode.LTE_8]: ALL_TAGS.map((tag)=>({
+            label: TypeTag[tag],
+            setup: [
+                {
+                    offset: 0,
+                    value: randomWithTag(tag)
+                },
+                {
+                    offset: 1,
+                    value: randomWithTag(tag)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new Lte(/*indirect=*/ 0, /*aOffset=*/ 0, /*bOffset=*/ 1, /*dstOffset=*/ 2).as(Opcode.LTE_8, Lte.wireFormat8)
+                ]
+        })),
+    // ═══════════════════════════════════════════════════════════════════════════
+    // BITWISE - Integer types only (no FIELD) (random values)
+    // ═══════════════════════════════════════════════════════════════════════════
+    [Opcode.AND_8]: INT_TAGS.map((tag)=>({
+            label: TypeTag[tag],
+            setup: [
+                {
+                    offset: 0,
+                    value: randomWithTag(tag)
+                },
+                {
+                    offset: 1,
+                    value: randomWithTag(tag)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new And(/*indirect=*/ 0, /*aOffset=*/ 0, /*bOffset=*/ 1, /*dstOffset=*/ 0).as(Opcode.AND_8, And.wireFormat8)
+                ]
+        })),
+    [Opcode.OR_8]: INT_TAGS.map((tag)=>({
+            label: TypeTag[tag],
+            setup: [
+                {
+                    offset: 0,
+                    value: randomWithTag(tag)
+                },
+                {
+                    offset: 1,
+                    value: randomWithTag(tag)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new Or(/*indirect=*/ 0, /*aOffset=*/ 0, /*bOffset=*/ 1, /*dstOffset=*/ 0).as(Opcode.OR_8, Or.wireFormat8)
+                ]
+        })),
+    [Opcode.XOR_8]: INT_TAGS.map((tag)=>({
+            label: TypeTag[tag],
+            setup: [
+                {
+                    offset: 0,
+                    value: randomWithTag(tag)
+                },
+                {
+                    offset: 1,
+                    value: randomWithTag(tag)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new Xor(/*indirect=*/ 0, /*aOffset=*/ 0, /*bOffset=*/ 1, /*dstOffset=*/ 0).as(Opcode.XOR_8, Xor.wireFormat8)
+                ]
+        })),
+    [Opcode.NOT_8]: INT_TAGS.map((tag)=>({
+            label: TypeTag[tag],
+            setup: [
+                {
+                    offset: 0,
+                    value: randomWithTag(tag)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new Not(/*indirect=*/ 0, /*srcOffset=*/ 0, /*dstOffset=*/ 0).as(Opcode.NOT_8, Not.wireFormat8)
+                ]
+        })),
+    [Opcode.SHL_8]: INT_TAGS.map((tag)=>({
+            label: TypeTag[tag],
+            setup: [
+                {
+                    offset: 0,
+                    value: randomWithTag(tag)
+                },
+                {
+                    offset: 1,
+                    value: withTag(1n, tag)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new Shl(/*indirect=*/ 0, /*aOffset=*/ 0, /*bOffset=*/ 1, /*dstOffset=*/ 0).as(Opcode.SHL_8, Shl.wireFormat8)
+                ]
+        })),
+    [Opcode.SHR_8]: INT_TAGS.map((tag)=>({
+            label: TypeTag[tag],
+            setup: [
+                {
+                    offset: 0,
+                    value: randomWithTag(tag)
+                },
+                {
+                    offset: 1,
+                    value: withTag(1n, tag)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new Shr(/*indirect=*/ 0, /*aOffset=*/ 0, /*bOffset=*/ 1, /*dstOffset=*/ 0).as(Opcode.SHR_8, Shr.wireFormat8)
+                ]
+        })),
+    // ═══════════════════════════════════════════════════════════════════════════
+    // CAST / MOV - Test with all type variants (random values)
+    // ═══════════════════════════════════════════════════════════════════════════
+    [Opcode.CAST_8]: ALL_TAGS.map((tag)=>({
+            label: TypeTag[tag],
+            setup: [
+                {
+                    offset: 0,
+                    value: randomWithTag(tag)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new Cast(/*indirect=*/ 0, /*srcOffset=*/ 0, /*dstOffset=*/ 1, /*dstTag=*/ TypeTag.UINT32).as(Opcode.CAST_8, Cast.wireFormat8)
+                ]
+        })),
+    [Opcode.MOV_8]: ALL_TAGS.map((tag)=>({
+            label: TypeTag[tag],
+            setup: [
+                {
+                    offset: 0,
+                    value: randomWithTag(tag)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new Mov(/*indirect=*/ 0, /*srcOffset=*/ 0, /*dstOffset=*/ 1).as(Opcode.MOV_8, Mov.wireFormat8)
+                ]
+        })),
+    // ═══════════════════════════════════════════════════════════════════════════
+    // MEMORY - SET
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Not testing all wire formats as they should be roughly the same in terms of simulation
+    // and proving time
+    //[Opcode.SET_8]: [
+    //  {
+    //    setup: [],
+    //    targetInstructions: () => [new Set(0, 0, TypeTag.UINT8, 42).as(Opcode.SET_8, Set.wireFormat8)],
+    //  },
+    //],
+    //[Opcode.SET_16]: [
+    //  {
+    //    setup: [],
+    //    targetInstructions: () => [new Set(0, 0, TypeTag.UINT16, 4242).as(Opcode.SET_16, Set.wireFormat16)],
+    //  },
+    //],
+    //[Opcode.SET_32]: [
+    //  {
+    //    setup: [],
+    //    targetInstructions: () => [new Set(0, 0, TypeTag.UINT32, 424242).as(Opcode.SET_32, Set.wireFormat32)],
+    //  },
+    //],
+    //[Opcode.SET_64]: [
+    //  {
+    //    setup: [],
+    //    targetInstructions: () => [new Set(0, 0, TypeTag.UINT64, 42424242n).as(Opcode.SET_64, Set.wireFormat64)],
+    //  },
+    //],
+    [Opcode.SET_128]: [
+        {
+            setup: [],
+            targetInstructions: ()=>[
+                    new Set(/*indirect=*/ 0, /*dstOffset=*/ 0, /*inTag=*/ TypeTag.UINT128, /*value=*/ 4242424242424242n).as(Opcode.SET_128, Set.wireFormat128)
+                ]
+        }
+    ],
+    //[Opcode.SET_FF]: [
+    //  {
+    //    setup: [],
+    //    targetInstructions: () => [new Set(0, 0, TypeTag.FIELD, 42n).as(Opcode.SET_FF, Set.wireFormatFF)],
+    //  },
+    //],
+    // ═══════════════════════════════════════════════════════════════════════════
+    // CONTROL FLOW
+    // ═══════════════════════════════════════════════════════════════════════════
+    [Opcode.JUMP_32]: [
+        {
+            setup: [],
+            // Target will be overwritten by loop builder
+            targetInstructions: ()=>[
+                    new Jump(/*jumpOffset=*/ 0)
+                ]
+        }
+    ],
+    [Opcode.JUMPI_32]: [
+        {
+            setup: [
+                {
+                    offset: 0,
+                    value: new Uint1(0n)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new JumpI(/*indirect=*/ 0, /*condOffset=*/ 0, /*loc=*/ 0)
+                ]
+        }
+    ],
+    // INTERNALCALL: calls itself infinitely by jumping to its own PC (PC 0, since no setup)
+    // Creates infinite recursion until OOG (internal call stack grows forever)
+    [Opcode.INTERNALCALL]: [
+        {
+            setup: [],
+            targetInstructions: ()=>[
+                    new InternalCall(/*loc=*/ 0)
+                ]
+        }
+    ],
+    // INTERNALRETURN: needs INTERNALCALL to return without error
+    // Layout: INTERNALCALL(10) -> JUMP(0) -> INTERNALRETURN
+    // INTERNALCALL jumps to INTERNALRETURN, which returns to JUMP, which loops back
+    [Opcode.INTERNALRETURN]: [
+        {
+            setup: [],
+            targetInstructions: ()=>[
+                    new InternalCall(/*loc=*/ INTERNALCALL_SIZE + JUMP_SIZE),
+                    new Jump(/*jumpOffset=*/ 0),
+                    new InternalReturn()
+                ]
+        }
+    ],
+    // CALL (EXTERNALCALL): calls the current contract address (self) in a loop
+    // Contract address is passed via calldata[0] and propagated to nested calls
+    [Opcode.CALL]: [
+        EXTERNAL_CALL_CONFIG
+    ],
+    [Opcode.STATICCALL]: [
+        STATIC_CALL_CONFIG
+    ],
+    // RETURN: terminates execution, so we need to use the two-contract pattern
+    // Outer contract CALLs inner contract in a loop, inner contract does RETURN
+    [Opcode.RETURN]: [
+        {
+            setup: [
+                {
+                    offset: 0,
+                    value: new Uint32(0)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new Return(/*indirect=*/ 0, /*returnSizeOffset=*/ 0, /*returnOffset=*/ 0)
+                ],
+            // Use the side-effect-limit pattern (even though it's not a side-effect) as it fits
+            // this case (we want to CALL, RETURN, then CALL again back in parent). We omit "cleanup"
+            // because we don't need to REVERT as we do for real side-effects.
+            limit: 1
+        }
+    ],
+    // REVERT: terminates execution, so we need to use the two-contract pattern
+    // Outer contract CALLs inner contract in a loop, inner contract does REVERT
+    [Opcode.REVERT_8]: [
+        {
+            setup: [
+                {
+                    offset: 0,
+                    value: new Uint32(0)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new Revert(/*indirect=*/ 0, /*retSizeOffset=*/ 0, /*returnOffset=*/ 1).as(Opcode.REVERT_8, Revert.wireFormat8)
+                ],
+            limit: 1
+        }
+    ],
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ENVIRONMENT
+    // ═══════════════════════════════════════════════════════════════════════════
+    [Opcode.GETENVVAR_16]: [
+        {
+            setup: [],
+            targetInstructions: ()=>[
+                    new GetEnvVar(/*indirect=*/ 0, /*dstOffset=*/ 0, /*varEnum=*/ 0).as(Opcode.GETENVVAR_16, GetEnvVar.wireFormat16)
+                ]
+        }
+    ],
+    // CALLDATACOPY has dynamic gas scaling with copySize
+    [Opcode.CALLDATACOPY]: [
+        {
+            label: 'Min copy size',
+            // CalldataCopy with copySize=0 is a no-op but still executes the opcode
+            setup: [
+                {
+                    offset: 0,
+                    value: new Uint32(0n)
+                },
+                {
+                    offset: 1,
+                    value: new Uint32(0n)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new CalldataCopy(/*indirect=*/ 0, /*copySizeOffset=*/ 0, /*cdStartOffset=*/ 1, /*dstOffset=*/ 2)
+                ]
+        },
+        {
+            label: 'Large copy size',
+            // Large copySize with large dynamic gas - will OOG quickly
+            // NOTE: we don't want it so large that it exceeds memory bounds (MAX_MEMORY_SIZE = 2^32)
+            // and we really want it small enough that we run at least 1 successful target opcode.
+            setup: [
+                {
+                    offset: 0,
+                    value: new Uint32(1000n)
+                },
+                {
+                    offset: 1,
+                    value: new Uint32(0n)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new CalldataCopy(/*indirect=*/ 0, /*copySizeOffset=*/ 0, /*cdStartOffset=*/ 1, /*dstOffset=*/ 2)
+                ]
+        },
+        {
+            label: 'Near min copy size of 1',
+            // Near-min but actually copies data (more meaningful than size=0 no-op)
+            setup: [
+                {
+                    offset: 0,
+                    value: new Uint32(1n)
+                },
+                {
+                    offset: 1,
+                    value: new Uint32(0n)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new CalldataCopy(/*indirect=*/ 0, /*copySizeOffset=*/ 0, /*cdStartOffset=*/ 1, /*dstOffset=*/ 2)
+                ]
+        }
+    ],
+    [Opcode.SUCCESSCOPY]: [
+        {
+            setup: [],
+            targetInstructions: ()=>[
+                    new SuccessCopy(/*indirect=*/ 0, /*dstOffset=*/ 0)
+                ]
+        }
+    ],
+    [Opcode.RETURNDATASIZE]: [
+        {
+            setup: [],
+            targetInstructions: ()=>[
+                    new ReturndataSize(/*indirect=*/ 0, /*dstOffset=*/ 0)
+                ]
+        }
+    ],
+    // RETURNDATACOPY has dynamic gas scaling with copySize
+    [Opcode.RETURNDATACOPY]: [
+        {
+            label: 'Min copy size',
+            setup: [
+                {
+                    offset: 0,
+                    value: new Uint32(0n)
+                },
+                {
+                    offset: 1,
+                    value: new Uint32(0n)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new ReturndataCopy(/*indirect=*/ 0, /*copySizeOffset=*/ 0, /*rdStartOffset=*/ 1, /*dstOffset=*/ 2)
+                ]
+        },
+        {
+            label: 'Large copy size',
+            // Large copySize to maximize dynamic gas - will OOG quickly
+            // NOTE: we don't want it so large that it exceeds memory bounds (MAX_MEMORY_SIZE = 2^32)
+            // and we really want it small enough that we run at least 1 successful target opcode.
+            setup: [
+                {
+                    offset: 0,
+                    value: new Uint32(1000n)
+                },
+                {
+                    offset: 1,
+                    value: new Uint32(0n)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new ReturndataCopy(/*indirect=*/ 0, /*copySizeOffset=*/ 0, /*rdStartOffset=*/ 1, /*dstOffset=*/ 2)
+                ]
+        },
+        {
+            label: 'Near min copy size of 1',
+            // Near-min but actually copies data (more meaningful than size=0 no-op)
+            setup: [
+                {
+                    offset: 0,
+                    value: new Uint32(1n)
+                },
+                {
+                    offset: 1,
+                    value: new Uint32(0n)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new ReturndataCopy(/*indirect=*/ 0, /*copySizeOffset=*/ 0, /*rdStartOffset=*/ 1, /*dstOffset=*/ 2)
+                ]
+        }
+    ],
+    // ═══════════════════════════════════════════════════════════════════════════
+    // WORLD STATE READS
+    // ═══════════════════════════════════════════════════════════════════════════
+    [Opcode.SLOAD]: [
+        {
+            label: 'Cold read (slot not written)',
+            setup: [
+                {
+                    offset: 0,
+                    value: new Field(Fr.random())
+                }
+            ],
+            targetInstructions: ()=>[
+                    new SLoad(/*indirect=*/ 0, /*slotOffset=*/ 0, /*dstOffset=*/ 1)
+                ]
+        },
+        {
+            label: 'Warm read (from tree)',
+            // Uses pre-inserted storage from insertWarmTreeEntries() which is called after contract deployment
+            setup: [
+                {
+                    offset: 0,
+                    value: new Field(WARM_STORAGE_SLOT)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new SLoad(/*indirect=*/ 0, /*slotOffset=*/ 0, /*dstOffset=*/ 1)
+                ]
+        },
+        {
+            label: 'Warm read (SSTORE first, unique slot per SLOAD)',
+            // Memory layout: slot (incremented), value, constant 1, revertSize, loaded value
+            setup: [
+                {
+                    offset: 0,
+                    value: new Field(Fr.random())
+                },
+                {
+                    offset: 1,
+                    value: new Field(Fr.random())
+                },
+                {
+                    offset: 2,
+                    value: new Field(1n)
+                },
+                {
+                    offset: 3,
+                    value: new Uint32(0n)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new SStore(/*indirect=*/ 0, /*srcOffset=*/ 1, /*slotOffset=*/ 0),
+                    new SLoad(/*indirect=*/ 0, /*slotOffset=*/ 0, /*dstOffset=*/ 4),
+                    new Add(/*indirect=*/ 0, /*aOffset=*/ 0, /*bOffset=*/ 2, /*dstOffset=*/ 0).as(Opcode.ADD_8, Add.wireFormat8)
+                ],
+            cleanupInstructions: ()=>[
+                    new Revert(/*indirect=*/ 0, /*retSizeOffset=*/ 3, /*returnOffset=*/ 0).as(Opcode.REVERT_8, Revert.wireFormat8)
+                ],
+            limit: MAX_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX
+        }
+    ],
+    [Opcode.NOTEHASHEXISTS]: [
+        {
+            label: 'Cold (non-existent)',
+            // Note: Can't easily do "write first" version - would need to know the leaf index
+            // that EMITNOTEHASH will produce, which depends on tree state
+            setup: [
+                {
+                    offset: 0,
+                    value: new Field(Fr.random())
+                },
+                {
+                    offset: 1,
+                    value: randomWithTag(TypeTag.UINT64)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new NoteHashExists(/*indirect=*/ 0, /*noteHashOffset=*/ 0, /*leafIndexOffset=*/ 1, /*existsOffset=*/ 2)
+                ]
+        },
+        {
+            label: 'Warm (exists in tree)',
+            // Uses pre-inserted note hash from insertWarmTreeEntries()
+            setup: [
+                {
+                    offset: 0,
+                    value: new Field(WARM_NOTE_HASH)
+                },
+                {
+                    offset: 1,
+                    value: new Uint64(WARM_NOTE_HASH_LEAF_INDEX)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new NoteHashExists(/*indirect=*/ 0, /*noteHashOffset=*/ 0, /*leafIndexOffset=*/ 1, /*existsOffset=*/ 2)
+                ]
+        }
+    ],
+    [Opcode.NULLIFIEREXISTS]: [
+        {
+            label: 'Non-existent nullifier',
+            setup: [
+                {
+                    offset: 0,
+                    value: new Field(Fr.random())
+                },
+                {
+                    offset: 1,
+                    value: new Field(Fr.random())
+                }
+            ],
+            targetInstructions: ()=>[
+                    new NullifierExists(/*indirect=*/ 0, /*nullifierOffset=*/ 0, /*addressOffset=*/ 1, /*existsOffset=*/ 2)
+                ]
+        },
+        {
+            label: 'Existing nullifier (warm - from tree)',
+            // Uses pre-inserted nullifier from insertWarmTreeEntries()
+            setup: [
+                {
+                    offset: 0,
+                    value: new Field(WARM_NULLIFIER)
+                },
+                {
+                    offset: 1,
+                    value: new Field(WARM_NULLIFIER_ADDRESS.toField())
+                }
+            ],
+            targetInstructions: ()=>[
+                    new NullifierExists(/*indirect=*/ 0, /*nullifierOffset=*/ 0, /*addressOffset=*/ 1, /*existsOffset=*/ 2)
+                ]
+        },
+        {
+            label: 'Existing nullifier (warm - EMITNULLIFIER first)',
+            // Memory layout: nullifier (incremented), constant 1, current address (from GETENVVAR), revertSize, exists result
+            setup: [
+                {
+                    offset: 0,
+                    value: new Field(Fr.random())
+                },
+                {
+                    offset: 1,
+                    value: new Field(1n)
+                },
+                ()=>[
+                        // Get current contract address into offset 2
+                        new GetEnvVar(/*indirect=*/ 0, /*dstOffset=*/ 2, /*varEnum=*/ 0).as(Opcode.GETENVVAR_16, GetEnvVar.wireFormat16)
+                    ],
+                {
+                    offset: 3,
+                    value: new Uint32(0n)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new EmitNullifier(/*indirect=*/ 0, /*nullifierOffset=*/ 0),
+                    new NullifierExists(/*indirect=*/ 0, /*nullifierOffset=*/ 0, /*addressOffset=*/ 2, /*existsOffset=*/ 4),
+                    new Add(/*indirect=*/ 0, /*aOffset=*/ 0, /*bOffset=*/ 1, /*dstOffset=*/ 0).as(Opcode.ADD_8, Add.wireFormat8)
+                ],
+            cleanupInstructions: ()=>[
+                    new Revert(/*indirect=*/ 0, /*retSizeOffset=*/ 3, /*returnOffset=*/ 0).as(Opcode.REVERT_8, Revert.wireFormat8)
+                ],
+            limit: MAX_NULLIFIERS_PER_TX - 1
+        }
+    ],
+    [Opcode.L1TOL2MSGEXISTS]: [
+        {
+            label: 'Cold (non-existent)',
+            setup: [
+                {
+                    offset: 0,
+                    value: new Field(Fr.random())
+                },
+                {
+                    offset: 1,
+                    value: randomWithTag(TypeTag.UINT64)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new L1ToL2MessageExists(/*indirect=*/ 0, /*msgHashOffset=*/ 0, /*msgLeafIndexOffset=*/ 1, /*existsOffset=*/ 2)
+                ]
+        },
+        {
+            label: 'Warm (exists in tree)',
+            // Uses pre-inserted L1 to L2 message from insertWarmTreeEntries()
+            setup: [
+                {
+                    offset: 0,
+                    value: new Field(WARM_L1_TO_L2_MSG)
+                },
+                {
+                    offset: 1,
+                    value: new Uint64(WARM_L1_TO_L2_MSG_LEAF_INDEX)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new L1ToL2MessageExists(/*indirect=*/ 0, /*msgHashOffset=*/ 0, /*msgLeafIndexOffset=*/ 1, /*existsOffset=*/ 2)
+                ]
+        }
+    ],
+    [Opcode.GETCONTRACTINSTANCE]: [
+        {
+            // Use GETENVVAR to get current contract address (varEnum 0 = ADDRESS)
+            // This ensures we're querying a valid deployed contract
+            setup: [
+                ()=>[
+                        new GetEnvVar(/*indirect=*/ 0, /*dstOffset=*/ 0, /*varEnum=*/ 0).as(Opcode.GETENVVAR_16, GetEnvVar.wireFormat16)
+                    ]
+            ],
+            // memberEnum 0 = DEPLOYER
+            targetInstructions: ()=>[
+                    new GetContractInstance(/*indirect=*/ 0, /*addressOffset=*/ 0, /*dstOffset=*/ 1, /*memberEnum=*/ 0)
+                ]
+        }
+    ],
+    // ═══════════════════════════════════════════════════════════════════════════
+    // SIDE-EFFECT LIMITED (have per-TX limit, use nested call pattern)
+    // ═══════════════════════════════════════════════════════════════════════════
+    [Opcode.EMITNOTEHASH]: [
+        {
+            setup: [
+                {
+                    offset: 0,
+                    value: new Field(Fr.random())
+                },
+                {
+                    offset: 1,
+                    value: new Uint32(0n)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new EmitNoteHash(/*indirect=*/ 0, /*noteHashOffset=*/ 0)
+                ],
+            cleanupInstructions: ()=>[
+                    new Revert(/*indirect=*/ 0, /*retSizeOffset=*/ 1, /*returnOffset=*/ 0).as(Opcode.REVERT_8, Revert.wireFormat8)
+                ],
+            limit: MAX_NOTE_HASHES_PER_TX
+        }
+    ],
+    [Opcode.EMITNULLIFIER]: [
+        {
+            // Nullifiers must be unique - increment value after each emit
+            // Memory layout: offset 0 = nullifier value, offset 1 = constant 1 for incrementing
+            setup: [
+                {
+                    offset: 0,
+                    value: new Field(Fr.random())
+                },
+                {
+                    offset: 1,
+                    value: new Field(1n)
+                },
+                {
+                    offset: 2,
+                    value: new Uint32(0n)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new EmitNullifier(/*indirect=*/ 0, /*nullifierOffset=*/ 0),
+                    new Add(/*indirect=*/ 0, /*aOffset=*/ 0, /*bOffset=*/ 1, /*dstOffset=*/ 0).as(Opcode.ADD_8, Add.wireFormat8)
+                ],
+            cleanupInstructions: ()=>[
+                    new Revert(/*indirect=*/ 0, /*retSizeOffset=*/ 2, /*returnOffset=*/ 0).as(Opcode.REVERT_8, Revert.wireFormat8)
+                ],
+            limit: MAX_NULLIFIERS_PER_TX - 1
+        }
+    ],
+    [Opcode.SENDL2TOL1MSG]: [
+        {
+            setup: [
+                {
+                    offset: 0,
+                    value: new Field(Fr.random())
+                },
+                {
+                    offset: 1,
+                    value: new Field(Fr.random())
+                },
+                {
+                    offset: 2,
+                    value: new Uint32(0n)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new SendL2ToL1Message(/*indirect=*/ 0, /*recipientOffset=*/ 0, /*contentOffset=*/ 1)
+                ],
+            cleanupInstructions: ()=>[
+                    new Revert(/*indirect=*/ 0, /*retSizeOffset=*/ 2, /*returnOffset=*/ 0).as(Opcode.REVERT_8, Revert.wireFormat8)
+                ],
+            limit: MAX_L2_TO_L1_MSGS_PER_TX
+        }
+    ],
+    // SSTORE has two modes:
+    // 1. Same slot: Writing to the same slot repeatedly has no per-TX limit - it just overwrites.
+    // 2. Unique slots: Writing to unique slots is limited by MAX_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX.
+    [Opcode.SSTORE]: [
+        {
+            label: 'Same slot (no limit)',
+            setup: [
+                {
+                    offset: 0,
+                    value: new Field(Fr.random())
+                },
+                {
+                    offset: 1,
+                    value: new Field(Fr.random())
+                },
+                {
+                    offset: 2,
+                    value: new Uint32(0n)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new SStore(/*indirect=*/ 0, /*srcOffset=*/ 0, /*slotOffset=*/ 1)
+                ],
+            cleanupInstructions: ()=>[
+                    new Revert(/*indirect=*/ 0, /*retSizeOffset=*/ 2, /*returnOffset=*/ 0).as(Opcode.REVERT_8, Revert.wireFormat8)
+                ]
+        },
+        {
+            label: 'Unique slots (side-effect limited)',
+            setup: [
+                {
+                    offset: 0,
+                    value: new Field(Fr.random())
+                },
+                {
+                    offset: 1,
+                    value: new Field(Fr.random())
+                },
+                {
+                    offset: 2,
+                    value: new Field(1n)
+                },
+                {
+                    offset: 3,
+                    value: new Uint32(0n)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new SStore(/*indirect=*/ 0, /*srcOffset=*/ 0, /*slotOffset=*/ 1),
+                    new Add(/*indirect=*/ 0, /*aOffset=*/ 1, /*bOffset=*/ 2, /*dstOffset=*/ 1).as(Opcode.ADD_8, Add.wireFormat8)
+                ],
+            cleanupInstructions: ()=>[
+                    new Revert(/*indirect=*/ 0, /*retSizeOffset=*/ 3, /*returnOffset=*/ 0).as(Opcode.REVERT_8, Revert.wireFormat8)
+                ],
+            limit: MAX_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX
+        }
+    ],
+    // EMITUNENCRYPTEDLOG - two configs: minimal (many small logs) and max-size (one large log)
+    [Opcode.EMITUNENCRYPTEDLOG]: [
+        {
+            label: 'Many empty logs, revert, repeat',
+            setup: [
+                {
+                    offset: 0,
+                    value: new Uint32(0n)
+                },
+                {
+                    offset: 1,
+                    value: new Uint32(0n)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new EmitUnencryptedLog(/*indirect=*/ 0, /*logSizeOffset=*/ 0, /*logOffset=*/ 1)
+                ],
+            cleanupInstructions: ()=>[
+                    new Revert(/*indirect=*/ 0, /*retSizeOffset=*/ 1, /*returnOffset=*/ 0).as(Opcode.REVERT_8, Revert.wireFormat8)
+                ],
+            // Max logs with 0-field content: floor(4096 / 2) = 2048
+            limit: Math.floor(FLAT_PUBLIC_LOGS_PAYLOAD_LENGTH / PUBLIC_LOG_HEADER_LENGTH)
+        },
+        {
+            label: 'One max size log, revert, repeat',
+            setup: [
+                // logSize = MAX_PUBLIC_LOG_SIZE_IN_FIELDS
+                {
+                    offset: 0,
+                    value: new Uint32(BigInt(MAX_PUBLIC_LOG_SIZE_IN_FIELDS))
+                },
+                {
+                    offset: 1,
+                    value: new Uint32(0n)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new EmitUnencryptedLog(/*indirect=*/ 0, /*logSizeOffset=*/ 0, /*logOffset=*/ 2)
+                ],
+            cleanupInstructions: ()=>[
+                    new Revert(/*indirect=*/ 0, /*retSizeOffset=*/ 1, /*returnOffset=*/ 0).as(Opcode.REVERT_8, Revert.wireFormat8)
+                ],
+            limit: 1
+        }
+    ],
+    // ═══════════════════════════════════════════════════════════════════════════
+    // GADGETS - Random inputs (seeded via SEED env var)
+    // ═══════════════════════════════════════════════════════════════════════════
+    [Opcode.POSEIDON2]: [
+        {
+            // Poseidon2 takes 4 field elements as input
+            setup: Array.from({
+                length: 4
+            }, (_, i)=>({
+                    offset: i,
+                    value: new Field(Fr.random())
+                })),
+            // Poseidon hash data at M[0..3], write result to M[0:3] (reuse results as next inputs)
+            targetInstructions: ()=>[
+                    new Poseidon2(/*indirect=*/ 0, /*inputStateOffset=*/ 0, /*outputStateOffset=*/ 0)
+                ]
+        }
+    ],
+    [Opcode.SHA256COMPRESSION]: [
+        {
+            setup: [
+                // State: 8 x UINT32 at offsets 0-7 (random initial state)
+                ...Array.from({
+                    length: 8
+                }, (_, i)=>({
+                        offset: i,
+                        value: randomWithTag(TypeTag.UINT32)
+                    })),
+                // Inputs: 16 x UINT32 at offsets 8-23 (random message block)
+                ...Array.from({
+                    length: 16
+                }, (_, i)=>({
+                        offset: 8 + i,
+                        value: randomWithTag(TypeTag.UINT32)
+                    }))
+            ],
+            targetInstructions: ()=>[
+                    new Sha256Compression(/*indirect=*/ 0, /*outputOffset=*/ 0, /*stateOffset=*/ 0, /*inputsOffset=*/ 8)
+                ]
+        }
+    ],
+    [Opcode.KECCAKF1600]: [
+        {
+            // Keccak state: 25 x UINT64 (5x5 lane array) with random values
+            setup: Array.from({
+                length: 25
+            }, (_, i)=>({
+                    offset: i,
+                    value: randomWithTag(TypeTag.UINT64)
+                })),
+            targetInstructions: ()=>[
+                    new KeccakF1600(/*indirect=*/ 0, /*dstOffset=*/ 0, /*inputOffset=*/ 0)
+                ]
+        }
+    ],
+    [Opcode.ECADD]: [
+        {
+            // Use the Grumpkin generator point G for both points (valid curve point)
+            setup: [
+                {
+                    offset: 0,
+                    value: new Field(Grumpkin.generator.x)
+                },
+                {
+                    offset: 1,
+                    value: new Field(Grumpkin.generator.y)
+                },
+                {
+                    offset: 2,
+                    value: new Uint1(0n)
+                },
+                {
+                    offset: 3,
+                    value: new Field(Grumpkin.generator.x)
+                },
+                {
+                    offset: 4,
+                    value: new Field(Grumpkin.generator.y)
+                },
+                {
+                    offset: 5,
+                    value: new Uint1(0n)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new EcAdd(/*indirect=*/ 0, /*p1XOffset=*/ 0, /*p1YOffset=*/ 1, /*p1IsInfiniteOffset=*/ 2, /*p2XOffset=*/ 3, /*p2YOffset=*/ 4, /*p2IsInfiniteOffset=*/ 5, /*dstOffset=*/ 0)
+                ]
+        }
+    ],
+    // TORADIXBE has dynamic gas scaling with numLimbs
+    [Opcode.TORADIXBE]: [
+        {
+            label: 'Min limbs',
+            setup: [
+                {
+                    offset: 0,
+                    value: new Field(1n)
+                },
+                {
+                    offset: 1,
+                    value: new Uint32(2n)
+                },
+                {
+                    offset: 2,
+                    value: new Uint32(1n)
+                },
+                {
+                    offset: 3,
+                    value: new Uint1(0n)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new ToRadixBE(/*indirect=*/ 0, /*srcOffset=*/ 0, /*radixOffset=*/ 1, /*numLimbsOffset=*/ 2, /*outputBitsOffset=*/ 3, /*dstOffset=*/ 4)
+                ]
+        },
+        {
+            label: 'Max limbs',
+            setup: [
+                {
+                    offset: 0,
+                    value: new Field(Fr.random())
+                },
+                {
+                    offset: 1,
+                    value: new Uint32(2n)
+                },
+                {
+                    offset: 2,
+                    value: new Uint32(256n)
+                },
+                {
+                    offset: 3,
+                    value: new Uint1(0n)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new ToRadixBE(/*indirect=*/ 0, /*srcOffset=*/ 0, /*radixOffset=*/ 1, /*numLimbsOffset=*/ 2, /*outputBitsOffset=*/ 3, /*dstOffset=*/ 4)
+                ]
+        },
+        {
+            label: 'Radix 3 (slow divmod path)',
+            // Radix 3 bypasses the fast path for power-of-2 radixes (4, 8, 16, 32, 64, 128, 256)
+            // and uses the slow divmod implementation instead
+            setup: [
+                {
+                    offset: 0,
+                    value: new Field(Fr.random())
+                },
+                {
+                    offset: 1,
+                    value: new Uint32(3n)
+                },
+                {
+                    offset: 2,
+                    value: new Uint32(161n)
+                },
+                {
+                    offset: 3,
+                    value: new Uint1(0n)
+                }
+            ],
+            targetInstructions: ()=>[
+                    new ToRadixBE(/*indirect=*/ 0, /*srcOffset=*/ 0, /*radixOffset=*/ 1, /*numLimbsOffset=*/ 2, /*outputBitsOffset=*/ 3, /*dstOffset=*/ 4)
+                ]
+        }
+    ],
+    // ═══════════════════════════════════════════════════════════════════════════
+    // MISC
+    // ═══════════════════════════════════════════════════════════════════════════
+    // DEBUGLOG only has base gas (no dynamic gas scaling) - memory reads only happen
+    // when collectDebugLogs config is enabled
+    [Opcode.DEBUGLOG]: [
+        {
+            setup: [
+                {
+                    offset: 0,
+                    value: new Field(0n)
+                },
+                {
+                    offset: 1,
+                    value: new Field(0n)
+                },
+                {
+                    offset: 2,
+                    value: new Field(0n)
+                },
+                {
+                    offset: 3,
+                    value: new Uint32(0n)
+                }
+            ],
+            // messageSize = 0
+            targetInstructions: ()=>[
+                    new DebugLog(/*indirect=*/ 0, /*levelOffset=*/ 0, /*messageOffset=*/ 1, /*fieldsOffset=*/ 2, /*fieldsSizeOffset=*/ 3, /*messageSize=*/ 0)
+                ]
+        }
+    ]
+};
+/**
+ * Get all spam test cases grouped by opcode.
+ * This is the main entry point for tests - it handles all the complexity of
+ * type variants, multiple configs, etc.
+ *
+ * Returns hierarchical structure for nested describe blocks in tests.
+ *
+ * @param maxConfigsPerOpcode - Maximum number of configs to include per opcode.
+ *                              Defaults to Infinity (no limit). Useful for quick
+ *                              smoke tests where testing all type variants is too slow,
+ *                              or for proving tests that are inherently slower.
+ */ export function getSpamConfigsPerOpcode(maxConfigsPerOpcode = Infinity) {
+    const groups = [];
+    for (const [opcodeKey, configs] of Object.entries(SPAM_CONFIGS)){
+        const opcode = Opcode[Number(opcodeKey)];
+        if (!configs) {
+            throw new Error(`Opcode ${opcode} listed in spam configs, but empty`);
+        }
+        // Apply the limit to the number of configs per opcode
+        const limitedConfigs = configs.slice(0, maxConfigsPerOpcode);
+        const cases = limitedConfigs.map((config)=>({
+                ...config,
+                // unlabeled configs just get opcode name
+                label: config.label ? `${opcode}/${config.label}` : opcode
+            }));
+        groups.push({
+            opcode: opcode,
+            configs: cases
+        });
+    }
+    return groups;
+}
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Create a SET instruction from a MemoryValue.
+ * Chooses smallest SET variant based on offset and value magnitude for optimal bytecode density.
+ */ function createSetInstruction(offset, memValue) {
+    const tag = memValue.getTag();
+    const value = memValue.toBigInt();
+    // SET_8 only supports offset <= 255 and value <= 255
+    if (offset <= 0xff && value <= 0xffn) {
+        return new Set(0, offset, tag, Number(value)).as(Opcode.SET_8, Set.wireFormat8);
+    }
+    // SET_16+ support offset <= 65535
+    if (value <= 0xffffn) {
+        return new Set(0, offset, tag, Number(value)).as(Opcode.SET_16, Set.wireFormat16);
+    }
+    if (value <= 0xffffffffn) {
+        return new Set(0, offset, tag, Number(value)).as(Opcode.SET_32, Set.wireFormat32);
+    }
+    if (value <= 0xffffffffffffffffn) {
+        return new Set(0, offset, tag, value).as(Opcode.SET_64, Set.wireFormat64);
+    }
+    if (value <= 0xffffffffffffffffffffffffffffffffn) {
+        return new Set(0, offset, tag, value).as(Opcode.SET_128, Set.wireFormat128);
+    }
+    return new Set(0, offset, tag, value).as(Opcode.SET_FF, Set.wireFormatFF);
+}
+/**
+ * Append (to the instructions array) the SET instructions for the setup.
+ *
+ * @param instructions - the instructions array to append the setup to
+ * @param setup - the setup configuration specifying what SETs to do
+ */ function appendSetupInstructions(instructions, setup) {
+    for (const item of setup){
+        if (typeof item === 'function') {
+            // item is a function that creates setup instructions (like)
+            instructions.push(...item());
+        } else {
+            // MemSetup
+            instructions.push(createSetInstruction(item.offset, item.value));
+        }
+    }
+}
+/**
+ * Append (to the instructions array) the target instructions nTimes times.
+ *
+ * @param instructions - the instructions array to append the loop to
+ * @param config - the spam config to use
+ * @param nTimes - the number of times to append the target instructions
+ * @returns the number of target instructions appended
+ */ function appendTargetNTimes(instructions, config, nTimes) {
+    for(let i = 0; i < nTimes; i++){
+        instructions.push(...config.targetInstructions());
+    }
+}
+/**
+ * Append (to the instructions array) an infinite loop that maximizes target instruction density.
+ * Fills remaining bytecode space with unrolled target instructions.
+ *
+ * @param instructions - the instructions array to append the loop to
+ * @param config - the spam config to use
+ * @returns the number of target instructions in the loop body
+ */ function appendInfiniteLoop(instructions, config) {
+    const setupBytecode = encodeToBytecode(instructions);
+    const setupSize = setupBytecode.length;
+    // Compute the size of the target instruction(s)
+    const targetSize = encodeToBytecode(config.targetInstructions()).length;
+    // Fill remaining space (loop body) with target instructions
+    const availableForLoopBody = MAX_BYTECODE_BYTES - setupSize - JUMP_SIZE;
+    const numTargetsInLoopBody = Math.floor(availableForLoopBody / targetSize);
+    const loopStartPc = setupSize;
+    appendTargetNTimes(instructions, config, numTargetsInLoopBody);
+    instructions.push(new Jump(loopStartPc)); // JUMP_SIZE (JUMP_32)
+    return numTargetsInLoopBody;
+}
+/**
+ * Generate basic opcode spam bytecode from a SpamConfig.
+ * Spams the target instruction(s) in an infinite loop until out-of-gas.
+ */ export function createOpcodeSpamBytecode(config) {
+    assert(config.limit === undefined, 'If config has `limit`, use createSideEffectLimitedSpamInRevertingNestedCall instead');
+    const instructions = [];
+    // 1. Setup memory
+    appendSetupInstructions(instructions, config.setup);
+    // 2. Infinite loop - maximize calls to target until out-of-gas
+    appendInfiniteLoop(instructions, config);
+    return encodeToBytecode(instructions);
+}
+/**
+ * Generate a bytecode that spams a side-effect limited opcode #limit times
+ * NOT in a loop, but inline/unrolled. Then revert.
+ *
+ * @param config - the side-effect limited spam config to use
+ * @returns the bytecode for the side-effect limited spam
+ */ export function createSideEffectSpamBytecode(config) {
+    assert(config.limit !== undefined, 'If config has `limit`, use createSideEffectLimitedSpamInRevertingNestedCall instead');
+    const instructions = [];
+    // 1. Setup
+    appendSetupInstructions(instructions, config.setup);
+    // 2. Body - run target instruction(s) #limit times
+    appendTargetNTimes(instructions, config, config.limit);
+    // 3. Cleanup (revert)
+    if (config.cleanupInstructions) {
+        instructions.push(...config.cleanupInstructions());
+    }
+    return encodeToBytecode(instructions);
+}
+async function testStandardOpcodeSpam(tester, config, expectToBeTrue) {
+    const bytecode = createOpcodeSpamBytecode(config);
+    const contract = await deployCustomBytecode(bytecode, tester, config.label);
+    await insertWarmTreeEntries(tester.merkleTrees, contract.address);
+    // Should we pass the contract address as calldata?
+    const calldata = config.addressAsCalldata ? [
+        contract.address.toField()
+    ] : [];
+    const result = await executeCustomBytecode(contract, tester, config.label, calldata);
+    // should have halted with out of gas
+    expectToBeTrue(!result.revertCode.isOK());
+    const revertReason = result.findRevertReason()?.message.toLowerCase();
+    const allowedReasons = [
+        'out of gas',
+        'not enough l2gas'
+    ];
+    // expect the reason to match ONE of the allowed reasons
+    expectToBeTrue(allowedReasons.some((allowedReason)=>revertReason?.includes(allowedReason)));
+    return result;
+}
+async function testSideEffectOpcodeSpam(tester, config, expectToBeTrue) {
+    // Inner contract will spam the side-effect limited opcode up to its limit, then REVERT
+    const innerBytecode = createSideEffectSpamBytecode(config);
+    // Outer contract will CALL to inner contract in a loop
+    const outerBytecode = createOpcodeSpamBytecode(EXTERNAL_CALL_CONFIG);
+    const innerContract = await deployCustomBytecode(innerBytecode, tester, `${config.label}_Inner`);
+    const outerContract = await deployCustomBytecode(outerBytecode, tester, `${config.label}_Outer`);
+    // Outer contract reads calldata[0] as inner contract address to CALL to
+    const result = await executeCustomBytecode(outerContract, tester, config.label, [
+        innerContract.address.toField()
+    ]);
+    // should have halted with out of gas or explicit REVERT (assertion failed)
+    expectToBeTrue(!result.revertCode.isOK());
+    const revertReason = result.findRevertReason()?.message.toLowerCase();
+    const allowedReasons = [
+        'assertion failed',
+        'out of gas',
+        'not enough l2gas'
+    ];
+    // expect the reason to match ONE of the allowed reasons
+    expectToBeTrue(allowedReasons.some((allowedReason)=>revertReason?.includes(allowedReason)));
+    // Top-level should _always_ run out of gas for these tests
+    // Check top-level halting message
+    // WARNING: only the C++ simulator (or TsVsCpp) will have haltingMessage
+    const allowedOuterReasons = [
+        'out of gas',
+        'not enough l2gas'
+    ];
+    if (result.callStackMetadata && result.callStackMetadata.length > 0) {
+        const outerCallMetadata = result.callStackMetadata[0];
+        const outerReason = outerCallMetadata.haltingMessage?.toLowerCase();
+        // expect the reason to match ONE of the allowed reasons
+        expectToBeTrue(allowedOuterReasons.some((allowedReason)=>outerReason?.includes(allowedReason)));
+    }
+    return result;
+}
+export async function testOpcodeSpamCase(tester, config, expectToBeTrue = ()=>{}) {
+    if (config.limit) {
+        return await testSideEffectOpcodeSpam(tester, config, expectToBeTrue);
+    }
+    return await testStandardOpcodeSpam(tester, config, expectToBeTrue);
+}