@aztec/simulator 0.23.0 → 0.26.1

package/src/client/execution_note_cache.ts

@@ -0,0 +1,90 @@
+import { siloNullifier } from '@aztec/circuits.js/hash';
+import { AztecAddress } from '@aztec/foundation/aztec-address';
+import { Fr } from '@aztec/foundation/fields';
+
+import { NoteData } from '../acvm/index.js';
+
+/**
+ * Data that's accessible by all the function calls in an execution.
+ */
+export class ExecutionNoteCache {
+  /**
+   * New notes created in this transaction.
+   * This mapping maps from a contract address to the notes in the contract.
+   */
+  private newNotes: Map<bigint, NoteData[]> = new Map();
+
+  /**
+   * The list of nullifiers created in this transaction.
+   * This mapping 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 nullifiers: Map<bigint, Set<bigint>> = new Map();
+
+  /**
+   * Add a new note to cache.
+   * @param note - New note created during execution.
+   */
+  public addNewNote(note: NoteData) {
+    const notes = this.newNotes.get(note.contractAddress.toBigInt()) ?? [];
+    notes.push(note);
+    this.newNotes.set(note.contractAddress.toBigInt(), notes);
+  }
+
+  /**
+   * 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 storageSlot - Storage slot of the note.
+   * @param innerNullifier - Inner nullifier of the note.
+   * @param innerNoteHash - Inner note 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 nullifyNote(contractAddress: AztecAddress, innerNullifier: Fr, innerNoteHash: Fr) {
+    const siloedNullifier = siloNullifier(contractAddress, innerNullifier);
+    const nullifiers = this.getNullifiers(contractAddress);
+    nullifiers.add(siloedNullifier.value);
+    this.nullifiers.set(contractAddress.toBigInt(), nullifiers);
+
+    // Find and remove the matching new note if the emitted innerNoteHash is not empty.
+    if (!innerNoteHash.equals(Fr.ZERO)) {
+      const notes = this.newNotes.get(contractAddress.toBigInt()) ?? [];
+      const noteIndexToRemove = notes.findIndex(n => n.innerNoteHash.equals(innerNoteHash));
+      if (noteIndexToRemove === -1) {
+        throw new Error('Attempt to remove a pending note that does not exist.');
+      }
+      notes.splice(noteIndexToRemove, 1);
+      this.newNotes.set(contractAddress.toBigInt(), notes);
+    }
+  }
+
+  /**
+   * 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.newNotes.get(contractAddress.toBigInt()) ?? [];
+    return notes.filter(n => n.storageSlot.equals(storageSlot));
+  }
+
+  /**
+   * Check if a note exists in the newNotes array.
+   * @param contractAddress - Contract address of the note.
+   * @param storageSlot - Storage slot of the note.
+   * @param innerNoteHash - Inner note hash of the note.
+   **/
+  public checkNoteExists(contractAddress: AztecAddress, innerNoteHash: Fr) {
+    const notes = this.newNotes.get(contractAddress.toBigInt()) ?? [];
+    return notes.some(n => n.innerNoteHash.equals(innerNoteHash));
+  }
+
+  /**
+   * Return all nullifiers emitted from a contract.
+   * @param contractAddress - Address of the contract.
+   */
+  public getNullifiers(contractAddress: AztecAddress): Set<bigint> {
+    return this.nullifiers.get(contractAddress.toBigInt()) ?? new Set();
+  }
+}

package/src/client/execution_result.ts

