@aztec/pxe 0.0.1-commit.9ef841308 → 0.0.1-commit.a5db02d

package/src/contract_function_simulator/aztec_node_read_cache.ts

@@ -0,0 +1,89 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { BlockHash, BlockParameter } from '@aztec/stdlib/block';
+import type { AztecNode } from '@aztec/stdlib/interfaces/server';
+import type { TxHash } from '@aztec/stdlib/tx';
+
+/**
+ * Per-execution cache for immutable Aztec node reads.
+ */
+export class AztecNodeReadCache {
+  private readonly cache = new Map<string, Promise<unknown>>();
+
+  constructor(private readonly aztecNode: AztecNode) {}
+
+  /** Fetches a block without reissuing the same node request. */
+  public getBlock(block: BlockParameter) {
+    return this.#cachedRead(`block:${this.#keyPart(block)}`, () => this.aztecNode.getBlock(block));
+  }
+
+  /** Fetches a transaction receipt with its effect attached. */
+  public getTxReceiptWithEffect(txHash: TxHash) {
+    return this.#cachedRead(`tx-receipt-with-effect:${txHash.toString()}`, () =>
+      this.aztecNode.getTxReceipt(txHash, { includeTxEffect: true } as const),
+    );
+  }
+
+  /** Fetches an archive-tree witness for a block hash. */
+  public getBlockHashMembershipWitness(referenceBlock: BlockParameter, blockHash: BlockHash) {
+    return this.#cachedRead(
+      `block-hash-membership-witness:${this.#keyPart(referenceBlock)}:${blockHash.toString()}`,
+      () => this.aztecNode.getBlockHashMembershipWitness(referenceBlock, blockHash),
+    );
+  }
+
+  /** Fetches a public-data-tree witness for a leaf slot. */
+  public getPublicDataWitness(referenceBlock: BlockParameter, leafSlot: Fr) {
+    return this.#cachedRead(`public-data-witness:${this.#keyPart(referenceBlock)}:${leafSlot.toString()}`, () =>
+      this.aztecNode.getPublicDataWitness(referenceBlock, leafSlot),
+    );
+  }
+
+  /** Fetches public storage for a single slot. */
+  public getPublicStorageAt(referenceBlock: BlockParameter, contractAddress: AztecAddress, storageSlot: Fr) {
+    return this.#cachedRead(
+      `public-storage:${this.#keyPart(referenceBlock)}:${contractAddress.toString()}:${storageSlot.toString()}`,
+      () => this.aztecNode.getPublicStorageAt(referenceBlock, contractAddress, storageSlot),
+    );
+  }
+
+  /** Fetches a contiguous public storage range, reusing cached reads for overlapping slots. */
+  public getPublicStorageRange(
+    referenceBlock: BlockParameter,
+    contractAddress: AztecAddress,
+    startStorageSlot: Fr,
+    numberOfElements: number,
+  ) {
+    const slots = Array(numberOfElements)
+      .fill(0)
+      .map((_, i) => new Fr(startStorageSlot.value + BigInt(i)));
+
+    return Promise.all(slots.map(storageSlot => this.getPublicStorageAt(referenceBlock, contractAddress, storageSlot)));
+  }
+
+  #cachedRead<T>(key: string, fetch: () => Promise<T>): Promise<T> {
+    const cached = this.cache.get(key);
+    if (cached) {
+      return cached as Promise<T>;
+    }
+
+    const promise = fetch();
+    promise.catch(() => this.cache.delete(key));
+    this.cache.set(key, promise);
+    return promise;
+  }
+
+  #keyPart(value: unknown): string {
+    if (['string', 'number', 'bigint', 'boolean'].includes(typeof value)) {
+      return String(value);
+    }
+    if (value && typeof value === 'object') {
+      const toString = (value as { toString?: () => string }).toString;
+      if (toString && toString !== Object.prototype.toString) {
+        return toString.call(value);
+      }
+      return JSON.stringify(value, (_key, nested) => (typeof nested === 'bigint' ? nested.toString() : nested));
+    }
+    return String(value);
+  }
+}

package/src/contract_function_simulator/contract_function_simulator.ts

