@aztec/simulator 0.68.0 → 0.68.1

package/src/avm/avm_tree.ts

@@ -1,4 +1,4 @@
-import { type IndexedTreeId, MerkleTreeId, type MerkleTreeReadOperations, getTreeHeight } from '@aztec/circuit-types';
+import { type IndexedTreeId, MerkleTreeId, type MerkleTreeReadOperations } from '@aztec/circuit-types';
 import { AppendOnlyTreeSnapshot, NullifierLeafPreimage, PublicDataTreeLeafPreimage } from '@aztec/circuits.js';
 import { poseidon2Hash } from '@aztec/foundation/crypto';
 import { Fr } from '@aztec/foundation/fields';
@@ -398,35 +398,36 @@ export class AvmEphemeralForest {
     // First, search the indexed updates (no DB fallback) to find
     // the leafIndex of the leaf with the largest key <= the specified key.
     const minIndexedLeafIndex = this._getLeafIndexOrNextLowestInIndexedUpdates(treeId, key);
+
+    // Then we search on the external DB
+    const leafOrLowLeafWitnessFromExternalDb: GetLeafResult<T> = await this._getLeafOrLowLeafWitnessInExternalDb(
+      treeId,
+      bigIntKey,
+    );
+
+    // If the indexed updates are empty, we can return the leaf from the DB
     if (minIndexedLeafIndex === -1n) {
-      // No leaf is present in the indexed updates that is <= the key,
-      // so retrieve the leaf or low leaf from the underlying DB.
-      const leafOrLowLeafPreimage: GetLeafResult<T> = await this._getLeafOrLowLeafWitnessInExternalDb(
-        treeId,
-        bigIntKey,
-      );
-      return [leafOrLowLeafPreimage, /*pathAbsentInEphemeralTree=*/ true];
+      return [leafOrLowLeafWitnessFromExternalDb, /*pathAbsentInEphemeralTree=*/ true];
+    }
+
+    // Otherwise, we return the closest one. First fetch the leaf from the indexed updates.
+    const minIndexedUpdate: T = this.getIndexedUpdate(treeId, minIndexedLeafIndex);
+
+    // And get both keys
+    const keyFromIndexed = minIndexedUpdate.getKey();
+    const keyFromExternal = leafOrLowLeafWitnessFromExternalDb.preimage.getKey();
+
+    if (keyFromExternal > keyFromIndexed) {
+      // this.log.debug(`Using leaf from external DB for ${MerkleTreeId[treeId]}`);
+      return [leafOrLowLeafWitnessFromExternalDb, /*pathAbsentInEphemeralTree=*/ true];
     } else {
-      // A leaf was found in the indexed updates that is <= the key
-      const minPreimage: T = this.getIndexedUpdate(treeId, minIndexedLeafIndex);
-      if (minPreimage.getKey() === bigIntKey) {
-        // the index found is an exact match, no need to search further
-        const leafInfo = { preimage: minPreimage, index: minIndexedLeafIndex, alreadyPresent: true };
-        return [leafInfo, /*pathAbsentInEphemeralTree=*/ false];
-      } else {
-        // We are starting with the leaf with largest key <= the specified key
-        // Starting at that "min leaf", search for specified key in both the indexed updates
-        // and the underlying DB. If not found, return its low leaf.
-        const [leafOrLowLeafInfo, pathAbsentInEphemeralTree] = await this._searchForLeafOrLowLeaf<ID, T>(
-          treeId,
-          bigIntKey,
-          minPreimage,
-          minIndexedLeafIndex,
-        );
-        // We did not find it - this is unexpected... the leaf OR low leaf should always be present
-        assert(leafOrLowLeafInfo !== undefined, 'Could not find leaf or low leaf. This should not happen!');
-        return [leafOrLowLeafInfo, pathAbsentInEphemeralTree];
-      }
+      // this.log.debug(`Using leaf from indexed DB for ${MerkleTreeId[treeId]}`);
+      const leafInfo = {
+        preimage: minIndexedUpdate,
+        index: minIndexedLeafIndex,
+        alreadyPresent: keyFromIndexed === bigIntKey,
+      };
+      return [leafInfo, /*pathAbsentInEphemeralTree=*/ false];
     }
   }
 
