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

package/dest/storage/contract_store/contract_store.js

@@ -0,0 +1,281 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { toArray } from '@aztec/foundation/iterable';
+import { BufferReader, numToUInt8, serializeToBuffer } from '@aztec/foundation/serialize';
+import { FunctionCall, FunctionSelector, FunctionType, contractArtifactFromBuffer, contractArtifactToBuffer, encodeArguments, findFunctionAbiBySelector, findFunctionArtifactBySelector, getFunctionDebugMetadata } from '@aztec/stdlib/abi';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { SerializableContractInstancePreimage, getContractClassFromArtifact } from '@aztec/stdlib/contract';
+import { PrivateFunctionsTree } from './private_functions_tree.js';
+const VERSION = 1;
+/**
+ * All contract class data except the large packedBytecode.
+ * The expensive data from the ContractClass is precomputed and stored in this format to avoid redundant hashing.
+ * Since we have to store the artifacts anyway, the final ContractClass is reconstructed by combining this data
+ * with the packedBytecode obtained from the former. That way we can have quick class lookups without wasted storage.
+ */ export class SerializableContractClassData {
+    version = VERSION;
+    id;
+    artifactHash;
+    privateFunctionsRoot;
+    publicBytecodeCommitment;
+    privateFunctions;
+    constructor(data){
+        this.id = data.id;
+        this.artifactHash = data.artifactHash;
+        this.privateFunctionsRoot = data.privateFunctionsRoot;
+        this.publicBytecodeCommitment = data.publicBytecodeCommitment;
+        this.privateFunctions = data.privateFunctions;
+    }
+    toBuffer() {
+        return serializeToBuffer(numToUInt8(this.version), this.id, this.artifactHash, this.privateFunctionsRoot, this.publicBytecodeCommitment, this.privateFunctions.length, ...this.privateFunctions.map((fn)=>serializeToBuffer(fn.selector, fn.vkHash)));
+    }
+    static fromBuffer(bufferOrReader) {
+        const reader = BufferReader.asReader(bufferOrReader);
+        const version = reader.readUInt8();
+        if (version !== VERSION) {
+            throw new Error(`Unexpected contract class data version ${version}`);
+        }
+        return new SerializableContractClassData({
+            id: reader.readObject(Fr),
+            artifactHash: reader.readObject(Fr),
+            privateFunctionsRoot: reader.readObject(Fr),
+            publicBytecodeCommitment: reader.readObject(Fr),
+            privateFunctions: reader.readVector({
+                fromBuffer: (r)=>({
+                        selector: r.readObject(FunctionSelector),
+                        vkHash: r.readObject(Fr)
+                    })
+            })
+        });
+    }
+}
+/**
+ * ContractStore serves as a data manager and retriever for Aztec.nr contracts.
+ * It provides methods to obtain contract addresses, function ABI, bytecode, and membership witnesses
+ * from a given contract address and function selector. The class maintains a cache of ContractTree instances
+ * to efficiently serve the requested data. It interacts with the ContractDatabase and AztecNode to fetch
+ * the required information and facilitate cryptographic proof generation.
+ */ export class ContractStore {
+    /** Map from contract class id to private function tree. */ // TODO: Update it to be LRU cache so that it doesn't keep all the data all the time.
+    #privateFunctionTrees = new Map();
+    /**
+   * In-memory cache of deserialized ContractArtifact objects, keyed by class id string.
+   * Avoids repeated LMDB reads + JSON.parse + Zod validation on every oracle call.
+   * Artifacts are large but immutable after registration — safe to cache for the lifetime of the store.
+   */ // TODO: Update it to be LRU cache so that it doesn't keep all the data all the time.
+    #contractArtifactCache = new Map();
+    #store;
+    #contractArtifacts;
+    #contractClassData;
+    #contractInstances;
+    constructor(store){
+        this.#store = store;
+        this.#contractArtifacts = store.openMap('contract_artifacts');
+        this.#contractClassData = store.openMap('contract_classes');
+        this.#contractInstances = store.openMap('contracts_instances');
+    }
+    // Setters
+    /**
+   * Registers a new contract artifact and its corresponding class data.
+   *
+   * IMPORTANT: This method does not verify that the provided artifact matches the class data or that the class id
+   * matches the artifact. It is the caller's responsibility to ensure the consistency and correctness of the provided
+   * data. This is done to avoid redundant, expensive contract class computations.
+   */ async addContractArtifact(contract, contractClassWithIdAndPreimage) {
+        const contractClass = contractClassWithIdAndPreimage ?? await getContractClassFromArtifact(contract);
+        const key = contractClass.id.toString();
+        if (this.#contractArtifactCache.has(key)) {
+            return contractClass.id;
+        }
+        const privateFunctions = contract.functions.filter((functionArtifact)=>functionArtifact.functionType === FunctionType.PRIVATE);
+        const privateSelectors = await Promise.all(privateFunctions.map(async (fn)=>(await FunctionSelector.fromNameAndParameters(fn.name, fn.parameters)).toString()));
+        if (privateSelectors.length !== new Set(privateSelectors).size) {
+            throw new Error('Repeated function selectors of private functions');
+        }
+        this.#contractArtifactCache.set(key, contract);
+        await this.#store.transactionAsync(async ()=>{
+            await this.#contractArtifacts.set(key, contractArtifactToBuffer(contract));
+            await this.#contractClassData.set(key, new SerializableContractClassData(contractClass).toBuffer());
+        });
+        return contractClass.id;
+    }
+    async addContractInstance(contract) {
+        await this.#store.transactionAsync(async ()=>{
+            await this.#contractInstances.set(contract.address.toString(), new SerializableContractInstancePreimage(contract).toBuffer());
+        });
+    }
+    // Private getters
+    async #getPrivateFunctionTreeForClassId(classId) {
+        if (!this.#privateFunctionTrees.has(classId.toString())) {
+            const artifact = await this.getContractArtifact(classId);
+            if (!artifact) {
+                return;
+            }
+            const tree = await PrivateFunctionsTree.create(artifact);
+            this.#privateFunctionTrees.set(classId.toString(), tree);
+        }
+        return this.#privateFunctionTrees.get(classId.toString());
+    }
+    // Public getters
+    getContractsAddresses() {
+        return this.#store.transactionAsync(async ()=>{
+            const keys = await toArray(this.#contractInstances.keysAsync());
+            return keys.map(AztecAddress.fromStringUnsafe);
+        });
+    }
+    /** Returns the address preimage of a given address. */ getContractInstance(contractAddress) {
+        return this.#store.transactionAsync(async ()=>{
+            const contract = await this.#contractInstances.getAsync(contractAddress.toString());
+            return contract && SerializableContractInstancePreimage.fromBuffer(contract).withAddress(contractAddress);
+        });
+    }
+    /** Returns the raw contract artifact for a given class id. */ async getContractArtifact(contractClassId) {
+        const key = contractClassId.toString();
+        const cached = this.#contractArtifactCache.get(key);
+        if (cached) {
+            return cached;
+        }
+        const artifact = await this.#store.transactionAsync(async ()=>{
+            const buf = await this.#contractArtifacts.getAsync(key);
+            return buf && contractArtifactFromBuffer(buf);
+        });
+        if (artifact) {
+            this.#contractArtifactCache.set(key, artifact);
+        }
+        return artifact;
+    }
+    /** Returns a contract class for a given class id. */ async getContractClassWithPreimage(contractClassId) {
+        const key = contractClassId.toString();
+        const buf = await this.#store.transactionAsync(()=>this.#contractClassData.getAsync(key));
+        if (!buf) {
+            return undefined;
+        }
+        const classData = SerializableContractClassData.fromBuffer(buf);
+        const artifact = await this.getContractArtifact(contractClassId);
+        if (!artifact) {
+            return undefined;
+        }
+        const packedBytecode = artifact.functions.find((f)=>f.name === 'public_dispatch')?.bytecode ?? Buffer.alloc(0);
+        return {
+            ...classData,
+            packedBytecode
+        };
+    }
+    /**
+   * Retrieves the artifact of a specified function within a given contract class.
+   *
+   * @param contractClassId - The id of the contract class containing the function.
+   * @param selector - The function selector.
+   * @returns The corresponding function's artifact as an object, or `undefined` if the class is not registered.
+   */ async getFunctionArtifact(contractClassId, selector) {
+        const artifact = await this.getContractArtifact(contractClassId);
+        if (!artifact) {
+            return undefined;
+        }
+        const fn = assertSelectorInArtifact(artifact, await findFunctionArtifactBySelector(artifact, selector), {
+            contractClassId,
+            selector
+        });
+        return {
+            ...fn,
+            contractName: artifact.name
+        };
+    }
+    /**
+   * Same as {@link getFunctionArtifact} but with debug metadata attached. Returns `undefined` when the class artifact
+   * is not registered.
+   */ async getFunctionArtifactWithDebugMetadata(contractClassId, selector) {
+        const artifact = await this.getContractArtifact(contractClassId);
+        if (!artifact) {
+            return undefined;
+        }
+        const fn = assertSelectorInArtifact(artifact, await findFunctionArtifactBySelector(artifact, selector), {
+            contractClassId,
+            selector
+        });
+        return {
+            ...fn,
+            contractName: artifact.name,
+            debug: getFunctionDebugMetadata(artifact, fn)
+        };
+    }
+    async getPublicFunctionArtifact(contractClassId) {
+        const artifact = await this.getContractArtifact(contractClassId);
+        const fn = artifact && artifact.functions.find((f)=>f.functionType === FunctionType.PUBLIC);
+        return fn && {
+            ...fn,
+            contractName: artifact.name
+        };
+    }
+    /**
+   * Retrieves the debug metadata of a specified function within a given contract class.
+   *
+   * @param contractClassId - The id of the contract class containing the function.
+   * @param selector - The function selector.
+   * @returns The corresponding function's debug metadata, or undefined.
+   */ async getFunctionDebugMetadata(contractClassId, selector) {
+        const artifact = await this.getContractArtifact(contractClassId);
+        if (!artifact) {
+            return undefined;
+        }
+        const fn = await findFunctionArtifactBySelector(artifact, selector);
+        return fn && getFunctionDebugMetadata(artifact, fn);
+    }
+    async getPublicFunctionDebugMetadata(contractClassId) {
+        const artifact = await this.getContractArtifact(contractClassId);
+        const fn = artifact && artifact.functions.find((f)=>f.functionType === FunctionType.PUBLIC);
+        return fn && getFunctionDebugMetadata(artifact, fn);
+    }
+    /**
+   * Retrieve the function membership witness for the given contract class and function selector.
+   *
+   * @param contractClassId - The id of the class.
+   * @param selector - The function selector.
+   * @returns A promise that resolves with the MembershipWitness instance for the specified contract's function.
+   */ async getFunctionMembershipWitness(contractClassId, selector) {
+        const tree = await this.#getPrivateFunctionTreeForClassId(contractClassId);
+        return tree?.getFunctionMembershipWitness(selector);
+    }
+    async getDebugContractName(contractClassId) {
+        const artifact = await this.getContractArtifact(contractClassId);
+        return artifact?.name;
+    }
+    async getDebugFunctionName(contractClassId, selector) {
+        const artifact = await this.getContractArtifact(contractClassId);
+        const fn = artifact && await findFunctionAbiBySelector(artifact, selector);
+        return `${artifact?.name ?? contractClassId}:${fn?.name ?? selector}`;
+    }
+    async getFunctionCall(functionName, args, to, contractClassId) {
+        const artifact = await this.getContractArtifact(contractClassId);
+        if (!artifact) {
+            throw new Error(`No artifact registered for contract class ${contractClassId} (contract ${to}): register it by calling ` + `wallet.registerContract(...).\nSee docs for context: https://docs.aztec.network/errors/14`);
+        }
+        const functionDao = artifact.functions.find((f)=>f.name === functionName);
+        if (!functionDao) {
+            throw new Error(`Unknown function ${functionName} in contract ${artifact.name}.`);
+        }
+        const selector = await FunctionSelector.fromNameAndParameters(functionDao.name, functionDao.parameters);
+        return FunctionCall.from({
+            name: functionDao.name,
+            to,
+            selector,
+            type: functionDao.functionType,
+            hideMsgSender: false,
+            isStatic: functionDao.isStatic,
+            args: encodeArguments(functionDao, args),
+            returnTypes: functionDao.returnTypes
+        });
+    }
+}
+/**
+ * Narrows the result of a selector lookup against a registered artifact. A missing class artifact is reported as
+ * `undefined` by the callers (an absence they can handle), but a selector that is absent from an artifact we *do* have
+ * is exceptional and throws rather than returning undefined. We cannot tell from here why the selector is missing: it
+ * may be that no such function exists in the contract (a wrong selector), or that the registered artifact does not
+ * correspond to the resolved class id (registration performs no validation, so a mismatched artifact is possible). The
+ * error names both possibilities.
+ */ function assertSelectorInArtifact(artifact, fn, context) {
+    if (!fn) {
+        throw new Error(`Function with selector ${context.selector} not found in the registered artifact for contract class ` + `${context.contractClassId} (${artifact.name}). Either no function with this selector exists in the ` + `contract, or the registered artifact does not match the class id (re-register it via ` + `wallet.registerContract(...)).`);
+    }
+    return fn;
+}

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_data_provider → contract_store}/private_functions_tree.d.ts

