@aztec/simulator 0.23.0 → 0.26.1

package/src/acvm/oracle/typed_oracle.ts

@@ -0,0 +1,225 @@
+import {
+  CompleteAddress,
+  MerkleTreeId,
+  Note,
+  NoteStatus,
+  NullifierMembershipWitness,
+  PublicDataWitness,
+  PublicKey,
+  SiblingPath,
+  UnencryptedL2Log,
+} from '@aztec/circuit-types';
+import {
+  GrumpkinPrivateKey,
+  Header,
+  L1_TO_L2_MSG_TREE_HEIGHT,
+  PrivateCallStackItem,
+  PublicCallRequest,
+} from '@aztec/circuits.js';
+import { FunctionSelector } from '@aztec/foundation/abi';
+import { AztecAddress } from '@aztec/foundation/aztec-address';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { Fr } from '@aztec/foundation/fields';
+import { ContractInstance } from '@aztec/types/contracts';
+
+/**
+ * A pair of public key and secret key.
+ */
+export interface KeyPair {
+  /**
+   * Public key.
+   */
+  publicKey: PublicKey;
+  /**
+   * Secret Key.
+   */
+  secretKey: GrumpkinPrivateKey;
+}
+
+/**
+ * Information about a note needed during execution.
+ */
+export interface NoteData {
+  /** The note. */
+  note: Note;
+  /** The contract address of the note. */
+  contractAddress: AztecAddress;
+  /** The storage slot of the note. */
+  storageSlot: Fr;
+  /** The nonce of the note. */
+  nonce: Fr;
+  /** The inner note hash of the note. */
+  innerNoteHash: Fr;
+  /** The corresponding nullifier of the note. Undefined for pending notes. */
+  siloedNullifier?: Fr;
+  /** The note's leaf index in the note hash tree. Undefined for pending notes. */
+  index?: bigint;
+}
+
+export class MessageLoadOracleInputs<N extends number> {
+  constructor(
+    /** The index of the message commitment in the merkle tree. */
+    public index: bigint,
+    /** The path in the merkle tree to the message. */
+    public siblingPath: SiblingPath<N>,
+  ) {}
+
+  toFields(): Fr[] {
+    return [new Fr(this.index), ...this.siblingPath.toFields()];
+  }
+}
+
+/**
+ * Oracle with typed parameters and typed return values.
+ * Methods that require read and/or write will have to be implemented based on the context (public, private, or view)
+ * and are unavailable by default.
+ */
+export abstract class TypedOracle {
+  getRandomField(): Fr {
+    return Fr.random();
+  }
+
+  packArguments(_args: Fr[]): Promise<Fr> {
+    throw new Error('Not available.');
+  }
+
+  getNullifierKeyPair(_accountAddress: AztecAddress): Promise<KeyPair> {
+    throw new Error('Not available.');
+  }
+
+  getPublicKeyAndPartialAddress(_address: AztecAddress): Promise<Fr[] | undefined> {
+    throw new Error('Not available.');
+  }
+
+  getContractInstance(_address: AztecAddress): Promise<ContractInstance> {
+    throw new Error('Not available.');
+  }
+
+  getMembershipWitness(_blockNumber: number, _treeId: MerkleTreeId, _leafValue: Fr): Promise<Fr[] | undefined> {
+    throw new Error('Not available.');
+  }
+
+  getSiblingPath(_blockNumber: number, _treeId: MerkleTreeId, _leafIndex: Fr): Promise<Fr[]> {
+    throw new Error('Not available.');
+  }
+
+  getNullifierMembershipWitness(_blockNumber: number, _nullifier: Fr): Promise<NullifierMembershipWitness | undefined> {
+    throw new Error('Not available.');
+  }
+
+  getPublicDataTreeWitness(_blockNumber: number, _leafSlot: Fr): Promise<PublicDataWitness | undefined> {
+    throw new Error('Not available.');
+  }
+
+  getLowNullifierMembershipWitness(
+    _blockNumber: number,
+    _nullifier: Fr,
+  ): Promise<NullifierMembershipWitness | undefined> {
+    throw new Error('Not available.');
+  }
+
+  getHeader(_blockNumber: number): Promise<Header | undefined> {
+    throw new Error('Not available.');
+  }
+
+  getCompleteAddress(_address: AztecAddress): Promise<CompleteAddress> {
+    throw new Error('Not available.');
+  }
+
+  getAuthWitness(_messageHash: Fr): Promise<Fr[] | undefined> {
+    throw new Error('Not available.');
+  }
+
+  popCapsule(): Promise<Fr[]> {
+    throw new Error('Not available.');
+  }
+
+  getNotes(
+    _storageSlot: Fr,
+    _numSelects: number,
+    _selectBy: number[],
+    _selectValues: Fr[],
+    _selectComparators: number[],
+    _sortBy: number[],
+    _sortOrder: number[],
+    _limit: number,
+    _offset: number,
+    _status: NoteStatus,
+  ): Promise<NoteData[]> {
+    throw new Error('Not available.');
+  }
+
+  notifyCreatedNote(_storageSlot: Fr, _noteTypeId: Fr, _note: Fr[], _innerNoteHash: Fr): void {
+    throw new Error('Not available.');
+  }
+
+  notifyNullifiedNote(_innerNullifier: Fr, _innerNoteHash: Fr): Promise<void> {
+    throw new Error('Not available.');
+  }
+
+  checkNullifierExists(_innerNullifier: Fr): Promise<boolean> {
+    throw new Error('Not available.');
+  }
+
+  getL1ToL2MembershipWitness(_entryKey: Fr): Promise<MessageLoadOracleInputs<typeof L1_TO_L2_MSG_TREE_HEIGHT>> {
+    throw new Error('Not available.');
+  }
+
+  getPortalContractAddress(_contractAddress: AztecAddress): Promise<EthAddress> {
+    throw new Error('Not available.');
+  }
+
+  storageRead(_startStorageSlot: Fr, _numberOfElements: number): Promise<Fr[]> {
+    throw new Error('Not available.');
+  }
+
+  storageWrite(_startStorageSlot: Fr, _values: Fr[]): Promise<Fr[]> {
+    throw new Error('Not available.');
+  }
+
+  emitEncryptedLog(
+    _contractAddress: AztecAddress,
+    _storageSlot: Fr,
+    _noteTypeId: Fr,
+    _publicKey: PublicKey,
+    _log: Fr[],
+  ): void {
+    throw new Error('Not available.');
+  }
+
+  emitUnencryptedLog(_log: UnencryptedL2Log): void {
+    throw new Error('Not available.');
+  }
+
+  callPrivateFunction(
+    _targetContractAddress: AztecAddress,
+    _functionSelector: FunctionSelector,
+    _argsHash: Fr,
+    _sideffectCounter: number,
+    _isStaticCall: boolean,
+    _isDelegateCall: boolean,
+  ): Promise<PrivateCallStackItem> {
+    throw new Error('Not available.');
+  }
+
+  callPublicFunction(
+    _targetContractAddress: AztecAddress,
+    _functionSelector: FunctionSelector,
+    _argsHash: Fr,
+    _isStaticCall: boolean,
+    _isDelegateCall: boolean,
+  ): Promise<Fr[]> {
+    throw new Error('Not available.');
+  }
+
+  enqueuePublicFunctionCall(
+    _targetContractAddress: AztecAddress,
+    _functionSelector: FunctionSelector,
+    _argsHash: Fr,
+    _sideffectCounter: number,
+    _isStaticCall: boolean,
+    _isDelegateCall: boolean,
+  ): Promise<PublicCallRequest> {
+    throw new Error('Not available.');
+  }
+}

