[DPS] Add functionality for encrypting ProvingRequests (#1172)

* Add functionality for encrypting ProvingRequest ciphertexts

* Make cryptobox functions synchronous, enclose private request functions in a retry loop, update delegated proving types

* Add encryption for scanner registration requests

* Modify provingResponse type to handle all possible responses

* Add correct types for the Proving Response + add a ProvingRequestSafe method that enables handling of responses by the caller instead of throwing

* Allow for ProvingResponse types to be BigInts

Author: iamalwaysuncomfortable

sdk/package.json

@@ -56,6 +56,7 @@
     "comlink": "^4.4.2",
     "core-js": "^3.40.0",
     "mime": "^4.0.6",
+    "libsodium-wrappers": "^0.8.2",
     "xmlhttprequest-ssl": "^4.0.0"
   },
   "devDependencies": {

sdk/src/browser.ts

@@ -4,8 +4,10 @@ import { Account } from "./account.js";
 import { AleoNetworkClient, ProgramImports } from "./network-client.js";
 import { BlockJSON, Header, Metadata } from "./models/blockJSON.js";
 import { ConfirmedTransactionJSON } from "./models/confirmed_transaction.js";
+import { CryptoBoxPubKey } from "./models/cryptoBoxPubkey.js";
 import { DeploymentJSON, VerifyingKeys } from "./models/deployment/deploymentJSON.js";
 import { DeploymentObject } from "./models/deployment/deploymentObject.js";
+import { EncryptedProvingRequest } from "./models/encryptedProvingRequest.js";
 import { EncryptedRecord } from "./models/record-provider/encryptedRecord.js";
 import { ExecutionJSON, FeeExecutionJSON } from "./models/execution/executionJSON.js";
 import { ExecutionObject, FeeExecutionObject } from "./models/execution/executionObject.js";
@@ -25,7 +27,7 @@ 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 { ProvingResponse, BroadcastResponse, BroadcastResult, ProvingResult, ProvingFailure, ProvingSuccess, ProveApiErrorBody, ProvingRequestError, isProvingResponse, isProveApiErrorBody } from "./models/provingResponse.js";
 import { RatificationJSON } from "./models/ratification.js";
 import { RecordsFilter } from "./models/record-scanner/recordsFilter.js";
 import { RecordsResponseFilter } from "./models/record-scanner/recordsResponseFilter.js";
@@ -142,10 +144,14 @@ export {
     AleoNetworkClient,
     BlockJSON,
     BlockHeightSearch,
+    BroadcastResponse,
+    BroadcastResult,
     CachedKeyPair,
     ConfirmedTransactionJSON,
+    CryptoBoxPubKey,
     DeploymentJSON,
     DeploymentObject,
+    EncryptedProvingRequest,
     EncryptedRecord,
     ExecutionJSON,
     ExecutionObject,
@@ -157,6 +163,8 @@ export {
     FunctionKeyPair,
     FunctionKeyProvider,
     Header,
+    isProvingResponse,
+    isProveApiErrorBody,
     ImportedPrograms,
     ImportedVerifyingKeys,
     InputJSON,
@@ -177,7 +185,12 @@ export {
     PlaintextObject,
     PlaintextStruct,
     ProgramImports,
+    ProveApiErrorBody,
+    ProvingFailure,
+    ProvingRequestError,
     ProvingRequestJSON,
+    ProvingResult,
+    ProvingSuccess,
     ProvingResponse,
     RatificationJSON,
     RecordsFilter,
@@ -194,3 +207,5 @@ export {
     TransitionObject,
     VerifyingKeys,
 };
+
+export { encryptAuthorization, encryptProvingRequest, encryptViewKey, encryptRegistrationRequest } from "./security.js";

sdk/src/constants.ts

@@ -118,5 +118,5 @@ export const RECORD_DOMAIN = "RecordScannerV0";
  * Zero address on Aleo blockchain that corresponds to field element 0. Used as padding in Merkle trees and as a sentinel value.
  */
 export const ZERO_ADDRESS = "aleo1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq3ljyzc";
-
 export const FIVE_MINUTES = 5 * 60 * 1000; // 5 minutes in milliseconds
+

sdk/src/models/cryptoBoxPubkey.ts

@@ -0,0 +1,4 @@
+export interface CryptoBoxPubKey {
+    key_id: string,
+    public_key: string,
+}

sdk/src/models/encryptedProvingRequest.ts

@@ -0,0 +1,4 @@
+export interface EncryptedProvingRequest {
+    key_id: string,
+    ciphertext: string,
+}

sdk/src/models/provingResponse.ts

@@ -1,6 +1,66 @@
-import { TransactionJSON } from "./transaction/transactionJSON";
+import { TransactionJSON } from "./transaction/transactionJSON.js";
 
+/** HTTP status and optional message from snarkOS broadcast (Accepted/Rejected variants). */
+export interface BroadcastResponse {
+    status_code: bigint | number;
+    message?: string;
+}
+
+/** Result of the optional broadcast step. Discriminated by `status`. */
+export type BroadcastResult =
+    | { status: "Accepted"; status_code: bigint | number; message?: string }
+    | { status: "Rejected"; status_code: bigint | number; message?: string }
+    | { status: "Failed"; message: string }
+    | { status: "Skipped" };
+
+/** Success response body for POST /prove (HTTP 200). */
 export interface ProvingResponse {
-    transaction: TransactionJSON,
-    broadcast?: boolean,
+    transaction: TransactionJSON;
+    broadcast_result: BroadcastResult;
+}
+
+/** Error response body for POST /prove (HTTP 400, 500, 503). Same shape for all error cases. */
+export interface ProveApiErrorBody {
+    message: string;
+}
+
+/** Error thrown on prove API failure; `status` is set for retry logic (e.g. retryWithBackoff checks error.status >= 500). */
+export interface ProvingRequestError extends Error {
+    status?: bigint | number;
+}
+
+/** Success variant of a proving request result. */
+export interface ProvingSuccess {
+    ok: true;
+    data: ProvingResponse;
+}
+
+/** Failure variant of a proving request result (HTTP 400, 500, 503). */
+export interface ProvingFailure {
+    ok: false;
+    status: bigint | number;
+    error: ProveApiErrorBody;
+}
+
+/** Result of a proving request. Type used to give callers the ability to self-handle errors. */
+export type ProvingResult = ProvingSuccess | ProvingFailure;
+
+/** Type guard: value is a ProvingResponse. */
+export function isProvingResponse(value: unknown): value is ProvingResponse {
+    return (
+        typeof value === "object" &&
+        value !== null &&
+        "transaction" in value &&
+        "broadcast_result" in value &&
+        typeof (value as ProvingResponse).broadcast_result === "object"
+    );
+}
+
+/** Type guard: value is a ProveApiErrorBody. */
+export function isProveApiErrorBody(value: unknown): value is ProveApiErrorBody {
+    return (
+        typeof value === "object" &&
+        value !== null &&
+        "message" in value
+    );
 }