feat: contract class/instance overrides for simulation

Adds `contractClasses?: ContractClassPublic[]` and
`contractInstances?: ContractInstanceWithAddress[]` to `StateOverrides`,
allowing simulation callers to shadow contracts in the simulator's
contract DB without on-chain registration:

```ts
type StateOverrides = {
  publicStorage?: PublicStorageOverride[];
  contractClasses?: ContractClassPublic[];
  contractInstances?: ContractInstanceWithAddress[];
};
```

Plumbing:
- `PublicContractsDB.addContracts({ contractClasses?, contractInstances? })`:
  typed-injection method that pushes overrides onto the contract DB
  checkpoint stack. Bypasses the log/event-extraction path.
- `PublicContractsDB.addContractsFromLogs(ContractDeploymentData)`: log/event-
  based injection used by the C++ AVM contract provider during real
  execution. Disambiguated from the typed variant.
- `PublicProcessorFactory.createContractsDB()` and
  `create(merkleTree, globalVars, config, contractsDB?)`: lets
  `simulatePublicCalls` populate the DB before constructing the processor,
  keeping production block-building paths untouched (they still call
  `create(...)` without the optional `contractsDB`).
- `simulatePublicCalls` injects the contract overrides into a fresh
  `contractsDB` after `createContractsDB()` and before `factory.create(...)`.

Overrides are ephemeral — they live in the per-call contract DB and are
discarded after simulation; nothing reaches committed state.

Author: dbanks12

yarn-project/aztec-node/src/aztec-node/server.ts

@@ -1549,7 +1549,11 @@ export class AztecNodeService implements AztecNode, AztecNodeAdmin, AztecNodeDeb
           maxDebugLogMemoryReads: this.config.rpcSimulatePublicMaxDebugLogMemoryReads,
         }),
       });
-      const processor = publicProcessorFactory.create(merkleTreeFork, newGlobalVariables, config);
+      const contractsDB = publicProcessorFactory.createContractsDB();
+      if (stateOverrides) {
+        contractsDB.addContracts(stateOverrides);
+      }
+      const processor = publicProcessorFactory.create(merkleTreeFork, newGlobalVariables, config, contractsDB);
 
       // REFACTOR: Consider merging ProcessReturnValues into ProcessedTx
       const [processedTxs, failedTxs, _usedTxs, returns, debugLogs] = await processor.process([tx]);

yarn-project/simulator/src/public/public_db_sources.ts

@@ -55,7 +55,8 @@ export class PublicContractsDB implements PublicContractsDBInterface {
     this.log = createLogger('simulator:contracts-data-source', bindings);
   }
 
