@aztec/pxe 0.87.4 → 0.87.6

package/src/contract_function_simulator/execution_data_provider.ts

@@ -0,0 +1,391 @@
+import type { L1_TO_L2_MSG_TREE_HEIGHT } from '@aztec/constants';
+import type { Fr, Point } from '@aztec/foundation/fields';
+import type {
+  EventSelector,
+  FunctionArtifact,
+  FunctionArtifactWithContractName,
+  FunctionSelector,
+} from '@aztec/stdlib/abi';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { L2Block } from '@aztec/stdlib/block';
+import type { CompleteAddress, ContractInstance } from '@aztec/stdlib/contract';
+import type { KeyValidationRequest } from '@aztec/stdlib/kernel';
+import { IndexedTaggingSecret, LogWithTxData } from '@aztec/stdlib/logs';
+import type { NoteStatus } from '@aztec/stdlib/note';
+import { type MerkleTreeId, type NullifierMembershipWitness, PublicDataWitness } from '@aztec/stdlib/trees';
+import type { BlockHeader, NodeStats, TxHash } from '@aztec/stdlib/tx';
+
+import type { MessageLoadOracleInputs } from './oracle/message_load_oracle_inputs.js';
+import type { NoteData } from './oracle/typed_oracle.js';
+
+/**
+ * Error thrown when a contract is not found in the database.
+ */
+export class ContractNotFoundError extends Error {
+  constructor(contractAddress: string) {
+    super(`DB has no contract with address ${contractAddress}`);
+  }
+}
+
+/**
+ * Error thrown when a contract class is not found in the database.
+ */
+export class ContractClassNotFoundError extends Error {
+  constructor(contractClassId: string) {
+    super(`DB has no contract class with id ${contractClassId}`);
+  }
+}
+
+/*
+ * Collected stats during the execution of a transaction.
+ */
+export type ExecutionStats = {
+  /**
+   * Contains an entry for each RPC call performed during the execution
+   */
+  nodeRPCCalls: NodeStats;
+};
+
+/**
+ * The interface for the data layer required to perform private and utility execution.
+ */
+export interface ExecutionDataProvider {
+  /**
+   * Returns a contract instance associated with an address, if available.
+   * @param address - Address.
+   * @returns A contract instance.
+   */
+  getContractInstance(address: AztecAddress): Promise<ContractInstance>;
+
+  /**
+   * Retrieve the complete address associated to a given address.
+   * @param account - The account address.
+   * @returns A complete address associated with the input address.
+   * @throws An error if the account is not registered in the database.
+   */
+  getCompleteAddress(account: AztecAddress): Promise<CompleteAddress>;
+
+  /**
+   * Retrieve keys associated with a specific master public key and app address.
+   * @param pkMHash - The master public key hash.
+   * @returns A Promise that resolves to nullifier keys.
+   * @throws If the keys are not registered in the key store.
+   */
+  getKeyValidationRequest(pkMHash: Fr, contractAddress: AztecAddress): Promise<KeyValidationRequest>;
+
+  /**
+   * Retrieves a set of notes stored in the database for a given contract address and storage slot.
+   * The query result is paginated using 'limit' and 'offset' values.
+   * Returns an object containing an array of note data.
+   *
+   * @param contractAddress - The contract address of the notes.
+   * @param storageSlot - The storage slot of the notes.
+   * @param status - The status of notes to fetch.
+   * @param scopes - The accounts whose notes we can access in this call. Currently optional and will default to all.
+   * @returns A Promise that resolves to an array of note data.
+   */
+  getNotes(
+    contractAddress: AztecAddress,
+    storageSlot: Fr,
+    status: NoteStatus,
+    scopes?: AztecAddress[],
+  ): Promise<NoteData[]>;
+
+  /**
+   * Retrieve the artifact information of a specific function within a contract.
+   * The function is identified by its selector, which is a unique identifier generated from the function signature.
+   *
+   * @param contractAddress - The contract address.
+   * @param selector - The corresponding function selector.
+   * @returns A Promise that resolves to a FunctionArtifact object.
+   */
+  getFunctionArtifact(
+    contractAddress: AztecAddress,
+    selector: FunctionSelector,
+  ): Promise<FunctionArtifactWithContractName>;
+
+  /**
+   * Generates a stable function name for debug purposes.
+   * @param contractAddress - The contract address.
+   * @param selector - The corresponding function selector.
+   */
+  getDebugFunctionName(contractAddress: AztecAddress, selector: FunctionSelector): Promise<string>;
+
+  /**
+   * Retrieves the artifact of a specified function within a given contract.
+   * The function is identified by its name, which is unique within a contract.
+   *
+   * @param contractAddress - The AztecAddress representing the contract containing the function.
+   * @param functionName - The name of the function.
+   * @returns The corresponding function's artifact as an object.
+   */
+  getFunctionArtifactByName(contractAddress: AztecAddress, functionName: string): Promise<FunctionArtifact | undefined>;
+
+  /**
+   * Gets the index of a nullifier in the nullifier tree.
+   * @param nullifier - The nullifier.
+   * @returns - The index of the nullifier. Undefined if it does not exist in the tree.
+   */
+  getNullifierIndex(nullifier: Fr): Promise<bigint | undefined>;
+
+  /**
+   * Gets the index of a nullifier in the nullifier tree.
+   * @param nullifier - The nullifier.
+   * @returns - The index of the nullifier. Undefined if it does not exist in the tree.
+   */
+  getNullifierIndex(nullifier: Fr): Promise<bigint | undefined>;
+
+  /**
+   * Returns a nullifier membership witness for the given nullifier or undefined if not found.
+   * REFACTOR: Same as getL1ToL2MembershipWitness, can be combined with aztec-node method that does almost the same thing.
+   * @param nullifier - Nullifier we're looking for.
+   */
+  getNullifierMembershipWitnessAtLatestBlock(nullifier: Fr): Promise<NullifierMembershipWitness | undefined>;
+
+  /**
+   * Fetches a message from the db, given its key.
+   * @param contractAddress - Address of a contract by which the message was emitted.
+   * @param messageHash - Hash of the message.
+   * @param secret - Secret used to compute a nullifier.
+   * @dev Contract address and secret are only used to compute the nullifier to get non-nullified messages
+   * @returns The l1 to l2 membership witness (index of message in the tree and sibling path).
+   */
+  getL1ToL2MembershipWitness(
+    contractAddress: AztecAddress,
+    messageHash: Fr,
+    secret: Fr,
+  ): Promise<MessageLoadOracleInputs<typeof L1_TO_L2_MSG_TREE_HEIGHT>>;
+
+  /**
+   * Retrieve the databases view of the Block Header object.
+   * This structure is fed into the circuits simulator and is used to prove against certain historical roots.
+   *
+   * @returns A Promise that resolves to a Header object.
+   */
+  getBlockHeader(): Promise<BlockHeader>;
+
+  /**
+   * Fetches the index and sibling path of a leaf at a given block from a given tree.
+   * @param blockNumber - The block number at which to get the membership witness.
+   * @param treeId - Id of the tree to get the sibling path from.
+   * @param leafValue - The leaf value
+   * @returns The index and sibling path concatenated [index, sibling_path]
+   */
+  getMembershipWitness(blockNumber: number, treeId: MerkleTreeId, leafValue: Fr): Promise<Fr[]>;
+
+  /**
+   * Returns a nullifier membership witness for a given nullifier at a given block.
+   * @param blockNumber - The block number at which to get the index.
+   * @param nullifier - Nullifier we try to find witness for.
+   * @returns The nullifier membership witness (if found).
+   */
+  getNullifierMembershipWitness(blockNumber: number, nullifier: Fr): Promise<NullifierMembershipWitness | undefined>;
+
+  /**
+   * Returns a low nullifier membership witness for a given nullifier at a given block.
+   * @param blockNumber - The block number at which to get the index.
+   * @param nullifier - Nullifier we try to find the low nullifier witness for.
+   * @returns The low nullifier membership witness (if found).
+   * @remarks Low nullifier witness can be used to perform a nullifier non-inclusion proof by leveraging the "linked
+   * list structure" of leaves and proving that a lower nullifier is pointing to a bigger next value than the nullifier
+   * we are trying to prove non-inclusion for.
+   */
+  getLowNullifierMembershipWitness(blockNumber: number, nullifier: Fr): Promise<NullifierMembershipWitness | undefined>;
+
+  /**
+   * Returns a witness for a given slot of the public data tree at a given block.
+   * @param blockNumber - The block number at which to get the witness.
+   * @param leafSlot - The slot of the public data in the public data tree.
+   */
+  getPublicDataWitness(blockNumber: number, leafSlot: Fr): Promise<PublicDataWitness | undefined>;
+
+  /**
+   * Gets the storage value at the given contract storage slot.
+   *
+   * @remarks The storage slot here refers to the slot as it is defined in Noir not the index in the merkle tree.
+   * Aztec's version of `eth_getStorageAt`.
+   *
+   * @param blockNumber - The block number at which to get the data.
+   * @param contract - Address of the contract to query.
+   * @param slot - Slot to query.
+   * @returns Storage value at the given contract slot.
+   * @throws If the contract is not deployed.
+   */
+  getPublicStorageAt(blockNumber: number, contract: AztecAddress, slot: Fr): Promise<Fr>;
+
+  /**
+   * Fetch a block corresponding to the given block number.
+   * @param blockNumber - The block number of a block to fetch.
+   * @returns - The block corresponding to the given block number. Undefined if it does not exist.
+   */
+  getBlock(blockNumber: number): Promise<L2Block | undefined>;
+
+  /**
+   * Fetches the current block number.
+   * @returns The block number.
+   */
+  getBlockNumber(): Promise<number>;
+
+  /**
+   * Fetches the current chain id.
+   * @returns The chain id.
+   */
+  getChainId(): Promise<number>;
+
+  /**
+   * Fetches the current chain id.
+   * @returns The chain id.
+   */
+  getVersion(): Promise<number>;
+
+  /**
+   * Returns the tagging secret for a given sender and recipient pair. For this to work, the ivsk_m of the sender must be known.
+   * Includes the next index to be used used for tagging with this secret.
+   * @param contractAddress - The contract address to silo the secret for
+   * @param sender - The address sending the note
+   * @param recipient - The address receiving the note
+   * @returns A tagging secret that can be used to tag notes.
+   */
+  getIndexedTaggingSecretAsSender(
+    contractAddress: AztecAddress,
+    sender: AztecAddress,
+    recipient: AztecAddress,
+  ): Promise<IndexedTaggingSecret>;
+
+  /**
+   * Increments the tagging secret for a given sender and recipient pair. For this to work, the ivsk_m of the sender must be known.
+   * @param contractAddress - The contract address to silo the secret for
+   * @param sender - The address sending the note
+   * @param recipient - The address receiving the note
+   */
+  incrementAppTaggingSecretIndexAsSender(
+    contractAddress: AztecAddress,
+    sender: AztecAddress,
+    recipient: AztecAddress,
+  ): Promise<void>;
+
+  /**
+   * Synchronizes the logs tagged with scoped addresses and all the senders in the address book. Stores the found logs
+   * in CapsuleArray ready for a later retrieval in Aztec.nr.
+   * @param contractAddress - The address of the contract that the logs are tagged for.
+   * @param pendingTaggedLogArrayBaseSlot - The base slot of the pending tagged log capsule array in which found logs will be stored.
+   * @param scopes - The scoped addresses to sync logs for. If not provided, all accounts in the address book will be
+   * synced.
+   */
+  syncTaggedLogs(
+    contractAddress: AztecAddress,
+    pendingTaggedLogArrayBaseSlot: Fr,
+    scopes?: AztecAddress[],
+  ): Promise<void>;
+
+  /**
+   * Delivers the preimage and metadata of a committed note so that it can be later requested via the `getNotes`
+   * oracle.
+   *
+   * @param contractAddress - The address of the contract that created the note (i.e. the siloing contract)
+   * @param storageSlot - The storage slot of the note - used for indexing in `getNotes`
+   * @param nonce - The nonce of the note used by the kernel to compute the unique note hash
+   * @param content - The note's content: this is the primary item to return in `getNotes`
+   * @param noteHash - The non-unique non-siloed note hash
+   * @param nullifier - The inner (non-siloed) note nullifier
+   * @param txHash - The transaction in which the note was added to the note hash tree
+   * @param recipient - The account that discovered the note
+   */
+  deliverNote(
+    contractAddress: AztecAddress,
+    storageSlot: Fr,
+    nonce: Fr,
+    content: Fr[],
+    noteHash: Fr,
+    nullifier: Fr,
+    txHash: TxHash,
+    recipient: AztecAddress,
+  ): Promise<void>;
+
+  /**
+   * Searches for a log with the corresponding `tag` and returns it along with contextual transaction information.
+   * Returns null if no such log exists, and throws if more than one exists.
+   *
+   * @param tag - The log tag to search for.
+   */
+  getLogByTag(tag: Fr): Promise<LogWithTxData | null>;
+
+  /**
+   * Removes all of a contract's notes that have been nullified from the note database.
+   */
+  removeNullifiedNotes(contractAddress: AztecAddress): Promise<void>;
+
+  /**
+   * Stores arbitrary information in a per-contract non-volatile database, which can later be retrieved with `loadCapsule`.
+   * * If data was already stored at this slot, it is overwritten.
+   * @param contractAddress - The contract address to scope the data under.
+   * @param slot - The slot in the database in which to store the value. Slots need not be contiguous.
+   * @param capsule - An array of field elements representing the capsule.
+   * @remarks A capsule is a "blob" of data that is passed to the contract through an oracle. It works similarly
+   * to public contract storage in that it's indexed by the contract address and storage slot but instead of the global
+   * network state it's backed by local PXE db.
+   */
+  storeCapsule(contractAddress: AztecAddress, slot: Fr, capsule: Fr[]): Promise<void>;
+
+  /**
+   * Returns data previously stored via `storeCapsule` in the per-contract non-volatile database.
+   * @param contractAddress - The contract address under which the data is scoped.
+   * @param slot - The slot in the database to read.
+   * @returns The stored data or `null` if no data is stored under the slot.
+   */
+  loadCapsule(contractAddress: AztecAddress, slot: Fr): Promise<Fr[] | null>;
+
+  /**
+   * Deletes data in the per-contract non-volatile database. Does nothing if no data was present.
+   * @param contractAddress - The contract address under which the data is scoped.
+   * @param slot - The slot in the database to delete.
+   */
+  deleteCapsule(contractAddress: AztecAddress, slot: Fr): Promise<void>;
+
+  /**
+   * Copies a number of contiguous entries in the per-contract non-volatile database. This allows for efficient data
+   * structures by avoiding repeated calls to `loadCapsule` and `storeCapsule`.
+   * Supports overlapping source and destination regions (which will result in the overlapped source values being
+   * overwritten). All copied slots must exist in the database (i.e. have been stored and not deleted)
+   *
+   * @param contractAddress - The contract address under which the data is scoped.
+   * @param srcSlot - The first slot to copy from.
+   * @param dstSlot - The first slot to copy to.
+   * @param numEntries - The number of entries to copy.
+   */
+  copyCapsule(contractAddress: AztecAddress, srcSlot: Fr, dstSlot: Fr, numEntries: number): Promise<void>;
+
+  /**
+   * Retrieves the shared secret for a given address and ephemeral public key.
+   * @param address - The address to get the secret for.
+   * @param ephPk - The ephemeral public key to get the secret for.
+   * @returns The secret for the given address.
+   */
+  getSharedSecret(address: AztecAddress, ephPk: Point): Promise<Point>;
+
+  /**
+   * Stores an event log in the database.
+   * @param contractAddress - The address of the contract that emitted the log.
+   * @param recipient - The address of the recipient.
+   * @param eventSelector - The event selector of the event.
+   * @param msgContent - The content of the private event message.
+   * @param txHash - The hash of the transaction that emitted the log.
+   * @param logIndexInTx - The index of the log within the transaction.
+   * @param txIndexInBlock - The index of the transaction in which the log was emitted in the block.
+   */
+  storePrivateEventLog(
+    contractAddress: AztecAddress,
+    recipient: AztecAddress,
+    eventSelector: EventSelector,
+    msgContent: Fr[],
+    txHash: TxHash,
+    logIndexInTx: number,
+    txIndexInBlock: number,
+  ): Promise<void>;
+
+  /**
+   * Returns the execution statistics collected during the simulator run.
+   * @returns The execution statistics.
+   */
+  getStats(): ExecutionStats;
+}

