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

package/dest/storage/fact_store/stored_fact.d.ts

@@ -0,0 +1,32 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { BufferReader } from '@aztec/foundation/serialize';
+import { FactCollectionKey, type OriginBlock } from './fact_store_keys.js';
+/** A fact as returned by the fact store. */
+export type Fact = {
+    factTypeId: Fr;
+    payload: Fr[];
+    originBlock: OriginBlock | undefined;
+};
+/**
+ * A single immutable fact belonging to a fact collection.
+ */
+export declare class StoredFact {
+    readonly factCollectionKey: FactCollectionKey;
+    readonly factTypeId: Fr;
+    readonly payload: Fr[];
+    readonly originBlock: OriginBlock | undefined;
+    constructor(factCollectionKey: FactCollectionKey, factTypeId: Fr, payload: Fr[], originBlock: OriginBlock | undefined);
+    /** Whether this fact is deleted on block pruning (true) or survives reorgs (false). */
+    get isRetractable(): boolean;
+    /** Stable digest of the payload, used for fact idempotency. */
+    payloadHash(): Fr;
+    /** Returns the externally facing view of this fact. */
+    toFact(): Fact;
+    toBuffer(): Buffer;
+    static fromBuffer(buffer: Buffer | BufferReader): StoredFact;
+}
+/**
+ * Builds the serialized key that identifies a fact in the store.
+ */
+export declare function factKeyStrOf(fact: StoredFact): string;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3RvcmVkX2ZhY3QuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9zdG9yYWdlL2ZhY3Rfc3RvcmUvc3RvcmVkX2ZhY3QudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQ0EsT0FBTyxFQUFFLEVBQUUsRUFBRSxNQUFNLGdDQUFnQyxDQUFDO0FBQ3BELE9BQU8sRUFBRSxZQUFZLEVBQXFCLE1BQU0sNkJBQTZCLENBQUM7QUFHOUUsT0FBTyxFQUFFLGlCQUFpQixFQUFFLEtBQUssV0FBVyxFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFFM0UsNENBQTRDO0FBQzVDLE1BQU0sTUFBTSxJQUFJLEdBQUc7SUFBRSxVQUFVLEVBQUUsRUFBRSxDQUFDO0lBQUMsT0FBTyxFQUFFLEVBQUUsRUFBRSxDQUFDO0lBQUMsV0FBVyxFQUFFLFdBQVcsR0FBRyxTQUFTLENBQUE7Q0FBRSxDQUFDO0FBRTNGOztHQUVHO0FBQ0gscUJBQWEsVUFBVTthQUVILGlCQUFpQixFQUFFLGlCQUFpQjthQUNwQyxVQUFVLEVBQUUsRUFBRTthQUNkLE9BQU8sRUFBRSxFQUFFLEVBQUU7YUFDYixXQUFXLEVBQUUsV0FBVyxHQUFHLFNBQVM7SUFKdEQsWUFDa0IsaUJBQWlCLEVBQUUsaUJBQWlCLEVBQ3BDLFVBQVUsRUFBRSxFQUFFLEVBQ2QsT0FBTyxFQUFFLEVBQUUsRUFBRSxFQUNiLFdBQVcsRUFBRSxXQUFXLEdBQUcsU0FBUyxFQUNsRDtJQUVKLHVGQUF1RjtJQUN2RixJQUFJLGFBQWEsSUFBSSxPQUFPLENBRTNCO0lBRUQsK0RBQStEO0lBQy9ELFdBQVcsSUFBSSxFQUFFLENBRWhCO0lBRUQsdURBQXVEO0lBQ3ZELE1BQU0sSUFBSSxJQUFJLENBRWI7SUFFRCxRQUFRLElBQUksTUFBTSxDQWFqQjtJQUVELE1BQU0sQ0FBQyxVQUFVLENBQUMsTUFBTSxFQUFFLE1BQU0sR0FBRyxZQUFZLEdBQUcsVUFBVSxDQW1CM0Q7Q0FDRjtBQUVEOztHQUVHO0FBQ0gsd0JBQWdCLFlBQVksQ0FBQyxJQUFJLEVBQUUsVUFBVSxHQUFHLE1BQU0sQ0FHckQifQ==

