@aztec/pxe 0.23.0 → 0.26.1

package/src/database/pxe_database_test_suite.ts

@@ -0,0 +1,258 @@
+import { NoteFilter, NoteStatus, randomTxHash } from '@aztec/circuit-types';
+import { AztecAddress, CompleteAddress, INITIAL_L2_BLOCK_NUM } from '@aztec/circuits.js';
+import { makeHeader } from '@aztec/circuits.js/testing';
+import { Fr, Point } from '@aztec/foundation/fields';
+import { BenchmarkingContractArtifact } from '@aztec/noir-contracts.js/Benchmarking';
+import { SerializableContractInstance } from '@aztec/types/contracts';
+
+import { NoteDao } from './note_dao.js';
+import { randomNoteDao } from './note_dao.test.js';
+import { PxeDatabase } from './pxe_database.js';
+
+/**
+ * A common test suite for a PXE database.
+ * @param getDatabase - A function that returns a database instance.
+ */
+export function describePxeDatabase(getDatabase: () => PxeDatabase) {
+  let database: PxeDatabase;
+
+  beforeEach(() => {
+    database = getDatabase();
+  });
+
+  describe('Database', () => {
+    describe('auth witnesses', () => {
+      it('stores and retrieves auth witnesses', async () => {
+        const messageHash = Fr.random();
+        const witness = [Fr.random(), Fr.random()];
+
+        await database.addAuthWitness(messageHash, witness);
+        await expect(database.getAuthWitness(messageHash)).resolves.toEqual(witness);
+      });
+
+      it("returns undefined if it doesn't have auth witnesses for the message", async () => {
+        const messageHash = Fr.random();
+        await expect(database.getAuthWitness(messageHash)).resolves.toBeUndefined();
+      });
+
+      it.skip('refuses to overwrite auth witnesses for the same message', async () => {
+        const messageHash = Fr.random();
+        const witness = [Fr.random(), Fr.random()];
+
+        await database.addAuthWitness(messageHash, witness);
+        await expect(database.addAuthWitness(messageHash, witness)).rejects.toThrow();
+      });
+    });
+
+    describe('capsules', () => {
+      it('stores and retrieves capsules', async () => {
+        const capsule = [Fr.random(), Fr.random()];
+
+        await database.addCapsule(capsule);
+        await expect(database.popCapsule()).resolves.toEqual(capsule);
+      });
+
+      it("returns undefined if it doesn't have capsules", async () => {
+        await expect(database.popCapsule()).resolves.toBeUndefined();
+      });
+
+      it('behaves like a stack when storing capsules', async () => {
+        const capsule1 = [Fr.random(), Fr.random()];
+        const capsule2 = [Fr.random(), Fr.random()];
+
+        await database.addCapsule(capsule1);
+        await database.addCapsule(capsule2);
+        await expect(database.popCapsule()).resolves.toEqual(capsule2);
+        await expect(database.popCapsule()).resolves.toEqual(capsule1);
+      });
+    });
+
+    describe('notes', () => {
+      let owners: CompleteAddress[];
+      let contractAddresses: AztecAddress[];
+      let storageSlots: Fr[];
+      let notes: NoteDao[];
+
+      const filteringTests: [() => NoteFilter, () => NoteDao[]][] = [
+        [() => ({}), () => notes],
+
+        [
+          () => ({ contractAddress: contractAddresses[0] }),
+          () => notes.filter(note => note.contractAddress.equals(contractAddresses[0])),
+        ],
+        [() => ({ contractAddress: AztecAddress.random() }), () => []],
+
+        [
+          () => ({ storageSlot: storageSlots[0] }),
+          () => notes.filter(note => note.storageSlot.equals(storageSlots[0])),
+        ],
+        [() => ({ storageSlot: Fr.random() }), () => []],
+
+        [() => ({ txHash: notes[0].txHash }), () => [notes[0]]],
+        [() => ({ txHash: randomTxHash() }), () => []],
+
+        [() => ({ owner: owners[0].address }), () => notes.filter(note => note.publicKey.equals(owners[0].publicKey))],
+
+        [
+          () => ({ contractAddress: contractAddresses[0], storageSlot: storageSlots[0] }),
+          () =>
+            notes.filter(
+              note => note.contractAddress.equals(contractAddresses[0]) && note.storageSlot.equals(storageSlots[0]),
+            ),
+        ],
+        [() => ({ contractAddress: contractAddresses[0], storageSlot: storageSlots[1] }), () => []],
+      ];
+
+      beforeEach(() => {
+        owners = Array.from({ length: 2 }).map(() => CompleteAddress.random());
+        contractAddresses = Array.from({ length: 2 }).map(() => AztecAddress.random());
+        storageSlots = Array.from({ length: 2 }).map(() => Fr.random());
+
+        notes = Array.from({ length: 10 }).map((_, i) =>
+          randomNoteDao({
+            contractAddress: contractAddresses[i % contractAddresses.length],
+            storageSlot: storageSlots[i % storageSlots.length],
+            publicKey: owners[i % owners.length].publicKey,
+            index: BigInt(i),
+          }),
+        );
+      });
+
+      beforeEach(async () => {
+        for (const owner of owners) {
+          await database.addCompleteAddress(owner);
+        }
+      });
+
+      it.each(filteringTests)('stores notes in bulk and retrieves notes', async (getFilter, getExpected) => {
+        await database.addNotes(notes);
+        await expect(database.getNotes(getFilter())).resolves.toEqual(getExpected());
+      });
+
+      it.each(filteringTests)('stores notes one by one and retrieves notes', async (getFilter, getExpected) => {
+        for (const note of notes) {
+          await database.addNote(note);
+        }
+        await expect(database.getNotes(getFilter())).resolves.toEqual(getExpected());
+      });
+
+      it.each(filteringTests)('retrieves nullified notes', async (getFilter, getExpected) => {
+        await database.addNotes(notes);
+
+        // Nullify all notes and use the same filter as other test cases
+        for (const owner of owners) {
+          const notesToNullify = notes.filter(note => note.publicKey.equals(owner.publicKey));
+          const nullifiers = notesToNullify.map(note => note.siloedNullifier);
+          await expect(database.removeNullifiedNotes(nullifiers, owner.publicKey)).resolves.toEqual(notesToNullify);
+        }
+
+        await expect(database.getNotes({ ...getFilter(), status: NoteStatus.ACTIVE_OR_NULLIFIED })).resolves.toEqual(
+          getExpected(),
+        );
+      });
+
+      it('skips nullified notes by default or when requesting active', async () => {
+        await database.addNotes(notes);
+
+        const notesToNullify = notes.filter(note => note.publicKey.equals(owners[0].publicKey));
+        const nullifiers = notesToNullify.map(note => note.siloedNullifier);
+        await expect(database.removeNullifiedNotes(nullifiers, notesToNullify[0].publicKey)).resolves.toEqual(
+          notesToNullify,
+        );
+
+        const actualNotesWithDefault = await database.getNotes({});
+        const actualNotesWithActive = await database.getNotes({ status: NoteStatus.ACTIVE });
+
+        expect(actualNotesWithDefault).toEqual(actualNotesWithActive);
+        expect(actualNotesWithActive).toEqual(notes.filter(note => !notesToNullify.includes(note)));
+      });
+
+      it('returns active and nullified notes when requesting either', async () => {
+        await database.addNotes(notes);
+
+        const notesToNullify = notes.filter(note => note.publicKey.equals(owners[0].publicKey));
+        const nullifiers = notesToNullify.map(note => note.siloedNullifier);
+        await expect(database.removeNullifiedNotes(nullifiers, notesToNullify[0].publicKey)).resolves.toEqual(
+          notesToNullify,
+        );
+
+        const result = await database.getNotes({
+          status: NoteStatus.ACTIVE_OR_NULLIFIED,
+        });
+
+        // We have to compare the sorted arrays since the database does not return the same order as when originally
+        // inserted combining active and nullified results.
+        expect(result.sort()).toEqual([...notes].sort());
+      });
+    });
+
+    describe('block header', () => {
+      it('stores and retrieves the block header', async () => {
+        const header = makeHeader(Math.floor(Math.random() * 1000), INITIAL_L2_BLOCK_NUM);
+
+        await database.setHeader(header);
+        expect(database.getHeader()).toEqual(header);
+      });
+
+      it('rejects getting header if no block set', () => {
+        expect(() => database.getHeader()).toThrow();
+      });
+    });
+
+    describe('addresses', () => {
+      it('stores and retrieves addresses', async () => {
+        const address = CompleteAddress.random();
+        await expect(database.addCompleteAddress(address)).resolves.toBe(true);
+        await expect(database.getCompleteAddress(address.address)).resolves.toEqual(address);
+      });
+
+      it('silently ignores an address it already knows about', async () => {
+        const address = CompleteAddress.random();
+        await expect(database.addCompleteAddress(address)).resolves.toBe(true);
+        await expect(database.addCompleteAddress(address)).resolves.toBe(false);
+      });
+
+      it.skip('refuses to overwrite an address with a different public key', async () => {
+        const address = CompleteAddress.random();
+        const otherAddress = new CompleteAddress(address.address, Point.random(), address.partialAddress);
+
+        await database.addCompleteAddress(address);
+        await expect(database.addCompleteAddress(otherAddress)).rejects.toThrow();
+      });
+
+      it('returns all addresses', async () => {
+        const addresses = Array.from({ length: 10 }).map(() => CompleteAddress.random());
+        for (const address of addresses) {
+          await database.addCompleteAddress(address);
+        }
+
+        const result = await database.getCompleteAddresses();
+        expect(result).toEqual(expect.arrayContaining(addresses));
+      });
+
+      it("returns an empty array if it doesn't have addresses", async () => {
+        expect(await database.getCompleteAddresses()).toEqual([]);
+      });
+
+      it("returns undefined if it doesn't have an address", async () => {
+        expect(await database.getCompleteAddress(CompleteAddress.random().address)).toBeUndefined();
+      });
+    });
+
+    describe('contracts', () => {
+      it('stores a contract artifact', async () => {
+        const artifact = BenchmarkingContractArtifact;
+        const id = Fr.random();
+        await database.addContractArtifact(id, artifact);
+        await expect(database.getContractArtifact(id)).resolves.toEqual(artifact);
+      });
+
+      it('stores a contract instance', async () => {
+        const address = AztecAddress.random();
+        const instance = SerializableContractInstance.random().withAddress(address);
+        await database.addContractInstance(instance);
+        await expect(database.getContractInstance(address)).resolves.toEqual(instance);
+      });
+    });
+  });
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export * from './pxe_service/index.js';
+export * from './pxe_http/index.js';
+export * from './config/index.js';
+
+export { Tx, TxHash } from '@aztec/circuit-types';
+
+export { TxRequest, PartialAddress } from '@aztec/circuits.js';
+export * from '@aztec/foundation/fields';
+export * from '@aztec/foundation/eth-address';
+export * from '@aztec/foundation/aztec-address';
+export * from '@aztec/key-store';

package/src/kernel_oracle/index.ts

@@ -0,0 +1,65 @@
+import { AztecNode, KeyStore } from '@aztec/circuit-types';
+import {
+  AztecAddress,
+  Fr,
+  FunctionSelector,
+  MembershipWitness,
+  NOTE_HASH_TREE_HEIGHT,
+  Point,
+  computeContractClassIdPreimage,
+  computeSaltedInitializationHash,
+} from '@aztec/circuits.js';
+import { Tuple } from '@aztec/foundation/serialize';
+
+import { ContractDataOracle } from '../contract_data_oracle/index.js';
+import { ProvingDataOracle } from './../kernel_prover/proving_data_oracle.js';
+
+/**
+ * A data oracle that provides information needed for simulating a transaction.
+ */
+export class KernelOracle implements ProvingDataOracle {
+  constructor(private contractDataOracle: ContractDataOracle, private keyStore: KeyStore, private node: AztecNode) {}
+
+  public async getContractAddressPreimage(address: AztecAddress) {
+    const instance = await this.contractDataOracle.getContractInstance(address);
+    return {
+      saltedInitializationHash: computeSaltedInitializationHash(instance),
+      ...instance,
+    };
+  }
+
+  public async getContractClassIdPreimage(contractClassId: Fr) {
+    const contractClass = await this.contractDataOracle.getContractClass(contractClassId);
+    return computeContractClassIdPreimage(contractClass);
+  }
+
+  public async getFunctionMembershipWitness(contractAddress: AztecAddress, selector: FunctionSelector) {
+    return await this.contractDataOracle.getFunctionMembershipWitness(contractAddress, selector);
+  }
+
+  public async getVkMembershipWitness() {
+    return await this.contractDataOracle.getVkMembershipWitness();
+  }
+
+  async getNoteMembershipWitness(leafIndex: bigint): Promise<MembershipWitness<typeof NOTE_HASH_TREE_HEIGHT>> {
+    const path = await this.node.getNoteHashSiblingPath('latest', leafIndex);
+    return new MembershipWitness<typeof NOTE_HASH_TREE_HEIGHT>(
+      path.pathSize,
+      leafIndex,
+      path.toFields() as Tuple<Fr, typeof NOTE_HASH_TREE_HEIGHT>,
+    );
+  }
+
+  getNullifierMembershipWitness(blockNumber: number, nullifier: Fr) {
+    return this.node.getNullifierMembershipWitness(blockNumber, nullifier);
+  }
+
+  async getNoteHashTreeRoot(): Promise<Fr> {
+    const header = await this.node.getHeader();
+    return header.state.partial.noteHashTree.root;
+  }
+
+  public getMasterNullifierSecretKey(nullifierPublicKey: Point) {
+    return this.keyStore.getNullifierSecretKeyFromPublicKey(nullifierPublicKey);
+  }
+}

package/src/kernel_prover/hints_builder.ts

@@ -0,0 +1,170 @@
+import {
+  Fr,
+  GrumpkinScalar,
+  MAX_NEW_NOTE_HASHES_PER_TX,
+  MAX_NEW_NULLIFIERS_PER_TX,
+  MAX_NOTE_HASH_READ_REQUESTS_PER_TX,
+  MAX_NULLIFIER_KEY_VALIDATION_REQUESTS_PER_TX,
+  MAX_NULLIFIER_READ_REQUESTS_PER_TX,
+  MembershipWitness,
+  NULLIFIER_TREE_HEIGHT,
+  NullifierKeyValidationRequestContext,
+  NullifierReadRequestResetHintsBuilder,
+  ReadRequestContext,
+  SideEffect,
+  SideEffectLinkedToNoteHash,
+  SideEffectType,
+} from '@aztec/circuits.js';
+import { siloNullifier } from '@aztec/circuits.js/hash';
+import { makeTuple } from '@aztec/foundation/array';
+import { Tuple } from '@aztec/foundation/serialize';
+
+import { ProvingDataOracle } from './proving_data_oracle.js';
+
+export class HintsBuilder {
+  constructor(private oracle: ProvingDataOracle) {}
+
+  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>];
+  }
+
+  /**
+   * Performs the matching between an array of read request and an array of note hashes. This produces
+   * hints for the private kernel tail circuit to efficiently match a read request with the corresponding
+   * note hash. Several read requests might be pointing to the same note hash. It is therefore valid
+   * to return more than one hint with the same index (contrary to getNullifierHints).
+   *
+   * @param noteHashReadRequests - The array of read requests.
+   * @param noteHashes - The array of note hashes.
+   * @returns An array of hints where each element is the index of the note hash in note hashes array
+   *  corresponding to the read request. In other words we have readRequests[i] == noteHashes[hints[i]].
+   */
+  getNoteHashReadRequestHints(
+    noteHashReadRequests: Tuple<SideEffect, typeof MAX_NOTE_HASH_READ_REQUESTS_PER_TX>,
+    noteHashes: Tuple<SideEffect, typeof MAX_NEW_NOTE_HASHES_PER_TX>,
+  ): Tuple<Fr, typeof MAX_NOTE_HASH_READ_REQUESTS_PER_TX> {
+    const hints = makeTuple(MAX_NOTE_HASH_READ_REQUESTS_PER_TX, Fr.zero);
+    for (let i = 0; i < MAX_NOTE_HASH_READ_REQUESTS_PER_TX && !noteHashReadRequests[i].isEmpty(); i++) {
+      const equalToRR = (cmt: SideEffect) => cmt.value.equals(noteHashReadRequests[i].value);
+      const result = noteHashes.findIndex(equalToRR);
+      if (result == -1) {
+        throw new Error(
+          `The read request at index ${i} ${noteHashReadRequests[i].toString()} does not match to any note hash.`,
+        );
+      } else {
+        hints[i] = new Fr(result);
+      }
+    }
+    return hints;
+  }
+
+  async getNullifierReadRequestResetHints(
+    nullifierReadRequests: Tuple<ReadRequestContext, typeof MAX_NULLIFIER_READ_REQUESTS_PER_TX>,
+    nullifiers: Tuple<SideEffectLinkedToNoteHash, typeof MAX_NEW_NULLIFIERS_PER_TX>,
+  ) {
+    // TODO - Should be comparing un-siloed values and contract addresses.
+    const builder = new NullifierReadRequestResetHintsBuilder();
+    const nullifierIndexMap: Map<bigint, number> = new Map();
+    nullifiers.forEach((n, i) => nullifierIndexMap.set(n.value.toBigInt(), i));
+    const siloedReadRequestValues = nullifierReadRequests.map(r =>
+      r.isEmpty() ? Fr.ZERO : siloNullifier(r.contractAddress, r.value),
+    );
+    for (let i = 0; i < nullifierReadRequests.length; ++i) {
+      const value = siloedReadRequestValues[i];
+      if (value.isZero()) {
+        break;
+      }
+      const pendingValueIndex = nullifierIndexMap.get(value.toBigInt());
+      if (pendingValueIndex !== undefined) {
+        builder.addPendingReadRequest(i, pendingValueIndex);
+      } else {
+        const membershipWitness = await this.oracle.getNullifierMembershipWitness(0, value);
+        if (!membershipWitness) {
+          throw new Error('Read request is reading an unknown nullifier value.');
+        }
+        builder.addSettledReadRequest(
+          i,
+          new MembershipWitness(
+            NULLIFIER_TREE_HEIGHT,
+            membershipWitness.index,
+            membershipWitness.siblingPath.toTuple<typeof NULLIFIER_TREE_HEIGHT>(),
+          ),
+          membershipWitness.leafPreimage,
+        );
+      }
+    }
+    return builder.toHints();
+  }
+
+  /**
+   * Performs the matching between an array of nullified note hashes and an array of note hashes. This produces
+   * hints for the private kernel tail circuit to efficiently match a nullifier with the corresponding
+   * note hash. Note that the same note hash value might appear more than once in the note hashes
+   * (resp. nullified note hashes) array. It is crucial in this case that each hint points to a different index
+   * of the nullified note hashes array. Otherwise, the private kernel will fail to validate.
+   *
+   * @param nullifiedNoteHashes - The array of nullified note hashes.
+   * @param noteHashes - The array of note hashes.
+   * @returns An array of hints where each element is the index of the note hash in note hashes array
+   *  corresponding to the nullified note hash. In other words we have nullifiedNoteHashes[i] == noteHashes[hints[i]].
+   */
+  getNullifierHints(
+    nullifiedNoteHashes: Tuple<Fr, typeof MAX_NEW_NULLIFIERS_PER_TX>,
+    noteHashes: Tuple<SideEffect, typeof MAX_NEW_NOTE_HASHES_PER_TX>,
+  ): Tuple<Fr, typeof MAX_NEW_NULLIFIERS_PER_TX> {
+    const hints = makeTuple(MAX_NEW_NULLIFIERS_PER_TX, Fr.zero);
+    const alreadyUsed = new Set<number>();
+    for (let i = 0; i < MAX_NEW_NULLIFIERS_PER_TX; i++) {
+      if (!nullifiedNoteHashes[i].isZero()) {
+        const result = noteHashes.findIndex(
+          (cmt: SideEffect, index: number) => cmt.value.equals(nullifiedNoteHashes[i]) && !alreadyUsed.has(index),
+        );
+        alreadyUsed.add(result);
+        if (result == -1) {
+          throw new Error(
+            `The nullified note hash at index ${i} with value ${nullifiedNoteHashes[
+              i
+            ].toString()} does not match to any note hash.`,
+          );
+        } else {
+          hints[i] = new Fr(result);
+        }
+      }
+    }
+    return hints;
+  }
+
+  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/index.ts

@@ -0,0 +1,2 @@
+export * from './kernel_prover.js';
+export * from './proving_data_oracle.js';