@@ -480,69 +481,6 @@ export class AvmEphemeralForest {
     return { preimage: leafPreimage as T, index: leafIndex, alreadyPresent };
   }
 
-  /**
-   * Search for the leaf for the specified key.
-   * Some leaf with key <= the specified key is expected to be present in the ephemeral tree's "indexed updates".
-   * While searching, this function bounces between our local indexedUpdates and the external DB.
-   *
-   * @param key - The key for which we are look up the leaf or low leaf for.
-   * @param minPreimage - The leaf with the largest key <= the specified key. Expected to be present in local indexedUpdates.
-   * @param minIndex - The index of the leaf with the largest key <= the specified key.
-   * @param T - The type of the preimage (PublicData or Nullifier)
-   * @returns [
-   *     GetLeafResult | undefined - The leaf or low leaf info (preimage & leaf index),
-   *     pathAbsentInEphemeralTree - whether its sibling path is absent in the ephemeral tree (useful during insertions)
-   * ]
-   *
-   * @details We look for the low element by bouncing between our local indexedUpdates map or the external DB
-   * The conditions we are looking for are:
-   * (1) Exact Match: curr.nextKey == key (this is only valid for public data tree)
-   * (2) Sandwich Match: curr.nextKey > key and curr.key < key
-   * (3) Max Condition: curr.next_index == 0 and curr.key < key
-   * Note the min condition does not need to be handled since indexed trees are prefilled with at least the 0 element
-   */
-  private async _searchForLeafOrLowLeaf<ID extends IndexedTreeId, T extends IndexedTreeLeafPreimage>(
-    treeId: ID,
-    key: bigint,
-    minPreimage: T,
-    minIndex: bigint,
-  ): Promise<[GetLeafResult<T> | undefined, /*pathAbsentInEphemeralTree=*/ boolean]> {
-    let found = false;
-    let curr = minPreimage as T;
-    let result: GetLeafResult<T> | undefined = undefined;
-    // Temp to avoid infinite loops - the limit is the number of leaves we may have to read
-    const LIMIT = 2n ** BigInt(getTreeHeight(treeId)) - 1n;
-    let counter = 0n;
-    let lowPublicDataIndex = minIndex;
-    let pathAbsentInEphemeralTree = false;
-    while (!found && counter < LIMIT) {
-      const bigIntKey = key;
-      if (curr.getKey() === bigIntKey) {
-        // We found an exact match - therefore this is an update
-        found = true;
-        result = { preimage: curr, index: lowPublicDataIndex, alreadyPresent: true };
-      } else if (curr.getKey() < bigIntKey && (curr.getNextIndex() === 0n || curr.getNextKey() > bigIntKey)) {
-        // We found it via sandwich or max condition, this is a low nullifier
-        found = true;
-        result = { preimage: curr, index: lowPublicDataIndex, alreadyPresent: false };
-      }
-      // Update the the values for the next iteration
-      else {
-        lowPublicDataIndex = curr.getNextIndex();
-        if (this.hasLocalUpdates(treeId, lowPublicDataIndex)) {
-          curr = this.getIndexedUpdate(treeId, lowPublicDataIndex)!;
-          pathAbsentInEphemeralTree = false;
-        } else {
-          const preimage: IndexedTreeLeafPreimage = (await this.treeDb.getLeafPreimage(treeId, lowPublicDataIndex))!;
-          curr = preimage as T;
-          pathAbsentInEphemeralTree = true;
-        }
-      }
-      counter++;
-    }
-    return [result, pathAbsentInEphemeralTree];
-  }
-
   /**
    * This hashes the preimage to a field element
    */

package/src/avm/errors.ts