package/dest/storage/fact_store/stored_fact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stored_fact.d.ts","sourceRoot":"","sources":["../../../src/storage/fact_store/stored_fact.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,EAAE,EAAE,MAAM,gCAAgC,CAAC;AACpD,OAAO,EAAE,YAAY,EAAqB,MAAM,6BAA6B,CAAC;AAG9E,OAAO,EAAE,iBAAiB,EAAE,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAE3E,4CAA4C;AAC5C,MAAM,MAAM,IAAI,GAAG;IAAE,UAAU,EAAE,EAAE,CAAC;IAAC,OAAO,EAAE,EAAE,EAAE,CAAC;IAAC,WAAW,EAAE,WAAW,GAAG,SAAS,CAAA;CAAE,CAAC;AAE3F;;GAEG;AACH,qBAAa,UAAU;aAEH,iBAAiB,EAAE,iBAAiB;aACpC,UAAU,EAAE,EAAE;aACd,OAAO,EAAE,EAAE,EAAE;aACb,WAAW,EAAE,WAAW,GAAG,SAAS;IAJtD,YACkB,iBAAiB,EAAE,iBAAiB,EACpC,UAAU,EAAE,EAAE,EACd,OAAO,EAAE,EAAE,EAAE,EACb,WAAW,EAAE,WAAW,GAAG,SAAS,EAClD;IAEJ,uFAAuF;IACvF,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED,+DAA+D;IAC/D,WAAW,IAAI,EAAE,CAEhB;IAED,uDAAuD;IACvD,MAAM,IAAI,IAAI,CAEb;IAED,QAAQ,IAAI,MAAM,CAajB;IAED,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,UAAU,CAmB3D;CACF;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAGrD"}

package/dest/storage/fact_store/stored_fact.js

@@ -0,0 +1,64 @@
+import { sha256ToField } from '@aztec/foundation/crypto/sha256';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { FactCollectionKey } from './fact_store_keys.js';
+/**
+ * A single immutable fact belonging to a fact collection.
+ */ export class StoredFact {
+    factCollectionKey;
+    factTypeId;
+    payload;
+    originBlock;
+    constructor(factCollectionKey, factTypeId, payload, originBlock){
+        this.factCollectionKey = factCollectionKey;
+        this.factTypeId = factTypeId;
+        this.payload = payload;
+        this.originBlock = originBlock;
+    }
+    /** Whether this fact is deleted on block pruning (true) or survives reorgs (false). */ get isRetractable() {
+        return this.originBlock !== undefined;
+    }
+    /** Stable digest of the payload, used for fact idempotency. */ payloadHash() {
+        return sha256ToField([
+            this.payload.length,
+            ...this.payload
+        ]);
+    }
+    /** Returns the externally facing view of this fact. */ toFact() {
+        return {
+            factTypeId: this.factTypeId,
+            payload: this.payload,
+            originBlock: this.originBlock
+        };
+    }
+    toBuffer() {
+        return serializeToBuffer(this.factCollectionKey.contractAddress, this.factCollectionKey.scope, this.factCollectionKey.factCollectionTypeId, this.factCollectionKey.factCollectionId, this.factTypeId, this.payload.length, ...this.payload, this.originBlock !== undefined, this.originBlock ? this.originBlock.blockNumber : 0, this.originBlock ? this.originBlock.blockHash : Fr.ZERO);
+    }
+    static fromBuffer(buffer) {
+        const reader = BufferReader.asReader(buffer);
+        const contractAddress = reader.readObject(AztecAddress);
+        const scope = reader.readObject(AztecAddress);
+        const factCollectionTypeId = reader.readObject(Fr);
+        const factCollectionId = reader.readObject(Fr);
+        const factTypeId = reader.readObject(Fr);
+        const payloadLen = reader.readNumber();
+        const payload = reader.readArray(payloadLen, Fr);
+        const hasOriginBlock = reader.readBoolean();
+        const blockNumber = reader.readNumber();
+        const blockHash = reader.readObject(Fr);
+        const originBlock = hasOriginBlock ? {
+            blockNumber,
+            blockHash
+        } : undefined;
+        return new StoredFact(new FactCollectionKey(contractAddress, scope, factCollectionTypeId, factCollectionId), factTypeId, [
+            ...payload
+        ], originBlock);
+    }
+}
+/**
+ * Builds the serialized key that identifies a fact in the store.
+ */ export function factKeyStrOf(fact) {
+    const origin = fact.originBlock ? `${fact.originBlock.blockNumber}:${fact.originBlock.blockHash}` : 'none';
+    return `${fact.factCollectionKey}:${fact.factTypeId}:${fact.payloadHash()}:${origin}`;
+}

package/dest/storage/index.d.ts

@@ -1,9 +1,10 @@
-export * from './address_data_provider/index.js';
-export * from './capsule_data_provider/index.js';
-export * from './contract_data_provider/index.js';
-export * from './note_data_provider/index.js';
-export * from './sync_data_provider/index.js';
-export * from './tagging_data_provider/index.js';
+export * from './address_store/index.js';
+export * from './anchor_block_store/index.js';
+export * from './capsule_store/index.js';
+export * from './contract_store/index.js';
+export * from './fact_store/index.js';
+export * from './note_store/index.js';
+export * from './tagging_store/index.js';
 export * from './metadata.js';
