@aztec/pxe 0.0.1-commit.d431d1c → 0.0.1-commit.d58ff9d0

package/dest/storage/note_store/note_store.js

@@ -1,317 +1,372 @@
-import { toArray } from '@aztec/foundation/iterable';
-import { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { createLogger } from '@aztec/foundation/log';
+import { Semaphore } from '@aztec/foundation/queue';
 import { NoteStatus } from '@aztec/stdlib/note';
-import { NoteDao } from '@aztec/stdlib/note';
+import { StoredNote } from './stored_note.js';
 /**
- * NoteStore manages the storage and retrieval of notes.
+ * NoteStore manages the storage and retrieval of notes using an append-only model.
  *
- * 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 {
+ * Notes are written once (keyed by siloedNullifier) and never mutated. They might be deleted in case of reorg though.
+ * Nullifier emissions are recorded as separate append-only entries: a map from nullifier to the number of the block
+ * that emitted it.
+ *
+ * Reorgs are handled by delete-on-prune: the `chain-pruned` event triggers deletion of every note and nullifier
+ * originating on a reorg'd block.
+ */ export class NoteStore {
+    storeName = 'note';
+    logger = createLogger('note_store');
     #store;
-    // Note that we use the siloedNullifier as the note id in the store as it's guaranteed to be unique.
-    /** noteId (siloedNullifier) -> NoteDao (serialized) */ #notes;
-    /** noteId (siloedNullifier) -> NoteDao (serialized) */ #nullifiedNotes;
-    /** blockNumber -> siloedNullifier */ #nullifiersByBlockNumber;
-    /** noteId (siloedNullifier) -> scope */ #nullifiedNotesToScope;
-    /** contractAddress -> noteId (siloedNullifier) */ #nullifiedNotesByContract;
-    /** storageSlot -> noteId (siloedNullifier) */ #nullifiedNotesByStorageSlot;
-    /** scope (AztecAddress) -> true */ #scopes;
-    /** noteId (siloedNullifier) -> scope */ #notesToScope;
-    /** scope -> MultiMap(contractAddress -> noteId) */ #notesByContractAndScope;
-    /** scope -> MultiMap(storageSlot -> noteId) */ #notesByStorageSlotAndScope;
+    // Note that we use the siloedNullifier as the note id in this 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 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
+    #notesByContractAddress;
+    // block number => nullifier
+    #notesByBlockNumber;
+    // Records, for each nullified note, the block number where its nullifier was emitted.
+    // nullifier => emission block number
+    #nullifierEmissions;
+    // Index of emitted nullifiers by block height, used for performance reasons upon reorgs.
+    // nullification block number => nullifier
+    #nullifierEmissionsByBlockNumber;
+    // 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
+    #notesForJob;
+    // Staged nullifier emissions per job.
+    // jobId => nullifier => emission block number
+    #nullifierEmissionsForJob;
+    // 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.#nullifiedNotes = store.openMap('nullified_notes');
-        this.#nullifiersByBlockNumber = store.openMultiMap('nullifier_to_block_number');
-        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.#scopes = store.openMap('scopes');
-        this.#notesToScope = store.openMultiMap('notes_to_scope');
-        this.#notesByContractAndScope = new Map();
-        this.#notesByStorageSlotAndScope = new Map();
-    }
-    /**
-   * Creates and initializes a new NoteStore instance.
-   *
-   * This factory method creates a NoteStore 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 NoteStore instance
-   */ static async create(store) {
-        const pxeDB = new NoteStore(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`));
-        }
-        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
-   */ async addScope(scope) {
-        const scopeString = scope.toString();
-        if (await this.#scopes.hasAsync(scopeString)) {
-            return false;
-        }
-        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`));
-        return true;
+        this.#notesByContractAddress = store.openMultiMap('note_nullifiers_by_contract');
+        this.#notesByBlockNumber = store.openMultiMap('note_nullifiers_by_block');
+        this.#nullifierEmissions = store.openMap('note_nullifications_by_nullifier');
+        this.#nullifierEmissionsByBlockNumber = store.openMultiMap('note_nullifications_by_block');
+        this.#jobLocks = new Map();
+        this.#notesForJob = new Map();
+        this.#nullifierEmissionsForJob = new Map();
     }
     /**
-   * Adds multiple notes to the data provider under the specified scope.
+   * 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.
+   * 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
-   */ addNotes(notes, scope) {
-        return this.#store.transactionAsync(async ()=>{
-            if (!await this.#scopes.hasAsync(scope.toString())) {
-                await this.addScope(scope);
-            }
-            for (const dao of notes){
-                const noteId = dao.siloedNullifier.toString();
-                await this.#notes.set(noteId, dao.toBuffer());
-                await this.#notesToScope.set(noteId, scope.toString());
-                await this.#notesByContractAndScope.get(scope.toString()).set(dao.contractAddress.toString(), noteId);
-                await this.#notesByStorageSlotAndScope.get(scope.toString()).set(dao.storageSlot.toString(), noteId);
-            }
-        });
+   * @param jobId - The job context for staged writes
+   */ addNotes(notes, scope, jobId) {
+        return this.#withJobLock(jobId, ()=>this.#store.transactionAsync(()=>Promise.all(notes.map(async (note)=>{
+                    const noteForJob = await this.#readNote(note.siloedNullifier.toString(), jobId) ?? new StoredNote(note, new Set());
+                    noteForJob.addScope(scope.toString());
+                    this.#writeNote(noteForJob, jobId);
+                }))));
     }
