@aztec/pxe 0.22.0 → 0.24.0

package/src/kernel_prover/kernel_prover.ts

@@ -0,0 +1,388 @@
+import {
+  AztecAddress,
+  CallRequest,
+  Fr,
+  GrumpkinScalar,
+  MAX_NEW_COMMITMENTS_PER_TX,
+  MAX_NEW_NULLIFIERS_PER_TX,
+  MAX_NULLIFIER_KEY_VALIDATION_REQUESTS_PER_TX,
+  MAX_PRIVATE_CALL_STACK_LENGTH_PER_CALL,
+  MAX_PUBLIC_CALL_STACK_LENGTH_PER_CALL,
+  MAX_READ_REQUESTS_PER_CALL,
+  MAX_READ_REQUESTS_PER_TX,
+  NullifierKeyValidationRequestContext,
+  PrivateCallData,
+  PrivateKernelInitCircuitPrivateInputs,
+  PrivateKernelInnerCircuitPrivateInputs,
+  PrivateKernelInnerCircuitPublicInputs,
+  PrivateKernelInnerData,
+  PrivateKernelTailCircuitPrivateInputs,
+  ReadRequestMembershipWitness,
+  SideEffect,
+  SideEffectLinkedToNoteHash,
+  SideEffectType,
+  TxRequest,
+  VK_TREE_HEIGHT,
+  VerificationKey,
+  makeEmptyProof,
+} from '@aztec/circuits.js';
+import { makeTuple } from '@aztec/foundation/array';
+import { padArrayEnd } from '@aztec/foundation/collection';
+import { Tuple, assertLength, mapTuple } from '@aztec/foundation/serialize';
+import { pushTestData } from '@aztec/foundation/testing';
+import { ExecutionResult, NoteAndSlot } from '@aztec/simulator';
+
+import { KernelProofCreator, ProofCreator, ProofOutput, ProofOutputFinal } from './proof_creator.js';
+import { ProvingDataOracle } from './proving_data_oracle.js';
+
+/**
+ * Represents an output note data object.
+ * Contains the contract address, new note data and commitment for the note,
+ * resulting from the execution of a transaction in the Aztec network.
+ */
+export interface OutputNoteData {
+  /**
+   * The address of the contract the note was created in.
+   */
+  contractAddress: AztecAddress;
+  /**
+   * The encrypted note data for an output note.
+   */
+  data: NoteAndSlot;
+  /**
+   * The unique value representing the note.
+   */
+  commitment: Fr;
+}
+
+/**
+ * Represents the output data of the Kernel Prover.
+ * Provides information about the newly created notes, along with the public inputs and proof.
+ */
+export interface KernelProverOutput extends ProofOutputFinal {
+  /**
+   * An array of output notes containing the contract address, note data, and commitment for each new note.
+   */
+  outputNotes: OutputNoteData[];
+}
+
+/**
+ * The KernelProver class is responsible for generating kernel proofs.
+ * It takes a transaction request, its signature, and the simulation result as inputs, and outputs a proof
+ * along with output notes. The class interacts with a ProvingDataOracle to fetch membership witnesses and
+ * constructs private call data based on the execution results.
+ */
+export class KernelProver {
+  constructor(private oracle: ProvingDataOracle, private proofCreator: ProofCreator = new KernelProofCreator()) {}
+
+  /**
+   * Generate a proof for a given transaction request and execution result.
+   * The function iterates through the nested executions in the execution result, creates private call data,
+   * and generates a proof using the provided ProofCreator instance. It also maintains an index of new notes
+   * created during the execution and returns them as a part of the KernelProverOutput.
+   *
+   * @param txRequest - The authenticated transaction request object.
+   * @param executionResult - The execution result object containing nested executions and preimages.
+   * @returns A Promise that resolves to a KernelProverOutput object containing proof, public inputs, and output notes.
+   */
+  async prove(txRequest: TxRequest, executionResult: ExecutionResult): Promise<KernelProverOutput> {
+    const executionStack = [executionResult];
+    const newNotes: { [commitmentStr: string]: OutputNoteData } = {};
+    let firstIteration = true;
+    let previousVerificationKey = VerificationKey.makeFake();
+
+    let output: ProofOutput = {
+      publicInputs: PrivateKernelInnerCircuitPublicInputs.empty(),
+      proof: makeEmptyProof(),
+    };
+
+    while (executionStack.length) {
+      const currentExecution = executionStack.pop()!;
+      executionStack.push(...currentExecution.nestedExecutions);
+
+      const privateCallRequests = currentExecution.nestedExecutions.map(result => result.callStackItem.toCallRequest());
+      const publicCallRequests = currentExecution.enqueuedPublicFunctionCalls.map(result => result.toCallRequest());
+
+      // Start with the partially filled in read request witnesses from the simulator
+      // and fill the non-transient ones in with sibling paths via oracle.
+      const readRequestMembershipWitnesses = currentExecution.readRequestPartialWitnesses;
+      for (let rr = 0; rr < readRequestMembershipWitnesses.length; rr++) {
+        // Pretty sure this check was forever broken. I made some changes to Fr and this started triggering.
+        // The conditional makes no sense to me anyway.
+        // if (currentExecution.callStackItem.publicInputs.readRequests[rr] == Fr.ZERO) {
+        //   throw new Error(
+        //     'Number of read requests output from Noir circuit does not match number of read request commitment indices output from simulator.',
+        //   );
+        // }
+        const rrWitness = readRequestMembershipWitnesses[rr];
+        if (!rrWitness.isTransient) {
+          // Non-transient reads must contain full membership witness with sibling path from commitment to root.
+          // Get regular membership witness to fill in sibling path in the read request witness.
+          const membershipWitness = await this.oracle.getNoteMembershipWitness(rrWitness.leafIndex.toBigInt());
+          rrWitness.siblingPath = membershipWitness.siblingPath;
+        }
+      }
+
+      // fill in witnesses for remaining/empty read requests
+      readRequestMembershipWitnesses.push(
+        ...Array(MAX_READ_REQUESTS_PER_CALL - readRequestMembershipWitnesses.length)
+          .fill(0)
+          .map(() => ReadRequestMembershipWitness.empty(BigInt(0))),
+      );
+
+      const privateCallData = await this.createPrivateCallData(
+        currentExecution,
+        privateCallRequests,
+        publicCallRequests,
+        readRequestMembershipWitnesses,
+      );
+
+      if (firstIteration) {
+        const proofInput = new PrivateKernelInitCircuitPrivateInputs(txRequest, privateCallData);
+        pushTestData('private-kernel-inputs-init', proofInput);
+        output = await this.proofCreator.createProofInit(proofInput);
+      } else {
+        const previousVkMembershipWitness = await this.oracle.getVkMembershipWitness(previousVerificationKey);
+        const previousKernelData = new PrivateKernelInnerData(
+          output.publicInputs,
+          output.proof,
+          previousVerificationKey,
+          Number(previousVkMembershipWitness.leafIndex),
+          assertLength<Fr, typeof VK_TREE_HEIGHT>(previousVkMembershipWitness.siblingPath, VK_TREE_HEIGHT),
+        );
+        const proofInput = new PrivateKernelInnerCircuitPrivateInputs(previousKernelData, privateCallData);
+        pushTestData('private-kernel-inputs-inner', proofInput);
+        output = await this.proofCreator.createProofInner(proofInput);
+      }
+      (await this.getNewNotes(currentExecution)).forEach(n => {
+        newNotes[n.commitment.toString()] = n;
+      });
+      firstIteration = false;
+      previousVerificationKey = privateCallData.vk;
+    }
+
+    const previousVkMembershipWitness = await this.oracle.getVkMembershipWitness(previousVerificationKey);
+    const previousKernelData = new PrivateKernelInnerData(
+      output.publicInputs,
+      output.proof,
+      previousVerificationKey,
+      Number(previousVkMembershipWitness.leafIndex),
+      assertLength<Fr, typeof VK_TREE_HEIGHT>(previousVkMembershipWitness.siblingPath, VK_TREE_HEIGHT),
+    );
+
+    const [sortedCommitments, sortedCommitmentsIndexes] = this.sortSideEffects<
+      SideEffect,
+      typeof MAX_NEW_COMMITMENTS_PER_TX
+    >(output.publicInputs.end.newCommitments);
+
+    const [sortedNullifiers, sortedNullifiersIndexes] = this.sortSideEffects<
+      SideEffectLinkedToNoteHash,
+      typeof MAX_NEW_NULLIFIERS_PER_TX
+    >(output.publicInputs.end.newNullifiers);
+
+    const readCommitmentHints = this.getReadRequestHints(output.publicInputs.end.readRequests, sortedCommitments);
+
+    const nullifierCommitmentHints = this.getNullifierHints(
+      mapTuple(sortedNullifiers, n => n.noteHash),
+      sortedCommitments,
+    );
+
+    const masterNullifierSecretKeys = await this.getMasterNullifierSecretKeys(
+      output.publicInputs.end.nullifierKeyValidationRequests,
+    );
+
+    const privateInputs = new PrivateKernelTailCircuitPrivateInputs(
+      previousKernelData,
+      sortedCommitments,
+      sortedCommitmentsIndexes,
+      readCommitmentHints,
+      sortedNullifiers,
+      sortedNullifiersIndexes,
+      nullifierCommitmentHints,
+      masterNullifierSecretKeys,
+    );
+    pushTestData('private-kernel-inputs-ordering', privateInputs);
+    const outputFinal = await this.proofCreator.createProofTail(privateInputs);
+
+    // Only return the notes whose commitment is in the commitments of the final proof.
+    const finalNewCommitments = outputFinal.publicInputs.end.newCommitments;
+    const outputNotes = finalNewCommitments.map(c => newNotes[c.value.toString()]).filter(c => !!c);
+
+    return { ...outputFinal, outputNotes };
+  }
+
+  private sortSideEffects<T extends SideEffectType, K extends number>(
+    sideEffects: Tuple<T, K>,
+  ): [Tuple<T, K>, Tuple<number, K>] {
+    const sorted = sideEffects
+      .map((sideEffect, index) => ({ sideEffect, index }))
+      .sort((a, b) => {
+        // Empty ones go to the right
+        if (a.sideEffect.isEmpty()) {
+          return 1;
+        }
+        return Number(a.sideEffect.counter.toBigInt() - b.sideEffect.counter.toBigInt());
+      });
+
+    const originalToSorted = sorted.map(() => 0);
+    sorted.forEach(({ index }, i) => {
+      originalToSorted[index] = i;
+    });
+
+    return [sorted.map(({ sideEffect }) => sideEffect) as Tuple<T, K>, originalToSorted as Tuple<number, K>];
+  }
+
+  private async createPrivateCallData(
+    { callStackItem, vk }: ExecutionResult,
+    privateCallRequests: CallRequest[],
+    publicCallRequests: CallRequest[],
+    readRequestMembershipWitnesses: ReadRequestMembershipWitness[],
+  ) {
+    const { contractAddress, functionData, publicInputs } = callStackItem;
+    const { portalContractAddress } = publicInputs.callContext;
+
+    // Pad with empty items to reach max/const length expected by circuit.
+    const privateCallStack = padArrayEnd(
+      privateCallRequests,
+      CallRequest.empty(),
+      MAX_PRIVATE_CALL_STACK_LENGTH_PER_CALL,
+    );
+    const publicCallStack = padArrayEnd(publicCallRequests, CallRequest.empty(), MAX_PUBLIC_CALL_STACK_LENGTH_PER_CALL);
+
+    const functionLeafMembershipWitness = await this.oracle.getFunctionMembershipWitness(
+      contractAddress,
+      functionData.selector,
+    );
+    const { contractClassId, publicKeysHash, saltedInitializationHash } = await this.oracle.getContractAddressPreimage(
+      contractAddress,
+    );
+    const { artifactHash: contractClassArtifactHash, publicBytecodeCommitment: contractClassPublicBytecodeCommitment } =
+      await this.oracle.getContractClassIdPreimage(contractClassId);
+
+    // TODO(#262): Use real acir hash
+    // const acirHash = keccak(Buffer.from(bytecode, 'hex'));
+    const acirHash = Fr.fromBuffer(Buffer.alloc(32, 0));
+
+    // TODO
+    const proof = makeEmptyProof();
+
+    return PrivateCallData.from({
+      callStackItem,
+      privateCallStack,
+      publicCallStack,
+      proof,
+      vk: VerificationKey.fromBuffer(vk),
+      publicKeysHash,
+      contractClassArtifactHash,
+      contractClassPublicBytecodeCommitment,
+      saltedInitializationHash,
+      functionLeafMembershipWitness,
+      readRequestMembershipWitnesses: makeTuple(MAX_READ_REQUESTS_PER_CALL, i => readRequestMembershipWitnesses[i], 0),
+      portalContractAddress: portalContractAddress.toField(),
+      acirHash,
+    });
+  }
+
+  /**
+   * Retrieves the new output notes for a given execution result.
+   * The function maps over the new notes and associates them with their corresponding
+   * commitments in the public inputs of the execution result. It also includes the contract address
+   * from the call context of the public inputs.
+   *
+   * @param executionResult - The execution result object containing notes and public inputs.
+   * @returns An array of OutputNoteData objects, each representing an output note with its associated data.
+   */
+  private async getNewNotes(executionResult: ExecutionResult): Promise<OutputNoteData[]> {
+    const {
+      callStackItem: { publicInputs },
+      newNotes,
+    } = executionResult;
+    const contractAddress = publicInputs.callContext.storageContractAddress;
+    // Assuming that for each new commitment there's an output note added to the execution result.
+    const newCommitments = await this.proofCreator.getSiloedCommitments(publicInputs);
+    return newNotes.map((data, i) => ({
+      contractAddress,
+      data,
+      commitment: newCommitments[i],
+    }));
+  }
+
+  /**
+   * Performs the matching between an array of read request and an array of commitments. This produces
+   * hints for the private kernel ordering circuit to efficiently match a read request with the corresponding
+   * commitment.
+   *
+   * @param readRequests - The array of read requests.
+   * @param commitments - The array of commitments.
+   * @returns An array of hints where each element is the index of the commitment in commitments array
+   *  corresponding to the read request. In other words we have readRequests[i] == commitments[hints[i]].
+   */
+  private getReadRequestHints(
+    readRequests: Tuple<SideEffect, typeof MAX_READ_REQUESTS_PER_TX>,
+    commitments: Tuple<SideEffect, typeof MAX_NEW_COMMITMENTS_PER_TX>,
+  ): Tuple<Fr, typeof MAX_READ_REQUESTS_PER_TX> {
+    const hints = makeTuple(MAX_READ_REQUESTS_PER_TX, Fr.zero);
+    for (let i = 0; i < MAX_READ_REQUESTS_PER_TX && !readRequests[i].isEmpty(); i++) {
+      const equalToRR = (cmt: SideEffect) => cmt.value.equals(readRequests[i].value);
+      const result = commitments.findIndex(equalToRR);
+      if (result == -1) {
+        throw new Error(
+          `The read request at index ${i} with value ${readRequests[i].toString()} does not match to any commitment.`,
+        );
+      } else {
+        hints[i] = new Fr(result);
+      }
+    }
+    return hints;
+  }
+
+  /**
+   *  Performs the matching between an array of nullified commitments and an array of commitments. This produces
+   * hints for the private kernel ordering circuit to efficiently match a nullifier with the corresponding
+   * commitment.
+   *
+   * @param nullifiedCommitments - The array of nullified commitments.
+   * @param commitments - The array of commitments.
+   * @returns An array of hints where each element is the index of the commitment in commitments array
+   *  corresponding to the nullified commitments. In other words we have nullifiedCommitments[i] == commitments[hints[i]].
+   */
+  private getNullifierHints(
+    nullifiedCommitments: Tuple<Fr, typeof MAX_NEW_NULLIFIERS_PER_TX>,
+    commitments: Tuple<SideEffect, typeof MAX_NEW_COMMITMENTS_PER_TX>,
+  ): Tuple<Fr, typeof MAX_NEW_NULLIFIERS_PER_TX> {
+    const hints = makeTuple(MAX_NEW_NULLIFIERS_PER_TX, Fr.zero);
+    for (let i = 0; i < MAX_NEW_NULLIFIERS_PER_TX; i++) {
+      if (!nullifiedCommitments[i].isZero()) {
+        const equalToCommitment = (cmt: SideEffect) => cmt.value.equals(nullifiedCommitments[i]);
+        const result = commitments.findIndex(equalToCommitment);
+        if (result == -1) {
+          throw new Error(
+            `The nullified commitment at index ${i} with value ${nullifiedCommitments[
+              i
+            ].toString()} does not match to any commitment.`,
+          );
+        } else {
+          hints[i] = new Fr(result);
+        }
+      }
+    }
+    return hints;
+  }
+
+  private async getMasterNullifierSecretKeys(
+    nullifierKeyValidationRequests: Tuple<
+      NullifierKeyValidationRequestContext,
+      typeof MAX_NULLIFIER_KEY_VALIDATION_REQUESTS_PER_TX
+    >,
+  ) {
+    const keys = makeTuple(MAX_NULLIFIER_KEY_VALIDATION_REQUESTS_PER_TX, GrumpkinScalar.zero);
+    for (let i = 0; i < nullifierKeyValidationRequests.length; ++i) {
+      const request = nullifierKeyValidationRequests[i];
+      if (request.isEmpty()) {
+        break;
+      }
+      keys[i] = await this.oracle.getMasterNullifierSecretKey(request.publicKey);
+    }
+    return keys;
+  }
+}

