@aztec/simulator 0.23.0 → 0.24.0

package/src/public/executor.ts

@@ -0,0 +1,158 @@
+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 { AvmWorldStateJournal } 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 } 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,
+    newCommitments: newCommitmentsPadded,
+    newNullifiers: newNullifiersPadded,
+  } = PublicCircuitPublicInputs.fromFields(returnWitness);
+
+  const newL2ToL1Messages = newL2ToL1Msgs.filter(v => !v.isZero());
+  const newCommitments = newCommitmentsPadded.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(', ')}`,
+  );
+
+  const nestedExecutions = context.getNestedExecutions();
+  const unencryptedLogs = context.getUnencryptedLogs();
+
+  return {
+    execution,
+    newCommitments,
+    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,
+    );
+
+    try {
+      return await executePublicFunction(context, acir);
+    } catch (err) {
+      throw createSimulationError(err instanceof Error ? err : new Error('Unknown error during public execution'));
+    }
+  }
+
+  /**
+   * 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 AvmWorldStateJournal(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.worldState.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';

package/src/public/public_execution_context.ts

@@ -0,0 +1,217 @@
+import { FunctionL2Logs, UnencryptedL2Log } from '@aztec/circuit-types';
+import { CallContext, FunctionData, FunctionSelector, GlobalVariables, Header } from '@aztec/circuits.js';
+import { AztecAddress } from '@aztec/foundation/aztec-address';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { Fr } from '@aztec/foundation/fields';
+import { createDebugLogger } from '@aztec/foundation/log';
+
+import { TypedOracle, toACVMWitness } from '../acvm/index.js';
+import { PackedArgsCache, SideEffectCounter } from '../common/index.js';
+import { CommitmentsDB, PublicContractsDB, PublicStateDB } from './db.js';
+import { PublicExecution, PublicExecutionResult } from './execution.js';
+import { executePublicFunction } from './executor.js';
+import { ContractStorageActionsCollector } from './state_actions.js';
+
+/**
+ * The execution context for a public tx simulation.
+ */
+export class PublicExecutionContext extends TypedOracle {
+  private storageActions: ContractStorageActionsCollector;
+  private nestedExecutions: PublicExecutionResult[] = [];
+  private unencryptedLogs: UnencryptedL2Log[] = [];
+
+  constructor(
+    /**
+     * Data for this execution.
+     */
+    public readonly execution: PublicExecution,
+    private readonly header: Header,
+    private readonly globalVariables: GlobalVariables,
+    private readonly packedArgsCache: PackedArgsCache,
+    private readonly sideEffectCounter: SideEffectCounter,
+    private readonly stateDb: PublicStateDB,
+    private readonly contractsDb: PublicContractsDB,
+    private readonly commitmentsDb: CommitmentsDB,
+    private log = createDebugLogger('aztec:simulator:public_execution_context'),
+  ) {
+    super();
+    this.storageActions = new ContractStorageActionsCollector(stateDb, execution.contractAddress);
+  }
+
+  /**
+   * Generates the initial witness for a public function.
+   * @param args - The arguments to the function.
+   * @param callContext - The call context of the function.
+   * @param header - Contains data required to reconstruct a block hash (historical roots etc.).
+   * @param globalVariables - The global variables.
+   * @param witnessStartIndex - The index where to start inserting the parameters.
+   * @returns The initial witness.
+   */
+  public getInitialWitness(witnessStartIndex = 0) {
+    const { callContext, args } = this.execution;
+    const fields = [...callContext.toFields(), ...this.header.toFields(), ...this.globalVariables.toFields(), ...args];
+
+    return toACVMWitness(witnessStartIndex, fields);
+  }
+
+  /**
+   * Return the nested execution results during this execution.
+   */
+  public getNestedExecutions() {
+    return this.nestedExecutions;
+  }
+
+  /**
+   * Return the encrypted logs emitted during this execution.
+   */
+  public getUnencryptedLogs() {
+    return new FunctionL2Logs(this.unencryptedLogs.map(log => log.toBuffer()));
+  }
+
+  /**
+   * Return the data read and updated during this execution.
+   */
+  public getStorageActionData() {
+    const [contractStorageReads, contractStorageUpdateRequests] = this.storageActions.collect();
+    return { contractStorageReads, contractStorageUpdateRequests };
+  }
+
+  /**
+   * Pack the given arguments.
+   * @param args - Arguments to pack
+   */
+  public packArguments(args: Fr[]): Promise<Fr> {
+    return Promise.resolve(this.packedArgsCache.pack(args));
+  }
+
+  /**
+   * 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.commitmentsDb.getL1ToL2Message(msgKey);
+  }
+
+  /**
+   * Emit an unencrypted log.
+   * @param log - The unencrypted log to be emitted.
+   */
+  public emitUnencryptedLog(log: UnencryptedL2Log) {
+    // TODO(https://github.com/AztecProtocol/aztec-packages/issues/885)
+    this.unencryptedLogs.push(log);
+    this.log(`Emitted unencrypted log: "${log.toHumanReadable()}"`);
+  }
+
+  /**
+   * Retrieves the portal contract address associated with the given contract address.
+   * Returns zero address 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 async getPortalContractAddress(contractAddress: AztecAddress) {
+    return (await this.contractsDb.getPortalContractAddress(contractAddress)) ?? EthAddress.ZERO;
+  }
+
+  /**
+   * 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 = 0; i < Number(numberOfElements); i++) {
+      const storageSlot = new Fr(startStorageSlot.value + BigInt(i));
+      const sideEffectCounter = this.sideEffectCounter.count();
+      const value = await this.storageActions.read(storageSlot, sideEffectCounter);
+      this.log(`Oracle storage read: slot=${storageSlot.toString()} value=${value.toString()}`);
+      values.push(value);
+    }
+    return values;
+  }
+
+  /**
+   * Write some values to the public storage.
+   * @param startStorageSlot - The starting storage slot.
+   * @param values - The values to be written.
+   */
+  public async storageWrite(startStorageSlot: Fr, values: Fr[]) {
+    const newValues = [];
+    for (let i = 0; i < values.length; i++) {
+      const storageSlot = new Fr(startStorageSlot.value + BigInt(i));
+      const newValue = values[i];
+      const sideEffectCounter = this.sideEffectCounter.count();
+      this.storageActions.write(storageSlot, newValue, sideEffectCounter);
+      await this.stateDb.storageWrite(this.execution.contractAddress, storageSlot, newValue);
+      this.log(`Oracle storage write: slot=${storageSlot.toString()} value=${newValue.toString()}`);
+      newValues.push(newValue);
+    }
+    return newValues;
+  }
+
+  /**
+   * Calls a public function as a nested execution.
+   * @param targetContractAddress - The address of the contract to call.
+   * @param functionSelector - The function selector of the function to call.
+   * @param argsHash - The packed arguments to pass to the function.
+   * @returns The return values of the public function.
+   */
+  public async callPublicFunction(
+    targetContractAddress: AztecAddress,
+    functionSelector: FunctionSelector,
+    argsHash: Fr,
+  ) {
+    const args = this.packedArgsCache.unpack(argsHash);
+    this.log(`Public function call: addr=${targetContractAddress} selector=${functionSelector} args=${args.join(',')}`);
+
+    const portalAddress = (await this.contractsDb.getPortalContractAddress(targetContractAddress)) ?? EthAddress.ZERO;
+    const isInternal = await this.contractsDb.getIsInternal(targetContractAddress, functionSelector);
+    if (isInternal === undefined) {
+      throw new Error(`ERR: Method not found - ${targetContractAddress.toString()}:${functionSelector.toString()}`);
+    }
+
+    const acir = await this.contractsDb.getBytecode(targetContractAddress, functionSelector);
+    if (!acir) {
+      throw new Error(`Bytecode not found for ${targetContractAddress}:${functionSelector}`);
+    }
+
+    const functionData = new FunctionData(functionSelector, isInternal, false, false);
+
+    const callContext = CallContext.from({
+      msgSender: this.execution.contractAddress,
+      portalContractAddress: portalAddress,
+      storageContractAddress: targetContractAddress,
+      functionSelector,
+      isContractDeployment: false,
+      isDelegateCall: false,
+      isStaticCall: false,
+      startSideEffectCounter: 0, // TODO use counters in public execution
+    });
+
+    const nestedExecution: PublicExecution = {
+      args,
+      contractAddress: targetContractAddress,
+      functionData,
+      callContext,
+    };
+
+    const context = new PublicExecutionContext(
+      nestedExecution,
+      this.header,
+      this.globalVariables,
+      this.packedArgsCache,
+      this.sideEffectCounter,
+      this.stateDb,
+      this.contractsDb,
+      this.commitmentsDb,
+      this.log,
+    );
+
+    const childExecutionResult = await executePublicFunction(context, acir);
+
+    this.nestedExecutions.push(childExecutionResult);
+    this.log(`Returning from nested call: ret=${childExecutionResult.returnValues.join(', ')}`);
+
+    return childExecutionResult.returnValues;
+  }
+}

package/src/public/state_actions.ts

@@ -0,0 +1,100 @@
+import { ContractStorageRead, ContractStorageUpdateRequest } from '@aztec/circuits.js';
+import { AztecAddress } from '@aztec/foundation/aztec-address';
+import { Fr } from '@aztec/foundation/fields';
+
+import { PublicStateDB } from './db.js';
+
+/**
+ * Implements read/write operations on a contract public storage, collecting
+ * all read and update operations, and collapsing them into a single
+ * read or update per slot.
+ */
+export class ContractStorageActionsCollector {
+  // Map from slot to first read value
+  private readonly contractStorageReads: Map<
+    bigint,
+    { /** The value read. */ currentValue: Fr; /** Side effect counter. */ sideEffectCounter: number }
+  > = new Map();
+
+  // Map from slot to first read value and latest updated value
+  private readonly contractStorageUpdateRequests: Map<
+    bigint,
+    {
+      /** The updated value. */ newValue: Fr;
+      /** Side effect counter. */ sideEffectCounter: number;
+    }
+  > = new Map();
+
+  constructor(private db: PublicStateDB, private address: AztecAddress) {}
+
+  /**
+   * Returns the current value of a slot according to the latest update request for it,
+   * falling back to the public db. Collects the operation in storage reads,
+   * as long as there is no existing update request.
+   * @param storageSlot - Slot to check.
+   * @param sideEffectCounter - Side effect counter associated with this storage action.
+   * @returns The current value as affected by all update requests so far.
+   */
+  public async read(storageSlot: Fr, sideEffectCounter: number): Promise<Fr> {
+    const slot = storageSlot.value;
+    const updateRequest = this.contractStorageUpdateRequests.get(slot);
+    if (updateRequest) {
+      return updateRequest.newValue;
+    }
+    const read = this.contractStorageReads.get(slot);
+    if (read) {
+      return read.currentValue;
+    }
+    const value = await this.db.storageRead(this.address, storageSlot);
+    this.contractStorageReads.set(slot, { currentValue: value, sideEffectCounter });
+    return value;
+  }
+
+  /**
+   * Sets a new value for a slot in the internal update requests cache,
+   * clearing any previous storage read or update operation for the same slot.
+   * @param storageSlot - Slot to write to.
+   * @param newValue - Value to write to it.
+   * @param sideEffectCounter - Side effect counter associated with this storage action.
+   */
+  public write(storageSlot: Fr, newValue: Fr, sideEffectCounter: number): void {
+    const slot = storageSlot.value;
+    const updateRequest = this.contractStorageUpdateRequests.get(slot);
+    if (updateRequest) {
+      this.contractStorageUpdateRequests.set(slot, { newValue, sideEffectCounter });
+      return;
+    }
+
+    const read = this.contractStorageReads.get(slot);
+    if (read) {
+      this.contractStorageReads.delete(slot);
+      this.contractStorageUpdateRequests.set(slot, { newValue, sideEffectCounter });
+      return;
+    }
+
+    this.contractStorageUpdateRequests.set(slot, { newValue, sideEffectCounter });
+    return;
+  }
+
+  /**
+   * Returns all storage reads and update requests performed.
+   * @returns All storage read and update requests.
+   */
+  public collect(): [ContractStorageRead[], ContractStorageUpdateRequest[]] {
+    const reads = Array.from(this.contractStorageReads.entries()).map(([slot, valueAndCounter]) =>
+      ContractStorageRead.from({
+        storageSlot: new Fr(slot),
+        ...valueAndCounter,
+      }),
+    );
+
+    const updateRequests = Array.from(this.contractStorageUpdateRequests.entries()).map(([slot, valuesAndCounter]) =>
+      ContractStorageUpdateRequest.from({
+        storageSlot: new Fr(slot),
+        ...valuesAndCounter,
+      }),
+    );
+
+    return [reads, updateRequests];
+  }
+}

package/src/test/utils.ts

@@ -0,0 +1,38 @@
+import { L1Actor, L1ToL2Message, L2Actor } from '@aztec/circuit-types';
+import { AztecAddress, EthAddress, Fr } from '@aztec/circuits.js';
+import { computeSecretMessageHash } from '@aztec/circuits.js/abis';
+import { sha256 } from '@aztec/foundation/crypto';
+
+/**
+ * Test utility function to craft an L1 to L2 message.
+ * @param selector - The cross chain message selector.
+ * @param contentPreimage - The args after the selector.
+ * @param targetContract - The contract to consume the message.
+ * @param secret - The secret to unlock the message.
+ * @returns The L1 to L2 message.
+ */
+export const buildL1ToL2Message = (
+  selector: string,
+  contentPreimage: Fr[],
+  targetContract: AztecAddress,
+  secret: Fr,
+) => {
+  // Write the selector into a buffer.
+  const selectorBuf = Buffer.from(selector, 'hex');
+
+  const contentBuf = Buffer.concat([selectorBuf, ...contentPreimage.map(field => field.toBuffer())]);
+  const content = Fr.fromBufferReduce(sha256(contentBuf));
+
+  const secretHash = computeSecretMessageHash(secret);
+
+  // Eventually the kernel will need to prove the kernel portal pair exists within the contract tree,
+  // EthAddress.random() will need to be replaced when this happens
+  return new L1ToL2Message(
+    new L1Actor(EthAddress.random(), 1),
+    new L2Actor(targetContract, 1),
+    content,
+    secretHash,
+    0,
+    0,
+  );
+};

package/src/utils.ts

@@ -0,0 +1,18 @@
+import { pedersenHash } from '@aztec/foundation/crypto';
+import { Fr } from '@aztec/foundation/fields';
+
+/**
+ * Computes the resulting storage slot for an entry in a mapping.
+ * @param mappingSlot - The slot of the mapping within state.
+ * @param key - The key of the mapping.
+ * @returns The slot in the contract storage where the value is stored.
+ */
+export function computeSlotForMapping(
+  mappingSlot: Fr,
+  key: {
+    /** Serialize to a field. */
+    toField: () => Fr;
+  },
+) {
+  return Fr.fromBuffer(pedersenHash([mappingSlot, key.toField()].map(field => field.toBuffer())));
+}