@aztec-labs/pxe 6.0.0-nightly.20260829

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

@@ -0,0 +1,2 @@
+export { ContractStore } from './contract_store.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9zdG9yYWdlL2NvbnRyYWN0X3N0b3JlL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxhQUFhLEVBQUUsTUFBTSxxQkFBcUIsQ0FBQyJ9

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/storage/contract_store/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}

package/dest/storage/contract_store/index.js

@@ -0,0 +1 @@
+export { ContractStore } from './contract_store.js';

package/dest/storage/contract_store/private_functions_tree.d.ts

@@ -0,0 +1,27 @@
+import { FUNCTION_TREE_HEIGHT } from '@aztec-labs/constants';
+import { MembershipWitness } from '@aztec-labs/foundation/trees';
+import { type ContractArtifact, FunctionSelector } from '@aztec-labs/stdlib/abi';
+/**
+ * Represents a Merkle tree of functions for a particular Contract Class.
+ * It manages the construction of the function tree, computes its root, and generates membership witnesses
+ * for constrained functions. This class also enables lookup of specific function artifact using selectors.
+ * It is used in combination with the AztecNode to compute various data for executing private transactions.
+ */
+export declare class PrivateFunctionsTree {
+    private readonly privateFunctions;
+    private tree?;
+    private constructor();
+    static create(artifact: ContractArtifact): Promise<PrivateFunctionsTree>;
+    /**
+     * Retrieve the membership witness of a function within a contract's function tree.
+     * A membership witness represents the position and authentication path of a target function
+     * in the Merkle tree of constrained functions. It is required to prove the existence of the
+     * function within the contract during execution. Throws if fn does not exist or is not private.
+     *
+     * @param selector - The function selector.
+     * @returns A MembershipWitness instance representing the position and authentication path of the function in the function tree.
+     */
+    getFunctionMembershipWitness(selector: FunctionSelector): Promise<MembershipWitness<typeof FUNCTION_TREE_HEIGHT>>;
+    private getTree;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicHJpdmF0ZV9mdW5jdGlvbnNfdHJlZS5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL3N0b3JhZ2UvY29udHJhY3Rfc3RvcmUvcHJpdmF0ZV9mdW5jdGlvbnNfdHJlZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsb0JBQW9CLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQUk3RCxPQUFPLEVBQUUsaUJBQWlCLEVBQW1CLE1BQU0sOEJBQThCLENBQUM7QUFDbEYsT0FBTyxFQUFFLEtBQUssZ0JBQWdCLEVBQUUsZ0JBQWdCLEVBQWdCLE1BQU0sd0JBQXdCLENBQUM7QUFRL0Y7Ozs7O0dBS0c7QUFDSCxxQkFBYSxvQkFBb0I7SUFHWCxPQUFPLENBQUMsUUFBUSxDQUFDLGdCQUFnQjtJQUZyRCxPQUFPLENBQUMsSUFBSSxDQUFDLENBQWE7SUFFMUIsT0FBTyxlQUFxRTtJQUU1RSxPQUFhLE1BQU0sQ0FBQyxRQUFRLEVBQUUsZ0JBQWdCLGlDQU83QztJQUVEOzs7Ozs7OztPQVFHO0lBQ1UsNEJBQTRCLENBQ3ZDLFFBQVEsRUFBRSxnQkFBZ0IsR0FDekIsT0FBTyxDQUFDLGlCQUFpQixDQUFDLE9BQU8sb0JBQW9CLENBQUMsQ0FBQyxDQWV6RDtZQUVhLE9BQU87Q0FNdEIifQ==

package/dest/storage/contract_store/private_functions_tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"private_functions_tree.d.ts","sourceRoot":"","sources":["../../../src/storage/contract_store/private_functions_tree.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAI7D,OAAO,EAAE,iBAAiB,EAAmB,MAAM,8BAA8B,CAAC;AAClF,OAAO,EAAE,KAAK,gBAAgB,EAAE,gBAAgB,EAAgB,MAAM,wBAAwB,CAAC;AAQ/F;;;;;GAKG;AACH,qBAAa,oBAAoB;IAGX,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IAFrD,OAAO,CAAC,IAAI,CAAC,CAAa;IAE1B,OAAO,eAAqE;IAE5E,OAAa,MAAM,CAAC,QAAQ,EAAE,gBAAgB,iCAO7C;IAED;;;;;;;;OAQG;IACU,4BAA4B,CACvC,QAAQ,EAAE,gBAAgB,GACzB,OAAO,CAAC,iBAAiB,CAAC,OAAO,oBAAoB,CAAC,CAAC,CAezD;YAEa,OAAO;CAMtB"}

package/dest/storage/contract_store/private_functions_tree.js

@@ -0,0 +1,48 @@
+import { FUNCTION_TREE_HEIGHT } from '@aztec-labs/constants';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { allToCompletion } from '@aztec-labs/foundation/promise';
+import { assertLength } from '@aztec-labs/foundation/serialize';
+import { MembershipWitness } from '@aztec-labs/foundation/trees';
+import { FunctionType } from '@aztec-labs/stdlib/abi';
+import { computePrivateFunctionLeaf, computePrivateFunctionsTree, getContractClassPrivateFunctionFromArtifact } from '@aztec-labs/stdlib/contract';
+/**
+ * Represents a Merkle tree of functions for a particular Contract Class.
+ * It manages the construction of the function tree, computes its root, and generates membership witnesses
+ * for constrained functions. This class also enables lookup of specific function artifact using selectors.
+ * It is used in combination with the AztecNode to compute various data for executing private transactions.
+ */ export class PrivateFunctionsTree {
+    privateFunctions;
+    tree;
+    constructor(privateFunctions){
+        this.privateFunctions = privateFunctions;
+    }
+    static async create(artifact) {
+        const privateFunctions = await allToCompletion(artifact.functions.filter((fn)=>fn.functionType === FunctionType.PRIVATE).map(getContractClassPrivateFunctionFromArtifact));
+        return new PrivateFunctionsTree(privateFunctions);
+    }
+    /**
+   * Retrieve the membership witness of a function within a contract's function tree.
+   * A membership witness represents the position and authentication path of a target function
+   * in the Merkle tree of constrained functions. It is required to prove the existence of the
+   * function within the contract during execution. Throws if fn does not exist or is not private.
+   *
+   * @param selector - The function selector.
+   * @returns A MembershipWitness instance representing the position and authentication path of the function in the function tree.
+   */ async getFunctionMembershipWitness(selector) {
+        const fn = this.privateFunctions.find((f)=>f.selector.equals(selector));
+        if (!fn) {
+            throw new Error(`Private function with selector ${selector.toString()} not found in contract class.`);
+        }
+        const leaf = await computePrivateFunctionLeaf(fn);
+        const tree = await this.getTree();
+        const index = tree.getIndex(leaf);
+        const path = tree.getSiblingPath(index);
+        return new MembershipWitness(FUNCTION_TREE_HEIGHT, BigInt(index), assertLength(path.map(Fr.fromBuffer), FUNCTION_TREE_HEIGHT));
+    }
+    async getTree() {
+        if (!this.tree) {
+            this.tree = await computePrivateFunctionsTree(this.privateFunctions);
+        }
+        return this.tree;
+    }
+}

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

@@ -0,0 +1,23 @@
+import type { Fr } from '@aztec-labs/foundation/curves/bn254';
+import type { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import type { ChangeSetId } from '../staged_write_coordinator.js';
+import type { FactStore } from './fact_store.js';
+import type { FactCollectionKey, FactCollectionTypeKey, OriginBlock } from './fact_store_keys.js';
+import { type FactCollectionWithOriginState, type TipBlockNumbers } from './origin_state.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;
+    private readonly factStore;
+    private readonly allowedScopes;
+    constructor(factStore: FactStore, allowedScopes: AztecAddress[]);
+    recordFact(factCollectionKey: FactCollectionKey, factTypeId: Fr, payload: Fr[], originBlock: OriginBlock | undefined, changeSetId: ChangeSetId): Promise<void>;
+    deleteFactCollection(factCollectionKey: FactCollectionKey, changeSetId: ChangeSetId): Promise<void>;
+    getFactCollection(factCollectionKey: FactCollectionKey, tips: TipBlockNumbers, changeSetId: ChangeSetId): Promise<FactCollectionWithOriginState | undefined>;
+    getFactCollectionsByType(factCollectionTypeKey: FactCollectionTypeKey, tips: TipBlockNumbers, changeSetId: ChangeSetId): Promise<FactCollectionWithOriginState[]>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZmFjdF9zZXJ2aWNlLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvc3RvcmFnZS9mYWN0X3N0b3JlL2ZhY3Rfc2VydmljZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssRUFBRSxFQUFFLEVBQUUsTUFBTSxxQ0FBcUMsQ0FBQztBQUM5RCxPQUFPLEtBQUssRUFBRSxZQUFZLEVBQUUsTUFBTSxrQ0FBa0MsQ0FBQztBQUdyRSxPQUFPLEtBQUssRUFBRSxXQUFXLEVBQUUsTUFBTSxnQ0FBZ0MsQ0FBQztBQUNsRSxPQUFPLEtBQUssRUFBRSxTQUFTLEVBQUUsTUFBTSxpQkFBaUIsQ0FBQztBQUNqRCxPQUFPLEtBQUssRUFBRSxpQkFBaUIsRUFBRSxxQkFBcUIsRUFBRSxXQUFXLEVBQUUsTUFBTSxzQkFBc0IsQ0FBQztBQUNsRyxPQUFPLEVBQ0wsS0FBSyw2QkFBNkIsRUFFbEMsS0FBSyxlQUFlLEVBRXJCLE1BQU0sbUJBQW1CLENBQUM7QUFHM0I7Ozs7O0dBS0c7QUFDSCxxQkFBYSxXQUFXOztJQUVwQixPQUFPLENBQUMsUUFBUSxDQUFDLFNBQVM7SUFDMUIsT0FBTyxDQUFDLFFBQVEsQ0FBQyxhQUFhO0lBRmhDLFlBQ21CLFNBQVMsRUFBRSxTQUFTLEVBQ3BCLGFBQWEsRUFBRSxZQUFZLEVBQUUsRUFDNUM7SUFFSixVQUFVLENBQ1IsaUJBQWlCLEVBQUUsaUJBQWlCLEVBQ3BDLFVBQVUsRUFBRSxFQUFFLEVBQ2QsT0FBTyxFQUFFLEVBQUUsRUFBRSxFQUNiLFdBQVcsRUFBRSxXQUFXLEdBQUcsU0FBUyxFQUNwQyxXQUFXLEVBQUUsV0FBVyxHQUN2QixPQUFPLENBQUMsSUFBSSxDQUFDLENBR2Y7SUFFRCxvQkFBb0IsQ0FBQyxpQkFBaUIsRUFBRSxpQkFBaUIsRUFBRSxXQUFXLEVBQUUsV0FBVyxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FHbEc7SUFFSyxpQkFBaUIsQ0FDckIsaUJBQWlCLEVBQUUsaUJBQWlCLEVBQ3BDLElBQUksRUFBRSxlQUFlLEVBQ3JCLFdBQVcsRUFBRSxXQUFXLEdBQ3ZCLE9BQU8sQ0FBQyw2QkFBNkIsR0FBRyxTQUFTLENBQUMsQ0FPcEQ7SUFFSyx3QkFBd0IsQ0FDNUIscUJBQXFCLEVBQUUscUJBQXFCLEVBQzVDLElBQUksRUFBRSxlQUFlLEVBQ3JCLFdBQVcsRUFBRSxXQUFXLEdBQ3ZCLE9BQU8sQ0FBQyw2QkFBNkIsRUFBRSxDQUFDLENBSTFDO0NBS0YifQ==

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,qCAAqC,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAGrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAClG,OAAO,EACL,KAAK,6BAA6B,EAElC,KAAK,eAAe,EAErB,MAAM,mBAAmB,CAAC;AAG3B;;;;;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,WAAW,EAAE,WAAW,GACvB,OAAO,CAAC,IAAI,CAAC,CAGf;IAED,oBAAoB,CAAC,iBAAiB,EAAE,iBAAiB,EAAE,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAGlG;IAEK,iBAAiB,CACrB,iBAAiB,EAAE,iBAAiB,EACpC,IAAI,EAAE,eAAe,EACrB,WAAW,EAAE,WAAW,GACvB,OAAO,CAAC,6BAA6B,GAAG,SAAS,CAAC,CAOpD;IAEK,wBAAwB,CAC5B,qBAAqB,EAAE,qBAAqB,EAC5C,IAAI,EAAE,eAAe,EACrB,WAAW,EAAE,WAAW,GACvB,OAAO,CAAC,6BAA6B,EAAE,CAAC,CAI1C;CAKF"}

package/dest/storage/fact_store/fact_service.js

@@ -0,0 +1,45 @@
+import { assertAllowedScope } from '../allowed_scopes.js';
+import { toFactWithOriginState } from './origin_state.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, changeSetId) {
+        assertAllowedScope(factCollectionKey.scope, this.allowedScopes);
+        return this.factStore.recordFact(factCollectionKey, factTypeId, payload, originBlock, changeSetId);
+    }
+    deleteFactCollection(factCollectionKey, changeSetId) {
+        assertAllowedScope(factCollectionKey.scope, this.allowedScopes);
+        return this.factStore.deleteFactCollection(factCollectionKey, changeSetId);
+    }
+    async getFactCollection(factCollectionKey, tips, changeSetId) {
+        assertAllowedScope(factCollectionKey.scope, this.allowedScopes);
+        const collection = await this.factStore.getFactCollection(factCollectionKey, changeSetId);
+        if (!collection) {
+            return undefined;
+        }
+        return {
+            key: collection.key,
+            facts: this.#annotate(collection.facts, tips)
+        };
+    }
+    async getFactCollectionsByType(factCollectionTypeKey, tips, changeSetId) {
+        assertAllowedScope(factCollectionTypeKey.scope, this.allowedScopes);
+        const collections = await this.factStore.getFactCollectionsByType(factCollectionTypeKey, changeSetId);
+        return collections.map((collection)=>({
+                key: collection.key,
+                facts: this.#annotate(collection.facts, tips)
+            }));
+    }
+    #annotate(facts, tips) {
+        return facts.map((fact)=>toFactWithOriginState(fact, tips));
+    }
+}

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

