@provablehq/sdk 0.10.2 → 0.10.4

package/dist/testnet/constants.d.cts

@@ -0,0 +1,40 @@
+import { VerifyingKey } from "./wasm.js";
+export declare const KEY_STORE: string;
+export interface Key {
+    name: string;
+    locator: string;
+    prover: string;
+    verifier: string;
+    verifyingKey: () => VerifyingKey;
+}
+export declare const CREDITS_PROGRAM_KEYS: {
+    bond_public: Key;
+    bond_validator: Key;
+    claim_unbond_public: Key;
+    fee_private: Key;
+    fee_public: Key;
+    inclusion: Key;
+    join: Key;
+    set_validator_state: Key;
+    split: Key;
+    transfer_private: Key;
+    transfer_private_to_public: Key;
+    transfer_public: Key;
+    transfer_public_as_signer: Key;
+    transfer_public_to_private: Key;
+    unbond_public: Key;
+    getKey: (key: string) => Key;
+};
+export declare const PRIVATE_TRANSFER_TYPES: Set<string>;
+export declare const VALID_TRANSFER_TYPES: Set<string>;
+export declare const PRIVATE_TRANSFER: Set<string>;
+export declare const PRIVATE_TO_PUBLIC_TRANSFER: Set<string>;
+export declare const PUBLIC_TRANSFER: Set<string>;
+export declare const PUBLIC_TRANSFER_AS_SIGNER: Set<string>;
+export declare const PUBLIC_TO_PRIVATE_TRANSFER: Set<string>;
+export declare const RECORD_DOMAIN = "RecordScannerV0";
+/**
+ * Zero address on Aleo blockchain that corresponds to field element 0. Used as padding in Merkle trees and as a sentinel value.
+ */
+export declare const ZERO_ADDRESS = "aleo1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq3ljyzc";
+export declare const FIVE_MINUTES: number;

package/dist/testnet/external-signing.d.cts

@@ -0,0 +1,76 @@
+import { ExecutionRequest } from "./wasm.js";
+import type { ExternalSigningInput, ExternalSigningOptions, ExecutionRequestParams, InputStrategy } from "./models/external-signing.js";
+export * from "./models/external-signing.js";
+/**
+ * Build an ExecutionRequest from externally signed data.
+ *
+ * The `strategy` parameter determines how record input IDs are resolved:
+ * - `{ recordViewKeys?, gammas? }` — explicit record view keys and gammas
+ * - `{ viewKey, gammas? }` — derive record view keys from a ViewKey
+ * - `{ inputIds }` — pre-computed input IDs (Field or [Field, Group, Field, Field, Field] tuples)
+ *
+ * @throws {Error} If `strategy` is not a valid `InputStrategy` variant.
+ *
+ * @example
+ * // With explicit record view keys
+ * buildExecutionRequestFromExternallySignedData(
+ *   { programId, functionName, inputs, inputTypes, signature, tvk, signer, skTag },
+ *   { recordViewKeys: [...], gammas: [...] },
+ * );
+ *
+ * // With a view key
+ * buildExecutionRequestFromExternallySignedData(
+ *   { programId, functionName, inputs, inputTypes, signature, tvk, signer, skTag },
+ *   { viewKey: "AViewKey1..." },
+ * );
+ *
+ * // With pre-computed input IDs
+ * buildExecutionRequestFromExternallySignedData(
+ *   { programId, functionName, inputs, inputTypes, signature, tvk, signer, skTag },
+ *   { inputIds: [...] },
+ * );
+ */
+export declare function buildExecutionRequestFromExternallySignedData(params: ExecutionRequestParams, strategy?: InputStrategy): ExecutionRequest;
+/**
+ * Computes the function ID and serialized input data for a program function call.
+ * Used by external signing wallets and other applications that need publicly computable inputs
+ * for building a signed execution request (e.g. before calling {@link ExecutionRequest.sign}).
+ *
+ * The optional `outputFormat` field controls how field elements are returned:
+ * - `"string"` (default) — human-readable strings like `"123field"`
+ * - `"bytes"` — raw little-endian `Uint8Array`s
+ *
+ * @param {ExternalSigningOptions} options - Program name, function name, inputs, input_types, root flag, an optional program checksum, an optional view key, and an optional output format.
+ * @throws Throws if parsing the program ID, function name, or inputs fails or if the inputs do not match the type signatures passed in the input_types parameter.
+ *
+ * @example
+ * // String output (default)
+ * const result = await computeExternalSigningInputs({
+ *   programName: "credits.aleo",
+ *   functionName: "transfer_public",
+ *   inputs: ["aleo1...", "100u64"],
+ *   inputTypes: ["address.public", "u64.public"],
+ *   isRoot: true,
+ * });
+ * result.functionId; // string
+ *
+ * @example
+ * // Bytes output
+ * const result = await computeExternalSigningInputs({
+ *   programName: "credits.aleo",
+ *   functionName: "transfer_public",
+ *   inputs: ["aleo1...", "100u64"],
+ *   inputTypes: ["address.public", "u64.public"],
+ *   isRoot: true,
+ *   outputFormat: "bytes",
+ * });
+ * result.functionId; // Uint8Array
+ *
+ * @returns {ExternalSigningInput} A JSON object for inputs to external signing algorithms.
+ */
+export declare function computeExternalSigningInputs(options: ExternalSigningOptions & {
+    outputFormat: "bytes";
+}): Promise<ExternalSigningInput<"bytes">>;
+export declare function computeExternalSigningInputs(options: ExternalSigningOptions & {
+    outputFormat?: "string";
+}): Promise<ExternalSigningInput<"string">>;