-export * from './private_event_data_provider/private_event_data_provider.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9zdG9yYWdlL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsa0NBQWtDLENBQUM7QUFDakQsY0FBYyxrQ0FBa0MsQ0FBQztBQUNqRCxjQUFjLG1DQUFtQyxDQUFDO0FBQ2xELGNBQWMsK0JBQStCLENBQUM7QUFDOUMsY0FBYywrQkFBK0IsQ0FBQztBQUM5QyxjQUFjLGtDQUFrQyxDQUFDO0FBQ2pELGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsOERBQThELENBQUMifQ==
+export * from './private_event_store/private_event_store.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9zdG9yYWdlL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsMEJBQTBCLENBQUM7QUFDekMsY0FBYywrQkFBK0IsQ0FBQztBQUM5QyxjQUFjLDBCQUEwQixDQUFDO0FBQ3pDLGNBQWMsMkJBQTJCLENBQUM7QUFDMUMsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLHVCQUF1QixDQUFDO0FBQ3RDLGNBQWMsMEJBQTBCLENBQUM7QUFDekMsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyw4Q0FBOEMsQ0FBQyJ9

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

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

package/dest/storage/index.js

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

package/dest/storage/metadata.d.ts

@@ -1,2 +1,2 @@
-export declare const PXE_DATA_SCHEMA_VERSION = 2;
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibWV0YWRhdGEuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9zdG9yYWdlL21ldGFkYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGVBQU8sTUFBTSx1QkFBdUIsSUFBSSxDQUFDIn0=
+export declare const PXE_DATA_SCHEMA_VERSION = 13;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibWV0YWRhdGEuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9zdG9yYWdlL21ldGFkYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGVBQU8sTUFBTSx1QkFBdUIsS0FBSyxDQUFDIn0=

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