-    /**
-   * 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) {
-        await this.#rewindNullifiersAfterBlock(blockNumber, synchedBlockNumber);
-        await this.#deleteActiveNotesAfterBlock(blockNumber);
+    async #readNote(nullifier, jobId) {
+        // Always issue DB read to keep IndexedDB transaction alive (they auto-commit when a new micro-task starts and there
+        // are no pending read requests). The staged value still takes precedence if it exists.
+        const noteBuffer = await this.#notes.getAsync(nullifier);
+        const noteForJob = this.#getNotesForJob(jobId).get(nullifier);
+        return noteForJob ?? (noteBuffer ? StoredNote.fromBuffer(noteBuffer) : undefined);
     }
-    /**
-   * 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
-   */ async #deleteActiveNotesAfterBlock(blockNumber) {
-        const notes = await toArray(this.#notes.valuesAsync());
-        for (const note of notes){
-            const noteDao = NoteDao.fromBuffer(note);
-            if (noteDao.l2BlockNumber > blockNumber) {
-                const noteId = noteDao.siloedNullifier.toString();
-                await this.#notes.delete(noteId);
-                await this.#notesToScope.delete(noteId);
-                const scopes = await toArray(this.#scopes.keysAsync());
-                for (const scope of scopes){
-                    await this.#notesByContractAndScope.get(scope).deleteValue(noteDao.contractAddress.toString(), noteId);
-                    await this.#notesByStorageSlotAndScope.get(scope).deleteValue(noteDao.storageSlot.toString(), noteId);
-                }
-            }
-        }
+    #writeNote(note, jobId) {
+        this.#getNotesForJob(jobId).set(note.noteDao.siloedNullifier.toString(), note);
     }
     /**
-   * 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, synchedBlockNumber) {
-        const noteIdsToReinsert = [];
-        const currentBlockNumber = blockNumber + 1;
-        for(let i = currentBlockNumber; i <= synchedBlockNumber; i++){
-            // noteId === siloedNullifier.toString(), so we can use nullifiers directly as noteIds
-            noteIdsToReinsert.push(...await toArray(this.#nullifiersByBlockNumber.getValuesAsync(i)));
-        }
-        const nullifiedNoteBuffers = await Promise.all(noteIdsToReinsert.map((noteId)=>this.#nullifiedNotes.getAsync(noteId)));
-        const noteDaos = nullifiedNoteBuffers.filter((buffer)=>buffer != undefined).map((buffer)=>NoteDao.fromBuffer(buffer));
-        for (const dao of noteDaos){
-            const noteId = dao.siloedNullifier.toString();
-            const scopes = await toArray(this.#nullifiedNotesToScope.getValuesAsync(noteId));
-            if (scopes.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(`No scopes found for nullified note with nullifier ${noteId}`);
-            }
-            for (const scope of scopes){
-                await Promise.all([
-                    this.#notesByContractAndScope.get(scope.toString()).set(dao.contractAddress.toString(), noteId),
-                    this.#notesByStorageSlotAndScope.get(scope.toString()).set(dao.storageSlot.toString(), noteId),
-                    this.#notesToScope.set(noteId, scope)
-                ]);
-            }
-            await Promise.all([
-                this.#notes.set(noteId, dao.toBuffer()),
-                this.#nullifiedNotes.delete(noteId),
-                this.#nullifiedNotesToScope.delete(noteId),
-                this.#nullifiersByBlockNumber.deleteValue(dao.l2BlockNumber, dao.siloedNullifier.toString()),
-                this.#nullifiedNotesByContract.deleteValue(dao.contractAddress.toString(), noteId),
-                this.#nullifiedNotesByStorageSlot.deleteValue(dao.storageSlot.toString(), noteId)
-            ]);
-        }
+   * Reads the block number at which a note's nullifier was emitted, layering the current job's staged emission over
+   * committed state, the nullifier emission counterpart to {@link #readNote}. Returns the emission block number if the
+   * nullifier has been emitted (committed or staged in this job), or `undefined` if it has not.
+   */ async #readNullifierEmission(nullifier, jobId) {
+        // Always issue the DB read to keep the IndexedDB transaction alive (see #readNote); the staged emission still takes
+        // precedence if present.
+        const committed = await this.#nullifierEmissions.getAsync(nullifier);
+        const staged = this.#getNullifierEmissionsForJob(jobId).get(nullifier);
+        return staged ?? committed;
+    }
+    #writeNullifierEmission(nullifier, blockNumber, jobId) {
+        this.#getNullifierEmissionsForJob(jobId).set(nullifier, blockNumber);
     }
     /**
    * Retrieves notes based on the provided filter criteria.
    *
-   * This method queries both active and optionally nullified notes based on the filter
-   * parameters.
+   * A note is considered nullified iff its corresponding nullifier emission has been recorded.
    *
-   * @param filter - Filter criteria including contractAddress (required), and optional
-   *                 owner, storageSlot, status, scopes, and siloedNullifier.
-   * @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) {
-        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.');
+   * All DB reads are kicked off before any await so IndexedDB does not auto-commit the transaction mid-read.
+   *
+   * @param filter - Filter criteria including contractAddress (required), and optional owner,
+   *                 storageSlot, status, scopes, and siloedNullifier.
+   * @param jobId - the job context to read from.
+   * @returns Filtered and deduplicated notes (a note might be present in multiple scopes, but returned at most once)
+   */ getNotes(filter, jobId) {
+        if (filter.scopes.length === 0) {
+            return Promise.resolve([]);
         }
-        const candidateNoteSources = [];
-        filter.scopes ??= (await toArray(this.#scopes.keysAsync())).map((addressString)=>AztecAddress.fromString(addressString));
-        const activeNoteIdsPerScope = [];
-        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 a scope that is not in the PXE database');
+        return this.#store.transactionAsync(async ()=>{
+            const targetStatus = filter.status ?? NoteStatus.ACTIVE;
+            // Collect note-read and nullifier-emission-read promises together in one map so all DB reads are in-flight
+            // before any await. This keeps the IndexedDB transaction alive (IndexedDB auto-commits when a new micro-task
+            // starts with no pending read requests), so both promises must be started during the synchronous iteration.
+            const candidates = new Map();
+            // Committed notes indexed by contract address
+            for await (const nullifier of this.#notesByContractAddress.getValuesAsync(filter.contractAddress.toString())){
+                candidates.set(nullifier, {
+                    notePromise: this.#readNote(nullifier, jobId),
+                    nullificationPromise: this.#readNullifierEmission(nullifier, jobId)
+                });
             }
-            activeNoteIdsPerScope.push(filter.storageSlot ? await toArray(this.#notesByStorageSlotAndScope.get(formattedScopeString).getValuesAsync(filter.storageSlot.toString())) : await toArray(this.#notesByContractAndScope.get(formattedScopeString).getValuesAsync(filter.contractAddress.toString())));
-        }
-        candidateNoteSources.push({
-            ids: new Set(activeNoteIdsPerScope.flat()),
-            notes: this.#notes
-        });
-        // 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()));
-            const filteredNullifiedIds = new Set();
-            for (const noteId of nullifiedIds){
-                const scopeList = await toArray(this.#nullifiedNotesToScope.getValuesAsync(noteId));
-                if (scopeList.some((scope)=>setOfScopes.has(scope))) {
-                    filteredNullifiedIds.add(noteId);
+            // Staged notes from the current job (not yet committed to the DB index)
+            for (const storedNote of this.#getNotesForJob(jobId).values()){
+                if (storedNote.noteDao.contractAddress.equals(filter.contractAddress)) {
+                    const nullifier = storedNote.noteDao.siloedNullifier.toString();
+                    if (!candidates.has(nullifier)) {
+                        candidates.set(nullifier, {
+                            notePromise: Promise.resolve(storedNote),
+                            nullificationPromise: this.#readNullifierEmission(nullifier, jobId)
+                        });
+                    }
                 }
             }
-            if (filteredNullifiedIds.size > 0) {
-                candidateNoteSources.push({
-                    ids: filteredNullifiedIds,
-                    notes: this.#nullifiedNotes
-                });
+            // Await all DB reads together before the await-free tail.
+            const entries = [
+                ...candidates.entries()
+            ];
+            const notes = await Promise.all(entries.map(([, { notePromise }])=>notePromise));
+            const nullifierEmissions = await Promise.all(entries.map(([, { nullificationPromise }])=>nullificationPromise));
+            // Await-free tail: filter and sort. No DB ops from here on.
+            // Build a lookup: nullifier => emission block number
+            const emissionByNullifier = new Map();
+            for(let i = 0; i < entries.length; i++){
+                emissionByNullifier.set(entries[i][0], nullifierEmissions[i]);
             }
-        }
-        const result = [];
-        for (const { ids, notes } of candidateNoteSources){
-            for (const id of ids){
-                const serializedNote = await notes.getAsync(id);
-                if (!serializedNote) {
+            const foundNotes = new Map();
+            for (const note of notes){
+                // 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.');
+                }
+                // A note is nullified once its nullifier emission has been recorded (committed or staged in this job).
+                const nullified = emissionByNullifier.get(note.noteDao.siloedNullifier.toString()) !== undefined;
+                if (targetStatus === NoteStatus.ACTIVE && nullified) {
                     continue;
                 }
-                const note = NoteDao.fromBuffer(serializedNote);
-                if (!note.contractAddress.equals(filter.contractAddress)) {
+                if (filter.owner && !note.noteDao.owner.equals(filter.owner)) {
                     continue;
                 }
-                if (filter.owner && !note.owner.equals(filter.owner)) {
+                if (filter.storageSlot && !note.noteDao.storageSlot.equals(filter.storageSlot)) {
                     continue;
                 }
-                if (filter.storageSlot && !note.storageSlot.equals(filter.storageSlot)) {
+                if (filter.siloedNullifier && !note.noteDao.siloedNullifier.equals(filter.siloedNullifier)) {
                     continue;
                 }
-                if (filter.siloedNullifier && !note.siloedNullifier.equals(filter.siloedNullifier)) {
+                if (note.scopes.intersection(new Set(filter.scopes.map((s)=>s.toString()))).size === 0) {
                     continue;
                 }
-                result.push(note);
+                foundNotes.set(note.noteDao.siloedNullifier.toString(), note.noteDao);
             }
-        }
-        // A note might be present in multiple scopes - we ensure it is only returned once
-        const deduplicated = [];
-        for (const note of result){
-            if (!deduplicated.some((existing)=>existing.equals(note))) {
-                deduplicated.push(note);
-            }
-        }
-        // Sort by block number, then by tx index within block, then by note index within tx
-        deduplicated.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;
+            // 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;
+            });
         });
-        return deduplicated;
     }
     /**
-   * Transitions notes from "active" to "nullified" state.
+   * Records emission of the given siloed nullifiers, which causes notes to be considered nullified.
+   *
+   * Each nullifier gets an append-only entry recording the block number at which it was emitted.
+   *
+   * Every nullifier passed must correspond to a note already present in this store. Callers only apply nullifiers for
+   * notes of scopes they track, and a note is always discovered before the nullifier that spends it, so a nullifier
+   * with no matching note signals a bug (broken nonce/index discovery, a sync-ordering error, store corruption, etc).
    *
-   * 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: a nullifier whose emission is already recorded (committed or staged in this job) is
+   * skipped, so re-applying it neither re-writes the emission, changes note visibility, nor appears in the result.
    *
-   * @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) {
-        if (nullifiers.length === 0) {
+   * @param siloedNullifiers - Array of nullifiers with their block locations to record
+   * @param jobId - The job context for staged writes
+   * @returns The notes that transition from active to nullified in this call; already-nullified notes are skipped, so
+   *          a repeat application returns an empty array.
+   * @throws If any nullifier has no matching note in this store, or was emitted at block 0.
+   */ applyNullifiers(siloedNullifiers, jobId) {
+        if (siloedNullifiers.length === 0) {
             return Promise.resolve([]);
         }
-        return this.#store.transactionAsync(async ()=>{
-            const nullifiedNotes = [];
-            for (const blockScopedNullifier of nullifiers){
-                const { data: nullifier, l2BlockNumber: blockNumber } = blockScopedNullifier;
-                const noteId = nullifier.toString();
-                const noteBuffer = await this.#notes.getAsync(noteId);
-                if (!noteBuffer) {
-                    // Check if already nullified (noteId === siloedNullifier, so we can check #nullifiedNotes directly)
-                    if (await this.#nullifiedNotes.hasAsync(noteId)) {
-                        throw new Error(`Nullifier already applied in applyNullifiers`);
+        if (siloedNullifiers.some((n)=>n.l2BlockNumber === 0)) {
+            return Promise.reject(new Error('applyNullifiers: nullifiers cannot have been emitted at block 0'));
+        }
+        return this.#withJobLock(jobId, ()=>this.#store.transactionAsync(async ()=>{
+                // Kick off the note read and the existing-emission read together during the synchronous map so all are in
+                // flight before the first await, which keeps the IndexedDB transaction alive.
+                const resolved = await Promise.all(siloedNullifiers.map(async (nullifier)=>{
+                    const key = nullifier.data.toString();
+                    const [storedNote, existingEmission] = await Promise.all([
+                        this.#readNote(key, jobId),
+                        this.#readNullifierEmission(key, jobId)
+                    ]);
+                    if (!storedNote) {
+                        throw new Error(`Attempted to mark a note as nullified which does not exist in PXE DB: ${key}`);
                     }
-                    throw new Error('Nullifier not found in applyNullifiers');
-                }
-                const noteScopes = await toArray(this.#notesToScope.getValuesAsync(noteId));
-                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(noteId);
-                await this.#notesToScope.delete(noteId);
-                const scopes = await toArray(this.#scopes.keysAsync());
-                for (const scope of scopes){
-                    await this.#notesByContractAndScope.get(scope).deleteValue(note.contractAddress.toString(), noteId);
-                    await this.#notesByStorageSlotAndScope.get(scope).deleteValue(note.storageSlot.toString(), noteId);
-                }
-                for (const scope of noteScopes){
-                    await this.#nullifiedNotesToScope.set(noteId, scope);
+                    return {
+                        nullifier,
+                        storedNote,
+                        alreadyEmitted: existingEmission !== undefined
+                    };
+                }));
+                // Await-free tail: record an emission only for notes not already nullified, and return exactly those that
+                // transition active -> nullified in this call.
+                const affected = [];
+                for (const { nullifier, storedNote, alreadyEmitted } of resolved){
+                    if (alreadyEmitted) {
+                        continue;
+                    }
+                    this.#writeNullifierEmission(nullifier.data.toString(), nullifier.l2BlockNumber, jobId);
+                    affected.push(storedNote.noteDao);
                 }
-                await this.#nullifiedNotes.set(noteId, note.toBuffer());
-                await this.#nullifiersByBlockNumber.set(blockNumber, noteId);
-                await this.#nullifiedNotesByContract.set(note.contractAddress.toString(), noteId);
-                await this.#nullifiedNotesByStorageSlot.set(note.storageSlot.toString(), noteId);
+                return affected;
+            }));
+    }
+    /**
+   * 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
+   */ async commit(jobId) {
+        for (const [nullifier, storedNote] of this.#getNotesForJob(jobId)){
+            await this.#notes.set(nullifier, storedNote.toBuffer());
+            await this.#notesByContractAddress.set(storedNote.noteDao.contractAddress.toString(), nullifier);
+            await this.#notesByBlockNumber.set(storedNote.noteDao.l2BlockNumber, nullifier);
+        }
+        for (const [nullifier, blockNumber] of this.#getNullifierEmissionsForJob(jobId)){
+            await this.#nullifierEmissions.set(nullifier, blockNumber);
+            await this.#nullifierEmissionsByBlockNumber.set(blockNumber, nullifier);
+        }
+        this.#clearJobData(jobId);
+    }
+    discardStaged(jobId) {
+        this.#clearJobData(jobId);
+        return Promise.resolve();
+    }
+    #clearJobData(jobId) {
+        this.#notesForJob.delete(jobId);
+        this.#nullifierEmissionsForJob.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;
+    }
+    #getNullifierEmissionsForJob(jobId) {
+        let nullificationsForJob = this.#nullifierEmissionsForJob.get(jobId);
+        if (!nullificationsForJob) {
+            nullificationsForJob = new Map();
+            this.#nullifierEmissionsForJob.set(jobId, nullificationsForJob);
+        }
+        return nullificationsForJob;
+    }
+    /** Returns the nullifiers (note ids) of all notes created at the given block number. Used by delete-on-prune. */ async nullifiersOfNotesAtBlock(blockNumber) {
+        const nullifiers = [];
+        for await (const nullifier of this.#notesByBlockNumber.getValuesAsync(blockNumber)){
+            nullifiers.push(nullifier);
+        }
+        return nullifiers;
+    }
+    /**
+   * Rolls the store back to `toBlock`: deletes every note and nullifier emission originating on a block strictly above
+   * it, as if nothing past that block height ever happened. Used to retract notes and nullifiers on a reorg.
+   *
+   * Must be called inside a transaction owned by the caller (it issues no `transactionAsync` of its own, because the
+   * reorg path wraps it together with other store operations, and IndexedDB has no nested transaction support).
+   *
+   * Throws if any job has uncommitted staged writes, since rolling back mid-job could later re-introduce notes or
+   * nullifier emissions anchored to deleted blocks.
+   */ async rollback(toBlock) {
+        if (this.#notesForJob.size > 0 || this.#nullifierEmissionsForJob.size > 0) {
+            throw new Error('PXE note store rollback is not allowed while jobs are running');
+        }
+        // Snapshot the orphaned (block, nullifier) pairs before mutating so we never delete from the cursor we are
+        // iterating. Scanning from `toBlock + 1` upward covers everything above the rollback target without needing to know
+        // the chain tip. Each nullifier's rows are independent (nullifiers are globally unique), so the deletes run
+        // concurrently. Keeping requests in flight also prevents the IndexedDB transaction from auto-committing mid-way.
+        const orphanedNotes = [];
+        for await (const [block, siloedNullifier] of this.#notesByBlockNumber.entriesAsync({
+            start: toBlock + 1
+        })){
+            orphanedNotes.push({
+                block,
+                siloedNullifier
+            });
+        }
+        let removedNotes = 0;
+        await Promise.all(orphanedNotes.map(async ({ block, siloedNullifier })=>{
+            const buf = await this.#notes.getAsync(siloedNullifier);
+            if (!buf) {
+                throw new Error(`Note not found for siloedNullifier ${siloedNullifier}`);
             }
-            return nullifiedNotes;
+            const stored = StoredNote.fromBuffer(buf);
+            await this.#notes.delete(siloedNullifier);
+            await this.#notesByContractAddress.deleteValue(stored.noteDao.contractAddress.toString(), siloedNullifier);
+            await this.#notesByBlockNumber.deleteValue(block, siloedNullifier);
+            removedNotes++;
+        }));
+        // Same procedure, with nullifier emissions
+        const orphanedEmissions = [];
+        for await (const [block, siloedNullifier] of this.#nullifierEmissionsByBlockNumber.entriesAsync({
+            start: toBlock + 1
+        })){
+            orphanedEmissions.push({
+                block,
+                siloedNullifier
+            });
+        }
+        await Promise.all(orphanedEmissions.map(async ({ block, siloedNullifier })=>{
+            await this.#nullifierEmissions.delete(siloedNullifier);
+            await this.#nullifierEmissionsByBlockNumber.deleteValue(block, siloedNullifier);
+        }));
+        this.logger.verbose('rolled back notes and nullifier emissions', {
+            removedNotes,
+            removedNullifierEmissions: orphanedEmissions.length,
+            toBlock
         });
     }
 }