@aztec/pxe 0.42.0 → 0.43.0

package/src/database/outgoing_note_dao.ts

@@ -0,0 +1,90 @@
+import { Note, TxHash } from '@aztec/circuit-types';
+import { AztecAddress, Fr, Point, type PublicKey } from '@aztec/circuits.js';
+import { toBigIntBE } from '@aztec/foundation/bigint-buffer';
+import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
+
+/**
+ * A note with contextual data which was decrypted as outgoing.
+ */
+export class OutgoingNoteDao {
+  constructor(
+    /** 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 note type identifier for the contract. */
+    public noteTypeId: Fr,
+    /** The hash of the tx the note was created in. */
+    public txHash: TxHash,
+    /** The nonce of the note. */
+    public nonce: Fr,
+    /**
+     * Inner note hash of the note. This is customizable by the app circuit.
+     * We can use this value to compute siloedNoteHash and uniqueSiloedNoteHash.
+     */
+    public innerNoteHash: Fr,
+    /** The location of the relevant note in the note hash tree. */
+    public index: bigint,
+    /** The public key with which the note was encrypted. */
+    public ovpkM: PublicKey,
+  ) {}
+
+  toBuffer(): Buffer {
+    return serializeToBuffer([
+      this.note,
+      this.contractAddress,
+      this.storageSlot,
+      this.noteTypeId,
+      this.txHash.buffer,
+      this.nonce,
+      this.innerNoteHash,
+      this.index,
+      this.ovpkM,
+    ]);
+  }
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+
+    const note = Note.fromBuffer(reader);
+    const contractAddress = AztecAddress.fromBuffer(reader);
+    const storageSlot = Fr.fromBuffer(reader);
+    const noteTypeId = Fr.fromBuffer(reader);
+    const txHash = new TxHash(reader.readBytes(TxHash.SIZE));
+    const nonce = Fr.fromBuffer(reader);
+    const innerNoteHash = Fr.fromBuffer(reader);
+    const index = toBigIntBE(reader.readBytes(32));
+    const publicKey = Point.fromBuffer(reader);
+
+    return new OutgoingNoteDao(
+      note,
+      contractAddress,
+      storageSlot,
+      noteTypeId,
+      txHash,
+      nonce,
+      innerNoteHash,
+      index,
+      publicKey,
+    );
+  }
+
+  toString() {
+    return '0x' + this.toBuffer().toString('hex');
+  }
+
+  static fromString(str: string) {
+    const hex = str.replace(/^0x/, '');
+    return OutgoingNoteDao.fromBuffer(Buffer.from(hex, 'hex'));
+  }
+
+  /**
+   * Returns the size in bytes of the Note Dao.
+   * @returns - Its size in bytes.
+   */
+  public getSize() {
+    const noteSize = 4 + this.note.items.length * Fr.SIZE_IN_BYTES;
+    return noteSize + AztecAddress.SIZE_IN_BYTES + Fr.SIZE_IN_BYTES * 2 + TxHash.SIZE + Point.SIZE_IN_BYTES;
+  }
+}

package/src/database/pxe_database.ts

@@ -1,4 +1,4 @@
-import { type NoteFilter } from '@aztec/circuit-types';
+import { type IncomingNotesFilter, type OutgoingNotesFilter } from '@aztec/circuit-types';
 import { type CompleteAddress, type Header, type PublicKey } from '@aztec/circuits.js';
 import { type ContractArtifact } from '@aztec/foundation/abi';
 import { type AztecAddress } from '@aztec/foundation/aztec-address';
@@ -8,7 +8,8 @@ import { type ContractInstanceWithAddress } from '@aztec/types/contracts';
 import { type ContractArtifactDatabase } from './contracts/contract_artifact_db.js';
 import { type ContractInstanceDatabase } from './contracts/contract_instance_db.js';
 import { type DeferredNoteDao } from './deferred_note_dao.js';
-import { type NoteDao } from './note_dao.js';
+import { type IncomingNoteDao } from './incoming_note_dao.js';
+import { type OutgoingNoteDao } from './outgoing_note_dao.js';
 
 /**
  * A database interface that provides methods for retrieving, adding, and removing transactional data related to Aztec
@@ -46,26 +47,39 @@ export interface PxeDatabase extends ContractArtifactDatabase, ContractInstanceD
   popCapsule(): Promise<Fr[] | undefined>;
 
   /**
-   * Gets notes based on the provided filter.
+   * Gets incoming notes based on the provided filter.
    * @param filter - The filter to apply to the notes.
    * @returns The requested notes.
    */