-  public addContracts(contractDeploymentData: ContractDeploymentData): void {
+  /** Parses raw log data from the C++/NAPI bridge and inserts the resulting contracts into the current checkpoint. */
+  public addContractsFromLogs(contractDeploymentData: ContractDeploymentData): void {
     const currentState = this.getCurrentState();
 
     this.addContractClassesFromEvents(
@@ -71,8 +72,22 @@ export class PublicContractsDB implements PublicContractsDBInterface {
 
   public addNewContracts(tx: Tx): void {
     const contractDeploymentData = AllContractDeploymentData.fromTx(tx);
-    this.addContracts(contractDeploymentData.getNonRevertibleContractDeploymentData());
-    this.addContracts(contractDeploymentData.getRevertibleContractDeploymentData());
+    this.addContractsFromLogs(contractDeploymentData.getNonRevertibleContractDeploymentData());
+    this.addContractsFromLogs(contractDeploymentData.getRevertibleContractDeploymentData());
+  }
+
+  /** Inserts typed contract classes and instances directly into the current checkpoint. */
+  public addContracts(overrides: {
+    contractClasses?: ContractClassPublic[];
+    contractInstances?: ContractInstanceWithAddress[];
+  }): void {
+    const currentState = this.getCurrentState();
+    for (const contractClass of overrides.contractClasses ?? []) {
+      currentState.addClass(contractClass.id, contractClass);
+    }
+    for (const instance of overrides.contractInstances ?? []) {
+      currentState.addInstance(instance.address, instance);
+    }
   }
 
   /**

yarn-project/simulator/src/public/public_processor/public_processor.ts

@@ -73,20 +73,23 @@ export class PublicProcessorFactory {
     this.log = createLogger('simulator:public-processor-factory', bindings);
   }
 
+  /** Creates a fresh PublicContractsDB backed by this factory's data source. */
+  public createContractsDB(): PublicContractsDB {
+    return new PublicContractsDB(this.contractDataSource, this.log.getBindings());
+  }
+
   /**
    * Creates a new instance of a PublicProcessor.
    * @param globalVariables - The global variables for the block being processed.
-   * @param skipFeeEnforcement - Allows disabling balance checks for fee estimations.
+   * @param contractsDB - Optional pre-populated contracts DB; a fresh one is created if omitted.
    * @returns A new instance of a PublicProcessor.
    */
   public create(
     merkleTree: MerkleTreeWriteOperations,
     globalVariables: GlobalVariables,
     config: PublicSimulatorConfig,
+    contractsDB: PublicContractsDB = this.createContractsDB(),
   ): PublicProcessor {
-    const bindings = this.log.getBindings();
-    const contractsDB = new PublicContractsDB(this.contractDataSource, bindings);
-
     const guardedFork = new GuardedMerkleTreeOperations(merkleTree);
     const publicTxSimulator = this.createPublicTxSimulator(guardedFork, contractsDB, globalVariables, config);
 
@@ -97,7 +100,7 @@ export class PublicProcessorFactory {
       publicTxSimulator,
       this.dateProvider,
       this.telemetryClient,
-      createLogger('simulator:public-processor', bindings),
+      createLogger('simulator:public-processor', this.log.getBindings()),
     );
   }
 

yarn-project/simulator/src/public/public_tx_simulator/contract_provider_for_cpp.ts

@@ -61,9 +61,8 @@ export class ContractProviderForCpp implements ContractProvider {
     // Construct ContractDeploymentData from plain object.
     const contractDeploymentData = ContractDeploymentData.fromPlainObject(rawData);
 
-    // Add contracts to the contracts DB
-    this.log.trace(`Calling contractsDB.addContracts`);
-    this.contractsDB.addContracts(contractDeploymentData);
+    this.log.trace(`Calling contractsDB.addContractsFromLogs`);
+    this.contractsDB.addContractsFromLogs(contractDeploymentData);
   };
 
   public getBytecodeCommitment = async (classId: string): Promise<Buffer | undefined> => {

yarn-project/simulator/src/public/public_tx_simulator/public_tx_simulator.ts

@@ -401,7 +401,7 @@ export class PublicTxSimulator implements PublicTxSimulatorInterface {
     // However, things work as expected because later calls to getters on the hintingContractsDB
     // will pick up the new contracts and will generate the necessary hints.
     // So, a consumer of the hints will always see the new contracts.
-    this.contractsDB.addContracts(context.nonRevertibleContractDeploymentData);
+    this.contractsDB.addContractsFromLogs(context.nonRevertibleContractDeploymentData);
   }
 
   /**
@@ -490,7 +490,7 @@ export class PublicTxSimulator implements PublicTxSimulatorInterface {
     // However, things work as expected because later calls to getters on the hintingContractsDB
     // will pick up the new contracts and will generate the necessary hints.
     // So, a consumer of the hints will always see the new contracts.
-    this.contractsDB.addContracts(context.revertibleContractDeploymentData);
+    this.contractsDB.addContractsFromLogs(context.revertibleContractDeploymentData);
   }
 
   private async payFee(context: PublicTxContext) {

yarn-project/stdlib/src/interfaces/state_overrides.ts

@@ -1,21 +1,34 @@
 import { z } from 'zod';
 
+import { type ContractClassPublic, ContractClassPublicSchema } from '../contract/interfaces/contract_class.js';
+import {
+  type ContractInstanceWithAddress,
+  ContractInstanceWithAddressSchema,
+} from '../contract/interfaces/contract_instance.js';
 import { type PublicStorageOverride, PublicStorageOverrideSchema } from './public_storage_override.js';
 
 /**
  * Pre-simulation state overrides. Each field is optional and additive: the simulator applies all
- * provided overrides to the ephemeral world-state fork before running the tx.
+ * provided overrides to the ephemeral world-state fork (and contract DB) before running the tx.
+ *
+ * - `publicStorage`: write specific (contract, slot) pairs in the public-data tree
+ * - `contractClasses`: shadow contract classes in the contract DB
+ * - `contractInstances`: shadow contract instances in the contract DB
  *
  * Modeled after Foundry / Geth `eth_call` state overrides: a single argument that bundles all the
- * override types in one place rather than threading separate parameters through the RPC. Future
- * override flavors (e.g. contract class/instance shadows, nullifier overrides) can be added as
- * additional optional fields without changing the RPC shape.
+ * override types in one place rather than threading separate parameters through the RPC.
  */
 export type StateOverrides = {
   /** Public-storage writes to apply before simulation. */
   publicStorage?: PublicStorageOverride[];
+  /** Contract classes to shadow in the contract DB for the duration of the simulation. */
+  contractClasses?: ContractClassPublic[];
+  /** Contract instances to shadow in the contract DB for the duration of the simulation. */
+  contractInstances?: ContractInstanceWithAddress[];
 };
 
 export const StateOverridesSchema = z.object({
   publicStorage: z.array(PublicStorageOverrideSchema).optional(),
+  contractClasses: z.array(ContractClassPublicSchema).optional(),
+  contractInstances: z.array(ContractInstanceWithAddressSchema).optional(),
 });