@aztec/pxe 5.0.0-rc.1 → 5.0.0-rc.2

package/dest/storage/capsule_store/capsule_service.js

@@ -1,4 +1,5 @@
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { assertAllowedScope } from '../allowed_scopes.js';
 /**
  * Wraps a CapsuleStore with scope-based access control. Each operation asserts that the requested scope is in the
  * allowed scopes list before delegating to the underlying store.
@@ -7,7 +8,11 @@ import { AztecAddress } from '@aztec/stdlib/aztec-address';
     allowedScopes;
     constructor(capsuleStore, allowedScopes){
         this.capsuleStore = capsuleStore;
-        this.allowedScopes = allowedScopes;
+        // The zero address denotes the global capsule scope, which is always permitted.
+        this.allowedScopes = [
+            ...allowedScopes,
+            AztecAddress.ZERO
+        ];
     }
     setCapsule(contractAddress, slot, capsule, jobId, scope) {
         assertAllowedScope(scope, this.allowedScopes);
@@ -40,11 +45,3 @@ import { AztecAddress } from '@aztec/stdlib/aztec-address';
         return this.capsuleStore.setCapsuleArray(contractAddress, baseSlot, content, jobId, scope);
     }
 }
-function assertAllowedScope(scope, allowedScopes) {
-    if (scope.equals(AztecAddress.ZERO)) {
-        return;
-    }
-    if (!allowedScopes.some((allowed)=>allowed.equals(scope))) {
-        throw new Error(`Scope ${scope.toString()} is not in the allowed scopes list: [${allowedScopes.map((s)=>s.toString()).join(', ')}]. See https://docs.aztec.network/errors/10`);
-    }
-}

package/dest/storage/contract_store/contract_store.js

@@ -135,7 +135,7 @@ const VERSION = 1;
     getContractsAddresses() {
         return this.#store.transactionAsync(async ()=>{
             const keys = await toArray(this.#contractInstances.keysAsync());
-            return keys.map(AztecAddress.fromString);
+            return keys.map(AztecAddress.fromStringUnsafe);
         });
     }
     /** Returns a contract instance for a given address. */ getContractInstance(contractAddress) {
@@ -271,7 +271,7 @@ const VERSION = 1;
     async getFunctionCall(functionName, args, to) {
         const contract = await this.getContract(to);
         if (!contract) {
-            throw new Error(`Unknown contract ${to}: add it to PXE by calling server.addContracts(...).\nSee docs for context: https://docs.aztec.network/developers/resources/debugging/aztecnr-errors#unknown-contract-0x0-add-it-to-pxe-by-calling-serveraddcontracts`);
+            throw new Error(`Unknown contract ${to}: register it by calling wallet.registerContract(...).\nSee docs for context: https://docs.aztec.network/errors/14`);
         }
         const functionDao = contract.functions.find((f)=>f.name === functionName);
         if (!functionDao) {

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

@@ -0,0 +1,20 @@
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { FactCollection, FactStore } from './fact_store.js';
+import type { FactCollectionKey, FactCollectionTypeKey, OriginBlock } from './fact_store_keys.js';
+/**
+ * Wraps a {@link FactStore} with scope-based access control.
+ *
+ * Each method asserts scope validity before delegating to FactStore, gating which accounts a contract may record facts
+ * under or read facts from.
+ */
+export declare class FactService {
+    private readonly factStore;
+    private readonly allowedScopes;
+    constructor(factStore: FactStore, allowedScopes: AztecAddress[]);
+    recordFact(factCollectionKey: FactCollectionKey, factTypeId: Fr, payload: Fr[], originBlock: OriginBlock | undefined, jobId: string): Promise<void>;
+    deleteFactCollection(factCollectionKey: FactCollectionKey, jobId: string): Promise<void>;
+    getFactCollection(factCollectionKey: FactCollectionKey, jobId: string): Promise<FactCollection | undefined>;
+    getFactCollectionsByType(factCollectionTypeKey: FactCollectionTypeKey, jobId: string): Promise<FactCollection[]>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZmFjdF9zZXJ2aWNlLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvc3RvcmFnZS9mYWN0X3N0b3JlL2ZhY3Rfc2VydmljZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssRUFBRSxFQUFFLEVBQUUsTUFBTSxnQ0FBZ0MsQ0FBQztBQUN6RCxPQUFPLEtBQUssRUFBRSxZQUFZLEVBQUUsTUFBTSw2QkFBNkIsQ0FBQztBQUdoRSxPQUFPLEtBQUssRUFBRSxjQUFjLEVBQUUsU0FBUyxFQUFFLE1BQU0saUJBQWlCLENBQUM7QUFDakUsT0FBTyxLQUFLLEVBQUUsaUJBQWlCLEVBQUUscUJBQXFCLEVBQUUsV0FBVyxFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFFbEc7Ozs7O0dBS0c7QUFDSCxxQkFBYSxXQUFXO0lBRXBCLE9BQU8sQ0FBQyxRQUFRLENBQUMsU0FBUztJQUMxQixPQUFPLENBQUMsUUFBUSxDQUFDLGFBQWE7SUFGaEMsWUFDbUIsU0FBUyxFQUFFLFNBQVMsRUFDcEIsYUFBYSxFQUFFLFlBQVksRUFBRSxFQUM1QztJQUVKLFVBQVUsQ0FDUixpQkFBaUIsRUFBRSxpQkFBaUIsRUFDcEMsVUFBVSxFQUFFLEVBQUUsRUFDZCxPQUFPLEVBQUUsRUFBRSxFQUFFLEVBQ2IsV0FBVyxFQUFFLFdBQVcsR0FBRyxTQUFTLEVBQ3BDLEtBQUssRUFBRSxNQUFNLEdBQ1osT0FBTyxDQUFDLElBQUksQ0FBQyxDQUdmO0lBRUQsb0JBQW9CLENBQUMsaUJBQWlCLEVBQUUsaUJBQWlCLEVBQUUsS0FBSyxFQUFFLE1BQU0sR0FBRyxPQUFPLENBQUMsSUFBSSxDQUFDLENBR3ZGO0lBRUQsaUJBQWlCLENBQUMsaUJBQWlCLEVBQUUsaUJBQWlCLEVBQUUsS0FBSyxFQUFFLE1BQU0sR0FBRyxPQUFPLENBQUMsY0FBYyxHQUFHLFNBQVMsQ0FBQyxDQUcxRztJQUVELHdCQUF3QixDQUFDLHFCQUFxQixFQUFFLHFCQUFxQixFQUFFLEtBQUssRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLGNBQWMsRUFBRSxDQUFDLENBRy9HO0NBQ0YifQ==

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

@@ -0,0 +1 @@
+{"version":3,"file":"fact_service.d.ts","sourceRoot":"","sources":["../../../src/storage/fact_store/fact_service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,gCAAgC,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAGhE,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAElG;;;;;GAKG;AACH,qBAAa,WAAW;IAEpB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAFhC,YACmB,SAAS,EAAE,SAAS,EACpB,aAAa,EAAE,YAAY,EAAE,EAC5C;IAEJ,UAAU,CACR,iBAAiB,EAAE,iBAAiB,EACpC,UAAU,EAAE,EAAE,EACd,OAAO,EAAE,EAAE,EAAE,EACb,WAAW,EAAE,WAAW,GAAG,SAAS,EACpC,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAGf;IAED,oBAAoB,CAAC,iBAAiB,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvF;IAED,iBAAiB,CAAC,iBAAiB,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAG1G;IAED,wBAAwB,CAAC,qBAAqB,EAAE,qBAAqB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAG/G;CACF"}

package/dest/storage/fact_store/fact_service.js

@@ -0,0 +1,30 @@
+import { assertAllowedScope } from '../allowed_scopes.js';
+/**
+ * Wraps a {@link FactStore} with scope-based access control.
+ *
+ * Each method asserts scope validity before delegating to FactStore, gating which accounts a contract may record facts
+ * under or read facts from.
+ */ export class FactService {
+    factStore;
+    allowedScopes;
+    constructor(factStore, allowedScopes){
+        this.factStore = factStore;
+        this.allowedScopes = allowedScopes;
+    }
+    recordFact(factCollectionKey, factTypeId, payload, originBlock, jobId) {
+        assertAllowedScope(factCollectionKey.scope, this.allowedScopes);
+        return this.factStore.recordFact(factCollectionKey, factTypeId, payload, originBlock, jobId);
+    }
+    deleteFactCollection(factCollectionKey, jobId) {
+        assertAllowedScope(factCollectionKey.scope, this.allowedScopes);
+        return this.factStore.deleteFactCollection(factCollectionKey, jobId);
+    }
+    getFactCollection(factCollectionKey, jobId) {
+        assertAllowedScope(factCollectionKey.scope, this.allowedScopes);
+        return this.factStore.getFactCollection(factCollectionKey, jobId);
+    }
+    getFactCollectionsByType(factCollectionTypeKey, jobId) {
+        assertAllowedScope(factCollectionTypeKey.scope, this.allowedScopes);
+        return this.factStore.getFactCollectionsByType(factCollectionTypeKey, jobId);
+    }
+}

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

@@ -0,0 +1,95 @@
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import type { AztecAsyncKVStore } from '@aztec/kv-store';
+import type { StagedStore } from '../../job_coordinator/job_coordinator.js';
+import { FactCollectionKey, type FactCollectionTypeKey, type OriginBlock } from './fact_store_keys.js';
+import { type Fact } from './stored_fact.js';
+type BlockNum = number;
+/** A fact collection as returned by the store. */
+export type FactCollection = {
+    key: FactCollectionKey;
+    facts: Fact[];
+};
+/**
+ * Stores immutable facts grouped into collections, isolated by contract and scope.
+ *
+ * A fact collection is a contract-defined bag of facts identified by a {@link FactCollectionKey} (contract, scope,
+ * collection type, and id). A fact is a contract-defined immutable, typed datum in a collection. Collections are
+ * implicit: one comes into being when its first fact is recorded and ceases to exist once it has no facts left.
+ *
+ * What makes this store different to, for example, the `CapsuleStore`, is that it is designed to support use cases
+ * where resilience to reorgs is needed, via what we call _retractability_.
+ *
+ * Facts can be retractable or non-retractable. They are retractable if they are associated to an origin block.
+ * Retractable facts are removed from the store when their origin block is pruned (typically due to a reorg).
+ * Non-retractable facts survive reorgs: they must then be explicitly deleted, so as not to keep consuming resources
+ * (storage and compute) indefinitely.
+ *
+ * Fact collections are isolated by scope.
+ *
+ * This store is designed to enable Aztec.nr to implement complex workflows such as offchain reception or partial note
+ * processing by storing structured data that is guaranteed to exist conditionally to specific blocks being included in
+ * the chain, while leaving the complexity of ensuring said guarantees to PXE.
+ *
+ * A key design driver is that PXE knows nothing about the actual fact contents: it just manages enough metadata to
+ * provide the guarantees mentioned above. That way, concepts such as offchain delivery or partial notes are completely
+ * defined by Aztec.nr, opening the door to further extension without the need for ad-hoc PXE support.
+ *
+ * As with most other PXE stores, writes are staged per-job and flushed atomically on commit.
+ */
+export declare class FactStore implements StagedStore {
+    #private;
+    readonly storeName: string;
+    logger: import("@aztec/foundation/log").Logger;
+    constructor(store: AztecAsyncKVStore);
+    /**
+     * Records a fact in a collection.
+     *
+     * The collection is created implicitly on the first fact recorded for its key: recording into an existing collection
+     * just adds to it.
+     *
+     * If `originBlock === undefined`, the fact is non-retractable: it survives reorgs. A defined origin block makes the
+     * fact retractable: on a prune below its block, it will be deleted.
+     *
+     * Idempotent: re-recording an identical fact (same collection, fact type, payload, and origin block) is a no-op.
+     * The same payload tied to a different origin block is a distinct fact.
+     */
+    recordFact(factCollectionKey: FactCollectionKey, factTypeId: Fr, payload: Fr[], originBlock: OriginBlock | undefined, jobId: string): Promise<void>;
+    /**
+     * Deletes a fact collection: removes every fact under the (scope-qualified) collection key.
+     *
+     * Idempotent: deleting a collection that does not exist is a no-op.
+     */
+    deleteFactCollection(factCollectionKey: FactCollectionKey, jobId: string): Promise<void>;
+    /**
+     * Returns the fact collection for the (scope-qualified) key, or undefined if it has no facts.
+     */
+    getFactCollection(factCollectionKey: FactCollectionKey, jobId: string): Promise<FactCollection | undefined>;
+    /**
+     * Returns every fact collection of the given type for the queried scope, each holding its facts.
+     */
+    getFactCollectionsByType(factCollectionTypeKey: FactCollectionTypeKey, jobId: string): Promise<FactCollection[]>;
+    /**
+     * Commits all staged operations for the given job to persistent storage.
+     *
+     * Must be called inside a transaction owned by the caller (JobCoordinator wraps all commits in a single
+     * transactionAsync, and IndexedDB does not support nested transactions).
+     *
+     * DO NOT call `#withJobLock` here: awaiting the lock creates a microtask boundary that causes IndexedDB to
+     * auto-commit the outer transaction.
+     */
+    commit(jobId: string): Promise<void>;
+    /** Discards all staged operations for the given job without persisting them. */
+    discardStaged(jobId: string): Promise<void>;
+    /**
+     * Removes every retractable fact originating from blocks over height `toBlock`, across all scopes.
+     *
+     * Non-retractable facts are untouched. Must run inside a caller-owned transaction (because it needs to share the
+     * transaction with other stores and IndexedDB has no nested transactions).
+     *
+     * Throws if any job is in flight (has accessed the store and not yet committed or discarded), since rolling back
+     * mid-job could re-introduce records originating from deleted blocks or change state underneath a job's view.
+     */
+    rollback(toBlock: BlockNum): Promise<void>;
+}
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZmFjdF9zdG9yZS5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL3N0b3JhZ2UvZmFjdF9zdG9yZS9mYWN0X3N0b3JlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxFQUFFLEVBQUUsRUFBRSxNQUFNLGdDQUFnQyxDQUFDO0FBR3pELE9BQU8sS0FBSyxFQUFFLGlCQUFpQixFQUFxQyxNQUFNLGlCQUFpQixDQUFDO0FBRTVGLE9BQU8sS0FBSyxFQUFFLFdBQVcsRUFBRSxNQUFNLDBDQUEwQyxDQUFDO0FBQzVFLE9BQU8sRUFBRSxpQkFBaUIsRUFBRSxLQUFLLHFCQUFxQixFQUFFLEtBQUssV0FBVyxFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFDdkcsT0FBTyxFQUFFLEtBQUssSUFBSSxFQUE0QixNQUFNLGtCQUFrQixDQUFDO0FBR3ZFLEtBQUssUUFBUSxHQUFHLE1BQU0sQ0FBQztBQU12QixrREFBa0Q7QUFDbEQsTUFBTSxNQUFNLGNBQWMsR0FBRztJQUFFLEdBQUcsRUFBRSxpQkFBaUIsQ0FBQztJQUFDLEtBQUssRUFBRSxJQUFJLEVBQUUsQ0FBQTtDQUFFLENBQUM7QUFRdkU7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBMEJHO0FBQ0gscUJBQWEsU0FBVSxZQUFXLFdBQVc7O0lBQzNDLFFBQVEsQ0FBQyxTQUFTLEVBQUUsTUFBTSxDQUFVO0lBbUJwQyxNQUFNLHlDQUE4QjtJQUVwQyxZQUFZLEtBQUssRUFBRSxpQkFBaUIsRUFPbkM7SUFFRDs7Ozs7Ozs7Ozs7T0FXRztJQUNILFVBQVUsQ0FDUixpQkFBaUIsRUFBRSxpQkFBaUIsRUFDcEMsVUFBVSxFQUFFLEVBQUUsRUFDZCxPQUFPLEVBQUUsRUFBRSxFQUFFLEVBQ2IsV0FBVyxFQUFFLFdBQVcsR0FBRyxTQUFTLEVBQ3BDLEtBQUssRUFBRSxNQUFNLEdBQ1osT0FBTyxDQUFDLElBQUksQ0FBQyxDQVFmO0lBRUQ7Ozs7T0FJRztJQUNILG9CQUFvQixDQUFDLGlCQUFpQixFQUFFLGlCQUFpQixFQUFFLEtBQUssRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQUt2RjtJQUVEOztPQUVHO0lBQ0csaUJBQWlCLENBQUMsaUJBQWlCLEVBQUUsaUJBQWlCLEVBQUUsS0FBSyxFQUFFLE1BQU0sR0FBRyxPQUFPLENBQUMsY0FBYyxHQUFHLFNBQVMsQ0FBQyxDQVVoSDtJQUVEOztPQUVHO0lBQ0csd0JBQXdCLENBQzVCLHFCQUFxQixFQUFFLHFCQUFxQixFQUM1QyxLQUFLLEVBQUUsTUFBTSxHQUNaLE9BQU8sQ0FBQyxjQUFjLEVBQUUsQ0FBQyxDQU8zQjtJQUVEOzs7Ozs7OztPQVFHO0lBQ0csTUFBTSxDQUFDLEtBQUssRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQWdCekM7SUFFRCxnRkFBZ0Y7SUFDaEYsYUFBYSxDQUFDLEtBQUssRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQUcxQztJQUVEOzs7Ozs7OztPQVFHO0lBQ0csUUFBUSxDQUFDLE9BQU8sRUFBRSxRQUFRLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQVEvQztDQTJSRiJ9

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

@@ -0,0 +1 @@
+{"version":3,"file":"fact_store.d.ts","sourceRoot":"","sources":["../../../src/storage/fact_store/fact_store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,gCAAgC,CAAC;AAGzD,OAAO,KAAK,EAAE,iBAAiB,EAAqC,MAAM,iBAAiB,CAAC;AAE5F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0CAA0C,CAAC;AAC5E,OAAO,EAAE,iBAAiB,EAAE,KAAK,qBAAqB,EAAE,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACvG,OAAO,EAAE,KAAK,IAAI,EAA4B,MAAM,kBAAkB,CAAC;AAGvE,KAAK,QAAQ,GAAG,MAAM,CAAC;AAMvB,kDAAkD;AAClD,MAAM,MAAM,cAAc,GAAG;IAAE,GAAG,EAAE,iBAAiB,CAAC;IAAC,KAAK,EAAE,IAAI,EAAE,CAAA;CAAE,CAAC;AAQvE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,SAAU,YAAW,WAAW;;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAU;IAmBpC,MAAM,yCAA8B;IAEpC,YAAY,KAAK,EAAE,iBAAiB,EAOnC;IAED;;;;;;;;;;;OAWG;IACH,UAAU,CACR,iBAAiB,EAAE,iBAAiB,EACpC,UAAU,EAAE,EAAE,EACd,OAAO,EAAE,EAAE,EAAE,EACb,WAAW,EAAE,WAAW,GAAG,SAAS,EACpC,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAQf;IAED;;;;OAIG;IACH,oBAAoB,CAAC,iBAAiB,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKvF;IAED;;OAEG;IACG,iBAAiB,CAAC,iBAAiB,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAUhH;IAED;;OAEG;IACG,wBAAwB,CAC5B,qBAAqB,EAAE,qBAAqB,EAC5C,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,cAAc,EAAE,CAAC,CAO3B;IAED;;;;;;;;OAQG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBzC;IAED,gFAAgF;IAChF,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG1C;IAED;;;;;;;;OAQG;IACG,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ/C;CA2RF"}

package/dest/storage/fact_store/fact_store.js

@@ -0,0 +1,408 @@
+import { createLogger } from '@aztec/foundation/log';
+import { Semaphore } from '@aztec/foundation/queue';
+import { FactCollectionKey } from './fact_store_keys.js';
+import { StoredFact, factKeyStrOf } from './stored_fact.js';
+/**
+ * Stores immutable facts grouped into collections, isolated by contract and scope.
+ *
+ * A fact collection is a contract-defined bag of facts identified by a {@link FactCollectionKey} (contract, scope,
+ * collection type, and id). A fact is a contract-defined immutable, typed datum in a collection. Collections are
+ * implicit: one comes into being when its first fact is recorded and ceases to exist once it has no facts left.
+ *
+ * What makes this store different to, for example, the `CapsuleStore`, is that it is designed to support use cases
+ * where resilience to reorgs is needed, via what we call _retractability_.
+ *
+ * Facts can be retractable or non-retractable. They are retractable if they are associated to an origin block.
+ * Retractable facts are removed from the store when their origin block is pruned (typically due to a reorg).
+ * Non-retractable facts survive reorgs: they must then be explicitly deleted, so as not to keep consuming resources
+ * (storage and compute) indefinitely.
+ *
+ * Fact collections are isolated by scope.
+ *
+ * This store is designed to enable Aztec.nr to implement complex workflows such as offchain reception or partial note
+ * processing by storing structured data that is guaranteed to exist conditionally to specific blocks being included in
+ * the chain, while leaving the complexity of ensuring said guarantees to PXE.
+ *
+ * A key design driver is that PXE knows nothing about the actual fact contents: it just manages enough metadata to
+ * provide the guarantees mentioned above. That way, concepts such as offchain delivery or partial notes are completely
+ * defined by Aztec.nr, opening the door to further extension without the need for ad-hoc PXE support.
+ *
+ * As with most other PXE stores, writes are staged per-job and flushed atomically on commit.
+ */ export class FactStore {
+    storeName = 'fact';
+    #store;
+    /** Primary index of fact records. */ #facts;
+    /** Index for per-collection fact enumeration and by-type collection discovery. */ #factsByCollection;
+    /** Index for delete-on-prune of retractable facts (those with an origin block). */ #factsByBlock;
+    /** Job uncommitted data */ #opsForJob;
+    /** Per-job locks */ #jobLocks;
+    logger = createLogger('fact_store');
+    constructor(store){
+        this.#store = store;
+        this.#facts = store.openMap('facts');
+        this.#factsByCollection = store.openMultiMap('facts_by_collection');
+        this.#factsByBlock = store.openMultiMap('facts_by_block');
+        this.#opsForJob = new Map();
+        this.#jobLocks = new Map();
+    }
+    /**
+   * Records a fact in a collection.
+   *
+   * The collection is created implicitly on the first fact recorded for its key: recording into an existing collection
+   * just adds to it.
+   *
+   * If `originBlock === undefined`, the fact is non-retractable: it survives reorgs. A defined origin block makes the
+   * fact retractable: on a prune below its block, it will be deleted.
+   *
+   * Idempotent: re-recording an identical fact (same collection, fact type, payload, and origin block) is a no-op.
+   * The same payload tied to a different origin block is a distinct fact.
+   */ recordFact(factCollectionKey, factTypeId, payload, originBlock, jobId) {
+        return this.#withJobLock(jobId, ()=>{
+            this.#stagedOpsFor(jobId).push({
+                kind: 'recordFact',
+                fact: new StoredFact(factCollectionKey, factTypeId, payload, originBlock)
+            });
+            return Promise.resolve();
+        });
+    }
+    /**
+   * Deletes a fact collection: removes every fact under the (scope-qualified) collection key.
+   *
+   * Idempotent: deleting a collection that does not exist is a no-op.
+   */ deleteFactCollection(factCollectionKey, jobId) {
+        return this.#withJobLock(jobId, ()=>{
+            this.#stagedOpsFor(jobId).push({
+                kind: 'deleteFactCollection',
+                key: factCollectionKey
+            });
+            return Promise.resolve();
+        });
+    }
+    /**
+   * Returns the fact collection for the (scope-qualified) key, or undefined if it has no facts.
+   */ async getFactCollection(factCollectionKey, jobId) {
+        const collectionKey = factCollectionKey.toString();
+        const committed = await this.#store.transactionAsync(()=>this.#readCollectionsFromDb([
+                factCollectionKey
+            ]));
+        const collection = this.#foldStagedOps(committed, jobId).get(collectionKey);
+        if (!collection) {
+            return undefined;
+        }
+        const facts = [
+            ...collection.facts.values()
+        ];
+        return facts.length > 0 ? {
+            key: factCollectionKey,
+            facts
+        } : undefined;
+    }
+    /**
+   * Returns every fact collection of the given type for the queried scope, each holding its facts.
+   */ async getFactCollectionsByType(factCollectionTypeKey, jobId) {
+        const typeKey = factCollectionTypeKey.toString();
+        const committed = await this.#readCollectionsFromDbByType(typeKey);
+        return Array.from(this.#foldStagedOps(committed, jobId, typeKey).values()).map((collection)=>({
+                key: collection.key,
+                facts: [
+                    ...collection.facts.values()
+                ]
+            })).filter((collection)=>collection.facts.length > 0);
+    }
+    /**
+   * Commits all staged operations for the given job to persistent storage.
+   *
+   * Must be called inside a transaction owned by the caller (JobCoordinator wraps all commits in a single
+   * transactionAsync, and IndexedDB does not support nested transactions).
+   *
+   * DO NOT call `#withJobLock` here: awaiting the lock creates a microtask boundary that causes IndexedDB to
+   * auto-commit the outer transaction.
+   */ async commit(jobId) {
+        for (const op of this.#stagedOpsFor(jobId)){
+            switch(op.kind){
+                case 'recordFact':
+                    await this.#commitFact(op.fact);
+                    break;
+                case 'deleteFactCollection':
+                    await this.#deleteCollection(op.key.toString());
+                    break;
+                default:
+                    {
+                        const _exhaustive = op;
+                        throw new Error(`Unhandled FactStore staged op kind: ${JSON.stringify(_exhaustive)}`);
+                    }
+            }
+        }
+        this.#clearJobData(jobId);
+    }
+    /** Discards all staged operations for the given job without persisting them. */ discardStaged(jobId) {
+        this.#clearJobData(jobId);
+        return Promise.resolve();
+    }
+    /**
+   * Removes every retractable fact originating from blocks over height `toBlock`, across all scopes.
+   *
+   * Non-retractable facts are untouched. Must run inside a caller-owned transaction (because it needs to share the
+   * transaction with other stores and IndexedDB has no nested transactions).
+   *
+   * Throws if any job is in flight (has accessed the store and not yet committed or discarded), since rolling back
+   * mid-job could re-introduce records originating from deleted blocks or change state underneath a job's view.
+   */ async rollback(toBlock) {
+        if (this.#opsForJob.size > 0) {
+            throw new Error('PXE fact store rollback is not allowed while jobs are running');
+        }
+        const removedFacts = await this.#retractFacts(toBlock);
+        this.logger.verbose('rolled back fact store', {
+            removedFacts,
+            toBlock
+        });
+    }
+    /**
+   * Deletes retractable facts originating above `toBlock`, returning the number of by-block entries scanned.
+   * Retraction is scope-agnostic: a reorg invalidates a fact regardless of which scope's collection it belongs to.
+   *
+   * Requires to be run in a transactionAsync context.
+   */ async #retractFacts(toBlock) {
+        // Snapshot the orphaned fact keys before mutating so we never delete from the cursor we are iterating, kicking off
+        // each fact-body read during the scan so a DB request stays pending across the cursor-to-delete boundary (a drained
+        // cursor with no read in flight would let the transaction auto-commit before the deletes).
+        const factReads = new Map();
+        for await (const [, factKey] of this.#factsByBlock.entriesAsync({
+            start: toBlock + 1
+        })){
+            factReads.set(factKey, this.#facts.getAsync(factKey));
+        }
+        await Promise.all(Array.from(factReads, async ([factKey, read])=>{
+            const buf = await read;
+            if (!buf) {
+                // The by-block index just yielded this factKey, so a missing primary record means the indexes are out of
+                // sync. Log as this should be unreachable unless there is a bug.
+                this.logger.warn('Skipping retraction of a fact missing from the primary store: by-block index is stale', {
+                    factKey
+                });
+                return;
+            }
+            await this.#deleteFact(factKey, StoredFact.fromBuffer(buf));
+        }));
+        return factReads.size;
+    }
+    /**
+   * Reads the given collections (their facts) by key into a Map keyed by collection key, skipping
+   * keys with no committed facts.
+   *
+   * Reads are not wrapped in a transaction: the caller owns the transaction boundary.
+   */ async #readCollectionsFromDb(keys) {
+        const result = new Map();
+        for (const key of keys){
+            const collection = await this.#loadCommittedCollection(key);
+            if (collection) {
+                result.set(key.toString(), collection);
+            }
+        }
+        return result;
+    }
+    #readCollectionsFromDbByType(typeKey) {
+        return this.#store.transactionAsync(async ()=>{
+            const factReadsByCollection = new Map();
+            for await (const [collectionKey, factKey] of this.#factsByCollection.entriesAsync({
+                start: `${typeKey}:`,
+                end: `${typeKey};`
+            })){
+                let reads = factReadsByCollection.get(collectionKey);
+                if (!reads) {
+                    reads = new Map();
+                    factReadsByCollection.set(collectionKey, reads);
+                }
+                reads.set(factKey, this.#facts.getAsync(factKey));
+            }
+            const result = new Map();
+            for (const [collectionKey, reads] of factReadsByCollection){
+                const collection = await this.#assembleCollection(FactCollectionKey.fromString(collectionKey), reads);
+                result.set(collectionKey, collection);
+            }
+            return result;
+        });
+    }
+    async #loadCommittedCollection(collectionKey) {
+        // Kick off each fact read while iterating the index so a DB request is always pending. Draining the cursor and only
+        // then reading the facts one `await` at a time would let the IndexedDB transaction auto-commit at the boundary
+        // (IndexedDB auto-commits once control returns to the event loop with no pending request), throwing mid-read on the
+        // browser backend.
+        const factReads = new Map();
+        for await (const factKey of this.#factsByCollection.getValuesAsync(collectionKey.toString())){
+            factReads.set(factKey, this.#facts.getAsync(factKey));
+        }
+        if (factReads.size === 0) {
+            return undefined;
+        }
+        return this.#assembleCollection(collectionKey, factReads);
+    }
+    /**
+   * Assemble a collection's facts from a set of in-flight DB reads.
+   */ async #assembleCollection(collectionKey, reads) {
+        const factKeys = [
+            ...reads.keys()
+        ];
+        const bufs = await Promise.all(reads.values());
+        // Await-free tail: deserialize. No DB ops from here on.
+        const facts = new Map();
+        for(let i = 0; i < factKeys.length; i++){
+            const factKey = factKeys[i];
+            const buf = bufs[i];
+            if (!buf) {
+                // Defensive: a #factsByCollection entry must always reference a live #facts entry. A missing one means the
+                // indexes are corrupt.
+                throw new Error(`Fact not found for factKey ${factKey}`);
+            }
+            const stored = StoredFact.fromBuffer(buf);
+            if (stored.factCollectionKey.toString() !== collectionKey.toString()) {
+                // Defensive: every read fact must belong to the collection being assembled. A mismatch means the indexes are
+                // corrupt.
+                throw new Error(`Fact ${factKey} does not belong to collection ${collectionKey}`);
+            }
+            facts.set(factKey, stored.toFact());
+        }
+        return {
+            key: collectionKey,
+            facts
+        };
+    }
+    /**
+   * Assembles the current view of a collection of collections together with their facts, combining the committed with
+   * staged data.
+   *
+   * When `typeKey` is given, staged records of other types are ignored, so the result holds only that type.
+   */ #foldStagedOps(committed, jobId, typeKey) {
+        const result = new Map();
+        // Copy to avoid mutating the contents of `committed`.
+        for (const [collectionKey, { key, facts }] of committed){
+            result.set(collectionKey, {
+                key,
+                facts: new Map(facts)
+            });
+        }
+        for (const op of this.#stagedOpsFor(jobId)){
+            switch(op.kind){
+                case 'recordFact':
+                    this.#foldRecordFact(result, op, typeKey);
+                    break;
+                case 'deleteFactCollection':
+                    this.#foldDeleteFactCollection(result, op);
+                    break;
+                default:
+                    {
+                        const _exhaustive = op;
+                        throw new Error(`Unhandled FactStore staged op kind: ${JSON.stringify(_exhaustive)}`);
+                    }
+            }
+        }
+        return result;
+    }
+    /**
+   * Folds a staged `recordFact` op into view.
+   *
+   * When `typeKey` is given, an op of another type is ignored, keeping the view limited to that type.
+   */ #foldRecordFact(result, op, typeKey) {
+        const key = op.fact.factCollectionKey;
+        // Type filter doesn't match, nothing to do with this fact
+        if (typeKey !== undefined && key.factCollectionTypeKey().toString() !== typeKey) {
+            return;
+        }
+        const collectionKey = key.toString();
+        let collection = result.get(collectionKey);
+        // Collection didn't exist before this point, the created fact brings it into existence
+        if (!collection) {
+            collection = {
+                key,
+                facts: new Map()
+            };
+            result.set(collectionKey, collection);
+        }
+        const fKey = factKeyStrOf(op.fact);
+        if (!collection.facts.has(fKey)) {
+            collection.facts.set(fKey, op.fact.toFact());
+        }
+    }
+    /**
+   * Folds a staged `deleteFactCollection` op into the view: the scope-qualified collection is removed outright.
+   */ #foldDeleteFactCollection(result, op) {
+        result.delete(op.key.toString());
+    }
+    /**
+   * Writes a fact to persistent storage. Idempotent: an identical fact (same scope-qualified key) is left untouched.
+   */ async #commitFact(fact) {
+        const factKey = factKeyStrOf(fact);
+        if (await this.#facts.hasAsync(factKey)) {
+            this.logger.debug(`Ignoring already recorded fact`, {
+                factKey
+            });
+            return;
+        }
+        await this.#facts.set(factKey, fact.toBuffer());
+        await this.#factsByCollection.set(fact.factCollectionKey.toString(), factKey);
+        if (fact.originBlock !== undefined) {
+            await this.#factsByBlock.set(fact.originBlock.blockNumber, factKey);
+        }
+    }
+    /**
+   * Deletes every fact under the (scope-qualified) collection key.
+   *
+   * Caller must wrap in a transaction.
+   */ async #deleteCollection(collectionKey) {
+        // Snapshot the fact index before mutating so we never delete from the cursor we are iterating, kicking off each
+        // fact-body read during the scan so a DB request stays pending across the cursor-to-mutation boundary (a drained
+        // cursor with no read in flight would let the transaction auto-commit before the deletes).
+        const factReads = new Map();
+        for await (const factKey of this.#factsByCollection.getValuesAsync(collectionKey)){
+            factReads.set(factKey, this.#facts.getAsync(factKey));
+        }
+        await Promise.all(Array.from(factReads, async ([factKey, read])=>{
+            const buf = await read;
+            if (!buf) {
+                // A #factsByCollection entry must always reference a live #facts entry, a missing one means the indexes are
+                // corrupt.
+                throw new Error(`Fact not found for factKey ${factKey}`);
+            }
+            await this.#deleteFact(factKey, StoredFact.fromBuffer(buf));
+        }));
+    }
+    /**
+   * Deletes a fact from the primary store and all its indexes (`#factsByCollection`, plus `#factsByBlock` if
+   * retractable).
+   *
+   * Caller must wrap in a transaction.
+   */ async #deleteFact(factKey, fact) {
+        await this.#facts.delete(factKey);
+        await this.#factsByCollection.deleteValue(fact.factCollectionKey.toString(), factKey);
+        if (fact.originBlock !== undefined) {
+            await this.#factsByBlock.deleteValue(fact.originBlock.blockNumber, factKey);
+        }
+    }
+    /**
+   * Returns the job's staged-ops array, creating it on first access.
+   * */ #stagedOpsFor(jobId) {
+        let ops = this.#opsForJob.get(jobId);
+        if (ops === undefined) {
+            ops = [];
+            this.#opsForJob.set(jobId, ops);
+        }
+        return ops;
+    }
+    #clearJobData(jobId) {
+        this.#opsForJob.delete(jobId);
+        this.#jobLocks.delete(jobId);
+    }
+    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();
+        }
+    }
+}

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

