@aztec-labs/pxe 6.0.0-nightly.20260829

package/dest/storage/private_event_store/private_event_store.js

@@ -0,0 +1,276 @@
+import { BlockNumber } from '@aztec-labs/foundation/branded-types';
+import { createLogger } from '@aztec-labs/foundation/log';
+import { allToCompletion } from '@aztec-labs/foundation/promise';
+import { Semaphore } from '@aztec-labs/foundation/queue';
+import { StoredPrivateEvent } from './stored_private_event.js';
+/**
+ * Stores decrypted private event logs.
+ *
+ * Append-only: events are never deleted during normal operation. Reorgs are handled by delete-on-prune, which removes
+ * every event originating on a reorg'd block.
+ */ export class PrivateEventStore {
+    storeName = 'private_event';
+    #store;
+    /** Actual private event log entries, keyed by siloedEventCommitment */ #events;
+    /** Multi-map from contractAddress_eventSelector to siloedEventCommitment for efficient lookup */ #eventsByContractAndEventSelector;
+    /** Multi-map from block number to siloedEventCommitment, for delete-on-prune. */ #eventsByBlockNumber;
+    /** changeSetId => eventId (event siloed nullifier) => StoredPrivateEvent */ #eventsForChangeSet;
+    /** Per-change-set locks to prevent concurrent writes from affecting each other. */ #changeSetLocks;
+    logger = createLogger('private_event_store');
+    constructor(store){
+        this.#store = store;
+        this.#events = this.#store.openMap('private_event_logs');
+        this.#eventsByContractAndEventSelector = this.#store.openMultiMap('events_by_contract_selector');
+        this.#eventsByBlockNumber = this.#store.openMultiMap('events_by_block_number');
+        this.#eventsForChangeSet = new Map();
+        this.#changeSetLocks = new Map();
+    }
+    /**
+   * Store a private event log.
+   * @param eventSelector - The event selector of the event.
+   * @param randomness - The randomness used for the event commitment.
+   * @param msgContent - The content of the event.
+   * @param siloedEventCommitment - The siloed event commitment (used as unique identifier).
+   * @param metadata
+   *  contractAddress - The address of the contract that emitted the event.
+   *  scope - The address to which the event is scoped.
+   *  txHash - The transaction hash of the event log.
+   *  blockNumber - The block number in which the event was emitted.
+   */ storePrivateEventLog(eventSelector, randomness, msgContent, siloedEventCommitment, metadata, changeSetId) {
+        return this.#withChangeSetLock(changeSetId, ()=>this.#store.transactionAsync(async ()=>{
+                const { contractAddress, scope, txHash, l2BlockNumber, l2BlockHash, txIndexInBlock, eventIndexInTx } = metadata;
+                const eventId = siloedEventCommitment.toString();
+                this.logger.verbose('storing private event log (staged)', {
+                    eventId,
+                    contractAddress,
+                    scope,
+                    msgContent,
+                    l2BlockNumber
+                });
+                const existing = await this.#readEvent(eventId, changeSetId);
+                if (existing) {
+                    // If we already stored this event, we still want to make sure to track it for the given scope
+                    existing.addScope(scope.toString());
+                    this.#writeEvent(eventId, existing, changeSetId);
+                } else {
+                    this.#writeEvent(eventId, new StoredPrivateEvent(randomness, msgContent, l2BlockNumber, l2BlockHash, txHash, txIndexInBlock, eventIndexInTx, contractAddress, eventSelector, new Set([
+                        scope.toString()
+                    ])), changeSetId);
+                }
+            }));
+    }
+    /**
+   * Returns the private events given search parameters.
+   * @param eventSelector - The event selector to filter by.
+   * @param filter - Filtering criteria:
+   *  contractAddress: The address of the contract to get events from.
+   *  fromBlock: The block number to search from (inclusive).
+   *  toBlock: The block number to search upto (exclusive).
+   *  scope: - The addresses that decrypted the logs.
+   * @returns - The event log contents, augmented with metadata about the transaction and block in which the event was
+   * included.
+   */ getPrivateEvents(eventSelector, filter) {
+        return this.#store.transactionAsync(async ()=>{
+            const key = this.#keyFor(filter.contractAddress, eventSelector);
+            const targetScopes = new Set(filter.scopes.map((s)=>s.toString()));
+            // Map from eventId to the promise that reads the event buffer.
+            // We start reads during iteration to keep DB requests pending and avoid IndexedDB auto-commit.
+            const eventReadPromises = new Map();
+            for await (const eventId of this.#eventsByContractAndEventSelector.getValuesAsync(key)){
+                eventReadPromises.set(eventId, this.#events.getAsync(eventId));
+            }
+            const eventIds = [
+                ...eventReadPromises.keys()
+            ];
+            const eventBuffers = await allToCompletion([
+                ...eventReadPromises.values()
+            ]);
+            const events = [];
+            for(let i = 0; i < eventIds.length; i++){
+                const eventId = eventIds[i];
+                const eventBuffer = eventBuffers[i];
+                // Defensive, if it happens, there's a problem with how we're handling #eventsByContractAndEventSelector
+                if (!eventBuffer) {
+                    this.logger.verbose(`EventId ${eventId} does not exist in main index but it is referenced from contract event selector index`);
+                    continue;
+                }
+                const storedPrivateEvent = StoredPrivateEvent.fromBuffer(eventBuffer);
+                // Filter by block range
+                if (storedPrivateEvent.l2BlockNumber < filter.fromBlock || storedPrivateEvent.l2BlockNumber >= filter.toBlock) {
+                    continue;
+                }
+                // Filter by scopes
+                if (storedPrivateEvent.scopes.intersection(targetScopes).size === 0) {
+                    continue;
+                }
+                // Filter by txHash
+                if (filter.txHash && !storedPrivateEvent.txHash.equals(filter.txHash)) {
+                    continue;
+                }
+                events.push({
+                    l2BlockNumber: storedPrivateEvent.l2BlockNumber,
+                    txIndexInBlock: storedPrivateEvent.txIndexInBlock,
+                    eventIndexInTx: storedPrivateEvent.eventIndexInTx,
+                    event: {
+                        packedEvent: storedPrivateEvent.msgContent,
+                        l2BlockNumber: BlockNumber(storedPrivateEvent.l2BlockNumber),
+                        txHash: storedPrivateEvent.txHash,
+                        l2BlockHash: storedPrivateEvent.l2BlockHash,
+                        eventSelector
+                    }
+                });
+            }
+            // Sort by block number, then by tx index within block, then by event index within tx
+            events.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.eventIndexInTx - b.eventIndexInTx;
+            });
+            return events.map((ev)=>ev.event);
+        });
+    }
+    /** Returns the ids (siloed event commitments) of all events emitted at the given block number. Used by delete-on-prune. */ async eventIdsAtBlock(blockNumber) {
+        const eventIds = [];
+        for await (const eventId of this.#eventsByBlockNumber.getValuesAsync(blockNumber)){
+            eventIds.push(eventId);
+        }
+        return eventIds;
+    }
+    /**
+   * Rolls the store back to `toBlock`: deletes every event anchored to a block strictly above it, as if nothing past
+   * that block height ever happened. Used by the reorg (`chain-pruned`) path to truncate the orphaned tail. Scanning
+   * from `toBlock + 1` upward covers everything above the rollback target without needing to know the chain tip.
+   *
+   * Must be called inside a transaction owned by the caller (it issues no `transactionAsync` of its own, the reorg path
+   * wraps it together with the anchor update, and IndexedDB has no nested transactions). Throws if any change set has
+   * uncommitted staged writes, since rolling back mid-change-set could later re-introduce events anchored to deleted
+   * blocks.
+   */ async rollbackToBlock(toBlock) {
+        if (this.#eventsForChangeSet.size > 0) {
+            throw new Error('PXE private event store rollback is not allowed while staged writes are pending');
+        }
+        // Snapshot before mutating so we never delete from the multimap we are iterating.
+        const orphaned = [];
+        for await (const [block, eventId] of this.#eventsByBlockNumber.entriesAsync({
+            start: toBlock + 1
+        })){
+            orphaned.push({
+                block,
+                eventId
+            });
+        }
+        let removedCount = 0;
+        for (const { block, eventId } of orphaned){
+            const buf = await this.#events.getAsync(eventId);
+            if (!buf) {
+                throw new Error(`Event not found for eventId ${eventId}`);
+            }
+            const stored = StoredPrivateEvent.fromBuffer(buf);
+            await this.#events.delete(eventId);
+            await this.#eventsByContractAndEventSelector.deleteValue(this.#keyFor(stored.contractAddress, stored.eventSelector), eventId);
+            await this.#eventsByBlockNumber.deleteValue(block, eventId);
+            removedCount++;
+        }
+        this.logger.verbose('rolled back private events', {
+            removedCount,
+            toBlock
+        });
+    }
+    /**
+   * Commits in-memory staged data to persistent storage.
+   *
+   * Called by StagedWriteCoordinator when an operation completes successfully.
+   *
+   * Note: StagedWriteCoordinator 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 changeSetId - The changeSetId identifying which staged data to commit
+   */ async commitChangeSet(changeSetId) {
+        // Note: Don't use #withChangeSetLock here - commit runs within StagedWriteCoordinator's transactionAsync,
+        // and awaiting the lock would create a microtask boundary with no pending DB request,
+        // causing IndexedDB to auto-commit the transaction.
+        for (const [eventId, entry] of this.#getEventsForChangeSet(changeSetId).entries()){
+            const lookupKey = this.#keyFor(entry.contractAddress, entry.eventSelector);
+            this.logger.verbose('storing private event log', {
+                eventId,
+                lookupKey
+            });
+            await allToCompletion([
+                this.#events.set(eventId, entry.toBuffer()),
+                this.#eventsByContractAndEventSelector.set(lookupKey, eventId),
+                this.#eventsByBlockNumber.set(entry.l2BlockNumber, eventId)
+            ]);
+        }
+        this.#clearChangeSetData(changeSetId);
+    }
+    /**
+   * Discards in-memory staged data without persisting it.
+   */ discardChangeSet(changeSetId) {
+        this.#clearChangeSetData(changeSetId);
+    }
+    /**
+   * Reads an event from in-memory staged data first, falling back to persistent storage if not found.
+   *
+   * Returns undefined if the event does not exist in the store overall.
+   */ async #readEvent(eventId, changeSetId) {
+        // 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 buffer = await this.#events.getAsync(eventId);
+        const eventForChangeSet = this.#getEventsForChangeSet(changeSetId).get(eventId);
+        return eventForChangeSet ?? (buffer ? StoredPrivateEvent.fromBuffer(buffer) : undefined);
+    }
+    /**
+   * Writes an event to in-memory staged data.
+   *
+   * Writes are only allowed in a change set context. Events modified while staged will only be persisted when `commit`
+   * is called.
+   */ #writeEvent(eventId, entry, changeSetId) {
+        this.#getEventsForChangeSet(changeSetId).set(eventId, entry);
+    }
+    /**
+   * Get in-memory data only visible to @param changeSetId
+   */ #getEventsForChangeSet(changeSetId) {
+        let eventsForChangeSet = this.#eventsForChangeSet.get(changeSetId);
+        if (eventsForChangeSet === undefined) {
+            eventsForChangeSet = new Map();
+            this.#eventsForChangeSet.set(changeSetId, eventsForChangeSet);
+        }
+        return eventsForChangeSet;
+    }
+    /**
+   * Clear data structures supporting a specific change set.
+   */ #clearChangeSetData(changeSetId) {
+        this.#eventsForChangeSet.delete(changeSetId);
+        this.#changeSetLocks.delete(changeSetId);
+    }
+    /**
+   * Ensures a function can only run once it acquires a unique per-change-set lock, and handles proper lock release
+   * after it runs.
+   *
+   * This primitive allows concurrent writes on this store without risking data corruption due to unsound write
+   * interleaving.
+   */ async #withChangeSetLock(changeSetId, fn) {
+        let lock = this.#changeSetLocks.get(changeSetId);
+        if (!lock) {
+            lock = new Semaphore(1);
+            this.#changeSetLocks.set(changeSetId, lock);
+        }
+        await lock.acquire();
+        try {
+            return await fn();
+        } finally{
+            lock.release();
+        }
+    }
+    /**
+   * Returns a string key based on @param contractAddress and @param eventSelector.
+   *
+   * The returned key is meant to be used when interacting with index #eventsByContractAndEventSelector.
+   */ #keyFor(contractAddress, eventSelector) {
+        return `${contractAddress.toString()}_${eventSelector.toString()}`;
+    }
+}

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