package/src/acvm/serialize.ts

@@ -0,0 +1,75 @@
+import { PublicCallRequest } 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 { ACVMField } from './acvm_types.js';
+
+/**
+ * Adapts the buffer to the field size.
+ * @param originalBuf - The buffer to adapt.
+ * @returns The adapted buffer.
+ */
+function adaptBufferSize(originalBuf: Buffer) {
+  const buffer = Buffer.alloc(Fr.SIZE_IN_BYTES);
+  if (originalBuf.length > buffer.length) {
+    throw new Error('Buffer does not fit in field');
+  }
+  originalBuf.copy(buffer, buffer.length - originalBuf.length);
+  return buffer;
+}
+
+/**
+ * Converts a value to an ACVM field.
+ * @param value - The value to convert.
+ * @returns The ACVM field.
+ */
+export function toACVMField(
+  value: AztecAddress | EthAddress | Fr | Buffer | boolean | number | bigint | ACVMField,
+): ACVMField {
+  let buffer;
+  if (Buffer.isBuffer(value)) {
+    buffer = value;
+  } else if (typeof value === 'boolean' || typeof value === 'number' || typeof value === 'bigint') {
+    buffer = new Fr(value).toBuffer();
+  } else if (typeof value === 'string') {
+    buffer = Fr.fromString(value).toBuffer();
+  } else {
+    buffer = value.toBuffer();
+  }
+  return `0x${adaptBufferSize(buffer).toString('hex')}`;
+}
+
+// Utilities to write TS classes to ACVM Field arrays
+// In the order that the ACVM expects them
+
+/**
+ * Converts a public call stack item with the request for executing a public function to
+ * a set of ACVM fields accepted by the enqueue_public_function_call_oracle Aztec.nr function.
+ * Note that only the fields related to the request are serialized: those related to the result
+ * are empty since this is just an execution request, so we don't send them to the circuit.
+ * @param item - The public call stack item to serialize to be passed onto Noir.
+ * @returns The fields expected by the enqueue_public_function_call_oracle Aztec.nr function.
+ * TODO(#4380): Nuke this and replace it with PublicCallRequest.toFields()
+ */
+export function toAcvmEnqueuePublicFunctionResult(item: PublicCallRequest): ACVMField[] {
+  return [
+    item.contractAddress.toField(),
+    ...item.functionData.toFields(),
+    ...item.callContext.toFields(),
+    item.getArgsHash(),
+  ].map(toACVMField);
+}
+
+/**
+ * Inserts a list of ACVM fields to a witness.
+ * @param witnessStartIndex - The index where to start inserting the fields.
+ * @param fields - The fields to insert.
+ * @returns The witness.
+ */
+export function toACVMWitness(witnessStartIndex: number, fields: Parameters<typeof toACVMField>[0][]) {
+  return fields.reduce((witness, field, index) => {
+    witness.set(index + witnessStartIndex, toACVMField(field));
+    return witness;
+  }, new Map<number, ACVMField>());
+}

