Build proving request abstraction and supporting methods for generating 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";
@@ -53,7 +55,7 @@ async function initializeWasm() {
 
 export { createAleoWorker } from "./managed-worker.js";
 
-export { ProgramManager } from "./program-manager.js";
+export { ProgramManager, ProvingRequestOptions, ExecuteOptions, FeeAuthorizationOptions, AuthorizationOptions } from "./program-manager.js";
 
 export { logAndThrow } from "./utils.js";
 
@@ -84,6 +86,7 @@ export {
     Program,
     ProgramManager as ProgramManagerBase,
     ProvingKey,
+    ProvingRequest,
     RecordCiphertext,
     RecordPlaintext,
     Signature,
@@ -150,6 +153,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

@@ -24,6 +24,7 @@ import {
     VerifyingKey,
     Transaction,
     ProgramManager as WasmProgramManager,
+    ProvingRequest,
     verifyFunctionExecution,
 } from "./wasm.js";
 
@@ -71,6 +72,39 @@ interface ExecuteOptions {
     imports?: ProgramImports;
 }
 
+/**
+ * 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;
+}
+
 /**
  * Options for building an Authorization for a function.
  *
@@ -696,6 +730,153 @@ 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: true,
+     * });
+     *
+     * // Submit the ProvingRequest to the network and await the response.
+     * const provingResponse = await programManager.networkClient.submitProvingRequest(provingRequest);
+     * // Get the transaction from the proving response.
+     * const tx = provingResponse.transaction;
+     * // Check if the proving service has already submitted the transaction.
+     * const submitted = provingResponse.broadcast;
+     *
+     * // Get the transaction id.
+     * const tx_id = tx.id();
+     *
+     * // If the response doesn't indicate the transaction was submitted, submit it manually.
+     * if (!submitted) {
+     *   await programManager.networkClient.submitTransaction(tx);
+     * }
+     *
+     * // Wait to see if the transaction has appeared on chain.
+     * setTimeout(async () => {
+     *  const transaction = await programManager.networkClient.getTransaction(tx.id());
+     *  assert(transaction.id() === tx.id());
+     * }, 10000);
+     */
+    async provingRequest(
+        options: ProvingRequestOptions,
+    ): Promise<ProvingRequest> {
+        // Destructure the options object to access the parameters.
+        const {
+            programName,
+            functionName,
+            baseFee,
+            priorityFee,
+            privateFee,
+            inputs,
+            recordSearchParams,
+            broadcast = 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
+        );
+    }
+
     /**
      * 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.
      *
@@ -2283,4 +2464,4 @@ function validateTransferType(transferType: string): string {
           );
 }
 
-export { ProgramManager, AuthorizationOptions, FeeAuthorizationOptions, ExecuteOptions };
+export { ProgramManager, AuthorizationOptions, FeeAuthorizationOptions, ExecuteOptions, ProvingRequestOptions };

sdk/src/wasm.ts

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

sdk/tests/network-client.test.ts

@@ -434,15 +434,28 @@ describe("NodeConnection", () => {
             const mappings =
                 await connection.getProgramMappingNames("credits.aleo");
             if (!(mappings instanceof Error)) {
-                expect(mappings).deep.equal([
-                    "committee",
-                    "delegated",
-                    "metadata",
-                    "bonded",
-                    "unbonding",
-                    "account",
-                    "withdraw",
-                ]);
+                if (connection.network == "testnet") {
+                    expect(mappings).deep.equal([
+                        "committee",
+                        "delegated",
+                        "metadata",
+                        "bonded",
+                        "unbonding",
+                        "account",
+                        "withdraw",
+                        "pool"
+                    ]);
+                } else {
+                    expect(mappings).deep.equal([
+                        "committee",
+                        "delegated",
+                        "metadata",
+                        "bonded",
+                        "unbonding",
+                        "account",
+                        "withdraw",
+                    ]);
+                }
             }
         });
     });
@@ -589,7 +602,7 @@ describe("NodeConnection", () => {
             }
         });
 
-        it("should have correct data within the wasm object and summary object for a deployment transaction", async () => {
+        it.skip("should have correct data within the wasm object and summary object for a deployment transaction", async () => {
             // Get the deployment transaction for token_registry.aleo
             if (connection.network === "mainnet") {
                 const transaction = await connection.getTransactionObject("at15mwg0jyhvpjjrfxwrlwzn8puusnmy7r3xzvpjht4e5gzgnp68q9qd0qqec");

sdk/tests/program-manager.test.ts

@@ -8,6 +8,7 @@ import {
     PrivateKey,
     Program,
     ProgramManager,
+    ProvingRequest,
     RecordPlaintext,
     Transaction,
     verifyFunctionExecution,
@@ -108,6 +109,43 @@ describe('Program Manager', () => {
     });
 
     describe('Proving Requests and Authorizations', () => {
+        it('Should build correct authorizations from Proving Request', async () => {
+            // Build a proving request for the "spin" function of "puzzle_spinner_v002.aleo".
+            const provingRequest = await programManager.provingRequest({
+                programName: PUZZLE_SPINNER_PROGRAM_ID,
+                functionName: "spin",
+                baseFee: 1000000,
+                priorityFee: 0,
+                privateFee: false,
+                inputs: [
+                    PUZZLE_SPINNER_V002_INPUT_0,
+                    PUZZLE_SPINNER_V002_INPUT_1,
+                    PUZZLE_SPINNER_V002_INPUT_2,
+                ],
+                broadcast: false,
+                privateKey: PrivateKey.from_string(<string>process.env["PUZZLE_PK"])
+            });
+
+            // Ensure serialization methods lead to the expected.
+            const provingRequestFromString = ProvingRequest.fromString(provingRequest.toString());
+            const provingRequestFromBytes = ProvingRequest.fromBytesLe(provingRequest.toBytesLe());
+
+            // Ensure all authorizations are equal.
+            expect(provingRequestFromString.equals(provingRequestFromBytes));
+            expect(provingRequestFromString.equals(provingRequest));
+
+            // Ensure the broadcast flag is set to false.
+            expect(provingRequest.broadcast()).equal(false);
+
+            // Get the authorizations.
+            const authorization = provingRequest.authorization();
+            const feeAuthorization = <Authorization>provingRequest.feeAuthorization();
+
+            // Ensure the authorizations have the correct number of transitions.
+            expect(authorization.transitions().length).equal(3);
+            expect(feeAuthorization.transitions().length).equal(1);
+        })
+
         it('Should build correct authorizations', async () => {
             // Build an authorization for the spin function of "puzzle_spinner_v002.aleo".
             const authorization = await programManager.buildAuthorization({

wasm/src/programs/manager/mod.rs

@@ -18,6 +18,7 @@ mod authorize;
 mod deploy;
 mod execute;
 mod join;
+mod proving_request;
 mod split;
 mod transfer;