Merge pull request #1057 from ProvableHQ/feat/proving-requests

[Feature] Proving Requests

Author: iamalwaysuncomfortable

sdk/src/browser.ts

@@ -20,6 +20,8 @@ import { PlaintextArray} from "./models/plaintext/array.js";
 import { PlaintextLiteral} from "./models/plaintext/literal.js";
 import { PlaintextObject } from "./models/plaintext/plaintext.js";
 import { PlaintextStruct} from "./models/plaintext/struct.js";
+import { ProvingRequestJSON } from "./models/provingRequest.js";
+import { ProvingResponse } from "./models/provingResponse.js";
 import { RatificationJSON } from "./models/ratification.js";
 import { SolutionsJSON, SolutionJSON, PartialSolutionJSON } from "./models/solution.js";
 import { TransactionJSON } from "./models/transaction/transactionJSON.js";
@@ -51,7 +53,7 @@ async function initializeWasm() {
     console.warn("initializeWasm is deprecated, you no longer need to use it");
 }
 
-export { ProgramManager } from "./program-manager.js";
+export { ProgramManager, ProvingRequestOptions, ExecuteOptions, FeeAuthorizationOptions, AuthorizationOptions } from "./program-manager.js";
 
 export { logAndThrow } from "./utils.js";
 
@@ -83,6 +85,7 @@ export {
     Program,
     ProgramManager as ProgramManagerBase,
     ProvingKey,
+    ProvingRequest,
     RecordCiphertext,
     RecordPlaintext,
     Signature,
@@ -149,6 +152,8 @@ export {
     PlaintextObject,
     PlaintextStruct,
     ProgramImports,
+    ProvingRequestJSON,
+    ProvingResponse,
     RatificationJSON,
     RecordProvider,
     RecordSearchParams,

sdk/src/models/provingRequest.ts

@@ -0,0 +1,7 @@
+import { AuthorizationJSON } from "./authorization";
+
+export interface ProvingRequestJSON {
+    authorization: AuthorizationJSON;
+    fee_authorization?: AuthorizationJSON;
+    broadcast: boolean;
+}

sdk/src/models/provingResponse.ts

@@ -0,0 +1,6 @@
+import { TransactionJSON } from "./transaction/transactionJSON";
+
+export interface ProvingResponse {
+    transaction: TransactionJSON,
+    broadcast?: boolean,
+}

sdk/src/program-manager.ts

@@ -21,6 +21,7 @@ import {
     PrivateKey,
     Program,
     ProvingKey,
+    ProvingRequest,
     VerifyingKey,
     Transaction,
     ProgramManager as WasmProgramManager,
@@ -107,6 +108,40 @@ interface FeeAuthorizationOptions {
     feeRecord?: RecordPlaintext,
 }
 
+/**
+ * Represents the options for executing a transaction in the Aleo network.
+ * This interface is used to specify the parameters required for building and submitting an execution transaction.
+ *
+ * @property {string} programName - The name of the program containing the function to be executed.
+ * @property {string} functionName - The name of the function to execute within the program.
+ * @property {number} baseFee - The base fee to be paid for the transaction.
+ * @property {number} priorityFee - The optional priority fee to be paid for the transaction.
+ * @property {boolean} privateFee - If true, uses a private record to pay the fee; otherwise, uses the account's public credit balance.
+ * @property {string[]} inputs - The inputs to the function being executed.
+ * @property {RecordSearchParams} [recordSearchParams] - Optional parameters for searching for a record to pay the execution transaction fee.
+ * @property {string | RecordPlaintext} [feeRecord] - Optional fee record to use for the transaction.
+ * @property {PrivateKey} [privateKey] - Optional private key to use for the transaction.
+ * @property {string | Program} [program] - Optional program source code to use for the transaction.
+ * @property {string} uri - The URI send the ProvingRequest to.
+ * @property {ProgramImports} [imports] - Optional programs that the program being executed imports.
+ * @property {boolean} broadcast - Whether to broadcast the Transaction generated by the remove prover to the Aleo network.
+ */
+interface ProvingRequestOptions {
+    programName: string;
+    functionName: string;
+    baseFee: number,
+    priorityFee: number;
+    privateFee: boolean;
+    inputs: string[];
+    recordSearchParams?: RecordSearchParams;
+    feeRecord?: string | RecordPlaintext;
+    privateKey?: PrivateKey;
+    programSource?: string | Program;
+    programImports?: ProgramImports;
+    broadcast?: boolean;
+    unchecked?: boolean;
+}
+
 /**
  * The ProgramManager class is used to execute and deploy programs on the Aleo network and create value transfers.
  */
@@ -316,13 +351,13 @@ class ProgramManager {
         try {
             feeRecord = privateFee
                 ? <RecordPlaintext>(
-                      await this.getCreditsRecord(
-                          priorityFee,
-                          [],
-                          feeRecord,
-                          recordSearchParams,
-                      )
-                  )
+                    await this.getCreditsRecord(
+                        priorityFee,
+                        [],
+                        feeRecord,
+                        recordSearchParams,
+                    )
+                )
                 : undefined;
         } catch (e: any) {
             logAndThrow(
@@ -530,13 +565,13 @@ class ProgramManager {
         try {
             feeRecord = privateFee
                 ? <RecordPlaintext>(
-                      await this.getCreditsRecord(
-                          priorityFee,
-                          [],
-                          feeRecord,
-                          recordSearchParams,
-                      )
-                  )
+                    await this.getCreditsRecord(
+                        priorityFee,
+                        [],
+                        feeRecord,
+                        recordSearchParams,
+                    )
+                )
                 : undefined;
         } catch (e: any) {
             logAndThrow(
@@ -790,6 +825,134 @@ class ProgramManager {
         );
     }
 
+    /**
+     * Builds a `ProvingRequest` for submission to a prover for execution.
+     *
+     * @param {ProvingRequestOptions} options - The options for building the proving request
+     * @returns {Promise<ProvingRequest>} - A promise that resolves to the transaction or an error.
+     *
+     * @example
+     * /// Import the mainnet version of the sdk.
+     * import { AleoKeyProvider, ProgramManager, NetworkRecordProvider } from "@provablehq/sdk/mainnet.js";
+     *
+     * // Create a new NetworkClient, KeyProvider, and RecordProvider.
+     * const keyProvider = new AleoKeyProvider();
+     * const recordProvider = new NetworkRecordProvider(account, networkClient);
+     * keyProvider.useCache = true;
+     *
+     * // Initialize a ProgramManager with the key and record providers.
+     * const programManager = new ProgramManager("https://api.explorer.provable.com/v1", keyProvider, recordProvider);
+     *
+     * // Build the proving request.
+     * const provingRequest = await programManager.provingRequest({
+     *   programName: "credits.aleo",
+     *   functionName: "transfer_public",
+     *   baseFee: 100000,
+     *   priorityFee: 0,
+     *   privateFee: false,
+     *   inputs: [
+     *     "aleo1vwls2ete8dk8uu2kmkmzumd7q38fvshrht8hlc0a5362uq8ftgyqnm3w08",
+     *     "10000000u64",
+     *   ],
+     *   broadcast: false,
+     * });
+     */
+    async provingRequest(
+        options: ProvingRequestOptions,
+    ): Promise<ProvingRequest> {
+        // Destructure the options object to access the parameters.
+        const {
+            programName,
+            functionName,
+            baseFee,
+            priorityFee,
+            privateFee,
+            inputs,
+            recordSearchParams,
+            broadcast = false,
+            unchecked = false,
+        } = options;
+
+        const privateKey = options.privateKey;
+        let program = options.programSource;
+        let feeRecord = options.feeRecord;
+        let imports = options.programImports;
+
+        // Ensure the function exists on the network.
+        if (program === undefined) {
+            try {
+                program = <string>(
+                    await this.networkClient.getProgram(programName)
+                );
+            } catch (e: any) {
+                logAndThrow(
+                    `Error finding ${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 Program) {
+            program = program.toString();
+        }
+
+        // Get the private key from the account if it is not provided in the parameters.
+        let executionPrivateKey = privateKey;
+        if (
+            typeof privateKey === "undefined" &&
+            typeof this.account !== "undefined"
+        ) {
+            executionPrivateKey = this.account.privateKey();
+        }
+
+        if (typeof executionPrivateKey === "undefined") {
+            throw "No private key provided and no private key set in the ProgramManager";
+        }
+
+        // Get the fee record from the account if it is not provided in the parameters.
+        try {
+            feeRecord = privateFee
+                ? <RecordPlaintext>(
+                    await this.getCreditsRecord(
+                        priorityFee,
+                        [],
+                        feeRecord,
+                        recordSearchParams,
+                    )
+                )
+                : undefined;
+        } catch (e: any) {
+            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.`,
+            );
+        }
+
+        // Resolve the program imports if they exist.
+        const numberOfImports = Program.fromString(program).getImports().length;
+        if (numberOfImports > 0 && !imports) {
+            try {
+                imports = <ProgramImports>(
+                    await this.networkClient.getProgramImports(programName)
+                );
+            } catch (e: any) {
+                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 and return the `ProvingRequest`.
+        return await WasmProgramManager.buildProvingRequest(
+            executionPrivateKey,
+            program,
+            functionName,
+            inputs,
+            baseFee,
+            priorityFee,
+            feeRecord,
+            imports,
+            broadcast,
+            unchecked
+        );
+    }
+
     /**
      * Builds a SnarkVM fee `Authorization` for `credits.aleo/fee_private` or `credits.aleo/fee_public`. If a record is provided `fee_private` will be executed, otherwise `fee_public` will be executed.
      *
@@ -1082,13 +1245,13 @@ class ProgramManager {
         try {
             feeRecord = privateFee
                 ? <RecordPlaintext>(
-                      await this.getCreditsRecord(
-                          priorityFee,
-                          [],
-                          feeRecord,
-                          recordSearchParams,
-                      )
-                  )
+                    await this.getCreditsRecord(
+                        priorityFee,
+                        [],
+                        feeRecord,
+                        recordSearchParams,
+                    )
+                )
                 : undefined;
         } catch (e: any) {
             logAndThrow(
@@ -1168,14 +1331,14 @@ class ProgramManager {
         privateKey?: PrivateKey,
         offlineQuery?: OfflineQuery,
     ): Promise<string> {
-         // Get the private key from the account if it is not provided in the parameters
-         let executionPrivateKey = privateKey;
-         if (
-             typeof privateKey === "undefined" &&
-             typeof this.account !== "undefined"
-         ) {
-             executionPrivateKey = this.account.privateKey();
-         }
+        // Get the private key from the account if it is not provided in the parameters
+        let executionPrivateKey = privateKey;
+        if (
+            typeof privateKey === "undefined" &&
+            typeof this.account !== "undefined"
+        ) {
+            executionPrivateKey = this.account.privateKey();
+        }
 
         if (typeof executionPrivateKey === "undefined") {
             throw "No private key provided and no private key set in the ProgramManager";
@@ -1368,13 +1531,13 @@ class ProgramManager {
             }
             feeRecord = privateFee
                 ? <RecordPlaintext>(
-                      await this.getCreditsRecord(
-                          priorityFee,
-                          nonces,
-                          feeRecord,
-                          recordSearchParams,
-                      )
-                  )
+                    await this.getCreditsRecord(
+                        priorityFee,
+                        nonces,
+                        feeRecord,
+                        recordSearchParams,
+                    )
+                )
                 : undefined;
         } catch (e: any) {
             logAndThrow(
@@ -2376,8 +2539,8 @@ function validateTransferType(transferType: string): string {
     return VALID_TRANSFER_TYPES.has(transferType)
         ? transferType
         : logAndThrow(
-              `Invalid transfer type '${transferType}'. Valid transfer types are 'private', 'privateToPublic', 'public', and 'publicToPrivate'.`,
-          );
+            `Invalid transfer type '${transferType}'. Valid transfer types are 'private', 'privateToPublic', 'public', and 'publicToPrivate'.`,
+        );
 }
 
-export { ProgramManager, AuthorizationOptions, FeeAuthorizationOptions, ExecuteOptions };
+export { ProgramManager, AuthorizationOptions, FeeAuthorizationOptions, ExecuteOptions, ProvingRequestOptions };

sdk/src/wasm.ts

@@ -27,6 +27,7 @@ export {
     Program,
     ProgramManager,
     ProvingKey,
+    ProvingRequest,
     RecordCiphertext,
     RecordPlaintext,
     Scalar,

sdk/tests/network-client.test.ts

@@ -323,8 +323,8 @@ describe("NodeConnection", () => {
                     ? testnetAcceptedTx
                     : mainnetAcceptedTx
                 : isTestnet
-                  ? testnetRejectedTx
-                  : mainnetRejectedTx;
+                    ? testnetRejectedTx
+                    : mainnetRejectedTx;
         }
 
         it("should return confirmed transaction data for an accepted tx ID", async () => {