@aztec/pxe 0.0.1-commit.96bb3f7 → 0.0.1-commit.a072138

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

@@ -1 +1 @@
-{"version":3,"file":"note_store.d.ts","sourceRoot":"","sources":["../../../src/storage/note_store/note_store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,gCAAgC,CAAC;AAEzD,OAAO,KAAK,EAAE,iBAAiB,EAAqC,MAAM,iBAAiB,CAAC;AAC5F,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAc,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE7C;;;;;IAKI;AACJ,qBAAa,SAAS;;IAiBpB,OAAO,eAgBN;IAED;;;;;;;;OAQG;IACH,OAAoB,MAAM,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,CAAC,CAOvE;IAED;;;;;;;;OAQG;IACU,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CAY3D;IAED;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB7D;IAED;;;;;;;;;OASG;IACU,0BAA0B,CAAC,WAAW,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGtG;IAuFD;;;;;;;;;;;OAWG;IACG,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAwGtD;IAED;;;;;;;;;;OAUG;IACH,eAAe,CAAC,UAAU,EAAE,WAAW,CAAC,EAAE,CAAC,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CA8DjE;CACF"}
+{"version":3,"file":"note_store.d.ts","sourceRoot":"","sources":["../../../src/storage/note_store/note_store.ts"],"names":[],"mappings":"AACA,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,CAarF;IAcD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CA6F/D;IAED;;;;;;;;;;;;;;OAcG;IACH,eAAe,CAAC,UAAU,EAAE,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAqChF;IAED;;;;;;;;;;;OAWG;IACU,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMpF;IA6ED;;;;;;;;;OASG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAUzC;IAED,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG1C;CAkCF"}

package/dest/storage/note_store/note_store.js

@@ -1,322 +1,341 @@
-import { toBufferBE } from '@aztec/foundation/bigint-buffer';
-import { toArray } from '@aztec/foundation/iterable';
-import { AztecAddress } from '@aztec/stdlib/aztec-address';
+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.
  *
- * Notes can be active or nullified. This class processes new notes, nullifications,
- * and performs rollback handling in the case of a reorg.
+ * 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;
-    #nullifiedNotes;
-    #nullifierToNoteId;
-    #nullifiersByBlockNumber;
-    #nullifiedNotesToScope;
-    #nullifiedNotesByContract;
-    #nullifiedNotesByStorageSlot;
-    #nullifiedNotesByNullifier;
-    #scopes;
-    #notesToScope;
-    #notesByContractAndScope;
-    #notesByStorageSlotAndScope;
+    // 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.#nullifiedNotes = store.openMap('nullified_notes');
-        this.#nullifierToNoteId = store.openMap('nullifier_to_note');
-        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.#nullifiedNotesByNullifier = store.openMap('nullified_notes_by_nullifier');
-        this.#scopes = store.openMap('scopes');
-        this.#notesToScope = store.openMultiMap('notes_to_scope');
-        this.#notesByContractAndScope = new Map();
-        this.#notesByStorageSlotAndScope = new Map();
+        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();
     }
     /**
-   * Creates and initializes a new NoteStore instance.
+   * Adds multiple notes to the notes store under the specified scope.
    *
-   * 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;
-    }
-    /**
-   * 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.
+   * 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 noteIndex = toBufferBE(dao.index, 32).toString('hex');
-                await this.#notes.set(noteIndex, dao.toBuffer());
-                await this.#notesToScope.set(noteIndex, scope.toString());
-                await this.#nullifierToNoteId.set(dao.siloedNullifier.toString(), noteIndex);
-                await this.#notesByContractAndScope.get(scope.toString()).set(dao.contractAddress.toString(), noteIndex);
-                await this.#notesByStorageSlotAndScope.get(scope.toString()).set(dao.storageSlot.toString(), noteIndex);
-            }
-        });
+   * @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.
-   *
-   * @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 rollbackNotesAndNullifiers(blockNumber, synchedBlockNumber) {
-        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) {
-        return this.#store.transactionAsync(async ()=>{
-            const notes = await toArray(this.#notes.valuesAsync());
-            for (const note of notes){
-                const noteDao = NoteDao.fromBuffer(note);
-                if (noteDao.l2BlockNumber > blockNumber) {
-                    const noteIndex = toBufferBE(noteDao.index, 32).toString('hex');
-                    await this.#notes.delete(noteIndex);
-                    await this.#notesToScope.delete(noteIndex);
-                    await this.#nullifierToNoteId.delete(noteDao.siloedNullifier.toString());
-                    const scopes = await toArray(this.#scopes.keysAsync());
-                    for (const scope of scopes){
-                        await this.#notesByContractAndScope.get(scope).deleteValue(noteDao.contractAddress.toString(), noteIndex);
-                        await this.#notesByStorageSlotAndScope.get(scope).deleteValue(noteDao.storageSlot.toString(), noteIndex);
-                    }
-                }
-            }
-        });
+    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);
     }
-    /**
-   * 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) {
-        await this.#store.transactionAsync(async ()=>{
-            const nullifiersToUndo = [];
-            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);
-                const scopes = await toArray(this.#nullifiedNotesToScope.getValuesAsync(noteIndex));
-                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 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.#notesToScope.set(noteIndex, scope);
-                }
-                await this.#nullifiedNotes.delete(noteIndex);
-                await this.#nullifiedNotesToScope.delete(noteIndex);
-                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.#nullifiedNotesByNullifier.delete(dao.siloedNullifier.toString());
-            }
-        });
+    #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.
+   * 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.
+   * @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) {
-        filter.status = filter.status ?? NoteStatus.ACTIVE;
-        // throw early if scopes is an empty array
+   */ getNotes(filter, jobId) {
         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.');
+            return Promise.reject(new Error('Trying to get notes with an empty scopes array'));
         }