@@ -0,0 +1,89 @@
+import { FunctionL2Logs, Note } from '@aztec/circuit-types';
+import { NoteHashReadRequestMembershipWitness, PrivateCallStackItem, PublicCallRequest } from '@aztec/circuits.js';
+import { DecodedReturn } from '@aztec/foundation/abi';
+import { Fr } from '@aztec/foundation/fields';
+
+import { ACVMField } from '../acvm/index.js';
+
+/**
+ * The contents of a new note.
+ */
+export interface NoteAndSlot {
+  /** The note. */
+  note: Note;
+  /** The storage slot of the note. */
+  storageSlot: Fr;
+  /** The note type identifier. */
+  noteTypeId: Fr;
+}
+
+/**
+ * The result of executing a private function.
+ */
+export interface ExecutionResult {
+  // Needed for prover
+  /** The ACIR bytecode. */
+  acir: Buffer;
+  /** The verification key. */
+  vk: Buffer;
+  /** The partial witness. */
+  partialWitness: Map<number, ACVMField>;
+  // Needed for the verifier (kernel)
+  /** The call stack item. */
+  callStackItem: PrivateCallStackItem;
+  /** The partially filled-in read request membership witnesses for commitments being read. */
+  noteHashReadRequestPartialWitnesses: NoteHashReadRequestMembershipWitness[];
+  // Needed when we enable chained txs. The new notes can be cached and used in a later transaction.
+  /** The notes created in the executed function. */
+  newNotes: NoteAndSlot[];
+  /** The decoded return values of the executed function. */
+  returnValues: DecodedReturn;
+  /** The nested executions. */
+  nestedExecutions: this[];
+  /** Enqueued public function execution requests to be picked up by the sequencer. */
+  enqueuedPublicFunctionCalls: PublicCallRequest[];
+  /**
+   * Encrypted logs emitted during execution of this function call.
+   * Note: These are preimages to `encryptedLogsHash`.
+   */
+  encryptedLogs: FunctionL2Logs;
+  /**
+   * Unencrypted logs emitted during execution of this function call.
+   * Note: These are preimages to `unencryptedLogsHash`.
+   */
+  unencryptedLogs: FunctionL2Logs;
+}
+
+/**
+ * Collect all encrypted logs across all nested executions.
+ * @param execResult - The topmost execution result.
+ * @returns All encrypted logs.
+ */
+export function collectEncryptedLogs(execResult: ExecutionResult): FunctionL2Logs[] {
+  // without the .reverse(), the logs will be in a queue like fashion which is wrong as the kernel processes it like a stack.
+  return [execResult.encryptedLogs, ...[...execResult.nestedExecutions].reverse().flatMap(collectEncryptedLogs)];
+}
+
+/**
+ * Collect all unencrypted logs across all nested executions.
+ * @param execResult - The topmost execution result.
+ * @returns All unencrypted logs.
+ */
+export function collectUnencryptedLogs(execResult: ExecutionResult): FunctionL2Logs[] {
+  // without the .reverse(), the logs will be in a queue like fashion which is wrong as the kernel processes it like a stack.
+  return [execResult.unencryptedLogs, ...[...execResult.nestedExecutions].reverse().flatMap(collectUnencryptedLogs)];
+}
+
+/**
+ * Collect all enqueued public function calls across all nested executions.
+ * @param execResult - The topmost execution result.
+ * @returns All enqueued public function calls.
+ */
+export function collectEnqueuedPublicFunctionCalls(execResult: ExecutionResult): PublicCallRequest[] {
+  // without the reverse sort, the logs will be in a queue like fashion which is wrong
+  // as the kernel processes it like a stack, popping items off and pushing them to output
+  return [
+    ...execResult.enqueuedPublicFunctionCalls,
+    ...[...execResult.nestedExecutions].flatMap(collectEnqueuedPublicFunctionCalls),
+  ].sort((a, b) => b.callContext.startSideEffectCounter - a.callContext.startSideEffectCounter);
+}

package/src/client/index.ts

@@ -0,0 +1,3 @@
+export * from './simulator.js';
+export * from './db_oracle.js';
+export * from './execution_result.js';

package/src/client/pick_notes.ts

@@ -0,0 +1,125 @@
+import { Comparator, Note } from '@aztec/circuit-types';
+import { Fr } from '@aztec/foundation/fields';
+
+/**
+ * Configuration for selecting values.
+ */
+export interface Select {
+  /**
+   * Index of the field to select and match.
+   */
+  index: number;
+  /**
+   * Required value of the field.
+   */
+  value: Fr;
+  /**
+   * The comparator to use
+   */
+  comparator: Comparator;
+}
+
+/**
+ * The order to sort an array.
+ */
+export enum SortOrder {
+  NADA = 0,
+  DESC = 1,
+  ASC = 2,
+}
+
+/**
+ * Configuration for sorting values.
+ */
+export interface Sort {
+  /**
+   * Index of the field to sort.
+   */
+  index: number;
+  /**
+   * Order to sort the field.
+   */
+  order: SortOrder;
+}
+
+/**
+ * Options for picking items from an array of BasicNoteData.
+ */
+interface GetOptions {
+  /**
+   * Configurations for selecting items.
+   * Default: empty array.
+   */
+  selects?: Select[];
+  /**
+   * Configurations for sorting items.
+   * Default: empty array.
+   */
+  sorts?: Sort[];
+  /**
+   * The number of items to retrieve per query.
+   * Default: 0. No limit.
+   */
+  limit?: number;
+  /**
+   * The starting index for pagination.
+   * Default: 0.
+   */
+  offset?: number;
+}
+
+/**
+ * Data needed from to perform sort.
+ */
+interface ContainsNote {
+  /**
+   * The note.
+   */
+  note: Note;
+}
+
+const selectNotes = <T extends ContainsNote>(noteDatas: T[], selects: Select[]): T[] =>
+  noteDatas.filter(noteData =>
+    selects.every(({ index, value, comparator }) => {
+      const comparatorSelector = {
+        [Comparator.EQ]: () => noteData.note.items[index].equals(value),
+        [Comparator.NEQ]: () => !noteData.note.items[index].equals(value),
+        [Comparator.LT]: () => noteData.note.items[index].lt(value),
+        [Comparator.LTE]: () => noteData.note.items[index].lt(value) || noteData.note.items[index].equals(value),
+        [Comparator.GT]: () => !noteData.note.items[index].lt(value) && !noteData.note.items[index].equals(value),
+        [Comparator.GTE]: () => !noteData.note.items[index].lt(value),
+      };
+
+      return comparatorSelector[comparator]();
+    }),
+  );
+
+const sortNotes = (a: Fr[], b: Fr[], sorts: Sort[], level = 0): number => {
+  if (sorts[level] === undefined) {
+    return 0;
+  }
+
+  const { index, order } = sorts[level];
+  if (order === 0) {
+    return 0;
+  }
+
+  const dir = order === 1 ? [-1, 1] : [1, -1];
+  return a[index].value === b[index].value
+    ? sortNotes(a, b, sorts, level + 1)
+    : a[index].value > b[index].value
+    ? dir[0]
+    : dir[1];
+};
+
+/**
+ * Pick from a note array a number of notes that meet the criteria.
+ */
+export function pickNotes<T extends ContainsNote>(
+  noteDatas: T[],
+  { selects = [], sorts = [], limit = 0, offset = 0 }: GetOptions,
+): T[] {
+  return selectNotes(noteDatas, selects)
+    .sort((a, b) => sortNotes(a.note.items, b.note.items, sorts))
+    .slice(offset, limit ? offset + limit : undefined);
+}

