@provablehq/sdk 0.9.14 → 0.9.15-enc

package/dist/mainnet/account.d.ts

@@ -52,6 +52,21 @@ export declare class Account {
      * const account = Account.fromCiphertext(process.env.ciphertext, process.env.password);
      */
     static fromCiphertext(ciphertext: PrivateKeyCiphertext | string, password: string): Account;
+    /**
+     * Validates whether the given input is a valid Aleo address.
+     * @param {string | Uint8Array} address The address to validate, either as a string or bytes
+     * @returns {boolean} True if the address is valid, false otherwise
+     *
+     * @example
+     * import { Account } from "@provablehq/sdk/testnet.js";
+     *
+     * const isValid = Account.isValidAddress("aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px");
+     * console.log(isValid); // true
+     *
+     * const isInvalid = Account.isValidAddress("invalid_address");
+     * console.log(isInvalid); // false
+     */
+    static isValidAddress(address: string | Uint8Array): boolean;
     /**
      * Creates a PrivateKey from the provided parameters.
      * @param {AccountParam} params The parameters containing either a private key string or a seed

package/dist/mainnet/browser.d.ts

@@ -3,8 +3,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";
@@ -24,7 +26,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";
@@ -45,4 +47,5 @@ export { logAndThrow } from "./utils.js";
 export { Address, Authorization, Boolean, BHP256, BHP512, BHP768, BHP1024, Ciphertext, ComputeKey, Execution as FunctionExecution, ExecutionRequest, ExecutionResponse, EncryptionToolkit, Field, GraphKey, Group, I8, I16, I32, I64, I128, OfflineQuery, Pedersen64, Pedersen128, Plaintext, Poseidon2, Poseidon4, Poseidon8, PrivateKey, PrivateKeyCiphertext, Program, ProgramManager as ProgramManagerBase, ProvingKey, ProvingRequest, RecordCiphertext, RecordPlaintext, Signature, Scalar, Transaction, Transition, U8, U16, U32, U64, U128, VerifyingKey, ViewKey, initThreadPool, getOrInitConsensusVersionTestHeights, verifyFunctionExecution, } from "./wasm.js";
 export { initializeWasm };
 export { Key, CREDITS_PROGRAM_KEYS, KEY_STORE, PRIVATE_TRANSFER, PRIVATE_TO_PUBLIC_TRANSFER, PRIVATE_TRANSFER_TYPES, PUBLIC_TRANSFER, PUBLIC_TRANSFER_AS_SIGNER, PUBLIC_TO_PRIVATE_TRANSFER, RECORD_DOMAIN, VALID_TRANSFER_TYPES, } from "./constants.js";
-export { Account, AleoKeyProvider, AleoKeyProviderParams, AleoKeyProviderInitParams, AleoNetworkClient, BlockJSON, BlockHeightSearch, CachedKeyPair, ConfirmedTransactionJSON, DeploymentJSON, DeploymentObject, EncryptedRecord, ExecutionJSON, ExecutionObject, FeeExecutionJSON, FeeExecutionObject, FinalizeJSON, FunctionInput, FunctionObject, FunctionKeyPair, FunctionKeyProvider, Header, ImportedPrograms, ImportedVerifyingKeys, InputJSON, InputObject, KeySearchParams, Metadata, NetworkRecordProvider, OfflineKeyProvider, OfflineSearchParams, OutputJSON, OutputObject, OwnedFilter, OwnedRecord, OwnerJSON, PartialSolutionJSON, PlaintextArray, PlaintextLiteral, PlaintextObject, PlaintextStruct, ProgramImports, ProvingRequestJSON, ProvingResponse, RatificationJSON, RecordsFilter, RecordsResponseFilter, RecordProvider, RecordScanner, RecordSearchParams, SealanceMerkleTree, SolutionJSON, SolutionsJSON, TransactionJSON, TransactionObject, TransitionJSON, TransitionObject, VerifyingKeys, };
+export { Account, AleoKeyProvider, AleoKeyProviderParams, AleoKeyProviderInitParams, AleoNetworkClient, BlockJSON, BlockHeightSearch, BroadcastResponse, BroadcastResult, CachedKeyPair, ConfirmedTransactionJSON, CryptoBoxPubKey, DeploymentJSON, DeploymentObject, EncryptedProvingRequest, EncryptedRecord, ExecutionJSON, ExecutionObject, FeeExecutionJSON, FeeExecutionObject, FinalizeJSON, FunctionInput, FunctionObject, FunctionKeyPair, FunctionKeyProvider, Header, isProvingResponse, isProveApiErrorBody, ImportedPrograms, ImportedVerifyingKeys, InputJSON, InputObject, KeySearchParams, Metadata, NetworkRecordProvider, OfflineKeyProvider, OfflineSearchParams, OutputJSON, OutputObject, OwnedFilter, OwnedRecord, OwnerJSON, PartialSolutionJSON, PlaintextArray, PlaintextLiteral, PlaintextObject, PlaintextStruct, ProgramImports, ProveApiErrorBody, ProvingFailure, ProvingRequestError, ProvingRequestJSON, ProvingResult, ProvingSuccess, ProvingResponse, RatificationJSON, RecordsFilter, RecordsResponseFilter, RecordProvider, RecordScanner, RecordSearchParams, SealanceMerkleTree, SolutionJSON, SolutionsJSON, TransactionJSON, TransactionObject, TransitionJSON, TransitionObject, VerifyingKeys, };
+export { encryptAuthorization, encryptProvingRequest, encryptViewKey, encryptRegistrationRequest } from "./security.js";

package/dist/mainnet/browser.js

@@ -1,6 +1,7 @@
 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, verifyFunctionExecution } from '@provablehq/wasm/mainnet.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, ProvingKey, ProvingRequest, RecordCiphertext, RecordPlaintext, Scalar, Signature, Transaction, Transition, U128, U16, U32, U64, U8, VerifyingKey, ViewKey, getOrInitConsensusVersionTestHeights, initThreadPool, verifyFunctionExecution } from '@provablehq/wasm/mainnet.js';
+import sodium from 'libsodium-wrappers';
 import { bech32m } from '@scure/base';
 
 /**
@@ -72,6 +73,23 @@ class Account {
             throw new Error("Wrong password or invalid ciphertext");
         }
     }
+    /**
+     * Validates whether the given input is a valid Aleo address.
+     * @param {string | Uint8Array} address The address to validate, either as a string or bytes
+     * @returns {boolean} True if the address is valid, false otherwise
+     *
+     * @example
+     * import { Account } from "@provablehq/sdk/testnet.js";
+     *
+     * const isValid = Account.isValidAddress("aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px");
+     * console.log(isValid); // true
+     *
+     * const isInvalid = Account.isValidAddress("invalid_address");
+     * console.log(isInvalid); // false
+     */
+    static isValidAddress(address) {
+        return Address.isValid(address);
+    }
     /**
      * Creates a PrivateKey from the provided parameters.
      * @param {AccountParam} params The parameters containing either a private key string or a seed
@@ -466,6 +484,91 @@ async function retryWithBackoff(fn, { maxAttempts = 5, baseDelay = 100, jitter,
     throw new Error("retryWithBackoff: unreachable");
 }
 
+/** Type guard: value is a ProvingResponse. */
+function isProvingResponse(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "transaction" in value &&
+        "broadcast_result" in value &&
+        typeof value.broadcast_result === "object");
+}
+/** Type guard: value is a ProveApiErrorBody. */
+function isProveApiErrorBody(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "message" in value);
+}
+
+await sodium.ready;
+/**
+ * Encrypt an authorization with a libsodium cryptobox public key.
+ *
+ * @param {string} publicKey The cryptobox X25519 public key to encrypt with (encoded in RFC 4648 standard Base64).
+ * @param {Authorization} authorization the authorization to encrypt.
+ *
+ * @returns {string} the encrypted authorization in RFC 4648 standard Base64.
+ */
+function encryptAuthorization(publicKey, authorization) {
+    // Ready the cryptobox lib.
+    return encryptMessage(publicKey, authorization.toBytesLe());
+}
+/**
+ * Encrypt a ProvingRequest with a libsodium cryptobox public key.
+ *
+ * @param {string} publicKey The cryptobox X25519 public key to encrypt with (encoded in RFC 4648 standard Base64).
+ * @param {Authorization} provingRequest the ProvingRequest to encrypt.
+ *
+ * @returns {string} the encrypted ProvingRequest in RFC 4648 standard Base64.
+ */
+function encryptProvingRequest(publicKey, provingRequest) {
+    return encryptMessage(publicKey, provingRequest.toBytesLe());
+}
+/**
+ * Encrypt a view key with a libsodium cryptobox public key.
+ *
+ * @param {string} publicKey The cryptobox X25519 public key to encrypt with (encoded in RFC 4648 standard Base64).
+ * @param {ViewKey} viewKey the view key to encrypt.
+ *
+ * @returns {string} the encrypted view key in RFC 4648 standard Base64.
+ */
+function encryptViewKey(publicKey, viewKey) {
+    return encryptMessage(publicKey, viewKey.toBytesLe());
+}
+/**
+ * Encrypt a record scanner registration request.
+ *
+ * @param {string} publicKey The cryptobox X25519 public key to encrypt with (encoded in RFC 4648 standard Base64).
+ * @param {ViewKey} viewKey the view key to encrypt.
+ * @param {number} start the start height of the registration request.
+ *
+ * @returns {string} the encrypted view key in RFC 4648 standard Base64.
+ */
+function encryptRegistrationRequest(publicKey, viewKey, start) {
+    // Turn the view key into a Uint8Array.
+    const vk_bytes = viewKey.toBytesLe();
+    // Create a new array to hold the original bytes and the 4-byte start height.
+    const bytes = new Uint8Array(vk_bytes.length + 4);
+    // Copy existing bytes.
+    bytes.set(vk_bytes, 0);
+    // Write the 4-byte number in LE format at the end of the array.
+    const view = new DataView(bytes.buffer);
+    view.setUint32(vk_bytes.length, start, true);
+    // Encrypt the encoded bytes.
+    return encryptMessage(publicKey, bytes);
+}
+/**
+ * Encrypt arbitrary bytes with a libsodium cryptobox public key.
+ *
+ * @param {string} publicKey The cryptobox X25519 public key to encrypt with (encoded in RFC 4648 standard Base64).
+ * @param {Uint8Array} message the bytes to encrypt.
+ *
+ * @returns {string} the encrypted bytes in RFC 4648 standard Base64.
+ */
+function encryptMessage(publicKey, message) {
+    const publicKeyBytes = sodium.from_base64(publicKey, sodium.base64_variants.ORIGINAL);
+    return sodium.to_base64(sodium.crypto_box_seal(message, publicKeyBytes), sodium.base64_variants.ORIGINAL);
+}
+
 const KEY_STORE = Metadata.baseUrl();
 function convert(metadata) {
     // This looks up the method name in VerifyingKey
@@ -591,18 +694,37 @@ class AleoNetworkClient {
     apiKey;
     consumerId;
     jwtData;
+    proverUri;
+    recordScannerUri;
     constructor(host, options) {
         this.host = host + "/mainnet";
         this.network = "mainnet";
         this.ctx = {};
         this.verboseErrors = true;
-        if (options && options.headers) {
-            this.headers = options.headers;
+        if (options) {
+            if (options.headers) {
+                this.headers = options.headers;
+            }
+            else {
+                this.headers = {
+                    // This is replaced by the actual version by a Rollup plugin
+                    "X-Aleo-SDK-Version": "0.9.15-enc",
+                    "X-Aleo-environment": environment(),
+                };
+            }
+            // If a prover uri was specified, set the prover uri.
+            if (options.proverUri) {
+                this.proverUri = options.proverUri + "/mainnet";
+            }
+            // If a record scanner uri was specified, set the record scanner uri.
+            if (options.recordScannerUri) {
+                this.recordScannerUri = options.recordScannerUri + "/mainnet";
+            }
         }
         else {
             this.headers = {
                 // This is replaced by the actual version by a Rollup plugin
-                "X-Aleo-SDK-Version": "0.9.14",
+                "X-Aleo-SDK-Version": "0.9.15-enc",
                 "X-Aleo-environment": environment(),
             };
         }
@@ -647,6 +769,40 @@ class AleoNetworkClient {
     setHost(host) {
         this.host = host + "/mainnet";
     }
+    /**
+     * Set a new uri for a remote prover.
+     *
+     * @param {string} proverUri The uri of the remote prover.
+     *
+     * @example
+     * import { AleoNetworkClient } from "@provablehq/sdk/mainnet.js";
+     *
+     * // Create a networkClient that connects to the provable explorer api.
+     * const networkClient = new AleoNetworkClient("http://api.explorer.provable.com/v1", undefined);
+     *
+     * // Set the prover uri.
+     * networkClient.setProverUri("https://prover.provable.prove");
+     */
+    setProverUri(proverUri) {
+        this.proverUri = proverUri + "/mainnet";
+    }
+    /**
+     * Set a new uri for a remote record scanner.
+     *
+     * @param {string} recordScannerUri The uri of the remote record scanner.
+     *
+     * @example
+     * import { AleoNetworkClient } from "@provablehq/sdk/mainnet.js";
+     *
+     * // Create a networkClient that connects to the provable explorer api.
+     * const networkClient = new AleoNetworkClient("http://api.explorer.provable.com/v1", undefined);
+     *
+     * // Set the record scanner uri.
+     * networkClient.setRecordScannerUri("https://scanner.provable.scan");
+     */
+    setRecordScannerUri(recordScannerUri) {
+        this.recordScannerUri = recordScannerUri + "/mainnet";
+    }
     /**
      * Set verbose errors to true or false for the `AleoNetworkClient`. When set to true, if `submitTransaction` fails, the failure responses will report descriptive information as to why the transaction failed.
      *
@@ -1972,33 +2128,87 @@ class AleoNetworkClient {
         };
     }
     /**
-     * Submit a `ProvingRequest` to a remote proving service for delegated proving. If the broadcast flag of the `ProvingRequest` is set to `true` the remote service will attempt to broadcast the result `Transaction` on behalf of the requestor.
+     * Parses a /prove or /prove/encrypted response. Returns a result object (never throws for 200/400/500/503).
+     */
+    async handleProvingResponse(response) {
+        // Get the proving response text.
+        const text = await response.text();
+        let body;
+        // Parse the body.
+        try {
+            body = parseJSON(text);
+        }
+        catch {
+            body = {};
+        }
+        // If the status is 200, attempt to parse the Proving Request along its expected structure.
+        if (response.status === 200) {
+            if (isProvingResponse(body)) {
+                return { ok: true, data: body };
+            }
+            return {
+                ok: false,
+                status: response.status,
+                error: { message: "Invalid response from proving service" },
+            };
+        }
+        // If the response is non 200, return the information back to the caller so it can be handled.
+        if (response.status === 400 || response.status === 500 || response.status === 503) {
+            const error = isProveApiErrorBody(body)
+                ? body
+                : { message: text || `${response.status} error` };
+            return { ok: false, status: response.status, error };
+        }
+        return {
+            ok: false,
+            status: response.status,
+            error: { message: text || `${response.status} error` },
+        };
+    }
+    /**
+     * Submit a `ProvingRequest` to a remote proving service for delegated proving. If the broadcast flag of the `ProvingRequest` is set to `true` the remote service will attempt to broadcast the result `Transaction` on behalf of the requestor. Throws on HTTP 400, 500, 503 (and retries on 500/503). Callers should {@link submitProvingRequestSafe} to handle proving request failures without throwing.
      *
      * @param {DelegatedProvingParams} options - The optional parameters required to submit a proving request.
      * @returns {Promise<ProvingResponse>} The ProvingResponse containing the transaction result and the result of the broadcast if the `broadcast` flag was set to `true`.
      */
     async submitProvingRequest(options) {
-        const proverUri = options.url ?? this.host;
+        const result = await this.submitProvingRequestSafe(options);
+        if (result.ok) {
+            return result.data;
+        }
+        const err = new Error(result.error.message);
+        err.status = result.status;
+        throw err;
+    }
+    /**
+     * Submit a proving request and return a result object instead of throwing. This method is usable when callers want to handle HTTP status (400, 500, 503) yourself. Retries on 500/503 and returns on 200 or 400.
+     *
+     * @param {DelegatedProvingParams} options - The optional parameters required to submit a proving request.
+     * @returns {Promise<ProvingResult>} `{ ok: true, data }` on success (200), or `{ ok: false, status, error }` on 400/500/503. Check `result.ok` and then either `result.data` or `result.status` / `result.error.message`.
+     */
+    async submitProvingRequestSafe(options) {
+        // Attempt to get the Prover URI first from the options, then from any configured globally, or third try the main configured host.
+        const proverUri = (options.url ?? this.proverUri) ?? this.host;
         const provingRequestString = options.provingRequest instanceof ProvingRequest
             ? options.provingRequest.toString()
             : options.provingRequest;
+        // Try to get JWT data to access the Provable API.
         const apiKey = options.apiKey ?? this.apiKey;
         const consumerId = options.consumerId ?? this.consumerId;
         let jwtData = options.jwtData ?? this.jwtData;
-        // Check if JWT is expired or missing
-        const bufferTime = FIVE_MINUTES; // 5 minutes buffer
-        const isExpired = jwtData && Date.now() >= jwtData.expiration - bufferTime;
+        // Check to see if the JWT needs refreshing.
+        const isExpired = jwtData && Date.now() >= jwtData.expiration - FIVE_MINUTES;
         if (!jwtData || isExpired) {
             if (options.apiKey && options.consumerId) {
                 jwtData = await this.refreshJwt(apiKey, consumerId);
-                // Update both the class and the options with the new JWT
                 this.jwtData = jwtData;
                 options.jwtData = jwtData;
             }
             else {
-                throw new Error('JWT or both apiKey and consumerId are required');
+                console.warn('JWT or both apiKey and consumerId are required when using the Provable API');
             }
         }
+        // Create the necessary headers to hit the provable api.
         const headers = {
             ...this.headers,
             "X-ALEO-METHOD": "submitProvingRequest",
@@ -2007,17 +2217,67 @@ class AleoNetworkClient {
         if (jwtData?.jwt) {
             headers["Authorization"] = jwtData.jwt;
         }
-        try {
-            const response = await retryWithBackoff(() => post(`${proverUri}`, {
+        // Encapsulate the requests in a locally scoped function that can be run with a retry closure.
+        const runRequest = async () => {
+            // If DPS privacy is set, call invoke the encrypted flow.
+            if (options.dpsPrivacy) {
+                // Get an ephemeral public key from a DPS service.
+                const pubKeyResponse = await get(proverUri + "/pubkey", {
+                    headers,
+                });
+                // Encrypt the provingRequest.
+                const pubkey = parseJSON(await pubKeyResponse.text());
+                const ciphertext = encryptProvingRequest(pubkey.public_key, ProvingRequest.fromString(provingRequestString));
+                // Form the expected query a DPS service expects (including the key_id).
+                const payload = {
+                    key_id: pubkey.key_id,
+                    ciphertext: ciphertext,
+                };
+                const res = await fetch(`${proverUri}/prove/encrypted`, {
+                    method: "POST",
+                    body: JSON.stringify(payload),
+                    headers,
+                });
+                // Properly handle the proving response.
+                return this.handleProvingResponse(res);
+            }
+            // If encrypted usage is not specified use the unencrypted endpoint.
+            const proveEndpoint = proverUri.endsWith("/prove")
+                ? proverUri
+                : proverUri + "/prove";
+            const res = await fetch(proveEndpoint, {
+                method: "POST",
                 body: provingRequestString,
-                headers
-            }));
-            const responseText = await response.text();
-            return parseJSON(responseText);
+                headers,
+            });
+            // Properly handle the proving response.
+            return this.handleProvingResponse(res);
+        };
+        try {
+            // Run the request with retries.
+            return await retryWithBackoff(async () => {
+                // Run the encrypted or non-encrypted flow as specified by the flags.
+                const result = await runRequest();
+                if (result.ok) {
+                    return result;
+                }
+                // If 500s are hit responses are returned, attempt retries.
+                if (result.status === 500 || result.status === 503) {
+                    const err = new Error(result.error.message);
+                    err.status = result.status;
+                    throw err;
+                }
+                return result;
+            });
         }
-        catch (error) {
-            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-            throw new Error(`Failed to submit proving request: ${errorMessage}`);
+        catch (err) {
+            // If an error is returned, provide usable information to the caller.
+            const e = err;
+            return {
+                ok: false,
+                status: e.status ?? 500,
+                error: { message: e.message },
+            };
         }
     }
     /**
@@ -3333,6 +3593,20 @@ class BlockHeightSearch {
     }
 }
 
+/**
+ * Error thrown when a record scanner request fails (e.g. /register, /register/encrypted).
+ * Includes HTTP status so callers can handle 422 vs 500 etc.
+ */
+class RecordScannerRequestError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = "RecordScannerRequestError";
+        this.status = status;
+        Object.setPrototypeOf(this, RecordScannerRequestError.prototype);
+    }
+}
+
 /**
  * RecordScanner is a RecordProvider implementation that uses the record scanner service to find records.
  *
@@ -3342,7 +3616,8 @@ class BlockHeightSearch {
  * const recordScanner = new RecordScanner({ url: "https://record-scanner.aleo.org" });
  * recordScanner.setAccount(account);
  * recordScanner.setApiKey("your-api-key");
- * const uuid = await recordScanner.register(0);
+ * const result = await recordScanner.register(viewKey, 0);
+ * if (result.ok) { const uuid = result.data.uuid; }
  *
  * const filter = {
  *     uuid,
@@ -3378,9 +3653,21 @@ class RecordScanner {
     url;
     apiKey;
     uuid;
+    consumerId;
+    jwtData;
     constructor(options) {
-        this.url = options.url;
+        // Set the network by detecting which version of the SDK is being used.
+        const network = "/mainnet";
+        // If the user has configured a network in their uri, throw
+        if (options.url.endsWith("/mainnet") || options.url.endsWith("/testnet")) {
+            throw new Error("The record scanning url should not include the specific network, this is automatically configured by the Provable SDK.");
+        }
+        // Configure the url to use the network the SDK is using.
+        this.url = options.url + network;
+        // Configure authentication options/
         this.apiKey = typeof options.apiKey === "string" ? { header: "X-Provable-API-Key", value: options.apiKey } : options.apiKey;
+        this.consumerId = options.consumerId;
+        this.jwtData = options.jwtData;
     }
     /**
      * Set the API key to use for the record scanner.
@@ -3390,6 +3677,59 @@ class RecordScanner {
     async setApiKey(apiKey) {
         this.apiKey = typeof apiKey === "string" ? { header: "X-Provable-API-Key", value: apiKey } : apiKey;
     }
+    /**
+     * Set the consumer ID used for JWT refresh when using authenticated record scanner (e.g. Provable API).
+     */
+    async setConsumerId(consumerId) {
+        this.consumerId = consumerId;
+    }
+    /**
+     * Set JWT data for authentication. Optional; when not set, JWT can be refreshed from apiKey + consumerId if provided.
+     */
+    async setJwtData(jwtData) {
+        this.jwtData = jwtData;
+    }
+    /**
+     * Refreshes the JWT by making a POST request to /jwts/{consumer_id}. Used when authentication is required.
+     */
+    async refreshJwt(apiKey, consumerId) {
+        const response = await post(`https://api.provable.com/jwts/${consumerId}`, {
+            headers: {
+                "X-Provable-API-Key": apiKey,
+            },
+        });
+        const authHeader = response.headers.get("authorization");
+        if (!authHeader) {
+            throw new Error("No authorization header in JWT refresh response");
+        }
+        const body = await response.json();
+        return {
+            jwt: authHeader,
+            expiration: body.exp * 1000, // Convert to milliseconds
+        };
+    }
+    /**
+     * Returns auth headers (e.g. Authorization with JWT). Refreshes JWT if expired and apiKey + consumerId are set. Empty when auth is not configured.
+     */
+    async getAuthHeaders() {
+        let jwtData = this.jwtData;
+        const isExpired = jwtData && Date.now() >= jwtData.expiration - FIVE_MINUTES;
+        if (!jwtData || isExpired) {
+            const apiKey = this.apiKey?.value;
+            if (apiKey && this.consumerId) {
+                jwtData = await this.refreshJwt(apiKey, this.consumerId);
+                this.jwtData = jwtData;
+            }
+            else if (jwtData?.jwt) {
+                // Use existing JWT even if expired when we can't refresh
+                return { Authorization: jwtData.jwt };
+            }
+            else {
+                return {};
+            }
+        }
+        return jwtData?.jwt ? { Authorization: jwtData.jwt } : {};
+    }
     /**
      * Set the UUID to use for the record scanner.
      *
@@ -3399,14 +3739,15 @@ class RecordScanner {
         this.uuid = uuidOrViewKey instanceof ViewKey ? this.computeUUID(uuidOrViewKey) : uuidOrViewKey;
     }
     /**
-     * Register the account with the record scanner service.
+     * Register the account with the record scanner service (unencrypted POST /register). Does not throw if a valid error response from the record scanner is received; returns a result object instead.
      *
+     * @param {ViewKey} viewKey The view key to register.
      * @param {number} startBlock The block height to start scanning from.
-     * @returns {Promise<RegistrationResponse>} The response from the record scanner service.
+     * @returns {Promise<RegisterResult>} `{ ok: true, data }` on success, or `{ ok: false, status, error }` on failure.
      */
     async register(viewKey, startBlock) {
         try {
-            let request = {
+            const request = {
                 view_key: viewKey.to_string(),
                 start: startBlock,
             };
@@ -3417,11 +3758,63 @@ class RecordScanner {
             }));
             const data = await response.json();
             this.uuid = data.uuid;
-            return data;
+            return { ok: true, data };
         }
-        catch (error) {
-            console.error(`Failed to register view key: ${error}`);
-            throw error;
+        catch (err) {
+            if (err instanceof RecordScannerRequestError) {
+                return {
+                    ok: false,
+                    status: err.status,
+                    error: { message: err.message },
+                };
+            }
+            console.error(`Failed to register view key: ${err}`);
+            throw err;
+        }
+    }
+    /**
+     * Fetches an ephemeral public key from the record scanner service for use with registerEncrypted.
+     * Follows the same pattern as the delegated proving service /pubkey endpoint.
+     *
+     * @returns {Promise<CryptoBoxPubKey>} The service's ephemeral public key and key_id.
+     */
+    async getPubkey() {
+        const response = await this.request(new Request(`${this.url}/pubkey`, { method: "GET" }));
+        return parseJSON(await response.text());
+    }
+    /**
+     * Registers the account with the record scanner service using the encrypted flow: 1. fetches an ephemeral public key from /pubkey - 2. encrypts the registration request (view key + start block) - 3. POSTs to /register/encrypted. Does not HTTP error on a proper error response from the record scanner; returns a result object instead.
+     *
+     * @param {ViewKey} viewKey The view key to register.
+     * @param {number} startBlock The block height to start scanning from.
+     * @returns {Promise<RegisterResult>} `{ ok: true, data }` on success, or `{ ok: false, status, error }` on failure.
+     */
+    async registerEncrypted(viewKey, startBlock) {
+        try {
+            const pubkey = await this.getPubkey();
+            const ciphertext = encryptRegistrationRequest(pubkey.public_key, viewKey, startBlock);
+            const payload = {
+                key_id: pubkey.key_id,
+                ciphertext,
+            };
+            const response = await this.request(new Request(`${this.url}/register/encrypted`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(payload),
+            }));
+            const data = await response.json();
+            this.uuid = data.uuid;
+            return { ok: true, data };
+        }
+        catch (err) {
+            if (err instanceof RecordScannerRequestError) {
+                return {
+                    ok: false,
+                    status: err.status,
+                    error: { message: err.message },
+                };
+            }
+            throw err;
         }
     }
     /**
@@ -3614,18 +4007,24 @@ class RecordScanner {
     }
     /**
      * Wrapper function to make a request to the record scanner service and handle any errors.
+     * Optionally adds JWT Authorization header when consumerId/jwtData (or apiKey+consumerId) are configured.
      *
      * @param {Request} req The request to make.
      * @returns {Promise<Response>} The response.
      */
     async request(req) {
         try {
+            const authHeaders = await this.getAuthHeaders();
+            for (const [key, value] of Object.entries(authHeaders)) {
+                req.headers.set(key, value);
+            }
             if (this.apiKey) {
                 req.headers.set(this.apiKey.header, this.apiKey.value);
             }
             const response = await fetch(req);
             if (!response.ok) {
-                throw new Error(await response.text() ?? `Request to ${req.url} failed with status ${response.status}`);
+                const text = await response.text();
+                throw new RecordScannerRequestError(text || `Request to ${req.url} failed with status ${response.status}`, response.status);
             }
             return response;
         }
@@ -6623,5 +7022,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, KEY_STORE, 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, RecordScanner, SealanceMerkleTree, VALID_TRANSFER_TYPES, initializeWasm, logAndThrow };
+export { Account, AleoKeyProvider, AleoKeyProviderParams, AleoNetworkClient, BlockHeightSearch, CREDITS_PROGRAM_KEYS, KEY_STORE, 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, RecordScanner, SealanceMerkleTree, VALID_TRANSFER_TYPES, encryptAuthorization, encryptProvingRequest, encryptRegistrationRequest, encryptViewKey, initializeWasm, isProveApiErrorBody, isProvingResponse, logAndThrow };
 //# sourceMappingURL=browser.js.map