@@ -24,4 +24,4 @@ export declare class PrivateFunctionsTree {
     getFunctionMembershipWitness(selector: FunctionSelector): Promise<MembershipWitness<typeof FUNCTION_TREE_HEIGHT>>;
     private getTree;
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicHJpdmF0ZV9mdW5jdGlvbnNfdHJlZS5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL3N0b3JhZ2UvY29udHJhY3RfZGF0YV9wcm92aWRlci9wcml2YXRlX2Z1bmN0aW9uc190cmVlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxvQkFBb0IsRUFBRSxNQUFNLGtCQUFrQixDQUFDO0FBR3hELE9BQU8sRUFBRSxpQkFBaUIsRUFBbUIsTUFBTSx5QkFBeUIsQ0FBQztBQUM3RSxPQUFPLEVBQUUsS0FBSyxnQkFBZ0IsRUFBRSxnQkFBZ0IsRUFBZ0IsTUFBTSxtQkFBbUIsQ0FBQztBQVExRjs7Ozs7R0FLRztBQUNILHFCQUFhLG9CQUFvQjtJQUdYLE9BQU8sQ0FBQyxRQUFRLENBQUMsZ0JBQWdCO0lBRnJELE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FBYTtJQUUxQixPQUFPLGVBQXFFO0lBRTVFLE9BQWEsTUFBTSxDQUFDLFFBQVEsRUFBRSxnQkFBZ0IsaUNBTzdDO0lBRUQ7Ozs7Ozs7O09BUUc7SUFDVSw0QkFBNEIsQ0FDdkMsUUFBUSxFQUFFLGdCQUFnQixHQUN6QixPQUFPLENBQUMsaUJBQWlCLENBQUMsT0FBTyxvQkFBb0IsQ0FBQyxDQUFDLENBZXpEO1lBRWEsT0FBTztDQU10QiJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicHJpdmF0ZV9mdW5jdGlvbnNfdHJlZS5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL3N0b3JhZ2UvY29udHJhY3Rfc3RvcmUvcHJpdmF0ZV9mdW5jdGlvbnNfdHJlZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsb0JBQW9CLEVBQUUsTUFBTSxrQkFBa0IsQ0FBQztBQUd4RCxPQUFPLEVBQUUsaUJBQWlCLEVBQW1CLE1BQU0seUJBQXlCLENBQUM7QUFDN0UsT0FBTyxFQUFFLEtBQUssZ0JBQWdCLEVBQUUsZ0JBQWdCLEVBQWdCLE1BQU0sbUJBQW1CLENBQUM7QUFRMUY7Ozs7O0dBS0c7QUFDSCxxQkFBYSxvQkFBb0I7SUFHWCxPQUFPLENBQUMsUUFBUSxDQUFDLGdCQUFnQjtJQUZyRCxPQUFPLENBQUMsSUFBSSxDQUFDLENBQWE7SUFFMUIsT0FBTyxlQUFxRTtJQUU1RSxPQUFhLE1BQU0sQ0FBQyxRQUFRLEVBQUUsZ0JBQWdCLGlDQU83QztJQUVEOzs7Ozs7OztPQVFHO0lBQ1UsNEJBQTRCLENBQ3ZDLFFBQVEsRUFBRSxnQkFBZ0IsR0FDekIsT0FBTyxDQUFDLGlCQUFpQixDQUFDLE9BQU8sb0JBQW9CLENBQUMsQ0FBQyxDQWV6RDtZQUVhLE9BQU87Q0FNdEIifQ==

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,kBAAkB,CAAC;AAGxD,OAAO,EAAE,iBAAiB,EAAmB,MAAM,yBAAyB,CAAC;AAC7E,OAAO,EAAE,KAAK,gBAAgB,EAAE,gBAAgB,EAAgB,MAAM,mBAAmB,CAAC;AAQ1F;;;;;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_data_provider → contract_store}/private_functions_tree.js

