@provablehq/sdk 0.11.5 → 0.11.6

package/dist/testnet/browser.cjs

@@ -1603,7 +1603,7 @@ class AleoNetworkClient {
             else {
                 this.headers = {
                     // This is replaced by the actual version by a Rollup plugin
-                    "X-Aleo-SDK-Version": "0.11.5",
+                    "X-Aleo-SDK-Version": "0.11.6",
                     "X-Aleo-environment": environment(),
                 };
             }
@@ -1619,7 +1619,7 @@ class AleoNetworkClient {
         else {
             this.headers = {
                 // This is replaced by the actual version by a Rollup plugin
-                "X-Aleo-SDK-Version": "0.11.5",
+                "X-Aleo-SDK-Version": "0.11.6",
                 "X-Aleo-environment": environment(),
             };
         }
@@ -5799,6 +5799,56 @@ function generateHookData(recipientAddress, secretNonce) {
     return hookData;
 }
 
+const preparedProgramBuilders = new WeakMap();
+function clonePreparedProgramBuilder(preparedProgram) {
+    const builder = preparedProgramBuilders.get(preparedProgram);
+    if (!builder) {
+        throw new Error("Prepared program has already been freed");
+    }
+    // The WASM clone is a cheap shared Rc handle, not a deep copy. Mutations
+    // made while authorizing intentionally remain cached in the prepared context.
+    return builder.clone();
+}
+function programImportsFromBuilder(builder, entryProgramName) {
+    const imports = {};
+    for (const name of Array.from(builder.programNames())) {
+        if (name === entryProgramName)
+            continue;
+        const source = builder.getProgram(name);
+        if (source)
+            imports[name] = source;
+    }
+    return imports;
+}
+/**
+ * A reusable program context created by {@link ProgramManager.prepareProgram}.
+ *
+ * The context is scoped to one program function. Calls using it must be
+ * sequential. The caller owns the context and should call {@link free} when it
+ * is no longer needed.
+ */
+class PreparedProgram {
+    programName;
+    functionName;
+    programSource;
+    edition;
+    /**
+     * Instances are normally created through {@link ProgramManager.prepareProgram}.
+     */
+    constructor(programName, functionName, programSource, edition) {
+        this.programName = programName;
+        this.functionName = functionName;
+        this.programSource = programSource;
+        this.edition = edition;
+    }
+    /**
+     * Release the prepared snarkVM process. This method is idempotent.
+     */
+    free() {
+        preparedProgramBuilders.get(this)?.free();
+        preparedProgramBuilders.delete(this);
+    }
+}
 /**
  * The ProgramManager class is used to execute and deploy programs on the Aleo network and create value transfers.
  */
@@ -5907,6 +5957,93 @@ class ProgramManager {
     setKeyStore(keyStore) {
         this._keyStore = keyStore;
     }
+    /**
+     * Prepare a program for later authorization or proving-request generation.
+     *
+     * This resolves the source, edition, and transitive imports and initializes
+     * the underlying snarkVM process without accessing a private key. Reuse the
+     * returned context through the `preparedProgram` option, then call `free()`
+     * when it is no longer needed.
+     *
+     * @param options Program and function to prepare.
+     * @returns A reusable, caller-owned context.
+     *
+     * @example
+     * const prepared = await programManager.prepareProgram({
+     *     programName: "hello_hello.aleo",
+     *     functionName: "hello",
+     * });
+     * try {
+     *     const authorization = await programManager.buildAuthorization({
+     *         programName: "hello_hello.aleo",
+     *         functionName: "hello",
+     *         inputs: ["5u32", "5u32"],
+     *         preparedProgram: prepared,
+     *     });
+     * } finally {
+     *     prepared.free();
+     * }
+     */
+    async prepareProgram(options) {
+        let program = options.programSource;
+        if (program === undefined) {
+            try {
+                program = await this.networkClient.getProgram(options.programName);
+            }
+            catch (e) {
+                logAndThrow(`Error finding ${options.programName}. Network response: '${e.message}'. Please ensure you're connected to a valid Aleo network the program is deployed to the network.`);
+            }
+        }
+        else if (program instanceof testnet_js.Program) {
+            program = program.toString();
+        }
+        const parsedProgram = testnet_js.Program.fromString(program);
+        if (parsedProgram.id() !== options.programName) {
+            throw new Error(`Program source ID '${parsedProgram.id()}' does not match requested program '${options.programName}'`);
+        }
+        if (!parsedProgram.getFunctions().includes(options.functionName)) {
+            throw new Error(`Function '${options.functionName}' does not exist in program '${options.programName}'`);
+        }
+        const edition = options.edition
+            ?? (await this.resolveEditionAndAmendment(options.programName)).edition;
+        const { builder } = await this.buildProgramImports(program, options.programImports, false, options.functionName);
+        // Add the entry program as well as its imports so the snarkVM process is
+        // fully initialized before an authorization is requested.
+        builder.addProgram(options.programName, program, edition);
+        const preparedProgram = new PreparedProgram(options.programName, options.functionName, program, edition);
+        preparedProgramBuilders.set(preparedProgram, builder);
+        return preparedProgram;
+    }
+    validatePreparedProgram(preparedProgram, options) {
+        if (preparedProgram.programName !== options.programName
+            || preparedProgram.functionName !== options.functionName) {
+            throw new Error(`Prepared program is for ${preparedProgram.programName}/${preparedProgram.functionName}, not ${options.programName}/${options.functionName}`);
+        }
+        const providedSource = options.programSource instanceof testnet_js.Program
+            ? options.programSource.toString()
+            : options.programSource;
+        if (providedSource !== undefined
+            && providedSource !== preparedProgram.programSource) {
+            throw new Error("Prepared program source does not match the supplied program source");
+        }
+        if (options.edition !== undefined
+            && options.edition !== preparedProgram.edition) {
+            throw new Error("Prepared program edition does not match the supplied edition");
+        }
+        if (options.programImports) {
+            const builder = clonePreparedProgramBuilder(preparedProgram);
+            try {
+                for (const [name, source] of Object.entries(options.programImports)) {
+                    if (builder.getProgram(name) !== source.toString()) {
+                        throw new Error(`Prepared program import '${name}' does not match the supplied import`);
+                    }
+                }
+            }
+            finally {
+                builder.free();
+            }
+        }
+    }
     /**
      * Collect static imports declared by the entry program together with any
      * caller-provided imports, then resolve missing transitive dependencies.
@@ -6907,11 +7044,15 @@ class ProgramManager {
     async buildAuthorization(options) {
         // Destructure the options object to access the parameters.
         const { functionName, inputs, } = options;
+        const preparedProgram = options.preparedProgram;
+        if (preparedProgram) {
+            this.validatePreparedProgram(preparedProgram, options);
+        }
         const privateKey = options.privateKey;
-        let program = options.programSource;
-        let programName = options.programName;
-        let imports = options.programImports;
-        let edition = options.edition;
+        let program = preparedProgram?.programSource ?? options.programSource;
+        let programName = preparedProgram?.programName ?? options.programName;
+        const imports = options.programImports;
+        let edition = preparedProgram?.edition ?? options.edition;
         // Ensure the function exists on the network.
         if (program === undefined) {
             try {
@@ -6937,16 +7078,21 @@ class ProgramManager {
         if (typeof executionPrivateKey === "undefined") {
             throw "No private key provided and no private key set in the ProgramManager";
         }
-        const resolved = await this.resolveEditionAndAmendment(programName, edition);
-        edition = edition ?? resolved.edition;
+        if (!preparedProgram) {
+            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, functionName);
+        const builder = preparedProgram
+            ? clonePreparedProgramBuilder(preparedProgram)
+            : (await this.buildProgramImports(program, imports, false, functionName)).builder;
+        const hasPreparedProcess = preparedProgram !== undefined;
         const hasImports = !builder.isEmpty();
         // Build and return an `Authorization` for the desired function.
-        const authorization = await testnet_js.ProgramManager.authorize(executionPrivateKey, program, functionName, preparedInputs, hasImports ? undefined : imports, edition, hasImports ? builder?.clone() : undefined);
+        const authorization = await testnet_js.ProgramManager.authorize(executionPrivateKey, program, functionName, preparedInputs, hasPreparedProcess || hasImports ? undefined : imports, edition, hasPreparedProcess ? builder : hasImports ? builder.clone() : undefined);
         return authorization;
     }
     /**
@@ -6980,11 +7126,15 @@ class ProgramManager {
     async buildAuthorizationUnchecked(options) {
         // Destructure the options object to access the parameters.
         const { functionName, inputs, } = options;
+        const preparedProgram = options.preparedProgram;
+        if (preparedProgram) {
+            this.validatePreparedProgram(preparedProgram, options);
+        }
         const privateKey = options.privateKey;
-        let program = options.programSource;
-        let programName = options.programName;
-        let imports = options.programImports;
-        let edition = options.edition;
+        let program = preparedProgram?.programSource ?? options.programSource;
+        let programName = preparedProgram?.programName ?? options.programName;
+        const imports = options.programImports;
+        let edition = preparedProgram?.edition ?? options.edition;
         // Ensure the function exists on the network.
         if (program === undefined) {
             try {
@@ -7010,16 +7160,21 @@ class ProgramManager {
         if (typeof executionPrivateKey === "undefined") {
             throw "No private key provided and no private key set in the ProgramManager";
         }
-        const resolved = await this.resolveEditionAndAmendment(programName, edition);
-        edition = edition ?? resolved.edition;
+        if (!preparedProgram) {
+            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, functionName);
+        const builder = preparedProgram
+            ? clonePreparedProgramBuilder(preparedProgram)
+            : (await this.buildProgramImports(program, imports, false, functionName)).builder;
+        const hasPreparedProcess = preparedProgram !== undefined;
         const hasImports = !builder.isEmpty();
         // Build and return an `Authorization` for the desired function.
-        const authorization = await testnet_js.ProgramManager.buildAuthorizationUnchecked(executionPrivateKey, program, functionName, preparedInputs, hasImports ? undefined : imports, edition, hasImports ? builder?.clone() : undefined);
+        const authorization = await testnet_js.ProgramManager.buildAuthorizationUnchecked(executionPrivateKey, program, functionName, preparedInputs, hasPreparedProcess || hasImports ? undefined : imports, edition, hasPreparedProcess ? builder : hasImports ? builder.clone() : undefined);
         return authorization;
     }
     /**
@@ -7056,14 +7211,18 @@ class ProgramManager {
     async provingRequest(options) {
         // Destructure the options object to access the parameters.
         const { functionName, priorityFee, privateFee, inputs, recordSearchParams, broadcast = false, unchecked = false, } = options;
+        const preparedProgram = options.preparedProgram;
+        if (preparedProgram) {
+            this.validatePreparedProgram(preparedProgram, options);
+        }
         const baseFee = options.baseFee ? options.baseFee : 0;
         const privateKey = options.privateKey;
         const useFeeMaster = options.useFeeMaster ? options.useFeeMaster : false;
-        let program = options.programSource;
-        let programName = options.programName;
+        let program = preparedProgram?.programSource ?? options.programSource;
+        let programName = preparedProgram?.programName ?? options.programName;
         let feeRecord = options.feeRecord;
         let imports = options.programImports;
-        let edition = options.edition;
+        let edition = preparedProgram?.edition ?? options.edition;
         if (!inputs && !options.executionRequest) {
             throw new Error("Either function inputs or an execution request must be provided to form a proving request");
         }
@@ -7083,8 +7242,10 @@ class ProgramManager {
         if (programName === undefined) {
             programName = testnet_js.Program.fromString(program).id();
         }
-        const resolved = await this.resolveEditionAndAmendment(programName, edition);
-        edition = edition ?? resolved.edition;
+        if (!preparedProgram) {
+            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" &&
@@ -7094,7 +7255,7 @@ class ProgramManager {
         }
         // Resolve the program imports if they exist.
         const numberOfImports = testnet_js.Program.fromString(program).getImports().length;
-        if (numberOfImports > 0 && !imports) {
+        if (!preparedProgram && numberOfImports > 0 && !imports) {
             try {
                 imports = (await this.networkClient.getProgramImports(programName));
             }
@@ -7102,6 +7263,28 @@ 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.`);
             }
         }
+        // Build ProgramImportsBuilder for import resolution (no key loading —
+        // proving requests don't synthesize keys).
+        const builder = preparedProgram
+            ? clonePreparedProgramBuilder(preparedProgram)
+            : (await this.buildProgramImports(program, imports, false, functionName)).builder;
+        const hasPreparedProcess = preparedProgram !== undefined;
+        const hasImports = !builder.isEmpty();
+        // Normalize imports once to the full merged set from the builder so
+        // both the private-fee estimate below and the Rust-side fee estimator
+        // (estimate_fee_for_authorization uses the legacy imports Object to
+        // avoid a RefCell double-borrow — see proving_request.rs) see 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). The prepared executionRequest path skips the copy: it passes
+        // the process builder directly and never estimates fees, so the
+        // imports Object goes unused there.
+        const importsObjectUnused = hasPreparedProcess
+            && options.executionRequest instanceof testnet_js.ExecutionRequest;
+        if ((hasPreparedProcess || hasImports) && !importsObjectUnused) {
+            imports = programImportsFromBuilder(builder, programName);
+        }
         // Get the fee record from the account if it is not provided in the parameters
         try {
             if (privateFee && !useFeeMaster && !options.executionRequest) {
@@ -7122,30 +7305,11 @@ 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, functionName);
-        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 testnet_js.ExecutionRequest) {
-            return await testnet_js.ProgramManager.buildProvingRequestFromExecutionRequest(options.executionRequest, program, unchecked, broadcast, edition, imports, // kept for fee estimation in Rust
-            executionPrivateKey, hasImports ? builder?.clone() : undefined);
+            return await testnet_js.ProgramManager.buildProvingRequestFromExecutionRequest(options.executionRequest, program, unchecked, broadcast, edition, 
+            // The prepared process supersedes the legacy imports Object;
+            // without one, imports is kept for fee estimation in Rust.
+            hasPreparedProcess ? undefined : imports, executionPrivateKey, hasPreparedProcess ? builder : hasImports ? builder.clone() : undefined);
         }
         else {
             // Ensure the private key exists.
@@ -7160,7 +7324,7 @@ class ProgramManager {
             const preparedInputs = this.prepareInputs(program, functionName, inputs);
             // Build and return the `ProvingRequest`.
             return await testnet_js.ProgramManager.buildProvingRequest(executionPrivateKey, program, functionName, preparedInputs, baseFee, priorityFee, feeRecord, imports, // kept for fee estimation in Rust
-            broadcast, unchecked, edition, useFeeMaster, hasImports ? builder?.clone() : undefined);
+            broadcast, unchecked, edition, useFeeMaster, hasPreparedProcess ? builder : hasImports ? builder.clone() : undefined);
         }
     }
     /**
@@ -8537,7 +8701,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,13,14,15,16");
+     * getOrInitConsensusVersionTestHeights("0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17");
      *
      * // Create a new NetworkClient and RecordProvider.
      * const recordProvider = new NetworkRecordProvider(account, networkClient);
@@ -8664,7 +8828,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,13,14,15,16");
+     * getOrInitConsensusVersionTestHeights("0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17");
      *
      * // Create a new NetworkClient, and RecordProvider
      * const recordProvider = new NetworkRecordProvider(account, networkClient);
@@ -9472,6 +9636,7 @@ exports.PRIVATE_TRANSFER_TYPES = PRIVATE_TRANSFER_TYPES;
 exports.PUBLIC_TO_PRIVATE_TRANSFER = PUBLIC_TO_PRIVATE_TRANSFER;
 exports.PUBLIC_TRANSFER = PUBLIC_TRANSFER;
 exports.PUBLIC_TRANSFER_AS_SIGNER = PUBLIC_TRANSFER_AS_SIGNER;
+exports.PreparedProgram = PreparedProgram;
 exports.ProgramManager = ProgramManager;
 exports.RECORD_DOMAIN = RECORD_DOMAIN;
 exports.RecordNotFoundError = RecordNotFoundError;