package/src/avm/avm_context.ts

@@ -0,0 +1,63 @@
+import { AztecAddress } from '@aztec/circuits.js';
+import { Fr } from '@aztec/foundation/fields';
+
+import { AvmExecutionEnvironment } from './avm_execution_environment.js';
+import { AvmMachineState } from './avm_machine_state.js';
+import { AvmPersistableStateManager } from './journal/journal.js';
+
+/**
+ * An execution context includes the information necessary to initiate AVM
+ * execution along with all state maintained by the AVM throughout execution.
+ */
+export class AvmContext {
+  /**
+   * Create a new AVM context
+   * @param persistableState - Manages world state and accrued substate during execution - (caching, fetching, tracing)
+   * @param environment - Contains constant variables provided by the kernel
+   * @param machineState - VM state that is modified on an instruction-by-instruction basis
+   * @returns new AvmContext instance
+   */
+  constructor(
+    public persistableState: AvmPersistableStateManager,
+    public environment: AvmExecutionEnvironment,
+    public machineState: AvmMachineState,
+  ) {}
+
+  /**
+   * Prepare a new AVM context that will be ready for an external/nested call
+   * - Fork the world state journal
+   * - Derive a machine state from the current state
+   *   - E.g., gas metering is preserved but pc is reset
+   * - Derive an execution environment from the caller/parent
+   *   - Alter both address and storageAddress
+   *
+   * @param address - The contract instance to initialize a context for
+   * @param calldata - Data/arguments for nested call
+   * @returns new AvmContext instance
+   */
+  public createNestedContractCallContext(address: AztecAddress, calldata: Fr[]): AvmContext {
+    const newExecutionEnvironment = this.environment.deriveEnvironmentForNestedCall(address, calldata);
+    const forkedWorldState = this.persistableState.fork();
+    const machineState = AvmMachineState.fromState(this.machineState);
+    return new AvmContext(forkedWorldState, newExecutionEnvironment, machineState);
+  }
+
+  /**
+   * Prepare a new AVM context that will be ready for an external/nested static call
+   * - Fork the world state journal
+   * - Derive a machine state from the current state
+   *   - E.g., gas metering is preserved but pc is reset
+   * - Derive an execution environment from the caller/parent
+   *   - Alter both address and storageAddress
+   *
+   * @param address - The contract instance to initialize a context for
+   * @param calldata - Data/arguments for nested call
+   * @returns new AvmContext instance
+   */
+  public createNestedContractStaticCallContext(address: AztecAddress, calldata: Fr[]): AvmContext {
+    const newExecutionEnvironment = this.environment.deriveEnvironmentForNestedStaticCall(address, calldata);
+    const forkedWorldState = this.persistableState.fork();
+    const machineState = AvmMachineState.fromState(this.machineState);
+    return new AvmContext(forkedWorldState, newExecutionEnvironment, machineState);
+  }
+}

