@aztec-labs/pxe 6.0.0-nightly.20260829

package/dest/storage/capsule_store/capsule_store.js

@@ -0,0 +1,256 @@
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { createLogger } from '@aztec-labs/foundation/log';
+export class CapsuleStore {
+    storeName = 'capsule';
+    #store;
+    // Arbitrary data stored by contracts. Key is computed as `${contractAddress}:${scope}:${key}`, using the zero
+    // address for the global scope.
+    #capsules;
+    // changeSetId => `${contractAddress}:${scope}:${key}` => capsule data
+    // when `#stagedCapsules.get('some-change-set-id').get('${some-contract-address}:${some-scope}:${some-key}')` is
+    // null, it signals that the capsule was deleted during the change set, so it needs to be deleted on commit
+    #stagedCapsules;
+    logger;
+    constructor(store){
+        this.#store = store;
+        this.#capsules = this.#store.openMap('capsules');
+        this.#stagedCapsules = new Map();
+        this.logger = createLogger('pxe:capsule-data-provider');
+    }
+    /**
+   * Given a change set denoted by `changeSetId`, it returns the capsules that said change set has interacted with.
+   *
+   * Capsules that haven't been committed to persistence KV storage
+   * are kept in-memory in `#stagedCapsules`, this method provides a convenient
+   * way to access that in-memory collection of data.
+   *
+   * @param changeSetId
+   * @returns
+   */ #getStagedCapsules(changeSetId) {
+        let stagedCapsules = this.#stagedCapsules.get(changeSetId);
+        if (!stagedCapsules) {
+            stagedCapsules = new Map();
+            this.#stagedCapsules.set(changeSetId, stagedCapsules);
+        }
+        return stagedCapsules;
+    }
+    /**
+   * Reads a capsule's slot from the staged version of the data associated to the given changeSetId.
+   *
+   * If it is not there, it reads it from the KV store.
+   */ async #getFromStage(changeSetId, dbSlotKey) {
+        const stagedCapsules = this.#getStagedCapsules(changeSetId);
+        const staged = stagedCapsules.get(dbSlotKey);
+        // Always issue DB read to keep IndexedDB transaction alive, even if the value is in the staged data. This
+        // keeps IndexedDB transactions alive (they auto-commit when a new micro-task starts and there are no pending read
+        // requests). The staged value still takes precedence if it exists (including null for deletions).
+        const dbValue = await this.#loadCapsuleFromDb(dbSlotKey);
+        return staged !== undefined ? staged : dbValue;
+    }
+    /**
+   * Writes a capsule to the staging area.
+   */ #setOnStage(changeSetId, dbSlotKey, capsuleData) {
+        this.#getStagedCapsules(changeSetId).set(dbSlotKey, capsuleData);
+    }
+    /**
+   * Deletes a capsule on the staging area. Note the capsule will still
+   * exist in storage until the change set is committed.
+   */ #deleteOnStage(changeSetId, dbSlotKey) {
+        this.#getStagedCapsules(changeSetId).set(dbSlotKey, null);
+    }
+    async #loadCapsuleFromDb(dbSlotKey) {
+        const dataBuffer = await this.#capsules.getAsync(dbSlotKey);
+        if (!dataBuffer) {
+            return null;
+        }
+        return dataBuffer;
+    }
+    /**
+   * Commits staged data to main storage. Called by StagedWriteCoordinator when an operation completes successfully.
+   * Note: StagedWriteCoordinator wraps all commits in a single transaction, so we don't need our own transactionAsync
+   * here (and using one would deadlock on IndexedDB).
+   * @param changeSetId - The changeSetId identifying which staged data to commit
+   */ async commitChangeSet(changeSetId) {
+        const stagedCapsules = this.#getStagedCapsules(changeSetId);
+        for (const [key, value] of stagedCapsules){
+            // In the write stage, we represent deleted capsules with null
+            // (as opposed to undefined, which denotes there was never a capsule there to begin with).
+            // So we delete from actual KV store here.
+            if (value === null) {
+                await this.#capsules.delete(key);
+            } else {
+                await this.#capsules.set(key, value);
+            }
+        }
+        this.#stagedCapsules.delete(changeSetId);
+    }
+    /**
+   * Discards staged data without committing.
+   */ discardChangeSet(changeSetId) {
+        this.#stagedCapsules.delete(changeSetId);
+    }
+    /**
+   * Stores arbitrary information in a per-contract non-volatile database, which can later be retrieved with `loadCapsule`.
+   * * If data was already stored at this slot, it is overwritten.
+   * @param contractAddress - The contract address to scope the data under.
+   * @param slot - The slot in the database in which to store the value. Slots need not be contiguous.
+   * @param capsule - An array of field elements representing the capsule.
+   * @param changeSetId - The context in which this store will be visible until PXE decides to persist it to underlying
+   * KV store
+   * @remarks A capsule is a "blob" of data that is passed to the contract through an oracle. It works similarly
+   * to public contract storage in that it's indexed by the contract address and storage slot but instead of the global
+   * network state it's backed by local PXE db.
+   */ setCapsule(contractAddress, slot, capsule, changeSetId, scope) {
+        const dbSlotKey = dbSlotToKey(contractAddress, slot, scope);
+        // A store overrides any pre-existing data on the slot
+        this.#setOnStage(changeSetId, dbSlotKey, Buffer.concat(capsule.map((value)=>value.toBuffer())));
+    }
+    /**
+   * Returns data previously stored via `storeCapsule` in the per-contract non-volatile database.
+   * @param contractAddress - The contract address under which the data is scoped.
+   * @param slot - The slot in the database to read.
+   * @returns The stored data or `null` if no data is stored under the slot.
+   */ getCapsule(contractAddress, slot, changeSetId, scope) {
+        return this.#store.transactionAsync(()=>this.#getCapsuleInternal(contractAddress, slot, changeSetId, scope));
+    }
+    /** Same as getCapsule but without its own transaction, for use inside an existing transactionAsync. */ async #getCapsuleInternal(contractAddress, slot, changeSetId, scope) {
+        const dataBuffer = await this.#getFromStage(changeSetId, dbSlotToKey(contractAddress, slot, scope));
+        if (!dataBuffer) {
+            this.logger.trace(`Data not found for contract ${contractAddress.toString()} and slot ${slot.toString()}`);
+            return null;
+        }
+        const capsule = [];
+        for(let i = 0; i < dataBuffer.length; i += Fr.SIZE_IN_BYTES){
+            capsule.push(Fr.fromBuffer(dataBuffer.subarray(i, i + Fr.SIZE_IN_BYTES)));
+        }
+        return capsule;
+    }
+    /**
+   * Deletes data in the per-contract non-volatile database. Does nothing if no data was present.
+   * @param contractAddress - The contract address under which the data is scoped.
+   * @param slot - The slot in the database to delete.
+   */ deleteCapsule(contractAddress, slot, changeSetId, scope) {
+        // When we commit this, we will interpret null as a deletion, so we'll propagate the delete to the KV store
+        this.#deleteOnStage(changeSetId, dbSlotToKey(contractAddress, slot, scope));
+    }
+    /**
+   * Copies a number of contiguous entries in the per-contract non-volatile database. This allows for efficient data
+   * structures by avoiding repeated calls to `loadCapsule` and `storeCapsule`.
+   * Supports overlapping source and destination regions (which will result in the overlapped source values being
+   * overwritten). All copied slots must exist in the database (i.e. have been stored and not deleted)
+   *
+   * @param contractAddress - The contract address under which the data is scoped.
+   * @param srcSlot - The first slot to copy from.
+   * @param dstSlot - The first slot to copy to.
+   * @param numEntries - The number of entries to copy.
+   */ copyCapsule(contractAddress, srcSlot, dstSlot, numEntries, changeSetId, scope) {
+        // This transactional context gives us "copy atomicity":
+        // there shouldn't be concurrent writes to what's being copied here.
+        // Equally important: this in practice is expected to perform thousands of DB operations
+        // and not using a transaction here would heavily impact performance.
+        return this.#store.transactionAsync(async ()=>{
+            // In order to support overlapping source and destination regions, we need to check the relative positions of source
+            // and destination. If destination is ahead of source, then by the time we overwrite source elements using forward
+            // indexes we'll have already read those. On the contrary, if source is ahead of destination we need to use backward
+            // indexes to avoid reading elements that've been overwritten.
+            const indexes = Array.from(Array(numEntries).keys());
+            if (srcSlot.lt(dstSlot)) {
+                indexes.reverse();
+            }
+            for (const i of indexes){
+                const currentSrcSlot = dbSlotToKey(contractAddress, srcSlot.add(new Fr(i)), scope);
+                const currentDstSlot = dbSlotToKey(contractAddress, dstSlot.add(new Fr(i)), scope);
+                const toCopy = await this.#getFromStage(changeSetId, currentSrcSlot);
+                if (!toCopy) {
+                    throw new Error(`Attempted to copy empty slot ${currentSrcSlot} for contract ${contractAddress.toString()}`);
+                }
+                this.#setOnStage(changeSetId, currentDstSlot, toCopy);
+            }
+        });
+    }
+    /**
+   * Appends multiple capsules to a capsule array stored at the base slot.
+   * The array length is stored at the base slot, and elements are stored in consecutive slots after it.
+   * All operations are performed in a single transaction.
+   * @param contractAddress - The contract address that owns the capsule array
+   * @param baseSlot - The slot where the array length is stored
+   * @param content - Array of capsule data to append
+   */ appendToCapsuleArray(contractAddress, baseSlot, content, changeSetId, scope) {
+        // We wrap this in a transaction to serialize concurrent calls from allToCompletion.
+        // Without this, concurrent appends to the same array could race: both read length=0,
+        // both write at the same slots, one overwrites the other.
+        // Equally important: this in practice is expected to perform thousands of DB operations
+        // and not using a transaction here would heavily impact performance.
+        return this.#store.transactionAsync(async ()=>{
+            // Load current length, defaulting to 0 if not found
+            const lengthData = await this.#getCapsuleInternal(contractAddress, baseSlot, changeSetId, scope);
+            const currentLength = lengthData ? lengthData[0].toNumber() : 0;
+            // Store each capsule at consecutive slots after baseSlot + 1 + currentLength
+            for(let i = 0; i < content.length; i++){
+                const nextSlot = arraySlot(baseSlot, currentLength + i);
+                this.setCapsule(contractAddress, nextSlot, content[i], changeSetId, scope);
+            }
+            // Update length to include all new capsules
+            const newLength = currentLength + content.length;
+            this.setCapsule(contractAddress, baseSlot, [
+                new Fr(newLength)
+            ], changeSetId, scope);
+        });
+    }
+    readCapsuleArray(contractAddress, baseSlot, changeSetId, scope) {
+        // I'm leaving this transactional context here though because I'm assuming this gives us "read array atomicity":
+        // there shouldn't be concurrent writes to what's being copied here. This is one point we should revisit in the
+        // future if we want to relax the concurrency of change sets: different calls running concurrently on the same
+        // contract may cause trouble.
+        return this.#store.transactionAsync(async ()=>{
+            // Load length, defaulting to 0 if not found
+            const maybeLength = await this.#getCapsuleInternal(contractAddress, baseSlot, changeSetId, scope);
+            const length = maybeLength ? maybeLength[0].toBigInt() : 0n;
+            const values = [];
+            // Read each capsule at consecutive slots after baseSlot
+            for(let i = 0; i < length; i++){
+                const currentValue = await this.#getCapsuleInternal(contractAddress, arraySlot(baseSlot, i), changeSetId, scope);
+                if (currentValue == undefined) {
+                    throw new Error(`Expected non-empty value at capsule array in base slot ${baseSlot} at index ${i} for contract ${contractAddress}`);
+                }
+                values.push(currentValue);
+            }
+            return values;
+        });
+    }
+    setCapsuleArray(contractAddress, baseSlot, content, changeSetId, scope) {
+        // This transactional context in theory isn't so critical now because we aren't writing to DB so if there's
+        // exceptions midway and it blows up, no visible impact to persistent storage will happen. I'm leaving this
+        // transactional context here though because I'm assuming this gives us "write array atomicity": there shouldn't be
+        // concurrent writes to what's being copied here. This is one point we should revisit in the future if we want to
+        // relax the concurrency of change sets: different calls running concurrently on the same contract may cause
+        // trouble.
+        return this.#store.transactionAsync(async ()=>{
+            // Load current length, defaulting to 0 if not found
+            const maybeLength = await this.#getCapsuleInternal(contractAddress, baseSlot, changeSetId, scope);
+            const originalLength = maybeLength ? maybeLength[0].toNumber() : 0;
+            // Set the new length
+            this.setCapsule(contractAddress, baseSlot, [
+                new Fr(content.length)
+            ], changeSetId, scope);
+            // Store the new content, possibly overwriting existing values
+            for(let i = 0; i < content.length; i++){
+                this.setCapsule(contractAddress, arraySlot(baseSlot, i), content[i], changeSetId, scope);
+            }
+            // Clear any stragglers
+            for(let i = content.length; i < originalLength; i++){
+                this.deleteCapsule(contractAddress, arraySlot(baseSlot, i), changeSetId, scope);
+            }
+        });
+    }
+}
+function dbSlotToKey(contractAddress, slot, scope) {
+    return [
+        contractAddress.toString(),
+        scope.toString(),
+        slot.toString()
+    ].join(':');
+}
+function arraySlot(baseSlot, index) {
+    return baseSlot.add(new Fr(1)).add(new Fr(index));
+}

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

