@aztec/pxe 0.0.0-test.1 → 0.0.1-commit.5476d83

package/src/storage/note_data_provider/note_data_provider.ts

@@ -1,18 +1,20 @@
 import { toBufferBE } from '@aztec/foundation/bigint-buffer';
-import type { Fr, Point } from '@aztec/foundation/fields';
+import type { Fr } from '@aztec/foundation/fields';
 import { toArray } from '@aztec/foundation/iterable';
 import type { AztecAsyncKVStore, AztecAsyncMap, AztecAsyncMultiMap } from '@aztec/kv-store';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 import type { InBlock } from '@aztec/stdlib/block';
-import type { PublicKey } from '@aztec/stdlib/keys';
 import { NoteStatus, type NotesFilter } from '@aztec/stdlib/note';
-
-import type { DataProvider } from '../data_provider.js';
-import { NoteDao } from './note_dao.js';
-
-export class NoteDataProvider implements DataProvider {
+import { NoteDao } from '@aztec/stdlib/note';
+
+/**
+ * NoteDataProvider manages the storage and retrieval of notes.
+ *
+ * Notes can be active or nullified. This class processes new notes, nullifications,
+ * and performs rollback handling in the case of a reorg.
+ **/
+export class NoteDataProvider {
   #store: AztecAsyncKVStore;
-
   #notes: AztecAsyncMap<string, Buffer>;
   #nullifiedNotes: AztecAsyncMap<string, Buffer>;
   #nullifierToNoteId: AztecAsyncMap<string, string>;
@@ -21,16 +23,12 @@ export class NoteDataProvider implements DataProvider {
   #nullifiedNotesToScope: AztecAsyncMultiMap<string, string>;
   #nullifiedNotesByContract: AztecAsyncMultiMap<string, string>;
   #nullifiedNotesByStorageSlot: AztecAsyncMultiMap<string, string>;
-  #nullifiedNotesByTxHash: AztecAsyncMultiMap<string, string>;
-  #nullifiedNotesByAddressPoint: AztecAsyncMultiMap<string, string>;
   #nullifiedNotesByNullifier: AztecAsyncMap<string, string>;
 
   #scopes: AztecAsyncMap<string, true>;
   #notesToScope: AztecAsyncMultiMap<string, string>;
   #notesByContractAndScope: Map<string, AztecAsyncMultiMap<string, string>>;
   #notesByStorageSlotAndScope: Map<string, AztecAsyncMultiMap<string, string>>;
-  #notesByTxHashAndScope: Map<string, AztecAsyncMultiMap<string, string>>;
-  #notesByAddressPointAndScope: Map<string, AztecAsyncMultiMap<string, string>>;
 
   private constructor(store: AztecAsyncKVStore) {
     this.#store = store;
@@ -42,29 +40,41 @@ export class NoteDataProvider implements DataProvider {
     this.#nullifiedNotesToScope = store.openMultiMap('nullified_notes_to_scope');
     this.#nullifiedNotesByContract = store.openMultiMap('nullified_notes_by_contract');
     this.#nullifiedNotesByStorageSlot = store.openMultiMap('nullified_notes_by_storage_slot');
-    this.#nullifiedNotesByTxHash = store.openMultiMap('nullified_notes_by_tx_hash');
-    this.#nullifiedNotesByAddressPoint = store.openMultiMap('nullified_notes_by_address_point');
     this.#nullifiedNotesByNullifier = store.openMap('nullified_notes_by_nullifier');
 
     this.#scopes = store.openMap('scopes');
     this.#notesToScope = store.openMultiMap('notes_to_scope');
     this.#notesByContractAndScope = new Map<string, AztecAsyncMultiMap<string, string>>();
     this.#notesByStorageSlotAndScope = new Map<string, AztecAsyncMultiMap<string, string>>();
-    this.#notesByTxHashAndScope = new Map<string, AztecAsyncMultiMap<string, string>>();
-    this.#notesByAddressPointAndScope = new Map<string, AztecAsyncMultiMap<string, string>>();
   }
 
+  /**
+   * Creates and initializes a new NoteDataProvider instance.
+   *
+   * This factory method creates a NoteDataProvider and restores any existing
+   * scope-specific indexes from the database.
+   *
+   * @param store - The key-value store to use for persistence
+   * @returns Promise resolving to a fully initialized NoteDataProvider instance
+   */
   public static async create(store: AztecAsyncKVStore): Promise<NoteDataProvider> {
     const pxeDB = new NoteDataProvider(store);
     for await (const scope of pxeDB.#scopes.keysAsync()) {
       pxeDB.#notesByContractAndScope.set(scope, store.openMultiMap(`${scope}:notes_by_contract`));
       pxeDB.#notesByStorageSlotAndScope.set(scope, store.openMultiMap(`${scope}:notes_by_storage_slot`));
-      pxeDB.#notesByTxHashAndScope.set(scope, store.openMultiMap(`${scope}:notes_by_tx_hash`));
-      pxeDB.#notesByAddressPointAndScope.set(scope, store.openMultiMap(`${scope}:notes_by_address_point`));
     }
     return pxeDB;
   }
 
+  /**
+   * Adds a new scope to the note data provider.
+   *
+   * Scopes provide privacy isolation by creating separate indexes for each user.
+   * Each scope gets its own set of indexes for efficient note retrieval by various criteria.
+   *
+   * @param scope - The AztecAddress representing the scope/user to add
+   * @returns Promise resolving to true if scope was added, false if it already existed
+   */
   public async addScope(scope: AztecAddress): Promise<boolean> {
     const scopeString = scope.toString();
 
@@ -75,26 +85,27 @@ export class NoteDataProvider implements DataProvider {
     await this.#scopes.set(scopeString, true);
     this.#notesByContractAndScope.set(scopeString, this.#store.openMultiMap(`${scopeString}:notes_by_contract`));
     this.#notesByStorageSlotAndScope.set(scopeString, this.#store.openMultiMap(`${scopeString}:notes_by_storage_slot`));
-    this.#notesByTxHashAndScope.set(scopeString, this.#store.openMultiMap(`${scopeString}:notes_by_tx_hash`));
-    this.#notesByAddressPointAndScope.set(
-      scopeString,
-      this.#store.openMultiMap(`${scopeString}:notes_by_address_point`),
-    );
 
     return true;
   }
 
-  async addNotes(notes: NoteDao[], scope: AztecAddress = AztecAddress.ZERO): Promise<void> {
-    if (!(await this.#scopes.hasAsync(scope.toString()))) {
-      await this.addScope(scope);
-    }
-
+  /**
+   * Adds multiple notes to the data provider under the specified scope.
+   *
+   * Notes are stored using their index from the notes hash tree as the key, which provides
+   * uniqueness and maintains creation order. Each note is indexed by multiple criteria
+   * for efficient retrieval.
+   *
+   * @param notes - Notes to store
+   * @param scope - The scope (user/account) under which to store the notes
+   */
+  addNotes(notes: NoteDao[], scope: AztecAddress): Promise<void> {
     return this.#store.transactionAsync(async () => {
+      if (!(await this.#scopes.hasAsync(scope.toString()))) {
+        await this.addScope(scope);
+      }
+
       for (const dao of notes) {
-        // store notes by their index in the notes hash tree
-        // this provides the uniqueness we need to store individual notes
-        // and should also return notes in the order that they were created.
-        // Had we stored them by their nullifier, they would be returned in random order
         const noteIndex = toBufferBE(dao.index, 32).toString('hex');
         await this.#notes.set(noteIndex, dao.toBuffer());
         await this.#notesToScope.set(noteIndex, scope.toString());
@@ -102,13 +113,34 @@ export class NoteDataProvider implements DataProvider {
 
         await this.#notesByContractAndScope.get(scope.toString())!.set(dao.contractAddress.toString(), noteIndex);
         await this.#notesByStorageSlotAndScope.get(scope.toString())!.set(dao.storageSlot.toString(), noteIndex);
-        await this.#notesByTxHashAndScope.get(scope.toString())!.set(dao.txHash.toString(), noteIndex);
-        await this.#notesByAddressPointAndScope.get(scope.toString())!.set(dao.addressPoint.toString(), noteIndex);
       }
     });
   }
 
-  public removeNotesAfter(blockNumber: number): Promise<void> {
+  /**
+   * Synchronizes notes and nullifiers to a specific block number.
+   *
+   * This method ensures that the state of notes and nullifiers is consistent with the
+   * specified block number. It restores any notes that were nullified after the given block
+   * and deletes any active notes created after that block.
+   *
+   * @param blockNumber - The new chain tip after a reorg
+   * @param synchedBlockNumber - The block number up to which PXE managed to sync before the reorg happened.
+   */
+  public async rollbackNotesAndNullifiers(blockNumber: number, synchedBlockNumber: number): Promise<void> {
+    await this.#rewindNullifiersAfterBlock(blockNumber, synchedBlockNumber);
+    await this.#deleteActiveNotesAfterBlock(blockNumber);
+  }
+
+  /**
+   * Deletes (removes) all active notes created after the specified block number.
+   *
+   * Permanently delete notes from the active notes store, e.g. during a reorg.
+   * Note: This only affects #notes (active notes), not #nullifiedNotes.
+   *
+   * @param blockNumber - Notes created after this block number will be deleted
+   */
+  #deleteActiveNotesAfterBlock(blockNumber: number): Promise<void> {
     return this.#store.transactionAsync(async () => {
       const notes = await toArray(this.#notes.valuesAsync());
       for (const note of notes) {
@@ -120,8 +152,6 @@ export class NoteDataProvider implements DataProvider {
           await this.#nullifierToNoteId.delete(noteDao.siloedNullifier.toString());
           const scopes = await toArray(this.#scopes.keysAsync());
           for (const scope of scopes) {
-            await this.#notesByAddressPointAndScope.get(scope)!.deleteValue(noteDao.addressPoint.toString(), noteIndex);
-            await this.#notesByTxHashAndScope.get(scope)!.deleteValue(noteDao.txHash.toString(), noteIndex);
             await this.#notesByContractAndScope.get(scope)!.deleteValue(noteDao.contractAddress.toString(), noteIndex);
             await this.#notesByStorageSlotAndScope.get(scope)!.deleteValue(noteDao.storageSlot.toString(), noteIndex);
           }
@@ -130,41 +160,50 @@ export class NoteDataProvider implements DataProvider {
     });
   }
 
-  public async unnullifyNotesAfter(blockNumber: number, synchedBlockNumber?: number): Promise<void> {
-    const nullifiersToUndo: string[] = [];
-    const currentBlockNumber = blockNumber + 1;
-    const maxBlockNumber = synchedBlockNumber ?? currentBlockNumber;
-    for (let i = currentBlockNumber; i <= maxBlockNumber; i++) {
-      nullifiersToUndo.push(...(await toArray(this.#nullifiersByBlockNumber.getValuesAsync(i))));
-    }
-    const notesIndexesToReinsert = await Promise.all(
-      nullifiersToUndo.map(nullifier => this.#nullifiedNotesByNullifier.getAsync(nullifier)),
-    );
-    const notNullNoteIndexes = notesIndexesToReinsert.filter(noteIndex => noteIndex != undefined);
-    const nullifiedNoteBuffers = await Promise.all(
-      notNullNoteIndexes.map(noteIndex => this.#nullifiedNotes.getAsync(noteIndex!)),
-    );
-    const noteDaos = nullifiedNoteBuffers
-      .filter(buffer => buffer != undefined)
-      .map(buffer => NoteDao.fromBuffer(buffer!));
-
+  /**
+   * Rewinds nullifications after a given block number.
+   *
+   * This operation "unnullifies" notes, rolling back nullifications that occurred
+   * in orphaned blocks, e.g. during a reorg.  The notes are restored to the
+   * active notes store and removed from the nullified store.
+   *
+   * @param blockNumber - Revert nullifications that occurred after this block
+   * @param synchedBlockNumber - Upper bound for the block range to process
+   */
+  async #rewindNullifiersAfterBlock(blockNumber: number, synchedBlockNumber: number): Promise<void> {
     await this.#store.transactionAsync(async () => {
+      const nullifiersToUndo: string[] = [];
+      const currentBlockNumber = blockNumber + 1;
+      for (let i = currentBlockNumber; i <= synchedBlockNumber; i++) {
+        nullifiersToUndo.push(...(await toArray(this.#nullifiersByBlockNumber.getValuesAsync(i))));
+      }
+      const notesIndexesToReinsert = await Promise.all(
+        nullifiersToUndo.map(nullifier => this.#nullifiedNotesByNullifier.getAsync(nullifier)),
+      );
+      const notNullNoteIndexes = notesIndexesToReinsert.filter(noteIndex => noteIndex != undefined);
+      const nullifiedNoteBuffers = await Promise.all(
+        notNullNoteIndexes.map(noteIndex => this.#nullifiedNotes.getAsync(noteIndex!)),
+      );
+      const noteDaos = nullifiedNoteBuffers
+        .filter(buffer => buffer != undefined)
+        .map(buffer => NoteDao.fromBuffer(buffer!));
+
       for (const dao of noteDaos) {
         const noteIndex = toBufferBE(dao.index, 32).toString('hex');
         await this.#notes.set(noteIndex, dao.toBuffer());
         await this.#nullifierToNoteId.set(dao.siloedNullifier.toString(), noteIndex);
 
-        let scopes = (await toArray(this.#nullifiedNotesToScope.getValuesAsync(noteIndex))) ?? [];
+        const scopes = await toArray(this.#nullifiedNotesToScope.getValuesAsync(noteIndex));
 
         if (scopes.length === 0) {
-          scopes = [new AztecAddress(dao.addressPoint.x).toString()];
+          // We should never run into this error because notes always have a scope assigned to them - either on initial
+          // insertion via `addNotes` or when removing their nullifiers.
+          throw new Error(`No scopes found for nullified note with index ${noteIndex}`);
         }
 
         for (const scope of scopes) {
           await this.#notesByContractAndScope.get(scope.toString())!.set(dao.contractAddress.toString(), noteIndex);
           await this.#notesByStorageSlotAndScope.get(scope.toString())!.set(dao.storageSlot.toString(), noteIndex);
-          await this.#notesByTxHashAndScope.get(scope.toString())!.set(dao.txHash.toString(), noteIndex);
-          await this.#notesByAddressPointAndScope.get(scope.toString())!.set(dao.addressPoint.toString(), noteIndex);
           await this.#notesToScope.set(noteIndex, scope);
         }
 
@@ -173,18 +212,32 @@ export class NoteDataProvider implements DataProvider {
         await this.#nullifiersByBlockNumber.deleteValue(dao.l2BlockNumber, dao.siloedNullifier.toString());
         await this.#nullifiedNotesByContract.deleteValue(dao.contractAddress.toString(), noteIndex);
         await this.#nullifiedNotesByStorageSlot.deleteValue(dao.storageSlot.toString(), noteIndex);
-        await this.#nullifiedNotesByTxHash.deleteValue(dao.txHash.toString(), noteIndex);
-        await this.#nullifiedNotesByAddressPoint.deleteValue(dao.addressPoint.toString(), noteIndex);
         await this.#nullifiedNotesByNullifier.delete(dao.siloedNullifier.toString());
       }
     });
   }
 
+  /**
+   * Retrieves notes based on the provided filter criteria.
+   *
+   * This method queries both active and optionally nullified notes based on the filter
+   * parameters.
+   *
+   * @param filter - Filter criteria including contractAddress (required), and optional
+   *                 storageSlot, status, scopes and siloedNullifier.
+   * @returns Promise resolving to array of NoteDao objects matching the filter
+   * @throws If filtering by an empty scopes array. Scopes have to be set to undefined or to a non-empty array.
+   */
   async getNotes(filter: NotesFilter): Promise<NoteDao[]> {
-    const publicKey: PublicKey | undefined = filter.owner ? await filter.owner.toAddressPoint() : undefined;
-
     filter.status = filter.status ?? NoteStatus.ACTIVE;
 
+    // throw early if scopes is an empty array
+    if (filter.scopes !== undefined && filter.scopes.length === 0) {
+      throw new Error(
+        'Trying to get notes with an empty scopes array. Scopes have to be set to undefined if intending on not filtering by scopes.',
+      );
+    }
+
     const candidateNoteSources = [];
 
     filter.scopes ??= (await toArray(this.#scopes.keysAsync())).map(addressString =>
@@ -196,29 +249,19 @@ export class NoteDataProvider implements DataProvider {
     for (const scope of new Set(filter.scopes)) {
       const formattedScopeString = scope.toString();
       if (!(await this.#scopes.hasAsync(formattedScopeString))) {
-        throw new Error('Trying to get incoming notes of an scope that is not in the PXE database');
+        throw new Error('Trying to get incoming notes of a scope that is not in the PXE database');
       }
 
       activeNoteIdsPerScope.push(
-        publicKey
-          ? await toArray(
-              this.#notesByAddressPointAndScope.get(formattedScopeString)!.getValuesAsync(publicKey.toString()),
-            )
-          : filter.txHash
+        filter.storageSlot
           ? await toArray(
-              this.#notesByTxHashAndScope.get(formattedScopeString)!.getValuesAsync(filter.txHash.toString()),
+              this.#notesByStorageSlotAndScope.get(formattedScopeString)!.getValuesAsync(filter.storageSlot.toString()),
             )
-          : filter.contractAddress
-          ? await toArray(
+          : await toArray(
               this.#notesByContractAndScope
                 .get(formattedScopeString)!
                 .getValuesAsync(filter.contractAddress.toString()),
-            )
-          : filter.storageSlot
-          ? await toArray(
-              this.#notesByStorageSlotAndScope.get(formattedScopeString)!.getValuesAsync(filter.storageSlot.toString()),
-            )
-          : await toArray(this.#notesByAddressPointAndScope.get(formattedScopeString)!.valuesAsync()),
+            ),
       );
     }
 
@@ -227,19 +270,28 @@ export class NoteDataProvider implements DataProvider {
       notes: this.#notes,
     });
 
-    if (filter.status == NoteStatus.ACTIVE_OR_NULLIFIED) {
-      candidateNoteSources.push({
-        ids: publicKey
-          ? await toArray(this.#nullifiedNotesByAddressPoint.getValuesAsync(publicKey.toString()))
-          : filter.txHash
-          ? await toArray(this.#nullifiedNotesByTxHash.getValuesAsync(filter.txHash.toString()))
-          : filter.contractAddress
-          ? await toArray(this.#nullifiedNotesByContract.getValuesAsync(filter.contractAddress.toString()))
-          : filter.storageSlot
-          ? await toArray(this.#nullifiedNotesByStorageSlot.getValuesAsync(filter.storageSlot.toString()))
-          : await toArray(this.#nullifiedNotes.keysAsync()),
-        notes: this.#nullifiedNotes,
-      });
+    // If status is ACTIVE_OR_NULLIFIED we add nullified notes as candidates on top of the default active ones.
+    if (filter.status === NoteStatus.ACTIVE_OR_NULLIFIED) {
+      const nullifiedIds = filter.storageSlot
+        ? await toArray(this.#nullifiedNotesByStorageSlot.getValuesAsync(filter.storageSlot.toString()))
+        : await toArray(this.#nullifiedNotesByContract.getValuesAsync(filter.contractAddress.toString()));
+
+      const setOfScopes = new Set(filter.scopes.map(s => s.toString() as string));
+      const filteredNullifiedIds = new Set<string>();
+
+      for (const noteId of nullifiedIds) {
+        const scopeList = await toArray(this.#nullifiedNotesToScope.getValuesAsync(noteId));
+        if (scopeList.some(scope => setOfScopes.has(scope))) {
+          filteredNullifiedIds.add(noteId);
+        }
+      }
+
+      if (filteredNullifiedIds.size > 0) {
+        candidateNoteSources.push({
+          ids: filteredNullifiedIds,
+          notes: this.#nullifiedNotes,
+        });
+      }
     }
 
     const result: NoteDao[] = [];
@@ -251,11 +303,7 @@ export class NoteDataProvider implements DataProvider {
         }
 
         const note = NoteDao.fromBuffer(serializedNote);
-        if (filter.contractAddress && !note.contractAddress.equals(filter.contractAddress)) {
-          continue;
-        }
-
-        if (filter.txHash && !note.txHash.equals(filter.txHash)) {
+        if (!note.contractAddress.equals(filter.contractAddress)) {
           continue;
         }
 
@@ -263,10 +311,6 @@ export class NoteDataProvider implements DataProvider {
           continue;
         }
 
-        if (publicKey && !note.addressPoint.equals(publicKey)) {
-          continue;
-        }
-
         if (filter.siloedNullifier && !note.siloedNullifier.equals(filter.siloedNullifier)) {
           continue;
         }
@@ -278,7 +322,18 @@ export class NoteDataProvider implements DataProvider {
     return result;
   }
 
-  removeNullifiedNotes(nullifiers: InBlock<Fr>[], accountAddressPoint: Point): Promise<NoteDao[]> {
+  /**
+   * Transitions notes from "active" to "nullified" state.
+   *
+   * This operation processes a batch of nullifiers to mark the corresponding notes
+   * as spent/nullified.  The operation is atomic - if any nullifier is not found,
+   * the entire operation fails and no notes are modified.
+   *
+   * @param nullifiers - Array of nullifiers with their block numbers to process
+   * @returns Promise resolving to array of nullified NoteDao objects
+   * @throws Error if any nullifier is not found in the active notes
+   */
+  applyNullifiers(nullifiers: InBlock<Fr>[]): Promise<NoteDao[]> {
     if (nullifiers.length === 0) {
       return Promise.resolve([]);
     }
@@ -288,24 +343,33 @@ export class NoteDataProvider implements DataProvider {
 
       for (const blockScopedNullifier of nullifiers) {
         const { data: nullifier, l2BlockNumber: blockNumber } = blockScopedNullifier;
-        const noteIndex = await this.#nullifierToNoteId.getAsync(nullifier.toString());
+        const nullifierKey = nullifier.toString();
+
+        const noteIndex = await this.#nullifierToNoteId.getAsync(nullifierKey);
         if (!noteIndex) {
-          continue;
+          // Check if already nullified?
+          const alreadyNullified = await this.#nullifiedNotesByNullifier.getAsync(nullifierKey);
+          if (alreadyNullified) {
+            throw new Error(`Nullifier already applied in applyNullifiers`);
+          }
+          throw new Error('Nullifier not found in applyNullifiers');
         }
 
         const noteBuffer = noteIndex ? await this.#notes.getAsync(noteIndex) : undefined;
 
         if (!noteBuffer) {
-          // note doesn't exist. Maybe it got nullified already
-          continue;
+          throw new Error('Note not found in applyNullifiers');
         }
-        const noteScopes = (await toArray(this.#notesToScope.getValuesAsync(noteIndex))) ?? [];
-        const note = NoteDao.fromBuffer(noteBuffer);
-        if (!note.addressPoint.equals(accountAddressPoint)) {
-          // tried to nullify someone else's note
-          continue;
+
+        const noteScopes = await toArray(this.#notesToScope.getValuesAsync(noteIndex));
+        if (noteScopes.length === 0) {
+          // We should never run into this error because notes always have a scope assigned to them - either on initial
+          // insertion via `addNotes` or when removing their nullifiers.
+          throw new Error('Note scopes are missing in applyNullifiers');
         }
 
+        const note = NoteDao.fromBuffer(noteBuffer);
+
         nullifiedNotes.push(note);
 
         await this.#notes.delete(noteIndex);
@@ -314,23 +378,17 @@ export class NoteDataProvider implements DataProvider {
         const scopes = await toArray(this.#scopes.keysAsync());
 
         for (const scope of scopes) {
-          await this.#notesByAddressPointAndScope.get(scope)!.deleteValue(accountAddressPoint.toString(), noteIndex);
-          await this.#notesByTxHashAndScope.get(scope)!.deleteValue(note.txHash.toString(), noteIndex);
           await this.#notesByContractAndScope.get(scope)!.deleteValue(note.contractAddress.toString(), noteIndex);
           await this.#notesByStorageSlotAndScope.get(scope)!.deleteValue(note.storageSlot.toString(), noteIndex);
         }
 
-        if (noteScopes !== undefined) {
-          for (const scope of noteScopes) {
-            await this.#nullifiedNotesToScope.set(noteIndex, scope);
-          }
+        for (const scope of noteScopes) {
+          await this.#nullifiedNotesToScope.set(noteIndex, scope);
         }
         await this.#nullifiedNotes.set(noteIndex, note.toBuffer());
         await this.#nullifiersByBlockNumber.set(blockNumber, nullifier.toString());
         await this.#nullifiedNotesByContract.set(note.contractAddress.toString(), noteIndex);
         await this.#nullifiedNotesByStorageSlot.set(note.storageSlot.toString(), noteIndex);
-        await this.#nullifiedNotesByTxHash.set(note.txHash.toString(), noteIndex);
-        await this.#nullifiedNotesByAddressPoint.set(note.addressPoint.toString(), noteIndex);
         await this.#nullifiedNotesByNullifier.set(nullifier.toString(), noteIndex);
 
         await this.#nullifierToNoteId.delete(nullifier.toString());
@@ -338,8 +396,4 @@ export class NoteDataProvider implements DataProvider {
       return nullifiedNotes;
     });
   }
-
-  async getSize() {
-    return (await this.getNotes({})).reduce((sum, note) => sum + note.getSize(), 0);
-  }
 }

package/src/storage/private_event_data_provider/private_event_data_provider.ts

@@ -0,0 +1,143 @@
+import { Fr } from '@aztec/foundation/fields';
+import { createLogger } from '@aztec/foundation/log';
+import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
+import type { AztecAsyncArray, AztecAsyncKVStore, AztecAsyncMap } from '@aztec/kv-store';
+import type { EventSelector } from '@aztec/stdlib/abi';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { L2BlockHash } from '@aztec/stdlib/block';
+import { TxHash } from '@aztec/stdlib/tx';
+
+import type { PrivateEvent } from '../../pxe.js';
+
+interface PrivateEventEntry {
+  msgContent: Buffer;
+  blockNumber: number;
+  blockHash: Buffer;
+  eventCommitmentIndex: number;
+  txHash: Buffer;
+}
+
+/**
+ * Stores decrypted private event logs.
+ */
+export class PrivateEventDataProvider {
+  #store: AztecAsyncKVStore;
+  /** Array storing the actual private event log entries containing the log content and block number */
+  #eventLogs: AztecAsyncArray<PrivateEventEntry>;
+  /** Map from contract_address_recipient_eventSelector to array of indices into #eventLogs for efficient lookup */
+  #eventLogIndex: AztecAsyncMap<string, number[]>;
+  /** Map from eventCommitmentIndex to boolean indicating if log has been seen. */
+  #seenLogs: AztecAsyncMap<number, boolean>;
+
+  logger = createLogger('private_event_data_provider');
+
+  constructor(store: AztecAsyncKVStore) {
+    this.#store = store;
+    this.#eventLogs = this.#store.openArray('private_event_logs');
+    this.#eventLogIndex = this.#store.openMap('private_event_log_index');
+    this.#seenLogs = this.#store.openMap('seen_logs');
+  }
+
+  /**
+   * Store a private event log.
+   * @param contractAddress - The address of the contract that emitted the event.
+   * @param recipient - The recipient of the event.
+   * @param eventSelector - The event selector of the event.
+   * @param msgContent - The content of the event.
+   * @param txHash - The transaction hash of the event log.
+   * @param eventCommitmentIndex - The index of the event commitment in the nullifier tree.
+   * @param blockNumber - The block number in which the event was emitted.
+   */
+  storePrivateEventLog(
+    contractAddress: AztecAddress,
+    recipient: AztecAddress,
+    eventSelector: EventSelector,
+    msgContent: Fr[],
+    txHash: TxHash,
+    eventCommitmentIndex: number,
+    blockNumber: number,
+    blockHash: L2BlockHash,
+  ): Promise<void> {
+    return this.#store.transactionAsync(async () => {
+      const key = `${contractAddress.toString()}_${recipient.toString()}_${eventSelector.toString()}`;
+
+      // Check if this exact log has already been stored using eventCommitmentIndex as unique identifier
+      const hasBeenSeen = await this.#seenLogs.getAsync(eventCommitmentIndex);
+      if (hasBeenSeen) {
+        this.logger.verbose('Ignoring duplicate event log', { txHash: txHash.toString(), eventCommitmentIndex });
+        return;
+      }
+
+      this.logger.verbose('storing private event log', { contractAddress, recipient, msgContent, blockNumber });
+
+      const index = await this.#eventLogs.lengthAsync();
+      await this.#eventLogs.push({
+        msgContent: serializeToBuffer(msgContent),
+        blockNumber,
+        blockHash: blockHash.toBuffer(),
+        eventCommitmentIndex,
+        txHash: txHash.toBuffer(),
+      });
+
+      const existingIndices = (await this.#eventLogIndex.getAsync(key)) || [];
+      await this.#eventLogIndex.set(key, [...existingIndices, index]);
+
+      // Mark this log as seen using eventCommitmentIndex
+      await this.#seenLogs.set(eventCommitmentIndex, true);
+    });
+  }
+
+  /**
+   * Returns the private events given search parameters.
+   * @param contractAddress - The address of the contract to get events from.
+   * @param from - The block number to search from.
+   * @param numBlocks - The amount of blocks to search.
+   * @param recipients - The addresses that decrypted the logs.
+   * @param eventSelector - The event selector to filter by.
+   * @returns - The event log contents.
+   */
+  public async getPrivateEvents(
+    contractAddress: AztecAddress,
+    from: number,
+    numBlocks: number,
+    recipients: AztecAddress[],
+    eventSelector: EventSelector,
+  ): Promise<PrivateEvent[]> {
+    const events: Array<{ eventCommitmentIndex: number; event: PrivateEvent }> = [];
+
+    for (const recipient of recipients) {
+      const key = `${contractAddress.toString()}_${recipient.toString()}_${eventSelector.toString()}`;
+      const indices = (await this.#eventLogIndex.getAsync(key)) || [];
+
+      for (const index of indices) {
+        const entry = await this.#eventLogs.atAsync(index);
+        if (!entry || entry.blockNumber < from || entry.blockNumber >= from + numBlocks) {
+          continue;
+        }
+
+        // Convert buffer back to Fr array
+        const reader = BufferReader.asReader(entry.msgContent);
+        const numFields = entry.msgContent.length / Fr.SIZE_IN_BYTES;
+        const msgContent = reader.readArray(numFields, Fr);
+        const txHash = TxHash.fromBuffer(entry.txHash);
+        const blockHash = L2BlockHash.fromBuffer(entry.blockHash);
+
+        events.push({
+          eventCommitmentIndex: entry.eventCommitmentIndex,
+          event: {
+            packedEvent: msgContent,
+            blockNumber: entry.blockNumber,
+            recipient,
+            txHash,
+            blockHash,
+            eventSelector,
+          },
+        });
+      }
+    }
+
+    // Sort by eventCommitmentIndex only
+    events.sort((a, b) => a.eventCommitmentIndex - b.eventCommitmentIndex);
+    return events.map(ev => ev.event);
+  }
+}

package/src/storage/sync_data_provider/sync_data_provider.ts

@@ -1,9 +1,7 @@
 import type { AztecAsyncKVStore, AztecAsyncSingleton } from '@aztec/kv-store';
 import { BlockHeader } from '@aztec/stdlib/tx';
 
-import type { DataProvider } from '../data_provider.js';
-
-export class SyncDataProvider implements DataProvider {
+export class SyncDataProvider {
   #store: AztecAsyncKVStore;
   #synchronizedHeader: AztecAsyncSingleton<Buffer>;
 
@@ -16,13 +14,13 @@ export class SyncDataProvider implements DataProvider {
     await this.#synchronizedHeader.set(header.toBuffer());
   }
 
-  async getBlockNumber(): Promise<number | undefined> {
+  async getBlockNumber(): Promise<number> {
     const headerBuffer = await this.#synchronizedHeader.getAsync();
     if (!headerBuffer) {
-      return undefined;
+      throw new Error(`Trying to get block number with a not-yet-synchronized PXE - this should never happen`);
     }
 
-    return Number(BlockHeader.fromBuffer(headerBuffer).globalVariables.blockNumber.toBigInt());
+    return BlockHeader.fromBuffer(headerBuffer).globalVariables.blockNumber;
   }
 
   async getBlockHeader(): Promise<BlockHeader> {
@@ -33,8 +31,4 @@ export class SyncDataProvider implements DataProvider {
 
     return BlockHeader.fromBuffer(headerBuffer);
   }
-
-  async getSize(): Promise<number> {
-    return (await this.#synchronizedHeader.getAsync())?.length ?? 0;
-  }
 }