@aztec/pxe 0.0.1-commit.d3ec352c → 0.0.1-commit.e6bd8901

package/dest/storage/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA,cAAc,kCAAkC,CAAC;AACjD,cAAc,kCAAkC,CAAC;AACjD,cAAc,mCAAmC,CAAC;AAClD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,kCAAkC,CAAC;AACjD,cAAc,eAAe,CAAC;AAC9B,cAAc,8DAA8D,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,eAAe,CAAC;AAC9B,cAAc,8CAA8C,CAAC"}

package/dest/storage/index.js

@@ -1,8 +1,8 @@
-export * from './address_data_provider/index.js';
-export * from './capsule_data_provider/index.js';
-export * from './contract_data_provider/index.js';
-export * from './note_data_provider/index.js';
-export * from './sync_data_provider/index.js';
-export * from './tagging_data_provider/index.js';
+export * from './address_store/index.js';
+export * from './capsule_store/index.js';
+export * from './contract_store/index.js';
+export * from './note_store/index.js';
+export * from './anchor_block_store/index.js';
+export * from './tagging_store/index.js';
 export * from './metadata.js';
-export * from './private_event_data_provider/private_event_data_provider.js';
+export * from './private_event_store/private_event_store.js';

package/dest/storage/note_store/index.d.ts

@@ -0,0 +1,3 @@
+export { NoteDao } from '@aztec/stdlib/note';
+export { NoteStore } from './note_store.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9zdG9yYWdlL25vdGVfc3RvcmUvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLE9BQU8sRUFBRSxNQUFNLG9CQUFvQixDQUFDO0FBQzdDLE9BQU8sRUFBRSxTQUFTLEVBQUUsTUFBTSxpQkFBaUIsQ0FBQyJ9

package/dest/storage/note_store/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/storage/note_store/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC"}

package/dest/storage/note_store/index.js

@@ -0,0 +1,2 @@
+export { NoteDao } from '@aztec/stdlib/note';
+export { NoteStore } from './note_store.js';

package/dest/storage/note_store/note_store.d.ts

