@aztec/pxe 0.23.0 → 0.26.1

package/src/contract_data_oracle/private_functions_tree.ts

@@ -0,0 +1,127 @@
+import { ContractDao } from '@aztec/circuit-types';
+import {
+  FUNCTION_TREE_HEIGHT,
+  MembershipWitness,
+  computePrivateFunctionLeaf,
+  computePrivateFunctionsTree,
+  getContractClassFromArtifact,
+} from '@aztec/circuits.js';
+import { MerkleTree } from '@aztec/circuits.js/merkle';
+import { FunctionSelector } from '@aztec/foundation/abi';
+import { Fr } from '@aztec/foundation/fields';
+import { assertLength } from '@aztec/foundation/serialize';
+import { ContractClassWithId } from '@aztec/types/contracts';
+
+/**
+ * Represents a Merkle tree of functions for a particular Contract Class.
+ * It manages the construction of the function tree, computes its root, and generates membership witnesses
+ * for constrained functions. This class also enables lookup of specific function artifact using selectors.
+ * It is used in combination with the AztecNode to compute various data for executing private transactions.
+ */
+export class PrivateFunctionsTree {
+  private tree?: MerkleTree;
+  private contractClass?: ContractClassWithId;
+
+  constructor(
+    /**
+     * The contract data object containing the artifact and contract address.
+     * TODO(@spalladino) Replace with contract class sourced from db.
+     */
+    public readonly contract: ContractDao,
+  ) {}
+
+  /**
+   * Retrieve the artifact of a given function.
+   * The function is identified by its selector, which represents a unique identifier for the function's signature.
+   * Throws an error if the function with the provided selector is not found in the contract.
+   *
+   * @param selector - The function selector.
+   * @returns The artifact object containing relevant information about the targeted function.
+   */
+  public getFunctionArtifact(selector: FunctionSelector) {
+    const artifact = this.contract.functions.find(f => f.selector.equals(selector));
+    if (!artifact) {
+      throw new Error(
+        `Unknown function. Selector ${selector.toString()} not found in the artifact of contract ${this.contract.instance.address.toString()}. Expected one of: ${this.contract.functions
+          .map(f => `${f.name} (${f.selector.toString()})`)
+          .join(', ')}`,
+      );
+    }
+    return artifact;
+  }
+
+  /**
+   * Retrieve the bytecode of a function in the contract by its function selector.
+   * The function selector is a unique identifier for each function in a contract.
+   * Throws an error if the function with the given selector is not found in the contract.
+   *
+   * @param selector - The selector of a function to get bytecode for.
+   * @returns The bytecode of the function as a string.
+   */
+  public getBytecode(selector: FunctionSelector) {
+    return this.getFunctionArtifact(selector).bytecode;
+  }
+
+  /**
+   * Calculate and return the root of the function tree for the current contract.
+   * This root is a cryptographic commitment to the set of constrained functions within the contract,
+   * which is used in the Aztec node's proof system. The root will be cached after the first call.
+   *
+   * @returns A promise that resolves to the Fr (finite field element) representation of the function tree root.
+   */
+  public getFunctionTreeRoot() {
+    return this.getTree();
+  }
+
+  /** Returns the contract class object. */
+  public getContractClass() {
+    if (!this.contractClass) {
+      this.contractClass = getContractClassFromArtifact(this.contract);
+    }
+    return this.contractClass;
+  }
+
+  /**
+   * Returns the contract class identifier for the given artifact.
+   */
+  public getContractClassId() {
+    return this.getContractClass().id;
+  }
+
+  /**
+   * Retrieve the membership witness of a function within a contract's function tree.
+   * A membership witness represents the position and authentication path of a target function
+   * in the Merkle tree of constrained functions. It is required to prove the existence of the
+   * function within the contract during execution. Throws if fn does not exist or is not private.
+   *
+   * @param selector - The function selector.
+   * @returns A MembershipWitness instance representing the position and authentication path of the function in the function tree.
+   */
+  public getFunctionMembershipWitness(
+    selector: FunctionSelector,
+  ): Promise<MembershipWitness<typeof FUNCTION_TREE_HEIGHT>> {
+    const fn = this.getContractClass().privateFunctions.find(f => f.selector.equals(selector));
+    if (!fn) {
+      throw new Error(`Private function with selector ${selector.toString()} not found in contract class.`);
+    }
+
+    const leaf = computePrivateFunctionLeaf(fn);
+    const index = this.getTree().getIndex(leaf);
+    const path = this.getTree().getSiblingPath(index);
+    return Promise.resolve(
+      new MembershipWitness<typeof FUNCTION_TREE_HEIGHT>(
+        FUNCTION_TREE_HEIGHT,
+        BigInt(index),
+        assertLength(path.map(Fr.fromBuffer), FUNCTION_TREE_HEIGHT),
+      ),
+    );
+  }
+
+  private getTree() {
+    if (!this.tree) {
+      const fns = this.getContractClass().privateFunctions;
+      this.tree = computePrivateFunctionsTree(fns);
+    }
+    return this.tree;
+  }
+}

package/src/contract_database/index.ts

@@ -0,0 +1 @@
+export * from './memory_contract_database.js';

package/src/contract_database/memory_contract_database.ts