-  getNotes(filter: NoteFilter): Promise<NoteDao[]>;
+  getIncomingNotes(filter: IncomingNotesFilter): Promise<IncomingNoteDao[]>;
+
+  /**
+   * Gets outgoing notes.
+   * @returns The outgoing notes.
+   */
+  getOutgoingNotes(filter: OutgoingNotesFilter): Promise<OutgoingNoteDao[]>;
 
   /**
    * Adds a note to DB.
    * @param note - The note to add.
    */
-  addNote(note: NoteDao): Promise<void>;
+  addNote(note: IncomingNoteDao): Promise<void>;
+
+  /**
+   * Adds a nullified note to DB.
+   * @param note - The note to add.
+   */
+  addNullifiedNote(note: IncomingNoteDao): 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 notes - An array of notes.
+   * @param incomingNotes - An array of notes which were decrypted as incoming.
+   * @param outgoingNotes - An array of notes which were decrypted as outgoing.
    */
-  addNotes(notes: NoteDao[]): Promise<void>;
+  addNotes(incomingNotes: IncomingNoteDao[], outgoingNotes: OutgoingNoteDao[]): Promise<void>;
 
   /**
    * Add notes to the database that are intended for us, but we don't yet have the contract.
@@ -93,7 +107,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: Fr[], account: PublicKey): Promise<NoteDao[]>;
+  removeNullifiedNotes(nullifiers: Fr[], account: PublicKey): Promise<IncomingNoteDao[]>;
 
   /**
    * Gets the most recently processed block number.
@@ -162,5 +176,5 @@ export interface PxeDatabase extends ContractArtifactDatabase, ContractInstanceD
    * Returns the estimated size in bytes of this db.
    * @returns The estimated size in bytes of this db.
    */
-  estimateSize(): number;
+  estimateSize(): Promise<number>;
 }

package/src/database/pxe_database_test_suite.ts

@@ -1,4 +1,4 @@
-import { type NoteFilter, NoteStatus, randomTxHash } from '@aztec/circuit-types';
+import { type IncomingNotesFilter, NoteStatus, type OutgoingNotesFilter, randomTxHash } from '@aztec/circuit-types';
 import { AztecAddress, CompleteAddress, INITIAL_L2_BLOCK_NUM, PublicKeys } from '@aztec/circuits.js';
 import { makeHeader } from '@aztec/circuits.js/testing';
 import { randomInt } from '@aztec/foundation/crypto';
@@ -6,8 +6,10 @@ import { Fr, Point } from '@aztec/foundation/fields';
 import { BenchmarkingContractArtifact } from '@aztec/noir-contracts.js/Benchmarking';
 import { SerializableContractInstance } from '@aztec/types/contracts';
 