package/src/avm/avm_execution_environment.ts

@@ -0,0 +1,98 @@
+import { FunctionSelector, GlobalVariables } from '@aztec/circuits.js';
+import { AztecAddress } from '@aztec/foundation/aztec-address';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { Fr } from '@aztec/foundation/fields';
+
+/**
+ * Contains variables that remain constant during AVM execution
+ * These variables are provided by the public kernel circuit
+ */
+// TODO(https://github.com/AztecProtocol/aztec-packages/issues/3992): gas not implemented
+export class AvmExecutionEnvironment {
+  constructor(
+    public readonly address: AztecAddress,
+
+    public readonly storageAddress: AztecAddress,
+
+    public readonly origin: AztecAddress,
+
+    public readonly sender: AztecAddress,
+
+    public readonly portal: EthAddress,
+
+    public readonly feePerL1Gas: Fr,
+
+    public readonly feePerL2Gas: Fr,
+
+    public readonly feePerDaGas: Fr,
+
+    public readonly contractCallDepth: Fr,
+
+    public readonly globals: GlobalVariables,
+
+    public readonly isStaticCall: boolean,
+
+    public readonly isDelegateCall: boolean,
+
+    public readonly calldata: Fr[],
+
+    public readonly temporaryFunctionSelector: FunctionSelector,
+  ) {}
+
+  public deriveEnvironmentForNestedCall(address: AztecAddress, calldata: Fr[]): AvmExecutionEnvironment {
+    return new AvmExecutionEnvironment(
+      /*address=*/ address,
+      /*storageAddress=*/ address,
+      this.origin,
+      this.sender,
+      this.portal,
+      this.feePerL1Gas,
+      this.feePerL2Gas,
+      this.feePerDaGas,
+      this.contractCallDepth,
+      this.globals,
+      this.isStaticCall,
+      this.isDelegateCall,
+      /*calldata=*/ calldata,
+      this.temporaryFunctionSelector,
+    );
+  }
+
+  public deriveEnvironmentForNestedStaticCall(address: AztecAddress, calldata: Fr[]): AvmExecutionEnvironment {
+    return new AvmExecutionEnvironment(
+      /*address=*/ address,
+      /*storageAddress=*/ address,
+      this.origin,
+      this.sender,
+      this.portal,
+      this.feePerL1Gas,
+      this.feePerL2Gas,
+      this.feePerDaGas,
+      this.contractCallDepth,
+      this.globals,
+      /*isStaticCall=*/ true,
+      this.isDelegateCall,
+      /*calldata=*/ calldata,
+      this.temporaryFunctionSelector,
+    );
+  }
+
+  public newDelegateCall(address: AztecAddress, calldata: Fr[]): AvmExecutionEnvironment {
+    return new AvmExecutionEnvironment(
+      /*address=*/ address,
+      this.storageAddress,
+      this.origin,
+      this.sender,
+      this.portal,
+      this.feePerL1Gas,
+      this.feePerL2Gas,
+      this.feePerDaGas,
+      this.contractCallDepth,
+      this.globals,
+      this.isStaticCall,
+      /*isDelegateCall=*/ true,
+      /*calldata=*/ calldata,
+      this.temporaryFunctionSelector,
+    );
+  }
+}