package/src/kernel_prover/proof_creator.ts

@@ -0,0 +1,157 @@
+import { CircuitSimulationStats } from '@aztec/circuit-types/stats';
+import {
+  PrivateCircuitPublicInputs,
+  PrivateKernelInitCircuitPrivateInputs,
+  PrivateKernelInnerCircuitPrivateInputs,
+  PrivateKernelInnerCircuitPublicInputs,
+  PrivateKernelTailCircuitPrivateInputs,
+  PrivateKernelTailCircuitPublicInputs,
+  Proof,
+  makeEmptyProof,
+} from '@aztec/circuits.js';
+import { siloCommitment } from '@aztec/circuits.js/abis';
+import { Fr } from '@aztec/foundation/fields';
+import { createDebugLogger } from '@aztec/foundation/log';
+import { elapsed } from '@aztec/foundation/timer';
+import { executeInit, executeInner, executeTail } from '@aztec/noir-protocol-circuits-types';
+
+/**
+ * Represents the output of the proof creation process for init and inner private kernel circuit.
+ * Contains the public inputs required for the init and inner private kernel circuit and the generated proof.
+ */
+export interface ProofOutput {
+  /**
+   * The public inputs required for the proof generation process.
+   */
+  publicInputs: PrivateKernelInnerCircuitPublicInputs;
+  /**
+   * The zk-SNARK proof for the kernel execution.
+   */
+  proof: Proof;
+}
+
+/**
+ * Represents the output of the proof creation process for final ordering private kernel circuit.
+ * Contains the public inputs required for the final ordering private kernel circuit and the generated proof.
+ */
+export interface ProofOutputFinal {
+  /**
+   * The public inputs required for the proof generation process.
+   */
+  publicInputs: PrivateKernelTailCircuitPublicInputs;
+  /**
+   * The zk-SNARK proof for the kernel execution.
+   */
+  proof: Proof;
+}
+
+/**
+ * ProofCreator provides functionality to create and validate proofs, and retrieve
+ * siloed commitments necessary for maintaining transaction privacy and security on the network.
+ */
+export interface ProofCreator {
+  /**
+   * Computes the siloed commitments for a given set of public inputs.
+   *
+   * @param publicInputs - The public inputs containing the contract address and new commitments to be used in generating siloed commitments.
+   * @returns An array of Fr (finite field) elements representing the siloed commitments.
+   */
+  getSiloedCommitments(publicInputs: PrivateCircuitPublicInputs): Promise<Fr[]>;
+
+  /**
+   * Creates a proof output for a given signed transaction request and private call data for the first iteration.
+   *
+   * @param privateKernelInputsInit - The private data structure for the initial iteration.
+   * @returns A Promise resolving to a ProofOutput object containing public inputs and the kernel proof.
+   */
+  createProofInit(privateKernelInputsInit: PrivateKernelInitCircuitPrivateInputs): Promise<ProofOutput>;
+
+  /**
+   * Creates a proof output for a given previous kernel data and private call data for an inner iteration.
+   *
+   * @param privateKernelInputsInner - The private input data structure for the inner iteration.
+   * @returns A Promise resolving to a ProofOutput object containing public inputs and the kernel proof.
+   */
+  createProofInner(privateKernelInputsInner: PrivateKernelInnerCircuitPrivateInputs): Promise<ProofOutput>;
+
+  /**
+   * Creates a proof output based on the last inner kernel iteration kernel data for the final ordering iteration.
+   *
+   * @param privateKernelInputsTail - The private input data structure for the final ordering iteration.
+   * @returns A Promise resolving to a ProofOutput object containing public inputs and the kernel proof.
+   */
+  createProofTail(privateKernelInputsTail: PrivateKernelTailCircuitPrivateInputs): Promise<ProofOutputFinal>;
+}
+
+/**
+ * The KernelProofCreator class is responsible for generating siloed commitments and zero-knowledge proofs
+ * for private kernel circuit. It leverages Barretenberg to perform cryptographic operations and proof creation.
+ * The class provides methods to compute commitments based on the given public inputs and to generate proofs based on
+ * signed transaction requests, previous kernel data, private call data, and a flag indicating whether it's the first
+ * iteration or not.
+ */
+export class KernelProofCreator implements ProofCreator {
+  constructor(private log = createDebugLogger('aztec:kernel_proof_creator')) {}
+
+  public getSiloedCommitments(publicInputs: PrivateCircuitPublicInputs) {
+    const contractAddress = publicInputs.callContext.storageContractAddress;
+
+    return Promise.resolve(
+      publicInputs.newCommitments.map(commitment => siloCommitment(contractAddress, commitment.value)),
+    );
+  }
+
+  public async createProofInit(privateInputs: PrivateKernelInitCircuitPrivateInputs): Promise<ProofOutput> {
+    const [duration, result] = await elapsed(() => executeInit(privateInputs));
+    this.log(`Simulated private kernel init`, {
+      eventName: 'circuit-simulation',
+      circuitName: 'private-kernel-init',
+      duration,
+      inputSize: privateInputs.toBuffer().length,
+      outputSize: result.toBuffer().length,
+    } satisfies CircuitSimulationStats);
+    this.log('Skipping private kernel init proving...');
+    const proof = makeEmptyProof();
+
+    return {
+      publicInputs: result,
+      proof: proof,
+    };
+  }
+
+  public async createProofInner(privateInputs: PrivateKernelInnerCircuitPrivateInputs): Promise<ProofOutput> {
+    const [duration, result] = await elapsed(() => executeInner(privateInputs));
+    this.log(`Simulated private kernel inner`, {
+      eventName: 'circuit-simulation',
+      circuitName: 'private-kernel-inner',
+      duration,
+      inputSize: privateInputs.toBuffer().length,
+      outputSize: result.toBuffer().length,
+    } satisfies CircuitSimulationStats);
+    this.log('Skipping private kernel inner proving...');
+    const proof = makeEmptyProof();
+
+    return {
+      publicInputs: result,
+      proof: proof,
+    };
+  }
+
+  public async createProofTail(privateInputs: PrivateKernelTailCircuitPrivateInputs): Promise<ProofOutputFinal> {
+    const [duration, result] = await elapsed(() => executeTail(privateInputs));
+    this.log(`Simulated private kernel ordering`, {
+      eventName: 'circuit-simulation',
+      circuitName: 'private-kernel-ordering',
+      duration,
+      inputSize: privateInputs.toBuffer().length,
+      outputSize: result.toBuffer().length,
+    } satisfies CircuitSimulationStats);
+    this.log('Skipping private kernel ordering proving...');
+    const proof = makeEmptyProof();
+
+    return {
+      publicInputs: result,
+      proof: proof,
+    };
+  }
+}