@@ -102,10 +102,21 @@ export class TagCheckError extends AvmExecutionError {
  * Error is thrown when a relative memory address resolved to an offset which
  * is out of range, i.e, greater than maxUint32.
  */
-export class AddressOutOfRangeError extends AvmExecutionError {
+export class RelativeAddressOutOfRangeError extends AvmExecutionError {
   constructor(baseAddr: number, relOffset: number) {
     super(`Address out of range. Base address ${baseAddr}, relative offset ${relOffset}`);
-    this.name = 'AddressOutOfRangeError';
+    this.name = 'RelativeAddressOutOfRangeError';
+  }
+}
+
+/**
+ * Error is thrown when a memory slice contains addresses which are
+ * out of range, i.e, greater than maxUint32.
+ */
+export class MemorySliceOutOfRangeError extends AvmExecutionError {
+  constructor(baseAddr: number, size: number) {
+    super(`Memory slice is out of range. Base address ${baseAddr}, size ${size}`);
+    this.name = 'MemorySliceOutOfRangeError';
   }
 }
 

package/src/avm/journal/journal.ts

@@ -64,29 +64,6 @@ export class AvmPersistableStateManager {
     public readonly txHash: TxHash,
   ) {}
 
-  /**
-   * Create a new state manager with some preloaded pending siloed nullifiers
-   */
-  public static async newWithPendingSiloedNullifiers(
-    worldStateDB: WorldStateDB,
-    trace: PublicSideEffectTraceInterface,
-    pendingSiloedNullifiers: Fr[],
-    doMerkleOperations: boolean = false,
-    txHash: TxHash,
-  ) {
-    const parentNullifiers = NullifierManager.newWithPendingSiloedNullifiers(worldStateDB, pendingSiloedNullifiers);
-    const ephemeralForest = await AvmEphemeralForest.create(worldStateDB.getMerkleInterface());
-    return new AvmPersistableStateManager(
-      worldStateDB,
-      trace,
-      /*publicStorage=*/ new PublicStorage(worldStateDB),
-      /*nullifiers=*/ parentNullifiers.fork(),
-      doMerkleOperations,
-      ephemeralForest,
-      txHash,
-    );
-  }
-
   /**
    * Create a new state manager
    */

package/src/avm/journal/nullifiers.ts

@@ -17,17 +17,6 @@ export class NullifierManager {
     private readonly parent?: NullifierManager,
   ) {}
 
-  /**
-   * Create a new nullifiers manager with some preloaded pending siloed nullifiers
-   */
-  public static newWithPendingSiloedNullifiers(hostNullifiers: CommitmentsDB, pendingSiloedNullifiers?: Fr[]) {
-    const cachedSiloedNullifiers = new Set<bigint>();
-    if (pendingSiloedNullifiers !== undefined) {
-      pendingSiloedNullifiers.forEach(nullifier => cachedSiloedNullifiers.add(nullifier.toBigInt()));
-    }
-    return new NullifierManager(hostNullifiers, cachedSiloedNullifiers);
-  }
-
   /**
    * Create a new nullifiers manager forked from this one
    */

package/src/avm/journal/public_storage.ts

@@ -1,4 +1,4 @@
-import { AztecAddress } from '@aztec/circuits.js';
+import { type AztecAddress } from '@aztec/circuits.js';
 import { Fr } from '@aztec/foundation/fields';
 
 import type { PublicStateDB } from '../../index.js';
@@ -33,13 +33,6 @@ export class PublicStorage {
     return new PublicStorage(this.hostPublicStorage, this);
   }
 
-  /**
-   * Get the pending storage.
-   */
-  public getCache() {
-    return this.cache;
-  }
-
   /**
    * Read a storage value from this' cache or parent's (recursively).
    * DOES NOT CHECK HOST STORAGE!
@@ -108,17 +101,6 @@ export class PublicStorage {
   public acceptAndMerge(incomingPublicStorage: PublicStorage) {
     this.cache.acceptAndMerge(incomingPublicStorage.cache);
   }
-
-  /**
-   * Commits ALL staged writes to the host's state.
-   */
-  public async commitToDB() {
-    for (const [contractAddress, cacheAtContract] of this.cache.cachePerContract) {
-      for (const [slot, value] of cacheAtContract) {
-        await this.hostPublicStorage.storageWrite(AztecAddress.fromBigInt(contractAddress), new Fr(slot), value);
-      }
-    }
-  }
 }
 
 /**
@@ -132,8 +114,7 @@ class PublicStorageCache {
    * One inner-map per contract storage address,
    * mapping storage slot to latest staged write value.
    */
-  public cachePerContract: Map<bigint, Map<bigint, Fr>> = new Map();
-  // FIXME: storage ^ should be private, but its value is used in commitToDB
+  private cachePerContract: Map<bigint, Map<bigint, Fr>> = new Map();
 
   /**
    * Read a staged value from storage, if it has been previously written to.

package/src/avm/opcodes/addressing_mode.ts

@@ -1,7 +1,7 @@
 import { strict as assert } from 'assert';
 
 import { TaggedMemory, type TaggedMemoryInterface } from '../avm_memory_types.js';
-import { AddressOutOfRangeError } from '../errors.js';
+import { RelativeAddressOutOfRangeError } from '../errors.js';
 
 export enum AddressingMode {
   DIRECT = 0,
@@ -67,7 +67,7 @@ export class Addressing {
         const baseAddr = Number(mem.get(0).toBigInt());
         resolved[i] += baseAddr;
         if (resolved[i] >= TaggedMemory.MAX_MEMORY_SIZE) {
-          throw new AddressOutOfRangeError(baseAddr, offset);
+          throw new RelativeAddressOutOfRangeError(baseAddr, offset);
         }
       }
       if (mode & AddressingMode.INDIRECT) {

package/src/avm/opcodes/ec_add.ts

@@ -84,10 +84,11 @@ export class EcAdd extends Instruction {
       dest = grumpkin.add(p1, p2);
     }
 
-    memory.set(dstOffset, new Field(dest.x));
-    memory.set(dstOffset + 1, new Field(dest.y));
+    // Important to use setSlice() and not set() in the two following statements as
+    // this checks that the offsets lie within memory range.
+    memory.setSlice(dstOffset, [new Field(dest.x), new Field(dest.y)]);
     // Check representation of infinity for grumpkin
-    memory.set(dstOffset + 2, new Uint1(dest.equals(Point.ZERO) ? 1 : 0));
+    memory.setSlice(dstOffset + 2, [new Uint1(dest.equals(Point.ZERO) ? 1 : 0)]);
 
     memory.assert({ reads: 6, writes: 3, addressing });
   }

package/src/avm/opcodes/external_calls.ts

@@ -39,10 +39,10 @@ abstract class ExternalCall extends Instruction {
     memory.checkTag(TypeTag.UINT32, argsSizeOffset);
 
     const calldataSize = memory.get(argsSizeOffset).toNumber();
+    const calldata = memory.getSlice(argsOffset, calldataSize).map(f => f.toFr());
     memory.checkTagsRange(TypeTag.FIELD, argsOffset, calldataSize);
 
     const callAddress = memory.getAs<Field>(addrOffset);
-    const calldata = memory.getSlice(argsOffset, calldataSize).map(f => f.toFr());
     // If we are already in a static call, we propagate the environment.
     const callType = context.environment.isStaticCall ? 'STATICCALL' : this.type;
 

package/src/avm/opcodes/hashing.ts

@@ -30,9 +30,10 @@ export class Poseidon2 extends Instruction {
     const operands = [this.inputStateOffset, this.outputStateOffset];
     const addressing = Addressing.fromWire(this.indirect, operands.length);
     const [inputOffset, outputOffset] = addressing.resolve(operands, memory);
-    memory.checkTagsRange(TypeTag.FIELD, inputOffset, Poseidon2.stateSize);
 
     const inputState = memory.getSlice(inputOffset, Poseidon2.stateSize);
+    memory.checkTagsRange(TypeTag.FIELD, inputOffset, Poseidon2.stateSize);
+
     const outputState = poseidon2Permutation(inputState);
     memory.setSlice(
       outputOffset,
@@ -68,9 +69,9 @@ export class KeccakF1600 extends Instruction {
     const [dstOffset, inputOffset] = addressing.resolve(operands, memory);
     context.machineState.consumeGas(this.gasCost());
 
+    const stateData = memory.getSlice(inputOffset, inputSize).map(word => word.toBigInt());
     memory.checkTagsRange(TypeTag.UINT64, inputOffset, inputSize);
 
-    const stateData = memory.getSlice(inputOffset, inputSize).map(word => word.toBigInt());
     const updatedState = keccakf1600(stateData);
 
     const res = updatedState.map(word => new Uint64(word));
@@ -113,11 +114,12 @@ export class Sha256Compression extends Instruction {
 
     // Note: size of output is same as size of state
     context.machineState.consumeGas(this.gasCost());
+    const inputs = Uint32Array.from(memory.getSlice(inputsOffset, INPUTS_SIZE).map(word => word.toNumber()));
+    const state = Uint32Array.from(memory.getSlice(stateOffset, STATE_SIZE).map(word => word.toNumber()));
+
     memory.checkTagsRange(TypeTag.UINT32, inputsOffset, INPUTS_SIZE);
     memory.checkTagsRange(TypeTag.UINT32, stateOffset, STATE_SIZE);
 
-    const state = Uint32Array.from(memory.getSlice(stateOffset, STATE_SIZE).map(word => word.toNumber()));
-    const inputs = Uint32Array.from(memory.getSlice(inputsOffset, INPUTS_SIZE).map(word => word.toNumber()));
     const output = sha256Compression(state, inputs);
 
     // Conversion required from Uint32Array to Uint32[] (can't map directly, need `...`)

package/src/avm/opcodes/misc.ts

@@ -39,14 +39,15 @@ export class DebugLog extends Instruction {
 
     memory.checkTag(TypeTag.UINT32, fieldsSizeOffset);
     const fieldsSize = memory.get(fieldsSizeOffset).toNumber();
+
+    const rawMessage = memory.getSlice(messageOffset, this.messageSize);
+    const fields = memory.getSlice(fieldsOffset, fieldsSize);
+
     memory.checkTagsRange(TypeTag.UINT8, messageOffset, this.messageSize);
     memory.checkTagsRange(TypeTag.FIELD, fieldsOffset, fieldsSize);
 
     context.machineState.consumeGas(this.gasCost(this.messageSize + fieldsSize));
 
-    const rawMessage = memory.getSlice(messageOffset, this.messageSize);
-    const fields = memory.getSlice(fieldsOffset, fieldsSize);
-
     // Interpret str<N> = [u8; N] to string.
     const messageAsStr = rawMessage.map(field => String.fromCharCode(field.toNumber())).join('');
     const formattedStr = applyStringFormatting(

package/src/avm/opcodes/multi_scalar_mul.ts

@@ -46,6 +46,12 @@ export class MultiScalarMul extends Instruction {
     if (pointsReadLength % 3 !== 0) {
       throw new InstructionExecutionError(`Points vector offset should be a multiple of 3, was ${pointsReadLength}`);
     }
+
+    // Get the unrolled (x, y, inf) representing the points
+    // Important to perform this before tag validation, as getSlice() first checks
+    // that the slice is not out of memory range. This needs to be aligned with circuit.
+    const pointsVector = memory.getSlice(pointsOffset, pointsReadLength);
+
     // Divide by 3 since each point is represented as a triplet to get the number of points
     const numPoints = pointsReadLength / 3;
     // The tag for each triplet will be (Field, Field, Uint8)
@@ -56,8 +62,6 @@ export class MultiScalarMul extends Instruction {
       // Check Uint1 (inf flag)
       memory.checkTag(TypeTag.UINT1, offset + 2);
     }
-    // Get the unrolled (x, y, inf) representing the points
-    const pointsVector = memory.getSlice(pointsOffset, pointsReadLength);
 
     // The size of the scalars vector is twice the NUMBER of points because of the scalar limb decomposition
     const scalarReadLength = numPoints * 2;
@@ -106,10 +110,11 @@ export class MultiScalarMul extends Instruction {
       }
     }, grumpkin.mul(firstBaseScalarPair[0], firstBaseScalarPair[1]));
 
-    memory.set(outputOffset, new Field(outputPoint.x));
-    memory.set(outputOffset + 1, new Field(outputPoint.y));
+    // Important to use setSlice() and not set() in the two following statements as
+    // this checks that the offsets lie within memory range.
+    memory.setSlice(outputOffset, [new Field(outputPoint.x), new Field(outputPoint.y)]);
     // Check representation of infinity for grumpkin
-    memory.set(outputOffset + 2, new Uint1(outputPoint.equals(Point.ZERO) ? 1 : 0));
+    memory.setSlice(outputOffset + 2, [new Uint1(outputPoint.equals(Point.ZERO) ? 1 : 0)]);
 
     memory.assert({
       reads: 1 + pointsReadLength + scalarReadLength /* points and scalars */,

package/src/public/bytecode_errors.ts

@@ -0,0 +1,6 @@
+export class ContractClassBytecodeError extends Error {
+  constructor(contractAddress: string) {
+    super(`Failed to get bytecode for contract at address ${contractAddress}`);
+    this.name = 'ContractClassBytecodeError';
+  }
+}

package/src/public/enqueued_call_side_effect_trace.ts

@@ -24,6 +24,7 @@ import {
   MAX_L2_TO_L1_MSGS_PER_TX,
   MAX_NOTE_HASHES_PER_TX,
   MAX_NULLIFIERS_PER_TX,
+  MAX_PUBLIC_CALLS_TO_UNIQUE_CONTRACT_CLASS_IDS,
   MAX_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX,
   MAX_TOTAL_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX,
   MAX_UNENCRYPTED_LOGS_PER_TX,
@@ -58,6 +59,7 @@ import { type AvmExecutionEnvironment } from '../avm/avm_execution_environment.j
 import { type EnqueuedPublicCallExecutionResultWithSideEffects, type PublicFunctionCallResult } from './execution.js';
 import { SideEffectLimitReachedError } from './side_effect_errors.js';
 import { type PublicSideEffectTraceInterface } from './side_effect_trace_interface.js';
+import { UniqueClassIds } from './unique_class_ids.js';
 
 const emptyPublicDataPath = () => new Array(PUBLIC_DATA_TREE_HEIGHT).fill(Fr.zero());
 const emptyNoteHashPath = () => new Array(NOTE_HASH_TREE_HEIGHT).fill(Fr.zero());
@@ -128,6 +130,8 @@ export class PublicEnqueuedCallSideEffectTrace implements PublicSideEffectTraceI
      *  otherwise the public kernel can fail to prove because TX limits are breached.
      */
     private readonly previousSideEffectArrayLengths: SideEffectArrayLengths = SideEffectArrayLengths.empty(),
+    /** We need to track the set of class IDs used for bytecode retrieval to deduplicate and enforce limits. */
+    private gotBytecodeFromClassIds: UniqueClassIds = new UniqueClassIds(),
   ) {
     this.log.debug(`Creating trace instance with startSideEffectCounter: ${startSideEffectCounter}`);
     this.sideEffectCounter = startSideEffectCounter;
@@ -145,6 +149,7 @@ export class PublicEnqueuedCallSideEffectTrace implements PublicSideEffectTraceI
         this.previousSideEffectArrayLengths.l2ToL1Msgs + this.l2ToL1Messages.length,
         this.previousSideEffectArrayLengths.unencryptedLogs + this.unencryptedLogs.length,
       ),
+      this.gotBytecodeFromClassIds.fork(),
     );
   }
 