@@ -0,0 +1,101 @@
+import type { Fr } from '@aztec-labs/foundation/curves/bn254';
+import type { AztecAsyncKVStore, AztecAsyncMap, AztecAsyncMultiMap } from '@aztec-labs/kv-store';
+import { BaseStagingStore } from '../base_staging_store.js';
+import type { ChangeSetId } from '../staged_write_coordinator.js';
+import { FactCollectionKey, type FactCollectionTypeKey, type OriginBlock } from './fact_store_keys.js';
+import { type Fact, StoredFact } from './stored_fact.js';
+type BlockNum = number;
+type FactBuffer = Buffer;
+type FactCollectionKeyStr = string;
+type FactKeyStr = string;
+/** A fact collection as returned by the store. */
+export type FactCollection = {
+    key: FactCollectionKey;
+    facts: Fact[];
+};
+/** A pending operation for a change set: record a fact, or delete a fact collection. */
+type StagedOp = {
+    kind: 'recordFact';
+    fact: StoredFact;
+} | {
+    kind: 'deleteFactCollection';
+    key: FactCollectionKey;
+};
+/**
+ * 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 change set ID and flushed atomically on commit.
+ */
+export declare class FactStore extends BaseStagingStore<FactStoreChangeSet, FactStoreDb> {
+    #private;
+    logger: import("@aztec-labs/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, changeSetId: ChangeSetId): 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, changeSetId: ChangeSetId): Promise<void>;
+    /**
+     * Returns the fact collection for the (scope-qualified) key, or undefined if it has no facts.
+     */
+    getFactCollection(factCollectionKey: FactCollectionKey, changeSetId: ChangeSetId): Promise<FactCollection | undefined>;
+    /**
+     * Returns every fact collection of the given type for the queried scope, each holding its facts.
+     */
+    getFactCollectionsByType(factCollectionTypeKey: FactCollectionTypeKey, changeSetId: ChangeSetId): Promise<FactCollection[]>;
+    protected flushChangeSet(changeSet: FactStoreChangeSet, db: FactStoreDb): Promise<void>;
+    /**
+     * Removes every retractable fact originating from blocks over height `toBlock`, across all scopes.
+     *
+     * Non-retractable facts are untouched.
+     */
+    protected applyRollback(toBlock: BlockNum, db: FactStoreDb): Promise<void>;
+}
+/** A change set's staged data: the ops it has accumulated, replayed over committed state on read and on flush. */
+type FactStoreChangeSet = StagedOp[];
+type FactStoreDb = {
+    /** Primary index of fact records. */
+    facts: AztecAsyncMap<FactKeyStr, FactBuffer>;
+    /** Index for per-collection fact enumeration and by-type collection discovery. */
+    factsByCollection: AztecAsyncMultiMap<FactCollectionKeyStr, FactKeyStr>;
+    /** Index for delete-on-prune of retractable facts (those with an origin block). */
+    factsByBlock: AztecAsyncMultiMap<BlockNum, FactKeyStr>;
+};
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZmFjdF9zdG9yZS5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL3N0b3JhZ2UvZmFjdF9zdG9yZS9mYWN0X3N0b3JlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxFQUFFLEVBQUUsRUFBRSxNQUFNLHFDQUFxQyxDQUFDO0FBRzlELE9BQU8sS0FBSyxFQUFFLGlCQUFpQixFQUFFLGFBQWEsRUFBRSxrQkFBa0IsRUFBRSxNQUFNLHNCQUFzQixDQUFDO0FBRWpHLE9BQU8sRUFBRSxnQkFBZ0IsRUFBbUIsTUFBTSwwQkFBMEIsQ0FBQztBQUM3RSxPQUFPLEtBQUssRUFBRSxXQUFXLEVBQUUsTUFBTSxnQ0FBZ0MsQ0FBQztBQUNsRSxPQUFPLEVBQUUsaUJBQWlCLEVBQUUsS0FBSyxxQkFBcUIsRUFBRSxLQUFLLFdBQVcsRUFBRSxNQUFNLHNCQUFzQixDQUFDO0FBQ3ZHLE9BQU8sRUFBRSxLQUFLLElBQUksRUFBRSxVQUFVLEVBQWdCLE1BQU0sa0JBQWtCLENBQUM7QUFFdkUsS0FBSyxRQUFRLEdBQUcsTUFBTSxDQUFDO0FBQ3ZCLEtBQUssVUFBVSxHQUFHLE1BQU0sQ0FBQztBQUV6QixLQUFLLG9CQUFvQixHQUFHLE1BQU0sQ0FBQztBQUNuQyxLQUFLLFVBQVUsR0FBRyxNQUFNLENBQUM7QUFFekIsa0RBQWtEO0FBQ2xELE1BQU0sTUFBTSxjQUFjLEdBQUc7SUFBRSxHQUFHLEVBQUUsaUJBQWlCLENBQUM7SUFBQyxLQUFLLEVBQUUsSUFBSSxFQUFFLENBQUE7Q0FBRSxDQUFDO0FBS3ZFLHdGQUF3RjtBQUN4RixLQUFLLFFBQVEsR0FBRztJQUFFLElBQUksRUFBRSxZQUFZLENBQUM7SUFBQyxJQUFJLEVBQUUsVUFBVSxDQUFBO0NBQUUsR0FBRztJQUFFLElBQUksRUFBRSxzQkFBc0IsQ0FBQztJQUFDLEdBQUcsRUFBRSxpQkFBaUIsQ0FBQTtDQUFFLENBQUM7QUFFcEg7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBMEJHO0FBQ0gscUJBQWEsU0FBVSxTQUFRLGdCQUFnQixDQUFDLGtCQUFrQixFQUFFLFdBQVcsQ0FBQzs7SUFDOUUsTUFBTSw4Q0FBOEI7SUFFcEMsWUFBWSxLQUFLLEVBQUUsaUJBQWlCLEVBV25DO0lBRUQ7Ozs7Ozs7Ozs7O09BV0c7SUFDSCxVQUFVLENBQ1IsaUJBQWlCLEVBQUUsaUJBQWlCLEVBQ3BDLFVBQVUsRUFBRSxFQUFFLEVBQ2QsT0FBTyxFQUFFLEVBQUUsRUFBRSxFQUNiLFdBQVcsRUFBRSxXQUFXLEdBQUcsU0FBUyxFQUNwQyxXQUFXLEVBQUUsV0FBVyxHQUN2QixPQUFPLENBQUMsSUFBSSxDQUFDLENBT2Y7SUFFRDs7OztPQUlHO0lBQ0gsb0JBQW9CLENBQUMsaUJBQWlCLEVBQUUsaUJBQWlCLEVBQUUsV0FBVyxFQUFFLFdBQVcsR0FBRyxPQUFPLENBQUMsSUFBSSxDQUFDLENBSWxHO0lBRUQ7O09BRUc7SUFDSCxpQkFBaUIsQ0FDZixpQkFBaUIsRUFBRSxpQkFBaUIsRUFDcEMsV0FBVyxFQUFFLFdBQVcsR0FDdkIsT0FBTyxDQUFDLGNBQWMsR0FBRyxTQUFTLENBQUMsQ0FhckM7SUFFRDs7T0FFRztJQUNILHdCQUF3QixDQUN0QixxQkFBcUIsRUFBRSxxQkFBcUIsRUFDNUMsV0FBVyxFQUFFLFdBQVcsR0FDdkIsT0FBTyxDQUFDLGNBQWMsRUFBRSxDQUFDLENBUzNCO0lBRUQsVUFBZ0IsY0FBYyxDQUFDLFNBQVMsRUFBRSxrQkFBa0IsRUFBRSxFQUFFLEVBQUUsV0FBVyxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FlNUY7SUFFRDs7OztPQUlHO0lBQ0gsVUFBZ0IsYUFBYSxDQUFDLE9BQU8sRUFBRSxRQUFRLEVBQUUsRUFBRSxFQUFFLFdBQVcsR0FBRyxPQUFPLENBQUMsSUFBSSxDQUFDLENBSS9FO0NBK09GO0FBRUQsa0hBQWtIO0FBQ2xILEtBQUssa0JBQWtCLEdBQUcsUUFBUSxFQUFFLENBQUM7QUFFckMsS0FBSyxXQUFXLEdBQUc7SUFDakIscUNBQXFDO0lBQ3JDLEtBQUssRUFBRSxhQUFhLENBQUMsVUFBVSxFQUFFLFVBQVUsQ0FBQyxDQUFDO0lBRTdDLGtGQUFrRjtJQUNsRixpQkFBaUIsRUFBRSxrQkFBa0IsQ0FBQyxvQkFBb0IsRUFBRSxVQUFVLENBQUMsQ0FBQztJQUV4RSxtRkFBbUY7SUFDbkYsWUFBWSxFQUFFLGtCQUFrQixDQUFDLFFBQVEsRUFBRSxVQUFVLENBQUMsQ0FBQztDQUN4RCxDQUFDIn0=

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,qCAAqC,CAAC;AAG9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAEjG,OAAO,EAAE,gBAAgB,EAAmB,MAAM,0BAA0B,CAAC;AAC7E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,KAAK,qBAAqB,EAAE,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACvG,OAAO,EAAE,KAAK,IAAI,EAAE,UAAU,EAAgB,MAAM,kBAAkB,CAAC;AAEvE,KAAK,QAAQ,GAAG,MAAM,CAAC;AACvB,KAAK,UAAU,GAAG,MAAM,CAAC;AAEzB,KAAK,oBAAoB,GAAG,MAAM,CAAC;AACnC,KAAK,UAAU,GAAG,MAAM,CAAC;AAEzB,kDAAkD;AAClD,MAAM,MAAM,cAAc,GAAG;IAAE,GAAG,EAAE,iBAAiB,CAAC;IAAC,KAAK,EAAE,IAAI,EAAE,CAAA;CAAE,CAAC;AAKvE,wFAAwF;AACxF,KAAK,QAAQ,GAAG;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,sBAAsB,CAAC;IAAC,GAAG,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAEpH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,SAAU,SAAQ,gBAAgB,CAAC,kBAAkB,EAAE,WAAW,CAAC;;IAC9E,MAAM,8CAA8B;IAEpC,YAAY,KAAK,EAAE,iBAAiB,EAWnC;IAED;;;;;;;;;;;OAWG;IACH,UAAU,CACR,iBAAiB,EAAE,iBAAiB,EACpC,UAAU,EAAE,EAAE,EACd,OAAO,EAAE,EAAE,EAAE,EACb,WAAW,EAAE,WAAW,GAAG,SAAS,EACpC,WAAW,EAAE,WAAW,GACvB,OAAO,CAAC,IAAI,CAAC,CAOf;IAED;;;;OAIG;IACH,oBAAoB,CAAC,iBAAiB,EAAE,iBAAiB,EAAE,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAIlG;IAED;;OAEG;IACH,iBAAiB,CACf,iBAAiB,EAAE,iBAAiB,EACpC,WAAW,EAAE,WAAW,GACvB,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAarC;IAED;;OAEG;IACH,wBAAwB,CACtB,qBAAqB,EAAE,qBAAqB,EAC5C,WAAW,EAAE,WAAW,GACvB,OAAO,CAAC,cAAc,EAAE,CAAC,CAS3B;IAED,UAAgB,cAAc,CAAC,SAAS,EAAE,kBAAkB,EAAE,EAAE,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAe5F;IAED;;;;OAIG;IACH,UAAgB,aAAa,CAAC,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAI/E;CA+OF;AAED,kHAAkH;AAClH,KAAK,kBAAkB,GAAG,QAAQ,EAAE,CAAC;AAErC,KAAK,WAAW,GAAG;IACjB,qCAAqC;IACrC,KAAK,EAAE,aAAa,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;IAE7C,kFAAkF;IAClF,iBAAiB,EAAE,kBAAkB,CAAC,oBAAoB,EAAE,UAAU,CAAC,CAAC;IAExE,mFAAmF;IACnF,YAAY,EAAE,kBAAkB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;CACxD,CAAC"}

package/dest/storage/fact_store/fact_store.js

@@ -0,0 +1,350 @@
+import { createLogger } from '@aztec-labs/foundation/log';
+import { allToCompletion } from '@aztec-labs/foundation/promise';
+import { BaseStagingStore } from '../base_staging_store.js';
+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 change set ID and flushed atomically on commit.
+ */ export class FactStore extends BaseStagingStore {
+    logger = createLogger('fact_store');
+    constructor(store){
+        super({
+            storeName: 'fact',
+            store,
+            buildChangeSet: ()=>[],
+            buildDb: (db)=>({
+                    facts: db.openMap('facts'),
+                    factsByCollection: db.openMultiMap('facts_by_collection'),
+                    factsByBlock: db.openMultiMap('facts_by_block')
+                })
+        });
+    }
+    /**
+   * 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, changeSetId) {
+        return this.withChangeSet(changeSetId, (changeSet)=>{
+            changeSet.push({
+                kind: 'recordFact',
+                fact: new StoredFact(factCollectionKey, factTypeId, payload, originBlock)
+            });
+        });
+    }
+    /**
+   * 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, changeSetId) {
+        return this.withChangeSet(changeSetId, (changeSet)=>{
+            changeSet.push({
+                kind: 'deleteFactCollection',
+                key: factCollectionKey
+            });
+        });
+    }
+    /**
+   * Returns the fact collection for the (scope-qualified) key, or undefined if it has no facts.
+   */ getFactCollection(factCollectionKey, changeSetId) {
+        return this.withChangeSetAndDb(changeSetId, async (changeSet, db)=>{
+            const collectionKey = factCollectionKey.toString();
+            const committedCollection = await this.#loadCommittedCollection(db, factCollectionKey);
+            const committed = new Map(committedCollection ? [
+                [
+                    collectionKey,
+                    committedCollection
+                ]
+            ] : []);
+            const collection = this.#foldStagedOps(committed, changeSet).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.
+   */ getFactCollectionsByType(factCollectionTypeKey, changeSetId) {
+        return this.withChangeSetAndDb(changeSetId, async (changeSet, db)=>{
+            const typeKey = factCollectionTypeKey.toString();
+            const committed = await this.#readCollectionsFromDbByType(db, typeKey);
+            return Array.from(this.#foldStagedOps(committed, changeSet, typeKey).values()).map((collection)=>({
+                    key: collection.key,
+                    facts: [
+                        ...collection.facts.values()
+                    ]
+                })).filter((collection)=>collection.facts.length > 0);
+        });
+    }
+    async flushChangeSet(changeSet, db) {
+        for (const op of changeSet){
+            switch(op.kind){
+                case 'recordFact':
+                    await this.#commitFact(db, op.fact);
+                    break;
+                case 'deleteFactCollection':
+                    await this.#deleteCollection(db, op.key.toString());
+                    break;
+                default:
+                    {
+                        const _exhaustive = op;
+                        throw new Error(`Unhandled FactStore staged op kind: ${JSON.stringify(_exhaustive)}`);
+                    }
+            }
+        }
+    }
+    /**
+   * Removes every retractable fact originating from blocks over height `toBlock`, across all scopes.
+   *
+   * Non-retractable facts are untouched.
+   */ async applyRollback(toBlock, db) {
+        const removedFacts = await this.#retractFacts(db, 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(db, 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 db.factsByBlock.entriesAsync({
+            start: toBlock + 1
+        })){
+            factReads.set(factKey, db.facts.getAsync(factKey));
+        }
+        await allToCompletion(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(db, factKey, StoredFact.fromBuffer(buf));
+        }));
+        return factReads.size;
+    }
+    async #readCollectionsFromDbByType(db, typeKey) {
+        const factReadsByCollection = new Map();
+        for await (const [collectionKey, factKey] of db.factsByCollection.entriesAsync({
+            start: `${typeKey}:`,
+            end: `${typeKey};`
+        })){
+            let reads = factReadsByCollection.get(collectionKey);
+            if (!reads) {
+                reads = new Map();
+                factReadsByCollection.set(collectionKey, reads);
+            }
+            reads.set(factKey, db.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(db, 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 db.factsByCollection.getValuesAsync(collectionKey.toString())){
+            factReads.set(factKey, db.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 allToCompletion([
+            ...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, changeSet, 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 changeSet){
+            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(db, fact) {
+        const factKey = factKeyStrOf(fact);
+        if (await db.facts.hasAsync(factKey)) {
+            this.logger.debug(`Ignoring already recorded fact`, {
+                factKey
+            });
+            return;
+        }
+        await db.facts.set(factKey, fact.toBuffer());
+        await db.factsByCollection.set(fact.factCollectionKey.toString(), factKey);
+        if (fact.originBlock !== undefined) {
+            await db.factsByBlock.set(fact.originBlock.blockNumber, factKey);
+        }
+    }
+    /**
+   * Deletes every fact under the (scope-qualified) collection key.
+   *
+   * Caller must wrap in a transaction.
+   */ async #deleteCollection(db, 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 db.factsByCollection.getValuesAsync(collectionKey)){
+            factReads.set(factKey, db.facts.getAsync(factKey));
+        }
+        await allToCompletion(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(db, 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(db, factKey, fact) {
+        await db.facts.delete(factKey);
+        await db.factsByCollection.deleteValue(fact.factCollectionKey.toString(), factKey);
+        if (fact.originBlock !== undefined) {
+            await db.factsByBlock.deleteValue(fact.originBlock.blockNumber, factKey);
+        }
+    }
+}