package/dist/testnet/integrations/sealance/merkle-tree.d.cts

@@ -0,0 +1,192 @@
+import { Field } from "../../wasm.js";
+/**
+ * Client library that encapsulates methods for constructing Merkle exclusion proofs for compliant stablecoin programs following the Sealance architecture.
+ *
+
+ * @example
+ * Construct a Merkle exclusion proof.
+ *  ```typescript
+ * const sealance = new SealanceMerkleTree();
+ * const leaves = [
+ *      "aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px",
+ *      "aleo1s3ws5tra87fjycnjrwsjcrnw2qxr8jfqqdugnf0xzqqw29q9m5pqem2u4t",
+ *      "aleo1s3ws5tra87fjycnjrwsjcrnw2qxr8jfqqdugnf0xzqqw29q9m5pqem2u4t",
+ *    ];
+ * const result = sealance.generateLeaves(leaves);
+ * const tree = sealance.buildTree(result);
+ * const [leftIdx, rightIdx] = sealance.getLeafIndices(tree, "aleo1kypwp5m7qtk9mwazgcpg0tq8aal23mnrvwfvug65qgcg9xvsrqgspyjm6n");
+ * const proof_left = sealance.getSiblingPath(tree, leftIdx, 15);
+ * const proof_right = sealance.getSiblingPath(tree, rightIdx, 15);
+ * const exclusion_proof = [proof_left, proof_right];
+ * const formatted_proof = sealance.formatMerkleProof(exclusion_proof);
+ * ```
+ */
+declare class SealanceMerkleTree {
+    private static hasher;
+    /**
+    * Converts an Aleo blockchain address to a field element.
+    *
+    * This function decodes a bech32m-encoded Aleo address and converts it to a field element
+    * represented as a BigInt. The address format follows the Aleo protocol specification,
+    * starting with the prefix "aleo1" followed by encoded data.
+    *
+    * @param address - The Aleo blockchain address (e.g., "aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px")
+    * @returns A BigInt representing the field element.
+    * @throws Error if the address is invalid or cannot be decoded.
+    *
+    * @example
+    * ```typescript
+    * const sealance = new SealanceMerkleTree();
+    * const address = "aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px";
+    * const fieldValue = sealance.convertAddressToField(address);
+    * console.log(fieldValue); // 123456789...n
+    * ```
+    */
+    convertAddressToField(address: string): bigint;
+    /**
+    * Hashes two elements using Poseidon4 hash function
+    * @param prefix - Prefix for the hash (e.g., "0field" for nodes, "1field" for leaves)
+    * @param el1 - First element to hash
+    * @param el2 - Second element to hash
+    * @returns The hash result as a Field
+    * @throws {Error} If inputs are empty or invalid
+    */
+    hashTwoElements(prefix: string, el1: string, el2: string): Field;
+    /**
+    * Builds a Merkle tree from given leaves. The tree is built bottom-up, hashing pairs of elements at each level.
+    *
+    * @param leaves - Array of leaf elements (must have even number of elements).
+    * @returns Array representing the complete Merkle tree as BigInts.
+    * @throws {Error} If leaves array is empty or has odd number of elements.
+    *
+    * @example
+    * ```typescript
+    * const sealance = new SealanceMerkleTree();
+    * const leaves = ["0field", "1field", "2field", "3field"];
+    * const tree = sealance.buildTree(leaves);
+    * const root = tree[tree.length - 1]; // Get the Merkle root
+    * ```
+    */
+    buildTree(leaves: string[]): bigint[];
+    /**
+    * Converts an array of decimal string representations of U256 numbers to an array of BigInts.
+    *
+    * @param tree - Array of decimal string representations of U256 numbers.
+    * @returns Array of BigInts.
+    *
+    * @example
+    * ```typescript
+    * const treeStrings = ["0","4328470178059738374782465505490977516512210899136548187530607227309847251692","1741259420362056497457198439964202806733137875365061915996980524089960046336"];
+    * const sealance = new SealanceMerkleTree();
+    * const treeBigInts = sealance.convertTreeToBigInt(treeStrings);
+    * console.log(treeBigInts); // [
+    *   0,
+    *   4328470178059738374782465505490977516512210899136548187530607227309847251692,
+    *   1741259420362056497457198439964202806733137875365061915996980524089960046336
+    *  ]
+    * ```
+    */
+    convertTreeToBigInt(tree: string[]): bigint[];
+    /**
+    * Converts Aleo addresses to field elements, sorts them, pads with zero fields, and returns an array. This prepares addresses for Merkle tree construction.
+    *
+    * @param addresses - Array of Aleo addresses.
+    * @param maxTreeDepth - Maximum depth of the Merkle tree (default: 15).
+    * @returns Array of field elements ready for Merkle tree construction.
+    * @throws {Error} If the number of addresses exceeds the maximum capacity.
+    *
+    * @example
+    * ```typescript
+    * const addresses = [
+ *      "aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px",
+ *      "aleo1s3ws5tra87fjycnjrwsjcrnw2qxr8jfqqdugnf0xzqqw29q9m5pqem2u4t",
+ *      "aleo1s3ws5tra87fjycnjrwsjcrnw2qxr8jfqqdugnf0xzqqw29q9m5pqem2u4t",
+ *    ];
+    * const sealance = new SealanceMerkleTree();
+    * const leaves = sealance.generateLeaves(addresses, 15);
+    * console.log(leaves); // [
+    *   "0field",
+    *   "1295133970529764960316948294624974168921228814652993007266766481909235735940field",
+    *   "1295133970529764960316948294624974168921228814652993007266766481909235735940field",
+    *   "3501665755452795161867664882580888971213780722176652848275908626939553697821field"
+    *  ]
+    * ```
+    */
+    generateLeaves(addresses: string[], maxTreeDepth?: number): string[];
+    /**
+    * Finds the leaf indices for non-inclusion proof of an address and returns the indices of the two adjacent leaves that surround the target address.
+    *
+    * @param merkleTree - The complete Merkle tree as array of BigInts.
+    * @param address - The Aleo address for which to find indices.
+    * @returns Tuple of [leftLeafIndex, rightLeafIndex].
+    *
+    * @example
+    * ```typescript
+    * const addresses = [
+ *      "aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px",
+ *      "aleo1s3ws5tra87fjycnjrwsjcrnw2qxr8jfqqdugnf0xzqqw29q9m5pqem2u4t",
+ *      "aleo1s3ws5tra87fjycnjrwsjcrnw2qxr8jfqqdugnf0xzqqw29q9m5pqem2u4t",
+ *    ];
+    * const sealance = new SealanceMerkleTree();
+    * const leaves = sealance.generateLeaves(addresses);
+    * const tree = sealance.buildTree(leaves);
+    * const [leftIdx, rightIdx] = sealance.getLeafIndices(tree, "aleo1...");
+    * ```
+    */
+    getLeafIndices(merkleTree: bigint[], address: string): [number, number];
+    /**
+    * Generates the sibling path (Merkle proof) for a given leaf index
+    *
+    * @param tree - The complete Merkle tree.
+    * @param leafIndex - Index of the leaf for which to generate the proof.
+    * @param depth - Maximum depth of the tree.
+    * @returns Object containing siblings array and leaf_index.
+    *
+    * @example
+    * ```typescript
+    * const addresses = [
+    *    "aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px",
+    *    "aleo1s3ws5tra87fjycnjrwsjcrnw2qxr8jfqqdugnf0xzqqw29q9m5pqem2u4t",
+    *    "aleo1s3ws5tra87fjycnjrwsjcrnw2qxr8jfqqdugnf0xzqqw29q9m5pqem2u4t",
+    *  ];
+    * const sealance = new SealanceMerkleTree();
+    * const leaves = sealance.generateLeaves(addresses);
+    * const tree = sealance.buildTree(leaves);
+    * const [leftIdx, rightIdx] = sealance.getLeafIndices(tree, "aleo1...");
+    * const proof = sealance.getSiblingPath(tree, leftIdx, 15);
+    * // proof = { siblings: [0n, 1n, ...], leaf_index: leftIdx }
+    * ```
+    */
+    getSiblingPath(tree: bigint[], leafIndex: number, depth: number): {
+        siblings: bigint[];
+        leaf_index: number;
+    };
+    /**
+    * Generates a formatted exclusion proof suitable for Aleo transactions.
+    *
+    * @param proof - An array of two {sibling path, leafindex} objects.
+    * @returns String representation of the exclusion proof.
+    *
+    * @example
+    * ```typescript
+    * const addresses = [
+    *    "aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px",
+    *    "aleo1s3ws5tra87fjycnjrwsjcrnw2qxr8jfqqdugnf0xzqqw29q9m5pqem2u4t",
+    *    "aleo1s3ws5tra87fjycnjrwsjcrnw2qxr8jfqqdugnf0xzqqw29q9m5pqem2u4t",
+    *  ];
+    * const sealance = new SealanceMerkleTree();
+    * const leaves = sealance.generateLeaves(addresses);
+    * const tree = sealance.buildTree(leaves);
+    * const [leftIdx, rightIdx] = sealance.getLeafIndices(tree, "aleo1...");
+    * const proof1 = getSiblingPath(tree, leftIdx, 15);
+    * const proof2 = getSiblingPath(tree, rightIdx, 15);
+    * const formattedProof = formatMerkleProof([proof1, proof2]);
+    * // formattedProof = "[{ siblings: [0field, 1field, ...], leaf_index: 0u32 }, { siblings: [0field, 2field, ...], leaf_index: 1u32 }]"
+    * ```
+    */
+    formatMerkleProof(proof: {
+        siblings: bigint[];
+        leaf_index: number;
+    }[]): string;
+}
+export { SealanceMerkleTree };