-import { type NoteDao } from './note_dao.js';
-import { randomNoteDao } from './note_dao.test.js';
+import { type IncomingNoteDao } from './incoming_note_dao.js';
+import { randomIncomingNoteDao } from './incoming_note_dao.test.js';
+import { type OutgoingNoteDao } from './outgoing_note_dao.js';
+import { randomOutgoingNoteDao } from './outgoing_note_dao.test.js';
 import { type PxeDatabase } from './pxe_database.js';
 
 /**
@@ -68,13 +70,13 @@ export function describePxeDatabase(getDatabase: () => PxeDatabase) {
       });
     });
 
-    describe('notes', () => {
+    describe('incoming notes', () => {
       let owners: CompleteAddress[];
       let contractAddresses: AztecAddress[];
       let storageSlots: Fr[];
-      let notes: NoteDao[];
+      let notes: IncomingNoteDao[];
 
-      const filteringTests: [() => NoteFilter, () => NoteDao[]][] = [
+      const filteringTests: [() => IncomingNotesFilter, () => IncomingNoteDao[]][] = [
         [() => ({}), () => notes],
 
         [
@@ -94,7 +96,7 @@ export function describePxeDatabase(getDatabase: () => PxeDatabase) {
 
         [
           () => ({ owner: owners[0].address }),
-          () => notes.filter(note => note.publicKey.equals(owners[0].publicKeys.masterIncomingViewingPublicKey)),
+          () => notes.filter(note => note.ivpkM.equals(owners[0].publicKeys.masterIncomingViewingPublicKey)),
         ],
 
         [
@@ -107,46 +109,44 @@ export function describePxeDatabase(getDatabase: () => PxeDatabase) {
         [() => ({ contractAddress: contractAddresses[0], storageSlot: storageSlots[1] }), () => []],
       ];
 
-      beforeEach(() => {
+      beforeEach(async () => {
         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({
+          randomIncomingNoteDao({
             contractAddress: contractAddresses[i % contractAddresses.length],
             storageSlot: storageSlots[i % storageSlots.length],
-            publicKey: owners[i % owners.length].publicKeys.masterIncomingViewingPublicKey,
+            ivpkM: owners[i % owners.length].publicKeys.masterIncomingViewingPublicKey,
             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());
+        await database.addNotes(notes, []);
+        await expect(database.getIncomingNotes(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());
+        await expect(database.getIncomingNotes(getFilter())).resolves.toEqual(getExpected());
       });
 
       it.each(filteringTests)('retrieves nullified notes', async (getFilter, getExpected) => {
-        await database.addNotes(notes);
+        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.publicKeys.masterIncomingViewingPublicKey),
+            note.ivpkM.equals(owner.publicKeys.masterIncomingViewingPublicKey),
           );
           const nullifiers = notesToNullify.map(note => note.siloedNullifier);
           await expect(
@@ -154,41 +154,41 @@ export function describePxeDatabase(getDatabase: () => PxeDatabase) {
           ).resolves.toEqual(notesToNullify);
         }
 
-        await expect(database.getNotes({ ...getFilter(), status: NoteStatus.ACTIVE_OR_NULLIFIED })).resolves.toEqual(
-          getExpected(),
-        );
+        await expect(
+          database.getIncomingNotes({ ...getFilter(), status: NoteStatus.ACTIVE_OR_NULLIFIED }),
+        ).resolves.toEqual(getExpected());
       });
 
       it('skips nullified notes by default or when requesting active', async () => {
-        await database.addNotes(notes);
+        await database.addNotes(notes, []);
 
         const notesToNullify = notes.filter(note =>
-          note.publicKey.equals(owners[0].publicKeys.masterIncomingViewingPublicKey),
+          note.ivpkM.equals(owners[0].publicKeys.masterIncomingViewingPublicKey),
         );
         const nullifiers = notesToNullify.map(note => note.siloedNullifier);
-        await expect(database.removeNullifiedNotes(nullifiers, notesToNullify[0].publicKey)).resolves.toEqual(
+        await expect(database.removeNullifiedNotes(nullifiers, notesToNullify[0].ivpkM)).resolves.toEqual(
           notesToNullify,
         );
 
-        const actualNotesWithDefault = await database.getNotes({});
-        const actualNotesWithActive = await database.getNotes({ status: NoteStatus.ACTIVE });
+        const actualNotesWithDefault = await database.getIncomingNotes({});
+        const actualNotesWithActive = await database.getIncomingNotes({ 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);
+        await database.addNotes(notes, []);
 
         const notesToNullify = notes.filter(note =>
-          note.publicKey.equals(owners[0].publicKeys.masterIncomingViewingPublicKey),
+          note.ivpkM.equals(owners[0].publicKeys.masterIncomingViewingPublicKey),
         );
         const nullifiers = notesToNullify.map(note => note.siloedNullifier);
-        await expect(database.removeNullifiedNotes(nullifiers, notesToNullify[0].publicKey)).resolves.toEqual(
+        await expect(database.removeNullifiedNotes(nullifiers, notesToNullify[0].ivpkM)).resolves.toEqual(
           notesToNullify,
         );
 
-        const result = await database.getNotes({
+        const result = await database.getIncomingNotes({
           status: NoteStatus.ACTIVE_OR_NULLIFIED,
         });
 
@@ -198,6 +198,70 @@ export function describePxeDatabase(getDatabase: () => PxeDatabase) {
       });
     });
 
+    describe('outgoing notes', () => {
+      let owners: CompleteAddress[];
+      let contractAddresses: AztecAddress[];
+      let storageSlots: Fr[];
+      let notes: OutgoingNoteDao[];
+
+      const filteringTests: [() => OutgoingNotesFilter, () => OutgoingNoteDao[]][] = [
+        [() => ({}), () => 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.ovpkM.equals(owners[0].publicKeys.masterOutgoingViewingPublicKey)),
+        ],
+
+        [
+          () => ({ 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(async () => {
+        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) =>
+          randomOutgoingNoteDao({
+            contractAddress: contractAddresses[i % contractAddresses.length],
+            storageSlot: storageSlots[i % storageSlots.length],
+            ovpkM: owners[i % owners.length].publicKeys.masterOutgoingViewingPublicKey,
+            index: BigInt(i),
+          }),
+        );
+
+        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.getOutgoingNotes(getFilter())).resolves.toEqual(getExpected());
+      });
+    });
+
     describe('block header', () => {
       it('stores and retrieves the block header', async () => {
         const header = makeHeader(randomInt(1000), INITIAL_L2_BLOCK_NUM);