-        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;
+            // The code below might read a bit unnatural, the reason is that we need to be careful in how we use `await` inside
+            // `transactionAsync`, otherwise browsers might choose to auto-commit the IndexedDB transaction forcing us to
+            // explicitly handle that condition. The rule we need to honor is: do not await unless you generate a database
+            // read or write or you're done using the DB for the remainder of the transaction. The following sequence is
+            // unsafe in IndexedDB:
+            //
+            // 1. start transactionAsync()
+            // 2. await readDb() <-- OK, transaction alive because we issued DB ops
+            // 3. run a bunch of computations (no await involved) <-- OK, tx alive because we are in the same microtask
+            // 4. await doSthNotInDb() <-- no DB ops issued in this task, browser's free to decide to commit the tx
+            // 5. await readDb() <-- BOOM, TransactionInactiveError
+            //
+            // Note that the real issue is in step number 5: we try to continue using a transaction that the browser might
+            // have already committed.
+            //
+            // We need to read candidate notes which are either indexed by contract address in the DB (in
+            // #nullifiersByContractAddress), or lie in memory for the not yet committed `jobId`.
+            // So we collect promises based on both sources without awaiting for them.
+            const noteReadPromises = new Map();
+            // Awaiting the getValuesAsync iterator is fine because it's reading from the DB
+            for await (const nullifier of this.#nullifiersByContractAddress.getValuesAsync(filter.contractAddress.toString())){
+                // Each #readNote will perform a DB read
+                noteReadPromises.set(nullifier, this.#readNote(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);
+            // Add staged nullifiers from job, no awaits involved, so we are fine
+            for (const storedNote of this.#getNotesForJob(jobId).values()){
+                if (storedNote.noteDao.contractAddress.equals(filter.contractAddress)) {
+                    const nullifier = storedNote.noteDao.siloedNullifier.toString();
+                    if (!noteReadPromises.has(nullifier)) {
+                        noteReadPromises.set(nullifier, Promise.resolve(storedNote));
+                    }
                 }
             }
-            if (filteredNullifiedIds.size > 0) {
-                candidateNoteSources.push({
-                    ids: filteredNullifiedIds,
-                    notes: this.#nullifiedNotes
-                });
-            }
-        }
-        const result = [];
-        for (const { ids, notes } of candidateNoteSources){
-            for (const id of ids){
-                const serializedNote = await notes.getAsync(id);
-                if (!serializedNote) {
+            // By now we have pending DB requests from all the #readNote calls. Await them all together.
+            const notes = await Promise.all(noteReadPromises.values());
+            // The rest of the function is await-free, and just deals with filtering and sorting our findings.
+            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.');
+                }
+                // Apply filters
+                if (targetStatus === NoteStatus.ACTIVE && note.isNullified()) {
                     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 (filter.scopes && 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);
-            }
-        }
-        return deduplicated;
+            // 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.
+   * 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
-   * @returns Promise resolving to array of nullified NoteDao objects
-   * @throws Error if any nullifier is not found in the active notes
-   */ applyNullifiers(nullifiers) {
+   * @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) {
         if (nullifiers.length === 0) {
             return Promise.resolve([]);
         }
-        return this.#store.transactionAsync(async ()=>{
-            const nullifiedNotes = [];
-            for (const blockScopedNullifier of nullifiers){
-                const { data: nullifier, l2BlockNumber: blockNumber } = blockScopedNullifier;
-                const nullifierKey = nullifier.toString();
-                const noteIndex = await this.#nullifierToNoteId.getAsync(nullifierKey);
-                if (!noteIndex) {
-                    // Check if already nullified?
-                    const alreadyNullified = await this.#nullifiedNotesByNullifier.getAsync(nullifierKey);
-                    if (alreadyNullified) {
-                        throw new Error(`Nullifier already applied in applyNullifiers`);
+        return this.#withJobLock(jobId, ()=>this.#store.transactionAsync(async ()=>{
+                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,
+                        blockNumber: nullifierInBlock.l2BlockNumber
+                    };
+                }));
+                const notesNullifiedInThisCall = new Map();
+                for (const noteToNullify of notesToNullify){
+                    const note = noteToNullify.storedNote;
+                    // Skip already nullified notes
+                    if (note.isNullified()) {
+                        continue;
                     }
-                    throw new Error('Nullifier not found in applyNullifiers');
+                    note.markAsNullified(noteToNullify.blockNumber);
+                    this.#writeNote(note, jobId);
+                    notesNullifiedInThisCall.set(note.noteDao.siloedNullifier.toString(), note.noteDao);
                 }
-                const noteBuffer = noteIndex ? await this.#notes.getAsync(noteIndex) : undefined;
+                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) {
+        // Collect notes to delete during iteration to keep IndexedDB transaction alive.
+        const notesToDelete = [];
+        for await (const noteBuffer of this.#notes.valuesAsync()){
+            const storedNote = StoredNote.fromBuffer(noteBuffer);
+            if (storedNote.noteDao.l2BlockNumber > blockNumber) {
+                notesToDelete.push({
+                    nullifier: storedNote.noteDao.siloedNullifier.toString(),
+                    contractAddress: storedNote.noteDao.contractAddress.toString()
+                });
+            }
+        }
+        // Delete all collected notes. Each delete is a DB operation that keeps the transaction alive.
+        for (const { nullifier, contractAddress } of notesToDelete){
+            await this.#notes.delete(nullifier);
+            await this.#nullifiersByContractAddress.deleteValue(contractAddress, nullifier);
+        }
+    }
+    /**
+   * 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) {
+        // First pass: collect all nullifiers for all blocks, starting reads during iteration to keep tx alive.
+        const nullifiersByBlock = new Map();
+        for(let i = blockNumber + 1; i <= anchorBlockNumber; i++){
+            const blockNullifiers = [];
+            for await (const nullifier of this.#nullifiersByNullificationBlockNumber.getValuesAsync(i)){
+                // Start read immediately during iteration to keep IndexedDB transaction alive
+                blockNullifiers.push({
+                    nullifier,
+                    noteReadPromise: this.#notes.getAsync(nullifier)
+                });
+            }
+            if (blockNullifiers.length > 0) {
+                nullifiersByBlock.set(i, blockNullifiers);
+            }
+        }
+        // Second pass: await reads and perform writes
+        for (const [block, nullifiers] of nullifiersByBlock){
+            for (const { nullifier, noteReadPromise } of nullifiers){
+                const noteBuffer = await noteReadPromise;
                 if (!noteBuffer) {
-                    throw new Error('Note not found in applyNullifiers');
-                }
-                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');
+                    throw new Error(`PXE DB integrity error: no note found with nullifier ${nullifier}`);
                 }
-                const note = NoteDao.fromBuffer(noteBuffer);
-                nullifiedNotes.push(note);
-                await this.#notes.delete(noteIndex);
-                await this.#notesToScope.delete(noteIndex);
-                const scopes = await toArray(this.#scopes.keysAsync());
-                for (const scope of scopes){
-                    await this.#notesByContractAndScope.get(scope).deleteValue(note.contractAddress.toString(), noteIndex);
-                    await this.#notesByStorageSlotAndScope.get(scope).deleteValue(note.storageSlot.toString(), noteIndex);
+                const storedNote = StoredNote.fromBuffer(noteBuffer);
+                if (storedNote.scopes.size === 0) {
+                    throw new Error(`No scopes found for nullified note with nullifier ${nullifier}`);
                 }
-                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.#nullifiedNotesByNullifier.set(nullifier.toString(), noteIndex);
-                await this.#nullifierToNoteId.delete(nullifier.toString());
+                storedNote.markAsActive();
+                await Promise.all([
+                    this.#notes.set(nullifier, storedNote.toBuffer()),
+                    this.#nullifiersByNullificationBlockNumber.deleteValue(block, nullifier)
+                ]);
             }
-            return nullifiedNotes;
-        });
+        }
+    }
+    /**
+   * 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.#nullifiersByContractAddress.set(storedNote.noteDao.contractAddress.toString(), nullifier);
+            if (storedNote.nullifiedAt !== undefined) {
+                await this.#nullifiersByNullificationBlockNumber.set(storedNote.nullifiedAt, nullifier);
+            }
+        }
+        this.#clearJobData(jobId);
+    }
+    discardStaged(jobId) {
+        this.#clearJobData(jobId);
+        return Promise.resolve();
+    }
+    #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;
     }
 }

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"}