@provablehq/sdk 0.10.0 → 0.10.2-rc.1

package/dist/testnet/browser.js

@@ -1,9 +1,360 @@
 import 'core-js/proposals/json-parse-with-source.js';
-import { ViewKey, ComputeKey, Address, PrivateKeyCiphertext, PrivateKey, RecordCiphertext, EncryptionToolkit, Group, Metadata, VerifyingKey, Program, Plaintext, Transaction, ProvingRequest, ProvingKey, RecordPlaintext, Field, Poseidon4, ProgramManager as ProgramManager$1, ExecutionRequest, verifyFunctionExecution, Value, Proof, Signature } from '@provablehq/wasm/testnet.js';
-export { Address, Authorization, BHP1024, BHP256, BHP512, BHP768, Boolean, Ciphertext, ComputeKey, EncryptionToolkit, ExecutionRequest, ExecutionResponse, Field, Execution as FunctionExecution, GraphKey, Group, I128, I16, I32, I64, I8, OfflineQuery, Pedersen128, Pedersen64, Plaintext, Poseidon2, Poseidon4, Poseidon8, PrivateKey, PrivateKeyCiphertext, Program, ProgramManager as ProgramManagerBase, Proof, ProvingKey, ProvingRequest, RecordCiphertext, RecordPlaintext, Scalar, Signature, Transaction, Transition, U128, U16, U32, U64, U8, Value, VerifyingKey, ViewKey, getOrInitConsensusVersionTestHeights, initThreadPool, snarkVerify, snarkVerifyBatch, stringToField, verifyFunctionExecution } from '@provablehq/wasm/testnet.js';
+import { ProvingKey, VerifyingKey, ViewKey, ComputeKey, Address, PrivateKeyCiphertext, PrivateKey, RecordCiphertext, EncryptionToolkit, Group, Metadata, Program, Plaintext, Transaction, ProvingRequest, RecordPlaintext, Field, Poseidon4, ProgramImports, ProgramManager as ProgramManager$1, ExecutionRequest, stringToField, verifyFunctionExecution, Value, Proof, Signature } from '@provablehq/wasm/testnet.js';
+export { Address, Authorization, BHP1024, BHP256, BHP512, BHP768, Boolean, Ciphertext, ComputeKey, DynamicRecord, EncryptionToolkit, ExecutionRequest, ExecutionResponse, Field, Execution as FunctionExecution, GraphKey, Group, I128, I16, I32, I64, I8, OfflineQuery, Pedersen128, Pedersen64, Plaintext, Poseidon2, Poseidon4, Poseidon8, PrivateKey, PrivateKeyCiphertext, Program, ProgramImports as ProgramImportsBuilder, ProgramManager as ProgramManagerBase, Proof, ProvingKey, ProvingRequest, RecordCiphertext, RecordPlaintext, Scalar, Signature, Transaction, Transition, U128, U16, U32, U64, U8, Value, VerifyingKey, ViewKey, getOrInitConsensusVersionTestHeights, initThreadPool, snarkVerify, snarkVerifyBatch, stringToField, verifyFunctionExecution } from '@provablehq/wasm/testnet.js';
 import sodium from 'libsodium-wrappers';
 import { bech32m } from '@scure/base';
 