package/src/kernel_prover/proving_data_oracle.ts

@@ -0,0 +1,76 @@
+import {
+  FUNCTION_TREE_HEIGHT,
+  Fr,
+  FunctionSelector,
+  GrumpkinPrivateKey,
+  MembershipWitness,
+  NOTE_HASH_TREE_HEIGHT,
+  Point,
+  VK_TREE_HEIGHT,
+  VerificationKey,
+} from '@aztec/circuits.js';
+import { AztecAddress } from '@aztec/foundation/aztec-address';
+
+/**
+ * Provides functionality to fetch membership witnesses for verification keys,
+ * contract addresses, and function selectors in their respective merkle trees.
+ */
+export interface ProvingDataOracle {
+  /** Retrieves the preimage of a contract address from the registered contract instances db. */
+  getContractAddressPreimage(
+    address: AztecAddress,
+  ): Promise<{ saltedInitializationHash: Fr; publicKeysHash: Fr; contractClassId: Fr }>;
+
+  /** Retrieves the preimage of a contract class id from the contract classes db. */
+  getContractClassIdPreimage(
+    contractClassId: Fr,
+  ): Promise<{ artifactHash: Fr; publicBytecodeCommitment: Fr; privateFunctionsRoot: Fr }>;
+
+  /**
+   * Retrieve the function membership witness for the given contract address and function selector.
+   * The function membership witness represents a proof that the function belongs to the specified contract.
+   * Throws an error if the contract address or function selector is unknown.
+   *
+   * @param contractAddress - The contract address.
+   * @param selector - The function selector.
+   * @returns A promise that resolves with the MembershipWitness instance for the specified contract's function.
+   */
+  getFunctionMembershipWitness(
+    contractAddress: AztecAddress,
+    selector: FunctionSelector,
+  ): Promise<MembershipWitness<typeof FUNCTION_TREE_HEIGHT>>;
+
+  /**
+   * Retrieve the membership witness corresponding to a verification key.
+   * This function currently returns a random membership witness of the specified height,
+   * which is a placeholder implementation until a concrete membership witness calculation
+   * is implemented.
+   *
+   * @param vk - The VerificationKey for which the membership witness is needed.
+   * @returns A Promise that resolves to the MembershipWitness instance.
+   */
+  getVkMembershipWitness(vk: VerificationKey): Promise<MembershipWitness<typeof VK_TREE_HEIGHT>>;
+
+  /**
+   * Get the note membership witness for a note in the note hash tree at the given leaf index.
+   *
+   * @param leafIndex - The leaf index of the note in the note hash tree.
+   * @returns the MembershipWitness for the note.
+   */
+  getNoteMembershipWitness(leafIndex: bigint): Promise<MembershipWitness<typeof NOTE_HASH_TREE_HEIGHT>>;
+
+  /**
+   * Get the root of the note hash tree.
+   *
+   * @returns the root of the note hash tree.
+   */
+  getNoteHashTreeRoot(): Promise<Fr>;
+
+  /**
+   * Get the master secret key of the nullifier public key.
+   *
+   * @param nullifierPublicKey - The nullifier public key.
+   * @returns the master nullifier secret key.
+   */
+  getMasterNullifierSecretKey(nullifierPublicKey: Point): Promise<GrumpkinPrivateKey>;
+}

package/src/note_processor/index.ts

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