@@ -0,0 +1,23 @@
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { EventSelector } from '@aztec-labs/stdlib/abi';
+import { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import { BlockHash } from '@aztec-labs/stdlib/block';
+import { TxHash } from '@aztec-labs/stdlib/tx';
+/** Serializable private event entry with scope tracking. */
+export declare class StoredPrivateEvent {
+    readonly randomness: Fr;
+    readonly msgContent: Fr[];
+    readonly l2BlockNumber: number;
+    readonly l2BlockHash: BlockHash;
+    readonly txHash: TxHash;
+    readonly txIndexInBlock: number;
+    readonly eventIndexInTx: number;
+    readonly contractAddress: AztecAddress;
+    readonly eventSelector: EventSelector;
+    readonly scopes: Set<string>;
+    constructor(randomness: Fr, msgContent: Fr[], l2BlockNumber: number, l2BlockHash: BlockHash, txHash: TxHash, txIndexInBlock: number, eventIndexInTx: number, contractAddress: AztecAddress, eventSelector: EventSelector, scopes: Set<string>);
+    addScope(scope: string): void;
+    toBuffer(): Buffer;
+    static fromBuffer(buffer: Buffer): StoredPrivateEvent;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3RvcmVkX3ByaXZhdGVfZXZlbnQuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9zdG9yYWdlL3ByaXZhdGVfZXZlbnRfc3RvcmUvc3RvcmVkX3ByaXZhdGVfZXZlbnQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLEVBQUUsRUFBRSxNQUFNLHFDQUFxQyxDQUFDO0FBRXpELE9BQU8sRUFBRSxhQUFhLEVBQUUsTUFBTSx3QkFBd0IsQ0FBQztBQUN2RCxPQUFPLEVBQUUsWUFBWSxFQUFFLE1BQU0sa0NBQWtDLENBQUM7QUFDaEUsT0FBTyxFQUFFLFNBQVMsRUFBRSxNQUFNLDBCQUEwQixDQUFDO0FBQ3JELE9BQU8sRUFBRSxNQUFNLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQUUvQyw0REFBNEQ7QUFDNUQscUJBQWEsa0JBQWtCO0lBRTNCLFFBQVEsQ0FBQyxVQUFVLEVBQUUsRUFBRTtJQUN2QixRQUFRLENBQUMsVUFBVSxFQUFFLEVBQUUsRUFBRTtJQUN6QixRQUFRLENBQUMsYUFBYSxFQUFFLE1BQU07SUFDOUIsUUFBUSxDQUFDLFdBQVcsRUFBRSxTQUFTO0lBQy9CLFFBQVEsQ0FBQyxNQUFNLEVBQUUsTUFBTTtJQUN2QixRQUFRLENBQUMsY0FBYyxFQUFFLE1BQU07SUFDL0IsUUFBUSxDQUFDLGNBQWMsRUFBRSxNQUFNO0lBQy9CLFFBQVEsQ0FBQyxlQUFlLEVBQUUsWUFBWTtJQUN0QyxRQUFRLENBQUMsYUFBYSxFQUFFLGFBQWE7SUFDckMsUUFBUSxDQUFDLE1BQU0sRUFBRSxHQUFHLENBQUMsTUFBTSxDQUFDO0lBVjlCLFlBQ1csVUFBVSxFQUFFLEVBQUUsRUFDZCxVQUFVLEVBQUUsRUFBRSxFQUFFLEVBQ2hCLGFBQWEsRUFBRSxNQUFNLEVBQ3JCLFdBQVcsRUFBRSxTQUFTLEVBQ3RCLE1BQU0sRUFBRSxNQUFNLEVBQ2QsY0FBYyxFQUFFLE1BQU0sRUFDdEIsY0FBYyxFQUFFLE1BQU0sRUFDdEIsZUFBZSxFQUFFLFlBQVksRUFDN0IsYUFBYSxFQUFFLGFBQWEsRUFDNUIsTUFBTSxFQUFFLEdBQUcsQ0FBQyxNQUFNLENBQUMsRUFDMUI7SUFFSixRQUFRLENBQUMsS0FBSyxFQUFFLE1BQU0sUUFFckI7SUFFRCxRQUFRLElBQUksTUFBTSxDQWdCakI7SUFFRCxNQUFNLENBQUMsVUFBVSxDQUFDLE1BQU0sRUFBRSxNQUFNLEdBQUcsa0JBQWtCLENBMkJwRDtDQUNGIn0=

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

@@ -0,0 +1 @@
+{"version":3,"file":"stored_private_event.d.ts","sourceRoot":"","sources":["../../../src/storage/private_event_store/stored_private_event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,qCAAqC,CAAC;AAEzD,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE/C,4DAA4D;AAC5D,qBAAa,kBAAkB;IAE3B,QAAQ,CAAC,UAAU,EAAE,EAAE;IACvB,QAAQ,CAAC,UAAU,EAAE,EAAE,EAAE;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM;IAC9B,QAAQ,CAAC,WAAW,EAAE,SAAS;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,cAAc,EAAE,MAAM;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM;IAC/B,QAAQ,CAAC,eAAe,EAAE,YAAY;IACtC,QAAQ,CAAC,aAAa,EAAE,aAAa;IACrC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC;IAV9B,YACW,UAAU,EAAE,EAAE,EACd,UAAU,EAAE,EAAE,EAAE,EAChB,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,SAAS,EACtB,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,YAAY,EAC7B,aAAa,EAAE,aAAa,EAC5B,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,EAC1B;IAEJ,QAAQ,CAAC,KAAK,EAAE,MAAM,QAErB;IAED,QAAQ,IAAI,MAAM,CAgBjB;IAED,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,CA2BpD;CACF"}

package/dest/storage/private_event_store/stored_private_event.js

@@ -0,0 +1,56 @@
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { BufferReader, serializeToBuffer } from '@aztec-labs/foundation/serialize';
+import { EventSelector } from '@aztec-labs/stdlib/abi';
+import { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import { BlockHash } from '@aztec-labs/stdlib/block';
+import { TxHash } from '@aztec-labs/stdlib/tx';
+/** Serializable private event entry with scope tracking. */ export class StoredPrivateEvent {
+    randomness;
+    msgContent;
+    l2BlockNumber;
+    l2BlockHash;
+    txHash;
+    txIndexInBlock;
+    eventIndexInTx;
+    contractAddress;
+    eventSelector;
+    scopes;
+    constructor(randomness, msgContent, l2BlockNumber, l2BlockHash, txHash, txIndexInBlock, eventIndexInTx, contractAddress, eventSelector, scopes){
+        this.randomness = randomness;
+        this.msgContent = msgContent;
+        this.l2BlockNumber = l2BlockNumber;
+        this.l2BlockHash = l2BlockHash;
+        this.txHash = txHash;
+        this.txIndexInBlock = txIndexInBlock;
+        this.eventIndexInTx = eventIndexInTx;
+        this.contractAddress = contractAddress;
+        this.eventSelector = eventSelector;
+        this.scopes = scopes;
+    }
+    addScope(scope) {
+        this.scopes.add(scope);
+    }
+    toBuffer() {
+        const scopesArray = [
+            ...this.scopes
+        ];
+        return serializeToBuffer(this.randomness, this.msgContent.length, ...this.msgContent, this.l2BlockNumber, this.l2BlockHash, this.txHash, this.txIndexInBlock, this.eventIndexInTx, this.contractAddress, this.eventSelector.toBuffer(), scopesArray.length, ...scopesArray);
+    }
+    static fromBuffer(buffer) {
+        const reader = BufferReader.asReader(buffer);
+        const randomness = Fr.fromBuffer(reader);
+        const msgContentLength = reader.readNumber();
+        const msgContent = reader.readArray(msgContentLength, Fr);
+        const l2BlockNumber = reader.readNumber();
+        const l2BlockHash = BlockHash.fromBuffer(reader);
+        const txHash = TxHash.fromBuffer(reader);
+        const txIndexInBlock = reader.readNumber();
+        const eventIndexInTx = reader.readNumber();
+        const contractAddress = AztecAddress.fromBuffer(reader);
+        const eventSelector = EventSelector.fromBuffer(reader);
+        const scopes = reader.readVector({
+            fromBuffer: (r)=>r.readString()
+        });
+        return new StoredPrivateEvent(randomness, msgContent, l2BlockNumber, l2BlockHash, txHash, txIndexInBlock, eventIndexInTx, contractAddress, eventSelector, new Set(scopes));
+    }
+}

package/dest/storage/rollbackable.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A store holding block-indexed state that must be truncated when a chain prune (reorg) is detected.
+ */
+export interface Rollbackable {
+    /**
+     * Rolls the store back to `toBlock`: deletes all state originating from blocks strictly above it, as if nothing
+     * past that block height ever happened.
+     *
+     * Called inside an already open store transaction shared with every other rollbackable and with the anchor block
+     * update, so implementations must not open one of their own. Throwing aborts that transaction, undoing the whole
+     * prune and leaving the sync cursor untouched so the prune event is re-emitted on the next sync.
+     */
+    rollbackToBlock(toBlock: number): Promise<void>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicm9sbGJhY2thYmxlLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvc3RvcmFnZS9yb2xsYmFja2FibGUudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7O0dBRUc7QUFDSCxNQUFNLFdBQVcsWUFBWTtJQUMzQjs7Ozs7OztPQU9HO0lBQ0gsZUFBZSxDQUFDLE9BQU8sRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQUFDO0NBQ2pEIn0=

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

@@ -0,0 +1 @@
+{"version":3,"file":"rollbackable.d.ts","sourceRoot":"","sources":["../../src/storage/rollbackable.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjD"}

package/dest/storage/rollbackable.js

@@ -0,0 +1,3 @@
+/**
+ * A store holding block-indexed state that must be truncated when a chain prune (reorg) is detected.
+ */ export { };

package/dest/storage/staged_write_coordinator.d.ts

@@ -0,0 +1,103 @@
+import { type LoggerBindings } from '@aztec-labs/foundation/log';
+import type { AztecAsyncKVStore } from '@aztec-labs/kv-store';
+/**
+ * Identifies a change set: the writes staged between a {@link StagedWriteCoordinator.begin} and its matching commit or
+ * abort, which are promoted to the database or dropped as a unit.
+ */
+export type ChangeSetId = string;
+/**
+ * A store that buffers its writes per change set instead of sending them straight to the database.
+ *
+ * Every read and write on such a store takes a change set ID. Writes are held under that ID; a read sees the database
+ * plus whatever its own change set has staged, never another's.
+ *
+ * {@link StagedWriteCoordinator} ends a change set by calling {@link commitChangeSet}, which promotes its staged writes
+ * to the database, or {@link discardChangeSet}, which throws them away.
+ */
+export interface StagedStore {
+    /** Unique name identifying this store (used for tracking staged stores from StagedWriteCoordinator) */
+    readonly storeName: string;
+    /**
+     * Notifies the store that a change set has been opened.
+     *
+     * TODO: make it required once every staged store extends `BaseStagingStore`. It is optional only while
+     * they migrate to per-change-set staging.
+     *
+     * @param changeSetId - The change set identifier
+     */
+    beginChangeSet?(changeSetId: ChangeSetId): void;
+    /**
+     * Commits staged data to persistent storage. Will be called within a db transaction for atomicity, alongside the
+     * writes of all other staged stores for the same change set.
+     *
+     * @param changeSetId - The change set identifier
+     */
+    commitChangeSet(changeSetId: ChangeSetId): Promise<void>;
+    /**
+     * Discards staged data without committing. Called on abort.
+     *
+     * @param changeSetId - The change set identifier
+     */
+    discardChangeSet(changeSetId: ChangeSetId): void;
+}
+/**
+ * StagedWriteCoordinator simulates a database transaction across the PXE stores, which some underlying KV stores
+ * (e.g. IndexedDB) cannot provide on their own for long-running async operations.
+ *
+ * It uses a staged writes pattern:
+ * 1. When a change set is opened, a unique ID is created
+ * 2. While a change set is open, all writes are staged under its ID, and reads observe the staged data
+ * 3. On commit, the staged data is promoted to persistent storage
+ * 4. On abort, staged data is discarded
+ *
+ * Only one change set can be open at a time: {@link begin} throws if one already is. Supporting overlapping change
+ * sets would mean merging them when one of them commits — a problem in its own right, and one no caller needs solved.
+ * Avoiding that throw is up to the caller, which must serialize whatever opens change sets, e.g. with a queue.
+ *
+ * Staged data is nonetheless keyed by change set ID, because aborting a change set does not cancel the async work it
+ * started. An oracle that was mid-write when the operation failed still finishes writing afterwards, and stages its
+ * write under the aborted ID, which nothing will ever promote. Were staged data not keyed by ID, that late write
+ * would instead sit in the store and be promoted by whichever change set commits next.
+ */
+export declare class StagedWriteCoordinator {
+    #private;
+    constructor(args: StagedWriteCoordinatorArgs);
+    /**
+     * Opens a change set and returns its ID for staged writes.
+     *
+     * All or nothing: if a store fails to open the change set, the stores that already opened it discard it again and
+     * nothing is left active, so a later change set can still be opened on this PXE instance.
+     *
+     * @returns Change set ID to pass to store operations
+     * @throws If a change set is already open, or if a store rejects the new one.
+     */
+    begin(): ChangeSetId;
+    /**
+     * Commits by promoting all staged data to persistent storage.
+     *
+     * Unlike {@link begin} and {@link abort}, a failed commit leaves the change set open, so the caller must still
+     * {@link abort} it before another can be opened.
+     *
+     * @param changeSetId - The change set ID returned from begin
+     * @throws If `changeSetId` is not the open change set, or if a store failed to commit.
+     */
+    commit(changeSetId: ChangeSetId): Promise<void>;
+    /**
+     * Aborts by discarding all staged data.
+     *
+     * Every store gets to drop its staged data even if an earlier one failed, and the change set always ends, so a
+     * failed abort never blocks later change sets.
+     *
+     * @param changeSetId - The change set ID returned from begin
+     * @throws If `changeSetId` is not the open change set, or if any store failed to discard.
+     */
+    abort(changeSetId: ChangeSetId): void;
+}
+/** Dependencies of the {@link StagedWriteCoordinator}. */
+type StagedWriteCoordinatorArgs = {
+    kvStore: AztecAsyncKVStore;
+    stagedStores: StagedStore[];
+    bindings?: LoggerBindings;
+};
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3RhZ2VkX3dyaXRlX2Nvb3JkaW5hdG9yLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvc3RvcmFnZS9zdGFnZWRfd3JpdGVfY29vcmRpbmF0b3IudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQ0EsT0FBTyxFQUFlLEtBQUssY0FBYyxFQUFnQixNQUFNLDRCQUE0QixDQUFDO0FBQzVGLE9BQU8sS0FBSyxFQUFFLGlCQUFpQixFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFFOUQ7OztHQUdHO0FBQ0gsTUFBTSxNQUFNLFdBQVcsR0FBRyxNQUFNLENBQUM7QUFFakM7Ozs7Ozs7O0dBUUc7QUFDSCxNQUFNLFdBQVcsV0FBVztJQUMxQix1R0FBdUc7SUFDdkcsUUFBUSxDQUFDLFNBQVMsRUFBRSxNQUFNLENBQUM7SUFFM0I7Ozs7Ozs7T0FPRztJQUNILGNBQWMsQ0FBQyxDQUFDLFdBQVcsRUFBRSxXQUFXLEdBQUcsSUFBSSxDQUFDO0lBRWhEOzs7OztPQUtHO0lBQ0gsZUFBZSxDQUFDLFdBQVcsRUFBRSxXQUFXLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQUFDO0lBRXpEOzs7O09BSUc7SUFDSCxnQkFBZ0IsQ0FBQyxXQUFXLEVBQUUsV0FBVyxHQUFHLElBQUksQ0FBQztDQUNsRDtBQUVEOzs7Ozs7Ozs7Ozs7Ozs7Ozs7R0FrQkc7QUFDSCxxQkFBYSxzQkFBc0I7O0lBT2pDLFlBQVksSUFBSSxFQUFFLDBCQUEwQixFQVMzQztJQUVEOzs7Ozs7OztPQVFHO0lBQ0gsS0FBSyxJQUFJLFdBQVcsQ0FhbkI7SUFFRDs7Ozs7Ozs7T0FRRztJQUNHLE1BQU0sQ0FBQyxXQUFXLEVBQUUsV0FBVyxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FtQnBEO0lBRUQ7Ozs7Ozs7O09BUUc7SUFDSCxLQUFLLENBQUMsV0FBVyxFQUFFLFdBQVcsR0FBRyxJQUFJLENBY3BDO0NBK0NGO0FBRUQsMERBQTBEO0FBQzFELEtBQUssMEJBQTBCLEdBQUc7SUFDaEMsT0FBTyxFQUFFLGlCQUFpQixDQUFDO0lBQzNCLFlBQVksRUFBRSxXQUFXLEVBQUUsQ0FBQztJQUM1QixRQUFRLENBQUMsRUFBRSxjQUFjLENBQUM7Q0FDM0IsQ0FBQyJ9

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

@@ -0,0 +1 @@
+{"version":3,"file":"staged_write_coordinator.d.ts","sourceRoot":"","sources":["../../src/storage/staged_write_coordinator.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,KAAK,cAAc,EAAgB,MAAM,4BAA4B,CAAC;AAC5F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC;AAEjC;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,uGAAuG;IACvG,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;;;;;;OAOG;IACH,cAAc,CAAC,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IAEhD;;;;;OAKG;IACH,eAAe,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzD;;;;OAIG;IACH,gBAAgB,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;CAClD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,sBAAsB;;IAOjC,YAAY,IAAI,EAAE,0BAA0B,EAS3C;IAED;;;;;;;;OAQG;IACH,KAAK,IAAI,WAAW,CAanB;IAED;;;;;;;;OAQG;IACG,MAAM,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBpD;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI,CAcpC;CA+CF;AAED,0DAA0D;AAC1D,KAAK,0BAA0B,GAAG;IAChC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B,CAAC"}

package/dest/storage/staged_write_coordinator.js

@@ -0,0 +1,141 @@
+import { randomBytes } from '@aztec-labs/foundation/crypto/random';
+import { createLogger } from '@aztec-labs/foundation/log';
+/**
+ * StagedWriteCoordinator simulates a database transaction across the PXE stores, which some underlying KV stores
+ * (e.g. IndexedDB) cannot provide on their own for long-running async operations.
+ *
+ * It uses a staged writes pattern:
+ * 1. When a change set is opened, a unique ID is created
+ * 2. While a change set is open, all writes are staged under its ID, and reads observe the staged data
+ * 3. On commit, the staged data is promoted to persistent storage
+ * 4. On abort, staged data is discarded
+ *
+ * Only one change set can be open at a time: {@link begin} throws if one already is. Supporting overlapping change
+ * sets would mean merging them when one of them commits — a problem in its own right, and one no caller needs solved.
+ * Avoiding that throw is up to the caller, which must serialize whatever opens change sets, e.g. with a queue.
+ *
+ * Staged data is nonetheless keyed by change set ID, because aborting a change set does not cancel the async work it
+ * started. An oracle that was mid-write when the operation failed still finishes writing afterwards, and stages its
+ * write under the aborted ID, which nothing will ever promote. Were staged data not keyed by ID, that late write
+ * would instead sit in the store and be promoted by whichever change set commits next.
+ */ export class StagedWriteCoordinator {
+    #kvStore;
+    #stagedStores = new Map();
+    #log;
+    #currentChangeSetId;
+    constructor(args){
+        this.#kvStore = args.kvStore;
+        this.#log = createLogger('pxe:staged_write_coordinator', args.bindings);
+        for (const store of args.stagedStores){
+            if (this.#stagedStores.has(store.storeName)) {
+                throw new Error(`Store "${store.storeName}" is already registered`);
+            }
+            this.#stagedStores.set(store.storeName, store);
+        }
+    }
+    /**
+   * Opens a change set and returns its ID for staged writes.
+   *
+   * All or nothing: if a store fails to open the change set, the stores that already opened it discard it again and
+   * nothing is left active, so a later change set can still be opened on this PXE instance.
+   *
+   * @returns Change set ID to pass to store operations
+   * @throws If a change set is already open, or if a store rejects the new one.
+   */ begin() {
+        if (this.#currentChangeSetId) {
+            throw new Error(`Cannot open change set: change set ${this.#currentChangeSetId} is already active. ` + `This should not happen - ensure change sets are properly committed or aborted.`);
+        }
+        const changeSetId = randomBytes(8).toString('hex');
+        this.#beginChangeSetOnStores(changeSetId);
+        this.#currentChangeSetId = changeSetId;
+        this.#log.debug(`Opened change set ${changeSetId}`, {
+            changeSetId
+        });
+        return changeSetId;
+    }
+    /**
+   * Commits by promoting all staged data to persistent storage.
+   *
+   * Unlike {@link begin} and {@link abort}, a failed commit leaves the change set open, so the caller must still
+   * {@link abort} it before another can be opened.
+   *
+   * @param changeSetId - The change set ID returned from begin
+   * @throws If `changeSetId` is not the open change set, or if a store failed to commit.
+   */ async commit(changeSetId) {
+        if (this.#currentChangeSetId !== changeSetId) {
+            throw new Error(`Cannot commit change set ${changeSetId}: no matching change set active. ` + `Current change set: ${this.#currentChangeSetId ?? 'none'}`);
+        }
+        this.#log.debug(`Committing change set ${changeSetId}`, {
+            changeSetId
+        });
+        // Commit all stores atomically in a single transaction.
+        await this.#kvStore.transactionAsync(async ()=>{
+            for (const store of this.#stagedStores.values()){
+                await store.commitChangeSet(changeSetId);
+            }
+        });
+        this.#currentChangeSetId = undefined;
+        this.#log.debug(`Change set ${changeSetId} committed successfully`, {
+            changeSetId
+        });
+    }
+    /**
+   * Aborts by discarding all staged data.
+   *
+   * Every store gets to drop its staged data even if an earlier one failed, and the change set always ends, so a
+   * failed abort never blocks later change sets.
+   *
+   * @param changeSetId - The change set ID returned from begin
+   * @throws If `changeSetId` is not the open change set, or if any store failed to discard.
+   */ abort(changeSetId) {
+        if (this.#currentChangeSetId !== changeSetId) {
+            throw new Error(`Cannot abort change set ${changeSetId}: no matching change set active. ` + `Current change set: ${this.#currentChangeSetId ?? 'none'}`);
+        }
+        this.#log.debug(`Aborting change set ${changeSetId}`, {
+            changeSetId
+        });
+        this.#currentChangeSetId = undefined;
+        this.#discardChangeSetOnStores(this.#stagedStores.values(), changeSetId);
+        this.#log.debug(`Change set ${changeSetId} aborted`, {
+            changeSetId
+        });
+    }
+    /** Opens the change set on every store, undoing it on any that accepted if a later one rejects, and rethrows. */ #beginChangeSetOnStores(changeSetId) {
+        const begunStores = [];
+        try {
+            for (const store of this.#stagedStores.values()){
+                store.beginChangeSet?.(changeSetId);
+                begunStores.push(store);
+            }
+        } catch (err) {
+            try {
+                this.#discardChangeSetOnStores(begunStores, changeSetId);
+            } catch (discardError) {
+                // The original error is that a store failed to begin the changeset, and we're throwing that
+                // unconditionally, so we just log this additional failure.
+                this.#log.error(`Failed to roll back change set ${changeSetId} after a store rejected it`, discardError, {
+                    changeSetId
+                });
+            }
+            throw err;
+        }
+    }
+    /** Discards the change set on every store in `stores`, throwing only once they have all had the chance. */ #discardChangeSetOnStores(stores, changeSetId) {
+        // A store that fails must not stop the ones after it, so the failures are collected and thrown at the end.
+        const failures = [];
+        for (const store of stores){
+            try {
+                store.discardChangeSet(changeSetId);
+            } catch (err) {
+                failures.push(new Error(`Store "${store.storeName}" failed to discard change set ${changeSetId} and may still hold staged data.`, {
+                    cause: err
+                }));
+            }
+        }
+        if (failures.length === 1) {
+            throw failures[0];
+        } else if (failures.length > 1) {
+            throw new AggregateError(failures);
+        }
+    }
+}