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

docs/docs-developers/docs/aztec-js/how_to_test.md

@@ -71,6 +71,12 @@ Use `.simulate()` to test reverts without spending gas. The simulation will thro
 
 `.simulate()` accepts a `stateOverrides` option that injects values into the simulator's ephemeral world-state fork before the call runs. The override is scoped to that single simulation; the real chain state is untouched.
 
+Three override flavors are supported:
+
+- `publicStorage`: write `(contract, slot, value)` triples into the public-data tree.
+- `contractClasses`: shadow contract classes in the simulator's contract DB (as if they had been published on the class registry).
+- `contractInstances`: shadow contract instances at specific addresses (as if they had been deployed, possibly pointing at one of the shadowed classes).
+
 Override a public-storage slot:
 
 ```typescript
@@ -81,10 +87,23 @@ const result = await contract.methods.read_balance(account).simulate({
 });
 ```
 
+Override a contract's class — useful for testing against a mock implementation:
+
+```typescript
+const result = await contract.methods.foo().simulate({
+  stateOverrides: {
+    contractClasses: [mockClass],
+    contractInstances: [{ ...existingInstance, currentContractClassId: mockClass.id }],
+  },
+});
+```
+
 Use this to:
 
 - Set up state preconditions without running a full setup transaction
 - Reproduce a bug from production by pinning storage to the values seen at a specific block
+- Swap a contract's bytecode for a mock implementation in tests
+- Simulate calls against contracts that aren't yet deployed
 - Test branches that depend on rare values without orchestrating the contract calls that produce them
 
 ## Further reading

docs/docs-developers/docs/resources/migration_notes.md

@@ -11,17 +11,25 @@ Aztec is in active development. Each version may introduce breaking changes that
 
 ### [Aztec.js] `simulate` accepts `stateOverrides` for fork-style testing
 
-`Contract.methods.foo(...).simulate(...)` now accepts a `stateOverrides` option that injects values into the simulator's ephemeral world-state fork before the call runs. The first override flavor is `publicStorage`, which writes a `(contract, slot, value)` triple into the public-data tree as if a previous tx had set it. Overrides are scoped to the simulation; the real chain state is untouched.
+`Contract.methods.foo(...).simulate(...)` now accepts a `stateOverrides` option that injects values into the simulator's ephemeral world-state fork before the call runs. Three override flavors are supported:
+
+- `publicStorage`: write a `(contract, slot, value)` triple into the public-data tree as if a previous tx had set it.
+- `contractClasses`: shadow contract classes in the simulator's contract DB as if they had been published on the class registry.
+- `contractInstances`: shadow contract instances at specific addresses as if they had been deployed (possibly pointing at one of the shadowed classes).
+
+Overrides are scoped to the simulation; the real chain state is untouched.
 
 ```typescript
 const result = await contract.methods.read_balance(account).simulate({
   stateOverrides: {
     publicStorage: [{ contract: contract.address, slot: BALANCE_SLOT, value: new Fr(1_000_000n) }],
+    contractClasses: [shadowedClass],
+    contractInstances: [shadowedInstance],
   },
 });
 ```
 
-The same option flows through `wallet.simulateTx`, `pxe.simulateTx`, and the `simulatePublicCalls` RPC on `AztecNode`. The bundled `StateOverrides` shape is forward-compatible: future override flavors (contract class/instance shadows, etc.) will be added as additional optional fields without changing the RPC.
+The same option flows through `wallet.simulateTx`, `pxe.simulateTx`, and the `simulatePublicCalls` RPC on `AztecNode`. The bundled `StateOverrides` shape is forward-compatible: future override flavors will be added as additional optional fields without changing the RPC.
 
 ### [PXE] `proveTx` takes an options bag
 

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

@@ -39,7 +39,7 @@ import {
   SequencerClient,
   type SequencerPublisher,
 } from '@aztec/sequencer-client';
-import { PublicProcessorFactory } from '@aztec/simulator/server';
+import { PublicContractsDB, PublicProcessorFactory } from '@aztec/simulator/server';
 import {
   AttestationsBlockWatcher,
   EpochPruneWatcher,
@@ -1549,7 +1549,11 @@ export class AztecNodeService implements AztecNode, AztecNodeAdmin, AztecNodeDeb
           maxDebugLogMemoryReads: this.config.rpcSimulatePublicMaxDebugLogMemoryReads,
         }),
       });
-      const processor = publicProcessorFactory.create(merkleTreeFork, newGlobalVariables, config);
+      const contractsDB = new PublicContractsDB(this.contractDataSource, this.log.getBindings());
+      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

@@ -76,17 +76,15 @@ export class PublicProcessorFactory {
   /**
    * 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 constructed if omitted.
    * @returns A new instance of a PublicProcessor.
    */
   public create(
     merkleTree: MerkleTreeWriteOperations,
     globalVariables: GlobalVariables,
     config: PublicSimulatorConfig,
+    contractsDB: PublicContractsDB = new PublicContractsDB(this.contractDataSource, this.log.getBindings()),
   ): 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 +95,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(),
 });