package/src/client/private_execution.ts

@@ -0,0 +1,79 @@
+import { FunctionData, PrivateCallStackItem, PrivateCircuitPublicInputs } from '@aztec/circuits.js';
+import { FunctionArtifactWithDebugMetadata, decodeReturnValues } from '@aztec/foundation/abi';
+import { AztecAddress } from '@aztec/foundation/aztec-address';
+import { Fr } from '@aztec/foundation/fields';
+import { createDebugLogger } from '@aztec/foundation/log';
+import { to2Fields } from '@aztec/foundation/serialize';
+
+import { extractReturnWitness } from '../acvm/deserialize.js';
+import { Oracle, acvm, extractCallStack } from '../acvm/index.js';
+import { ExecutionError } from '../common/errors.js';
+import { ClientExecutionContext } from './client_execution_context.js';
+import { ExecutionResult } from './execution_result.js';
+import { AcirSimulator } from './simulator.js';
+
+/**
+ * Execute a private function and return the execution result.
+ */
+export async function executePrivateFunction(
+  context: ClientExecutionContext,
+  artifact: FunctionArtifactWithDebugMetadata,
+  contractAddress: AztecAddress,
+  functionData: FunctionData,
+  log = createDebugLogger('aztec:simulator:secret_execution'),
+): Promise<ExecutionResult> {
+  const functionSelector = functionData.selector;
+  log(`Executing external function ${contractAddress}:${functionSelector}(${artifact.name})`);
+  const acir = Buffer.from(artifact.bytecode, 'base64');
+  const initialWitness = context.getInitialWitness(artifact);
+  const acvmCallback = new Oracle(context);
+  const { partialWitness } = await acvm(await AcirSimulator.getSolver(), acir, initialWitness, acvmCallback).catch(
+    (err: Error) => {
+      throw new ExecutionError(
+        err.message,
+        {
+          contractAddress,
+          functionSelector,
+        },
+        extractCallStack(err, artifact.debug),
+        { cause: err },
+      );
+    },
+  );
+
+  const returnWitness = extractReturnWitness(acir, partialWitness);
+  const publicInputs = PrivateCircuitPublicInputs.fromFields(returnWitness);
+
+  const encryptedLogs = context.getEncryptedLogs();
+  const unencryptedLogs = context.getUnencryptedLogs();
+  // TODO(https://github.com/AztecProtocol/aztec-packages/issues/1165) --> set this in Noir
+  publicInputs.encryptedLogsHash = to2Fields(encryptedLogs.hash());
+  publicInputs.encryptedLogPreimagesLength = new Fr(encryptedLogs.getSerializedLength());
+  publicInputs.unencryptedLogsHash = to2Fields(unencryptedLogs.hash());
+  publicInputs.unencryptedLogPreimagesLength = new Fr(unencryptedLogs.getSerializedLength());
+
+  const callStackItem = new PrivateCallStackItem(contractAddress, functionData, publicInputs);
+  const returnValues = decodeReturnValues(artifact, publicInputs.returnValues);
+  const noteHashReadRequestPartialWitnesses = context.getNoteHashReadRequestPartialWitnesses(
+    publicInputs.noteHashReadRequests,
+  );
+  const newNotes = context.getNewNotes();
+  const nestedExecutions = context.getNestedExecutions();
+  const enqueuedPublicFunctionCalls = context.getEnqueuedPublicFunctionCalls();
+
+  log(`Returning from call to ${contractAddress.toString()}:${functionSelector}`);
+
+  return {
+    acir,
+    partialWitness,
+    callStackItem,
+    returnValues,
+    noteHashReadRequestPartialWitnesses,
+    newNotes,
+    vk: Buffer.from(artifact.verificationKey!, 'hex'),
+    nestedExecutions,
+    enqueuedPublicFunctionCalls,
+    encryptedLogs,
+    unencryptedLogs,
+  };
+}