@aztec/simulator 0.34.0 → 0.35.0

package/src/public/executor.ts

@@ -1,12 +1,12 @@
 import { UnencryptedFunctionL2Logs } from '@aztec/circuit-types';
-import { Fr, type GlobalVariables, type Header, PublicCircuitPublicInputs } from '@aztec/circuits.js';
+import { Fr, Gas, type GlobalVariables, type Header, PublicCircuitPublicInputs } from '@aztec/circuits.js';
 import { createDebugLogger } from '@aztec/foundation/log';
 
 import { spawn } from 'child_process';
 import fs from 'fs/promises';
 import path from 'path';
 
-import { Oracle, acvm, extractCallStack, extractReturnWitness } from '../acvm/index.js';
+import { Oracle, acvm, extractCallStack, witnessMapToFields } 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';
@@ -15,7 +15,7 @@ import { AvmPersistableStateManager } from '../avm/journal/index.js';
 import { AcirSimulator } from '../client/simulator.js';
 import { ExecutionError, createSimulationError } from '../common/errors.js';
 import { SideEffectCounter } from '../common/index.js';
-import { PackedArgsCache } from '../common/packed_args_cache.js';
+import { PackedValuesCache } from '../common/packed_values_cache.js';
 import { type CommitmentsDB, type PublicContractsDB, type PublicStateDB } from './db.js';
 import { type PublicExecution, type PublicExecutionResult, checkValidStaticCall } from './execution.js';
 import { PublicExecutionContext } from './public_execution_context.js';
@@ -66,19 +66,18 @@ async function executePublicFunctionAvm(executionContext: PublicExecutionContext
     executionContext.globalVariables,
   );
 
-  // TODO(@spalladino) Load initial gas from the public execution request
-  const machineState = new AvmMachineState(1e7, 1e7, 1e7);
-
+  const machineState = new AvmMachineState(executionContext.execution.callContext.gasLeft);
   const context = new AvmContext(worldStateJournal, executionEnv, machineState);
   const simulator = new AvmSimulator(context);
 
   const result = await simulator.execute();
   const newWorldState = context.persistableState.flush();
 
-  log.verbose(`[AVM] ${address.toString()}:${selector} returned, reverted: ${result.reverted}.`);
+  log.verbose(
+    `[AVM] ${address.toString()}:${selector} returned, reverted: ${result.reverted}, reason: ${result.revertReason}.`,
+  );
 
