@aztec/pxe 0.69.0-devnet → 0.69.1-devnet

package/src/database/{incoming_note_dao.ts → note_dao.ts}

@@ -8,40 +8,57 @@ import { type NoteData } from '@aztec/simulator/acvm';
 import { type NoteInfo } from '../note_decryption_utils/index.js';
 
 /**
- * A note with contextual data which was decrypted as incoming.
+ * A Note Data Access Object, representing a note that was comitted to the note hash tree, holding all of the
+ * information required to use it during execution and manage its state.
  */
-export class IncomingNoteDao implements NoteData {
+export class NoteDao implements NoteData {
   constructor(
-    /** The note as emitted from the Noir contract. */
+    // Note information
+
+    /** The serialized content of the note, as will be returned in the getNotes oracle. */
     public note: Note,
-    /** The contract address this note is created in. */
+    /** The address of the contract that created the note (i.e. the address used by the kernel during siloing). */
     public contractAddress: AztecAddress,
-    /** The specific storage location of the note on the contract. */
+    /**
+     * The storage location of the note. This value is not used for anything in PXE, but we do index by storage slot
+     * since contracts typically make queries based on it.
+     * */
     public storageSlot: Fr,
-    /** The note type identifier for the contract. */
-    public noteTypeId: NoteSelector,
-    /** The hash of the tx the note was created in. */
-    public txHash: TxHash,
-    /** The L2 block number in which the tx with this note was included. */
-    public l2BlockNumber: number,
-    /** The L2 block hash in which the tx with this note was included. */
-    public l2BlockHash: string,
-    /** The nonce of the note. */
+    /** The kernel-provided nonce of the note, required to compute the uniqueNoteHash. */
     public nonce: Fr,
+
+    // Computed values
     /**
-     * A hash of the note. This is customizable by the app circuit.
-     * We can use this value to compute siloedNoteHash and uniqueSiloedNoteHash.
+     * The inner hash (non-unique, non-siloed) of the note. Each contract determines how the note content is hashed. Can
+     * be used alongside contractAddress and nonce to compute the uniqueNoteHash and the siloedNoteHash.
      */
     public noteHash: Fr,
     /**
-     * The nullifier of the note (siloed by contract address).
+     * The nullifier of the note, siloed by contract address.
      * Note: Might be set as 0 if the note was added to PXE as nullified.
      */
     public siloedNullifier: Fr,
-    /** The location of the relevant note in the note hash tree. */
+
+    // Metadata
+    /** The hash of the tx in which this note was created. Knowing the tx hash allows for efficient node queries e.g.
+     *  when searching for txEffects.
+     */
+    public txHash: TxHash,
+    /** The L2 block number in which the tx with this note was included. Used for note management while processing
+     * reorgs.*/
+    public l2BlockNumber: number,
+    /** The L2 block hash in which the tx with this note was included. Used for note management while processing
+     * reorgs.*/
+    public l2BlockHash: string,
+    /** The index of the leaf in the global note hash tree the note is stored at */
     public index: bigint,
-    /** The public key with which the note was encrypted. */
+    /** The public key with which the note content was encrypted during delivery. */
     public addressPoint: PublicKey,
+
+    /** The note type identifier for the contract.
+     * TODO: remove
+     */
+    public noteTypeId: NoteSelector,
   ) {}
 
   static fromPayloadAndNoteInfo(
@@ -54,19 +71,19 @@ export class IncomingNoteDao implements NoteData {
     addressPoint: PublicKey,
   ) {
     const noteHashIndexInTheWholeTree = BigInt(dataStartIndexForTx + noteInfo.noteHashIndex);
-    return new IncomingNoteDao(
+    return new NoteDao(
       note,
       payload.contractAddress,
       payload.storageSlot,
-      payload.noteTypeId,
-      noteInfo.txHash,
-      l2BlockNumber,
-      l2BlockHash,
       noteInfo.nonce,
       noteInfo.noteHash,
       noteInfo.siloedNullifier,
+      noteInfo.txHash,
+      l2BlockNumber,
+      l2BlockHash,
       noteHashIndexInTheWholeTree,
       addressPoint,
+      payload.noteTypeId,
     );
   }
 
@@ -75,15 +92,15 @@ export class IncomingNoteDao implements NoteData {
       this.note,
       this.contractAddress,
       this.storageSlot,
-      this.noteTypeId,
-      this.txHash.buffer,
-      this.l2BlockNumber,
-      Fr.fromHexString(this.l2BlockHash),
       this.nonce,
       this.noteHash,
       this.siloedNullifier,
+      this.txHash,
+      this.l2BlockNumber,
+      Fr.fromHexString(this.l2BlockHash),
       this.index,
       this.addressPoint,
+      this.noteTypeId,
     ]);
   }
 
@@ -93,29 +110,29 @@ export class IncomingNoteDao implements NoteData {
     const note = Note.fromBuffer(reader);
     const contractAddress = AztecAddress.fromBuffer(reader);
     const storageSlot = Fr.fromBuffer(reader);
-    const noteTypeId = reader.readObject(NoteSelector);
-    const txHash = reader.readObject(TxHash);
-    const l2BlockNumber = reader.readNumber();
-    const l2BlockHash = Fr.fromBuffer(reader).toString();
     const nonce = Fr.fromBuffer(reader);
     const noteHash = Fr.fromBuffer(reader);
     const siloedNullifier = Fr.fromBuffer(reader);
+    const txHash = reader.readObject(TxHash);
+    const l2BlockNumber = reader.readNumber();
+    const l2BlockHash = Fr.fromBuffer(reader).toString();
     const index = toBigIntBE(reader.readBytes(32));
     const publicKey = Point.fromBuffer(reader);
+    const noteTypeId = reader.readObject(NoteSelector);
 
-    return new IncomingNoteDao(
+    return new NoteDao(
       note,
       contractAddress,
       storageSlot,
-      noteTypeId,
-      txHash,
-      l2BlockNumber,
-      l2BlockHash,
       nonce,
       noteHash,
       siloedNullifier,
+      txHash,
+      l2BlockNumber,
+      l2BlockHash,
       index,
       publicKey,
+      noteTypeId,
     );
   }
 
@@ -125,7 +142,7 @@ export class IncomingNoteDao implements NoteData {
 
   static fromString(str: string) {
     const hex = str.replace(/^0x/, '');
-    return IncomingNoteDao.fromBuffer(Buffer.from(hex, 'hex'));
+    return NoteDao.fromBuffer(Buffer.from(hex, 'hex'));
   }
 
   /**
@@ -141,30 +158,30 @@ export class IncomingNoteDao implements NoteData {
   static random({
     note = Note.random(),
     contractAddress = AztecAddress.random(),
-    txHash = randomTxHash(),
     storageSlot = Fr.random(),
-    noteTypeId = NoteSelector.random(),
     nonce = Fr.random(),
-    l2BlockNumber = Math.floor(Math.random() * 1000),
-    l2BlockHash = Fr.random().toString(),
     noteHash = Fr.random(),
     siloedNullifier = Fr.random(),
+    txHash = randomTxHash(),
+    l2BlockNumber = Math.floor(Math.random() * 1000),
+    l2BlockHash = Fr.random().toString(),
     index = Fr.random().toBigInt(),
     addressPoint = Point.random(),
-  }: Partial<IncomingNoteDao> = {}) {
-    return new IncomingNoteDao(
+    noteTypeId = NoteSelector.random(),
+  }: Partial<NoteDao> = {}) {
+    return new NoteDao(
       note,
       contractAddress,
       storageSlot,
-      noteTypeId,
-      txHash,
-      l2BlockNumber,
-      l2BlockHash,
       nonce,
       noteHash,
       siloedNullifier,
+      txHash,
+      l2BlockNumber,
+      l2BlockHash,
       index,
       addressPoint,
+      noteTypeId,
     );
   }
 }

package/src/database/outgoing_note_dao.ts

@@ -69,7 +69,7 @@ export class OutgoingNoteDao {
       this.contractAddress,
       this.storageSlot,
       this.noteTypeId,
-      this.txHash.buffer,
+      this.txHash,
       this.l2BlockNumber,
       Fr.fromHexString(this.l2BlockHash),
       this.nonce,
@@ -85,7 +85,7 @@ export class OutgoingNoteDao {
     const contractAddress = AztecAddress.fromBuffer(reader);
     const storageSlot = Fr.fromBuffer(reader);
     const noteTypeId = reader.readObject(NoteSelector);
-    const txHash = new TxHash(reader.readBytes(TxHash.SIZE));
+    const txHash = reader.readObject(TxHash);
     const l2BlockNumber = reader.readNumber();
     const l2BlockHash = Fr.fromBuffer(reader).toString();
     const nonce = Fr.fromBuffer(reader);

package/src/database/pxe_database.ts

@@ -1,4 +1,4 @@
-import { type InBlock, type IncomingNotesFilter } from '@aztec/circuit-types';
+import { type InBlock, type NotesFilter } from '@aztec/circuit-types';
 import {
   type BlockHeader,
   type CompleteAddress,
@@ -12,7 +12,7 @@ import { type Fr } from '@aztec/foundation/fields';
 
 import { type ContractArtifactDatabase } from './contracts/contract_artifact_db.js';
 import { type ContractInstanceDatabase } from './contracts/contract_instance_db.js';
-import { type IncomingNoteDao } from './incoming_note_dao.js';
+import { type NoteDao } from './note_dao.js';
 
 /**
  * A database interface that provides methods for retrieving, adding, and removing transactional data related to Aztec
@@ -50,11 +50,11 @@ export interface PxeDatabase extends ContractArtifactDatabase, ContractInstanceD
   popCapsule(): Promise<Fr[] | undefined>;
 
   /**
-   * Gets incoming notes based on the provided filter.
+   * Gets notes based on the provided filter.
    * @param filter - The filter to apply to the notes.
    * @returns The requested notes.
    */
-  getIncomingNotes(filter: IncomingNotesFilter): Promise<IncomingNoteDao[]>;
+  getNotes(filter: NotesFilter): Promise<NoteDao[]>;
 
   /**
    * Adds a note to DB.
@@ -62,24 +62,24 @@ export interface PxeDatabase extends ContractArtifactDatabase, ContractInstanceD
    * @param scope - The scope to add the note under. Currently optional.
    * @remark - Will create a database for the scope if it does not already exist.
    */
-  addNote(note: IncomingNoteDao, scope?: AztecAddress): Promise<void>;
+  addNote(note: NoteDao, scope?: AztecAddress): Promise<void>;
 
   /**
    * Adds a nullified note to DB.
    * @param note - The note to add.
    */
-  addNullifiedNote(note: IncomingNoteDao): Promise<void>;
+  addNullifiedNote(note: NoteDao): Promise<void>;
 
   /**
    * Adds an array of notes to DB.
    * This function is used to insert multiple notes to the database at once,
    * which can improve performance when dealing with large numbers of transactions.
    *
-   * @param incomingNotes - An array of notes which were decrypted as incoming.
+   * @param notes - An array of notes.
    * @param scope - The scope to add the notes under. Currently optional.
    * @remark - Will create a database for the scope if it does not already exist.
    */
-  addNotes(incomingNotes: IncomingNoteDao[], scope?: AztecAddress): Promise<void>;
+  addNotes(notes: NoteDao[], scope?: AztecAddress): Promise<void>;
 
   /**
    * Remove nullified notes associated with the given account and nullifiers.
@@ -88,7 +88,7 @@ export interface PxeDatabase extends ContractArtifactDatabase, ContractInstanceD
    * @param account - A PublicKey instance representing the account for which the records are being removed.
    * @returns Removed notes.
    */
-  removeNullifiedNotes(nullifiers: InBlock<Fr>[], account: PublicKey): Promise<IncomingNoteDao[]>;
+  removeNullifiedNotes(nullifiers: InBlock<Fr>[], account: PublicKey): Promise<NoteDao[]>;
 
   /**
    * Gets the most recently processed block number.
@@ -213,4 +213,22 @@ export interface PxeDatabase extends ContractArtifactDatabase, ContractInstanceD
    * is also required to deal with chain reorgs.
    */
   resetNoteSyncData(): Promise<void>;
+
+  /**
+   * Used by contracts during execution to store arbitrary data in the local PXE database. The data is siloed/scoped
+   * to a specific `contract`.
+   * @param contract - An address of a contract that is requesting to store the data.
+   * @param key - A field element representing the key to store the data under.
+   * @param values - An array of field elements representing the data to store.
+   */
+  store(contract: AztecAddress, key: Fr, values: Fr[]): Promise<void>;
+
+  /**
+   * Used by contracts during execution to load arbitrary data from the local PXE database. The data is siloed/scoped
+   * to a specific `contract`.
+   * @param contract - An address of a contract that is requesting to load the data.
+   * @param key - A field element representing the key under which to load the data..
+   * @returns An array of field elements representing the stored data or `null` if no data is stored under the key.
+   */
+  load(contract: AztecAddress, key: Fr): Promise<Fr[] | null>;
 }

package/src/database/pxe_database_test_suite.ts

@@ -1,4 +1,4 @@
-import { type IncomingNotesFilter, NoteStatus, randomTxHash } from '@aztec/circuit-types';
+import { NoteStatus, type NotesFilter, randomTxHash } from '@aztec/circuit-types';
 import {
   AztecAddress,
   CompleteAddress,
@@ -13,7 +13,7 @@ import { Fr, Point } from '@aztec/foundation/fields';
 import { BenchmarkingContractArtifact } from '@aztec/noir-contracts.js/Benchmarking';
 import { TestContractArtifact } from '@aztec/noir-contracts.js/Test';
 
-import { IncomingNoteDao } from './incoming_note_dao.js';
+import { NoteDao } from './note_dao.js';
 import { type PxeDatabase } from './pxe_database.js';
 
 /**
@@ -78,9 +78,9 @@ export function describePxeDatabase(getDatabase: () => PxeDatabase) {
       let owners: CompleteAddress[];
       let contractAddresses: AztecAddress[];
       let storageSlots: Fr[];
-      let notes: IncomingNoteDao[];
+      let notes: NoteDao[];
 
-      const filteringTests: [() => IncomingNotesFilter, () => IncomingNoteDao[]][] = [
+      const filteringTests: [() => NotesFilter, () => NoteDao[]][] = [
         [() => ({}), () => notes],
 
         [
@@ -119,7 +119,7 @@ export function describePxeDatabase(getDatabase: () => PxeDatabase) {
         storageSlots = Array.from({ length: 2 }).map(() => Fr.random());
 
         notes = Array.from({ length: 10 }).map((_, i) =>
-          IncomingNoteDao.random({
+          NoteDao.random({
             contractAddress: contractAddresses[i % contractAddresses.length],
             storageSlot: storageSlots[i % storageSlots.length],
             addressPoint: owners[i % owners.length].address.toAddressPoint(),
@@ -135,7 +135,7 @@ export function describePxeDatabase(getDatabase: () => PxeDatabase) {
 
       it.each(filteringTests)('stores notes in bulk and retrieves notes', async (getFilter, getExpected) => {
         await database.addNotes(notes);
-        const returnedNotes = await database.getIncomingNotes(getFilter());
+        const returnedNotes = await database.getNotes(getFilter());
 
         expect(returnedNotes.sort()).toEqual(getExpected().sort());
       });
@@ -145,7 +145,7 @@ export function describePxeDatabase(getDatabase: () => PxeDatabase) {
           await database.addNote(note);
         }
 
-        const returnedNotes = await database.getIncomingNotes(getFilter());
+        const returnedNotes = await database.getNotes(getFilter());
 
         expect(returnedNotes.sort()).toEqual(getExpected().sort());
       });
@@ -166,9 +166,9 @@ export function describePxeDatabase(getDatabase: () => PxeDatabase) {
           );
         }
 
-        await expect(
-          database.getIncomingNotes({ ...getFilter(), status: NoteStatus.ACTIVE_OR_NULLIFIED }),
-        ).resolves.toEqual(getExpected());
+        await expect(database.getNotes({ ...getFilter(), status: NoteStatus.ACTIVE_OR_NULLIFIED })).resolves.toEqual(
+          getExpected(),
+        );
       });
 
       it('skips nullified notes by default or when requesting active', async () => {
@@ -184,8 +184,8 @@ export function describePxeDatabase(getDatabase: () => PxeDatabase) {
           notesToNullify,
         );
 
-        const actualNotesWithDefault = await database.getIncomingNotes({});
-        const actualNotesWithActive = await database.getIncomingNotes({ status: NoteStatus.ACTIVE });
+        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)));
@@ -206,7 +206,7 @@ export function describePxeDatabase(getDatabase: () => PxeDatabase) {
         );
         await expect(database.unnullifyNotesAfter(98)).resolves.toEqual(undefined);
 
-        const result = await database.getIncomingNotes({ status: NoteStatus.ACTIVE, owner: owners[0].address });
+        const result = await database.getNotes({ status: NoteStatus.ACTIVE, owner: owners[0].address });
 
         expect(result.sort()).toEqual([...notesToNullify].sort());
       });
@@ -224,7 +224,7 @@ export function describePxeDatabase(getDatabase: () => PxeDatabase) {
           notesToNullify,
         );
 
-        const result = await database.getIncomingNotes({
+        const result = await database.getNotes({
           status: NoteStatus.ACTIVE_OR_NULLIFIED,
         });
 
@@ -242,23 +242,23 @@ export function describePxeDatabase(getDatabase: () => PxeDatabase) {
           await database.addNote(note, owners[1].address);
         }
 
-        const owner0IncomingNotes = await database.getIncomingNotes({
+        const owner0Notes = await database.getNotes({
           scopes: [owners[0].address],
         });
 
-        expect(owner0IncomingNotes.sort()).toEqual(notes.slice(0, 5).sort());
+        expect(owner0Notes.sort()).toEqual(notes.slice(0, 5).sort());
 
-        const owner1IncomingNotes = await database.getIncomingNotes({
+        const owner1Notes = await database.getNotes({
           scopes: [owners[1].address],
         });
 
-        expect(owner1IncomingNotes.sort()).toEqual(notes.slice(5).sort());
+        expect(owner1Notes.sort()).toEqual(notes.slice(5).sort());
 
-        const bothOwnerIncomingNotes = await database.getIncomingNotes({
+        const bothOwnerNotes = await database.getNotes({
           scopes: [owners[0].address, owners[1].address],
         });
 
-        expect(bothOwnerIncomingNotes.sort()).toEqual(notes.sort());
+        expect(bothOwnerNotes.sort()).toEqual(notes.sort());
       });
 
       it('a nullified note removes notes from all accounts in the pxe', async () => {
@@ -266,12 +266,12 @@ export function describePxeDatabase(getDatabase: () => PxeDatabase) {
         await database.addNote(notes[0], owners[1].address);
 
         await expect(
-          database.getIncomingNotes({
+          database.getNotes({
             scopes: [owners[0].address],
           }),
         ).resolves.toEqual([notes[0]]);
         await expect(
-          database.getIncomingNotes({
+          database.getNotes({
             scopes: [owners[1].address],
           }),
         ).resolves.toEqual([notes[0]]);
@@ -290,12 +290,12 @@ export function describePxeDatabase(getDatabase: () => PxeDatabase) {
         ).resolves.toEqual([notes[0]]);
 
         await expect(
-          database.getIncomingNotes({
+          database.getNotes({
             scopes: [owners[0].address],
           }),
         ).resolves.toEqual([]);
         await expect(
-          database.getIncomingNotes({
+          database.getNotes({
             scopes: [owners[1].address],
           }),
         ).resolves.toEqual([]);
@@ -305,7 +305,7 @@ export function describePxeDatabase(getDatabase: () => PxeDatabase) {
         await database.addNotes(notes, owners[0].address);
 
         await database.removeNotesAfter(5);
-        const result = await database.getIncomingNotes({ scopes: [owners[0].address] });
+        const result = await database.getNotes({ scopes: [owners[0].address] });
         expect(new Set(result)).toEqual(new Set(notes.slice(0, 6)));
       });
     });
@@ -405,5 +405,66 @@ export function describePxeDatabase(getDatabase: () => PxeDatabase) {
         await expect(database.getContractInstance(address)).resolves.toEqual(instance);
       });
     });
+
+    describe('contract store', () => {
+      let contract: AztecAddress;
+
+      beforeEach(() => {
+        // Setup mock contract address
+        contract = AztecAddress.random();
+      });
+
+      it('stores and loads a single value', async () => {
+        const key = new Fr(1);
+        const values = [new Fr(42)];
+
+        await database.store(contract, key, values);
+        const result = await database.load(contract, key);
+        expect(result).toEqual(values);
+      });
+
+      it('stores and loads multiple values', async () => {
+        const key = new Fr(1);
+        const values = [new Fr(42), new Fr(43), new Fr(44)];
+
+        await database.store(contract, key, values);
+        const result = await database.load(contract, key);
+        expect(result).toEqual(values);
+      });
+
+      it('overwrites existing values', async () => {
+        const key = new Fr(1);
+        const initialValues = [new Fr(42)];
+        const newValues = [new Fr(100)];
+
+        await database.store(contract, key, initialValues);
+        await database.store(contract, key, newValues);
+
+        const result = await database.load(contract, key);
+        expect(result).toEqual(newValues);
+      });
+
+      it('stores values for different contracts independently', async () => {
+        const anotherContract = AztecAddress.random();
+        const key = new Fr(1);
+        const values1 = [new Fr(42)];
+        const values2 = [new Fr(100)];
+
+        await database.store(contract, key, values1);
+        await database.store(anotherContract, key, values2);
+
+        const result1 = await database.load(contract, key);
+        const result2 = await database.load(anotherContract, key);
+
+        expect(result1).toEqual(values1);
+        expect(result2).toEqual(values2);
+      });
+
+      it('returns null for non-existent keys', async () => {
+        const key = Fr.random();
+        const result = await database.load(contract, key);
+        expect(result).toBeNull();
+      });
+    });
   });
 }

package/src/kernel_oracle/index.ts

@@ -15,7 +15,7 @@ import {
 import { createLogger } from '@aztec/foundation/log';
 import { type Tuple } from '@aztec/foundation/serialize';
 import { type KeyStore } from '@aztec/key-store';
-import { getVKIndex, getVKSiblingPath } from '@aztec/noir-protocol-circuits-types/client';
+import { getVKIndex, getVKSiblingPath } from '@aztec/noir-protocol-circuits-types/vks';
 
 import { type ContractDataOracle } from '../contract_data_oracle/index.js';
 import { type ProvingDataOracle } from './../kernel_prover/proving_data_oracle.js';

package/src/kernel_prover/hints/build_private_kernel_reset_private_inputs.ts

@@ -57,7 +57,7 @@ function getNullifierMembershipWitnessResolver(oracle: ProvingDataOracle) {
   return async (nullifier: Fr) => {
     const res = await oracle.getNullifierMembershipWitness(nullifier);
     if (!res) {
-      throw new Error(`Cannot find the leaf for nullifier ${nullifier.toBigInt()}.`);
+      throw new Error(`Cannot find the leaf for nullifier ${nullifier}.`);
     }
 
     const { index, siblingPath, leafPreimage } = res;

package/src/kernel_prover/index.ts

@@ -1,4 +1,2 @@
-export { TestPrivateKernelProver } from './test/test_circuit_prover.js';
-
 export * from './kernel_prover.js';
 export * from './proving_data_oracle.js';