@aztec/simulator 0.23.0 → 0.26.1

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,100 @@
+import { NullifierMembershipWitness } from '@aztec/circuit-types';
+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, l1 to l2 message tree, and nullifier tree. */
+export interface CommitmentsDB {
+  /**
+   * Gets a confirmed L1 to L2 message for the given entry key.
+   * TODO(Maddiaa): Can be combined with aztec-node method that does the same thing.
+   * @param entryKey - The entry key.
+   * @returns - The l1 to l2 message object
+   */
+  getL1ToL2MembershipWitness(entryKey: 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>;
+
+  /**
+   * 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>;
+}

package/src/public/execution.ts

@@ -0,0 +1,161 @@
+import { FunctionL2Logs } from '@aztec/circuit-types';
+import {
+  AztecAddress,
+  CallContext,
+  ContractStorageRead,
+  ContractStorageUpdateRequest,
+  Fr,
+  FunctionData,
+  L2ToL1Message,
+  PublicDataRead,
+  PublicDataUpdateRequest,
+  SideEffect,
+  SideEffectLinkedToNoteHash,
+} from '@aztec/circuits.js';
+import { computePublicDataTreeLeafSlot, computePublicDataTreeValue } from '@aztec/circuits.js/hash';
+
+/**
+ * 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 note hashes to be inserted into the note hashes tree. */
+  newNoteHashes: SideEffect[];
+  /** The new l2 to l1 messages generated in this call. */
+  newL2ToL1Messages: L2ToL1Message[];
+  /** 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.callContext.storageContractAddress;
+
+  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.callContext.storageContractAddress;
+
+  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!,
+  );
+}
+
+/**
+ * Checks whether the child execution result is valid for a static call (no state modifications).
+ * @param executionResult - The execution result of a public function
+ */
+
+export function checkValidStaticCall(
+  newNoteHashes: SideEffect[],
+  newNullifiers: SideEffectLinkedToNoteHash[],
+  contractStorageUpdateRequests: ContractStorageUpdateRequest[],
+  newL2ToL1Messages: L2ToL1Message[],
+  unencryptedLogs: FunctionL2Logs,
+) {
+  if (
+    contractStorageUpdateRequests.length > 0 ||
+    newNoteHashes.length > 0 ||
+    newNullifiers.length > 0 ||
+    newL2ToL1Messages.length > 0 ||
+    unencryptedLogs.logs.length > 0
+  ) {
+    throw new Error('Static call cannot update the state, emit L2->L1 messages or generate logs');
+  }
+}

package/src/public/executor.ts

@@ -0,0 +1,178 @@
+import { GlobalVariables, Header, PublicCircuitPublicInputs } from '@aztec/circuits.js';
+import { createDebugLogger } from '@aztec/foundation/log';
+
+import { Oracle, acvm, extractCallStack, extractReturnWitness } from '../acvm/index.js';
+import { AvmContext } from '../avm/avm_context.js';
+import { AvmMachineState } from '../avm/avm_machine_state.js';
+import { AvmSimulator } from '../avm/avm_simulator.js';
+import { HostStorage } from '../avm/journal/host_storage.js';
+import { AvmPersistableStateManager } from '../avm/journal/index.js';
+import {
+  temporaryConvertAvmResults,
+  temporaryCreateAvmExecutionEnvironment,
+} from '../avm/temporary_executor_migration.js';
+import { ExecutionError, createSimulationError } from '../common/errors.js';
+import { SideEffectCounter } from '../common/index.js';
+import { PackedArgsCache } from '../common/packed_args_cache.js';
+import { AcirSimulator } from '../index.js';
+import { CommitmentsDB, PublicContractsDB, PublicStateDB } from './db.js';
+import { PublicExecution, PublicExecutionResult, checkValidStaticCall } from './execution.js';
+import { PublicExecutionContext } from './public_execution_context.js';
+
+/**
+ * Execute a public function and return the execution result.
+ */
+export async function executePublicFunction(
+  context: PublicExecutionContext,
+  acir: Buffer,
+  log = createDebugLogger('aztec:simulator:public_execution'),
+): Promise<PublicExecutionResult> {
+  const execution = context.execution;
+  const { contractAddress, functionData } = execution;
+  const selector = functionData.selector;
+  log(`Executing public external function ${contractAddress.toString()}:${selector}`);
+
+  const initialWitness = context.getInitialWitness();
+  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: selector,
+        },
+        extractCallStack(err),
+        { cause: err },
+      );
+    },
+  );
+
+  const returnWitness = extractReturnWitness(acir, partialWitness);
+  const {
+    returnValues,
+    newL2ToL1Msgs,
+    newNoteHashes: newNoteHashesPadded,
+    newNullifiers: newNullifiersPadded,
+  } = PublicCircuitPublicInputs.fromFields(returnWitness);
+
+  const newL2ToL1Messages = newL2ToL1Msgs.filter(v => !v.isEmpty());
+  const newNoteHashes = newNoteHashesPadded.filter(v => !v.isEmpty());
+  const newNullifiers = newNullifiersPadded.filter(v => !v.isEmpty());
+
+  const { contractStorageReads, contractStorageUpdateRequests } = context.getStorageActionData();
+
+  log(
+    `Contract storage reads: ${contractStorageReads
+      .map(r => r.toFriendlyJSON() + ` - sec: ${r.sideEffectCounter}`)
+      .join(', ')}`,
+  );
+  log(
+    `Contract storage update requests: ${contractStorageUpdateRequests
+      .map(r => r.toFriendlyJSON() + ` - sec: ${r.sideEffectCounter}`)
+      .join(', ')}`,
+  );
+
+  const nestedExecutions = context.getNestedExecutions();
+  const unencryptedLogs = context.getUnencryptedLogs();
+
+  return {
+    execution,
+    newNoteHashes,
+    newL2ToL1Messages,
+    newNullifiers,
+    contractStorageReads,
+    contractStorageUpdateRequests,
+    returnValues,
+    nestedExecutions,
+    unencryptedLogs,
+  };
+}
+
+/**
+ * Handles execution of public functions.
+ */
+export class PublicExecutor {
+  constructor(
+    private readonly stateDb: PublicStateDB,
+    private readonly contractsDb: PublicContractsDB,
+    private readonly commitmentsDb: CommitmentsDB,
+    private readonly header: Header,
+  ) {}
+
+  /**
+   * Executes a public execution request.
+   * @param execution - The execution to run.
+   * @param globalVariables - The global variables to use.
+   * @returns The result of the run plus all nested runs.
+   */
+  public async simulate(execution: PublicExecution, globalVariables: GlobalVariables): Promise<PublicExecutionResult> {
+    const selector = execution.functionData.selector;
+    const acir = await this.contractsDb.getBytecode(execution.contractAddress, selector);
+    if (!acir) {
+      throw new Error(`Bytecode not found for ${execution.contractAddress}:${selector}`);
+    }
+
+    // Functions can request to pack arguments before calling other functions.
+    // We use this cache to hold the packed arguments.
+    const packedArgs = PackedArgsCache.create([]);
+
+    const sideEffectCounter = new SideEffectCounter();
+
+    const context = new PublicExecutionContext(
+      execution,
+      this.header,
+      globalVariables,
+      packedArgs,
+      sideEffectCounter,
+      this.stateDb,
+      this.contractsDb,
+      this.commitmentsDb,
+    );
+
+    let executionResult;
+
+    try {
+      executionResult = await executePublicFunction(context, acir);
+    } catch (err) {
+      throw createSimulationError(err instanceof Error ? err : new Error('Unknown error during public execution'));
+    }
+
+    if (executionResult.execution.callContext.isStaticCall) {
+      checkValidStaticCall(
+        executionResult.newNoteHashes,
+        executionResult.newNullifiers,
+        executionResult.contractStorageUpdateRequests,
+        executionResult.newL2ToL1Messages,
+        executionResult.unencryptedLogs,
+      );
+    }
+
+    return executionResult;
+  }
+
+  /**
+   * Executes a public execution request in the avm.
+   * @param execution - The execution to run.
+   * @param globalVariables - The global variables to use.
+   * @returns The result of the run plus all nested runs.
+   */
+  public async simulateAvm(
+    execution: PublicExecution,
+    globalVariables: GlobalVariables,
+  ): Promise<PublicExecutionResult> {
+    // Temporary code to construct the AVM context
+    // These data structures will permiate across the simulator when the public executor is phased out
+    const hostStorage = new HostStorage(this.stateDb, this.contractsDb, this.commitmentsDb);
+    const worldStateJournal = new AvmPersistableStateManager(hostStorage);
+    const executionEnv = temporaryCreateAvmExecutionEnvironment(execution, globalVariables);
+    const machineState = new AvmMachineState(0, 0, 0);
+
+    const context = new AvmContext(worldStateJournal, executionEnv, machineState);
+    const simulator = new AvmSimulator(context);
+
+    const result = await simulator.execute();
+    const newWorldState = context.persistableState.flush();
+    return temporaryConvertAvmResults(execution, newWorldState, result);
+  }
+}

package/src/public/index.ts

@@ -0,0 +1,9 @@
+export * from './db.js';
+export {
+  PublicExecution,
+  PublicExecutionResult,
+  isPublicExecutionResult,
+  collectPublicDataReads,
+  collectPublicDataUpdateRequests,
+} from './execution.js';
+export { PublicExecutor } from './executor.js';