package/src/contract_function_simulator/execution_note_cache.ts

@@ -0,0 +1,217 @@
+import { Fr } from '@aztec/foundation/fields';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { computeNoteHashNonce, computeUniqueNoteHash, siloNoteHash, siloNullifier } from '@aztec/stdlib/hash';
+
+import type { NoteData } from './oracle/typed_oracle.js';
+
+interface PendingNote {
+  note: NoteData;
+  counter: number;
+  noteHashForConsumption: Fr;
+}
+
+/**
+ * Data that's accessible by all the function calls in an execution.
+ */
+export class ExecutionNoteCache {
+  /**
+   * New notes created in this transaction.
+   * They are pushed to this array in the same order as they are emitted.
+   */
+  private notes: PendingNote[] = [];
+  /**
+   * This mapping maps from a contract address to the notes in the contract.
+   */
+  private noteMap: Map<bigint, PendingNote[]> = new Map();
+
+  /**
+   * This maps from a contract address to the nullifiers emitted from the contract.
+   * The note which is nullified might be new or not (i.e., was generated in a previous transaction).
+   * Note that their value (bigint representation) is used because Frs cannot be looked up in Sets.
+   */
+  private nullifierMap: Map<bigint, Set<bigint>> = new Map();
+
+  /**
+   * All nullifiers emitted in this transaction.
+   */
+  private allNullifiers: Set<bigint> = new Set();
+
+  private minRevertibleSideEffectCounter = 0;
+
+  private inRevertiblePhase = false;
+
+  /**
+   * We don't need to use the tx request hash for nonces if another non revertible nullifier is emitted.
+   * In that case we disable injecting the tx request hash as a nullifier.
+   */
+  private usedTxRequestHashForNonces = true;
+
+  constructor(private readonly txRequestHash: Fr) {}
+
+  /**
+   * Enters the revertible phase of the transaction.
+   * @param minRevertibleSideEffectCounter - The counter at which the transaction enters the revertible phase.
+   */
+  public async setMinRevertibleSideEffectCounter(minRevertibleSideEffectCounter: number) {
+    if (this.inRevertiblePhase) {
+      throw new Error(
+        `Cannot enter the revertible phase twice. Current counter: ${minRevertibleSideEffectCounter}. Previous enter counter: ${this.minRevertibleSideEffectCounter}`,
+      );
+    }
+    this.inRevertiblePhase = true;
+    this.minRevertibleSideEffectCounter = minRevertibleSideEffectCounter;
+
+    let nonceGenerator = this.txRequestHash;
+    const nullifiers = this.getAllNullifiers();
+    if (nullifiers.length > 0) {
+      nonceGenerator = new Fr(nullifiers[0]);
+      this.usedTxRequestHashForNonces = false;
+    }
+
+    // The existing pending notes are all non-revertible.
+    // They cannot be squashed by nullifiers emitted after minRevertibleSideEffectCounter is set.
+    // Their indexes in the tx are known at this point and won't change. So we can assign a nonce to each one of them.
+    // The nonces will be used to create the "complete" nullifier.
+    const updatedNotes = await Promise.all(
+      this.notes.map(async ({ note, counter }, i) => {
+        const nonce = await computeNoteHashNonce(nonceGenerator, i);
+        const uniqueNoteHash = await computeUniqueNoteHash(
+          nonce,
+          await siloNoteHash(note.contractAddress, note.noteHash),
+        );
+        return {
+          counter,
+          note: { ...note, nonce },
+          noteHashForConsumption: uniqueNoteHash,
+        };
+      }),
+    );
+    // Rebuild the data.
+    this.notes = [];
+    this.noteMap = new Map();
+    updatedNotes.forEach(n => this.#addNote(n));
+  }
+
+  public finish() {
+    // If we never entered the revertible phase, we need to use the tx request hash as a nonce for the notes if no nullifiers have been emitted.
+    if (!this.inRevertiblePhase) {
+      this.usedTxRequestHashForNonces = this.getAllNullifiers().length === 0;
+    }
+    // If we entered the revertible phase, the nonce generator was decided based on wether or not a nullifier was emitted before entering.
+    return {
+      usedTxRequestHashForNonces: this.usedTxRequestHashForNonces,
+    };
+  }
+
+  /**
+   * Add a new note to cache.
+   * @param note - New note created during execution.
+   */
+  public addNewNote(note: NoteData, counter: number) {
+    const previousNote = this.notes[this.notes.length - 1];
+    if (previousNote && previousNote.counter >= counter) {
+      throw new Error(
+        `Note hash counters must be strictly increasing. Current counter: ${counter}. Previous counter: ${previousNote.counter}.`,
+      );
+    }
+
+    this.#addNote({ note, counter, noteHashForConsumption: note.noteHash });
+  }
+
+  /**
+   * Add a nullifier to cache. It could be for a db note or a new note created during execution.
+   * @param contractAddress - Contract address of the note.
+   * @param innerNullifier - Inner nullifier of the note.
+   * @param noteHash - A hash of the note. If this value equals 0, it means the note being nullified is from a previous
+   * transaction (and thus not a new note).
+   */
+  public async nullifyNote(contractAddress: AztecAddress, innerNullifier: Fr, noteHash: Fr) {
+    const siloedNullifier = await siloNullifier(contractAddress, innerNullifier);
+    let nullifiedNoteHashCounter: number | undefined = undefined;
+    // Find and remove the matching new note and log(s) if the emitted noteHash is not empty.
+    if (!noteHash.isEmpty()) {
+      const notesInContract = this.noteMap.get(contractAddress.toBigInt()) ?? [];
+      const noteIndexToRemove = notesInContract.findIndex(n => n.noteHashForConsumption.equals(noteHash));
+      if (noteIndexToRemove === -1) {
+        throw new Error('Attempt to remove a pending note that does not exist.');
+      }
+
+      const note = notesInContract.splice(noteIndexToRemove, 1)[0];
+      nullifiedNoteHashCounter = note.counter;
+      this.noteMap.set(contractAddress.toBigInt(), notesInContract);
+      this.notes = this.notes.filter(n => n.counter !== note.counter);
+
+      // If the note is non revertible and the nullifier was emitted in the revertible phase, both the note hash and the nullifier will be emitted
+      if (this.inRevertiblePhase && note.counter < this.minRevertibleSideEffectCounter) {
+        this.recordNullifier(contractAddress, siloedNullifier);
+      }
+    } else {
+      // If the note being nullified comes from a previous tx the nullifier will be emitted.
+      this.recordNullifier(contractAddress, siloedNullifier);
+    }
+    return nullifiedNoteHashCounter;
+  }
+
+  /**
+   * Adds a nullifier to the cache. Note cache needs to track all nullifiers to decide which nullifier to use for note siloing.
+   * @param contractAddress - Contract address that emitted the nullifier.
+   * @param innerNullifier
+   */
+  public async nullifierCreated(contractAddress: AztecAddress, innerNullifier: Fr) {
+    const siloedNullifier = await siloNullifier(contractAddress, innerNullifier);
+    this.recordNullifier(contractAddress, siloedNullifier);
+  }
+
+  /**
+   * Return notes created up to current point in execution.
+   * If a nullifier for a note in this list is emitted, the note will be deleted.
+   * @param contractAddress - Contract address of the notes.
+   * @param storageSlot - Storage slot of the notes.
+   **/
+  public getNotes(contractAddress: AztecAddress, storageSlot: Fr) {
+    const notes = this.noteMap.get(contractAddress.toBigInt()) ?? [];
+    return notes.filter(n => n.note.storageSlot.equals(storageSlot)).map(n => n.note);
+  }
+
+  /**
+   * Check if a note exists in the newNotes array.
+   * @param contractAddress - Contract address of the note.
+   * @param storageSlot - Storage slot of the note.
+   * @param noteHash - A hash of the note.
+   **/
+  public checkNoteExists(contractAddress: AztecAddress, noteHash: Fr) {
+    const notes = this.noteMap.get(contractAddress.toBigInt()) ?? [];
+    return notes.some(n => n.note.noteHash.equals(noteHash));
+  }
+
+  /**
+   * Return all nullifiers emitted from a contract.
+   * @param contractAddress - Address of the contract.
+   */
+  public getNullifiers(contractAddress: AztecAddress): Set<bigint> {
+    return this.nullifierMap.get(contractAddress.toBigInt()) ?? new Set();
+  }
+
+  #addNote(note: PendingNote) {
+    this.notes.push(note);
+
+    const notes = this.noteMap.get(note.note.contractAddress.toBigInt()) ?? [];
+    notes.push(note);
+    this.noteMap.set(note.note.contractAddress.toBigInt(), notes);
+  }
+
+  getAllNotes(): PendingNote[] {
+    return this.notes;
+  }
+
+  getAllNullifiers(): Fr[] {
+    return [...this.allNullifiers].map(n => new Fr(n));
+  }
+
+  recordNullifier(contractAddress: AztecAddress, siloedNullifier: Fr) {
+    const nullifiers = this.getNullifiers(contractAddress);
+    nullifiers.add(siloedNullifier.toBigInt());
+    this.nullifierMap.set(contractAddress.toBigInt(), nullifiers);
+    this.allNullifiers.add(siloedNullifier.toBigInt());
+  }
+}