@@ -0,0 +1,73 @@
+import type { Fr } from '@aztec/foundation/schemas';
+import type { AztecAsyncKVStore } from '@aztec/kv-store';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { DataInBlock } from '@aztec/stdlib/block';
+import { NoteDao, type NotesFilter } from '@aztec/stdlib/note';
+import type { StagedStore } from '../../job_coordinator/job_coordinator.js';
+/**
+ * NoteStore 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 declare class NoteStore implements StagedStore {
+    #private;
+    readonly storeName: string;
+    constructor(store: AztecAsyncKVStore);
+    /**
+     * Adds multiple notes to the notes store under the specified scope.
+     *
+     * Notes are stored using their siloedNullifier as the key, which provides uniqueness. 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
+     * @param jobId - The job context for staged writes
+     */
+    addNotes(notes: NoteDao[], scope: AztecAddress, jobId: string): Promise<void[]>;
+    /**
+     * 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 owner,
+     *                 storageSlot, status, scopes, and siloedNullifier.
+     * @params jobId - the job context to read from.
+     * @returns Filtered and deduplicated notes (a note might be present in multiple scopes - we ensure it is only
+     * returned once if this is the case)
+     * @throws If filtering by an empty scopes array. Scopes have to be set to undefined or to a non-empty array.
+     */
+    getNotes(filter: NotesFilter, jobId: string): 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.
+     *
+     * applyNullifiers is idempotent: the same nullifier can be applied multiple times without error.
+     * This relaxes constraints on usage of NoteService#validateAndStoreNote, which can then be run concurrently in a Promise.all
+     * context without risking unnecessarily defensive checks failing.
+     *
+     * @param nullifiers - Array of nullifiers with their block numbers to process
+     * @param jobId - The job context for staged writes
+     * @returns Array of NoteDao objects that were nullified
+     * @throws Error if any nullifier is not found in this notes store
+     */
+    applyNullifiers(nullifiers: DataInBlock<Fr>[], jobId: string): Promise<NoteDao[]>;
+    /**
+     * 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.
+     *
+     * IMPORTANT: This method must be called within a transaction to ensure atomicity.
+     *
+     * @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.
+     */
+    rollback(blockNumber: number, synchedBlockNumber: number): Promise<void>;
+    commit(jobId: string): Promise<void>;
+    discardStaged(jobId: string): Promise<void>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibm90ZV9zdG9yZS5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL3N0b3JhZ2Uvbm90ZV9zdG9yZS9ub3RlX3N0b3JlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUVBLE9BQU8sS0FBSyxFQUFFLEVBQUUsRUFBRSxNQUFNLDJCQUEyQixDQUFDO0FBQ3BELE9BQU8sS0FBSyxFQUFFLGlCQUFpQixFQUFxQyxNQUFNLGlCQUFpQixDQUFDO0FBQzVGLE9BQU8sS0FBSyxFQUFFLFlBQVksRUFBRSxNQUFNLDZCQUE2QixDQUFDO0FBQ2hFLE9BQU8sS0FBSyxFQUFFLFdBQVcsRUFBRSxNQUFNLHFCQUFxQixDQUFDO0FBQ3ZELE9BQU8sRUFBRSxPQUFPLEVBQWMsS0FBSyxXQUFXLEVBQUUsTUFBTSxvQkFBb0IsQ0FBQztBQUUzRSxPQUFPLEtBQUssRUFBRSxXQUFXLEVBQUUsTUFBTSwwQ0FBMEMsQ0FBQztBQUc1RTs7Ozs7SUFLSTtBQUNKLHFCQUFhLFNBQVUsWUFBVyxXQUFXOztJQUMzQyxRQUFRLENBQUMsU0FBUyxFQUFFLE1BQU0sQ0FBVTtJQStCcEMsWUFBWSxLQUFLLEVBQUUsaUJBQWlCLEVBUW5DO0lBRUQ7Ozs7Ozs7OztPQVNHO0lBQ0ksUUFBUSxDQUFDLEtBQUssRUFBRSxPQUFPLEVBQUUsRUFBRSxLQUFLLEVBQUUsWUFBWSxFQUFFLEtBQUssRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLElBQUksRUFBRSxDQUFDLENBRXJGO0lBK0JEOzs7Ozs7Ozs7OztPQVdHO0lBQ0csUUFBUSxDQUFDLE1BQU0sRUFBRSxXQUFXLEVBQUUsS0FBSyxFQUFFLE1BQU0sR0FBRyxPQUFPLENBQUMsT0FBTyxFQUFFLENBQUMsQ0FvRHJFO0lBRUQ7Ozs7Ozs7Ozs7Ozs7O09BY0c7SUFDSCxlQUFlLENBQUMsVUFBVSxFQUFFLFdBQVcsQ0FBQyxFQUFFLENBQUMsRUFBRSxFQUFFLEtBQUssRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLE9BQU8sRUFBRSxDQUFDLENBc0NoRjtJQUVEOzs7Ozs7Ozs7OztPQVdHO0lBQ1UsUUFBUSxDQUFDLFdBQVcsRUFBRSxNQUFNLEVBQUUsa0JBQWtCLEVBQUUsTUFBTSxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FNcEY7SUEwRUQsTUFBTSxDQUFDLEtBQUssRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQVluQztJQUVELGFBQWEsQ0FBQyxLQUFLLEVBQUUsTUFBTSxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FFMUM7Q0FpREYifQ==

package/dest/storage/note_store/note_store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"note_store.d.ts","sourceRoot":"","sources":["../../../src/storage/note_store/note_store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,2BAA2B,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAqC,MAAM,iBAAiB,CAAC;AAC5F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,OAAO,EAAc,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAE3E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0CAA0C,CAAC;AAG5E;;;;;IAKI;AACJ,qBAAa,SAAU,YAAW,WAAW;;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAU;IA+BpC,YAAY,KAAK,EAAE,iBAAiB,EAQnC;IAED;;;;;;;;;OASG;IACI,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAErF;IA+BD;;;;;;;;;;;OAWG;IACG,QAAQ,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAoDrE;IAED;;;;;;;;;;;;;;OAcG;IACH,eAAe,CAAC,UAAU,EAAE,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAsChF;IAED;;;;;;;;;;;OAWG;IACU,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMpF;IA0ED,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAYnC;IAED,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1C;CAiDF"}

package/dest/storage/note_store/note_store.js