@@ -152,7 +157,7 @@ export class PublicEnqueuedCallSideEffectTrace implements PublicSideEffectTraceI
     // sanity check to avoid merging the same forked trace twice
     assert(
       !forkedTrace.alreadyMergedIntoParent,
-      'Cannot merge a forked trace that has already been merged into its parent!',
+      'Bug! Cannot merge a forked trace that has already been merged into its parent!',
     );
     forkedTrace.alreadyMergedIntoParent = true;
 
@@ -171,10 +176,21 @@ export class PublicEnqueuedCallSideEffectTrace implements PublicSideEffectTraceI
   }
 
   private mergeHints(forkedTrace: this) {
+    this.gotBytecodeFromClassIds.acceptAndMerge(forkedTrace.gotBytecodeFromClassIds);
+
     this.avmCircuitHints.enqueuedCalls.items.push(...forkedTrace.avmCircuitHints.enqueuedCalls.items);
 
     this.avmCircuitHints.contractInstances.items.push(...forkedTrace.avmCircuitHints.contractInstances.items);
-    this.avmCircuitHints.contractBytecodeHints.items.push(...forkedTrace.avmCircuitHints.contractBytecodeHints.items);
+
+    // merge in contract bytecode hints
+    // UniqueClassIds should prevent duplication
+    for (const [contractClassId, bytecodeHint] of forkedTrace.avmCircuitHints.contractBytecodeHints) {
+      assert(
+        !this.avmCircuitHints.contractBytecodeHints.has(contractClassId),
+        'Bug preventing duplication of contract bytecode hints',
+      );
+      this.avmCircuitHints.contractBytecodeHints.set(contractClassId, bytecodeHint);
+    }
 
     this.avmCircuitHints.publicDataReads.items.push(...forkedTrace.avmCircuitHints.publicDataReads.items);
     this.avmCircuitHints.publicDataWrites.items.push(...forkedTrace.avmCircuitHints.publicDataWrites.items);
@@ -405,6 +421,14 @@ export class PublicEnqueuedCallSideEffectTrace implements PublicSideEffectTraceI
     lowLeafIndex: Fr = Fr.zero(),
     lowLeafPath: Fr[] = emptyNullifierPath(),
   ) {
+    // FIXME: The way we are hinting contract bytecodes is fundamentally broken.
+    // We are mapping contract class ID to a bytecode hint
+    // But a bytecode hint is tied to a contract INSTANCE.
+    // What if you encounter another contract instance with the same class ID?
+    // We can't hint that instance too since there is already an entry in the hints set that class ID.
+    // But without that instance hinted, the circuit can't prove that the called contract address
+    // actually corresponds to any class ID.
+
     const membershipHint = new AvmNullifierReadTreeHint(lowLeafPreimage, lowLeafIndex, lowLeafPath);
     const instance = new AvmContractInstanceHint(
       contractAddress,
@@ -416,13 +440,57 @@ export class PublicEnqueuedCallSideEffectTrace implements PublicSideEffectTraceI
       contractInstance.publicKeys,
       membershipHint,
     );
-    // We need to deduplicate the contract instances based on addresses
-    this.avmCircuitHints.contractBytecodeHints.items.push(
-      new AvmContractBytecodeHints(bytecode, instance, contractClass),
-    );
+
+    // Always hint the contract instance separately from the bytecode hint.
+    // Since the bytecode hints are keyed by class ID, we need to hint the instance separately
+    // since there might be multiple instances hinted for the same class ID.
+    this.avmCircuitHints.contractInstances.items.push(instance);
     this.log.debug(
-      `Bytecode retrieval for contract execution traced: exists=${exists}, instance=${jsonStringify(contractInstance)}`,
+      `Tracing contract instance for bytecode retrieval: exists=${exists}, instance=${jsonStringify(contractInstance)}`,
+    );
+
+    if (!exists) {
+      // this ensures there are no duplicates
+      this.log.debug(`Contract address ${contractAddress} does not exist. Not tracing bytecode & class ID.`);
+      return;
+    }
+    // We already hinted this bytecode. No need to
+    // Don't we still need to hint if the class ID already exists?
+    // Because the circuit needs to prove that the called contract address corresponds to the class ID.
+    // To do so, the circuit needs to know the class ID in the
+    if (this.gotBytecodeFromClassIds.has(contractInstance.contractClassId.toString())) {
+      // this ensures there are no duplicates
+      this.log.debug(
+        `Contract class id ${contractInstance.contractClassId.toString()} already exists in previous hints`,
+      );
+      return;
+    }
+
+    // If we could actually allow contract calls after the limit was reached, we would hint even if we have
+    // surpassed the limit of unique class IDs (still trace the failed bytecode retrieval)
+    // because the circuit needs to know the class ID to know when the limit is hit.
+    // BUT, the issue with this approach is that the sequencer could lie and say "this call was to a new class ID",
+    // and the circuit cannot prove that it's not true without deriving the class ID from bytecode,
+    // proving that it corresponds to the called contract address, and proving that the class ID wasn't already
+    // present/used. That would require more bytecode hashing which is exactly what this limit exists to avoid.
+    if (this.gotBytecodeFromClassIds.size() >= MAX_PUBLIC_CALLS_TO_UNIQUE_CONTRACT_CLASS_IDS) {
+      this.log.debug(
+        `Bytecode retrieval failure for contract class ID ${contractInstance.contractClassId.toString()} (limit reached)`,
+      );
+      throw new SideEffectLimitReachedError(
+        'contract calls to unique class IDs',
+        MAX_PUBLIC_CALLS_TO_UNIQUE_CONTRACT_CLASS_IDS,
+      );
+    }
+
+    this.log.debug(`Tracing bytecode & contract class for bytecode retrieval: class=${jsonStringify(contractClass)}`);
+    this.avmCircuitHints.contractBytecodeHints.set(
+      contractInstance.contractClassId.toString(),
+      new AvmContractBytecodeHints(bytecode, instance, contractClass),
     );
+    // After adding the bytecode hint, mark the classId as retrieved to avoid duplication.
+    // The above map alone isn't sufficient because we need to check the parent trace's (and its parent) as well.
+    this.gotBytecodeFromClassIds.add(contractInstance.contractClassId.toString());
   }
 
   /**