package/src/contract_function_simulator/hashed_values_cache.ts

@@ -0,0 +1,47 @@
+import { Fr } from '@aztec/foundation/fields';
+import { HashedValues } from '@aztec/stdlib/tx';
+
+/**
+ * A cache for hashed values (arguments, returns) during transaction execution.
+ */
+export class HashedValuesCache {
+  private cache: Map<bigint, Fr[]>;
+
+  constructor(initialArguments: HashedValues[] = []) {
+    this.cache = new Map();
+    for (const initialArg of initialArguments) {
+      this.cache.set(initialArg.hash.toBigInt(), initialArg.values);
+    }
+  }
+
+  /**
+   * Creates a new hashed values cache.
+   * @param initialArguments - The initial arguments to add to the cache.
+   * @returns The new hashed values cache.
+   */
+  public static create(initialArguments: HashedValues[] = []) {
+    return new HashedValuesCache(initialArguments);
+  }
+
+  /**
+   * Gets preimage of a hash.
+   * @param hash - The hash to get the preimage of.
+   * @returns The preimage.
+   */
+  public getPreimage(hash: Fr): Fr[] | undefined {
+    if (hash.isEmpty()) {
+      return [];
+    } else {
+      return this.cache.get(hash.toBigInt());
+    }
+  }
+
+  /**
+   * Stores values in cache and returns its hash.
+   * @param values - The values to store.
+   * @returns The hash of the values.
+   */
+  public store(values: Fr[], hash: Fr) {
+    this.cache.set(hash.toBigInt(), values);
+  }
+}