@@ -0,0 +1,58 @@
+import { ContractDao, ContractDatabase } from '@aztec/circuit-types';
+import { FunctionSelector } from '@aztec/circuits.js';
+import { AztecAddress } from '@aztec/foundation/aztec-address';
+import { DebugLogger } from '@aztec/foundation/log';
+
+/**
+ * The MemoryContractDatabase class serves as an in-memory implementation of the ContractDatabase interface.
+ * It allows for storing and retrieving contract data, such as ContractDao objects and associated function bytecodes,
+ * within a contracts array. This class is particularly useful for testing and development purposes where a
+ * persistent storage may not be required.
+ */
+export class MemoryContractDatabase implements ContractDatabase {
+  private contracts: ContractDao[] = [];
+
+  constructor(protected log: DebugLogger) {}
+
+  /**
+   * Adds a new ContractDao instance to the memory-based contract database.
+   * The function stores the contract in an array and returns a resolved promise indicating successful addition.
+   *
+   * @param contract - The ContractDao instance to be added to the memory database.
+   * @returns A Promise that resolves when the contract is successfully added.
+   */
+  public addContract(contract: ContractDao) {
+    this.log(`Adding contract ${contract.instance.address.toString()}`);
+    this.contracts.push(contract);
+    return Promise.resolve();
+  }
+
+  /**
+   * Retrieve a ContractDao instance with the specified AztecAddress from the in-memory contracts list.
+   * Returns the first match found or undefined if no contract with the given address is found.
+   *
+   * @param address - The AztecAddress to search for in the stored contracts.
+   * @returns A Promise resolving to the ContractDao instance matching the given address or undefined.
+   */
+  public getContract(address: AztecAddress): Promise<ContractDao | undefined> {
+    return Promise.resolve(this.contracts.find(c => c.instance.address.equals(address)));
+  }
+
+  public getContracts(): Promise<ContractDao[]> {
+    return Promise.resolve(this.contracts);
+  }
+
+  /**
+   * Retrieve the bytecode associated with a given contract address and function selector.
+   * This function searches through the stored contracts to find a matching contract and function,
+   * then returns the corresponding bytecode. If no match is found, it returns undefined.
+   *
+   * @param contractAddress - The AztecAddress representing the contract address to look for.
+   * @param selector - The function selector.
+   * @returns A Promise that resolves to the bytecode of the matching function or undefined if not found.
+   */
+  public async getCode(contractAddress: AztecAddress, selector: FunctionSelector) {
+    const contract = await this.getContract(contractAddress);
+    return contract?.functions.find(f => f.selector.equals(selector))?.bytecode;
+  }
+}

package/src/database/contracts/contract_artifact_db.ts

@@ -0,0 +1,19 @@
+import { ContractArtifact } from '@aztec/foundation/abi';
+import { Fr } from '@aztec/foundation/fields';
+
+/**
+ * PXE database for managing contract artifacts.
+ */
+export interface ContractArtifactDatabase {
+  /**
+   * Adds a new contract artifact to the database or updates an existing one.
+   * @param id - Id of the corresponding contract class.
+   * @param contract - Contract artifact to add.
+   */
+  addContractArtifact(id: Fr, contract: ContractArtifact): Promise<void>;
+  /**
+   * Gets a contract artifact given its resulting contract class id.
+   * @param id - Contract class id for the given artifact.
+   */
+  getContractArtifact(id: Fr): Promise<ContractArtifact | undefined>;
+}

package/src/database/contracts/contract_instance_db.ts

@@ -0,0 +1,18 @@
+import { AztecAddress } from '@aztec/circuits.js';
+import { ContractInstanceWithAddress } from '@aztec/types/contracts';
+
+/**
+ * PXE database for managing contract instances.
+ */
+export interface ContractInstanceDatabase {
+  /**
+   * Adds a new contract to the db or updates an existing one.
+   * @param contract - Contract to insert.
+   */
+  addContractInstance(contract: ContractInstanceWithAddress): Promise<void>;
+  /**
+   * Gets a contract given its address.
+   * @param address - Address of the contract.
+   */
+  getContractInstance(address: AztecAddress): Promise<ContractInstanceWithAddress | undefined>;
+}

package/src/database/deferred_note_dao.ts

@@ -0,0 +1,55 @@
+import { Note, TxHash } from '@aztec/circuit-types';
+import { AztecAddress, Fr, Point, PublicKey, Vector } from '@aztec/circuits.js';
+import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
+
+/**
+ * A note that is intended for us, but we cannot decode it yet because the contract is not yet in our database.
+ *
+ * So keep the state that we need to decode it later.
+ */
+export class DeferredNoteDao {
+  constructor(
+    /** The public key associated with this note */
+    public publicKey: PublicKey,
+    /** The note as emitted from the Noir contract. */
+    public note: Note,
+    /** The contract address this note is created in. */
+    public contractAddress: AztecAddress,
+    /** The specific storage location of the note on the contract. */
+    public storageSlot: Fr,
+    /** The type ID of the note on the contract. */
+    public noteTypeId: Fr,
+    /** The hash of the tx the note was created in. Equal to the first nullifier */
+    public txHash: TxHash,
+    /** New note hashes in this transaction, one of which belongs to this note */
+    public newNoteHashes: Fr[],
+    /** The next available leaf index for the note hash tree for this transaction */
+    public dataStartIndexForTx: number,
+  ) {}
+
+  toBuffer(): Buffer {
+    return serializeToBuffer(
+      this.publicKey.toBuffer(),
+      this.note.toBuffer(),
+      this.contractAddress.toBuffer(),
+      this.storageSlot.toBuffer(),
+      this.noteTypeId.toBuffer(),
+      this.txHash.toBuffer(),
+      new Vector(this.newNoteHashes),
+      this.dataStartIndexForTx,
+    );
+  }
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    return new DeferredNoteDao(
+      reader.readObject(Point),
+      reader.readObject(Note),
+      reader.readObject(AztecAddress),
+      reader.readObject(Fr),
+      reader.readObject(Fr),
+      reader.readObject(TxHash),
+      reader.readVector(Fr),
+      reader.readNumber(),
+    );
+  }
+}

package/src/database/index.ts

@@ -0,0 +1 @@
+export * from './pxe_database.js';