@aztec/pxe 0.0.0-test.1 → 0.0.1-commit.1142ef1

package/dest/storage/note_store/note_store.js

@@ -0,0 +1,322 @@
+import { toBufferBE } from '@aztec/foundation/bigint-buffer';
+import { toArray } from '@aztec/foundation/iterable';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { NoteStatus } from '@aztec/stdlib/note';
+import { NoteDao } from '@aztec/stdlib/note';
+/**
+ * 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 {
+    #store;
+    #notes;
+    #nullifiedNotes;
+    #nullifierToNoteId;
+    #nullifiersByBlockNumber;
+    #nullifiedNotesToScope;
+    #nullifiedNotesByContract;
+    #nullifiedNotesByStorageSlot;
+    #nullifiedNotesByNullifier;
+    #scopes;
+    #notesToScope;
+    #notesByContractAndScope;
+    #notesByStorageSlotAndScope;
+    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();
+    }
+    /**
+   * 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;
+    }
+    /**
+   * Adds multiple notes to the data provider under the specified scope.
+   *
+   * Notes are stored using their index from the notes hash tree as the key, which provides
+   * uniqueness and maintains creation order. Each note is indexed by multiple criteria
+   * for efficient retrieval.
+   *
+   * @param notes - Notes to store
+   * @param scope - The scope (user/account) under which to store the notes
+   */ addNotes(notes, 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);
+            }
+        });
+    }
+    /**
+   * 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);
+                    }
+                }
+            }
+        });
+    }
+    /**
+   * 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());
+            }
+        });
+    }
+    /**
+   * 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.
+   * @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.');
+        }
+        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');
+            }
+            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);
+                }
+            }
+            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) {
+                    continue;
+                }
+                const note = NoteDao.fromBuffer(serializedNote);
+                if (!note.contractAddress.equals(filter.contractAddress)) {
+                    continue;
+                }
+                if (filter.owner && !note.owner.equals(filter.owner)) {
+                    continue;
+                }
+                if (filter.storageSlot && !note.storageSlot.equals(filter.storageSlot)) {
+                    continue;
+                }
+                if (filter.siloedNullifier && !note.siloedNullifier.equals(filter.siloedNullifier)) {
+                    continue;
+                }
+                result.push(note);
+            }
+        }
+        // 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;
+    }
+    /**
+   * Transitions notes from "active" to "nullified" state.
+   *
+   * This operation processes a batch of nullifiers to mark the corresponding notes
+   * as spent/nullified.  The operation is atomic - if any nullifier is not found,
+   * the entire operation fails and no notes are modified.
+   *
+   * @param nullifiers - Array of nullifiers with their block numbers to process
+   * @returns Promise resolving to array of nullified NoteDao objects
+   * @throws Error if any nullifier is not found in the active notes
+   */ applyNullifiers(nullifiers) {
+        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`);
+                    }
+                    throw new Error('Nullifier not found in applyNullifiers');
+                }
+                const noteBuffer = noteIndex ? await this.#notes.getAsync(noteIndex) : undefined;
+                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');
+                }
+                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);
+                }
+                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());
+            }
+            return nullifiedNotes;
+        });
+    }
+}

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

@@ -0,0 +1,56 @@
+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 { PackedPrivateEvent } from '../../pxe.js';
+export type PrivateEventStoreFilter = {
+    contractAddress: AztecAddress;
+    fromBlock: number;
+    toBlock: number;
+    scopes: AztecAddress[];
+    txHash?: TxHash;
+};
+type PrivateEventMetadata = InTx & {
+    contractAddress: AztecAddress;
+    scope: AztecAddress;
+};
+/**
+ * Stores decrypted private event logs.
+ */
+export declare class PrivateEventStore {
+    #private;
+    logger: import("@aztec/foundation/log").Logger;
+    constructor(store: AztecAsyncKVStore);
+    /**
+     * Store a private event log.
+     * @param eventSelector - The event selector of the event.
+     * @param msgContent - The content of the event.
+     * @param eventCommitmentIndex - The index of the event commitment in the nullifier tree.
+     * @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[], eventCommitmentIndex: number, metadata: PrivateEventMetadata): 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 it the event was included in .
+     */
+    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).
+     */
+    rollbackEventsAfterBlock(blockNumber: number, synchedBlockNumber: number): Promise<void>;
+}
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicHJpdmF0ZV9ldmVudF9zdG9yZS5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL3N0b3JhZ2UvcHJpdmF0ZV9ldmVudF9zdG9yZS9wcml2YXRlX2V2ZW50X3N0b3JlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUNBLE9BQU8sRUFBRSxFQUFFLEVBQUUsTUFBTSxnQ0FBZ0MsQ0FBQztBQUdwRCxPQUFPLEtBQUssRUFBRSxpQkFBaUIsRUFBaUIsTUFBTSxpQkFBaUIsQ0FBQztBQUN4RSxPQUFPLEtBQUssRUFBRSxhQUFhLEVBQUUsTUFBTSxtQkFBbUIsQ0FBQztBQUN2RCxPQUFPLEtBQUssRUFBRSxZQUFZLEVBQUUsTUFBTSw2QkFBNkIsQ0FBQztBQUVoRSxPQUFPLEVBQUUsS0FBSyxJQUFJLEVBQUUsTUFBTSxFQUFFLE1BQU0sa0JBQWtCLENBQUM7QUFFckQsT0FBTyxLQUFLLEVBQUUsa0JBQWtCLEVBQUUsTUFBTSxjQUFjLENBQUM7QUFFdkQsTUFBTSxNQUFNLHVCQUF1QixHQUFHO0lBQ3BDLGVBQWUsRUFBRSxZQUFZLENBQUM7SUFDOUIsU0FBUyxFQUFFLE1BQU0sQ0FBQztJQUNsQixPQUFPLEVBQUUsTUFBTSxDQUFDO0lBQ2hCLE1BQU0sRUFBRSxZQUFZLEVBQUUsQ0FBQztJQUN2QixNQUFNLENBQUMsRUFBRSxNQUFNLENBQUM7Q0FDakIsQ0FBQztBQWFGLEtBQUssb0JBQW9CLEdBQUcsSUFBSSxHQUFHO0lBQ2pDLGVBQWUsRUFBRSxZQUFZLENBQUM7SUFDOUIsS0FBSyxFQUFFLFlBQVksQ0FBQztDQUNyQixDQUFDO0FBRUY7O0dBRUc7QUFDSCxxQkFBYSxpQkFBaUI7O0lBVzVCLE1BQU0seUNBQXVDO0lBRTdDLFlBQVksS0FBSyxFQUFFLGlCQUFpQixFQU1uQztJQU1EOzs7Ozs7Ozs7O09BVUc7SUFDSCxvQkFBb0IsQ0FDbEIsYUFBYSxFQUFFLGFBQWEsRUFDNUIsVUFBVSxFQUFFLEVBQUUsRUFDZCxVQUFVLEVBQUUsRUFBRSxFQUFFLEVBQ2hCLG9CQUFvQixFQUFFLE1BQU0sRUFDNUIsUUFBUSxFQUFFLG9CQUFvQixHQUM3QixPQUFPLENBQUMsSUFBSSxDQUFDLENBa0NmO0lBRUQ7Ozs7Ozs7Ozs7T0FVRztJQUNVLGdCQUFnQixDQUMzQixhQUFhLEVBQUUsYUFBYSxFQUM1QixNQUFNLEVBQUUsdUJBQXVCLEdBQzlCLE9BQU8sQ0FBQyxrQkFBa0IsRUFBRSxDQUFDLENBd0MvQjtJQUVEOzs7T0FHRztJQUNVLHdCQUF3QixDQUFDLFdBQVcsRUFBRSxNQUFNLEVBQUUsa0JBQWtCLEVBQUUsTUFBTSxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FxQ3BHO0NBQ0YifQ==

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;AAGpD,OAAO,KAAK,EAAE,iBAAiB,EAAiB,MAAM,iBAAiB,CAAC;AACxE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAEhE,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAErD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,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;AAaF,KAAK,oBAAoB,GAAG,IAAI,GAAG;IACjC,eAAe,EAAE,YAAY,CAAC;IAC9B,KAAK,EAAE,YAAY,CAAC;CACrB,CAAC;AAEF;;GAEG;AACH,qBAAa,iBAAiB;;IAW5B,MAAM,yCAAuC;IAE7C,YAAY,KAAK,EAAE,iBAAiB,EAMnC;IAMD;;;;;;;;;;OAUG;IACH,oBAAoB,CAClB,aAAa,EAAE,aAAa,EAC5B,UAAU,EAAE,EAAE,EACd,UAAU,EAAE,EAAE,EAAE,EAChB,oBAAoB,EAAE,MAAM,EAC5B,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAkCf;IAED;;;;;;;;;;OAUG;IACU,gBAAgB,CAC3B,aAAa,EAAE,aAAa,EAC5B,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAwC/B;IAED;;;OAGG;IACU,wBAAwB,CAAC,WAAW,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAqCpG;CACF"}

package/dest/storage/private_event_store/private_event_store.js

@@ -0,0 +1,158 @@
+import { BlockNumber } from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { createLogger } from '@aztec/foundation/log';
+import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
+import { L2BlockHash } from '@aztec/stdlib/block';
+import { TxHash } from '@aztec/stdlib/tx';
+/**
+ * Stores decrypted private event logs.
+ */ export class PrivateEventStore {
+    #store;
+    /** Map storing the actual private event log entries, keyed by eventCommitmentIndex */ #eventLogs;
+    /** Map from contractAddress_scope_eventSelector to eventCommitmentIndex[] for efficient lookup */ #eventsByContractScopeSelector;
+    /** Map from block number to eventCommitmentIndex[] for rollback support */ #eventsByBlockNumber;
+    /** Map from eventCommitmentIndex to boolean indicating if log has been seen. */ #seenLogs;
+    logger = createLogger('private_event_store');
+    constructor(store){
+        this.#store = store;
+        this.#eventLogs = this.#store.openMap('private_event_logs');
+        this.#eventsByContractScopeSelector = this.#store.openMap('events_by_contract_scope_selector');
+        this.#seenLogs = this.#store.openMap('seen_logs');
+        this.#eventsByBlockNumber = this.#store.openMap('events_by_block_number');
+    }
+    #keyFor(contractAddress, scope, eventSelector) {
+        return `${contractAddress.toString()}_${scope.toString()}_${eventSelector.toString()}`;
+    }
+    /**
+   * Store a private event log.
+   * @param eventSelector - The event selector of the event.
+   * @param msgContent - The content of the event.
+   * @param eventCommitmentIndex - The index of the event commitment in the nullifier tree.
+   * @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, randomness, msgContent, eventCommitmentIndex, metadata) {
+        const { contractAddress, scope, txHash, l2BlockNumber, l2BlockHash } = metadata;
+        return this.#store.transactionAsync(async ()=>{
+            const key = this.#keyFor(contractAddress, scope, eventSelector);
+            // Check if this exact log has already been stored using eventCommitmentIndex as unique identifier
+            const hasBeenSeen = await this.#seenLogs.getAsync(eventCommitmentIndex);
+            if (hasBeenSeen) {
+                this.logger.verbose('Ignoring duplicate event log', {
+                    txHash: txHash.toString(),
+                    eventCommitmentIndex
+                });
+                return;
+            }
+            this.logger.verbose('storing private event log', {
+                contractAddress,
+                scope,
+                msgContent,
+                l2BlockNumber
+            });
+            await this.#eventLogs.set(eventCommitmentIndex, {
+                randomness,
+                msgContent: serializeToBuffer(msgContent),
+                l2BlockNumber,
+                l2BlockHash: l2BlockHash.toBuffer(),
+                eventCommitmentIndex,
+                txHash: txHash.toBuffer(),
+                lookupKey: key
+            });
+            const existingIndices = await this.#eventsByContractScopeSelector.getAsync(key) || [];
+            await this.#eventsByContractScopeSelector.set(key, [
+                ...existingIndices,
+                eventCommitmentIndex
+            ]);
+            const existingBlockIndices = await this.#eventsByBlockNumber.getAsync(l2BlockNumber) || [];
+            await this.#eventsByBlockNumber.set(l2BlockNumber, [
+                ...existingBlockIndices,
+                eventCommitmentIndex
+            ]);
+            // Mark this log as seen using eventCommitmentIndex
+            await this.#seenLogs.set(eventCommitmentIndex, true);
+        });
+    }
+    /**
+   * 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 it the event was included in .
+   */ async getPrivateEvents(eventSelector, filter) {
+        const events = [];
+        for (const scope of filter.scopes){
+            const key = this.#keyFor(filter.contractAddress, scope, eventSelector);
+            const eventCommitmentIndices = await this.#eventsByContractScopeSelector.getAsync(key) || [];
+            for (const eventCommitmentIndex of eventCommitmentIndices){
+                const entry = await this.#eventLogs.getAsync(eventCommitmentIndex);
+                if (!entry || entry.l2BlockNumber < filter.fromBlock || entry.l2BlockNumber >= filter.toBlock) {
+                    continue;
+                }
+                // Convert buffer back to Fr array
+                const reader = BufferReader.asReader(entry.msgContent);
+                const numFields = entry.msgContent.length / Fr.SIZE_IN_BYTES;
+                const msgContent = reader.readArray(numFields, Fr);
+                const txHash = TxHash.fromBuffer(entry.txHash);
+                const l2BlockHash = L2BlockHash.fromBuffer(entry.l2BlockHash);
+                if (filter.txHash && !txHash.equals(filter.txHash)) {
+                    continue;
+                }
+                events.push({
+                    eventCommitmentIndex: entry.eventCommitmentIndex,
+                    event: {
+                        packedEvent: msgContent,
+                        l2BlockNumber: BlockNumber(entry.l2BlockNumber),
+                        txHash,
+                        l2BlockHash,
+                        eventSelector
+                    }
+                });
+            }
+        }
+        // Sort by eventCommitmentIndex only
+        events.sort((a, b)=>a.eventCommitmentIndex - b.eventCommitmentIndex);
+        return events.map((ev)=>ev.event);
+    }
+    /**
+   * 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).
+   */ async rollbackEventsAfterBlock(blockNumber, synchedBlockNumber) {
+        await this.#store.transactionAsync(async ()=>{
+            let removedCount = 0;
+            for(let block = blockNumber + 1; block <= synchedBlockNumber; block++){
+                const indices = await this.#eventsByBlockNumber.getAsync(block);
+                if (indices) {
+                    await this.#eventsByBlockNumber.delete(block);
+                    for (const eventCommitmentIndex of indices){
+                        const entry = await this.#eventLogs.getAsync(eventCommitmentIndex);
+                        if (!entry) {
+                            throw new Error(`Event log not found for eventCommitmentIndex ${eventCommitmentIndex}`);
+                        }
+                        await this.#eventLogs.delete(eventCommitmentIndex);
+                        await this.#seenLogs.delete(eventCommitmentIndex);
+                        // Update #eventsByContractScopeSelector using the stored lookupKey
+                        const existingIndices = await this.#eventsByContractScopeSelector.getAsync(entry.lookupKey);
+                        if (!existingIndices || existingIndices.length === 0) {
+                            throw new Error(`No indices found in #eventsByContractScopeSelector for key ${entry.lookupKey}`);
+                        }
+                        const filteredIndices = existingIndices.filter((idx)=>idx !== eventCommitmentIndex);
+                        if (filteredIndices.length === 0) {
+                            await this.#eventsByContractScopeSelector.delete(entry.lookupKey);
+                        } else {
+                            await this.#eventsByContractScopeSelector.set(entry.lookupKey, filteredIndices);
+                        }
+                        removedCount++;
+                    }
+                }
+            }
+            this.logger.verbose(`Rolled back ${removedCount} private events after block ${blockNumber}`);
+        });
+    }
+}

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