-  // TODO(@spalladino) Read gas left from machineState and return it
-  return await convertAvmResults(executionContext, newWorldState, result);
+  return await convertAvmResults(executionContext, newWorldState, result, machineState);
 }
 
 async function executePublicFunctionAcvm(
@@ -95,11 +94,12 @@ async function executePublicFunctionAcvm(
   const initialWitness = context.getInitialWitness();
   const acvmCallback = new Oracle(context);
 
-  const { partialWitness, reverted, revertReason } = await (async () => {
+  const { partialWitness, returnWitnessMap, reverted, revertReason } = await (async () => {
     try {
       const result = await acvm(await AcirSimulator.getSolver(), acir, initialWitness, acvmCallback);
       return {
         partialWitness: result.partialWitness,
+        returnWitnessMap: result.returnWitness,
         reverted: false,
         revertReason: undefined,
       };
@@ -121,6 +121,7 @@ async function executePublicFunctionAcvm(
       } else {
         return {
           partialWitness: undefined,
+          returnWitnessMap: undefined,
           reverted: true,
           revertReason: createSimulationError(ee),
         };
@@ -150,6 +151,7 @@ async function executePublicFunctionAcvm(
       unencryptedLogs: UnencryptedFunctionL2Logs.empty(),
       reverted,
       revertReason,
+      gasLeft: Gas.empty(),
     };
   }
 
@@ -157,9 +159,9 @@ async function executePublicFunctionAcvm(
     throw new Error('No partial witness returned from ACVM');
   }
 
-  const returnWitness = extractReturnWitness(acir, partialWitness);
+  const returnWitness = witnessMapToFields(returnWitnessMap);
   const {
-    returnValues,
+    returnsHash,
     nullifierReadRequests: nullifierReadRequestsPadded,
     nullifierNonExistentReadRequests: nullifierNonExistentReadRequestsPadded,
     newL2ToL1Msgs,
@@ -168,6 +170,7 @@ async function executePublicFunctionAcvm(
     startSideEffectCounter,
     endSideEffectCounter,
   } = PublicCircuitPublicInputs.fromFields(returnWitness);
+  const returnValues = await context.unpackReturns(returnsHash);
 
   const nullifierReadRequests = nullifierReadRequestsPadded.filter(v => !v.isEmpty());
   const nullifierNonExistentReadRequests = nullifierNonExistentReadRequestsPadded.filter(v => !v.isEmpty());
@@ -190,6 +193,7 @@ async function executePublicFunctionAcvm(
 
   const nestedExecutions = context.getNestedExecutions();
   const unencryptedLogs = context.getUnencryptedLogs();
+  const gasLeft = context.execution.callContext.gasLeft; // No gas metering for ACVM
 
   return {
     execution,
@@ -207,6 +211,7 @@ async function executePublicFunctionAcvm(
     unencryptedLogs,
     reverted: false,
     revertReason: undefined,
+    gasLeft,
   };
 }
 
@@ -235,7 +240,7 @@ export class PublicExecutor {
   ): Promise<PublicExecutionResult> {
     // Functions can request to pack arguments before calling other functions.
     // We use this cache to hold the packed arguments.
-    const packedArgs = PackedArgsCache.create([]);
+    const packedArgs = PackedValuesCache.create([]);
 
     const context = new PublicExecutionContext(
       execution,

package/src/public/hints_builder.ts

@@ -0,0 +1,119 @@
+import { MerkleTreeId } from '@aztec/circuit-types';
+import {
+  type Fr,
+  MAX_NEW_NULLIFIERS_PER_TX,
+  type MAX_NULLIFIER_NON_EXISTENT_READ_REQUESTS_PER_TX,
+  type MAX_NULLIFIER_READ_REQUESTS_PER_TX,
+  MAX_PUBLIC_DATA_READS_PER_TX,
+  MembershipWitness,
+  NULLIFIER_TREE_HEIGHT,
+  PUBLIC_DATA_TREE_HEIGHT,
+  type PublicDataRead,
+  PublicDataTreeLeafPreimage,
+  type ReadRequestContext,
+  type SideEffectLinkedToNoteHash,
+  buildNullifierNonExistentReadRequestHints,
+  buildNullifierReadRequestHints,
+  mergeAccumulatedData,
+} from '@aztec/circuits.js';
+import { makeTuple } from '@aztec/foundation/array';
+import { type Tuple } from '@aztec/foundation/serialize';
+import { type MerkleTreeOperations } from '@aztec/world-state';
+
+export class HintsBuilder {
+  constructor(private db: MerkleTreeOperations) {}
+
+  getNullifierReadRequestHints(
+    nullifierReadRequests: Tuple<ReadRequestContext, typeof MAX_NULLIFIER_READ_REQUESTS_PER_TX>,
+    nullifiersNonRevertible: Tuple<SideEffectLinkedToNoteHash, typeof MAX_NEW_NULLIFIERS_PER_TX>,
+    nullifiersRevertible: Tuple<SideEffectLinkedToNoteHash, typeof MAX_NEW_NULLIFIERS_PER_TX>,
+  ) {
+    return buildNullifierReadRequestHints(
+      this,
+      nullifierReadRequests,
+      mergeAccumulatedData(MAX_NEW_NULLIFIERS_PER_TX, nullifiersNonRevertible, nullifiersRevertible),
+    );
+  }
+
+  getNullifierNonExistentReadRequestHints(
+    nullifierNonExistentReadRequests: Tuple<ReadRequestContext, typeof MAX_NULLIFIER_NON_EXISTENT_READ_REQUESTS_PER_TX>,
+    nullifiersNonRevertible: Tuple<SideEffectLinkedToNoteHash, typeof MAX_NEW_NULLIFIERS_PER_TX>,
+    nullifiersRevertible: Tuple<SideEffectLinkedToNoteHash, typeof MAX_NEW_NULLIFIERS_PER_TX>,
+  ) {
+    const pendingNullifiers = mergeAccumulatedData(
+      MAX_NEW_NULLIFIERS_PER_TX,
+      nullifiersNonRevertible,
+      nullifiersRevertible,
+    );
+    return buildNullifierNonExistentReadRequestHints(this, nullifierNonExistentReadRequests, pendingNullifiers);
+  }
+
+  async getNullifierMembershipWitness(nullifier: Fr) {
+    const index = await this.db.findLeafIndex(MerkleTreeId.NULLIFIER_TREE, nullifier.toBuffer());
+    if (index === undefined) {
+      return;
+    }
+
+    return this.getNullifierMembershipWitnessWithPreimage(index);
+  }
+
+  async getLowNullifierMembershipWitness(nullifier: Fr) {
+    const res = await this.db.getPreviousValueIndex(MerkleTreeId.NULLIFIER_TREE, nullifier.toBigInt());
+    if (res === undefined) {
+      throw new Error(`Cannot find the low leaf for nullifier ${nullifier.toBigInt()}.`);
+    }
+
+    const { index, alreadyPresent } = res;
+    if (alreadyPresent) {
+      throw new Error(`Nullifier ${nullifier.toBigInt()} already exists in the tree.`);
+    }
+
+    return this.getNullifierMembershipWitnessWithPreimage(index);
+  }
+
+  private async getNullifierMembershipWitnessWithPreimage(index: bigint) {
+    const siblingPath = await this.db.getSiblingPath<typeof NULLIFIER_TREE_HEIGHT>(MerkleTreeId.NULLIFIER_TREE, index);
+    const membershipWitness = new MembershipWitness(
+      NULLIFIER_TREE_HEIGHT,
+      index,
+      siblingPath.toTuple<typeof NULLIFIER_TREE_HEIGHT>(),
+    );
+
+    const leafPreimage = await this.db.getLeafPreimage(MerkleTreeId.NULLIFIER_TREE, index);
+    if (!leafPreimage) {
+      throw new Error(`Cannot find the leaf preimage at index ${index}.`);
+    }
+
+    return { membershipWitness, leafPreimage };
+  }
+
+  async getPublicDataReadsInfo(publicDataReads: PublicDataRead[]) {
+    const newPublicDataReadsWitnesses: Tuple<
+      MembershipWitness<typeof PUBLIC_DATA_TREE_HEIGHT>,
+      typeof MAX_PUBLIC_DATA_READS_PER_TX
+    > = makeTuple(MAX_PUBLIC_DATA_READS_PER_TX, () => MembershipWitness.empty(PUBLIC_DATA_TREE_HEIGHT, 0n));
+
+    const newPublicDataReadsPreimages: Tuple<PublicDataTreeLeafPreimage, typeof MAX_PUBLIC_DATA_READS_PER_TX> =
+      makeTuple(MAX_PUBLIC_DATA_READS_PER_TX, () => PublicDataTreeLeafPreimage.empty());
+
+    for (const i in publicDataReads) {
+      const leafSlot = publicDataReads[i].leafSlot.value;
+      const lowLeafResult = await this.db.getPreviousValueIndex(MerkleTreeId.PUBLIC_DATA_TREE, leafSlot);
+      if (!lowLeafResult) {
+        throw new Error(`Public data tree should have one initial leaf`);
+      }
+      const preimage = await this.db.getLeafPreimage(MerkleTreeId.PUBLIC_DATA_TREE, lowLeafResult.index);
+      const path = await this.db.getSiblingPath(MerkleTreeId.PUBLIC_DATA_TREE, lowLeafResult.index);
+      newPublicDataReadsWitnesses[i] = new MembershipWitness(
+        PUBLIC_DATA_TREE_HEIGHT,
+        BigInt(lowLeafResult.index),
+        path.toTuple<typeof PUBLIC_DATA_TREE_HEIGHT>(),
+      );
+      newPublicDataReadsPreimages[i] = preimage! as PublicDataTreeLeafPreimage;
+    }
+    return {
+      newPublicDataReadsWitnesses,
+      newPublicDataReadsPreimages,
+    };
+  }
+}

package/src/public/index.ts

@@ -7,3 +7,8 @@ export {
   collectPublicDataUpdateRequests,
 } from './execution.js';
 export { PublicExecutor } from './executor.js';
+export { PublicProcessor, PublicProcessorFactory } from './public_processor.js';
+export * from './public_executor.js';
+export * from './abstract_phase_manager.js';
+export * from './public_kernel_circuit_simulator.js';
+export * from './public_kernel.js';

package/src/public/phase_manager_factory.ts

@@ -0,0 +1,126 @@
+import { type Tx } from '@aztec/circuit-types';
+import { type GlobalVariables, type Header, type PublicKernelCircuitPublicInputs } from '@aztec/circuits.js';
+import { type PublicExecutor, type PublicStateDB } from '@aztec/simulator';
+import { type MerkleTreeOperations } from '@aztec/world-state';
+
+import { type AbstractPhaseManager, PublicKernelPhase } from './abstract_phase_manager.js';
+import { AppLogicPhaseManager } from './app_logic_phase_manager.js';
+import { type ContractsDataSourcePublicDB } from './public_executor.js';
+import { type PublicKernelCircuitSimulator } from './public_kernel_circuit_simulator.js';
+import { SetupPhaseManager } from './setup_phase_manager.js';
+import { TailPhaseManager } from './tail_phase_manager.js';
+import { TeardownPhaseManager } from './teardown_phase_manager.js';
+
+export class PhaseDidNotChangeError extends Error {
+  constructor(phase: PublicKernelPhase) {
+    super(`Tried to advance the phase from [${phase}] when the circuit still needs [${phase}]`);
+  }
+}
+
+export class CannotTransitionToSetupError extends Error {
+  constructor() {
+    super('Cannot transition to setup phase');
+  }
+}
+
+export class PhaseManagerFactory {
+  public static phaseFromTx(
+    tx: Tx,
+    db: MerkleTreeOperations,
+    publicExecutor: PublicExecutor,
+    publicKernel: PublicKernelCircuitSimulator,
+    globalVariables: GlobalVariables,
+    historicalHeader: Header,
+    publicContractsDB: ContractsDataSourcePublicDB,
+    publicStateDB: PublicStateDB,
+  ): AbstractPhaseManager | undefined {
+    const data = tx.data.forPublic!;
+    if (data.needsSetup) {
+      return new SetupPhaseManager(
+        db,
+        publicExecutor,
+        publicKernel,
+        globalVariables,
+        historicalHeader,
+        publicContractsDB,
+        publicStateDB,
+      );
+    } else if (data.needsAppLogic) {
+      return new AppLogicPhaseManager(
+        db,
+        publicExecutor,
+        publicKernel,
+        globalVariables,
+        historicalHeader,
+        publicContractsDB,
+        publicStateDB,
+      );
+    } else if (data.needsTeardown) {
+      return new TeardownPhaseManager(
+        db,
+        publicExecutor,
+        publicKernel,
+        globalVariables,
+        historicalHeader,
+        publicContractsDB,
+        publicStateDB,
+      );
+    } else {
+      return undefined;
+    }
+  }
+
+  public static phaseFromOutput(
+    output: PublicKernelCircuitPublicInputs,
+    currentPhaseManager: AbstractPhaseManager,
+    db: MerkleTreeOperations,
+    publicExecutor: PublicExecutor,
+    publicKernel: PublicKernelCircuitSimulator,
+    globalVariables: GlobalVariables,
+    historicalHeader: Header,
+    publicContractsDB: ContractsDataSourcePublicDB,
+    publicStateDB: PublicStateDB,
+  ): AbstractPhaseManager | undefined {
+    if (output.needsSetup) {
+      throw new CannotTransitionToSetupError();
+    } else if (output.needsAppLogic) {
+      if (currentPhaseManager.phase === PublicKernelPhase.APP_LOGIC) {
+        throw new PhaseDidNotChangeError(currentPhaseManager.phase);
+      }
+      return new AppLogicPhaseManager(
+        db,
+        publicExecutor,
+        publicKernel,
+        globalVariables,
+        historicalHeader,
+        publicContractsDB,
+        publicStateDB,
+      );
+    } else if (output.needsTeardown) {
+      if (currentPhaseManager.phase === PublicKernelPhase.TEARDOWN) {
+        throw new PhaseDidNotChangeError(currentPhaseManager.phase);
+      }
+      return new TeardownPhaseManager(
+        db,
+        publicExecutor,
+        publicKernel,
+        globalVariables,
+        historicalHeader,
+        publicContractsDB,
+        publicStateDB,
+      );
+    } else if (currentPhaseManager.phase !== PublicKernelPhase.TAIL) {
+      return new TailPhaseManager(
+        db,
+        publicExecutor,
+        publicKernel,
+        globalVariables,
+        historicalHeader,
+        publicContractsDB,
+        publicStateDB,
+      );
+    } else {
+      return undefined;
+    }
+  }
+}

package/src/public/public_execution_context.ts

@@ -1,8 +1,4 @@
-import {
-  type NullifierMembershipWitness,
-  UnencryptedFunctionL2Logs,
-  type UnencryptedL2Log,
-} from '@aztec/circuit-types';
+import { UnencryptedFunctionL2Logs, type UnencryptedL2Log } from '@aztec/circuit-types';
 import {
   CallContext,
   FunctionData,
@@ -17,7 +13,7 @@ import { createDebugLogger } from '@aztec/foundation/log';
 import { type ContractInstance } from '@aztec/types/contracts';
 
 import { TypedOracle, toACVMWitness } from '../acvm/index.js';
-import { type PackedArgsCache, type SideEffectCounter } from '../common/index.js';
+import { type PackedValuesCache, type SideEffectCounter } from '../common/index.js';
 import { type CommitmentsDB, type PublicContractsDB, type PublicStateDB } from './db.js';
 import { type PublicExecution, type PublicExecutionResult, checkValidStaticCall } from './execution.js';
 import { executePublicFunction } from './executor.js';
@@ -38,7 +34,7 @@ export class PublicExecutionContext extends TypedOracle {
     public readonly execution: PublicExecution,
     public readonly header: Header,
     public readonly globalVariables: GlobalVariables,
-    private readonly packedArgsCache: PackedArgsCache,
+    private readonly packedValuesCache: PackedValuesCache,
     private readonly sideEffectCounter: SideEffectCounter,
     public readonly stateDb: PublicStateDB,
     public readonly contractsDb: PublicContractsDB,
@@ -98,7 +94,23 @@ export class PublicExecutionContext extends TypedOracle {
    * @param args - Arguments to pack
    */
   public packArguments(args: Fr[]): Promise<Fr> {
-    return Promise.resolve(this.packedArgsCache.pack(args));
+    return Promise.resolve(this.packedValuesCache.pack(args));
+  }
+
+  /**
+   * Pack the given returns.
+   * @param returns - Returns to pack
+   */
+  public packReturns(returns: Fr[]): Promise<Fr> {
+    return Promise.resolve(this.packedValuesCache.pack(returns));
+  }
+
+  /**
+   * Unpack the given returns.
+   * @param returnsHash - Returns hash to unpack
+   */
+  public unpackReturns(returnsHash: Fr): Promise<Fr[]> {
+    return Promise.resolve(this.packedValuesCache.unpack(returnsHash));
   }
 
   /**
@@ -186,21 +198,25 @@ export class PublicExecutionContext extends TypedOracle {
   ) {
     isStaticCall = isStaticCall || this.execution.callContext.isStaticCall;
 
-    const args = this.packedArgsCache.unpack(argsHash);
+    const args = this.packedValuesCache.unpack(argsHash);
     this.log.verbose(
       `Public function call: addr=${targetContractAddress} selector=${functionSelector} args=${args.join(',')}`,
     );
 
     const portalAddress = (await this.contractsDb.getPortalContractAddress(targetContractAddress)) ?? EthAddress.ZERO;
     const functionData = new FunctionData(functionSelector, /*isPrivate=*/ false);
+    const { transactionFee, gasSettings, gasLeft } = this.execution.callContext;
     const callContext = CallContext.from({
       msgSender: isDelegateCall ? this.execution.callContext.msgSender : this.execution.contractAddress,
       storageContractAddress: isDelegateCall ? this.execution.contractAddress : targetContractAddress,
       portalContractAddress: portalAddress,
       functionSelector,
+      gasLeft, // Propagate the same gas left as when we started since ACVM public functions don't have any metering
       isDelegateCall,
       isStaticCall,
       sideEffectCounter,
+      gasSettings,
+      transactionFee,
     });
 
     const nestedExecution: PublicExecution = {
@@ -214,7 +230,7 @@ export class PublicExecutionContext extends TypedOracle {
       nestedExecution,
       this.header,
       this.globalVariables,
-      this.packedArgsCache,
+      this.packedValuesCache,
       this.sideEffectCounter,
       this.stateDb,
       this.contractsDb,
@@ -240,14 +256,9 @@ export class PublicExecutionContext extends TypedOracle {
     return childExecutionResult.returnValues;
   }
 
-  public async getNullifierMembershipWitness(
-    blockNumber: number,
-    nullifier: Fr,
-  ): Promise<NullifierMembershipWitness | undefined> {
-    if (!this.header.globalVariables.blockNumber.equals(new Fr(blockNumber))) {
-      throw new Error(`Public execution oracle can only access nullifier membership witnesses for the current block`);
-    }
-    return await this.commitmentsDb.getNullifierMembershipWitnessAtLatestBlock(nullifier);
+  public async checkNullifierExists(nullifier: Fr): Promise<boolean> {
+    const witness = await this.commitmentsDb.getNullifierMembershipWitnessAtLatestBlock(nullifier);
+    return !!witness;
   }
 
   public async getContractInstance(address: AztecAddress): Promise<ContractInstance> {