@aztec/simulator 0.23.0 → 0.24.0

package/src/client/unconstrained_execution.ts

@@ -0,0 +1,49 @@
+import { FunctionData } from '@aztec/circuits.js';
+import { DecodedReturn, 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 { extractReturnWitness } from '../acvm/deserialize.js';
+import { Oracle, acvm, extractCallStack, toACVMWitness } from '../acvm/index.js';
+import { ExecutionError } from '../common/errors.js';
+import { AcirSimulator } from './simulator.js';
+import { ViewDataOracle } from './view_data_oracle.js';
+
+// docs:start:execute_unconstrained_function
+/**
+ * Execute an unconstrained function and return the decoded values.
+ */
+export async function executeUnconstrainedFunction(
+  oracle: ViewDataOracle,
+  artifact: FunctionArtifactWithDebugMetadata,
+  contractAddress: AztecAddress,
+  functionData: FunctionData,
+  args: Fr[],
+  log = createDebugLogger('aztec:simulator:unconstrained_execution'),
+): Promise<DecodedReturn> {
+  const functionSelector = functionData.selector;
+  log(`Executing unconstrained function ${contractAddress}:${functionSelector}`);
+
+  const acir = Buffer.from(artifact.bytecode, 'base64');
+  const initialWitness = toACVMWitness(0, args);
+  const { partialWitness } = await acvm(
+    await AcirSimulator.getSolver(),
+    acir,
+    initialWitness,
+    new Oracle(oracle),
+  ).catch((err: Error) => {
+    throw new ExecutionError(
+      err.message,
+      {
+        contractAddress,
+        functionSelector,
+      },
+      extractCallStack(err, artifact.debug),
+      { cause: err },
+    );
+  });
+
+  return decodeReturnValues(artifact, extractReturnWitness(acir, partialWitness));
+}
+// docs:end:execute_unconstrained_function

package/src/client/view_data_oracle.ts

@@ -0,0 +1,243 @@
+import {
+  AuthWitness,
+  AztecNode,
+  CompleteAddress,
+  MerkleTreeId,
+  NoteStatus,
+  NullifierMembershipWitness,
+  PublicDataWitness,
+} from '@aztec/circuit-types';
+import { Header } from '@aztec/circuits.js';
+import { siloNullifier } from '@aztec/circuits.js/abis';
+import { AztecAddress } from '@aztec/foundation/aztec-address';
+import { Fr } from '@aztec/foundation/fields';
+import { createDebugLogger } from '@aztec/foundation/log';
+
+import { NoteData, TypedOracle } from '../acvm/index.js';
+import { DBOracle } from './db_oracle.js';
+import { pickNotes } from './pick_notes.js';
+
+/**
+ * The execution context for a client view tx simulation.
+ * It only reads data from data sources. Nothing will be updated or created during this simulation.
+ */
+export class ViewDataOracle extends TypedOracle {
+  constructor(
+    protected readonly contractAddress: AztecAddress,
+    /** List of transient auth witnesses to be used during this simulation */
+    protected readonly authWitnesses: AuthWitness[],
+    protected readonly db: DBOracle,
+    protected readonly aztecNode: AztecNode,
+    protected log = createDebugLogger('aztec:simulator:client_view_context'),
+  ) {
+    super();
+  }
+
+  /**
+   * Return the nullifier key pair of an account to use in a specific contract.
+   * @param account - The account address of the nullifier key.
+   */
+  public getNullifierKeyPair(account: AztecAddress) {
+    return this.db.getNullifierKeyPair(account, this.contractAddress);
+  }
+
+  /**
+   * 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]
+   */
+  public async getMembershipWitness(blockNumber: number, treeId: MerkleTreeId, leafValue: Fr): Promise<Fr[]> {
+    const index = await this.db.findLeafIndex(blockNumber, treeId, leafValue);
+    if (!index) {
+      throw new Error(`Leaf value: ${leafValue} not found in ${MerkleTreeId[treeId]}`);
+    }
+    const siblingPath = await this.db.getSiblingPath(blockNumber, treeId, index);
+    return [new Fr(index), ...siblingPath];
+  }
+
+  /**
+   * Fetches a sibling path at a given block and index from a tree specified by `treeId`.
+   * @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 leafIndex - Index of the leaf to get sibling path for
+   * @returns The sibling path.
+   */
+  public getSiblingPath(blockNumber: number, treeId: MerkleTreeId, leafIndex: Fr): Promise<Fr[]> {
+    return this.db.getSiblingPath(blockNumber, treeId, leafIndex.toBigInt());
+  }
+
+  /**
+   * 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).
+   */
+  public async getNullifierMembershipWitness(
+    blockNumber: number,
+    nullifier: Fr,
+  ): Promise<NullifierMembershipWitness | undefined> {
+    return await this.db.getNullifierMembershipWitness(blockNumber, nullifier);
+  }
+
+  /**
+   * 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.
+   */
+  public async getLowNullifierMembershipWitness(
+    blockNumber: number,
+    nullifier: Fr,
+  ): Promise<NullifierMembershipWitness | undefined> {
+    return await this.db.getLowNullifierMembershipWitness(blockNumber, nullifier);
+  }
+
+  /**
+   * Returns a public data tree witness for a given leaf slot at a given block.
+   * @param blockNumber - The block number at which to get the index.
+   * @param leafSlot - The slot of the public data tree to get the witness for.
+   * @returns - The witness
+   */
+  public async getPublicDataTreeWitness(blockNumber: number, leafSlot: Fr): Promise<PublicDataWitness | undefined> {
+    return await this.db.getPublicDataTreeWitness(blockNumber, leafSlot);
+  }
+
+  /**
+   * Fetches a block header of a given block.
+   * @param blockNumber - The number of a block of which to get the block header.
+   * @returns Block extracted from a block with block number `blockNumber`.
+   */
+  public async getHeader(blockNumber: number): Promise<Header | undefined> {
+    const block = await this.db.getBlock(blockNumber);
+    if (!block) {
+      return undefined;
+    }
+    return block.header;
+  }
+
+  /**
+   * Retrieve the complete address associated to a given address.
+   * @param address - Address to fetch the complete address for.
+   * @returns A complete address associated with the input address.
+   */
+  public getCompleteAddress(address: AztecAddress): Promise<CompleteAddress> {
+    return this.db.getCompleteAddress(address);
+  }
+
+  /**
+   * Returns an auth witness for the given message hash. Checks on the list of transient witnesses
+   * for this transaction first, and falls back to the local database if not found.
+   * @param messageHash - Hash of the message to authenticate.
+   * @returns Authentication witness for the requested message hash.
+   */
+  public getAuthWitness(messageHash: Fr): Promise<Fr[] | undefined> {
+    return Promise.resolve(
+      this.authWitnesses.find(w => w.requestHash.equals(messageHash))?.witness ?? this.db.getAuthWitness(messageHash),
+    );
+  }
+
+  /**
+   * Pops a capsule from the capsule dispenser
+   * @returns The capsule values
+   * @remarks A capsule is a "blob" of data that is passed to the contract through an oracle.
+   */
+  public popCapsule(): Promise<Fr[]> {
+    return this.db.popCapsule();
+  }
+
+  /**
+   * Gets some notes for a contract address and storage slot.
+   * Returns a flattened array containing filtered notes.
+   *
+   * @remarks
+   * Check for pending notes with matching slot.
+   * Real notes coming from DB will have a leafIndex which
+   * represents their index in the note hash tree.
+   *
+   * @param storageSlot - The storage slot.
+   * @param numSelects - The number of valid selects in selectBy and selectValues.
+   * @param selectBy - An array of indices of the fields to selects.
+   * @param selectValues - The values to match.
+   * @param selectComparators - The comparators to use to match values.
+   * @param sortBy - An array of indices of the fields to sort.
+   * @param sortOrder - The order of the corresponding index in sortBy. (1: DESC, 2: ASC, 0: Do nothing)
+   * @param limit - The number of notes to retrieve per query.
+   * @param offset - The starting index for pagination.
+   * @param status - The status of notes to fetch.
+   * @returns Array of note data.
+   */
+  public async getNotes(
+    storageSlot: Fr,
+    numSelects: number,
+    selectBy: number[],
+    selectValues: Fr[],
+    selectComparators: number[],
+    sortBy: number[],
+    sortOrder: number[],
+    limit: number,
+    offset: number,
+    status: NoteStatus,
+  ): Promise<NoteData[]> {
+    const dbNotes = await this.db.getNotes(this.contractAddress, storageSlot, status);
+    return pickNotes<NoteData>(dbNotes, {
+      selects: selectBy
+        .slice(0, numSelects)
+        .map((index, i) => ({ index, value: selectValues[i], comparator: selectComparators[i] })),
+      sorts: sortBy.map((index, i) => ({ index, order: sortOrder[i] })),
+      limit,
+      offset,
+    });
+  }
+
+  /**
+   * Check if a nullifier exists in the nullifier tree.
+   * @param innerNullifier - The inner nullifier.
+   * @returns A boolean indicating whether the nullifier exists in the tree or not.
+   */
+  public async checkNullifierExists(innerNullifier: Fr) {
+    const nullifier = siloNullifier(this.contractAddress, innerNullifier!);
+    const index = await this.db.getNullifierIndex(nullifier);
+    return index !== undefined;
+  }
+
+  /**
+   * Fetches the a message from the db, given its key.
+   * @param msgKey - A buffer representing the message key.
+   * @returns The l1 to l2 message data
+   */
+  public async getL1ToL2Message(msgKey: Fr) {
+    return await this.db.getL1ToL2Message(msgKey);
+  }
+
+  /**
+   * Retrieves the portal contract address associated with the given contract address.
+   * Throws an error if the input contract address is not found or invalid.
+   * @param contractAddress - The address of the contract whose portal address is to be fetched.
+   * @returns The portal contract address.
+   */
+  public getPortalContractAddress(contractAddress: AztecAddress) {
+    return this.db.getPortalContractAddress(contractAddress);
+  }
+
+  /**
+   * Read the public storage data.
+   * @param startStorageSlot - The starting storage slot.
+   * @param numberOfElements - Number of elements to read from the starting storage slot.
+   */
+  public async storageRead(startStorageSlot: Fr, numberOfElements: number) {
+    const values = [];
+    for (let i = 0n; i < numberOfElements; i++) {
+      const storageSlot = new Fr(startStorageSlot.value + i);
+      const value = await this.aztecNode.getPublicStorageAt(this.contractAddress, storageSlot);
+
+      this.log(`Oracle storage read: slot=${storageSlot.toString()} value=${value}`);
+      values.push(value);
+    }
+    return values;
+  }
+}

package/src/common/errors.ts

@@ -0,0 +1,61 @@
+import { FailingFunction, NoirCallStack, SimulationError } from '@aztec/circuit-types';
+
+/**
+ * An error that occurred during the execution of a function.
+ */
+export class ExecutionError extends Error {
+  constructor(
+    message: string,
+    /**
+     * The function that failed.
+     */
+    public failingFunction: FailingFunction,
+    /**
+     * The noir call stack of the function that failed.
+     */
+    public noirCallStack?: NoirCallStack,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+  }
+}
+
+/**
+ * Traverses the cause chain of an error.
+ * @param error - The error to start from.
+ * @param callback - A callback on every error, including the first one.
+ */
+export function traverseCauseChain(error: Error, callback: (error: Error) => void) {
+  let currentError: Error | undefined = error;
+  while (currentError) {
+    callback(currentError);
+    if (currentError.cause && currentError.cause instanceof Error) {
+      currentError = currentError.cause;
+    } else {
+      currentError = undefined;
+    }
+  }
+}
+
+/**
+ * Creates a simulation error from an error chain generated during the execution of a function.
+ * @param error - The error thrown during execution.
+ * @returns - A simulation error.
+ */
+export function createSimulationError(error: Error): SimulationError {
+  let rootCause = error;
+  let noirCallStack: NoirCallStack | undefined = undefined;
+  const aztecCallStack: FailingFunction[] = [];
+
+  traverseCauseChain(error, cause => {
+    rootCause = cause;
+    if (cause instanceof ExecutionError) {
+      aztecCallStack.push(cause.failingFunction);
+      if (cause.noirCallStack) {
+        noirCallStack = cause.noirCallStack;
+      }
+    }
+  });
+
+  return new SimulationError(rootCause.message, aztecCallStack, noirCallStack, { cause: rootCause });
+}

package/src/common/index.ts

@@ -0,0 +1,3 @@
+export * from './packed_args_cache.js';
+export * from './errors.js';
+export * from './side_effect_counter.js';

package/src/common/packed_args_cache.ts

@@ -0,0 +1,55 @@
+import { PackedArguments } from '@aztec/circuit-types';
+import { Fr } from '@aztec/circuits.js';
+
+/**
+ * A cache for packed arguments during transaction execution.
+ */
+export class PackedArgsCache {
+  private cache: Map<bigint, Fr[]>;
+
+  constructor(initialArguments: PackedArguments[] = []) {
+    this.cache = new Map();
+    for (const initialArg of initialArguments) {
+      this.cache.set(initialArg.hash.toBigInt(), initialArg.args);
+    }
+  }
+
+  /**
+   * Creates a new packed arguments cache.
+   * @param initialArguments - The initial arguments to add to the cache.
+   * @returns The new packed arguments cache.
+   */
+  public static create(initialArguments: PackedArguments[] = []) {
+    return new PackedArgsCache(initialArguments);
+  }
+
+  /**
+   * Unpacks packed arguments.
+   * @param hash - The hash of the packed arguments.
+   * @returns The unpacked arguments.
+   */
+  public unpack(hash: Fr): Fr[] {
+    if (hash.equals(Fr.ZERO)) {
+      return [];
+    }
+    const packedArgs = this.cache.get(hash.value);
+    if (!packedArgs) {
+      throw new Error(`Packed arguments for hash ${hash.toString()} not found in cache`);
+    }
+    return packedArgs;
+  }
+
+  /**
+   * Packs arguments.
+   * @param args - The arguments to pack.
+   * @returns The hash of the packed arguments.
+   */
+  public pack(args: Fr[]) {
+    if (args.length === 0) {
+      return Fr.ZERO;
+    }
+    const packedArguments = PackedArguments.fromArgs(args);
+    this.cache.set(packedArguments.hash.value, packedArguments.args);
+    return packedArguments.hash;
+  }
+}

package/src/common/side_effect_counter.ts

@@ -0,0 +1,12 @@
+/**
+ * Keep track of the number of side effects across execution contexts.
+ */
+export class SideEffectCounter {
+  constructor(private value = 0) {}
+
+  count() {
+    const value = this.value;
+    this.value++;
+    return value;
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './client/index.js';
+export * from './acvm/index.js';
+export * from './public/index.js';

package/src/public/db.ts

@@ -0,0 +1,85 @@
+import { EthAddress, FunctionSelector, L1_TO_L2_MSG_TREE_HEIGHT } from '@aztec/circuits.js';
+import { AztecAddress } from '@aztec/foundation/aztec-address';
+import { Fr } from '@aztec/foundation/fields';
+
+import { MessageLoadOracleInputs } from '../acvm/index.js';
+
+/**
+ * Database interface for providing access to public state.
+ */
+export interface PublicStateDB {
+  /**
+   * Reads a value from public storage, returning zero if none.
+   * @param contract - Owner of the storage.
+   * @param slot - Slot to read in the contract storage.
+   * @returns The current value in the storage slot.
+   */
+  storageRead(contract: AztecAddress, slot: Fr): Promise<Fr>;
+
+  /**
+   * Records a write to public storage.
+   * @param contract - Owner of the storage.
+   * @param slot - Slot to read in the contract storage.
+   * @param newValue - The new value to store.
+   * @returns Nothing.
+   */
+  storageWrite(contract: AztecAddress, slot: Fr, newValue: Fr): Promise<void>;
+
+  /**
+   * Commit the pending changes to the DB.
+   * @returns Nothing.
+   */
+  commit(): Promise<void>;
+
+  /**
+   * Rollback the pending changes.
+   * @returns Nothing.
+   */
+  rollback(): Promise<void>;
+}
+
+/**
+ * Database interface for providing access to public contract data.
+ */
+export interface PublicContractsDB {
+  /**
+   * Returns the brillig (public bytecode) of a function.
+   * @param address - The contract address that owns this function.
+   * @param selector - The selector for the function.
+   * @returns The bytecode or undefined if not found.
+   */
+  getBytecode(address: AztecAddress, selector: FunctionSelector): Promise<Buffer | undefined>;
+
+  /**
+   * Returns whether a function is internal or not.
+   * @param address - The contract address that owns this function.
+   * @param selector - The selector for the function.
+   * @returns The `isInternal` flag found, undefined if not found.
+   */
+  getIsInternal(address: AztecAddress, selector: FunctionSelector): Promise<boolean | undefined>;
+
+  /**
+   * Returns the portal contract address for an L2 address.
+   * @param address - The L2 contract address.
+   * @returns The portal contract address or undefined if not found.
+   */
+  getPortalContractAddress(address: AztecAddress): Promise<EthAddress | undefined>;
+}
+
+/** Database interface for providing access to commitment tree and l1 to l2 message tree (append only data trees). */
+export interface CommitmentsDB {
+  /**
+   * Gets a confirmed L1 to L2 message for the given message key.
+   * TODO(Maddiaa): Can be combined with aztec-node method that does the same thing.
+   * @param msgKey - The message Key.
+   * @returns - The l1 to l2 message object
+   */
+  getL1ToL2Message(msgKey: Fr): Promise<MessageLoadOracleInputs<typeof L1_TO_L2_MSG_TREE_HEIGHT>>;
+
+  /**
+   * Gets the index of a commitment in the note hash tree.
+   * @param commitment - The commitment.
+   * @returns - The index of the commitment. Undefined if it does not exist in the tree.
+   */
+  getCommitmentIndex(commitment: Fr): Promise<bigint | undefined>;
+}

package/src/public/execution.ts

@@ -0,0 +1,137 @@
+import { FunctionL2Logs } from '@aztec/circuit-types';
+import {
+  AztecAddress,
+  CallContext,
+  ContractStorageRead,
+  ContractStorageUpdateRequest,
+  Fr,
+  FunctionData,
+  PublicDataRead,
+  PublicDataUpdateRequest,
+  SideEffect,
+  SideEffectLinkedToNoteHash,
+} from '@aztec/circuits.js';
+import { computePublicDataTreeLeafSlot, computePublicDataTreeValue } from '@aztec/circuits.js/abis';
+
+/**
+ * The public function execution result.
+ */
+export interface PublicExecutionResult {
+  /** The execution that triggered this result. */
+  execution: PublicExecution;
+  /** The return values of the function. */
+  returnValues: Fr[];
+  /** The new commitments to be inserted into the commitments tree. */
+  newCommitments: SideEffect[];
+  /** The new l2 to l1 messages generated in this call. */
+  newL2ToL1Messages: Fr[];
+  /** The new nullifiers to be inserted into the nullifier tree. */
+  newNullifiers: SideEffectLinkedToNoteHash[];
+  /** The contract storage reads performed by the function. */
+  contractStorageReads: ContractStorageRead[];
+  /** The contract storage update requests performed by the function. */
+  contractStorageUpdateRequests: ContractStorageUpdateRequest[];
+  /** The results of nested calls. */
+  nestedExecutions: this[];
+  /**
+   * Unencrypted logs emitted during execution of this function call.
+   * Note: These are preimages to `unencryptedLogsHash`.
+   */
+  unencryptedLogs: FunctionL2Logs;
+}
+
+/**
+ * The execution of a public function.
+ */
+export interface PublicExecution {
+  /** Address of the contract being executed. */
+  contractAddress: AztecAddress;
+  /** Function of the contract being called. */
+  functionData: FunctionData;
+  /** Arguments for the call. */
+  args: Fr[];
+  /** Context of the call. */
+  callContext: CallContext;
+}
+
+/**
+ * Returns if the input is a public execution result and not just a public execution.
+ * @param input - Public execution or public execution result.
+ * @returns Whether the input is a public execution result and not just a public execution.
+ */
+export function isPublicExecutionResult(
+  input: PublicExecution | PublicExecutionResult,
+): input is PublicExecutionResult {
+  return !!(input as PublicExecutionResult).execution;
+}
+
+/**
+ * Collect all public storage reads across all nested executions
+ * and convert them to PublicDataReads (to match kernel output).
+ * @param execResult - The topmost execution result.
+ * @returns All public data reads (in execution order).
+ */
+export function collectPublicDataReads(execResult: PublicExecutionResult): PublicDataRead[] {
+  // HACK(#1622): part of temporary hack - may be able to remove this function after public state ordering is fixed
+  const contractAddress = execResult.execution.contractAddress;
+
+  const thisExecPublicDataReads = execResult.contractStorageReads.map(read =>
+    contractStorageReadToPublicDataRead(read, contractAddress),
+  );
+  const unsorted = [
+    ...thisExecPublicDataReads,
+    ...[...execResult.nestedExecutions].flatMap(result => collectPublicDataReads(result)),
+  ];
+  return unsorted.sort((a, b) => a.sideEffectCounter! - b.sideEffectCounter!);
+}
+
+/**
+ * Collect all public storage update requests across all nested executions
+ * and convert them to PublicDataUpdateRequests (to match kernel output).
+ * @param execResult - The topmost execution result.
+ * @returns All public data reads (in execution order).
+ */
+export function collectPublicDataUpdateRequests(execResult: PublicExecutionResult): PublicDataUpdateRequest[] {
+  // HACK(#1622): part of temporary hack - may be able to remove this function after public state ordering is fixed
+  const contractAddress = execResult.execution.contractAddress;
+
+  const thisExecPublicDataUpdateRequests = execResult.contractStorageUpdateRequests.map(update =>
+    contractStorageUpdateRequestToPublicDataUpdateRequest(update, contractAddress),
+  );
+  const unsorted = [
+    ...thisExecPublicDataUpdateRequests,
+    ...[...execResult.nestedExecutions].flatMap(result => collectPublicDataUpdateRequests(result)),
+  ];
+  return unsorted.sort((a, b) => a.sideEffectCounter! - b.sideEffectCounter!);
+}
+
+/**
+ * Convert a Contract Storage Read to a Public Data Read.
+ * @param read - the contract storage read to convert
+ * @param contractAddress - the contract address of the read
+ * @returns The public data read.
+ */
+function contractStorageReadToPublicDataRead(read: ContractStorageRead, contractAddress: AztecAddress): PublicDataRead {
+  return new PublicDataRead(
+    computePublicDataTreeLeafSlot(contractAddress, read.storageSlot),
+    computePublicDataTreeValue(read.currentValue),
+    read.sideEffectCounter!,
+  );
+}
+
+/**
+ * Convert a Contract Storage Update Request to a Public Data Update Request.
+ * @param update - the contract storage update request to convert
+ * @param contractAddress - the contract address of the data update request.
+ * @returns The public data update request.
+ */
+function contractStorageUpdateRequestToPublicDataUpdateRequest(
+  update: ContractStorageUpdateRequest,
+  contractAddress: AztecAddress,
+): PublicDataUpdateRequest {
+  return new PublicDataUpdateRequest(
+    computePublicDataTreeLeafSlot(contractAddress, update.storageSlot),
+    computePublicDataTreeValue(update.newValue),
+    update.sideEffectCounter!,
+  );
+}