+/**
+ * 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
+ */
+class InvalidLocatorError extends Error {
+    locator;
+    reason;
+    /**
+     * @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, locator, reason) {
+        super(message);
+        this.locator = locator;
+        this.reason = reason;
+        this.name = "InvalidLocatorError";
+        Object.setPrototypeOf(this, InvalidLocatorError.prototype);
+    }
+}
+
+/**
+ * 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
+ */
+class KeyVerificationError extends Error {
+    locator;
+    field;
+    expected;
+    actual;
+    /**
+     * 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, field, expected, actual) {
+        super(`Key verification ${locator} ${field} mismatch: expected ${expected}, got ${actual}`);
+        this.locator = locator;
+        this.field = field;
+        this.expected = expected;
+        this.actual = actual;
+        this.name = "ChecksumMismatchError";
+        Object.setPrototypeOf(this, KeyVerificationError.prototype);
+    }
+}
+/**
+ * Computes the SHA-256 checksum of a given set of bytes.
+ *
+ * @param {Uint8Array} bytes - The bytes to compute the checksum of.
+ */
+async function sha256Hex(bytes) {
+    const hash = await crypto.subtle.digest("SHA-256", bytes);
+    return Array.from(new Uint8Array(hash))
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+
+/**
+ * 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}
+ */
+class MemKeyVerifier {
+    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.
+     */
+    async computeKeyMetadata(keyMetadata) {
+        // Compute the metadata from the key bytes
+        const computedFingerprint = {
+            checksum: await sha256Hex(keyMetadata.keyBytes),
+            size: keyMetadata.keyBytes.length
+        };
+        // If a KeyFingerprint is provided, verify it matches computed values.
+        if (keyMetadata.fingerprint) {
+            if (keyMetadata.fingerprint.size !== computedFingerprint.size) {
+                throw new KeyVerificationError(keyMetadata.locator ? keyMetadata.locator : "", "size", String(keyMetadata.fingerprint.size), String(computedFingerprint.size));
+            }
+            if (keyMetadata.fingerprint.checksum !== computedFingerprint.checksum) {
+                throw new KeyVerificationError(keyMetadata.locator ? keyMetadata.locator : "", "checksum", keyMetadata.fingerprint.checksum, computedFingerprint.checksum);
+            }
+        }
+        // If locator is provided, store only the fingerprint
+        if (keyMetadata.locator) {
+            this.keyStore[keyMetadata.locator] = computedFingerprint;
+        }
+        return computedFingerprint;
+    }
+    /**
+     * 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.
+     */
+    async verifyKeyBytes(keyMetadata) {
+        if (!keyMetadata.keyBytes) {
+            throw new Error("Key bytes must be provided for verification.");
+        }
+        // Compute the fingerprint for the provided bytes.
+        const computedFingerprint = await this.computeKeyMetadata({
+            keyBytes: keyMetadata.keyBytes
+        });
+        // Determine which fingerprint to verify against.
+        let fingerprintToVerify;
+        if (keyMetadata.fingerprint) {
+            // If a key fingerprint is provided, use it.
+            fingerprintToVerify = keyMetadata.fingerprint;
+        }
+        else if (keyMetadata.locator) {
+            // Otherwise try to get stored fingerprint by locator.
+            fingerprintToVerify = this.keyStore[keyMetadata.locator];
+        }
+        if (!fingerprintToVerify) {
+            throw new Error("Either fingerprint or a valid locator must be provided for verification.");
+        }
+        // Verify the key size.
+        if (fingerprintToVerify.size !== computedFingerprint.size) {
+            throw new KeyVerificationError(keyMetadata.locator || "", "size", String(fingerprintToVerify.size), String(computedFingerprint.size));
+        }
+        // Verify the key checksum.
+        if (fingerprintToVerify.checksum !== computedFingerprint.checksum) {
+            throw new KeyVerificationError(keyMetadata.locator || "", "checksum", fingerprintToVerify.checksum, computedFingerprint.checksum);
+        }
+    }
+}
+
+/**
+ * Browser-compatible {@link KeyStore} backed by IndexedDB.
+ *
+ * This is the browser counterpart to {@link LocalFileKeyStore} (which requires Node.js `fs`).
+ * It persists proving and verifying keys across page reloads and browser sessions using the
+ * IndexedDB API available in all modern browsers and Web Workers.
+ *
+ * @example
+ * ```ts
+ * import { IndexedDBKeyStore, ProgramManager } from "@provablehq/sdk";
+ *
+ * const keyStore = new IndexedDBKeyStore();
+ * const pm = new ProgramManager();
+ * pm.setKeyStore(keyStore);
+ * // Keys synthesized during execution are now cached in IndexedDB
+ * // and reloaded automatically on subsequent runs.
+ * ```
+ */
+class IndexedDBKeyStore {
+    dbName;
+    storeName = "keys";
+    keyVerifier = new MemKeyVerifier();
+    dbPromise = null;
+    /**
+     * @param dbName IndexedDB database name. Defaults to `"aleo-keystore"`.
+     */
+    constructor(dbName = "aleo-keystore") {
+        this.dbName = dbName;
+    }
+    // -------------------------------------------------------
+    // IndexedDB helpers
+    // -------------------------------------------------------
+    /** Opens (or creates) the database, returning a cached promise. */
+    openDB() {
+        if (this.dbPromise)
+            return this.dbPromise;
+        this.dbPromise = new Promise((resolve, reject) => {
+            const request = indexedDB.open(this.dbName, 1);
+            request.onupgradeneeded = () => {
+                const db = request.result;
+                if (!db.objectStoreNames.contains(this.storeName)) {
+                    db.createObjectStore(this.storeName, { keyPath: "locator" });
+                }
+            };
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => {
+                this.dbPromise = null;
+                reject(request.error);
+            };
+            request.onblocked = () => {
+                this.dbPromise = null;
+                reject(new DOMException("Database open blocked", "AbortError"));
+            };
+        });
+        return this.dbPromise;
+    }
+    /** Runs a single read-write transaction and returns the request result. */
+    async tx(mode, fn) {
+        const db = await this.openDB();
+        return new Promise((resolve, reject) => {
+            const txn = db.transaction(this.storeName, mode);
+            const store = txn.objectStore(this.storeName);
+            const req = fn(store);
+            let result;
+            req.onsuccess = () => { result = req.result; };
+            txn.oncomplete = () => resolve(result);
+            txn.onerror = () => reject(txn.error);
+            txn.onabort = () => reject(txn.error ?? new DOMException("Transaction aborted", "AbortError"));
+        });
+    }
+    // -------------------------------------------------------
+    // Locator serialization (mirrors LocalFileKeyStore)
+    // -------------------------------------------------------
+    validateComponent(value, label) {
+        if (value === "" || value === ".") {
+            throw new InvalidLocatorError(`KeyLocator ${label} must not be empty or "." (got "${value}")`, value, "reserved_name");
+        }
+        if (value.includes("..")) {
+            throw new InvalidLocatorError(`KeyLocator ${label} must not contain ".." (got "${value}")`, value, "path_traversal");
+        }
+        if (value.includes("/") || value.includes("\\") || value.includes("\0")) {
+            throw new InvalidLocatorError(`KeyLocator ${label} must not contain path separators or null bytes (got "${value}")`, value, "path_separator");
+        }
+    }
+    validateNonNegative(value, label) {
+        if (!Number.isInteger(value) || value < 0) {
+            throw new InvalidLocatorError(`KeyLocator ${label} must be a non-negative integer (got ${value})`, String(value), "negative_value");
+        }
+    }
+    serializeLocator(locator) {
+        this.validateComponent(locator.program, "program");
+        this.validateComponent(locator.functionName, "functionName");
+        this.validateComponent(locator.network, "network");
+        this.validateNonNegative(locator.edition, "edition");
+        this.validateNonNegative(locator.amendment, "amendment");
+        const base = `${locator.program}.${locator.functionName}.e${locator.edition}.a${locator.amendment}.${locator.network}.${locator.keyType}`;
+        if (locator.keyType === "translation") {
+            this.validateComponent(locator.recordName, "recordName");
+            this.validateNonNegative(locator.recordInputPosition, "recordInputPosition");
+            return `${base}.${locator.recordName}.${locator.recordInputPosition}`;
+        }
+        return base;
+    }
+    checksumToFingerprint(checksum, keyBytes) {
+        if (!checksum)
+            return undefined;
+        return { checksum, size: keyBytes.length };
+    }
+    // -------------------------------------------------------
+    // KeyStore interface
+    // -------------------------------------------------------
+    async getKeyBytes(locator) {
+        const key = this.serializeLocator(locator);
+        const record = await this.tx("readonly", (store) => store.get(key));
+        if (!record)
+            return null;
+        const fingerprint = this.checksumToFingerprint(locator.checksum, record.bytes) ?? record.metadata;
+        if (fingerprint) {
+            await this.keyVerifier.verifyKeyBytes({
+                keyBytes: record.bytes,
+                locator: key,
+                fingerprint,
+            });
+        }
+        return record.bytes;
+    }
+    async getProvingKey(locator) {
+        const bytes = await this.getKeyBytes(locator);
+        if (!bytes)
+            return null;
+        return ProvingKey.fromBytes(bytes);
+    }
+    async getVerifyingKey(locator) {
+        const bytes = await this.getKeyBytes(locator);
+        if (!bytes)
+            return null;
+        return VerifyingKey.fromBytes(bytes);
+    }
+    async setKeys(proverLocator, verifierLocator, keys) {
+        const proverKey = this.serializeLocator(proverLocator);
+        const verifierKey = this.serializeLocator(verifierLocator);
+        const [provingKey, verifyingKey] = keys;
+        const [provingKeyBytes, verifyingKeyBytes] = [
+            provingKey.toBytes(),
+            verifyingKey.toBytes(),
+        ];
+        const [proverFingerprint, verifierFingerprint] = await Promise.all([
+            this.keyVerifier.computeKeyMetadata({
+                keyBytes: provingKeyBytes,
+                locator: proverKey,
+                fingerprint: this.checksumToFingerprint(proverLocator.checksum, provingKeyBytes),
+            }),
+            this.keyVerifier.computeKeyMetadata({
+                keyBytes: verifyingKeyBytes,
+                locator: verifierKey,
+                fingerprint: this.checksumToFingerprint(verifierLocator.checksum, verifyingKeyBytes),
+            }),
+        ]);
+        const proverRecord = { locator: proverKey, bytes: provingKeyBytes, metadata: proverFingerprint };
+        const verifierRecord = { locator: verifierKey, bytes: verifyingKeyBytes, metadata: verifierFingerprint };
+        // Write both in a single transaction for atomicity.
+        const db = await this.openDB();
+        await new Promise((resolve, reject) => {
+            const txn = db.transaction(this.storeName, "readwrite");
+            const store = txn.objectStore(this.storeName);
+            store.put(proverRecord);
+            store.put(verifierRecord);
+            txn.oncomplete = () => resolve();
+            txn.onerror = () => reject(txn.error);
+            txn.onabort = () => reject(txn.error ?? new DOMException("Transaction aborted", "AbortError"));
+        });
+    }
+    async setKeyBytes(keyBytes, locator) {
+        const key = this.serializeLocator(locator);
+        const computedMetadata = await this.keyVerifier.computeKeyMetadata({
+            keyBytes,
+            locator: key,
+            fingerprint: this.checksumToFingerprint(locator.checksum, keyBytes),
+        });
+        const record = { locator: key, bytes: keyBytes, metadata: computedMetadata };
+        await this.tx("readwrite", (store) => store.put(record));
+    }
+    async getKeyMetadata(locator) {
+        const key = this.serializeLocator(locator);
+        const record = await this.tx("readonly", (store) => store.get(key));
+        return record?.metadata ?? null;
+    }
+    async has(locator) {
+        const key = this.serializeLocator(locator);
+        const count = await this.tx("readonly", (store) => store.count(IDBKeyRange.only(key)));
+        return count > 0;
+    }
+    async delete(locator) {
+        const key = this.serializeLocator(locator);
+        await this.tx("readwrite", (store) => store.delete(key));
+    }
+    async clear() {
+        await this.tx("readwrite", (store) => store.clear());
+    }
+}
+
 await sodium.ready;
 /**
  * Encrypt an authorization with a libsodium cryptobox public key.
@@ -849,7 +1200,7 @@ class AleoNetworkClient {
             else {
                 this.headers = {
                     // This is replaced by the actual version by a Rollup plugin
-                    "X-Aleo-SDK-Version": "0.10.0",
+                    "X-Aleo-SDK-Version": "0.10.2-rc.1",
                     "X-Aleo-environment": environment(),
                 };
             }
@@ -865,7 +1216,7 @@ class AleoNetworkClient {
         else {
             this.headers = {
                 // This is replaced by the actual version by a Rollup plugin
-                "X-Aleo-SDK-Version": "0.10.0",
+                "X-Aleo-SDK-Version": "0.10.2-rc.1",
                 "X-Aleo-environment": environment(),
             };
         }
@@ -1679,6 +2030,30 @@ class AleoNetworkClient {
             this.ctx = {};
         }
     }
+    /**
+     * Returns the current edition and amendment count for a program.
+     *
+     * @param {string} programId - The program ID (e.g. "hello_hello.aleo")
+     * @returns {{ program_id: string, edition: number, amendment_count: number }}
+     *
+     * @example
+     * const networkClient = new AleoNetworkClient("https://api.provable.com/v2");
+     * const info = await networkClient.getProgramAmendmentCount("hello_hello.aleo");
+     * console.log(info.edition, info.amendment_count);
+     */
+    async getProgramAmendmentCount(programId) {
+        try {
+            this.ctx = { "X-ALEO-METHOD": "getProgramAmendmentCount" };
+            const raw = await this.fetchRaw("/programs/" + programId + "/amendment_count");
+            return JSON.parse(raw);
+        }
+        catch (error) {
+            throw new Error(`Error fetching amendment count for ${programId}: ${error}`);
+        }
+        finally {
+            this.ctx = {};
+        }
+    }
     /**
      * Returns a program object from a program ID or program source code.
      *
@@ -2969,189 +3344,39 @@ class AleoKeyProvider {
             case CREDITS_PROGRAM_KEYS.set_validator_state.verifier:
                 return CREDITS_PROGRAM_KEYS.set_validator_state.verifyingKey();
             case CREDITS_PROGRAM_KEYS.split.verifier:
-                return CREDITS_PROGRAM_KEYS.split.verifyingKey();
-            case CREDITS_PROGRAM_KEYS.transfer_private.verifier:
-                return CREDITS_PROGRAM_KEYS.transfer_private.verifyingKey();
-            case CREDITS_PROGRAM_KEYS.transfer_private_to_public.verifier:
-                return CREDITS_PROGRAM_KEYS.transfer_private_to_public.verifyingKey();
-            case CREDITS_PROGRAM_KEYS.transfer_public.verifier:
-                return CREDITS_PROGRAM_KEYS.transfer_public.verifyingKey();
-            case CREDITS_PROGRAM_KEYS.transfer_public_as_signer.verifier:
-                return CREDITS_PROGRAM_KEYS.transfer_public_as_signer.verifyingKey();
-            case CREDITS_PROGRAM_KEYS.transfer_public_to_private.verifier:
-                return CREDITS_PROGRAM_KEYS.transfer_public_to_private.verifyingKey();
-            case CREDITS_PROGRAM_KEYS.unbond_public.verifier:
-                return CREDITS_PROGRAM_KEYS.unbond_public.verifyingKey();
-            default:
-                try {
-                    /// Try to fetch the verifying key from the network as a string
-                    const response = await get(verifierUri);
-                    const text = await response.text();
-                    return VerifyingKey.fromString(text);
-                }
-                catch (e) {
-                    /// If that fails, try to fetch the verifying key from the network as bytes
-                    try {
-                        return (VerifyingKey.fromBytes(await this.fetchBytes(verifierUri)));
-                    }
-                    catch (inner) {
-                        throw new Error("Invalid verifying key. Error: " + inner.message);
-                    }
-                }
-        }
-    }
-    unBondPublicKeys() {
-        return this.fetchCreditsKeys(CREDITS_PROGRAM_KEYS.unbond_public);
-    }
-}
-
-/**
- * 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
- */
-class KeyVerificationError extends Error {
-    locator;
-    field;
-    expected;
-    actual;
-    /**
-     * 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, field, expected, actual) {
-        super(`Key verification ${locator} ${field} mismatch: expected ${expected}, got ${actual}`);
-        this.locator = locator;
-        this.field = field;
-        this.expected = expected;
-        this.actual = actual;
-        this.name = "ChecksumMismatchError";
-        Object.setPrototypeOf(this, KeyVerificationError.prototype);
-    }
-}
-/**
- * Computes the SHA-256 checksum of a given set of bytes.
- *
- * @param {Uint8Array} bytes - The bytes to compute the checksum of.
- */
-async function sha256Hex(bytes) {
-    const hash = await crypto.subtle.digest("SHA-256", bytes);
-    return Array.from(new Uint8Array(hash))
-        .map((b) => b.toString(16).padStart(2, "0"))
-        .join("");
-}
-
-/**
- * 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}
- */
-class MemKeyVerifier {
-    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.
-     */
-    async computeKeyMetadata(keyMetadata) {
-        // Compute the metadata from the key bytes
-        const computedFingerprint = {
-            checksum: await sha256Hex(keyMetadata.keyBytes),
-            size: keyMetadata.keyBytes.length
-        };
-        // If a KeyFingerprint is provided, verify it matches computed values.
-        if (keyMetadata.fingerprint) {
-            if (keyMetadata.fingerprint.size !== computedFingerprint.size) {
-                throw new KeyVerificationError(keyMetadata.locator ? keyMetadata.locator : "", "size", String(keyMetadata.fingerprint.size), String(computedFingerprint.size));
-            }
-            if (keyMetadata.fingerprint.checksum !== computedFingerprint.checksum) {
-                throw new KeyVerificationError(keyMetadata.locator ? keyMetadata.locator : "", "checksum", keyMetadata.fingerprint.checksum, computedFingerprint.checksum);
-            }
-        }
-        // If locator is provided, store only the fingerprint
-        if (keyMetadata.locator) {
-            this.keyStore[keyMetadata.locator] = computedFingerprint;
-        }
-        return computedFingerprint;
-    }
-    /**
-     * 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.
-     */
-    async verifyKeyBytes(keyMetadata) {
-        if (!keyMetadata.keyBytes) {
-            throw new Error("Key bytes must be provided for verification.");
-        }
-        // Compute the fingerprint for the provided bytes.
-        const computedFingerprint = await this.computeKeyMetadata({
-            keyBytes: keyMetadata.keyBytes
-        });
-        // Determine which fingerprint to verify against.
-        let fingerprintToVerify;
-        if (keyMetadata.fingerprint) {
-            // If a key fingerprint is provided, use it.
-            fingerprintToVerify = keyMetadata.fingerprint;
-        }
-        else if (keyMetadata.locator) {
-            // Otherwise try to get stored fingerprint by locator.
-            fingerprintToVerify = this.keyStore[keyMetadata.locator];
-        }
-        if (!fingerprintToVerify) {
-            throw new Error("Either fingerprint or a valid locator must be provided for verification.");
-        }
-        // Verify the key size.
-        if (fingerprintToVerify.size !== computedFingerprint.size) {
-            throw new KeyVerificationError(keyMetadata.locator || "", "size", String(fingerprintToVerify.size), String(computedFingerprint.size));
-        }
-        // Verify the key checksum.
-        if (fingerprintToVerify.checksum !== computedFingerprint.checksum) {
-            throw new KeyVerificationError(keyMetadata.locator || "", "checksum", fingerprintToVerify.checksum, computedFingerprint.checksum);
+                return CREDITS_PROGRAM_KEYS.split.verifyingKey();
+            case CREDITS_PROGRAM_KEYS.transfer_private.verifier:
+                return CREDITS_PROGRAM_KEYS.transfer_private.verifyingKey();
+            case CREDITS_PROGRAM_KEYS.transfer_private_to_public.verifier:
+                return CREDITS_PROGRAM_KEYS.transfer_private_to_public.verifyingKey();
+            case CREDITS_PROGRAM_KEYS.transfer_public.verifier:
+                return CREDITS_PROGRAM_KEYS.transfer_public.verifyingKey();
+            case CREDITS_PROGRAM_KEYS.transfer_public_as_signer.verifier:
+                return CREDITS_PROGRAM_KEYS.transfer_public_as_signer.verifyingKey();
+            case CREDITS_PROGRAM_KEYS.transfer_public_to_private.verifier:
+                return CREDITS_PROGRAM_KEYS.transfer_public_to_private.verifyingKey();
+            case CREDITS_PROGRAM_KEYS.unbond_public.verifier:
+                return CREDITS_PROGRAM_KEYS.unbond_public.verifyingKey();
+            default:
+                try {
+                    /// Try to fetch the verifying key from the network as a string
+                    const response = await get(verifierUri);
+                    const text = await response.text();
+                    return VerifyingKey.fromString(text);
+                }
+                catch (e) {
+                    /// If that fails, try to fetch the verifying key from the network as bytes
+                    try {
+                        return (VerifyingKey.fromBytes(await this.fetchBytes(verifierUri)));
+                    }
+                    catch (inner) {
+                        throw new Error("Invalid verifying key. Error: " + inner.message);
+                    }
+                }
         }
     }
-}
-
-/**
- * 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
- */
-class InvalidLocatorError extends Error {
-    locator;
-    reason;
-    /**
-     * @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, locator, reason) {
-        super(message);
-        this.locator = locator;
-        this.reason = reason;
-        this.name = "InvalidLocatorError";
-        Object.setPrototypeOf(this, InvalidLocatorError.prototype);
+    unBondPublicKeys() {
+        return this.fetchCreditsKeys(CREDITS_PROGRAM_KEYS.unbond_public);
     }
 }
 
@@ -5151,17 +5376,19 @@ class ProgramManager {
     networkClient;
     recordProvider;
     inclusionKeysLoaded = false;
+    _keyStore;
     /** Create a new instance of the ProgramManager
      *
      * @param { string | undefined } host A host uri running the official Aleo API
      * @param { FunctionKeyProvider | undefined } keyProvider A key provider that implements {@link FunctionKeyProvider} interface
      * @param { RecordProvider | undefined } recordProvider A record provider that implements {@link RecordProvider} interface
      */
-    constructor(host, keyProvider, recordProvider, networkClientOptions) {
+    constructor(host, keyProvider, recordProvider, networkClientOptions, keyStore) {
         this.host = host ? host : "https://api.provable.com/v2";
         this.networkClient = new AleoNetworkClient(this.host, networkClientOptions);
         this.keyProvider = keyProvider ? keyProvider : new AleoKeyProvider();
         this.recordProvider = recordProvider;
+        this._keyStore = keyStore;
     }
     /**
      * Check if the fee is sufficient to pay for the transaction
@@ -5205,6 +5432,320 @@ class ProgramManager {
     setRecordProvider(recordProvider) {
         this.recordProvider = recordProvider;
     }
+    /**
+     * Set the key store for automatic key caching across executions.
+     *
+     * @param {KeyStore} keyStore
+     */
+    setKeyStore(keyStore) {
+        this._keyStore = keyStore;
+    }
+    /**
+     * Build a ProgramImportsBuilder from a program and its imports.
+     * Fetches imports from the network if not provided, resolves transitive
+     * dependencies, and optionally pre-loads cached keys from the KeyStore.
+     *
+     * @param loadKeys When true (default), loads cached proving/verifying keys
+     *   from the KeyStore into the builder. Set to false for authorization and
+     *   proving request paths where keys are not synthesized.
+     */
+    async buildProgramImports(program, imports, loadKeys = true) {
+        const builder = new ProgramImports();
+        const programSource = typeof program === "string" ? program : program.toString();
+        const programObj = Program.fromString(programSource);
+        const importNames = programObj.getImports();
+        if (importNames.length === 0 && (!imports || Object.keys(imports).length === 0)) {
+            return { builder, importEditions: new Map() };
+        }
+        let resolvedImports = {};
+        if (importNames.length > 0) {
+            try {
+                resolvedImports = await this.networkClient.getProgramImports(programSource);
+            }
+            catch (e) {
+                console.warn(`Failed to resolve program imports from network: ${e}. Falling back to user-provided imports.`);
+            }
+        }
+        if (imports) {
+            resolvedImports = { ...resolvedImports, ...imports };
+        }
+        // Build a map of which functions each import actually calls,
+        // so we only load keys for functions in the call chain.
+        const calledFunctions = ProgramManager.getCalledFunctions(programSource);
+        // Phase 1: Collect all programs via BFS, discovering transitive imports.
+        // The initial getProgramImports call above already resolves the full
+        // transitive closure via recursive DFS.  The BFS loop here only needs
+        // to handle user-provided imports whose transitive deps may not yet be
+        // known.  For each unknown import we issue a single getProgram() call
+        // (not a full recursive getProgramImports) and fetch siblings in
+        // parallel to minimize round-trips.
+        const collected = new Map();
+        const collectQueue = Object.entries(resolvedImports).map(([name, src]) => [name, typeof src === "string" ? src : src.toString()]);
+        while (collectQueue.length > 0) {
+            const [name, source] = collectQueue.shift();
+            if (collected.has(name))
+                continue;
+            collected.set(name, source);
+            // Discover transitive imports and collect called functions.
+            // Use regex instead of Program.fromString to avoid a WASM
+            // round-trip per import — we only need import names here.
+            try {
+                const subImports = ProgramManager.getImportNames(source);
+                if (subImports.length > 0) {
+                    const transitiveCalls = ProgramManager.getCalledFunctions(source);
+                    for (const [tProgram, tFns] of transitiveCalls) {
+                        if (!calledFunctions.has(tProgram)) {
+                            calledFunctions.set(tProgram, tFns);
+                        }
+                        else {
+                            for (const fn of tFns)
+                                calledFunctions.get(tProgram).add(fn);
+                        }
+                    }
+                    // Fetch only unknown transitive imports — the source for
+                    // programs already in collected/resolvedImports is known, so
+                    // we skip them.  Fetches within a BFS level run in parallel.
+                    const unknownImports = subImports.filter((id) => !collected.has(id) && !(id in resolvedImports));
+                    if (unknownImports.length > 0) {
+                        const fetched = await Promise.all(unknownImports.map(async (id) => {
+                            try {
+                                const src = await this.networkClient.getProgram(id);
+                                return [id, src];
+                            }
+                            catch {
+                                return null;
+                            }
+                        }));
+                        for (const entry of fetched) {
+                            if (entry && !collected.has(entry[0])) {
+                                collectQueue.push(entry);
+                            }
+                        }
+                    }
+                }
+            }
+            catch {
+                // Non-blocking — transitive resolution is best-effort
+            }
+        }
+        // Phase 2: Add programs in topological order (leaves first).
+        // A simple DFS post-order ensures dependencies are added before
+        // dependents, regardless of the order collected entries arrived.
+        const sorted = [];
+        const visited = new Set();
+        const visit = (name) => {
+            if (visited.has(name))
+                return;
+            visited.add(name);
+            const source = collected.get(name);
+            if (!source)
+                return;
+            for (const dep of ProgramManager.getImportNames(source)) {
+                if (collected.has(dep))
+                    visit(dep);
+            }
+            sorted.push([name, source]);
+        };
+        for (const [name] of collected)
+            visit(name);
+        // Resolve editions for all imports in parallel (each import may have
+        // a different edition than the top-level program).
+        const importEditions = new Map();
+        await Promise.all(sorted.map(async ([name]) => {
+            importEditions.set(name, await this.resolveEditionAndAmendment(name));
+        }));
+        for (const [name, source] of sorted) {
+            if (builder.contains(name))
+                continue;
+            const { edition: importEdition, amendment: importAmendment } = importEditions.get(name);
+            try {
+                builder.addProgram(name, source, importEdition);
+            }
+            catch (e) {
+                console.warn(`Failed to add import ${name} to builder: ${e}`);
+                continue;
+            }
+            if (loadKeys) {
+                const calledFns = calledFunctions.get(name);
+                await this.loadKeysFromStore(builder, name, calledFns ? [...calledFns] : [], importEdition, importAmendment);
+            }
+        }
+        return { builder, importEditions };
+    }
+    /**
+     * Extract `import program_name.aleo;` names from program source via regex.
+     * Avoids a WASM round-trip compared to Program.fromString + getImports.
+     */
+    static getImportNames(programSource) {
+        const result = [];
+        const importPattern = /^\s*import\s+([a-zA-Z_][a-zA-Z0-9_]*\.aleo)\s*;/gm;
+        let match;
+        while ((match = importPattern.exec(programSource)) !== null) {
+            result.push(match[1]);
+        }
+        return result;
+    }
+    /**
+     * Parse `call program.aleo/function` instructions from program source
+     * to determine which functions of each import are actually in the call chain.
+     * Returns a map of program name -> set of called function names.
+     */
+    static getCalledFunctions(programSource) {
+        const result = new Map();
+        const callPattern = /call\s+([a-zA-Z_][a-zA-Z0-9_]*\.aleo)\/([a-zA-Z_][a-zA-Z0-9_]*)/g;
+        let match;
+        while ((match = callPattern.exec(programSource)) !== null) {
+            const programName = match[1];
+            const functionName = match[2];
+            if (!result.has(programName)) {
+                result.set(programName, new Set());
+            }
+            result.get(programName).add(functionName);
+        }
+        return result;
+    }
+    /**
+     * Resolve the active KeyStore, preferring the directly-set _keyStore
+     * over the KeyProvider's keyStore().
+     */
+    async resolveKeyStore() {
+        if (this._keyStore)
+            return this._keyStore;
+        try {
+            return await this.keyProvider?.keyStore?.();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Resolve the edition and amendment count for a program from the network.
+     * Returns `{ edition, amendment }` or falls back to `{ edition: 1, amendment: 0 }`.
+     */
+    async resolveEditionAndAmendment(programName, fallbackEdition) {
+        try {
+            const info = await this.networkClient.getProgramAmendmentCount(programName);
+            return { edition: info.edition, amendment: info.amendment_count };
+        }
+        catch (e) {
+            console.warn(`Error finding edition/amendment for ${programName}. Network response: '${e.message}'. Defaulting to edition ${fallbackEdition ?? 1}, amendment 0.`);
+            return { edition: fallbackEdition ?? 1, amendment: 0 };
+        }
+    }
+    /**
+     * Load cached proving/verifying keys from the KeyStore into a ProgramImportsBuilder.
+     * Only loads keys for the specified functions — returns immediately if
+     * functionNames is empty or undefined.
+     * Resolves edition and amendment from the network for accurate key locator
+     * construction when not explicitly provided.
+     */
+    async loadKeysFromStore(builder, programName, functionNames, edition, amendment) {
+        if (!functionNames || functionNames.length === 0)
+            return;
+        const keyStore = await this.resolveKeyStore();
+        if (!keyStore)
+            return;
+        // Resolve edition and amendment from the network if not fully provided.
+        if (edition === undefined || amendment === undefined) {
+            const resolved = await this.resolveEditionAndAmendment(programName, edition);
+            edition = edition ?? resolved.edition;
+            amendment = amendment ?? resolved.amendment;
+        }
+        for (const fnName of functionNames) {
+            const pkLocator = provingKeyLocator(programName, fnName, edition, amendment);
+            const vkLocator = verifyingKeyLocator(programName, fnName, edition, amendment);
+            try {
+                const pk = await keyStore.getProvingKey(pkLocator);
+                if (pk)
+                    builder.addProvingKey(programName, fnName, pk);
+                const vk = await keyStore.getVerifyingKey(vkLocator);
+                if (vk)
+                    builder.addVerifyingKey(programName, fnName, vk);
+            }
+            catch (e) {
+                console.debug(`Failed to load keys for ${programName}/${fnName}: ${e}`);
+            }
+        }
+    }
+    /**
+     * Persist newly synthesized keys from the returned ProgramImportsBuilder
+     * into the KeyStore. Only writes keys that are not already in the store,
+     * avoiding unnecessary writes of large proving keys.
+     * Fetches each program's current edition and amendment count from the network
+     * for accurate key locator construction.
+     */
+    async persistExtractedKeys(builder, importEditions) {
+        const keyStore = await this.resolveKeyStore();
+        if (!keyStore)
+            return;
+        const programNames = Array.from(builder.programNames());
+        // Reuse editions resolved during buildProgramImports when available,
+        // falling back to parallel network resolution for any missing programs.
+        const editionMap = importEditions ?? new Map();
+        const missing = programNames.filter((name) => !editionMap.has(name));
+        if (missing.length > 0) {
+            await Promise.all(missing.map(async (name) => {
+                editionMap.set(name, await this.resolveEditionAndAmendment(name));
+            }));
+        }
+        for (const programName of programNames) {
+            const { edition, amendment } = editionMap.get(programName);
+            let fns;
+            try {
+                fns = Array.from(builder.functionKeysAvailable(programName));
+            }
+            catch (e) {
+                console.debug(`Failed to query keys for ${programName}: ${e}`);
+                continue;
+            }
+            for (const fnName of fns) {
+                try {
+                    const pkLocator = provingKeyLocator(programName, fnName, edition, amendment);
+                    const vkLocator = verifyingKeyLocator(programName, fnName, edition, amendment);
+                    // Skip keys already in the store.
+                    if (await keyStore.has(pkLocator) && await keyStore.has(vkLocator)) {
+                        continue;
+                    }
+                    const pk = builder.getProvingKey(programName, fnName);
+                    const vk = builder.getVerifyingKey(programName, fnName);
+                    if (pk && vk) {
+                        await keyStore.setKeys(pkLocator, vkLocator, [pk, vk]);
+                    }
+                }
+                catch (e) {
+                    console.debug(`Failed to persist key for ${programName}/${fnName}: ${e}`);
+                }
+            }
+        }
+    }
+    /**
+     * Resolve top-level function keys, checking the KeyStore first and
+     * falling back to the KeyProvider.
+     */
+    async resolveTopLevelKeys(programName, functionName, keySearchParams, edition, amendment) {
+        const keyStore = await this.resolveKeyStore();
+        if (keyStore) {
+            try {
+                const pkLocator = provingKeyLocator(programName, functionName, edition, amendment);
+                const vkLocator = verifyingKeyLocator(programName, functionName, edition, amendment);
+                if (await keyStore.has(pkLocator) && await keyStore.has(vkLocator)) {
+                    const pk = await keyStore.getProvingKey(pkLocator);
+                    const vk = await keyStore.getVerifyingKey(vkLocator);
+                    if (pk && vk)
+                        return [pk, vk];
+                }
+            }
+            catch {
+                // Fall through to KeyProvider
+            }
+        }
+        try {
+            return (await this.keyProvider.functionKeys(keySearchParams));
+        }
+        catch {
+            return undefined;
+        }
+    }
     /**
      * Set a header in the `AleoNetworkClient`s header map
      *
@@ -5639,15 +6180,9 @@ class ProgramManager {
         if (programName === undefined) {
             programName = programObject.id();
         }
-        if (edition == undefined) {
-            try {
-                edition = await this.networkClient.getLatestProgramEdition(programName);
-            }
-            catch (e) {
-                console.warn(`Error finding edition for ${programName}. Network response: '${e.message}'. Assuming edition 0.`);
-                edition = 0;
-            }
-        }
+        const resolved = await this.resolveEditionAndAmendment(programName, edition);
+        edition = edition ?? resolved.edition;
+        const { amendment } = resolved;
         // Get the private key from the account if it is not provided in the parameters
         let executionPrivateKey = privateKey;
         if (typeof privateKey === "undefined" &&
@@ -5668,23 +6203,19 @@ class ProgramManager {
             logAndThrow(`Error finding fee keys. Key finder response: '${e.message}'. Please ensure your key provider is configured correctly.`);
         }
         const [feeProvingKey, feeVerifyingKey] = feeKeys;
-        // If the function proving and verifying keys are not provided, attempt to find them using the key provider
+        // Build the ProgramImportsBuilder for import resolution and key caching.
+        const { builder: programImportsBuilder, importEditions } = await this.buildProgramImports(program, imports);
+        // Include the top-level program's already-resolved edition so
+        // persistExtractedKeys doesn't make a redundant network call for it.
+        importEditions.set(programName, { edition: edition, amendment });
+        // If the function proving and verifying keys are not provided, attempt to find them
         if (!provingKey || !verifyingKey) {
-            try {
-                [provingKey, verifyingKey] = (await this.keyProvider.functionKeys(keySearchParams));
-            }
-            catch (e) {
-                console.log(`Function keys not found. Key finder response: '${e}'. The function keys will be synthesized`);
-            }
-        }
-        // Resolve the program imports if they exist
-        const numberOfImports = programObject.getImports().length;
-        if (numberOfImports > 0 && !imports) {
-            try {
-                imports = (await this.networkClient.getProgramImports(programName));
+            const keys = await this.resolveTopLevelKeys(programName, functionName, keySearchParams, edition, amendment);
+            if (keys) {
+                [provingKey, verifyingKey] = keys;
             }
-            catch (e) {
-                logAndThrow(`Error finding program imports. Network response: '${e.message}'. Please ensure you're connected to a valid Aleo network and the program is deployed to the network.`);
+            else {
+                console.log("Function keys not found in KeyStore or KeyProvider. The function keys will be synthesized");
             }
         }
         // Get the fee record from the account if it is not provided in the parameters
@@ -5718,8 +6249,22 @@ class ProgramManager {
                 logAndThrow(`Inclusion key bytes not loaded, please ensure the program manager is initialized with a KeyProvider that includes the inclusion key.`);
             }
         }
-        // Build an execution transaction
-        return await ProgramManager$1.buildExecutionTransaction(executionPrivateKey, program, functionName, inputs, priorityFee, feeRecord, this.host, imports, provingKey, verifyingKey, feeProvingKey, feeVerifyingKey, offlineQuery, edition);
+        // Auto-convert bare string inputs to field elements where the function expects field type.
+        const preparedInputs = this.prepareInputs(program, functionName, inputs);
+        // Build an execution transaction. Always pass the builder so synthesized
+        // keys (including the top-level program's) are captured via Rc<RefCell<>>
+        // interior mutability and can be persisted to the KeyStore.
+        const result = await ProgramManager$1.buildExecutionTransaction(executionPrivateKey, program, functionName, preparedInputs, priorityFee, feeRecord, this.host, undefined, // imports (legacy Object path — builder handles resolution)
+        provingKey, verifyingKey, feeProvingKey, feeVerifyingKey, offlineQuery, edition, programImportsBuilder?.clone());
+        // The clone passed to WASM shares state with the original via
+        // Rc<RefCell<>> — synthesized keys are already visible.
+        try {
+            await this.persistExtractedKeys(programImportsBuilder, importEditions);
+        }
+        catch (e) {
+            console.debug(`Failed to persist extracted keys: ${e}`);
+        }
+        return result;
     }
     /**
      * Builds an execution transaction for submission to the Aleo network from an Authorization and Fee Authorization.
@@ -5797,6 +6342,10 @@ class ProgramManager {
         const feeAuthorization = options.feeAuthorization;
         const keySearchParams = options.keySearchParams;
         const offlineQuery = options.offlineQuery;
+        let edition = options.edition;
+        const resolved = await this.resolveEditionAndAmendment(programName, edition);
+        edition = edition ?? resolved.edition;
+        const { amendment } = resolved;
         let provingKey = options.provingKey;
         let verifyingKey = options.verifyingKey;
         let program = options.program;
@@ -5825,24 +6374,17 @@ class ProgramManager {
             logAndThrow(`Error finding fee keys. Key finder response: '${e.message}'. Please ensure your key provider is configured correctly.`);
         }
         const [feeProvingKey, feeVerifyingKey] = feeKeys;
-        // If the function proving and verifying keys are not provided, attempt to find them using the key provider.
+        // Build the ProgramImportsBuilder for import resolution and key caching.
+        const { builder: programImportsBuilder, importEditions } = await this.buildProgramImports(program, imports);
+        importEditions.set(programName, { edition: edition, amendment });
+        // If the function proving and verifying keys are not provided, attempt to find them.
         if (!provingKey || !verifyingKey) {
-            try {
-                [provingKey, verifyingKey] = (await this.keyProvider.functionKeys(keySearchParams));
-            }
-            catch (e) {
-                console.log(`Function keys not found. Key finder response: '${e}'. The function keys will be synthesized`);
-            }
-        }
-        // Resolve the program imports if they exist.
-        console.log("Resolving program imports");
-        const numberOfImports = Program.fromString(program).getImports().length;
-        if (numberOfImports > 0 && !imports) {
-            try {
-                imports = (await this.networkClient.getProgramImports(programName));
+            const keys = await this.resolveTopLevelKeys(programName, authorization.functionName(), keySearchParams, edition, amendment);
+            if (keys) {
+                [provingKey, verifyingKey] = keys;
             }
-            catch (e) {
-                logAndThrow(`Error finding program imports. Network response: '${e.message}'. Please ensure you're connected to a valid Aleo network and the program is deployed to the network.`);
+            else {
+                console.log("Function keys not found in KeyStore or KeyProvider. The function keys will be synthesized");
             }
         }
         // If the offline query exists, add the inclusion key.
@@ -5858,9 +6400,20 @@ class ProgramManager {
                 logAndThrow(`Inclusion key bytes not loaded, please ensure the program manager is initialized with a KeyProvider that includes the inclusion key.`);
             }
         }
-        // Build an execution transaction from the authorization.
-        console.log("Executing authorizations");
-        return await ProgramManager$1.executeAuthorization(authorization, feeAuthorization, program, provingKey, verifyingKey, feeProvingKey, feeVerifyingKey, imports, this.host, offlineQuery);
+        // Build an execution transaction from the authorization. The
+        // ProgramImportsBuilder is consumed by value (ownership transfers to WASM)
+        // and returned enriched with any keys synthesized during execution.
+        const result = await ProgramManager$1.executeAuthorization(authorization, feeAuthorization, program, provingKey, verifyingKey, feeProvingKey, feeVerifyingKey, undefined, // imports (legacy Object path — builder handles resolution)
+        this.host, offlineQuery, programImportsBuilder?.clone(), edition);
+        // The builder uses interior mutability (Rc<RefCell<>>) — synthesized
+        // keys are already visible through the caller's reference.
+        try {
+            await this.persistExtractedKeys(programImportsBuilder, importEditions);
+        }
+        catch (e) {
+            console.debug(`Failed to persist extracted keys: ${e}`);
+        }
+        return result;
     }
     /**
      * Builds a SnarkVM `Authorization` for a specific function.
@@ -5923,27 +6476,17 @@ class ProgramManager {
         if (typeof executionPrivateKey === "undefined") {
             throw "No private key provided and no private key set in the ProgramManager";
         }
-        if (edition == undefined) {
-            try {
-                edition = await this.networkClient.getLatestProgramEdition(programName);
-            }
-            catch (e) {
-                console.warn(`Error finding edition for ${programName}. Network response: '${e.message}'. Assuming edition 0.`);
-                edition = 0;
-            }
-        }
-        // Resolve the program imports if they exist.
-        const numberOfImports = Program.fromString(program).getImports().length;
-        if (numberOfImports > 0 && !imports) {
-            try {
-                imports = (await this.networkClient.getProgramImports(programName));
-            }
-            catch (e) {
-                logAndThrow(`Error finding program imports. Network response: '${e.message}'. Please ensure you're connected to a valid Aleo network and the program is deployed to the network.`);
-            }
-        }
+        const resolved = await this.resolveEditionAndAmendment(programName, edition);
+        edition = edition ?? resolved.edition;
+        // Auto-convert bare string inputs to field elements where the function expects field type.
+        const preparedInputs = this.prepareInputs(program, functionName, inputs);
+        // Build ProgramImportsBuilder for import resolution (no key loading —
+        // authorizations don't synthesize keys).
+        const { builder } = await this.buildProgramImports(program, imports, false);
+        const hasImports = !builder.isEmpty();
         // Build and return an `Authorization` for the desired function.
-        return await ProgramManager$1.authorize(executionPrivateKey, program, functionName, inputs, imports, edition);
+        const authorization = await ProgramManager$1.authorize(executionPrivateKey, program, functionName, preparedInputs, hasImports ? undefined : imports, edition, hasImports ? builder?.clone() : undefined);
+        return authorization;
     }
     /**
      * Builds a SnarkVM `Authorization` for a specific function without building a circuit first. This should be used when fast authorization generation is needed and the invoker is confident inputs are coorect.
@@ -6006,27 +6549,17 @@ class ProgramManager {
         if (typeof executionPrivateKey === "undefined") {
             throw "No private key provided and no private key set in the ProgramManager";
         }
-        // Resolve the program imports if they exist.
-        const numberOfImports = Program.fromString(program).getImports().length;
-        if (numberOfImports > 0 && !imports) {
-            try {
-                imports = (await this.networkClient.getProgramImports(programName));
-            }
-            catch (e) {
-                logAndThrow(`Error finding program imports. Network response: '${e.message}'. Please ensure you're connected to a valid Aleo network and the program is deployed to the network.`);
-            }
-        }
-        if (edition == undefined) {
-            try {
-                edition = await this.networkClient.getLatestProgramEdition(programName);
-            }
-            catch (e) {
-                console.warn(`Error finding edition for ${programName}. Network response: '${e.message}'. Assuming edition 0.`);
-                edition = 0;
-            }
-        }
+        const resolved = await this.resolveEditionAndAmendment(programName, edition);
+        edition = edition ?? resolved.edition;
+        // Auto-convert bare string inputs to field elements where the function expects field type.
+        const preparedInputs = this.prepareInputs(program, functionName, inputs);
+        // Build ProgramImportsBuilder for import resolution (no key loading —
+        // authorizations don't synthesize keys).
+        const { builder } = await this.buildProgramImports(program, imports, false);
+        const hasImports = !builder.isEmpty();
         // Build and return an `Authorization` for the desired function.
-        return await ProgramManager$1.buildAuthorizationUnchecked(executionPrivateKey, program, functionName, inputs, imports, edition);
+        const authorization = await ProgramManager$1.buildAuthorizationUnchecked(executionPrivateKey, program, functionName, preparedInputs, hasImports ? undefined : imports, edition, hasImports ? builder?.clone() : undefined);
+        return authorization;
     }
     /**
      * Builds a `ProvingRequest` for submission to a prover for execution. If building a proving request with an ExecutionRequest, a private key must be explicitly provided.
@@ -6089,15 +6622,8 @@ class ProgramManager {
         if (programName === undefined) {
             programName = Program.fromString(program).id();
         }
-        if (edition == undefined) {
-            try {
-                edition = await this.networkClient.getLatestProgramEdition(programName);
-            }
-            catch (e) {
-                console.warn(`Error finding edition for ${programName}. Network response: '${e.message}'. Assuming edition 0.`);
-                edition = 0;
-            }
-        }
+        const resolved = await this.resolveEditionAndAmendment(programName, edition);
+        edition = edition ?? resolved.edition;
         // Get the private key from the account if it is not provided in the parameters.
         let executionPrivateKey = privateKey;
         if (typeof privateKey === "undefined" &&
@@ -6135,8 +6661,30 @@ class ProgramManager {
         catch (e) {
             logAndThrow(`Error finding fee record. Record finder response: '${e.message}'. Please ensure you're connected to a valid Aleo network and a record with enough balance exists.`);
         }
+        // Build ProgramImportsBuilder for import resolution (no key loading —
+        // proving requests don't synthesize keys).
+        // Note: imports is kept for the Rust-side fee estimation fallback
+        // (estimate_fee_for_authorization uses the legacy imports Object to avoid
+        // a RefCell double-borrow — see proving_request.rs).
+        const { builder } = await this.buildProgramImports(program, imports, false);
+        const hasImports = !builder.isEmpty();
+        // Normalize imports to the full merged set from the builder so the
+        // Rust fee estimator sees all transitive imports, not just the
+        // caller's partial set. Use programNames + getProgram to avoid
+        // serializing key bytes (toObject would serialize all proving/
+        // verifying keys, which can be tens of MB).
+        if (hasImports) {
+            const merged = {};
+            for (const name of Array.from(builder.programNames())) {
+                const src = builder.getProgram(name);
+                if (src)
+                    merged[name] = src;
+            }
+            imports = merged;
+        }
         if (options.executionRequest instanceof ExecutionRequest) {
-            return await ProgramManager$1.buildProvingRequestFromExecutionRequest(options.executionRequest, program, unchecked, broadcast, edition, imports, executionPrivateKey);
+            return await ProgramManager$1.buildProvingRequestFromExecutionRequest(options.executionRequest, program, unchecked, broadcast, edition, imports, // kept for fee estimation in Rust
+            executionPrivateKey, hasImports ? builder?.clone() : undefined);
         }
         else {
             // Ensure the private key exists.
@@ -6147,8 +6695,11 @@ class ProgramManager {
             if (!inputs) {
                 throw new Error("No inputs provided to build a proving request");
             }
+            // Auto-convert bare string inputs to field elements where the function expects field type.
+            const preparedInputs = this.prepareInputs(program, functionName, inputs);
             // Build and return the `ProvingRequest`.
-            return await ProgramManager$1.buildProvingRequest(executionPrivateKey, program, functionName, inputs, baseFee, priorityFee, feeRecord, imports, broadcast, unchecked, edition, useFeeMaster);
+            return await ProgramManager$1.buildProvingRequest(executionPrivateKey, program, functionName, preparedInputs, baseFee, priorityFee, feeRecord, imports, // kept for fee estimation in Rust
+            broadcast, unchecked, edition, useFeeMaster, hasImports ? builder?.clone() : undefined);
         }
     }
     /**
@@ -6250,6 +6801,44 @@ class ProgramManager {
         }
         return await this.networkClient.submitTransaction(tx);
     }
+    /**
+     * Prepares user-provided inputs for a function call by auto-converting bare
+     * string identifiers to field elements where the function signature expects
+     * a `field` type. This lets callers of dynamic-dispatch programs pass
+     * human-readable strings (e.g. `"my_program"`) instead of requiring
+     * `stringToField("my_program").toString()`.
+     *
+     * Inputs that already look like a numeric field literal (matching
+     * `/^\d+field$/` after trimming whitespace) are left untouched. Non-field
+     * inputs are returned as-is. If introspection fails for any reason the
+     * original inputs are returned unchanged.
+     *
+     * @param {string | Program} programSource - The program source code or Program object
+     * @param {string} functionName - The function to inspect
+     * @param {string[]} inputs - The raw user-provided inputs
+     * @returns {string[]} The (possibly converted) inputs
+     */
+    prepareInputs(programSource, functionName, inputs) {
+        try {
+            const source = typeof programSource === "string" ? programSource : programSource.toString();
+            const programObj = Program.fromString(source);
+            const functionInputs = programObj.getFunctionInputs(functionName);
+            if (functionInputs.length !== inputs.length) {
+                return inputs;
+            }
+            return inputs.map((input, i) => {
+                const spec = functionInputs[i];
+                const isFieldLiteral = /^\d+field$/.test(input.trim());
+                if (spec?.type === "field" && !isFieldLiteral) {
+                    return stringToField(input).toString();
+                }
+                return input;
+            });
+        }
+        catch {
+            return inputs;
+        }
+    }
     /**
      * Run an Aleo program in offline mode
      *
@@ -6283,6 +6872,10 @@ class ProgramManager {
      * assert(result === ["10u32"]);
      */
     async run(program, function_name, inputs, proveExecution, imports, keySearchParams, provingKey, verifyingKey, privateKey, offlineQuery, edition) {
+        const programName = Program.fromString(program).id();
+        const resolved = await this.resolveEditionAndAmendment(programName, edition);
+        edition = edition ?? resolved.edition;
+        const { amendment } = resolved;
         // Get the private key from the account if it is not provided in the parameters
         let executionPrivateKey = privateKey;
         if (typeof privateKey === "undefined" &&
@@ -6292,20 +6885,33 @@ class ProgramManager {
         if (typeof executionPrivateKey === "undefined") {
             throw "No private key provided and no private key set in the ProgramManager";
         }
-        // If the function proving and verifying keys are not provided, attempt to find them using the key provider
+        // Build the ProgramImportsBuilder for import resolution and key caching.
+        const { builder, importEditions } = await this.buildProgramImports(program, imports);
+        importEditions.set(programName, { edition: edition, amendment });
         if (!provingKey || !verifyingKey) {
-            try {
-                [provingKey, verifyingKey] = (await this.keyProvider.functionKeys(keySearchParams));
+            const keys = await this.resolveTopLevelKeys(programName, function_name, keySearchParams, edition, amendment);
+            if (keys) {
+                [provingKey, verifyingKey] = keys;
             }
-            catch (e) {
-                console.log(`Function keys not found. Key finder response: '${e}'. The function keys will be synthesized`);
+            else {
+                console.log("Function keys not found in KeyStore or KeyProvider. The function keys will be synthesized");
             }
         }
-        // Run the program offline and return the result
-        console.log("Running program offline");
-        console.log("Proving key: ", provingKey);
-        console.log("Verifying key: ", verifyingKey);
-        return ProgramManager$1.executeFunctionOffline(executionPrivateKey, program, function_name, inputs, proveExecution, false, imports, provingKey, verifyingKey, this.host, offlineQuery, edition);
+        // Auto-convert bare string inputs to field elements where the function expects field type.
+        const preparedInputs = this.prepareInputs(program, function_name, inputs);
+        // Run the program offline. Always pass the builder so synthesized
+        // keys (including the top-level program's) are captured and persisted.
+        const result = await ProgramManager$1.executeFunctionOffline(executionPrivateKey, program, function_name, preparedInputs, proveExecution, false, undefined, // imports (legacy Object path — builder handles resolution)
+        provingKey, verifyingKey, this.host, offlineQuery, edition, builder?.clone());
+        // The clone passed to WASM shares state with the original via
+        // Rc<RefCell<>> — synthesized keys are already visible.
+        try {
+            await this.persistExtractedKeys(builder, importEditions);
+        }
+        catch (e) {
+            console.debug(`Failed to persist extracted keys: ${e}`);
+        }
+        return result;
     }
     /**
      * Join two credits records into a single credits record
@@ -6520,10 +7126,12 @@ class ProgramManager {
                 executionPrivateKey = new PrivateKey();
             }
         }
+        // Auto-convert bare string inputs to field elements where the function expects field type.
+        const preparedInputs = this.prepareInputs(program, function_id, inputs);
         // Attempt to run an offline execution of the program and extract the proving and verifying keys
         try {
             imports = await this.networkClient.getProgramImports(program);
-            const keyPair = await ProgramManager$1.synthesizeKeyPair(executionPrivateKey, program, function_id, inputs, imports);
+            const keyPair = await ProgramManager$1.synthesizeKeyPair(executionPrivateKey, program, function_id, preparedInputs, imports);
             return [
                 keyPair.provingKey(),
                 keyPair.verifyingKey(),
@@ -7405,12 +8013,8 @@ class ProgramManager {
             throw new Error("Authorization must be provided if estimating fee for Authorization.");
         }
         const programSource = program ? program.toString() : await this.networkClient.getProgram(programName, edition);
-        const programImports = imports ? imports : await this.networkClient.getProgramImports(programSource);
-        console.log(JSON.stringify(programImports));
-        if (Object.keys(programImports)) {
-            return ProgramManager$1.estimateFeeForAuthorization(authorization, programSource, programImports, edition);
-        }
-        return ProgramManager$1.estimateFeeForAuthorization(authorization, programSource, imports, edition);
+        const programImports = imports ?? await this.networkClient.getProgramImports(programSource);
+        return ProgramManager$1.estimateFeeForAuthorization(authorization, programSource, programImports, edition);
     }
     /**
      * Estimate the execution fee for an Aleo function.
@@ -7491,7 +8095,7 @@ class ProgramManager {
      * import { AleoKeyProvider, getOrInitConsensusVersionTestHeights, ProgramManager, NetworkRecordProvider } from "@provablehq/sdk/mainnet.js";
      *
      * // Initialize the development consensus heights in order to work with devnode.
-     * getOrInitConsensusVersionTestHeights("0,1,2,3,4,5,6,7,8,9,10,11,12");
+     * getOrInitConsensusVersionTestHeights("0,1,2,3,4,5,6,7,8,9,10,11,12,13");
      *
      * // Create a new NetworkClient and RecordProvider.
      * const recordProvider = new NetworkRecordProvider(account, networkClient);
@@ -7556,15 +8160,8 @@ class ProgramManager {
         if (programName === undefined) {
             programName = programObject.id();
         }
-        if (edition == undefined) {
-            try {
-                edition = await this.networkClient.getLatestProgramEdition(programName);
-            }
-            catch (e) {
-                console.warn(`Error finding edition for ${programName}. Network response: '${e.message}'. Assuming edition 0.`);
-                edition = 0;
-            }
-        }
+        const resolved = await this.resolveEditionAndAmendment(programName, edition);
+        edition = edition ?? resolved.edition;
         // Get the private key from the account if it is not provided in the parameters.
         let executionPrivateKey = privateKey;
         if (typeof privateKey === "undefined" &&
@@ -7607,8 +8204,10 @@ class ProgramManager {
                 logAndThrow(`Error finding program imports. Network response: '${e.message}'. Please ensure you're connected to a valid Aleo network and the program is deployed to the network.`);
             }
         }
+        // Auto-convert bare string inputs to field elements where the function expects field type.
+        const preparedInputs = this.prepareInputs(program, functionName, inputs);
         // Build a transaction without a proof
-        return await ProgramManager$1.buildDevnodeExecutionTransaction(executionPrivateKey, program, functionName, inputs, priorityFee, feeRecord, this.host, imports, edition);
+        return await ProgramManager$1.buildDevnodeExecutionTransaction(executionPrivateKey, program, functionName, preparedInputs, priorityFee, feeRecord, this.host, imports, edition);
     }
     /**
      * Builds a deployment transaction with placeholder certificates and verifying keys for each function in the program.
@@ -7623,7 +8222,7 @@ class ProgramManager {
      * import { ProgramManager, NetworkRecordProvider, getOrInitConsensusVersionTestHeights } from "@provablehq/sdk/mainnet.js";
      *
      * // Initialize the development consensus heights in order to work with a local devnode.
-     * getOrInitConsensusVersionTestHeights("0,1,2,3,4,5,6,7,8,9,10,11,12");
+     * getOrInitConsensusVersionTestHeights("0,1,2,3,4,5,6,7,8,9,10,11,12,13");
      *
      * // Create a new NetworkClient, and RecordProvider
      * const recordProvider = new NetworkRecordProvider(account, networkClient);
@@ -8147,5 +8746,5 @@ async function initializeWasm() {
     console.warn("initializeWasm is deprecated, you no longer need to use it");
 }
 
-export { Account, AleoKeyProvider, AleoKeyProviderParams, AleoNetworkClient, BlockHeightSearch, CREDITS_PROGRAM_KEYS, KeyVerificationError as ChecksumMismatchError, DecryptionNotEnabledError, InvalidLocatorError, KEY_STORE, KeyVerificationError, MemKeyVerifier, NetworkRecordProvider, OfflineKeyProvider, OfflineSearchParams, PRIVATE_TO_PUBLIC_TRANSFER, PRIVATE_TRANSFER, PRIVATE_TRANSFER_TYPES, PUBLIC_TO_PRIVATE_TRANSFER, PUBLIC_TRANSFER, PUBLIC_TRANSFER_AS_SIGNER, ProgramManager, RECORD_DOMAIN, RecordNotFoundError, RecordScanner, RecordScannerRequestError, SealanceMerkleTree, UUIDError, VALID_TRANSFER_TYPES, ViewKeyNotStoredError, buildExecutionRequestFromExternallySignedData, computeExternalSigningInputs, encryptAuthorization, encryptProvingRequest, encryptRegistrationRequest, encryptViewKey, initializeWasm, inputsToFields, isInputIdStrategy, isProveApiErrorBody, isProvingResponse, isRecordViewKeyStrategy, isViewKeyStrategy, logAndThrow, provingKeyLocator, sha256Hex, toAddress, toField, toGroup, toSignature, toViewKey, translationKeyLocator, verifyBatchProof, verifyProof, verifyingKeyLocator, zeroizeBytes };
+export { Account, AleoKeyProvider, AleoKeyProviderParams, AleoNetworkClient, BlockHeightSearch, CREDITS_PROGRAM_KEYS, KeyVerificationError as ChecksumMismatchError, DecryptionNotEnabledError, IndexedDBKeyStore, InvalidLocatorError, KEY_STORE, KeyVerificationError, MemKeyVerifier, NetworkRecordProvider, OfflineKeyProvider, OfflineSearchParams, PRIVATE_TO_PUBLIC_TRANSFER, PRIVATE_TRANSFER, PRIVATE_TRANSFER_TYPES, PUBLIC_TO_PRIVATE_TRANSFER, PUBLIC_TRANSFER, PUBLIC_TRANSFER_AS_SIGNER, ProgramManager, RECORD_DOMAIN, RecordNotFoundError, RecordScanner, RecordScannerRequestError, SealanceMerkleTree, UUIDError, VALID_TRANSFER_TYPES, ViewKeyNotStoredError, buildExecutionRequestFromExternallySignedData, computeExternalSigningInputs, encryptAuthorization, encryptProvingRequest, encryptRegistrationRequest, encryptViewKey, initializeWasm, inputsToFields, isInputIdStrategy, isProveApiErrorBody, isProvingResponse, isRecordViewKeyStrategy, isViewKeyStrategy, logAndThrow, provingKeyLocator, sha256Hex, toAddress, toField, toGroup, toSignature, toViewKey, translationKeyLocator, verifyBatchProof, verifyProof, verifyingKeyLocator, zeroizeBytes };
 //# sourceMappingURL=browser.js.map