@provablehq/sdk 0.9.13 → 0.9.15-enc

package/dist/mainnet/record-scanner.d.ts

@@ -1,17 +1,29 @@
 import { EncryptedRecord } from "./models/record-provider/encryptedRecord";
+import { CryptoBoxPubKey } from "./models/cryptoBoxPubkey.js";
 import { OwnedFilter } from "./models/record-scanner/ownedFilter";
 import { OwnedRecord } from "./models/record-provider/ownedRecord";
 import { RecordProvider } from "./record-provider";
 import { Field, ViewKey } from "./wasm";
 import { RecordsFilter } from "./models/record-scanner/recordsFilter";
-import { RegistrationResponse } from "./models/record-scanner/registrationResponse";
+import { RegisterResult } from "./models/record-scanner/registrationResult.js";
 import { StatusResponse } from "./models/record-scanner/statusResponse";
+/**
+ * JWT data for optional authentication with the record scanning service (e.g. Provable API).
+ */
+export interface RecordScannerJWTData {
+    jwt: string;
+    expiration: number;
+}
 type RecordScannerOptions = {
     url: string;
     apiKey?: string | {
         header: string;
         value: string;
     };
+    /** Required for JWT refresh when using authenticated record scanner (e.g. Provable API). */
+    consumerId?: string;
+    /** Optional JWT for auth. If omitted and apiKey + consumerId are set, JWT is refreshed when needed. */
+    jwtData?: RecordScannerJWTData;
 };
 /**
  * RecordScanner is a RecordProvider implementation that uses the record scanner service to find records.
@@ -22,7 +34,8 @@ type RecordScannerOptions = {
  * 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,
@@ -58,6 +71,8 @@ declare class RecordScanner implements RecordProvider {
     readonly url: string;
     private apiKey?;
     private uuid?;
+    private consumerId?;
+    private jwtData?;
     constructor(options: RecordScannerOptions);
     /**
      * Set the API key to use for the record scanner.
@@ -68,6 +83,22 @@ declare class RecordScanner implements RecordProvider {
         header: string;
         value: string;
     }): Promise<void>;
+    /**
+     * Set the consumer ID used for JWT refresh when using authenticated record scanner (e.g. Provable API).
+     */
+    setConsumerId(consumerId: string): Promise<void>;
+    /**
+     * Set JWT data for authentication. Optional; when not set, JWT can be refreshed from apiKey + consumerId if provided.
+     */
+    setJwtData(jwtData: RecordScannerJWTData | undefined): Promise<void>;
+    /**
+     * Refreshes the JWT by making a POST request to /jwts/{consumer_id}. Used when authentication is required.
+     */
+    private refreshJwt;
+    /**
+     * Returns auth headers (e.g. Authorization with JWT). Refreshes JWT if expired and apiKey + consumerId are set. Empty when auth is not configured.
+     */
+    private getAuthHeaders;
     /**
      * Set the UUID to use for the record scanner.
      *
@@ -75,12 +106,28 @@ declare class RecordScanner implements RecordProvider {
      */
     setUuid(uuidOrViewKey: Field | ViewKey): Promise<void>;
     /**
-     * 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<RegisterResult>} `{ ok: true, data }` on success, or `{ ok: false, status, error }` on failure.
+     */
+    register(viewKey: ViewKey, startBlock: number): Promise<RegisterResult>;
+    /**
+     * 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.
+     */
+    getPubkey(): Promise<CryptoBoxPubKey>;
+    /**
+     * 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<RegistrationResponse>} The response from the record scanner service.
+     * @returns {Promise<RegisterResult>} `{ ok: true, data }` on success, or `{ ok: false, status, error }` on failure.
      */
-    register(viewKey: ViewKey, startBlock: number): Promise<RegistrationResponse>;
+    registerEncrypted(viewKey: ViewKey, startBlock: number): Promise<RegisterResult>;
     /**
      * Get encrypted records from the record scanner service.
      *
@@ -141,6 +188,7 @@ declare class RecordScanner implements RecordProvider {
     findCreditsRecords(microcreditAmounts: number[], searchParameters: OwnedFilter): Promise<OwnedRecord[]>;
     /**
      * 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.

package/dist/mainnet/security.d.ts

@@ -0,0 +1,38 @@
+import { ViewKey, Authorization, ProvingRequest } from "@provablehq/wasm";
+/**
+ * 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.
+ */
+export declare function encryptAuthorization(publicKey: string, authorization: Authorization): string;
+/**
+ * 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.
+ */
+export declare function encryptProvingRequest(publicKey: string, provingRequest: ProvingRequest): string;
+/**
+ * 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.
+ */
+export declare function encryptViewKey(publicKey: string, viewKey: ViewKey): string;
+/**
+ * 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.
+ */
+export declare function encryptRegistrationRequest(publicKey: string, viewKey: ViewKey, start: number): string;

package/dist/testnet/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/testnet/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";