@@ -0,0 +1,34 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+import type { FieldsOf } from '@aztec/foundation/types';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+/**
+ * The block a retractable fact originates from.
+ */
+export type OriginBlock = {
+    blockNumber: number;
+    blockHash: Fr;
+};
+/** Identifies all fact collections of one type within a contract, for one scope. */
+export declare class FactCollectionTypeKey {
+    readonly contractAddress: AztecAddress;
+    readonly scope: AztecAddress;
+    readonly factCollectionTypeId: Fr;
+    constructor(contractAddress: AztecAddress, scope: AztecAddress, factCollectionTypeId: Fr);
+    static from(fields: FieldsOf<FactCollectionTypeKey>): FactCollectionTypeKey;
+    toString(): string;
+}
+/** Uniquely identifies a single fact collection, isolated by scope; all its facts share this key. */
+export declare class FactCollectionKey {
+    readonly contractAddress: AztecAddress;
+    readonly scope: AztecAddress;
+    readonly factCollectionTypeId: Fr;
+    readonly factCollectionId: Fr;
+    constructor(contractAddress: AztecAddress, scope: AztecAddress, factCollectionTypeId: Fr, factCollectionId: Fr);
+    static from(fields: FieldsOf<FactCollectionKey>): FactCollectionKey;
+    /** Inverse of toString */
+    static fromString(str: string): FactCollectionKey;
+    /** The key grouping this collection with the other collections of its type within the same contract and scope. */
+    factCollectionTypeKey(): FactCollectionTypeKey;
+    toString(): string;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZmFjdF9zdG9yZV9rZXlzLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvc3RvcmFnZS9mYWN0X3N0b3JlL2ZhY3Rfc3RvcmVfa2V5cy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsRUFBRSxFQUFFLE1BQU0sZ0NBQWdDLENBQUM7QUFDcEQsT0FBTyxLQUFLLEVBQUUsUUFBUSxFQUFFLE1BQU0seUJBQXlCLENBQUM7QUFDeEQsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLDZCQUE2QixDQUFDO0FBRTNEOztHQUVHO0FBQ0gsTUFBTSxNQUFNLFdBQVcsR0FBRztJQUFFLFdBQVcsRUFBRSxNQUFNLENBQUM7SUFBQyxTQUFTLEVBQUUsRUFBRSxDQUFBO0NBQUUsQ0FBQztBQVNqRSxvRkFBb0Y7QUFDcEYscUJBQWEscUJBQXFCO2FBRWQsZUFBZSxFQUFFLFlBQVk7YUFDN0IsS0FBSyxFQUFFLFlBQVk7YUFDbkIsb0JBQW9CLEVBQUUsRUFBRTtJQUgxQyxZQUNrQixlQUFlLEVBQUUsWUFBWSxFQUM3QixLQUFLLEVBQUUsWUFBWSxFQUNuQixvQkFBb0IsRUFBRSxFQUFFLEVBR3pDO0lBRUQsTUFBTSxDQUFDLElBQUksQ0FBQyxNQUFNLEVBQUUsUUFBUSxDQUFDLHFCQUFxQixDQUFDLEdBQUcscUJBQXFCLENBRTFFO0lBRUQsUUFBUSxJQUFJLE1BQU0sQ0FFakI7Q0FDRjtBQUVELHFHQUFxRztBQUNyRyxxQkFBYSxpQkFBaUI7YUFFVixlQUFlLEVBQUUsWUFBWTthQUM3QixLQUFLLEVBQUUsWUFBWTthQUNuQixvQkFBb0IsRUFBRSxFQUFFO2FBQ3hCLGdCQUFnQixFQUFFLEVBQUU7SUFKdEMsWUFDa0IsZUFBZSxFQUFFLFlBQVksRUFDN0IsS0FBSyxFQUFFLFlBQVksRUFDbkIsb0JBQW9CLEVBQUUsRUFBRSxFQUN4QixnQkFBZ0IsRUFBRSxFQUFFLEVBR3JDO0lBRUQsTUFBTSxDQUFDLElBQUksQ0FBQyxNQUFNLEVBQUUsUUFBUSxDQUFDLGlCQUFpQixDQUFDLEdBQUcsaUJBQWlCLENBT2xFO0lBRUQsMEJBQTBCO0lBQzFCLE1BQU0sQ0FBQyxVQUFVLENBQUMsR0FBRyxFQUFFLE1BQU0sR0FBRyxpQkFBaUIsQ0FRaEQ7SUFFRCxrSEFBa0g7SUFDbEgscUJBQXFCLElBQUkscUJBQXFCLENBRTdDO0lBRUQsUUFBUSxJQUFJLE1BQU0sQ0FFakI7Q0FDRiJ9

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

@@ -0,0 +1 @@
+{"version":3,"file":"fact_store_keys.d.ts","sourceRoot":"","sources":["../../../src/storage/fact_store/fact_store_keys.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,gCAAgC,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE3D;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,EAAE,CAAA;CAAE,CAAC;AASjE,oFAAoF;AACpF,qBAAa,qBAAqB;aAEd,eAAe,EAAE,YAAY;aAC7B,KAAK,EAAE,YAAY;aACnB,oBAAoB,EAAE,EAAE;IAH1C,YACkB,eAAe,EAAE,YAAY,EAC7B,KAAK,EAAE,YAAY,EACnB,oBAAoB,EAAE,EAAE,EAGzC;IAED,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,qBAAqB,CAAC,GAAG,qBAAqB,CAE1E;IAED,QAAQ,IAAI,MAAM,CAEjB;CACF;AAED,qGAAqG;AACrG,qBAAa,iBAAiB;aAEV,eAAe,EAAE,YAAY;aAC7B,KAAK,EAAE,YAAY;aACnB,oBAAoB,EAAE,EAAE;aACxB,gBAAgB,EAAE,EAAE;IAJtC,YACkB,eAAe,EAAE,YAAY,EAC7B,KAAK,EAAE,YAAY,EACnB,oBAAoB,EAAE,EAAE,EACxB,gBAAgB,EAAE,EAAE,EAGrC;IAED,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,iBAAiB,CAAC,GAAG,iBAAiB,CAOlE;IAED,0BAA0B;IAC1B,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAQhD;IAED,kHAAkH;IAClH,qBAAqB,IAAI,qBAAqB,CAE7C;IAED,QAAQ,IAAI,MAAM,CAEjB;CACF"}