package/dist/testnet/keys/keystore/error.d.cts

@@ -0,0 +1,24 @@
+/**
+ * Reason code for invalid locator validation failures.
+ * - `"reserved_name"`: A locator component is empty or `"."`.
+ * - `"path_traversal"`: A locator component contains `..`.
+ * - `"path_separator"`: A locator component contains a path separator (`/`, `\`) or null byte.
+ * - `"negative_value"`: A numeric locator field (edition, amendment, recordInputPosition) is not a non-negative integer.
+ */
+export type InvalidLocatorReason = "reserved_name" | "path_traversal" | "path_separator" | "negative_value";
+/**
+ * Error thrown when a key locator is invalid for filesystem use.
+ * Used to prevent path traversal and other filesystem injection when deriving paths from locators.
+ *
+ * @extends Error
+ */
+export declare class InvalidLocatorError extends Error {
+    readonly locator: string;
+    readonly reason: InvalidLocatorReason;
+    /**
+     * @param message - Human-readable description of the validation failure.
+     * @param locator - The invalid locator string that failed validation.
+     * @param reason - Machine-readable reason code for the failure.
+     */
+    constructor(message: string, locator: string, reason: InvalidLocatorReason);
+}

package/dist/testnet/keys/keystore/file.d.cts

@@ -0,0 +1,177 @@
+import { FunctionKeyPair } from "../../models/keyPair.js";
+import { KeyFingerprint } from "../verifier/interface.js";
+import { KeyLocator, KeyStore, ProvingKeyLocator, VerifyingKeyLocator } from "./interface.js";
+import { ProvingKey, VerifyingKey } from "../../wasm.js";
+export declare class LocalFileKeyStore implements KeyStore {
+    private directory;
+    private readonly keyVerifier;
+    /**
+     * Creates a new directory at the given path or CURRENTDIR/.aleo if none is provided to store keys.
+     * If a custom directory is passed and its last path segment is not ".aleo", ".aleo" is appended
+     * so keys are stored under that subdirectory (e.g. /home/project → /home/project/.aleo).
+     *
+     * @param {string} [directory] - Optional custom directory path for key storage. Defaults to ".aleo" in current working directory.
+     * @throws {Error} If directory creation fails.
+     */
+    constructor(directory?: string);
+    /**
+     * Validates a single locator component for unsafe filesystem characters.
+     *
+     * @private
+     * @param {string} value - The component value to validate.
+     * @param {string} label - Label for error messages (e.g. "program", "functionName").
+     * @throws {InvalidLocatorError} If the value is empty, contains traversal sequences, path separators, or null bytes.
+     */
+    private validateComponent;
+    /**
+     * Validates that a numeric locator field is not negative.
+     *
+     * @private
+     * @param {number} value - The numeric value to validate.
+     * @param {string} label - Label for error messages (e.g. "edition", "amendment").
+     * @throws {InvalidLocatorError} If the value is negative.
+     */
+    private validateNonNegative;
+    /**
+     * Serializes a {@link KeyLocator} to a filesystem-safe flat string, validating components first.
+     *
+     * For prover/verifier keys: `{program}.{functionName}.e{edition}.a{amendment}.{network}.{keyType}`
+     * For translation keys: `{program}.{functionName}.e{edition}.a{amendment}.{network}.translation.{recordName}.{recordInputPosition}`
+     *
+     * Note: The optional `checksum` field is excluded — it is used for integrity verification only
+     * (via {@link checksumToFingerprint}) and is not part of the key identity.
+     *
+     * @private
+     * @param {KeyLocator} locator - The key locator.
+     * @returns {string} A dot-delimited string safe for use as a filename.
+     * @throws {InvalidLocatorError} If any component contains unsafe characters.
+     */
+    private serializeLocator;
+    /**
+     * Converts an optional checksum string from a locator into a KeyFingerprint
+     * suitable for the key verifier, using the actual key byte length for size.
+     *
+     * @private
+     */
+    private checksumToFingerprint;
+    /**
+     * Generates the path for a key metadata file based on the locator.
+     *
+     * @private
+     * @param {string} locator - Unique identifier for the key.
+     * @returns {string} Full filesystem path to the metadata file.
+     */
+    private metadataPath;
+    /**
+     * Reads and parses the key fingerprint metadata from storage.
+     *
+     * @private
+     * @param {string} locator - Unique identifier for the key.
+     * @returns {Promise<KeyFingerprint | null>} The key fingerprint if found, null if file doesn't exist.
+     * @throws {Error} If file read fails for any reason other than not found.
+     */
+    private readKeyMetadata;
+    /**
+     * Writes key fingerprint metadata to storage.
+     *
+     * @private
+     * @param {string} locator - Unique identifier for the key.
+     * @param {KeyFingerprint} metadata - Key fingerprint metadata to store.
+     * @returns {Promise<void>}
+     * @throws {Error} If directory creation or file write fails.
+     */
+    private writeKeyMetadata;
+    private readFileOptional;
+    /**
+     * Atomically writes data to a file, ensuring the parent directories exist.
+     *
+     * @private
+     * @param {string} filepath - Full path to the file to write
+     * @param {Uint8Array} data - Binary data to write to the file
+     * @returns {Promise<void>} Resolves when write is complete
+     * @throws {Error} If directory creation or file write fails
+     */
+    private writeFileAtomic;
+    /**
+     * Recursively removes all files and subdirectories under the given directory, then removes the directory itself.
+     * Uses fs.rm with recursive: true and force: true so that symbolic links are removed without following them,
+     * avoiding deletion of content outside the keystore.
+     *
+     * @private
+     * @param {string} dir - Directory path to clear
+     * @returns {Promise<void>} Resolves when clearing is complete
+     * @throws {Error} If directory removal fails for reasons other than non-existence
+     */
+    private clearDirectory;
+    /**
+     * Retrieves the key bytes from storage and optionally verifies them.
+     *
+     * @param {KeyLocator} locator - The key locator with optional checksum for verification.
+     * @returns {Promise<Uint8Array | null>} The key bytes if found and verified, null if not found.
+     * @throws {KeyVerificationError} If verification fails.
+     */
+    getKeyBytes(locator: KeyLocator): Promise<Uint8Array | null>;
+    /**
+     * Retrieves and verifies a proving key from storage.
+     *
+     * @param {ProvingKeyLocator} locator - The proving key locator.
+     * @returns {Promise<ProvingKey | null>} The proving key if found and verified, null if not found.
+     * @throws {KeyVerificationError} If verification fails.
+     * @throws {Error} If key bytes cannot be parsed into a valid ProvingKey.
+     */
+    getProvingKey(locator: ProvingKeyLocator): Promise<ProvingKey | null>;
+    /**
+     * Retrieves and verifies a verifying key from storage.
+     *
+     * @param {VerifyingKeyLocator} locator - The verifying key locator.
+     * @returns {Promise<VerifyingKey | null>} The verifying key if found and verified, null if not found.
+     * @throws {KeyVerificationError} If verification fails.
+     * @throws {Error} If key bytes cannot be parsed into a valid VerifyingKey.
+     */
+    getVerifyingKey(locator: VerifyingKeyLocator): Promise<VerifyingKey | null>;
+    /**
+     * Stores proving and verifying keys in key storage.
+     *
+     * @param {ProvingKeyLocator} proverLocator The locator for the proving key.
+     * @param {VerifyingKeyLocator} verifierLocator The locator for the verifying key.
+     * @param {FunctionKeyPair} keys The proving and verifying keys.
+     */
+    setKeys(proverLocator: ProvingKeyLocator, verifierLocator: VerifyingKeyLocator, keys: FunctionKeyPair): Promise<void>;
+    /**
+     * Store a raw key in storage along with its fingerprint metadata for future verification.
+     *
+     * @param {Uint8Array} keyBytes The raw key bytes.
+     * @param {KeyLocator} locator The unique locator for the key.
+     * @returns {Promise<void>}
+     * @throws {Error} If computing key metadata or writing to storage fails
+     */
+    setKeyBytes(keyBytes: Uint8Array, locator: KeyLocator): Promise<void>;
+    /**
+     * Returns stored metadata for a key, if any.
+     *
+     * @param {KeyLocator} locator The unique locator for the key.
+     * @returns {Promise<KeyFingerprint | null>} The stored fingerprint metadata, or null if none exists.
+     */
+    getKeyMetadata(locator: KeyLocator): Promise<KeyFingerprint | null>;
+    /**
+     * Checks if a key exists for the given locator.
+     *
+     * @param {KeyLocator} locator - The unique key locator.
+     * @returns {Promise<boolean>} True if key exists, false otherwise.
+     */
+    has(locator: KeyLocator): Promise<boolean>;
+    /**
+     * Deletes a key and its associated metadata from storage. Silently ignores errors if files don't exist.
+     *
+     * @param {KeyLocator} locator - The unique key locator.
+     * @returns {Promise<void>}
+     */
+    delete(locator: KeyLocator): Promise<void>;
+    /**
+     * Clears the key storage directory by recursively removing all files and subdirectories under it, then removes the keystore directory itself.
+     *
+     * @returns {Promise<void>}
+     * @throws {Error} If directory listing fails for reasons other than non-existence.
+     */
+    clear(): Promise<void>;
+}