@@ -0,0 +1,3 @@
+export { CapsuleService } from './capsule_service.js';
+export { CapsuleStore } from './capsule_store.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9zdG9yYWdlL2NhcHN1bGVfc3RvcmUvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLGNBQWMsRUFBRSxNQUFNLHNCQUFzQixDQUFDO0FBQ3RELE9BQU8sRUFBRSxZQUFZLEVBQUUsTUFBTSxvQkFBb0IsQ0FBQyJ9

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/storage/capsule_store/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dest/storage/capsule_store/index.js

@@ -0,0 +1,2 @@
+export { CapsuleService } from './capsule_service.js';
+export { CapsuleStore } from './capsule_store.js';

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

@@ -0,0 +1,96 @@
+import type { FUNCTION_TREE_HEIGHT } from '@aztec-labs/constants';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { BufferReader } from '@aztec-labs/foundation/serialize';
+import type { MembershipWitness } from '@aztec-labs/foundation/trees';
+import type { AztecAsyncKVStore } from '@aztec-labs/kv-store';
+import { type ContractArtifact, type FunctionArtifactWithContractName, FunctionCall, type FunctionDebugMetadata, FunctionSelector } from '@aztec-labs/stdlib/abi';
+import { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import { type ContractClassIdPreimage, type ContractClassWithId, type ContractInstancePreimageWithAddress } from '@aztec-labs/stdlib/contract';
+/**
+ * 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 declare class SerializableContractClassData {
+    readonly version: 1;
+    readonly id: Fr;
+    readonly artifactHash: Fr;
+    readonly privateFunctionsRoot: Fr;
+    readonly publicBytecodeCommitment: Fr;
+    readonly privateFunctions: {
+        selector: FunctionSelector;
+        vkHash: Fr;
+    }[];
+    constructor(data: ContractClassIdPreimage & {
+        id: Fr;
+        privateFunctions: {
+            selector: FunctionSelector;
+            vkHash: Fr;
+        }[];
+    });
+    toBuffer(): Buffer;
+    static fromBuffer(bufferOrReader: Buffer | BufferReader): SerializableContractClassData;
+}
+/**
+ * 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 declare class ContractStore {
+    #private;
+    constructor(store: AztecAsyncKVStore);
+    /**
+     * 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.
+     */
+    addContractArtifact(contract: ContractArtifact, contractClassWithIdAndPreimage?: ContractClassWithId & ContractClassIdPreimage): Promise<Fr>;
+    addContractInstance(contract: ContractInstancePreimageWithAddress): Promise<void>;
+    getContractsAddresses(): Promise<AztecAddress[]>;
+    /** Returns the address preimage of a given address. */
+    getContractInstance(contractAddress: AztecAddress): Promise<ContractInstancePreimageWithAddress | undefined>;
+    /** Returns the raw contract artifact for a given class id. */
+    getContractArtifact(contractClassId: Fr): Promise<ContractArtifact | undefined>;
+    /** Returns a contract class for a given class id. */
+    getContractClassWithPreimage(contractClassId: Fr): Promise<(ContractClassWithId & ContractClassIdPreimage) | undefined>;
+    /**
+     * 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.
+     */
+    getFunctionArtifact(contractClassId: Fr, selector: FunctionSelector): Promise<FunctionArtifactWithContractName | undefined>;
+    /**
+     * Same as {@link getFunctionArtifact} but with debug metadata attached. Returns `undefined` when the class artifact
+     * is not registered.
+     */
+    getFunctionArtifactWithDebugMetadata(contractClassId: Fr, selector: FunctionSelector): Promise<FunctionArtifactWithContractName | undefined>;
+    getPublicFunctionArtifact(contractClassId: Fr): Promise<FunctionArtifactWithContractName | undefined>;
+    /**
+     * 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.
+     */
+    getFunctionDebugMetadata(contractClassId: Fr, selector: FunctionSelector): Promise<FunctionDebugMetadata | undefined>;
+    getPublicFunctionDebugMetadata(contractClassId: Fr): Promise<FunctionDebugMetadata | undefined>;
+    /**
+     * 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.
+     */
+    getFunctionMembershipWitness(contractClassId: Fr, selector: FunctionSelector): Promise<MembershipWitness<typeof FUNCTION_TREE_HEIGHT> | undefined>;
+    getDebugContractName(contractClassId: Fr): Promise<string | undefined>;
+    getDebugFunctionName(contractClassId: Fr, selector: FunctionSelector): Promise<string>;
+    getFunctionCall(functionName: string, args: any[], to: AztecAddress, contractClassId: Fr): Promise<FunctionCall>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29udHJhY3Rfc3RvcmUuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9zdG9yYWdlL2NvbnRyYWN0X3N0b3JlL2NvbnRyYWN0X3N0b3JlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxFQUFFLG9CQUFvQixFQUFFLE1BQU0sdUJBQXVCLENBQUM7QUFDbEUsT0FBTyxFQUFFLEVBQUUsRUFBRSxNQUFNLHFDQUFxQyxDQUFDO0FBR3pELE9BQU8sRUFBRSxZQUFZLEVBQWlDLE1BQU0sa0NBQWtDLENBQUM7QUFDL0YsT0FBTyxLQUFLLEVBQUUsaUJBQWlCLEVBQUUsTUFBTSw4QkFBOEIsQ0FBQztBQUN0RSxPQUFPLEtBQUssRUFBRSxpQkFBaUIsRUFBaUIsTUFBTSxzQkFBc0IsQ0FBQztBQUM3RSxPQUFPLEVBQ0wsS0FBSyxnQkFBZ0IsRUFDckIsS0FBSyxnQ0FBZ0MsRUFDckMsWUFBWSxFQUNaLEtBQUsscUJBQXFCLEVBQzFCLGdCQUFnQixFQVNqQixNQUFNLHdCQUF3QixDQUFDO0FBQ2hDLE9BQU8sRUFBRSxZQUFZLEVBQUUsTUFBTSxrQ0FBa0MsQ0FBQztBQUNoRSxPQUFPLEVBQ0wsS0FBSyx1QkFBdUIsRUFDNUIsS0FBSyxtQkFBbUIsRUFDeEIsS0FBSyxtQ0FBbUMsRUFHekMsTUFBTSw2QkFBNkIsQ0FBQztBQU1yQzs7Ozs7R0FLRztBQUNILHFCQUFhLDZCQUE2QjtJQUN4QyxTQUFnQixPQUFPLElBQVc7SUFDbEMsU0FBZ0IsRUFBRSxFQUFFLEVBQUUsQ0FBQztJQUN2QixTQUFnQixZQUFZLEVBQUUsRUFBRSxDQUFDO0lBQ2pDLFNBQWdCLG9CQUFvQixFQUFFLEVBQUUsQ0FBQztJQUN6QyxTQUFnQix3QkFBd0IsRUFBRSxFQUFFLENBQUM7SUFDN0MsU0FBZ0IsZ0JBQWdCLEVBQUU7UUFBRSxRQUFRLEVBQUUsZ0JBQWdCLENBQUM7UUFBQyxNQUFNLEVBQUUsRUFBRSxDQUFBO0tBQUUsRUFBRSxD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

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

@@ -0,0 +1 @@
+{"version":3,"file":"contract_store.d.ts","sourceRoot":"","sources":["../../../src/storage/contract_store/contract_store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,EAAE,EAAE,EAAE,MAAM,qCAAqC,CAAC;AAGzD,OAAO,EAAE,YAAY,EAAiC,MAAM,kCAAkC,CAAC;AAC/F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,KAAK,EAAE,iBAAiB,EAAiB,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,gCAAgC,EACrC,YAAY,EACZ,KAAK,qBAAqB,EAC1B,gBAAgB,EASjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAChE,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,mCAAmC,EAGzC,MAAM,6BAA6B,CAAC;AAMrC;;;;;GAKG;AACH,qBAAa,6BAA6B;IACxC,SAAgB,OAAO,IAAW;IAClC,SAAgB,EAAE,EAAE,EAAE,CAAC;IACvB,SAAgB,YAAY,EAAE,EAAE,CAAC;IACjC,SAAgB,oBAAoB,EAAE,EAAE,CAAC;IACzC,SAAgB,wBAAwB,EAAE,EAAE,CAAC;IAC7C,SAAgB,gBAAgB,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAC;QAAC,MAAM,EAAE,EAAE,CAAA;KAAE,EAAE,CAAC;IAE/E,YACE,IAAI,EAAE,uBAAuB,GAAG;QAC9B,EAAE,EAAE,EAAE,CAAC;QACP,gBAAgB,EAAE;YAAE,QAAQ,EAAE,gBAAgB,CAAC;YAAC,MAAM,EAAE,EAAE,CAAA;SAAE,EAAE,CAAC;KAChE,EAOF;IAED,QAAQ,IAAI,MAAM,CAUjB;IAED,MAAM,CAAC,UAAU,CAAC,cAAc,EAAE,MAAM,GAAG,YAAY,GAAG,6BAA6B,CAkBtF;CACF;AAED;;;;;;GAMG;AACH,qBAAa,aAAa;;IAkBxB,YAAY,KAAK,EAAE,iBAAiB,EAKnC;IAID;;;;;;OAMG;IACU,mBAAmB,CAC9B,QAAQ,EAAE,gBAAgB,EAC1B,8BAA8B,CAAC,EAAE,mBAAmB,GAAG,uBAAuB,GAC7E,OAAO,CAAC,EAAE,CAAC,CA4Bb;IAEK,mBAAmB,CAAC,QAAQ,EAAE,mCAAmC,GAAG,OAAO,CAAC,IAAI,CAAC,CAOtF;IAkBD,qBAAqB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAK/C;IAED,uDAAuD;IAChD,mBAAmB,CAAC,eAAe,EAAE,YAAY,GAAG,OAAO,CAAC,mCAAmC,GAAG,SAAS,CAAC,CAKlH;IAED,8DAA8D;IACjD,mBAAmB,CAAC,eAAe,EAAE,EAAE,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAc3F;IAED,qDAAqD;IACxC,4BAA4B,CACvC,eAAe,EAAE,EAAE,GAClB,OAAO,CAAC,CAAC,mBAAmB,GAAG,uBAAuB,CAAC,GAAG,SAAS,CAAC,CAatE;IAED;;;;;;OAMG;IACU,mBAAmB,CAC9B,eAAe,EAAE,EAAE,EACnB,QAAQ,EAAE,gBAAgB,GACzB,OAAO,CAAC,gCAAgC,GAAG,SAAS,CAAC,CAUvD;IAED;;;OAGG;IACU,oCAAoC,CAC/C,eAAe,EAAE,EAAE,EACnB,QAAQ,EAAE,gBAAgB,GACzB,OAAO,CAAC,gCAAgC,GAAG,SAAS,CAAC,CAcvD;IAEY,yBAAyB,CAAC,eAAe,EAAE,EAAE,GAAG,OAAO,CAAC,gCAAgC,GAAG,SAAS,CAAC,CAIjH;IAED;;;;;;OAMG;IACU,wBAAwB,CACnC,eAAe,EAAE,EAAE,EACnB,QAAQ,EAAE,gBAAgB,GACzB,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC,CAO5C;IAEY,8BAA8B,CAAC,eAAe,EAAE,EAAE,GAAG,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC,CAI3G;IAED;;;;;;OAMG;IACU,4BAA4B,CACvC,eAAe,EAAE,EAAE,EACnB,QAAQ,EAAE,gBAAgB,GACzB,OAAO,CAAC,iBAAiB,CAAC,OAAO,oBAAoB,CAAC,GAAG,SAAS,CAAC,CAGrE;IAEY,oBAAoB,CAAC,eAAe,EAAE,EAAE,+BAGpD;IAEY,oBAAoB,CAAC,eAAe,EAAE,EAAE,EAAE,QAAQ,EAAE,gBAAgB,mBAIhF;IAEY,eAAe,CAC1B,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,GAAG,EAAE,EACX,EAAE,EAAE,YAAY,EAChB,eAAe,EAAE,EAAE,GAClB,OAAO,CAAC,YAAY,CAAC,CA0BvB;CACF"}

package/dest/storage/contract_store/contract_store.js

@@ -0,0 +1,282 @@
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { toArray } from '@aztec-labs/foundation/iterable';
+import { allToCompletion } from '@aztec-labs/foundation/promise';
+import { BufferReader, numToUInt8, serializeToBuffer } from '@aztec-labs/foundation/serialize';
+import { FunctionCall, FunctionSelector, FunctionType, contractArtifactFromBuffer, contractArtifactToBuffer, encodeArguments, findFunctionAbiBySelector, findFunctionArtifactBySelector, getFunctionDebugMetadata, getFunctionReturnType } from '@aztec-labs/stdlib/abi';
+import { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import { SerializableContractInstancePreimage, getContractClassFromArtifact } from '@aztec-labs/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 allToCompletion(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),
+            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;
+}