@@ -1 +1 @@
-{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/storage/metadata.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,uBAAuB,IAAI,CAAC"}
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/storage/metadata.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,uBAAuB,KAAK,CAAC"}

package/dest/storage/metadata.js

@@ -1 +1 @@
-export const PXE_DATA_SCHEMA_VERSION = 2;
+export const PXE_DATA_SCHEMA_VERSION = 13;

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

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

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

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

package/dest/storage/note_store/index.js

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

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

@@ -0,0 +1,92 @@
+import type { Fr } from '@aztec/foundation/schemas';
+import type { AztecAsyncKVStore } from '@aztec/kv-store';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { DataInBlock } from '@aztec/stdlib/block';
+import { NoteDao } from '@aztec/stdlib/note';
+import type { StagedStore } from '../../job_coordinator/job_coordinator.js';
+import type { NotesFilter } from '../../notes_filter.js';
+/**
+ * NoteStore manages the storage and retrieval of notes using an append-only model.
+ *
+ * Notes are written once (keyed by siloedNullifier) and never mutated. They might be deleted in case of reorg though.
+ * Nullifier emissions are recorded as separate append-only entries: a map from nullifier to the number of the block
+ * that emitted it.
+ *
+ * Reorgs are handled by delete-on-prune: the `chain-pruned` event triggers deletion of every note and nullifier
+ * originating on a reorg'd block.
+ */
+export declare class NoteStore implements StagedStore {
+    #private;
+    readonly storeName: string;
+    logger: import("@aztec/foundation/log").Logger;
+    constructor(store: AztecAsyncKVStore);
+    /**
+     * Adds multiple notes to the notes store under the specified scope.
+     *
+     * Notes are stored using their siloedNullifier as the key, which provides uniqueness. Each note is indexed by
+     * multiple criteria for efficient retrieval.
+     *
+     * @param notes - Notes to store
+     * @param scope - The scope (user/account) under which to store the notes
+     * @param jobId - The job context for staged writes
+     */
+    addNotes(notes: NoteDao[], scope: AztecAddress, jobId: string): Promise<void[]>;
+    /**
+     * Retrieves notes based on the provided filter criteria.
+     *
+     * A note is considered nullified iff its corresponding nullifier emission has been recorded.
+     *
+     * All DB reads are kicked off before any await so IndexedDB does not auto-commit the transaction mid-read.
+     *
+     * @param filter - Filter criteria including contractAddress (required), and optional owner,
+     *                 storageSlot, status, scopes, and siloedNullifier.
+     * @param jobId - the job context to read from.
+     * @returns Filtered and deduplicated notes (a note might be present in multiple scopes, but returned at most once)
+     */
+    getNotes(filter: NotesFilter, jobId: string): Promise<NoteDao[]>;
+    /**
+     * Records emission of the given siloed nullifiers, which causes notes to be considered nullified.
+     *
+     * Each nullifier gets an append-only entry recording the block number at which it was emitted.
+     *
+     * Every nullifier passed must correspond to a note already present in this store. Callers only apply nullifiers for
+     * notes of scopes they track, and a note is always discovered before the nullifier that spends it, so a nullifier
+     * with no matching note signals a bug (broken nonce/index discovery, a sync-ordering error, store corruption, etc).
+     *
+     * `applyNullifiers` is idempotent: a nullifier whose emission is already recorded (committed or staged in this job) is
+     * skipped, so re-applying it neither re-writes the emission, changes note visibility, nor appears in the result.
+     *
+     * @param siloedNullifiers - Array of nullifiers with their block locations to record
+     * @param jobId - The job context for staged writes
+     * @returns The notes that transition from active to nullified in this call; already-nullified notes are skipped, so
+     *          a repeat application returns an empty array.
+     * @throws If any nullifier has no matching note in this store, or was emitted at block 0.
+     */
+    applyNullifiers(siloedNullifiers: DataInBlock<Fr>[], jobId: string): Promise<NoteDao[]>;
+    /**
+     * Commits in-memory job data to persistent storage.
+     *
+     * Called by JobCoordinator when a job completes successfully.
+     *
+     * Note: JobCoordinator wraps all commits in a single transaction, so we don't need our own transactionAsync here
+     * (and using one would throw on IndexedDB as it does not support nested txs).
+     *
+     * @param jobId - The jobId identifying which staged data to commit
+     */
+    commit(jobId: string): Promise<void>;
+    discardStaged(jobId: string): Promise<void>;
+    /** Returns the nullifiers (note ids) of all notes created at the given block number. Used by delete-on-prune. */
+    nullifiersOfNotesAtBlock(blockNumber: number): Promise<string[]>;
+    /**
+     * Rolls the store back to `toBlock`: deletes every note and nullifier emission originating on a block strictly above
+     * it, as if nothing past that block height ever happened. Used to retract notes and nullifiers on a reorg.
+     *
+     * Must be called inside a transaction owned by the caller (it issues no `transactionAsync` of its own, because the
+     * reorg path wraps it together with other store operations, and IndexedDB has no nested transaction support).
+     *
+     * Throws if any job has uncommitted staged writes, since rolling back mid-job could later re-introduce notes or
+     * nullifier emissions anchored to deleted blocks.
+     */
+    rollback(toBlock: number): Promise<void>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibm90ZV9zdG9yZS5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL3N0b3JhZ2Uvbm90ZV9zdG9yZS9ub3RlX3N0b3JlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUVBLE9BQU8sS0FBSyxFQUFFLEVBQUUsRUFBRSxNQUFNLDJCQUEyQixDQUFDO0FBQ3BELE9BQU8sS0FBSyxFQUFFLGlCQUFpQixFQUFxQyxNQUFNLGlCQUFpQixDQUFDO0FBQzVGLE9BQU8sS0FBSyxFQUFFLFlBQVksRUFBRSxNQUFNLDZCQUE2QixDQUFDO0FBQ2hFLE9BQU8sS0FBSyxFQUFFLFdBQVcsRUFBRSxNQUFNLHFCQUFxQixDQUFDO0FBQ3ZELE9BQU8sRUFBRSxPQUFPLEVBQWMsTUFBTSxvQkFBb0IsQ0FBQztBQUV6RCxPQUFPLEtBQUssRUFBRSxXQUFXLEVBQUUsTUFBTSwwQ0FBMEMsQ0FBQztBQUM1RSxPQUFPLEtBQUssRUFBRSxXQUFXLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQVV6RDs7Ozs7Ozs7O0dBU0c7QUFDSCxxQkFBYSxTQUFVLFlBQVcsV0FBVzs7SUFDM0MsUUFBUSxDQUFDLFNBQVMsRUFBRSxNQUFNLENBQVU7SUFFcEMsTUFBTSx5Q0FBOEI7SUEwQ3BDLFlBQVksS0FBSyxFQUFFLGlCQUFpQixFQVduQztJQUVEOzs7Ozs7Ozs7T0FTRztJQUNJLFFBQVEsQ0FBQyxLQUFLLEVBQUUsT0FBTyxFQUFFLEVBQUUsS0FBSyxFQUFFLFlBQVksRUFBRSxLQUFLLEVBQUUsTUFBTSxHQUFHLE9BQU8sQ0FBQyxJQUFJLEVBQUUsQ0FBQyxDQWFyRjtJQStCRDs7Ozs7Ozs7Ozs7T0FXRztJQUNILFFBQVEsQ0FBQyxNQUFNLEVBQUUsV0FBVyxFQUFFLEtBQUssRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLE9BQU8sRUFBRSxDQUFDLENBOEYvRDtJQUVEOzs7Ozs7Ozs7Ozs7Ozs7OztPQWlCRztJQUNILGVBQWUsQ0FBQyxnQkFBZ0IsRUFBRSxXQUFXLENBQUMsRUFBRSxDQUFDLEVBQUUsRUFBRSxLQUFLLEVBQUUsTUFBTSxHQUFHLE9BQU8sQ0FBQyxPQUFPLEVBQUUsQ0FBQyxDQXlDdEY7SUFFRDs7Ozs7Ozs7O09BU0c7SUFDRyxNQUFNLENBQUMsS0FBSyxFQUFFLE1BQU0sR0FBRyxPQUFPLENBQUMsSUFBSSxDQUFDLENBYXpDO0lBRUQsYUFBYSxDQUFDLEtBQUssRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQUcxQztJQTZDRCxpSEFBaUg7SUFDcEcsd0JBQXdCLENBQUMsV0FBVyxFQUFFLE1BQU0sR0FBRyxPQUFPLENBQUMsTUFBTSxFQUFFLENBQUMsQ0FNNUU7SUFFRDs7Ozs7Ozs7O09BU0c7SUFDVSxRQUFRLENBQUMsT0FBTyxFQUFFLE1BQU0sR0FBRyxPQUFPLENBQUMsSUFBSSxDQUFDLENBa0RwRDtDQUNGIn0=

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

@@ -0,0 +1 @@
+{"version":3,"file":"note_store.d.ts","sourceRoot":"","sources":["../../../src/storage/note_store/note_store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,2BAA2B,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAqC,MAAM,iBAAiB,CAAC;AAC5F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,OAAO,EAAc,MAAM,oBAAoB,CAAC;AAEzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0CAA0C,CAAC;AAC5E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAUzD;;;;;;;;;GASG;AACH,qBAAa,SAAU,YAAW,WAAW;;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAU;IAEpC,MAAM,yCAA8B;IA0CpC,YAAY,KAAK,EAAE,iBAAiB,EAWnC;IAED;;;;;;;;;OASG;IACI,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAarF;IA+BD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CA8F/D;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,eAAe,CAAC,gBAAgB,EAAE,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAyCtF;IAED;;;;;;;;;OASG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAazC;IAED,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG1C;IA6CD,iHAAiH;IACpG,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAM5E;IAED;;;;;;;;;OASG;IACU,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkDpD;CACF"}

package/dest/storage/note_store/note_store.js

@@ -0,0 +1,372 @@
+import { createLogger } from '@aztec/foundation/log';
+import { Semaphore } from '@aztec/foundation/queue';
+import { NoteStatus } from '@aztec/stdlib/note';
+import { StoredNote } from './stored_note.js';
+/**
+ * NoteStore manages the storage and retrieval of notes using an append-only model.
+ *
+ * Notes are written once (keyed by siloedNullifier) and never mutated. They might be deleted in case of reorg though.
+ * Nullifier emissions are recorded as separate append-only entries: a map from nullifier to the number of the block
+ * that emitted it.
+ *
+ * Reorgs are handled by delete-on-prune: the `chain-pruned` event triggers deletion of every note and nullifier
+ * originating on a reorg'd block.
+ */ export class NoteStore {
+    storeName = 'note';
+    logger = createLogger('note_store');
+    #store;
+    // Note that we use the siloedNullifier as the note id in this store as it's guaranteed to be unique.
+    // Main storage for notes. Avoid performing full scans on it as it contains all notes PXE knows, use
+    // #nullifiersByContractAddress to find relevant note nullifiers that can be used to read into this map instead.
+    //
+    // nullifier => StoredNote (serialized)
+    #notes;
+    // Indexes which notes (via their nullifiers) belong to a contract. Used in `getNotes` to reduce the amount of notes
+    // checked.
+    //
+    // contract address => nullifier
+    #notesByContractAddress;
+    // block number => nullifier
+    #notesByBlockNumber;
+    // Records, for each nullified note, the block number where its nullifier was emitted.
+    // nullifier => emission block number
+    #nullifierEmissions;
+    // Index of emitted nullifiers by block height, used for performance reasons upon reorgs.
+    // nullification block number => nullifier
+    #nullifierEmissionsByBlockNumber;
+    // In-memory changes performed during a not-yet committed job. When `commit` is called with said job's id, these
+    // changes are persisted in the DB maps specified above and cleared.
+    // jobId => nullifier => StoredNote
+    #notesForJob;
+    // Staged nullifier emissions per job.
+    // jobId => nullifier => emission block number
+    #nullifierEmissionsForJob;
+    // Per job locks to prevent multiple concurrent writes to affect each other.
+    // jobId => lock
+    #jobLocks;
+    constructor(store){
+        this.#store = store;
+        this.#notes = store.openMap('notes');
+        this.#notesByContractAddress = store.openMultiMap('note_nullifiers_by_contract');
+        this.#notesByBlockNumber = store.openMultiMap('note_nullifiers_by_block');
+        this.#nullifierEmissions = store.openMap('note_nullifications_by_nullifier');
+        this.#nullifierEmissionsByBlockNumber = store.openMultiMap('note_nullifications_by_block');
+        this.#jobLocks = new Map();
+        this.#notesForJob = new Map();
+        this.#nullifierEmissionsForJob = new Map();
+    }
+    /**
+   * Adds multiple notes to the notes store under the specified scope.
+   *
+   * Notes are stored using their siloedNullifier as the key, which provides uniqueness. Each note is indexed by
+   * multiple criteria for efficient retrieval.
+   *
+   * @param notes - Notes to store
+   * @param scope - The scope (user/account) under which to store the notes
+   * @param jobId - The job context for staged writes
+   */ addNotes(notes, scope, jobId) {
+        return this.#withJobLock(jobId, ()=>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);
+                }))));
+    }
+    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);
+    }
+    #writeNote(note, jobId) {
+        this.#getNotesForJob(jobId).set(note.noteDao.siloedNullifier.toString(), note);
+    }
+    /**
+   * Reads the block number at which a note's nullifier was emitted, layering the current job's staged emission over
+   * committed state, the nullifier emission counterpart to {@link #readNote}. Returns the emission block number if the
+   * nullifier has been emitted (committed or staged in this job), or `undefined` if it has not.
+   */ async #readNullifierEmission(nullifier, jobId) {
+        // Always issue the DB read to keep the IndexedDB transaction alive (see #readNote); the staged emission still takes
+        // precedence if present.
+        const committed = await this.#nullifierEmissions.getAsync(nullifier);
+        const staged = this.#getNullifierEmissionsForJob(jobId).get(nullifier);
+        return staged ?? committed;
+    }
+    #writeNullifierEmission(nullifier, blockNumber, jobId) {
+        this.#getNullifierEmissionsForJob(jobId).set(nullifier, blockNumber);
+    }
+    /**
+   * Retrieves notes based on the provided filter criteria.
+   *
+   * A note is considered nullified iff its corresponding nullifier emission has been recorded.
+   *
+   * All DB reads are kicked off before any await so IndexedDB does not auto-commit the transaction mid-read.
+   *
+   * @param filter - Filter criteria including contractAddress (required), and optional owner,
+   *                 storageSlot, status, scopes, and siloedNullifier.
+   * @param jobId - the job context to read from.
+   * @returns Filtered and deduplicated notes (a note might be present in multiple scopes, but returned at most once)
+   */ getNotes(filter, jobId) {
+        if (filter.scopes.length === 0) {
+            return Promise.resolve([]);
+        }
+        return this.#store.transactionAsync(async ()=>{
+            const targetStatus = filter.status ?? NoteStatus.ACTIVE;
+            // Collect note-read and nullifier-emission-read promises together in one map so all DB reads are in-flight
+            // before any await. This keeps the IndexedDB transaction alive (IndexedDB auto-commits when a new micro-task
+            // starts with no pending read requests), so both promises must be started during the synchronous iteration.
+            const candidates = new Map();
+            // Committed notes indexed by contract address
+            for await (const nullifier of this.#notesByContractAddress.getValuesAsync(filter.contractAddress.toString())){
+                candidates.set(nullifier, {
+                    notePromise: this.#readNote(nullifier, jobId),
+                    nullificationPromise: this.#readNullifierEmission(nullifier, jobId)
+                });
+            }
+            // Staged notes from the current job (not yet committed to the DB index)
+            for (const storedNote of this.#getNotesForJob(jobId).values()){
+                if (storedNote.noteDao.contractAddress.equals(filter.contractAddress)) {
+                    const nullifier = storedNote.noteDao.siloedNullifier.toString();
+                    if (!candidates.has(nullifier)) {
+                        candidates.set(nullifier, {
+                            notePromise: Promise.resolve(storedNote),
+                            nullificationPromise: this.#readNullifierEmission(nullifier, jobId)
+                        });
+                    }
+                }
+            }
+            // Await all DB reads together before the await-free tail.
+            const entries = [
+                ...candidates.entries()
+            ];
+            const notes = await Promise.all(entries.map(([, { notePromise }])=>notePromise));
+            const nullifierEmissions = await Promise.all(entries.map(([, { nullificationPromise }])=>nullificationPromise));
+            // Await-free tail: filter and sort. No DB ops from here on.
+            // Build a lookup: nullifier => emission block number
+            const emissionByNullifier = new Map();
+            for(let i = 0; i < entries.length; i++){
+                emissionByNullifier.set(entries[i][0], nullifierEmissions[i]);
+            }
+            const foundNotes = new Map();
+            for (const note of notes){
+                // Defensive: hitting this case means we're mishandling contract indices or in-memory job data
+                if (!note) {
+                    throw new Error('PXE note database is corrupted.');
+                }
+                // A note is nullified once its nullifier emission has been recorded (committed or staged in this job).
+                const nullified = emissionByNullifier.get(note.noteDao.siloedNullifier.toString()) !== undefined;
+                if (targetStatus === NoteStatus.ACTIVE && nullified) {
+                    continue;
+                }
+                if (filter.owner && !note.noteDao.owner.equals(filter.owner)) {
+                    continue;
+                }
+                if (filter.storageSlot && !note.noteDao.storageSlot.equals(filter.storageSlot)) {
+                    continue;
+                }
+                if (filter.siloedNullifier && !note.noteDao.siloedNullifier.equals(filter.siloedNullifier)) {
+                    continue;
+                }
+                if (note.scopes.intersection(new Set(filter.scopes.map((s)=>s.toString()))).size === 0) {
+                    continue;
+                }
+                foundNotes.set(note.noteDao.siloedNullifier.toString(), note.noteDao);
+            }
+            // Sort by block number, then by tx index within block, then by note index within tx
+            return [
+                ...foundNotes.values()
+            ].sort((a, b)=>{
+                if (a.l2BlockNumber !== b.l2BlockNumber) {
+                    return a.l2BlockNumber - b.l2BlockNumber;
+                }
+                if (a.txIndexInBlock !== b.txIndexInBlock) {
+                    return a.txIndexInBlock - b.txIndexInBlock;
+                }
+                return a.noteIndexInTx - b.noteIndexInTx;
+            });
+        });
+    }
+    /**
+   * Records emission of the given siloed nullifiers, which causes notes to be considered nullified.
+   *
+   * Each nullifier gets an append-only entry recording the block number at which it was emitted.
+   *
+   * Every nullifier passed must correspond to a note already present in this store. Callers only apply nullifiers for
+   * notes of scopes they track, and a note is always discovered before the nullifier that spends it, so a nullifier
+   * with no matching note signals a bug (broken nonce/index discovery, a sync-ordering error, store corruption, etc).
+   *
+   * `applyNullifiers` is idempotent: a nullifier whose emission is already recorded (committed or staged in this job) is
+   * skipped, so re-applying it neither re-writes the emission, changes note visibility, nor appears in the result.
+   *
+   * @param siloedNullifiers - Array of nullifiers with their block locations to record
+   * @param jobId - The job context for staged writes
+   * @returns The notes that transition from active to nullified in this call; already-nullified notes are skipped, so
+   *          a repeat application returns an empty array.
+   * @throws If any nullifier has no matching note in this store, or was emitted at block 0.
+   */ applyNullifiers(siloedNullifiers, jobId) {
+        if (siloedNullifiers.length === 0) {
+            return Promise.resolve([]);
+        }
+        if (siloedNullifiers.some((n)=>n.l2BlockNumber === 0)) {
+            return Promise.reject(new Error('applyNullifiers: nullifiers cannot have been emitted at block 0'));
+        }
+        return this.#withJobLock(jobId, ()=>this.#store.transactionAsync(async ()=>{
+                // Kick off the note read and the existing-emission read together during the synchronous map so all are in
+                // flight before the first await, which keeps the IndexedDB transaction alive.
+                const resolved = await Promise.all(siloedNullifiers.map(async (nullifier)=>{
+                    const key = nullifier.data.toString();
+                    const [storedNote, existingEmission] = await Promise.all([
+                        this.#readNote(key, jobId),
+                        this.#readNullifierEmission(key, jobId)
+                    ]);
+                    if (!storedNote) {
+                        throw new Error(`Attempted to mark a note as nullified which does not exist in PXE DB: ${key}`);
+                    }
+                    return {
+                        nullifier,
+                        storedNote,
+                        alreadyEmitted: existingEmission !== undefined
+                    };
+                }));
+                // Await-free tail: record an emission only for notes not already nullified, and return exactly those that
+                // transition active -> nullified in this call.
+                const affected = [];
+                for (const { nullifier, storedNote, alreadyEmitted } of resolved){
+                    if (alreadyEmitted) {
+                        continue;
+                    }
+                    this.#writeNullifierEmission(nullifier.data.toString(), nullifier.l2BlockNumber, jobId);
+                    affected.push(storedNote.noteDao);
+                }
+                return affected;
+            }));
+    }
+    /**
+   * Commits in-memory job data to persistent storage.
+   *
+   * Called by JobCoordinator when a job completes successfully.
+   *
+   * Note: JobCoordinator wraps all commits in a single transaction, so we don't need our own transactionAsync here
+   * (and using one would throw on IndexedDB as it does not support nested txs).
+   *
+   * @param jobId - The jobId identifying which staged data to commit
+   */ async commit(jobId) {
+        for (const [nullifier, storedNote] of this.#getNotesForJob(jobId)){
+            await this.#notes.set(nullifier, storedNote.toBuffer());
+            await this.#notesByContractAddress.set(storedNote.noteDao.contractAddress.toString(), nullifier);
+            await this.#notesByBlockNumber.set(storedNote.noteDao.l2BlockNumber, nullifier);
+        }
+        for (const [nullifier, blockNumber] of this.#getNullifierEmissionsForJob(jobId)){
+            await this.#nullifierEmissions.set(nullifier, blockNumber);
+            await this.#nullifierEmissionsByBlockNumber.set(blockNumber, nullifier);
+        }
+        this.#clearJobData(jobId);
+    }
+    discardStaged(jobId) {
+        this.#clearJobData(jobId);
+        return Promise.resolve();
+    }
+    #clearJobData(jobId) {
+        this.#notesForJob.delete(jobId);
+        this.#nullifierEmissionsForJob.delete(jobId);
+        this.#jobLocks.delete(jobId);
+    }
+    /**
+   * Functions run withJobLock are forced to wait for each other, i.e. if they share a `jobId`, they run serially
+   * instead of concurrently. This is needed because staged data is stored in memory, and concurrent async operations
+   * (e.g., Promise.all in `validateAndStoreNote`) could otherwise interleave and corrupt state.
+   */ async #withJobLock(jobId, fn) {
+        let lock = this.#jobLocks.get(jobId);
+        if (!lock) {
+            lock = new Semaphore(1);
+            this.#jobLocks.set(jobId, lock);
+        }
+        await lock.acquire();
+        try {
+            return await fn();
+        } finally{
+            lock.release();
+        }
+    }
+    #getNotesForJob(jobId) {
+        let notesForJob = this.#notesForJob.get(jobId);
+        if (!notesForJob) {
+            notesForJob = new Map();
+            this.#notesForJob.set(jobId, notesForJob);
+        }
+        return notesForJob;
+    }
+    #getNullifierEmissionsForJob(jobId) {
+        let nullificationsForJob = this.#nullifierEmissionsForJob.get(jobId);
+        if (!nullificationsForJob) {
+            nullificationsForJob = new Map();
+            this.#nullifierEmissionsForJob.set(jobId, nullificationsForJob);
+        }
+        return nullificationsForJob;
+    }
+    /** Returns the nullifiers (note ids) of all notes created at the given block number. Used by delete-on-prune. */ async nullifiersOfNotesAtBlock(blockNumber) {
+        const nullifiers = [];
+        for await (const nullifier of this.#notesByBlockNumber.getValuesAsync(blockNumber)){
+            nullifiers.push(nullifier);
+        }
+        return nullifiers;
+    }
+    /**
+   * Rolls the store back to `toBlock`: deletes every note and nullifier emission originating on a block strictly above
+   * it, as if nothing past that block height ever happened. Used to retract notes and nullifiers on a reorg.
+   *
+   * Must be called inside a transaction owned by the caller (it issues no `transactionAsync` of its own, because the
+   * reorg path wraps it together with other store operations, and IndexedDB has no nested transaction support).
+   *
+   * Throws if any job has uncommitted staged writes, since rolling back mid-job could later re-introduce notes or
+   * nullifier emissions anchored to deleted blocks.
+   */ async rollback(toBlock) {
+        if (this.#notesForJob.size > 0 || this.#nullifierEmissionsForJob.size > 0) {
+            throw new Error('PXE note store rollback is not allowed while jobs are running');
+        }
+        // Snapshot the orphaned (block, nullifier) pairs before mutating so we never delete from the cursor we are
+        // iterating. Scanning from `toBlock + 1` upward covers everything above the rollback target without needing to know
+        // the chain tip. Each nullifier's rows are independent (nullifiers are globally unique), so the deletes run
+        // concurrently. Keeping requests in flight also prevents the IndexedDB transaction from auto-committing mid-way.
+        const orphanedNotes = [];
+        for await (const [block, siloedNullifier] of this.#notesByBlockNumber.entriesAsync({
+            start: toBlock + 1
+        })){
+            orphanedNotes.push({
+                block,
+                siloedNullifier
+            });
+        }
+        let removedNotes = 0;
+        await Promise.all(orphanedNotes.map(async ({ block, siloedNullifier })=>{
+            const buf = await this.#notes.getAsync(siloedNullifier);
+            if (!buf) {
+                throw new Error(`Note not found for siloedNullifier ${siloedNullifier}`);
+            }
+            const stored = StoredNote.fromBuffer(buf);
+            await this.#notes.delete(siloedNullifier);
+            await this.#notesByContractAddress.deleteValue(stored.noteDao.contractAddress.toString(), siloedNullifier);
+            await this.#notesByBlockNumber.deleteValue(block, siloedNullifier);
+            removedNotes++;
+        }));
+        // Same procedure, with nullifier emissions
+        const orphanedEmissions = [];
+        for await (const [block, siloedNullifier] of this.#nullifierEmissionsByBlockNumber.entriesAsync({
+            start: toBlock + 1
+        })){
+            orphanedEmissions.push({
+                block,
+                siloedNullifier
+            });
+        }
+        await Promise.all(orphanedEmissions.map(async ({ block, siloedNullifier })=>{
+            await this.#nullifierEmissions.delete(siloedNullifier);
+            await this.#nullifierEmissionsByBlockNumber.deleteValue(block, siloedNullifier);
+        }));
+        this.logger.verbose('rolled back notes and nullifier emissions', {
+            removedNotes,
+            removedNullifierEmissions: orphanedEmissions.length,
+            toBlock
+        });
+    }
+}