@@ -0,0 +1,4 @@
+export { SenderTaggingStore } from './sender_tagging_store.js';
+export { SenderAddressBookStore } from './sender_address_book_store.js';
+export { RecipientTaggingStore } from './recipient_tagging_store.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9zdG9yYWdlL3RhZ2dpbmdfc3RvcmUvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLGtCQUFrQixFQUFFLE1BQU0sMkJBQTJCLENBQUM7QUFDL0QsT0FBTyxFQUFFLHNCQUFzQixFQUFFLE1BQU0sZ0NBQWdDLENBQUM7QUFDeEUsT0FBTyxFQUFFLHFCQUFxQixFQUFFLE1BQU0sOEJBQThCLENBQUMifQ==

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/storage/tagging_store/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC"}

package/dest/storage/tagging_store/index.js

@@ -0,0 +1,3 @@
+export { SenderTaggingStore } from './sender_tagging_store.js';
+export { SenderAddressBookStore } from './sender_address_book_store.js';
+export { RecipientTaggingStore } from './recipient_tagging_store.js';

package/dest/storage/tagging_store/recipient_tagging_store.d.ts

@@ -0,0 +1,21 @@
+import type { AztecAsyncKVStore } from '@aztec/kv-store';
+import type { DirectionalAppTaggingSecret } from '@aztec/stdlib/logs';
+/**
+ * Data provider of tagging data used when syncing the logs as a recipient. The sender counterpart of this class
+ * is called SenderTaggingStore. We have the providers separate for the sender and recipient because
+ * the algorithms are completely disjoint and there is not data reuse between the two.
+ *
+ * @dev Chain reorgs do not need to be handled here because both the finalized and aged indexes refer to finalized
+ * blocks, which by definition cannot be affected by reorgs.
+ *
+ * TODO(benesjan): Relocate to yarn-project/pxe/src/storage/tagging_store
+ */
+export declare class RecipientTaggingStore {
+    #private;
+    constructor(store: AztecAsyncKVStore);
+    getHighestAgedIndex(secret: DirectionalAppTaggingSecret): Promise<number | undefined>;
+    updateHighestAgedIndex(secret: DirectionalAppTaggingSecret, index: number): Promise<void>;
+    getHighestFinalizedIndex(secret: DirectionalAppTaggingSecret): Promise<number | undefined>;
+    updateHighestFinalizedIndex(secret: DirectionalAppTaggingSecret, index: number): Promise<void>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVjaXBpZW50X3RhZ2dpbmdfc3RvcmUuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9zdG9yYWdlL3RhZ2dpbmdfc3RvcmUvcmVjaXBpZW50X3RhZ2dpbmdfc3RvcmUudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLEVBQUUsaUJBQWlCLEVBQWlCLE1BQU0saUJBQWlCLENBQUM7QUFDeEUsT0FBTyxLQUFLLEVBQUUsMkJBQTJCLEVBQUUsTUFBTSxvQkFBb0IsQ0FBQztBQUV0RTs7Ozs7Ozs7O0dBU0c7QUFDSCxxQkFBYSxxQkFBcUI7O0lBTWhDLFlBQVksS0FBSyxFQUFFLGlCQUFpQixFQUtuQztJQUVELG1CQUFtQixDQUFDLE1BQU0sRUFBRSwyQkFBMkIsR0FBRyxPQUFPLENBQUMsTUFBTSxHQUFHLFNBQVMsQ0FBQyxDQUVwRjtJQUVLLHNCQUFzQixDQUFDLE1BQU0sRUFBRSwyQkFBMkIsRUFBRSxLQUFLLEVBQUUsTUFBTSxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FPOUY7SUFFRCx3QkFBd0IsQ0FBQyxNQUFNLEVBQUUsMkJBQTJCLEdBQUcsT0FBTyxDQUFDLE1BQU0sR0FBRyxTQUFTLENBQUMsQ0FFekY7SUFFSywyQkFBMkIsQ0FBQyxNQUFNLEVBQUUsMkJBQTJCLEVBQUUsS0FBSyxFQUFFLE1BQU0sR0FBRyxPQUFPLENBQUMsSUFBSSxDQUFDLENBUW5HO0NBQ0YifQ==

package/dest/storage/tagging_store/recipient_tagging_store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipient_tagging_store.d.ts","sourceRoot":"","sources":["../../../src/storage/tagging_store/recipient_tagging_store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAiB,MAAM,iBAAiB,CAAC;AACxE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC;AAEtE;;;;;;;;;GASG;AACH,qBAAa,qBAAqB;;IAMhC,YAAY,KAAK,EAAE,iBAAiB,EAKnC;IAED,mBAAmB,CAAC,MAAM,EAAE,2BAA2B,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAEpF;IAEK,sBAAsB,CAAC,MAAM,EAAE,2BAA2B,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO9F;IAED,wBAAwB,CAAC,MAAM,EAAE,2BAA2B,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAEzF;IAEK,2BAA2B,CAAC,MAAM,EAAE,2BAA2B,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQnG;CACF"}

package/dest/storage/tagging_store/recipient_tagging_store.js

@@ -0,0 +1,42 @@
+/**
+ * Data provider of tagging data used when syncing the logs as a recipient. The sender counterpart of this class
+ * is called SenderTaggingStore. We have the providers separate for the sender and recipient because
+ * the algorithms are completely disjoint and there is not data reuse between the two.
+ *
+ * @dev Chain reorgs do not need to be handled here because both the finalized and aged indexes refer to finalized
+ * blocks, which by definition cannot be affected by reorgs.
+ *
+ * TODO(benesjan): Relocate to yarn-project/pxe/src/storage/tagging_store
+ */ export class RecipientTaggingStore {
+    #store;
+    #highestAgedIndex;
+    #highestFinalizedIndex;
+    constructor(store){
+        this.#store = store;
+        this.#highestAgedIndex = this.#store.openMap('highest_aged_index');
+        this.#highestFinalizedIndex = this.#store.openMap('highest_finalized_index');
+    }
+    getHighestAgedIndex(secret) {
+        return this.#highestAgedIndex.getAsync(secret.toString());
+    }
+    async updateHighestAgedIndex(secret, index) {
+        const currentIndex = await this.#highestAgedIndex.getAsync(secret.toString());
+        if (currentIndex !== undefined && index <= currentIndex) {
+            // Log sync should never set a lower highest aged index.
+            throw new Error(`New highest aged index (${index}) must be higher than the current one (${currentIndex})`);
+        }
+        await this.#highestAgedIndex.set(secret.toString(), index);
+    }
+    getHighestFinalizedIndex(secret) {
+        return this.#highestFinalizedIndex.getAsync(secret.toString());
+    }
+    async updateHighestFinalizedIndex(secret, index) {
+        const currentIndex = await this.#highestFinalizedIndex.getAsync(secret.toString());
+        if (currentIndex !== undefined && index < currentIndex) {
+            // Log sync should never set a lower highest finalized index but it can happen that it would try to set the same
+            // one because we are loading logs from highest aged index + 1 and not from the highest finalized index.
+            throw new Error(`New highest finalized index (${index}) must be higher than the current one (${currentIndex})`);
+        }
+        await this.#highestFinalizedIndex.set(secret.toString(), index);
+    }
+}

package/dest/storage/tagging_store/sender_address_book_store.d.ts

@@ -0,0 +1,14 @@
+import type { AztecAsyncKVStore } from '@aztec/kv-store';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+/**
+ * Stores sender addresses. During recipient log synchronization, these senders are used, along with a given recipient,
+ * to derive directional app tagging secrets that are then used to sync the logs.
+ */
+export declare class SenderAddressBookStore {
+    #private;
+    constructor(store: AztecAsyncKVStore);
+    addSender(address: AztecAddress): Promise<boolean>;
+    getSenders(): Promise<AztecAddress[]>;
+    removeSender(address: AztecAddress): Promise<boolean>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2VuZGVyX2FkZHJlc3NfYm9va19zdG9yZS5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL3N0b3JhZ2UvdGFnZ2luZ19zdG9yZS9zZW5kZXJfYWRkcmVzc19ib29rX3N0b3JlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUNBLE9BQU8sS0FBSyxFQUFFLGlCQUFpQixFQUFpQixNQUFNLGlCQUFpQixDQUFDO0FBQ3hFLE9BQU8sRUFBRSxZQUFZLEVBQUUsTUFBTSw2QkFBNkIsQ0FBQztBQUUzRDs7O0dBR0c7QUFDSCxxQkFBYSxzQkFBc0I7O0lBSWpDLFlBQVksS0FBSyxFQUFFLGlCQUFpQixFQUluQztJQUVLLFNBQVMsQ0FBQyxPQUFPLEVBQUUsWUFBWSxHQUFHLE9BQU8sQ0FBQyxPQUFPLENBQUMsQ0FRdkQ7SUFFSyxVQUFVLElBQUksT0FBTyxDQUFDLFlBQVksRUFBRSxDQUFDLENBRTFDO0lBRUssWUFBWSxDQUFDLE9BQU8sRUFBRSxZQUFZLEdBQUcsT0FBTyxDQUFDLE9BQU8sQ0FBQyxDQVExRDtDQUNGIn0=

package/dest/storage/tagging_store/sender_address_book_store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sender_address_book_store.d.ts","sourceRoot":"","sources":["../../../src/storage/tagging_store/sender_address_book_store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAiB,MAAM,iBAAiB,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE3D;;;GAGG;AACH,qBAAa,sBAAsB;;IAIjC,YAAY,KAAK,EAAE,iBAAiB,EAInC;IAEK,SAAS,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CAQvD;IAEK,UAAU,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAE1C;IAEK,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CAQ1D;CACF"}