@provablehq/sdk 0.9.16 → 0.9.17

package/dist/testnet/{function-key-provider.d.ts → keys/provider/memory.d.ts}

@@ -1,19 +1,13 @@
-import { Key } from "./constants.js";
-import { ProvingKey, VerifyingKey } from "./wasm.js";
-type FunctionKeyPair = [ProvingKey, VerifyingKey];
-type CachedKeyPair = [Uint8Array, Uint8Array];
+import { Key } from "../../constants.js";
+import { CachedKeyPair, FunctionKeyPair } from "../../models/keyPair.js";
+import { FunctionKeyProvider, KeySearchParams } from "./interface";
+import { ProvingKey, VerifyingKey } from "../../wasm.js";
+import { KeyStore } from "../keystore/interface.js";
 type AleoKeyProviderInitParams = {
     proverUri?: string;
     verifierUri?: string;
     cacheKey?: string;
 };
-/**
- * Interface for record search parameters. This allows for arbitrary search parameters to be passed to record provider
- * implementations.
- */
-interface KeySearchParams {
-    [key: string]: any;
-}
 /**
  * AleoKeyProviderParams search parameter for the AleoKeyProvider. It allows for the specification of a proverUri and
  * verifierUri to fetch keys via HTTP from a remote resource as well as a unique cacheKey to store the keys in memory.
@@ -39,161 +33,8 @@ declare class AleoKeyProviderParams implements KeySearchParams {
     });
 }
 /**
- * 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 unbond_public function keys from the credits.aleo program
-     *
-     * @returns {Promise<FunctionKeyPair>} Proving and verifying keys for the 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>;
-    /**
-     * Get fee_private function keys from the credits.aleo program
-     *
-     * @returns {Promise<FunctionKeyPair>} Proving and verifying keys for the join function
-     */
-    feePrivateKeys(): Promise<FunctionKeyPair>;
-    /**
-     * Get fee_public function keys from the credits.aleo program
-     *
-     * @returns {Promise<FunctionKeyPair>} Proving and verifying keys for the join function
-     */
-    feePublicKeys(): Promise<FunctionKeyPair>;
-    /**
-     * Get keys for the inclusion proof.
-     *
-     * @returns {Promise<FunctionKeyPair>} Proving and verifying keys for the join function
-     */
-    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 join 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 join function
-     */
-    unBondPublicKeys(): Promise<FunctionKeyPair>;
-}
-/**
- * AleoKeyProvider class. Implements the KeyProvider interface. Enables the retrieval of Aleo program proving and
- * verifying keys for the credits.aleo program over http from official Aleo sources and storing and retrieving function
+ * AleoKeyProvider class. Implements the FunctionKeyProvider interface. Enables the retrieval of Aleo program proving and
+ * verifying keys for the credits.aleo program over HTTP from official Aleo sources and storing and retrieving function
  * keys from a local memory cache.
  */
 declare class AleoKeyProvider implements FunctionKeyProvider {
@@ -202,6 +43,7 @@ declare class AleoKeyProvider implements FunctionKeyProvider {
     keyUris: string;
     fetchBytes(url?: string): Promise<Uint8Array>;
     constructor();
+    keyStore(): Promise<KeyStore | undefined>;
     /**
      * Use local memory to store keys
      *
@@ -364,4 +206,4 @@ declare class AleoKeyProvider implements FunctionKeyProvider {
     getVerifyingKey(verifierUri: string): Promise<VerifyingKey>;
     unBondPublicKeys(): Promise<FunctionKeyPair>;
 }
-export { AleoKeyProvider, AleoKeyProviderParams, AleoKeyProviderInitParams, CachedKeyPair, FunctionKeyPair, FunctionKeyProvider, KeySearchParams };
+export { AleoKeyProvider, AleoKeyProviderInitParams, AleoKeyProviderParams };

package/dist/testnet/{offline-key-provider.d.ts → keys/provider/offline.d.ts}

@@ -1,5 +1,7 @@
-import { CachedKeyPair, FunctionKeyPair, FunctionKeyProvider, KeySearchParams } from "./function-key-provider.js";
-import { ProvingKey, VerifyingKey } from "./wasm.js";
+import { FunctionKeyProvider, KeySearchParams } from "./interface.js";
+import { CachedKeyPair, FunctionKeyPair } from "../../models/keyPair.js";
+import { ProvingKey, VerifyingKey } from "../../wasm.js";
+import { KeyStore } from "../keystore/interface.js";
 /**
  * Search parameters for the offline key provider. This class implements the KeySearchParams interface and includes
  * a convenience method for creating a new instance of this class for each function of the credits.aleo program.
@@ -32,7 +34,7 @@ declare class OfflineSearchParams implements KeySearchParams {
      */
     static bondValidatorKeyParams(): OfflineSearchParams;
     /**
-     * Create a new OfflineSearchParams instance for the claim_unbond_public function of the
+     * Create a new OfflineSearchParams instance for the claim_unbond_public function of the credits.aleo program.
      */
     static claimUnbondPublicKeyParams(): OfflineSearchParams;
     /**
@@ -138,6 +140,7 @@ declare class OfflineSearchParams implements KeySearchParams {
 declare class OfflineKeyProvider implements FunctionKeyProvider {
     cache: Map<string, CachedKeyPair>;
     constructor();
+    keyStore(): Promise<KeyStore | undefined>;
     /**
      * Get bond_public function keys from the credits.aleo program. The keys must be cached prior to calling this
      * method for it to work.

package/dist/testnet/keys/verifier/interface.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Fingerprint for a proving and verifying key that includes the checksum of the bytes and size in number of bytes.
+ *
+ * @property {string} checksum - SHA-256 checksum of the key bytes.
+ * @property {number} size - Size of the key in number of bytes.
+ */
+export interface KeyFingerprint {
+    checksum: string;
+    size: number;
+}
+/**
+ * Options for verifying the integrity of proving and verifying keys. An identifier to allow the interface to find key metadata and/or the desired metadata to verify must be passed in.
+ *
+ * @property {Uint8Array} keyBytes - The raw bytes of the cryptographic key.
+ * @property {string} [locator] - Optional identifier or path indicating where the key or KeyFingerprint might be stored.
+ * @property {KeyFingerprint} [fingerprint] - Optional metadata containing the key's expected checksum and size for verification purposes.
+ */
+export interface KeyMetadata {
+    keyBytes: Uint8Array;
+    locator?: string;
+    fingerprint?: KeyFingerprint;
+}
+/**
+ * Error thrown when there is a mismatch between expected and actual key metadata.
+ * This can occur during verification of either the checksum or size of a key.
+ *
+ * @extends Error
+ */
+export declare class KeyVerificationError extends Error {
+    readonly locator: string;
+    readonly field: "checksum" | "size";
+    readonly expected: string;
+    readonly actual: string;
+    /**
+     * Creates a new KeyVerificationError instance (error.name is "ChecksumMismatchError").
+     *
+     * @param {string} locator - The key locator where the mismatch occurred.
+     * @param {"checksum" | "size"} field - The field that failed verification (either "checksum" or "size").
+     * @param {string} expected - The expected value of the field.
+     * @param {string} actual - The actual value encountered.
+     */
+    constructor(locator: string, field: "checksum" | "size", expected: string, actual: string);
+}
+/**
+ * Computes the SHA-256 checksum of a given set of bytes.
+ *
+ * @param {Uint8Array} bytes - The bytes to compute the checksum of.
+ */
+export declare function sha256Hex(bytes: Uint8Array): Promise<string>;
+/**
+ * Verifies key-pair metadata (checksums and sizes) against raw bytes in order to ensure the correct keypair is used.
+ * Implementations throw {@link KeyVerificationError} when verification fails.
+ */
+export interface KeyVerifier {
+    /**
+     * Computes and optionally stores key metadata. If keyFingerprint is provided, verifies against it.
+     * @param {KeyMetadata} keyMetadata - Object containing key bytes and optional verification data.
+     * @throws {KeyVerificationError} When provided keyFingerprint doesn't match computed values.
+     * @returns {Promise<KeyFingerprint>} Computed key metadata.
+     */
+    computeKeyMetadata(keyMetadata: KeyMetadata): Promise<KeyFingerprint>;
+    /**
+     * Verifies prover bytes against key metadata (size + checksum).
+     *
+     * @param {KeyMetadata} keyMetadata - Object containing the key bytes, an optional locator and optional metadata for verification.
+     * @throws {KeyVerificationError} when size or checksum does not match.
+     * @returns {Promise<void>} Promise that resolves when verification succeeds.
+     */
+    verifyKeyBytes(keyMetadata: KeyMetadata): Promise<void>;
+}

package/dist/testnet/keys/verifier/memory.d.ts

@@ -0,0 +1,37 @@
+import { KeyVerifier, KeyFingerprint, KeyMetadata } from "./interface";
+/**
+ * In-memory implementation of KeyVerifier that stores and verifies key fingerprints.
+ * Provides functionality to compute and verify cryptographic checksums of keys, storing them
+ * in memory for subsequent verification. This implementation is primarily used for testing
+ * and development purposes where persistence is not required.
+ *
+ * Key features:
+ * - Computes SHA-256 checksums and sizes for key bytes.
+ * - Stores key fingerprints in memory using string locators.
+ * - Verifies key bytes against stored or provided fingerprints.
+ *
+ * @implements {KeyVerifier}
+ */
+export declare class MemKeyVerifier implements KeyVerifier {
+    private keyStore;
+    /**
+     * Computes and optionally stores key metadata. If a keyFingerprint is provided, this function will verify the computed checksum against it before storing it.
+     *
+     * @param {KeyMetadata} keyMetadata - Object containing key bytes and optional verification data.
+     * @throws {KeyVerificationError} When provided keyFingerprint doesn't match computed values.
+     * @returns {Promise<KeyFingerprint>} Computed key metadata.
+     */
+    computeKeyMetadata(keyMetadata: KeyMetadata): Promise<KeyFingerprint>;
+    /**
+     * Verifies key bytes against stored or provided metadata. Follows a priority verification scheme:
+     * 1. If KeyFingerprint is provided in the metadata, this method verifies against that first.
+     * 2. If a locator is provided, attempts to verify against stored fingerprint.
+     * 3. If neither is available, throws an error.
+     *
+     * @param {KeyMetadata} keyMetadata - Object containing the key bytes and optional verification metadata.
+     * @throws {Error} When neither fingerprint nor valid locator is provided for verification.
+     * @throws {KeyVerificationError} When size or checksum verification fails.
+     * @returns {Promise<void>} Promise that resolves when verification succeeds.
+     */
+    verifyKeyBytes(keyMetadata: KeyMetadata): Promise<void>;
+}

package/dist/testnet/models/keyPair.d.ts

@@ -0,0 +1,4 @@
+import { ProvingKey, VerifyingKey } from "../wasm.js";
+type FunctionKeyPair = [ProvingKey, VerifyingKey];
+type CachedKeyPair = [Uint8Array, Uint8Array];
+export { CachedKeyPair, FunctionKeyPair };

package/dist/testnet/models/record-scanner/error.d.ts

@@ -23,7 +23,7 @@ export declare class RecordNotFoundError extends Error {
     readonly filter?: OwnedFilter;
     constructor(message: string, filter?: OwnedFilter);
 }
-/** Error thrown when a record scanner request fails due to an invalid response. */
+/** Error thrown when no UUID is configured, the UUID is invalid, or a record scanner request fails due to an invalid UUID/response. */
 export declare class UUIDError extends Error {
     readonly uuid?: string;
     readonly filter?: OwnedFilter;

package/dist/testnet/models/record-scanner/revokeResult.d.ts

@@ -0,0 +1,17 @@
+import type { RecordScannerFailure } from "./error.js";
+/**
+ * Response from the record scanning service's revoke endpoint on success.
+ *
+ * @example
+ * const revokeResponse: RevokeResponse = { status: "OK" };
+ */
+export interface RevokeResponse {
+    status: string;
+}
+/** Success variant of revoke result. */
+export interface RevokeSuccess {
+    ok: true;
+    data: RevokeResponse;
+}
+/** Result of revoke(); never throws on HTTP error. */
+export type RevokeResult = RevokeSuccess | RecordScannerFailure;

package/dist/testnet/node.d.ts

@@ -1,2 +1,3 @@
 import "./node-polyfill.js";
+export { LocalFileKeyStore } from "./keys/keystore/file.js";
 export * from "./browser.js";