@provablehq/sdk 0.9.16 → 0.9.18

package/dist/mainnet/keys/keystore/error.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Reason code for invalid locator validation failures.
+ * - `"reserved_name"`: Locator is empty or the reserved name `"."` or `".."`.
+ * - `"path_traversal"`: Locator contains `..`.
+ * - `"path_separator"`: Locator contains a path separator (`/`, `\`) or null byte.
+ */
+export type InvalidLocatorReason = "reserved_name" | "path_traversal" | "path_separator";
+/**
+ * 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/mainnet/keys/keystore/file.d.ts

@@ -0,0 +1,217 @@
+import { FunctionKeyPair } from "../../models/keyPair.js";
+import { KeyFingerprint } from "../verifier/interface.js";
+import { KeyLocator, KeyStore } 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 that a locator is a safe filesystem identifier.
+     *
+     * @private
+     * @param {string} locator - Unique identifier used to derive a metadata file path.
+     * @throws {InvalidLocatorError} If the locator could cause path traversal.
+     */
+    private validateLocator;
+    /**
+     * 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 against a fingerprint.
+     *
+     * @param {KeyLocator} locator - Object containing a locator string for the key + optional fingerprint for verification.
+     * @returns {Promise<Uint8Array | null>} The key bytes if found and verified (if fingerprint provided), null if not found.
+     * @throws {KeyVerificationError} If fingerprint verification fails.
+     * @example
+     * const keyBytes = await getKeyBytes({
+     *   locator: 'transfer_private.prover.421e5a5',
+     *   fingerprint: { checksum: '421e5a52f01a1eeb068bbf56d15e19477ff7290e4b988d1013e15563f2b77801', size: 116746954 }
+     * });
+     * if (keyBytes) {
+     *   // Use the verified key bytes
+     * }
+     */
+    getKeyBytes(locator: KeyLocator): Promise<Uint8Array | null>;
+    /**
+     * Retrieves and verifies a proving key from storage.
+     *
+     * @param {KeyLocator} locator - Object containing the proving key location and optional fingerprint.
+     * @returns {Promise<ProvingKey | null>} The proving key if found and verified, null if not found.
+     * @throws {KeyVerificationError} If fingerprint verification fails.
+     * @throws {Error} If key bytes cannot be parsed into a valid ProvingKey.
+     *
+     * @example
+     * try {
+     *   const key = await getProvingKey({
+     *     locator: 'transfer_private.prover.421e5a5'
+     *   });
+     *   if (key) {
+     *     // Use the verified proving key
+     *   }
+     * } catch (err) {
+     *   if (err instanceof KeyVerificationError) {
+     *     // Handle verification failure.
+     *   } else {
+     *     // Handle key parsing error.
+     *   }
+     * }
+     */
+    getProvingKey(locator: KeyLocator): Promise<ProvingKey | null>;
+    /**
+     * Retrieves and verifies a verifying key from storage.
+     *
+     * @param {KeyLocator} locator - Object containing the verifying key location and optional fingerprint.
+     * @returns {Promise<VerifyingKey | null>} The verifying key if found and verified, null if not found.
+     * @throws {KeyVerificationError} If fingerprint verification fails.
+     * @throws {Error} If key bytes cannot be parsed into a valid VerifyingKey.
+     *
+     * @example
+     * try {
+     *   const key = await getVerifyingKey({
+     *     locator: 'transfer_private.verifier.4ac2f71'
+     *   });
+     *   if (key) {
+     *     // Use the verified verifying key
+     *   }
+     * } catch (err) {
+     *   if (err instanceof KeyVerificationError) {
+     *     // Handle verification failure.
+     *   } else {
+     *     // Handle key parsing error.
+     *   }
+     * }
+     */
+    getVerifyingKey(locator: KeyLocator): Promise<VerifyingKey | null>;
+    /**
+     * Stores proving and verifying keys in key storage.
+     *
+     * @param {KeyLocator} proverLocator The unique locator for the desired proving key.
+     * @param {KeyLocator} verifierLocator The unique locator for the desired verifying key.
+     * @param {FunctionKeyPair} keys The proving and verifying keys.
+     *
+     * @example
+     * const keys = await generateKeys();
+     * await setKeys(
+     *   { locator: 'transfer_private.prover' },
+     *   { locator: 'transfer_private.verifier' },
+     *   keys
+     * );
+     */
+    setKeys(proverLocator: KeyLocator, verifierLocator: KeyLocator, keys: FunctionKeyPair): Promise<void>;
+    /**
+     * Store a raw proving or verifying key in storage along with its fingerprint metadata for future verification.
+     *
+     * @param {Uint8Array} keyBytes The raw proving and verifying key bytes.
+     * @param {KeyLocator} locator The unique locator for the desired key pair.
+     * @returns {Promise<void>}
+     * @throws {Error} If computing key metadata or writing to storage fails
+     *
+     * @example
+     * const keys = await generateKeys();
+     * await setKeyBytes(keys.provingKey.toBytes(), { locator: 'transfer_private.prover' });
+     */
+    setKeyBytes(keyBytes: Uint8Array, locator: KeyLocator): Promise<void>;
+    /**
+     * Returns stored metadata for a key, if any.
+     *
+     * @param {string} locator The unique locator for the key.
+     * @returns {Promise<KeyFingerprint | null>} The stored fingerprint metadata for that locator, or null if none exists.
+     *
+     * @example
+     * const metadata = await getKeyMetadata('transfer_private.prover.421e5a5');
+     * if (metadata) {
+     *   // Use the stored metadata.
+     * }
+     */
+    getKeyMetadata(locator: string): Promise<KeyFingerprint | null>;
+    /**
+     * Checks if a key exists at the specified locator path.
+     *
+     * @param {string} locator - Unique identifier for the key location.
+     * @returns {Promise<boolean>} True if key exists at location, false otherwise.
+     *
+     * @example
+     * const exists = await has('transfer_private.prover.421e5a5');
+     * if (exists) {
+     *   // Key exists at location.
+     * } else {
+     *   // Key does not exist at location.
+     * }
+     */
+    has(locator: string): Promise<boolean>;
+    /**
+     * Deletes a key and its associated metadata from storage. Silently ignores errors if files don't exist.
+     *
+     * @param {string} locator - Unique identifier for the key to delete.
+     * @returns {Promise<void>}
+     *
+     * @example
+     * await delete('transfer_private.prover.421e5a5');
+     */
+    delete(locator: string): 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.
+     *
+     * @example
+     * await clear(); // Removes all files under the keystore directory.
+     */
+    clear(): Promise<void>;
+}

package/dist/mainnet/keys/keystore/interface.d.ts

@@ -0,0 +1,85 @@
+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";
+/**
+ * The key locator string and optional fingerprint to verify the integrity of the key.
+ *
+ * @property {string} locator - The unique identifier for the key.
+ * @property {KeyFingerprint} [fingerprint] - Optional fingerprint for verification.
+ */
+export interface KeyLocator {
+    locator: string;
+    fingerprint?: KeyFingerprint;
+}
+export interface KeyStore {
+    /**
+     * Returns the raw bytes of a proving or verifying 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 {KeyLocator} 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: KeyLocator): Promise<ProvingKey | null>;
+    /**
+     * Returns the `VerifyingKey` for a given locator.
+     *
+     * @param {KeyLocator} 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: KeyLocator): Promise<VerifyingKey | null>;
+    /**
+     * Stores proving and verifying keys in key storage.
+     *
+     * @param {KeyLocator} proverLocator The unique locator for the desired proving key.
+     * @param {KeyLocator} verifierLocator The unique locator for the desired verifying key.
+     * @param {FunctionKeyPair} keys The proving and verifying keys.
+     */
+    setKeys(proverLocator: KeyLocator, verifierLocator: KeyLocator, keys: FunctionKeyPair): Promise<void>;
+    /**
+     * Store a raw proving or verifying key in storage along with its fingerprint metadata for future verification.
+     *
+     * @param {Uint8Array} keyBytes The raw proving and verifying key bytes.
+     * @param {KeyLocator} locator The unique locator for the desired key pair.
+     * @returns {Promise<void>}
+     *
+     * @example
+     * const keys = await generateKeys();
+     * await setKeyBytes(keys.provingKey.toBytes(), { locator: 'transfer_private.prover' });
+     */
+    setKeyBytes(keyBytes: Uint8Array, locator: KeyLocator): Promise<void>;
+    /**
+     * Returns stored metadata for a key, if any.
+     *
+     * @param {string} locator The unique locator for the key.
+     * @returns {Promise<KeyFingerprint | null>} The stored fingerprint for that locator, or null if none exists.
+     */
+    getKeyMetadata(locator: string): Promise<KeyFingerprint | null>;
+    /**
+     * Determines if a given key exists or not.
+     *
+     * @param {string} locator The unique locator for the desired key.
+     * @returns {Promise<boolean>} True if the key exists, false otherwise.
+     */
+    has(locator: string): Promise<boolean>;
+    /**
+     * Deletes a key and its metadata corresponding to a given locator.
+     *
+     * @param {string} locator The unique locator for the desired key.
+     * @returns {Promise<void>}
+     */
+    delete(locator: string): Promise<void>;
+    /**
+     * Clears all keys in the keystore.
+     */
+    clear(): Promise<void>;
+}

package/dist/mainnet/keys/provider/interface.d.ts

@@ -0,0 +1,170 @@
+import { FunctionKeyPair } from "../../models/keyPair.js";
+import { KeyStore } from "../keystore/interface.js";
+/**
+ * Interface for key search parameters. This allows for arbitrary search parameters to be passed to key provider
+ * implementations.
+ */
+interface KeySearchParams {
+    [key: string]: any;
+}
+/**
+ * KeyProvider interface. Enables the retrieval of public proving and verifying keys for Aleo Programs.
+ */
+interface FunctionKeyProvider {
+    /**
+     * Get bond_public function keys from the credits.aleo program
+     *
+     * @returns {Promise<FunctionKeyPair>} Proving and verifying keys for the bond_public function
+     */
+    bondPublicKeys(): Promise<FunctionKeyPair>;
+    /**
+     * Get bond_validator function keys from the credits.aleo program
+     *
+     * @returns {Promise<FunctionKeyPair>} Proving and verifying keys for the bond_validator function
+     */
+    bondValidatorKeys(): Promise<FunctionKeyPair>;
+    /**
+     * Cache a set of keys. This will overwrite any existing keys with the same keyId. The user can check if a keyId
+     * exists in the cache using the containsKeys method prior to calling this method if overwriting is not desired.
+     *
+     * @param {string} keyId access key for the cache
+     * @param {FunctionKeyPair} keys keys to cache
+     */
+    cacheKeys(keyId: string, keys: FunctionKeyPair): void;
+    /**
+     * Get claim_unbond_public function keys from the credits.aleo program
+     *
+     * @returns {Promise<FunctionKeyPair>} Proving and verifying keys for the claim_unbond_public function
+     */
+    claimUnbondPublicKeys(): Promise<FunctionKeyPair>;
+    /**
+     * Get arbitrary function keys from a provider
+     *
+     * @param {KeySearchParams | undefined} params - Optional search parameters for the key provider
+     * @returns {Promise<FunctionKeyPair>} Proving and verifying keys for the specified program
+     *
+     * @example
+     * // Create a search object which implements the KeySearchParams interface
+     * class IndexDbSearch implements KeySearchParams {
+     *     db: string
+     *     keyId: string
+     *     constructor(params: {db: string, keyId: string}) {
+     *         this.db = params.db;
+     *         this.keyId = params.keyId;
+     *     }
+     * }
+     *
+     * // Create a new object which implements the KeyProvider interface
+     * class IndexDbKeyProvider implements FunctionKeyProvider {
+     *     async functionKeys(params: KeySearchParams): Promise<FunctionKeyPair> {
+     *         return new Promise((resolve, reject) => {
+     *             const request = indexedDB.open(params.db, 1);
+     *
+     *             request.onupgradeneeded = function(e) {
+     *                 const db = e.target.result;
+     *                 if (!db.objectStoreNames.contains('keys')) {
+     *                     db.createObjectStore('keys', { keyPath: 'id' });
+     *                 }
+     *             };
+     *
+     *             request.onsuccess = function(e) {
+     *                 const db = e.target.result;
+     *                 const transaction = db.transaction(["keys"], "readonly");
+     *                 const store = transaction.objectStore("keys");
+     *                 const request = store.get(params.keyId);
+     *                 request.onsuccess = function(e) {
+     *                     if (request.result) {
+     *                         resolve(request.result as FunctionKeyPair);
+     *                     } else {
+     *                         reject(new Error("Key not found"));
+     *                     }
+     *                 };
+     *                 request.onerror = function(e) { reject(new Error("Error fetching key")); };
+     *             };
+     *
+     *             request.onerror = function(e) { reject(new Error("Error opening database")); };
+     *         });
+     *     }
+     *
+     *     // implement the other methods...
+     * }
+     *
+     *
+     * const keyProvider = new AleoKeyProvider();
+     * const networkClient = new AleoNetworkClient("https://api.provable.com/v2");
+     * const recordProvider = new NetworkRecordProvider(account, networkClient);
+     *
+     * // Initialize a program manager with the key provider to automatically fetch keys for value transfers
+     * const programManager = new ProgramManager("https://api.provable.com/v2", keyProvider, recordProvider);
+     * programManager.transfer(1, "aleo166q6ww6688cug7qxwe7nhctjpymydwzy2h7rscfmatqmfwnjvggqcad0at", "public", 0.5);
+     *
+     * // Keys can also be fetched manually
+     * const searchParams = new IndexDbSearch({db: "keys", keyId: "credits.aleo:transferPrivate"});
+     * const [transferPrivateProvingKey, transferPrivateVerifyingKey] = await keyProvider.functionKeys(searchParams);
+     */
+    functionKeys(params?: KeySearchParams): Promise<FunctionKeyPair>;
+    /**
+     * Gets an object which implements the `KeyStore` interface for accessing proving and verifying
+     * keys directly from persistent storage.
+     *
+     * @returns {Promise<KeyStore | undefined>} The key store if available, or undefined.
+     */
+    keyStore(): Promise<KeyStore | undefined>;
+    /**
+     * Get fee_private function keys from the credits.aleo program
+     *
+     * @returns {Promise<FunctionKeyPair>} Proving and verifying keys for the fee_private function
+     */
+    feePrivateKeys(): Promise<FunctionKeyPair>;
+    /**
+     * Get fee_public function keys from the credits.aleo program
+     *
+     * @returns {Promise<FunctionKeyPair>} Proving and verifying keys for the fee_public function
+     */
+    feePublicKeys(): Promise<FunctionKeyPair>;
+    /**
+     * Get keys for the inclusion proof.
+     *
+     * @returns {Promise<FunctionKeyPair>} Proving and verifying keys for the inclusion proof
+     */
+    inclusionKeys(): Promise<FunctionKeyPair>;
+    /**
+     * Get join function keys from the credits.aleo program
+     *
+     * @returns {Promise<FunctionKeyPair>} Proving and verifying keys for the join function
+     */
+    joinKeys(): Promise<FunctionKeyPair>;
+    /**
+     * Get split function keys from the credits.aleo program
+     *
+     * @returns {Promise<FunctionKeyPair>} Proving and verifying keys for the split function
+     */
+    splitKeys(): Promise<FunctionKeyPair>;
+    /**
+     * Get keys for a variant of the transfer function from the credits.aleo program
+     *
+     * @param {string} visibility Visibility of the transfer function (private, public, privateToPublic, publicToPrivate)
+     * @returns {Promise<FunctionKeyPair>} Proving and verifying keys for the specified transfer function
+     *
+     * @example
+     * // Create a new object which implements the KeyProvider interface
+     * const networkClient = new AleoNetworkClient("https://api.provable.com/v2");
+     * const keyProvider = new AleoKeyProvider();
+     * const recordProvider = new NetworkRecordProvider(account, networkClient);
+     *
+     * // Initialize a program manager with the key provider to automatically fetch keys for value transfers
+     * const programManager = new ProgramManager("https://api.provable.com/v2", keyProvider, recordProvider);
+     * programManager.transfer(1, "aleo166q6ww6688cug7qxwe7nhctjpymydwzy2h7rscfmatqmfwnjvggqcad0at", "public", 0.5);
+     *
+     * // Keys can also be fetched manually
+     * const [transferPublicProvingKey, transferPublicVerifyingKey] = await keyProvider.transferKeys("public");
+     */
+    transferKeys(visibility: string): Promise<FunctionKeyPair>;
+    /**
+     * Get unbond_public function keys from the credits.aleo program
+     *
+     * @returns {Promise<FunctionKeyPair>} Proving and verifying keys for the unbond_public function
+     */
+    unBondPublicKeys(): Promise<FunctionKeyPair>;
+}
+export { FunctionKeyProvider, KeySearchParams };