@@ -0,0 +1,303 @@
+import { toArray } from '@aztec/foundation/iterable';
+import { Semaphore } from '@aztec/foundation/queue';
+import { NoteStatus } from '@aztec/stdlib/note';
+import { StoredNote } from './stored_note.js';
+/**
+ * NoteStore 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 NoteStore {
+    storeName = 'note';
+    #store;
+    // Note that we use the siloedNullifier as the note id in the store as it's guaranteed to be unique.
+    // Main storage for notes. Avoid performing full scans on it as it contains all notes PXE knows, use
+    // #nullifiersByContractAddress or #nullifiersByNullificationBlockNumber to find relevant note nullifiers that can be
+    // used to read into this map instead.
+    // nullifier => StoredNote (serialized)
+    #notes;
+    // Indexes which notes (via their nullifiers) belong to a contract. Used in `getNotes` to reduce the amount of notes
+    // checked.
+    // contract address => nullifier
+    #nullifiersByContractAddress;
+    // Groups note nullifiers by the block number they were added to the nullifier tree. Used in `rollback` to handle
+    // re-orgs.
+    // block number => nullifier (block number in which nullifier is included)
+    #nullifiersByNullificationBlockNumber;
+    // In-memory changes performed during a not-yet committed job. When `commit` is called with said job's id, these
+    // changes are persisted in the DB maps specified above and cleared.
+    // jobId => nullifier => StoredNote (serialized)
+    #notesForJob;
+    // Per job locks to prevent multiple concurrent writes to affect each other.
+    // jobId => lock
+    #jobLocks;
+    constructor(store){
+        this.#store = store;
+        this.#notes = store.openMap('notes');
+        this.#nullifiersByContractAddress = store.openMultiMap('note_nullifiers_by_contract');
+        this.#nullifiersByNullificationBlockNumber = store.openMultiMap('note_block_number_to_nullifier');
+        this.#jobLocks = new Map();
+        this.#notesForJob = new Map();
+    }
+    /**
+   * Adds multiple notes to the notes store under the specified scope.
+   *
+   * Notes are stored using their siloedNullifier as the key, which provides uniqueness. 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
+   * @param jobId - The job context for staged writes
+   */ addNotes(notes, scope, jobId) {
+        return this.#withJobLock(jobId, ()=>Promise.all(notes.map((noteDao)=>this.#addNote(noteDao, scope, jobId))));
+    }
+    async #addNote(note, scope, jobId) {
+        const noteForJob = await this.#readNote(note.siloedNullifier.toString(), jobId) ?? new StoredNote(note, new Set());
+        // Make sure the note is linked to the scope and staged for this job
+        noteForJob.addScope(scope.toString());
+        this.#writeNote(noteForJob, jobId);
+    }
+    async #readNote(nullifier, jobId) {
+        // First check staged notes for this job
+        const noteForJob = this.#getNotesForJob(jobId).get(nullifier);
+        if (noteForJob) {
+            return noteForJob;
+        }
+        // Then check persistent storage
+        const noteBuffer = await this.#notes.getAsync(nullifier);
+        if (noteBuffer) {
+            return StoredNote.fromBuffer(noteBuffer);
+        }
+        return undefined;
+    }
+    #writeNote(note, jobId) {
+        this.#getNotesForJob(jobId).set(note.noteDao.siloedNullifier.toString(), note);
+    }
+    /**
+   * 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 owner,
+   *                 storageSlot, status, scopes, and siloedNullifier.
+   * @params jobId - the job context to read from.
+   * @returns Filtered and deduplicated notes (a note might be present in multiple scopes - we ensure it is only
+   * returned once if this is the case)
+   * @throws If filtering by an empty scopes array. Scopes have to be set to undefined or to a non-empty array.
+   */ async getNotes(filter, jobId) {
+        if (filter.scopes !== undefined && filter.scopes.length === 0) {
+            throw new Error('Trying to get notes with an empty scopes array');
+        }
+        const targetStatus = filter.status ?? NoteStatus.ACTIVE;
+        const foundNotes = new Map();
+        const nullifiersOfContract = await this.#nullifiersOfContract(filter.contractAddress, jobId);
+        for (const nullifier of nullifiersOfContract){
+            const note = await this.#readNote(nullifier, jobId);
+            // Defensive: hitting this case means we're mishandling contract indices or in-memory job data
+            if (!note) {
+                throw new Error('PXE note database is corrupted.');
+            }
+            // Apply filters
+            if (targetStatus === NoteStatus.ACTIVE && note.isNullified()) {
+                continue;
+            }
+            if (filter.owner && !note.noteDao.owner.equals(filter.owner)) {
+                continue;
+            }
+            if (filter.storageSlot && !note.noteDao.storageSlot.equals(filter.storageSlot)) {
+                continue;
+            }
+            if (filter.siloedNullifier && !note.noteDao.siloedNullifier.equals(filter.siloedNullifier)) {
+                continue;
+            }
+            if (filter.scopes && note.scopes.intersection(new Set(filter.scopes.map((s)=>s.toString()))).size === 0) {
+                continue;
+            }
+            foundNotes.set(note.noteDao.siloedNullifier.toString(), note.noteDao);
+        }
+        // Sort by block number, then by tx index within block, then by note index within tx
+        return [
+            ...foundNotes.values()
+        ].sort((a, b)=>{
+            if (a.l2BlockNumber !== b.l2BlockNumber) {
+                return a.l2BlockNumber - b.l2BlockNumber;
+            }
+            if (a.txIndexInBlock !== b.txIndexInBlock) {
+                return a.txIndexInBlock - b.txIndexInBlock;
+            }
+            return a.noteIndexInTx - b.noteIndexInTx;
+        });
+    }
+    /**
+   * 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.
+   *
+   * applyNullifiers is idempotent: the same nullifier can be applied multiple times without error.
+   * This relaxes constraints on usage of NoteService#validateAndStoreNote, which can then be run concurrently in a Promise.all
+   * context without risking unnecessarily defensive checks failing.
+   *
+   * @param nullifiers - Array of nullifiers with their block numbers to process
+   * @param jobId - The job context for staged writes
+   * @returns Array of NoteDao objects that were nullified
+   * @throws Error if any nullifier is not found in this notes store
+   */ applyNullifiers(nullifiers, jobId) {
+        return this.#withJobLock(jobId, ()=>this.#store.transactionAsync(async ()=>{
+                if (nullifiers.length === 0) {
+                    return [];
+                }
+                const notesToNullify = await Promise.all(nullifiers.map(async (nullifierInBlock)=>{
+                    const nullifier = nullifierInBlock.data.toString();
+                    const storedNote = await this.#readNote(nullifier, jobId);
+                    if (!storedNote) {
+                        throw new Error(`Attempted to mark a note as nullified which does not exist in PXE DB`);
+                    }
+                    return {
+                        storedNote: await this.#readNote(nullifier, jobId),
+                        blockNumber: nullifierInBlock.l2BlockNumber
+                    };
+                }));
+                const notesNullifiedInThisCall = new Map();
+                for (const noteToNullify of notesToNullify){
+                    // Safe to coerce (!) because we throw if we find any undefined above
+                    const note = noteToNullify.storedNote;
+                    // Skip already nullified notes
+                    if (note.isNullified()) {
+                        continue;
+                    }
+                    note.markAsNullified(noteToNullify.blockNumber);
+                    this.#writeNote(note, jobId);
+                    notesNullifiedInThisCall.set(note.noteDao.siloedNullifier.toString(), note.noteDao);
+                }
+                return [
+                    ...notesNullifiedInThisCall.values()
+                ];
+            }));
+    }
+    /**
+   * 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.
+   *
+   * IMPORTANT: This method must be called within a transaction to ensure atomicity.
+   *
+   * @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.
+   */ async rollback(blockNumber, synchedBlockNumber) {
+        if (this.#notesForJob.size > 0) {
+            throw new Error('PXE note store rollback is not allowed while jobs are running');
+        }
+        await this.#rewindNullifiedNotesAfterBlock(blockNumber, synchedBlockNumber);
+        await this.#deleteActiveNotesAfterBlock(blockNumber);
+    }
+    /**
+   * Deletes (removes) all notes created after the specified block number.
+   *
+   * Permanently delete notes from the notes store, e.g. during a reorg.
+   *
+   * @param blockNumber - Notes created after this block number will be deleted
+   */ async #deleteActiveNotesAfterBlock(blockNumber) {
+        const notes = await toArray(this.#notes.valuesAsync());
+        for (const noteBuffer of notes){
+            const storedNote = StoredNote.fromBuffer(noteBuffer);
+            if (storedNote.noteDao.l2BlockNumber > blockNumber) {
+                const noteNullifier = storedNote.noteDao.siloedNullifier.toString();
+                await this.#notes.delete(noteNullifier);
+                await this.#nullifiersByContractAddress.deleteValue(storedNote.noteDao.contractAddress.toString(), noteNullifier);
+            }
+        }
+    }
+    /**
+   * Rewinds nullifications after a given block number.
+   *
+   * This operation "un-nullifies" notes, rolling back nullifications that occurred in orphaned blocks, e.g. during a
+   * reorg.
+   *
+   * @param blockNumber - Revert nullifications that occurred after this block
+   * @param anchorBlockNumber - Upper bound for the block range to process
+   */ async #rewindNullifiedNotesAfterBlock(blockNumber, anchorBlockNumber) {
+        const currentBlockNumber = blockNumber + 1;
+        for(let i = currentBlockNumber; i <= anchorBlockNumber; i++){
+            const noteNullifiersToReinsert = await toArray(this.#nullifiersByNullificationBlockNumber.getValuesAsync(i));
+            const nullifiedNoteBuffers = await Promise.all(noteNullifiersToReinsert.map(async (noteNullifier)=>{
+                const note = await this.#notes.getAsync(noteNullifier);
+                if (!note) {
+                    throw new Error(`PXE DB integrity error: no note found with nullifier ${noteNullifier}`);
+                }
+                return note;
+            }));
+            const storedNotes = nullifiedNoteBuffers.map((buffer)=>StoredNote.fromBuffer(buffer));
+            for (const storedNote of storedNotes){
+                const noteNullifier = storedNote.noteDao.siloedNullifier.toString();
+                const scopes = storedNote.scopes;
+                if (scopes.size === 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(`No scopes found for nullified note with nullifier ${noteNullifier}`);
+                }
+                storedNote.markAsActive();
+                await Promise.all([
+                    this.#notes.set(noteNullifier, storedNote.toBuffer()),
+                    this.#nullifiersByNullificationBlockNumber.deleteValue(i, noteNullifier)
+                ]);
+            }
+        }
+    }
+    commit(jobId) {
+        return this.#withJobLock(jobId, async ()=>{
+            for (const [nullifier, storedNote] of this.#getNotesForJob(jobId)){
+                await this.#notes.set(nullifier, storedNote.toBuffer());
+                await this.#nullifiersByContractAddress.set(storedNote.noteDao.contractAddress.toString(), nullifier);
+                if (storedNote.nullifiedAt !== undefined) {
+                    await this.#nullifiersByNullificationBlockNumber.set(storedNote.nullifiedAt, nullifier);
+                }
+            }
+            this.#clearJobData(jobId);
+        });
+    }
+    discardStaged(jobId) {
+        return this.#withJobLock(jobId, ()=>Promise.resolve(this.#clearJobData(jobId)));
+    }
+    #clearJobData(jobId) {
+        this.#notesForJob.delete(jobId);
+        this.#jobLocks.delete(jobId);
+    }
+    /**
+   * Functions run withJobLock are forced to wait for each other, i.e. if they share a `jobId`, they run serially
+   * instead of concurrently. This is needed because staged data is stored in memory, and concurrent async operations
+   * (e.g., Promise.all in `validateAndStoreNote`) could otherwise interleave and corrupt state.
+   */ async #withJobLock(jobId, fn) {
+        let lock = this.#jobLocks.get(jobId);
+        if (!lock) {
+            lock = new Semaphore(1);
+            this.#jobLocks.set(jobId, lock);
+        }
+        await lock.acquire();
+        try {
+            return await fn();
+        } finally{
+            lock.release();
+        }
+    }
+    #getNotesForJob(jobId) {
+        let notesForJob = this.#notesForJob.get(jobId);
+        if (!notesForJob) {
+            notesForJob = new Map();
+            this.#notesForJob.set(jobId, notesForJob);
+        }
+        return notesForJob;
+    }
+    async #nullifiersOfContract(contractAddress, jobId) {
+        // Collect persisted nullifiers for this contract
+        const persistedNullifiers = await toArray(this.#nullifiersByContractAddress.getValuesAsync(contractAddress.toString()));
+        // Collect staged nullifiers from the job where the note's contract matches
+        const stagedNullifiers = this.#getNotesForJob(jobId).values().filter((storedNote)=>storedNote.noteDao.contractAddress.equals(contractAddress)).map((storedNote)=>storedNote.noteDao.siloedNullifier.toString());
+        return new Set([
+            ...persistedNullifiers,
+            ...stagedNullifiers
+        ]);
+    }
+}