package/dist/testnet/keys/keystore/interface.d.cts

@@ -0,0 +1,161 @@
+import { FunctionKeyPair } from "../../models/keyPair.js";
+export type { InvalidLocatorReason } from "./error.js";
+export { InvalidLocatorError } from "./error.js";
+import { KeyFingerprint } from "../verifier/interface.js";
+import { ProvingKey, VerifyingKey } from "../../wasm.js";
+/**
+ * Discriminates the type of key a locator refers to.
+ */
+export type KeyType = "prover" | "verifier" | "translation";
+/**
+ * Shared fields for all function key locators.
+ *
+ * @property {string} program - The program name (e.g. "credits.aleo").
+ * @property {string} functionName - The function name (e.g. "transfer_private").
+ * @property {number} edition - The program edition (u16). Incremented when a program is re-deployed.
+ * @property {number} amendment - The program amendment. Reserved for future protocol-level amendments; defaults to 0.
+ * @property {string} network - The network name (e.g. "mainnet", "testnet").
+ * @property {string} [checksum] - Optional SHA-256 checksum for key verification. Used for integrity verification only; not part of the key identity or serialized form.
+ */
+export interface BaseFunctionKeyLocator {
+    program: string;
+    functionName: string;
+    edition: number;
+    amendment: number;
+    network: string;
+    checksum?: string;
+}
+/**
+ * Locator for a proving key.
+ */
+export interface ProvingKeyLocator extends BaseFunctionKeyLocator {
+    keyType: "prover";
+}
+/**
+ * Locator for a verifying key.
+ */
+export interface VerifyingKeyLocator extends BaseFunctionKeyLocator {
+    keyType: "verifier";
+}
+/**
+ * Locator for a translation key, which requires additional record information.
+ *
+ * @property {string} recordName - The name of the record associated with the translation key.
+ * @property {number} recordInputPosition - The position of the record input in the function signature.
+ */
+export interface TranslationKeyLocator extends BaseFunctionKeyLocator {
+    keyType: "translation";
+    recordName: string;
+    recordInputPosition: number;
+}
+/**
+ * A locator that uniquely identifies a function's proving, verifying, or translation key.
+ * Discriminated on the {@link KeyType} field.
+ *
+ * @example
+ * const prover: KeyLocator = { program: "credits.aleo", functionName: "transfer_private", edition: 1, amendment: 0, network: "mainnet", keyType: "prover" };
+ * const verifier: KeyLocator = { program: "credits.aleo", functionName: "transfer_private", edition: 1, amendment: 0, network: "mainnet", keyType: "verifier" };
+ */
+export type KeyLocator = ProvingKeyLocator | VerifyingKeyLocator | TranslationKeyLocator;
+/**
+ * Creates a {@link ProvingKeyLocator}.
+ *
+ * @param {string} program - The program name (e.g. "credits.aleo").
+ * @param {string} functionName - The function name (e.g. "transfer_private").
+ * @param {number} [edition=1] - The program edition.
+ * @param {number} [amendment=0] - The program amendment.
+ * @param {string} [network] - The network name. Defaults to the build-time network.
+ * @param {string} [checksum] - Optional SHA-256 checksum for key verification.
+ * @returns {ProvingKeyLocator}
+ */
+export declare function provingKeyLocator(program: string, functionName: string, edition?: number, amendment?: number, network?: string, checksum?: string): ProvingKeyLocator;
+/**
+ * Creates a {@link VerifyingKeyLocator}.
+ *
+ * @param {string} program - The program name (e.g. "credits.aleo").
+ * @param {string} functionName - The function name (e.g. "transfer_private").
+ * @param {number} [edition=1] - The program edition.
+ * @param {number} [amendment=0] - The program amendment.
+ * @param {string} [network] - The network name. Defaults to the build-time network.
+ * @param {string} [checksum] - Optional SHA-256 checksum for key verification.
+ * @returns {VerifyingKeyLocator}
+ */
+export declare function verifyingKeyLocator(program: string, functionName: string, edition?: number, amendment?: number, network?: string, checksum?: string): VerifyingKeyLocator;
+/**
+ * Creates a {@link TranslationKeyLocator}.
+ *
+ * @param {string} program - The program name (e.g. "credits.aleo").
+ * @param {string} functionName - The function name (e.g. "transfer_private").
+ * @param {string} recordName - The record name associated with the translation key.
+ * @param {number} recordInputPosition - The record input position in the function signature.
+ * @param {number} [edition=1] - The program edition.
+ * @param {number} [amendment=0] - The program amendment.
+ * @param {string} [network] - The network name. Defaults to the build-time network.
+ * @param {string} [checksum] - Optional SHA-256 checksum for key verification.
+ * @returns {TranslationKeyLocator}
+ */
+export declare function translationKeyLocator(program: string, functionName: string, recordName: string, recordInputPosition: number, edition?: number, amendment?: number, network?: string, checksum?: string): TranslationKeyLocator;
+export interface KeyStore {
+    /**
+     * Returns the raw bytes of a key for a given locator.
+     *
+     * @param {KeyLocator} locator The unique locator for the desired key.
+     * @returns {Promise<Uint8Array | null>} The raw key bytes if they exist, or null if not found.
+     */
+    getKeyBytes(locator: KeyLocator): Promise<Uint8Array | null>;
+    /**
+     * Returns the `ProvingKey` for a given locator.
+     *
+     * @param {ProvingKeyLocator} locator The unique locator for the desired `ProvingKey`.
+     * @returns {Promise<ProvingKey | null>} Returns the `ProvingKey` for the given locator if it exists or null if it does not.
+     */
+    getProvingKey(locator: ProvingKeyLocator): Promise<ProvingKey | null>;
+    /**
+     * Returns the `VerifyingKey` for a given locator.
+     *
+     * @param {VerifyingKeyLocator} locator The unique locator for the desired `VerifyingKey`.
+     * @returns {Promise<VerifyingKey | null>} Returns the `VerifyingKey` for the given locator if it exists or null if it does not exist.
+     */
+    getVerifyingKey(locator: VerifyingKeyLocator): Promise<VerifyingKey | null>;
+    /**
+     * Stores proving and verifying keys in key storage.
+     *
+     * @param {ProvingKeyLocator} proverLocator The locator for the proving key.
+     * @param {VerifyingKeyLocator} verifierLocator The locator for the verifying key.
+     * @param {FunctionKeyPair} keys The proving and verifying keys.
+     */
+    setKeys(proverLocator: ProvingKeyLocator, verifierLocator: VerifyingKeyLocator, keys: FunctionKeyPair): Promise<void>;
+    /**
+     * Store a raw key in storage along with its fingerprint metadata for future verification.
+     *
+     * @param {Uint8Array} keyBytes The raw key bytes.
+     * @param {KeyLocator} locator The unique locator for the desired key.
+     * @returns {Promise<void>}
+     */
+    setKeyBytes(keyBytes: Uint8Array, locator: KeyLocator): Promise<void>;
+    /**
+     * Returns stored metadata for a key, if any.
+     *
+     * @param {KeyLocator} locator The unique locator for the key.
+     * @returns {Promise<KeyFingerprint | null>} The stored fingerprint for that key, or null if none exists.
+     */
+    getKeyMetadata(locator: KeyLocator): Promise<KeyFingerprint | null>;
+    /**
+     * Determines if a given key exists or not.
+     *
+     * @param {KeyLocator} locator The unique locator for the key.
+     * @returns {Promise<boolean>} True if the key exists, false otherwise.
+     */
+    has(locator: KeyLocator): Promise<boolean>;
+    /**
+     * Deletes a key and its metadata corresponding to a given locator.
+     *
+     * @param {KeyLocator} locator The unique locator for the key.
+     * @returns {Promise<void>}
+     */
+    delete(locator: KeyLocator): Promise<void>;
+    /**
+     * Clears all keys in the keystore.
+     */
+    clear(): Promise<void>;
+}