package/src/contract_function_simulator/index.ts

@@ -0,0 +1,9 @@
+export { ExecutionNoteCache } from './execution_note_cache.js';
+export { HashedValuesCache } from './hashed_values_cache.js';
+export { pickNotes } from './pick_notes.js';
+export type { NoteData, TypedOracle } from './oracle/typed_oracle.js';
+export { MessageLoadOracleInputs } from './oracle/message_load_oracle_inputs.js';
+export { UtilityExecutionOracle } from './oracle/utility_execution_oracle.js';
+export { PrivateExecutionOracle } from './oracle/private_execution_oracle.js';
+export { Oracle } from './oracle/oracle.js';
+export { executePrivateFunction, extractPrivateCircuitPublicInputs } from './oracle/private_execution.js';

package/src/contract_function_simulator/oracle/index.ts

@@ -0,0 +1,16 @@
+import type { Oracle } from './oracle.js';
+
+export * from './oracle.js';
+export * from './typed_oracle.js';
+
+/**
+ * A conditional type that takes a type `T` and returns a union of its method names.
+ */
+type MethodNames<T> = {
+  [K in keyof T]: T[K] extends (...args: any[]) => any ? K : never;
+}[keyof T];
+
+/**
+ * Available oracle function names.
+ */
+export type ORACLE_NAMES = MethodNames<Oracle>;