@@ -19,6 +19,7 @@ import {
   MAX_PRIVATE_LOGS_PER_TX,
   MAX_TX_LIFETIME,
   PRIVATE_TX_L2_GAS_OVERHEAD,
+  PUBLIC_DATA_WRITE_LENGTH,
   PUBLIC_TX_L2_GAS_OVERHEAD,
   TX_DA_GAS_OVERHEAD,
 } from '@aztec/constants';
@@ -42,7 +43,7 @@ import type { FunctionCall } from '@aztec/stdlib/abi';
 import { FunctionSelector, FunctionType } from '@aztec/stdlib/abi';
 import type { AuthWitness } from '@aztec/stdlib/auth-witness';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
-import type { BlockParameter } from '@aztec/stdlib/block';
+import type { BlockParameter, L2TipsProvider } from '@aztec/stdlib/block';
 import { Gas } from '@aztec/stdlib/gas';
 import {
   computeNoteHashNonce,
@@ -76,9 +77,11 @@ import {
 import { PrivateLog } from '@aztec/stdlib/logs';
 import { ScopedL2ToL1Message } from '@aztec/stdlib/messaging';
 import { ChonkProof } from '@aztec/stdlib/proofs';
+import { MerkleTreeId } from '@aztec/stdlib/trees';
 import {
   BlockHeader,
   CallContext,
+  type ContractOverrides,
   HashedValues,
   type OffchainEffect,
   PrivateExecutionResult,
@@ -89,33 +92,34 @@ import {
   getFinalMinRevertibleSideEffectCounter,
 } from '@aztec/stdlib/tx';
 
-import type { AccessScopes } from '../access_scopes.js';
-import type { ContractSyncService } from '../contract_sync/contract_sync_service.js';
-import type { MessageContextService } from '../messages/message_context_service.js';
+import type { ContractClassService } from '../contract/contract_class_service.js';
+import type { ContractSyncService } from '../contract/contract_sync_service.js';
+import type { ExecutionHooks } from '../hooks/index.js';
+import type { TxResolverService } from '../messages/tx_resolver_service.js';
 import type { AddressStore } from '../storage/address_store/address_store.js';
 import { CapsuleService } from '../storage/capsule_store/capsule_service.js';
 import type { CapsuleStore } from '../storage/capsule_store/capsule_store.js';
 import type { ContractStore } from '../storage/contract_store/contract_store.js';
+import { FactService } from '../storage/fact_store/index.js';
+import type { FactStore } from '../storage/fact_store/index.js';
 import type { NoteStore } from '../storage/note_store/note_store.js';
 import type { PrivateEventStore } from '../storage/private_event_store/private_event_store.js';
 import type { RecipientTaggingStore } from '../storage/tagging_store/recipient_tagging_store.js';
-import type { SenderAddressBookStore } from '../storage/tagging_store/sender_address_book_store.js';
 import type { SenderTaggingStore } from '../storage/tagging_store/sender_tagging_store.js';
+import type { TaggingSecretSourcesStore } from '../storage/tagging_store/tagging_secret_sources_store.js';
+import { AnchoredContractData } from './anchored_contract_data.js';
 import type { BenchmarkedNode } from './benchmarked_node.js';
 import { ExecutionNoteCache } from './execution_note_cache.js';
 import { ExecutionTaggingIndexCache } from './execution_tagging_index_cache.js';
 import { HashedValuesCache } from './hashed_values_cache.js';
-import { Oracle } from './oracle/oracle.js';
+import { buildACIRCallback } from './oracle/acir_callback.js';
 import { executePrivateFunction } from './oracle/private_execution.js';
 import { PrivateExecutionOracle } from './oracle/private_execution_oracle.js';
 import { UtilityExecutionOracle } from './oracle/utility_execution_oracle.js';
+import { TransientArrayService } from './transient_array_service.js';
 
 /** Options for ContractFunctionSimulator.run. */
 export type ContractSimulatorRunOpts = {
-  /** The address of the contract (should match request.origin). */
-  contractAddress: AztecAddress;
-  /** The function selector of the entry point. */
-  selector: FunctionSelector;
   /** The address calling the function. Can be replaced to simulate a call from another contract or account. */
   msgSender?: AztecAddress;
   /** The block header to use as base state for this run. */
@@ -123,7 +127,7 @@ export type ContractSimulatorRunOpts = {
   /** The address used as a tagging sender when emitting private logs. */
   senderForTags?: AztecAddress;
   /** The accounts whose notes we can access in this call. */
-  scopes: AccessScopes;
+  scopes: AztecAddress[];
   /** The job ID for staged writes. */
   jobId: string;
 };
@@ -131,18 +135,24 @@ export type ContractSimulatorRunOpts = {
 /** Args for ContractFunctionSimulator constructor. */
 export type ContractFunctionSimulatorArgs = {
   contractStore: ContractStore;
+  contractClassService: ContractClassService;
+  /** Per-simulation contract overrides. */
+  overrides?: ContractOverrides;
   noteStore: NoteStore;
   keyStore: KeyStore;
   addressStore: AddressStore;
   aztecNode: AztecNode;
+  l2TipsStore: L2TipsProvider;
   senderTaggingStore: SenderTaggingStore;
   recipientTaggingStore: RecipientTaggingStore;
-  senderAddressBookStore: SenderAddressBookStore;
+  taggingSecretSourcesStore: TaggingSecretSourcesStore;
   capsuleStore: CapsuleStore;
+  factStore: FactStore;
   privateEventStore: PrivateEventStore;
   simulator: CircuitSimulator;
   contractSyncService: ContractSyncService;
-  messageContextService: MessageContextService;
+  txResolver: TxResolverService;
+  hooks?: ExecutionHooks;
 };
 
 /**
@@ -151,33 +161,43 @@ export type ContractFunctionSimulatorArgs = {
 export class ContractFunctionSimulator {
   private readonly log: Logger;
   private readonly contractStore: ContractStore;
+  private readonly contractClassService: ContractClassService;
+  private readonly overrides: ContractOverrides | undefined;
   private readonly noteStore: NoteStore;
   private readonly keyStore: KeyStore;
   private readonly addressStore: AddressStore;
   private readonly aztecNode: AztecNode;
+  private readonly l2TipsStore: L2TipsProvider;
   private readonly senderTaggingStore: SenderTaggingStore;
   private readonly recipientTaggingStore: RecipientTaggingStore;
-  private readonly senderAddressBookStore: SenderAddressBookStore;
+  private readonly taggingSecretSourcesStore: TaggingSecretSourcesStore;
   private readonly capsuleStore: CapsuleStore;
+  private readonly factStore: FactStore;
   private readonly privateEventStore: PrivateEventStore;
   private readonly simulator: CircuitSimulator;
   private readonly contractSyncService: ContractSyncService;
-  private readonly messageContextService: MessageContextService;
+  private readonly txResolver: TxResolverService;
+  private readonly hooks: ExecutionHooks | undefined;
 
   constructor(args: ContractFunctionSimulatorArgs) {
     this.contractStore = args.contractStore;
+    this.contractClassService = args.contractClassService;
+    this.overrides = args.overrides;
     this.noteStore = args.noteStore;
     this.keyStore = args.keyStore;
     this.addressStore = args.addressStore;
     this.aztecNode = args.aztecNode;
+    this.l2TipsStore = args.l2TipsStore;
     this.senderTaggingStore = args.senderTaggingStore;
     this.recipientTaggingStore = args.recipientTaggingStore;
-    this.senderAddressBookStore = args.senderAddressBookStore;
+    this.taggingSecretSourcesStore = args.taggingSecretSourcesStore;
     this.capsuleStore = args.capsuleStore;
+    this.factStore = args.factStore;
     this.privateEventStore = args.privateEventStore;
     this.simulator = args.simulator;
     this.contractSyncService = args.contractSyncService;
-    this.messageContextService = args.messageContextService;
+    this.txResolver = args.txResolver;
+    this.hooks = args.hooks;
     this.log = createLogger('simulator');
   }
 
@@ -188,9 +208,7 @@ export class ContractFunctionSimulator {
   public async run(
     request: TxExecutionRequest,
     {
-      contractAddress,
-      selector,
-      msgSender = AztecAddress.fromField(Fr.MAX_FIELD_VALUE),
+      msgSender = AztecAddress.NULL_MSG_SENDER,
       anchorBlockHeader,
       senderForTags,
       scopes,
@@ -199,18 +217,30 @@ export class ContractFunctionSimulator {
   ): Promise<PrivateExecutionResult> {
     const simulatorSetupTimer = new Timer();
 
-    const entryPointArtifact = await this.contractStore.getFunctionArtifactWithDebugMetadata(contractAddress, selector);
+    const contractAddress = request.origin;
 
-    if (entryPointArtifact.functionType !== FunctionType.PRIVATE) {
-      throw new Error(`Cannot run ${entryPointArtifact.functionType} function as private`);
-    }
+    const anchoredContractData = new AnchoredContractData(
+      this.contractStore,
+      this.contractClassService,
+      anchorBlockHeader,
+      this.overrides,
+    );
 
-    if (request.origin !== contractAddress) {
-      this.log.warn(
-        `Request origin does not match contract address in simulation. Request origin: ${request.origin}, contract address: ${contractAddress}`,
+    const entryPointArtifact = await anchoredContractData.getFunctionArtifactWithDebugMetadata(
+      contractAddress,
+      request.functionSelector,
+    );
+    if (!entryPointArtifact) {
+      throw new Error(
+        `Cannot run function ${request.functionSelector} on ${contractAddress}: the contract is not registered. ` +
+          `Register it via wallet.registerContract(...).`,
       );
     }
 
+    if (entryPointArtifact.functionType !== FunctionType.PRIVATE) {
+      throw new Error(`Cannot run ${entryPointArtifact.functionType} function as private`);
+    }
+
     // reserve the first side effect for the tx hash (inserted by the private kernel)
     const startSideEffectCounter = 2;
 
@@ -225,9 +255,15 @@ export class ContractFunctionSimulator {
     const noteCache = new ExecutionNoteCache(protocolNullifier);
     const taggingIndexCache = new ExecutionTaggingIndexCache();
 
+    // One shared transient store for the whole execution tree rooted at this transaction. Threaded into every child
+    // private oracle and inherited by nested utility frames, so that frames of the same contract see each other's
+    // transient arrays, then discarded when run() returns.
+    const transientArrayService = new TransientArrayService();
+
     const privateExecutionOracle = new PrivateExecutionOracle({
       argsHash: request.firstCallArgsHash,
       txContext: request.txContext,
+      txRequestSalt: request.salt,
       callContext,
       anchorBlockHeader,
       utilityExecutor: async (call, execScopes) => {
@@ -238,17 +274,18 @@ export class ContractFunctionSimulator {
       executionCache: HashedValuesCache.create(request.argsOfCalls),
       noteCache,
       taggingIndexCache,
-      contractStore: this.contractStore,
+      anchoredContractData,
       noteStore: this.noteStore,
       keyStore: this.keyStore,
       addressStore: this.addressStore,
       aztecNode: this.aztecNode,
       senderTaggingStore: this.senderTaggingStore,
       recipientTaggingStore: this.recipientTaggingStore,
-      senderAddressBookStore: this.senderAddressBookStore,
+      taggingSecretSourcesStore: this.taggingSecretSourcesStore,
       capsuleService: new CapsuleService(this.capsuleStore, scopes),
+      factService: new FactService(this.factStore, scopes),
       privateEventStore: this.privateEventStore,
-      messageContextService: this.messageContextService,
+      txResolver: this.txResolver,
       contractSyncService: this.contractSyncService,
       jobId,
       totalPublicCalldataCount: 0,
@@ -256,6 +293,9 @@ export class ContractFunctionSimulator {
       scopes,
       senderForTags,
       simulator: this.simulator,
+      l2TipsStore: this.l2TipsStore,
+      hooks: this.hooks,
+      transientArrayService,
     });
 
     const setupTime = simulatorSetupTimer.ms();
@@ -274,8 +314,7 @@ export class ContractFunctionSimulator {
       );
       const simulatorTeardownTimer = new Timer();
 
-      noteCache.finish();
-      const firstNullifierHint = noteCache.getNonceGenerator();
+      const firstNullifier = noteCache.getNonceGenerator();
 
       const publicCallRequests = collectNested([executionResult], r =>
         r.publicInputs.publicCallRequests
@@ -298,55 +337,79 @@ export class ContractFunctionSimulator {
       }
 
       // Not to be confused with a PrivateCallExecutionResult. This is a superset
-      // of the PrivateCallExecutionResult, containing also firstNullifierHint
+      // of the PrivateCallExecutionResult, containing also firstNullifier
       // and publicFunctionsCalldata.
-      return new PrivateExecutionResult(executionResult, firstNullifierHint, publicFunctionsCalldata);
+      return new PrivateExecutionResult(executionResult, firstNullifier, publicFunctionsCalldata);
     } catch (err) {
       throw createSimulationError(err instanceof Error ? err : new Error('Unknown error during private execution'));
     }
   }
 
-  // docs:start:execute_utility_function
   /**
    * Runs a utility function.
    * @param call - The function call to execute.
-   * @param authwits - Authentication witnesses required for the function call.
-   * @param anchorBlockHeader - The block header to use as base state for this run.
-   * @param scopes - Optional array of account addresses whose notes can be accessed in this call. Defaults to all
-   * accounts if not specified.
    * @returns A return value of the utility function in a form as returned by the simulator (Noir fields)
    */
   public async runUtility(
     call: FunctionCall,
     authwits: AuthWitness[],
     anchorBlockHeader: BlockHeader,
-    scopes: AccessScopes,
+    scopes: AztecAddress[],
     jobId: string,
   ): Promise<{ result: Fr[]; offchainEffects: OffchainEffect[] }> {
-    const entryPointArtifact = await this.contractStore.getFunctionArtifactWithDebugMetadata(call.to, call.selector);
+    const anchoredContractData = new AnchoredContractData(
+      this.contractStore,
+      this.contractClassService,
+      anchorBlockHeader,
+      this.overrides,
+    );
+
+    const entryPointArtifact = await anchoredContractData.getFunctionArtifactWithDebugMetadata(call.to, call.selector);
+    if (!entryPointArtifact) {
+      throw new Error(
+        `Cannot run function ${call.selector} on ${call.to}: the contract is not registered. ` +
+          `Register it via wallet.registerContract(...).`,
+      );
+    }
 
     if (entryPointArtifact.functionType !== FunctionType.UTILITY) {
       throw new Error(`Cannot run ${entryPointArtifact.functionType} function as utility`);
     }
 
+    const utilityExecutor = async (syncCall: FunctionCall, execScopes: AztecAddress[]) => {
+      await this.runUtility(syncCall, [], anchorBlockHeader, execScopes, jobId);
+    };
+
     const oracle = new UtilityExecutionOracle({
-      contractAddress: call.to,
+      callContext: CallContext.from({
+        msgSender: AztecAddress.NULL_MSG_SENDER,
+        contractAddress: call.to,
+        functionSelector: call.selector,
+        isStaticCall: true,
+      }),
       authWitnesses: authwits,
       capsules: [],
       anchorBlockHeader,
-      contractStore: this.contractStore,
+      anchoredContractData,
       noteStore: this.noteStore,
       keyStore: this.keyStore,
       addressStore: this.addressStore,
       aztecNode: this.aztecNode,
       recipientTaggingStore: this.recipientTaggingStore,
-      senderAddressBookStore: this.senderAddressBookStore,
+      taggingSecretSourcesStore: this.taggingSecretSourcesStore,
       capsuleService: new CapsuleService(this.capsuleStore, scopes),
+      factService: new FactService(this.factStore, scopes),
       privateEventStore: this.privateEventStore,
-      messageContextService: this.messageContextService,
+      txResolver: this.txResolver,
       contractSyncService: this.contractSyncService,
+      l2TipsStore: this.l2TipsStore,
       jobId,
       scopes,
+      simulator: this.simulator,
+      hooks: this.hooks,
+      utilityExecutor,
+      // Execution-tree root (top-level utility run or contract sync): own store; nested frames inherit it.
+      transientArrayService: new TransientArrayService(),
     });
 
     try {
@@ -357,7 +420,7 @@ export class ContractFunctionSimulator {
 
       const initialWitness = toACVMWitness(0, call.args);
       const acirExecutionResult = await this.simulator
-        .executeUserCircuit(initialWitness, entryPointArtifact, new Oracle(oracle).toACIRCallback())
+        .executeUserCircuit(initialWitness, entryPointArtifact, buildACIRCallback(oracle))
         .catch((err: Error) => {
           err.message = resolveAssertionMessageFromError(err, entryPointArtifact);
           throw new ExecutionError(
@@ -380,7 +443,6 @@ export class ContractFunctionSimulator {
       throw createSimulationError(err instanceof Error ? err : new Error('Unknown error during private execution'));
     }
   }
-  // docs:end:execute_utility_function
 
   /**
    * Returns the execution statistics collected during the simulator run.
@@ -593,12 +655,12 @@ export async function generateSimulatedProvingResult(
     siloedNullifiers,
     minRevertibleSideEffectCounter,
   );
+  // The protocol nullifier is the nonce generator and the tx's first nullifier. It is injected by the
+  // init kernel (at counter 1, index 0) rather than emitted by any private call, so it is absent from
+  // the executed nullifiers above. Mirror the kernel here by prepending it as the first non-revertible
+  // nullifier.
   const nonceGenerator = privateExecutionResult.firstNullifier;
-  if (nonRevertibleNullifiers.length === 0) {
-    nonRevertibleNullifiers.push(nonceGenerator);
-  } else if (!nonRevertibleNullifiers[0].equals(nonceGenerator)) {
-    throw new Error('The first non revertible nullifier should be equal to the nonce generator. This is a bug!');
-  }
+  nonRevertibleNullifiers.unshift(nonceGenerator);
 
   if (isPrivateOnlyTx) {
     // We must make the note hashes unique by using the
@@ -749,7 +811,7 @@ function squashTransientSideEffects(
  * at the tx's anchor block, mimicking the behavior of the kernels
  */
 async function verifyReadRequests(
-  node: Pick<AztecNode, 'getNoteHashMembershipWitness' | 'getNullifierMembershipWitness'>,
+  node: Pick<AztecNode, 'findLeavesIndexes'>,
   anchorBlockHash: BlockParameter,
   noteHashReadRequests: ScopedReadRequest[],
   nullifierReadRequests: ScopedReadRequest[],
@@ -782,13 +844,25 @@ async function verifyReadRequests(
     }
   }
 
-  const [noteHashWitnesses, nullifierWitnesses] = await Promise.all([
-    Promise.all(settledNoteHashReads.map(({ value }) => node.getNoteHashMembershipWitness(anchorBlockHash, value))),
-    Promise.all(settledNullifierReads.map(({ value }) => node.getNullifierMembershipWitness(anchorBlockHash, value))),
+  const [noteHashResults, nullifierResults] = await Promise.all([
+    settledNoteHashReads.length > 0
+      ? node.findLeavesIndexes(
+          anchorBlockHash,
+          MerkleTreeId.NOTE_HASH_TREE,
+          settledNoteHashReads.map(({ value }) => value),
+        )
+      : [],
+    settledNullifierReads.length > 0
+      ? node.findLeavesIndexes(
+          anchorBlockHash,
+          MerkleTreeId.NULLIFIER_TREE,
+          settledNullifierReads.map(({ value }) => value),
+        )
+      : [],
   ]);
 
   for (let i = 0; i < settledNoteHashReads.length; i++) {
-    if (!noteHashWitnesses[i]) {
+    if (!noteHashResults[i]) {
       throw new Error(
         `Note hash read request at index ${settledNoteHashReads[i].index} is reading an unknown note hash: ${settledNoteHashReads[i].value}`,
       );
@@ -796,7 +870,7 @@ async function verifyReadRequests(
   }
 
   for (let i = 0; i < settledNullifierReads.length; i++) {
-    if (!nullifierWitnesses[i]) {
+    if (!nullifierResults[i]) {
       throw new Error(
         `Nullifier read request at index ${settledNullifierReads[i].index} is reading an unknown nullifier: ${settledNullifierReads[i].value}`,
       );
@@ -849,6 +923,11 @@ function meterGasUsed(data: PrivateToRollupAccumulatedData | PrivateToPublicAccu
   );
   meteredL2Gas += numContractClassLogs * L2_GAS_PER_CONTRACT_CLASS_LOG;
 
+  if (isPrivateOnlyTx) {
+    // The public data write that the private tx base rollup always performs to update the fee payer's balance.
+    meteredDAFields += PUBLIC_DATA_WRITE_LENGTH;
+  }
+
   const meteredDAGas = meteredDAFields * DA_GAS_PER_FIELD;
 
   if ((data as PrivateToPublicAccumulatedData).publicCallRequests) {

package/src/contract_function_simulator/ephemeral_array_service.ts

@@ -0,0 +1,110 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+
+/** In-memory store for ephemeral arrays scoped to a single contract call frame. */
+export class EphemeralArrayService {
+  /**
+   * Maps a slot to the elements of the array stored at that slot. Each element is a serialized representation of
+   * the original type.
+   */
+  #arrays: Map<string, Fr[][]> = new Map();
+
+  /** Returns all elements in the array, or an empty array if uninitialized. */
+  readArrayAt(slot: Fr): Fr[][] {
+    return this.#arrays.get(slot.toString()) ?? [];
+  }
+
+  #setArray(slot: Fr, array: Fr[][]): void {
+    this.#arrays.set(slot.toString(), array);
+  }
+
+  /** Returns the number of elements in the array at the given slot. */
+  len(slot: Fr): number {
+    return this.readArrayAt(slot).length;
+  }
+
+  /** Appends an element to the array and returns the new length. */
+  push(slot: Fr, elements: Fr[]): number {
+    const array = this.readArrayAt(slot);
+    array.push(elements);
+    this.#setArray(slot, array);
+    return array.length;
+  }
+
+  /** Removes and returns the last element. Throws if empty. */
+  pop(slot: Fr): Fr[] {
+    const array = this.readArrayAt(slot);
+    if (array.length === 0) {
+      throw new Error(`Ephemeral array at slot ${slot} is empty`);
+    }
+    const element = array.pop()!;
+    this.#setArray(slot, array);
+    return element;
+  }
+
+  /** Returns the element at the given index. Throws if out of bounds. */
+  get(slot: Fr, index: number): Fr[] {
+    const array = this.readArrayAt(slot);
+    if (index < 0 || index >= array.length) {
+      throw new Error(
+        `Ephemeral array index ${index} out of bounds for array of length ${array.length} at slot ${slot}`,
+      );
+    }
+    return array[index];
+  }
+
+  /** Overwrites the element at the given index. Throws if out of bounds. */
+  set(slot: Fr, index: number, value: Fr[]): void {
+    const array = this.readArrayAt(slot);
+    if (index < 0 || index >= array.length) {
+      throw new Error(
+        `Ephemeral array index ${index} out of bounds for array of length ${array.length} at slot ${slot}`,
+      );
+    }
+    array[index] = value;
+  }
+
+  /** Removes the element at the given index, shifting subsequent elements backward. Throws if out of bounds. */
+  remove(slot: Fr, index: number): void {
+    const array = this.readArrayAt(slot);
+    if (index < 0 || index >= array.length) {
+      throw new Error(
+        `Ephemeral array index ${index} out of bounds for array of length ${array.length} at slot ${slot}`,
+      );
+    }
+    array.splice(index, 1);
+  }
+
+  /** Removes all elements from the array. */
+  clear(slot: Fr): void {
+    this.#arrays.delete(slot.toString());
+  }
+
+  /** Allocates a fresh, unused slot for a new ephemeral array. */
+  allocateSlot(): Fr {
+    let slot: Fr;
+    do {
+      slot = Fr.random();
+    } while (this.#arrays.has(slot.toString()));
+    return slot;
+  }
+
+  /** Creates a new ephemeral array pre-populated with the given elements and returns its slot. */
+  newArray(elements: Fr[][]): Fr {
+    const slot = this.allocateSlot();
+    this.#setArray(slot, elements);
+    return slot;
+  }
+
+  /** Copies `count` elements from the source array to the destination array (overwrites destination). */
+  copy(srcSlot: Fr, dstSlot: Fr, count: number): void {
+    const srcArray = this.readArrayAt(srcSlot);
+    if (count > srcArray.length) {
+      throw new Error(
+        `Cannot copy ${count} elements from ephemeral array of length ${srcArray.length} at slot ${srcSlot}`,
+      );
+    }
+    // Deep copy the elements to avoid aliasing
+    const copied = srcArray.slice(0, count).map(el => [...el]);
+    this.#setArray(dstSlot, copied);
+  }
+}