@aztec/pxe 0.0.1-commit.c31f2472 → 0.0.1-commit.c52d6e7

package/dest/storage/contract_store/contract_store.js

@@ -1,8 +1,53 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { toArray } from '@aztec/foundation/iterable';
-import { FunctionSelector, FunctionType, contractArtifactFromBuffer, contractArtifactToBuffer, encodeArguments, getFunctionDebugMetadata } from '@aztec/stdlib/abi';
+import { BufferReader, numToUInt8, serializeToBuffer } from '@aztec/foundation/serialize';
+import { FunctionCall, FunctionSelector, FunctionType, contractArtifactFromBuffer, contractArtifactToBuffer, encodeArguments, findFunctionAbiBySelector, findFunctionArtifactBySelector, getFunctionDebugMetadata, getFunctionReturnType } from '@aztec/stdlib/abi';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
-import { SerializableContractInstance, getContractClassFromArtifact } from '@aztec/stdlib/contract';
+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
@@ -12,47 +57,54 @@ import { PrivateFunctionsTree } from './private_functions_tree.js';
  */ 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();
-    /** Map from contract address to contract class id */ #contractClassIdMap = 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
-    async addContractArtifact(id, contract) {
+    /**
+   * 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 (privateFunctionArtifact)=>(await FunctionSelector.fromNameAndParameters(privateFunctionArtifact.name, privateFunctionArtifact.parameters)).toString()));
+        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');
         }
-        await this.#contractArtifacts.set(id.toString(), contractArtifactToBuffer(contract));
+        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) {
-        this.#contractClassIdMap.set(contract.address.toString(), contract.currentContractClassId);
-        await this.#contractInstances.set(contract.address.toString(), new SerializableContractInstance(contract).toBuffer());
+        await this.#store.transactionAsync(async ()=>{
+            await this.#contractInstances.set(contract.address.toString(), new SerializableContractInstancePreimage(contract).toBuffer());
+        });
     }
     // Private getters
-    async #getContractClassId(contractAddress) {
-        if (!this.#contractClassIdMap.has(contractAddress.toString())) {
-            const instance = await this.getContractInstance(contractAddress);
-            if (!instance) {
-                return;
-            }
-            this.#contractClassIdMap.set(contractAddress.toString(), instance.currentContractClassId);
-        }
-        return this.#contractClassIdMap.get(contractAddress.toString());
-    }
-    /**
-   * Retrieve or create a ContractTree instance based on the provided class id.
-   * If an existing tree with the same class id is found in the cache, it will be returned.
-   * Otherwise, a new ContractTree instance will be created using the contract data from the database
-   * and added to the cache before returning.
-   *
-   * @param classId - The class id of the contract for which the ContractTree is required.
-   * @returns A ContractTree instance associated with the specified contract address.
-   * @throws An Error if the contract is not found in the ContractDatabase.
-   */ async #getPrivateFunctionTreeForClassId(classId) {
+    async #getPrivateFunctionTreeForClassId(classId) {
         if (!this.#privateFunctionTrees.has(classId.toString())) {
             const artifact = await this.getContractArtifact(classId);
             if (!artifact) {
@@ -63,104 +115,118 @@ import { PrivateFunctionsTree } from './private_functions_tree.js';
         }
         return this.#privateFunctionTrees.get(classId.toString());
     }
-    async #getContractArtifactByAddress(contractAddress) {
-        const contractClassId = await this.#getContractClassId(contractAddress);
-        return contractClassId && this.getContractArtifact(contractClassId);
-    }
     // Public getters