package/src/avm/avm_machine_state.ts

@@ -0,0 +1,93 @@
+import { Fr } from '@aztec/circuits.js';
+
+import { TaggedMemory } from './avm_memory_types.js';
+import { AvmContractCallResults } from './avm_message_call_result.js';
+
+/**
+ * A few fields of machine state are initialized from AVM session inputs or call instruction arguments
+ */
+export type InitialAvmMachineState = {
+  l1GasLeft: number;
+  l2GasLeft: number;
+  daGasLeft: number;
+};
+
+/**
+ * Avm state modified on an instruction-per-instruction basis.
+ */
+export class AvmMachineState {
+  public l1GasLeft: number;
+  /** gas remaining of the gas allocated for a contract call */
+  public l2GasLeft: number;
+  public daGasLeft: number;
+  /** program counter */
+  public pc: number = 0;
+
+  /**
+   * On INTERNALCALL, internal call stack is pushed to with the current pc + 1
+   * On INTERNALRETURN, value is popped from the internal call stack and assigned to the pc.
+   */
+  public internalCallStack: number[] = [];
+
+  /** Memory accessible to user code */
+  public readonly memory: TaggedMemory = new TaggedMemory();
+
+  /**
+   * Signals that execution should end.
+   * AvmContext execution continues executing instructions until the machine state signals "halted"
+   * */
+  public halted: boolean = false;
+  /** Signals that execution has reverted normally (this does not cover exceptional halts) */
+  private reverted: boolean = false;
+  /** Output data must NOT be modified once it is set */
+  private output: Fr[] = [];
+
+  constructor(l1GasLeft: number, l2GasLeft: number, daGasLeft: number) {
+    this.l1GasLeft = l1GasLeft;
+    this.l2GasLeft = l2GasLeft;
+    this.daGasLeft = daGasLeft;
+  }
+
+  public static fromState(state: InitialAvmMachineState): AvmMachineState {
+    return new AvmMachineState(state.l1GasLeft, state.l2GasLeft, state.daGasLeft);
+  }
+
+  /**
+   * Most instructions just increment PC before they complete
+   */
+  public incrementPc() {
+    this.pc++;
+  }
+
+  /**
+   * Halt as successful
+   * Output data must NOT be modified once it is set
+   * @param output
+   */
+  public return(output: Fr[]) {
+    this.halted = true;
+    this.output = output;
+  }
+
+  /**
+   * Halt as reverted
+   * Output data must NOT be modified once it is set
+   * @param output
+   */
+  public revert(output: Fr[]) {
+    this.halted = true;
+    this.reverted = true;
+    this.output = output;
+  }
+
+  /**
+   * Get a summary of execution results for a halted machine state
+   * @returns summary of execution results
+   */
+  public getResults(): AvmContractCallResults {
+    if (!this.halted) {
+      throw new Error('Execution results are not ready! Execution is ongoing.');
+    }
+    return new AvmContractCallResults(this.reverted, this.output);
+  }
+}