package/dest/storage/note_store/stored_note.d.ts

@@ -0,0 +1,16 @@
+import { BlockNumber } from '@aztec/foundation/branded-types';
+import { NoteDao } from '@aztec/stdlib/note';
+export declare class StoredNote {
+    readonly noteDao: NoteDao;
+    readonly scopes: Set<string>;
+    private _nullifiedAt;
+    constructor(noteDao: NoteDao, scopes: Set<string>, _nullifiedAt?: BlockNumber | undefined);
+    static fromBuffer(buffer: Buffer): StoredNote;
+    toBuffer(): Buffer;
+    addScope(scope: string): void;
+    markAsNullified(blockNumber: BlockNumber): void;
+    markAsActive(): void;
+    isNullified(): boolean;
+    get nullifiedAt(): BlockNumber | undefined;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3RvcmVkX25vdGUuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9zdG9yYWdlL25vdGVfc3RvcmUvc3RvcmVkX25vdGUudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLFdBQVcsRUFBRSxNQUFNLGlDQUFpQyxDQUFDO0FBRTlELE9BQU8sRUFBRSxPQUFPLEVBQUUsTUFBTSxvQkFBb0IsQ0FBQztBQUU3QyxxQkFBYSxVQUFVO0lBRW5CLFFBQVEsQ0FBQyxPQUFPLEVBQUUsT0FBTztJQUN6QixRQUFRLENBQUMsTUFBTSxFQUFFLEdBQUcsQ0FBQyxNQUFNLENBQUM7SUFDNUIsT0FBTyxDQUFDLFlBQVk7SUFIdEIsWUFDVyxPQUFPLEVBQUUsT0FBTyxFQUNoQixNQUFNLEVBQUUsR0FBRyxDQUFDLE1BQU0sQ0FBQyxFQUNwQixZQUFZLEdBQUUsV0FBVyxHQUFHLFNBQXFCLEVBQ3ZEO0lBRUosTUFBTSxDQUFDLFVBQVUsQ0FBQyxNQUFNLEVBQUUsTUFBTSxjQVUvQjtJQUVELFFBQVEsSUFBSSxNQUFNLENBR2pCO0lBRUQsUUFBUSxDQUFDLEtBQUssRUFBRSxNQUFNLFFBRXJCO0lBRUQsZUFBZSxDQUFDLFdBQVcsRUFBRSxXQUFXLFFBRXZDO0lBRUQsWUFBWSxTQUVYO0lBRUQsV0FBVyxZQUVWO0lBRUQsSUFBSSxXQUFXLDRCQUVkO0NBQ0YifQ==

package/dest/storage/note_store/stored_note.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stored_note.d.ts","sourceRoot":"","sources":["../../../src/storage/note_store/stored_note.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAE9D,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE7C,qBAAa,UAAU;IAEnB,QAAQ,CAAC,OAAO,EAAE,OAAO;IACzB,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC;IAC5B,OAAO,CAAC,YAAY;IAHtB,YACW,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,EACpB,YAAY,GAAE,WAAW,GAAG,SAAqB,EACvD;IAEJ,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,cAU/B;IAED,QAAQ,IAAI,MAAM,CAGjB;IAED,QAAQ,CAAC,KAAK,EAAE,MAAM,QAErB;IAED,eAAe,CAAC,WAAW,EAAE,WAAW,QAEvC;IAED,YAAY,SAEX;IAED,WAAW,YAEV;IAED,IAAI,WAAW,4BAEd;CACF"}

package/dest/storage/note_store/stored_note.js

@@ -0,0 +1,43 @@
+import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
+import { NoteDao } from '@aztec/stdlib/note';
+export class StoredNote {
+    noteDao;
+    scopes;
+    _nullifiedAt;
+    constructor(noteDao, scopes, _nullifiedAt = undefined){
+        this.noteDao = noteDao;
+        this.scopes = scopes;
+        this._nullifiedAt = _nullifiedAt;
+    }
+    static fromBuffer(buffer) {
+        const reader = BufferReader.asReader(buffer);
+        const noteDao = NoteDao.fromBuffer(reader);
+        const scopes = reader.readVector({
+            fromBuffer: (r)=>r.readString()
+        });
+        const nullifiedAtRaw = reader.readNumber();
+        const nullifiedAt = nullifiedAtRaw === 0 ? undefined : nullifiedAtRaw;
+        return new StoredNote(noteDao, new Set(scopes), nullifiedAt);
+    }
+    toBuffer() {
+        const scopesArray = [
+            ...this.scopes
+        ];
+        return serializeToBuffer(this.noteDao, scopesArray.length, ...scopesArray, this._nullifiedAt ?? 0);
+    }
+    addScope(scope) {
+        this.scopes.add(scope);
+    }
+    markAsNullified(blockNumber) {
+        this._nullifiedAt = blockNumber;
+    }
+    markAsActive() {
+        this._nullifiedAt = undefined;
+    }
+    isNullified() {
+        return this._nullifiedAt !== undefined;
+    }
+    get nullifiedAt() {
+        return this._nullifiedAt;
+    }
+}

package/dest/storage/private_event_store/private_event_store.d.ts

@@ -0,0 +1,91 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+import type { AztecAsyncKVStore } from '@aztec/kv-store';
+import type { EventSelector } from '@aztec/stdlib/abi';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { InTx, TxHash } from '@aztec/stdlib/tx';
+import type { StagedStore } from '../../job_coordinator/job_coordinator.js';
+import type { PackedPrivateEvent } from '../../pxe.js';
+export type PrivateEventStoreFilter = {
+    contractAddress: AztecAddress;
+    fromBlock: number;
+    toBlock: number;
+    scopes: AztecAddress[];
+    txHash?: TxHash;
+};
+type PrivateEventMetadata = InTx & {
+    contractAddress: AztecAddress;
+    scope: AztecAddress;
+    /** The index of the tx within the block */
+    txIndexInBlock: number;
+    /** The index of the event within the tx (based on nullifier position) */
+    eventIndexInTx: number;
+};
+/**
+ * Stores decrypted private event logs.
+ */
+export declare class PrivateEventStore implements StagedStore {
+    #private;
+    readonly storeName: string;
+    logger: import("@aztec/foundation/log").Logger;
+    constructor(store: AztecAsyncKVStore);
+    /**
+     * Store a private event log.
+     * @param eventSelector - The event selector of the event.
+     * @param randomness - The randomness used for the event commitment.
+     * @param msgContent - The content of the event.
+     * @param siloedEventCommitment - The siloed event commitment (used as unique identifier).
+     * @param metadata
+     *  contractAddress - The address of the contract that emitted the event.
+     *  scope - The address to which the event is scoped.
+     *  txHash - The transaction hash of the event log.
+     *  blockNumber - The block number in which the event was emitted.
+     */
+    storePrivateEventLog(eventSelector: EventSelector, randomness: Fr, msgContent: Fr[], siloedEventCommitment: Fr, metadata: PrivateEventMetadata, jobId: string): Promise<void>;
+    /**
+     * Returns the private events given search parameters.
+     * @param eventSelector - The event selector to filter by.
+     * @param filter - Filtering criteria:
+     *  contractAddress: The address of the contract to get events from.
+     *  fromBlock: The block number to search from (inclusive).
+     *  toBlock: The block number to search upto (exclusive).
+     *  scope: - The addresses that decrypted the logs.
+     * @returns - The event log contents, augmented with metadata about the transaction and block in which the event was
+     * included.
+     */
+    getPrivateEvents(eventSelector: EventSelector, filter: PrivateEventStoreFilter): Promise<PackedPrivateEvent[]>;
+    /**
+     * Rolls back private events that were stored after a given `blockNumber` and up to `synchedBlockNumber` (the block
+     * number up to which PXE managed to sync before the reorg happened).
+     *
+     * We don't need staged writes for a rollback since it's handled in the context of a blockchain rewind.
+     *
+     * Rollbacks are handled by the BlockSynchronizer, which runs a DB transaction across stores when it detects a
+     * re-org, including setting the new anchor block after rolling back.
+     *
+     * So if anything fails in the process of rolling back any store, all DB changes occurring during rollbacks will be
+     * lost and the anchor block will not be updated; which means this code will eventually need to run again
+     * (i.e.: PXE will detect it's basing it work on an invalid block hash, then which re-triggers rewind).
+     *
+     * For further details, refer to `BlockSynchronizer#handleBlockStreamEvent`.
+     *
+     * IMPORTANT: This method must be called within a transaction to ensure atomicity.
+     */
+    rollback(blockNumber: number, synchedBlockNumber: number): Promise<void>;
+    /**
+     * Commits in memory job data to persistent storage.
+     *
+     * Called by JobCoordinator when a job completes successfully.
+     *
+     * Note: JobCoordinator wraps all commits in a single transaction, so we don't need our own transactionAsync here
+     * (and using one would throw on IndexedDB as it does not support nested txs).
+     *
+     * @param jobId - The jobId identifying which staged data to commit
+     */
+    commit(jobId: string): Promise<void>;
+    /**
+     * Discards in memory job data without persisting it.
+     */
+    discardStaged(jobId: string): Promise<void>;
+}
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicHJpdmF0ZV9ldmVudF9zdG9yZS5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL3N0b3JhZ2UvcHJpdmF0ZV9ldmVudF9zdG9yZS9wcml2YXRlX2V2ZW50X3N0b3JlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUNBLE9BQU8sRUFBRSxFQUFFLEVBQUUsTUFBTSxnQ0FBZ0MsQ0FBQztBQUlwRCxPQUFPLEtBQUssRUFBRSxpQkFBaUIsRUFBcUMsTUFBTSxpQkFBaUIsQ0FBQztBQUM1RixPQUFPLEtBQUssRUFBRSxhQUFhLEVBQUUsTUFBTSxtQkFBbUIsQ0FBQztBQUN2RCxPQUFPLEtBQUssRUFBRSxZQUFZLEVBQUUsTUFBTSw2QkFBNkIsQ0FBQztBQUNoRSxPQUFPLEtBQUssRUFBRSxJQUFJLEVBQUUsTUFBTSxFQUFFLE1BQU0sa0JBQWtCLENBQUM7QUFFckQsT0FBTyxLQUFLLEVBQUUsV0FBVyxFQUFFLE1BQU0sMENBQTBDLENBQUM7QUFDNUUsT0FBTyxLQUFLLEVBQUUsa0JBQWtCLEVBQUUsTUFBTSxjQUFjLENBQUM7QUFHdkQsTUFBTSxNQUFNLHVCQUF1QixHQUFHO0lBQ3BDLGVBQWUsRUFBRSxZQUFZLENBQUM7SUFDOUIsU0FBUyxFQUFFLE1BQU0sQ0FBQztJQUNsQixPQUFPLEVBQUUsTUFBTSxDQUFDO0lBQ2hCLE1BQU0sRUFBRSxZQUFZLEVBQUUsQ0FBQztJQUN2QixNQUFNLENBQUMsRUFBRSxNQUFNLENBQUM7Q0FDakIsQ0FBQztBQUVGLEtBQUssb0JBQW9CLEdBQUcsSUFBSSxHQUFHO0lBQ2pDLGVBQWUsRUFBRSxZQUFZLENBQUM7SUFDOUIsS0FBSyxFQUFFLFlBQVksQ0FBQztJQUNwQiwyQ0FBMkM7SUFDM0MsY0FBYyxFQUFFLE1BQU0sQ0FBQztJQUN2Qix5RUFBeUU7SUFDekUsY0FBYyxFQUFFLE1BQU0sQ0FBQztDQUN4QixDQUFDO0FBRUY7O0dBRUc7QUFDSCxxQkFBYSxpQkFBa0IsWUFBVyxXQUFXOztJQUNuRCxRQUFRLENBQUMsU0FBUyxFQUFFLE1BQU0sQ0FBbUI7SUFnQjdDLE1BQU0seUNBQXVDO0lBRTdDLFlBQVksS0FBSyxFQUFFLGlCQUFpQixFQVFuQztJQUVEOzs7Ozs7Ozs7OztPQVdHO0lBQ0gsb0JBQW9CLENBQ2xCLGFBQWEsRUFBRSxhQUFhLEVBQzVCLFVBQVUsRUFBRSxFQUFFLEVBQ2QsVUFBVSxFQUFFLEVBQUUsRUFBRSxFQUNoQixxQkFBcUIsRUFBRSxFQUFFLEVBQ3pCLFFBQVEsRUFBRSxvQkFBb0IsRUFDOUIsS0FBSyxFQUFFLE1BQU0saUJBdUNkO0lBRUQ7Ozs7Ozs7Ozs7T0FVRztJQUNJLGdCQUFnQixDQUNyQixhQUFhLEVBQUUsYUFBYSxFQUM1QixNQUFNLEVBQUUsdUJBQXVCLEdBQzlCLE9BQU8sQ0FBQyxrQkFBa0IsRUFBRSxDQUFDLENBcUUvQjtJQUVEOzs7Ozs7Ozs7Ozs7Ozs7O09BZ0JHO0lBQ1UsUUFBUSxDQUFDLFdBQVcsRUFBRSxNQUFNLEVBQUUsa0JBQWtCLEVBQUUsTUFBTSxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0E0QnBGO0lBRUQ7Ozs7Ozs7OztPQVNHO0lBQ0gsTUFBTSxDQUFDLEtBQUssRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQWVuQztJQUVEOztPQUVHO0lBQ0gsYUFBYSxDQUFDLEtBQUssRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQUUxQztDQTRFRiJ9

package/dest/storage/private_event_store/private_event_store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"private_event_store.d.ts","sourceRoot":"","sources":["../../../src/storage/private_event_store/private_event_store.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,EAAE,EAAE,MAAM,gCAAgC,CAAC;AAIpD,OAAO,KAAK,EAAE,iBAAiB,EAAqC,MAAM,iBAAiB,CAAC;AAC5F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAErD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0CAA0C,CAAC;AAC5E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGvD,MAAM,MAAM,uBAAuB,GAAG;IACpC,eAAe,EAAE,YAAY,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,KAAK,oBAAoB,GAAG,IAAI,GAAG;IACjC,eAAe,EAAE,YAAY,CAAC;IAC9B,KAAK,EAAE,YAAY,CAAC;IACpB,2CAA2C;IAC3C,cAAc,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF;;GAEG;AACH,qBAAa,iBAAkB,YAAW,WAAW;;IACnD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAmB;IAgB7C,MAAM,yCAAuC;IAE7C,YAAY,KAAK,EAAE,iBAAiB,EAQnC;IAED;;;;;;;;;;;OAWG;IACH,oBAAoB,CAClB,aAAa,EAAE,aAAa,EAC5B,UAAU,EAAE,EAAE,EACd,UAAU,EAAE,EAAE,EAAE,EAChB,qBAAqB,EAAE,EAAE,EACzB,QAAQ,EAAE,oBAAoB,EAC9B,KAAK,EAAE,MAAM,iBAuCd;IAED;;;;;;;;;;OAUG;IACI,gBAAgB,CACrB,aAAa,EAAE,aAAa,EAC5B,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAqE/B;IAED;;;;;;;;;;;;;;;;OAgBG;IACU,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA4BpF;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAenC;IAED;;OAEG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1C;CA4EF"}