-    async getContractsAddresses() {
-        const keys = await toArray(this.#contractInstances.keysAsync());
-        return keys.map(AztecAddress.fromString);
+    getContractsAddresses() {
+        return this.#store.transactionAsync(async ()=>{
+            const keys = await toArray(this.#contractInstances.keysAsync());
+            return keys.map(AztecAddress.fromStringUnsafe);
+        });
     }
-    /** Returns a contract instance for a given address. Throws if not found. */ async getContractInstance(contractAddress) {
-        const contract = await this.#contractInstances.getAsync(contractAddress.toString());
-        return contract && SerializableContractInstance.fromBuffer(contract).withAddress(contractAddress);
+    /** 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);
+        });
     }
-    async getContractArtifact(contractClassId) {
-        const contract = await this.#contractArtifacts.getAsync(contractClassId.toString());
-        // TODO(@spalladino): AztecAsyncMap lies and returns Uint8Arrays instead of Buffers, hence the extra Buffer.from.
-        return contract && contractArtifactFromBuffer(Buffer.from(contract));
-    }
-    /** Returns a contract class for a given class id. Throws if not found. */ async getContractClass(contractClassId) {
-        const artifact = await this.getContractArtifact(contractClassId);
-        return artifact && getContractClassFromArtifact(artifact);
+    /** 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;
     }
-    async getContract(address) {
-        const instance = await this.getContractInstance(address);
-        if (!instance) {
-            return;
+    /** 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 artifact = await this.getContractArtifact(instance.currentContractClassId);
+        const classData = SerializableContractClassData.fromBuffer(buf);
+        const artifact = await this.getContractArtifact(contractClassId);
         if (!artifact) {
-            return;
+            return undefined;
         }
+        const packedBytecode = artifact.functions.find((f)=>f.name === 'public_dispatch')?.bytecode ?? Buffer.alloc(0);
         return {
-            ...instance,
-            ...artifact
+            ...classData,
+            packedBytecode
         };
     }
     /**
-   * Retrieves the artifact of a specified function within a given contract.
-   * The function is identified by its selector, which is a unique code generated from the function's signature.
-   * Throws an error if the contract address or function selector are invalid or not found.
+   * Retrieves the artifact of a specified function within a given contract class.
    *
-   * @param contractAddress - The AztecAddress representing the contract containing the function.
+   * @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.
-   */ async getFunctionArtifact(contractAddress, selector) {
-        const artifact = await this.#getContractArtifactByAddress(contractAddress);
-        const fnArtifact = artifact && await this.#findFunctionArtifactBySelector(artifact, selector);
-        return fnArtifact && {
-            ...fnArtifact,
+   * @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
         };
     }
-    async getFunctionArtifactWithDebugMetadata(contractAddress, selector) {
-        const artifact = await this.getFunctionArtifact(contractAddress, selector);
+    /**
+   * 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) {
-            throw new Error(`Function artifact not found for contract ${contractAddress} and selector ${selector}.`);
+            return undefined;
         }
-        const debug = await this.getFunctionDebugMetadata(contractAddress, selector);
+        const fn = assertSelectorInArtifact(artifact, await findFunctionArtifactBySelector(artifact, selector), {
+            contractClassId,
+            selector
+        });
         return {
-            ...artifact,
-            debug
+            ...fn,
+            contractName: artifact.name,
+            debug: getFunctionDebugMetadata(artifact, fn)
         };
     }
-    async getPublicFunctionArtifact(contractAddress) {
-        const artifact = await this.#getContractArtifactByAddress(contractAddress);
-        const fnArtifact = artifact && artifact.functions.find((fn)=>fn.functionType === FunctionType.PUBLIC);
-        return fnArtifact && {
-            ...fnArtifact,
+    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
         };
     }
-    async getFunctionAbi(contractAddress, selector) {
-        const artifact = await this.#getContractArtifactByAddress(contractAddress);
-        return artifact && await this.#findFunctionAbiBySelector(artifact, selector);
-    }
     /**
-   * Retrieves the debug metadata of a specified function within a given contract.
-   * The function is identified by its selector, which is a unique code generated from the function's signature.
-   * Returns undefined if the debug metadata for the given function is not found.
-   * Throws if the contract has not been added to the database.
+   * Retrieves the debug metadata of a specified function within a given contract class.
    *
-   * @param contractAddress - The AztecAddress representing the contract containing the function.
+   * @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.
-   */ async getFunctionDebugMetadata(contractAddress, selector) {
-        const artifact = await this.#getContractArtifactByAddress(contractAddress);
-        const fnArtifact = artifact && await this.#findFunctionArtifactBySelector(artifact, selector);
-        return fnArtifact && getFunctionDebugMetadata(artifact, fnArtifact);
+   * @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(contractAddress) {
-        const artifact = await this.#getContractArtifactByAddress(contractAddress);
-        const fnArtifact = artifact && artifact.functions.find((fn)=>fn.functionType === FunctionType.PUBLIC);
-        return fnArtifact && getFunctionDebugMetadata(artifact, fnArtifact);
+    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.
-   * The function membership witness represents a proof that the function belongs to the specified contract.
-   * Throws an error if the contract address or function selector is unknown.
    *
    * @param contractClassId - The id of the class.
    * @param selector - The function selector.
@@ -169,56 +235,47 @@ import { PrivateFunctionsTree } from './private_functions_tree.js';
         const tree = await this.#getPrivateFunctionTreeForClassId(contractClassId);
         return tree?.getFunctionMembershipWitness(selector);
     }
-    async getDebugContractName(contractAddress) {
-        const artifact = await this.#getContractArtifactByAddress(contractAddress);
+    async getDebugContractName(contractClassId) {
+        const artifact = await this.getContractArtifact(contractClassId);
         return artifact?.name;
     }
-    async getDebugFunctionName(contractAddress, selector) {
-        const artifact = await this.#getContractArtifactByAddress(contractAddress);
-        const fnArtifact = artifact && await this.#findFunctionAbiBySelector(artifact, selector);
-        return `${artifact?.name ?? contractAddress}:${fnArtifact?.name ?? selector}`;
-    }
-    async #findFunctionArtifactBySelector(artifact, selector) {
-        const functions = artifact.functions;
-        for(let i = 0; i < functions.length; i++){
-            const fn = functions[i];
-            const fnSelector = await FunctionSelector.fromNameAndParameters(fn.name, fn.parameters);
-            if (fnSelector.equals(selector)) {
-                return fn;
-            }
-        }
-    }
-    async #findFunctionAbiBySelector(artifact, selector) {
-        const functions = [
-            ...artifact.functions,
-            ...artifact.nonDispatchPublicFunctions ?? []
-        ];
-        for(let i = 0; i < functions.length; i++){
-            const fn = functions[i];
-            const fnSelector = await FunctionSelector.fromNameAndParameters(fn.name, fn.parameters);
-            if (fnSelector.equals(selector)) {
-                return fn;
-            }
-        }
+    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) {
-        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`);
+    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 = contract.functions.find((f)=>f.name === functionName);
+        const functionDao = artifact.functions.find((f)=>f.name === functionName);
         if (!functionDao) {
-            throw new Error(`Unknown function ${functionName} in contract ${contract.name}.`);
+            throw new Error(`Unknown function ${functionName} in contract ${artifact.name}.`);
         }
-        return {
+        const selector = await FunctionSelector.fromNameAndParameters(functionDao.name, functionDao.parameters);
+        return FunctionCall.from({
             name: functionDao.name,
-            args: encodeArguments(functionDao, args),
-            selector: await FunctionSelector.fromNameAndParameters(functionDao.name, functionDao.parameters),
-            type: functionDao.functionType,
             to,
+            selector,
+            type: functionDao.functionType,
             hideMsgSender: false,
             isStatic: functionDao.isStatic,
-            returnTypes: functionDao.returnTypes
-        };
+            args: encodeArguments(functionDao, args),
+            returnType: getFunctionReturnType(functionDao)
+        });
+    }
+}
+/**
+ * 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/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"}