@@ -1,5 +1,5 @@
 import { FUNCTION_TREE_HEIGHT } from '@aztec/constants';
-import { Fr } from '@aztec/foundation/fields';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { assertLength } from '@aztec/foundation/serialize';
 import { MembershipWitness } from '@aztec/foundation/trees';
 import { FunctionType } from '@aztec/stdlib/abi';

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

@@ -0,0 +1,22 @@
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+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, jobId: string): Promise<void>;
+    deleteFactCollection(factCollectionKey: FactCollectionKey, jobId: string): Promise<void>;
+    getFactCollection(factCollectionKey: FactCollectionKey, tips: TipBlockNumbers, jobId: string): Promise<FactCollectionWithOriginState | undefined>;
+    getFactCollectionsByType(factCollectionTypeKey: FactCollectionTypeKey, tips: TipBlockNumbers, jobId: string): Promise<FactCollectionWithOriginState[]>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZmFjdF9zZXJ2aWNlLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvc3RvcmFnZS9mYWN0X3N0b3JlL2ZhY3Rfc2VydmljZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssRUFBRSxFQUFFLEVBQUUsTUFBTSxnQ0FBZ0MsQ0FBQztBQUN6RCxPQUFPLEtBQUssRUFBRSxZQUFZLEVBQUUsTUFBTSw2QkFBNkIsQ0FBQztBQUdoRSxPQUFPLEtBQUssRUFBRSxTQUFTLEVBQUUsTUFBTSxpQkFBaUIsQ0FBQztBQUNqRCxPQUFPLEtBQUssRUFBRSxpQkFBaUIsRUFBRSxxQkFBcUIsRUFBRSxXQUFXLEVBQUUsTUFBTSxzQkFBc0IsQ0FBQztBQUNsRyxPQUFPLEVBQ0wsS0FBSyw2QkFBNkIsRUFFbEMsS0FBSyxlQUFlLEVBRXJCLE1BQU0sbUJBQW1CLENBQUM7QUFHM0I7Ozs7O0dBS0c7QUFDSCxxQkFBYSxXQUFXOztJQUVwQixPQUFPLENBQUMsUUFBUSxDQUFDLFNBQVM7SUFDMUIsT0FBTyxDQUFDLFFBQVEsQ0FBQyxhQUFhO0lBRmhDLFlBQ21CLFNBQVMsRUFBRSxTQUFTLEVBQ3BCLGFBQWEsRUFBRSxZQUFZLEVBQUUsRUFDNUM7SUFFSixVQUFVLENBQ1IsaUJBQWlCLEVBQUUsaUJBQWlCLEVBQ3BDLFVBQVUsRUFBRSxFQUFFLEVBQ2QsT0FBTyxFQUFFLEVBQUUsRUFBRSxFQUNiLFdBQVcsRUFBRSxXQUFXLEdBQUcsU0FBUyxFQUNwQyxLQUFLLEVBQUUsTUFBTSxHQUNaLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FHZjtJQUVELG9CQUFvQixDQUFDLGlCQUFpQixFQUFFLGlCQUFpQixFQUFFLEtBQUssRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQUd2RjtJQUVLLGlCQUFpQixDQUNyQixpQkFBaUIsRUFBRSxpQkFBaUIsRUFDcEMsSUFBSSxFQUFFLGVBQWUsRUFDckIsS0FBSyxFQUFFLE1BQU0sR0FDWixPQUFPLENBQUMsNkJBQTZCLEdBQUcsU0FBUyxDQUFDLENBT3BEO0lBRUssd0JBQXdCLENBQzVCLHFCQUFxQixFQUFFLHFCQUFxQixFQUM1QyxJQUFJLEVBQUUsZUFBZSxFQUNyQixLQUFLLEVBQUUsTUFBTSxHQUNaLE9BQU8sQ0FBQyw2QkFBNkIsRUFBRSxDQUFDLENBSTFDO0NBS0YifQ==

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,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,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;IAEK,iBAAiB,CACrB,iBAAiB,EAAE,iBAAiB,EACpC,IAAI,EAAE,eAAe,EACrB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,6BAA6B,GAAG,SAAS,CAAC,CAOpD;IAEK,wBAAwB,CAC5B,qBAAqB,EAAE,qBAAqB,EAC5C,IAAI,EAAE,eAAe,EACrB,KAAK,EAAE,MAAM,GACZ,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, 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);
+    }
+    async getFactCollection(factCollectionKey, tips, jobId) {
+        assertAllowedScope(factCollectionKey.scope, this.allowedScopes);
+        const collection = await this.factStore.getFactCollection(factCollectionKey, jobId);
+        if (!collection) {
+            return undefined;
+        }
+        return {
+            key: collection.key,
+            facts: this.#annotate(collection.facts, tips)
+        };
+    }
+    async getFactCollectionsByType(factCollectionTypeKey, tips, jobId) {
+        assertAllowedScope(factCollectionTypeKey.scope, this.allowedScopes);
+        const collections = await this.factStore.getFactCollectionsByType(factCollectionTypeKey, jobId);
+        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,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"}