@provablehq/sdk 0.9.10-testnet-rc → 0.9.11

package/dist/testnet/constants.d.ts

@@ -33,3 +33,7 @@ export declare const PUBLIC_TRANSFER: Set<string>;
 export declare const PUBLIC_TRANSFER_AS_SIGNER: Set<string>;
 export declare const PUBLIC_TO_PRIVATE_TRANSFER: Set<string>;
 export declare 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 declare const ZERO_ADDRESS = "aleo1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq3ljyzc";

package/dist/testnet/integrations/sealance/merkle-tree.d.ts

@@ -0,0 +1,121 @@
+import { Field } from "../../wasm.js";
+/**
+ * Client library that encapsulates methods for constructing Merkle exclusion proofs for compliant stablecoin programs following the Sealance architecture.
+ *
+
+ * @example
+ * Construct a Merkle exclusion proof.
+ *  ```typescript
+ * const sealance = new SealanceMerkleTree();
+ * const leaves = [
+ *      "aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px",
+ *      "aleo1s3ws5tra87fjycnjrwsjcrnw2qxr8jfqqdugnf0xzqqw29q9m5pqem2u4t",
+ *      "aleo1s3ws5tra87fjycnjrwsjcrnw2qxr8jfqqdugnf0xzqqw29q9m5pqem2u4t",
+ *    ];
+ * const result = sealance.generateLeaves(leaves);
+ * const tree = sealance.buildTree(result);
+ * const [leftIdx, rightIdx] = sealance.getLeafIndices(tree, "aleo1kypwp5m7qtk9mwazgcpg0tq8aal23mnrvwfvug65qgcg9xvsrqgspyjm6n");
+ * const proof_left = sealance.getSiblingPath(tree, leftIdx, 15);
+ * const proof_right = sealance.getSiblingPath(tree, rightIdx, 15);
+ * const exclusion_proof = [proof_left, proof_right];
+ * ```
+ */
+declare class SealanceMerkleTree {
+    private static hasher;
+    /**
+    * Converts an Aleo blockchain address to a field element.
+    *
+    * This function decodes a bech32m-encoded Aleo address and converts it to a field element
+    * represented as a BigInt. The address format follows the Aleo protocol specification,
+    * starting with the prefix "aleo1" followed by encoded data.
+    *
+    * @param address - The Aleo blockchain address (e.g., "aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px")
+    * @returns A BigInt representing the field element.
+    * @throws Error if the address is invalid or cannot be decoded.
+    *
+    * @example
+    * ```typescript
+    * const address = "aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px";
+    * const fieldValue = convertAddressToField(address);
+    * console.log(fieldValue); // 123456789...n
+    * ```
+    */
+    convertAddressToField(address: string): bigint;
+    /**
+    * Hashes two elements using Poseidon4 hash function
+    * @param prefix - Prefix for the hash (e.g., "0field" for nodes, "1field" for leaves)
+    * @param el1 - First element to hash
+    * @param el2 - Second element to hash
+    * @returns The hash result as a Field
+    * @throws {Error} If inputs are empty or invalid
+    */
+    hashTwoElements(prefix: string, el1: string, el2: string): Field;
+    /**
+    * Builds a Merkle tree from given leaves. The tree is built bottom-up, hashing pairs of elements at each level.
+    *
+    * @param leaves - Array of leaf elements (must have even number of elements).
+    * @returns Array representing the complete Merkle tree as BigInts.
+    * @throws {Error} If leaves array is empty or has odd number of elements.
+    *
+    * @example
+    * ```typescript
+    * const leaves = ["0field", "1field", "2field", "3field"];
+    * const tree = buildTree(leaves);
+    * const root = tree[tree.length - 1]; // Get the Merkle root
+    * ```
+    */
+    buildTree(leaves: string[]): bigint[];
+    /**
+    * Converts Aleo addresses to field elements, sorts them, pads with zero fields, and returns an array. This prepares addresses for Merkle tree construction.
+    *
+    * @param addresses - Array of Aleo addresses.
+    * @param maxTreeDepth - Maximum depth of the Merkle tree (default: 15).
+    * @returns Array of field elements ready for Merkle tree construction.
+    * @throws {Error} If the number of addresses exceeds the maximum capacity.
+    *
+    * @example
+    * ```typescript
+    * const addresses = [
+    *   "aleo1...",
+    *   "aleo1..."
+    * ];
+    * const leaves = generateLeaves(addresses, 15);
+    * const tree = buildTree(leaves);
+    * ```
+    */
+    generateLeaves(addresses: string[], maxTreeDepth?: number): string[];
+    /**
+    * Finds the leaf indices for non-inclusion proof of an address and returns the indices of the two adjacent leaves that surround the target address.
+    *
+    * @param merkleTree - The complete Merkle tree as array of BigInts.
+    * @param address - The Aleo address for which to find indices.
+    * @returns Tuple of [leftLeafIndex, rightLeafIndex].
+    *
+    * @example
+    * ```typescript
+    * const tree = buildTree(leaves);
+    * const [leftIdx, rightIdx] = getLeafIndices(tree, "aleo1...");
+    * ```
+    */
+    getLeafIndices(merkleTree: bigint[], address: string): [number, number];
+    /**
+    * Generates the sibling path (Merkle proof) for a given leaf index
+    *
+    * @param tree - The complete Merkle tree.
+    * @param leafIndex - Index of the leaf for which to generate the proof.
+    * @param depth - Maximum depth of the tree.
+    * @returns Object containing siblings array and leaf_index.
+    *
+    * @example
+    * ```typescript
+    * const tree = buildTree(leaves);
+    * const proof = getSiblingPath(tree, 0, 15);
+    * // proof = { siblings: [0n, 1n, ...], leaf_index: 0 }
+    * ```
+    */
+    getSiblingPath(tree: bigint[], leafIndex: number, depth: number): {
+        siblings: bigint[];
+        leaf_index: number;
+    };
+}
+export { SealanceMerkleTree };

package/dist/testnet/node.js

@@ -1,5 +1,5 @@
 import './node-polyfill.js';
-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, VALID_TRANSFER_TYPES, initializeWasm, logAndThrow } from './browser.js';
+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 } from './browser.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/testnet.js';
 import 'core-js/proposals/json-parse-with-source.js';
 import 'node:crypto';
@@ -9,4 +9,5 @@ import 'xmlhttprequest-ssl';
 import 'sync-request';
 import 'node:worker_threads';
 import 'node:os';
+import '@scure/base';
 //# sourceMappingURL=node.js.map

package/dist/testnet/node.js.map

@@ -1 +1 @@
-{"version":3,"file":"node.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;"}
+{"version":3,"file":"node.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;"}

package/dist/testnet/program-manager.d.ts

@@ -45,12 +45,13 @@ interface ExecuteOptions {
 /**
  * Options for building an Authorization for a function.
  *
- * @property programName {string} Name of the program containing the function to build the authorization for.
- * @property functionName {string} Name of the function name to build the authorization for.
- * @property inputs {string[]} The inputs to the function.
- * @property programSource {string | Program} The optional source code for the program to build an execution for.
- * @property privateKey {PrivateKey} Optional private key to use to build the authorization.
- * @property programImports {ProgramImports} The other programs the program imports.
+ * @property {string} programName Name of the program containing the function to build the authorization for.
+ * @property {string} functionName Name of the function name to build the authorization for.
+ * @property {string[]} inputs The inputs to the function.
+ * @property {string | Program} [programSource] The optional source code for the program to build an execution for.
+ * @property {PrivateKey} [privateKey] Optional private key to use to build the authorization.
+ * @property {ProgramImports} [programImports] The other programs the program imports.
+ * @property {edition} [edition]
  */
 interface AuthorizationOptions {
     programName: string;
@@ -64,11 +65,11 @@ interface AuthorizationOptions {
 /**
  * Options for executing a fee authorization.
  *
- * @property deploymentOrExecutionId {string} The id of a previously built Execution or Authorization.
- * @property baseFeeCredits {number} The number of Aleo Credits to pay for the base fee.
- * @property priorityFeeCredits {number} The number of Aleo Credits to pay for the priority fee.
- * @property privateKey {PrivateKey} Optional private key to specify for the authorization.
- * @property feeRecord {RecordPlaintext} A record to specify to pay the private fee. If this is specified a `fee_private` authorization will be built.
+ * @property {string} deploymentOrExecutionId The id of a previously built Execution or Authorization.
+ * @property {number} baseFeeCredits The number of Aleo Credits to pay for the base fee.
+ * @property {number} [priorityFeeCredits] The number of Aleo Credits to pay for the priority fee.
+ * @property {PrivateKey} [privateKey]  Optional private key to specify for the authorization.
+ * @property {RecordPlaintext} [feeRecord]  A record to specify to pay the private fee. If this is specified a `fee_private` authorization will be built.
  */
 interface FeeAuthorizationOptions {
     deploymentOrExecutionId: string;
@@ -77,6 +78,28 @@ interface FeeAuthorizationOptions {
     privateKey?: PrivateKey;
     feeRecord?: RecordPlaintext;
 }
+/**
+ * Represents the options for executing a transaction on the Aleo Network from an authorization.
+ *
+ * @property {string} programName - The name of the program containing the function to be executed.
+ * @property {KeySearchParams} [keySearchParams] - Optional parameters for finding the matching proving & verifying keys for the function.
+ * @property {ProvingKey} [provingKey] - Optional proving key to use for the transaction.
+ * @property {VerifyingKey} [verifyingKey] - Optional verifying key to use for the transaction.
+ * @property {OfflineQuery} [offlineQuery] - Optional offline query if creating transactions in an offline environment.
+ * @property {string | Program} [program] - Optional program source code to use for the transaction.
+ * @property {ProgramImports} [imports] - Optional programs that the program being executed imports.
+ */
+interface ExecuteAuthorizationOptions {
+    programName: string;
+    authorization: Authorization;
+    feeAuthorization?: Authorization;
+    keySearchParams?: KeySearchParams;
+    provingKey?: ProvingKey;
+    verifyingKey?: VerifyingKey;
+    offlineQuery?: OfflineQuery;
+    program?: string | Program;
+    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.
@@ -98,10 +121,10 @@ interface FeeAuthorizationOptions {
 interface ProvingRequestOptions {
     programName: string;
     functionName: string;
-    baseFee: number;
     priorityFee: number;
     privateFee: boolean;
     inputs: string[];
+    baseFee?: number;
     recordSearchParams?: RecordSearchParams;
     feeRecord?: string | RecordPlaintext;
     privateKey?: PrivateKey;
@@ -111,6 +134,24 @@ interface ProvingRequestOptions {
     unchecked?: boolean;
     edition?: number;
 }
+/**
+ * Fee estimate options.
+ *
+ * @property {string} programName - The name of the program containing the function to estimate the fee for.
+ * @property {string} functionName - The name of the function to execute within the program to estimate the fee for.
+ * @property {string} [program] - Program source code to use for the fee estimate.
+ * @property {ProgramImports} [imports] - Programs that the program imports.
+ * @property {number} [edition] - Edition of the program to estimate the fee for.
+ * @property {Authorization} authorization - An authorization to estimate the fee for.
+ */
+interface FeeEstimateOptions {
+    programName: string;
+    functionName?: string;
+    program?: string | Program;
+    imports?: ProgramImports;
+    edition?: number;
+    authorization?: Authorization;
+}
 /**
  * The ProgramManager class is used to execute and deploy programs on the Aleo network and create value transfers.
  */
@@ -301,6 +342,77 @@ declare class ProgramManager {
      * }, 10000);
      */
     buildExecutionTransaction(options: ExecuteOptions): Promise<Transaction>;
+    /**
+     * Builds an execution transaction for submission to the Aleo network from an Authorization and Fee Authorization.
+     * This method is helpful if signing and authorization needs to be done in a secure environment separate from where
+     * transactions are built.
+     *
+     * @param {ExecuteAuthorizationOptions} options - The options for executing the authorizations.
+     * @returns {Promise<Transaction>} - A promise that resolves to the transaction or an error.
+     *
+     * @example
+     * import { AleoKeyProvider, PrivateKey, initThreadPool, ProgramManager } from "@provablehq/sdk";
+     *
+     * await initThreadPool();
+     *
+     * // Create a new KeyProvider.
+     * const keyProvider = new AleoKeyProvider();
+     * keyProvider.useCache(true);
+     *
+     * // Initialize a program manager with the key provider to automatically fetch keys for executions.
+     * const programManager = new ProgramManager("https://api.explorer.provable.com/v1", keyProvider);
+     *
+     * // Build the `Authorization`.
+     * const privateKey = new PrivateKey(); // Change this to a private key that has an aleo credit balance.
+     * const authorization = await programManager.buildAuthorization({
+     *     programName: "credits.aleo",
+     *     functionName: "transfer_public",
+     *     privateKey,
+     *     inputs: [
+     *         "aleo1vwls2ete8dk8uu2kmkmzumd7q38fvshrht8hlc0a5362uq8ftgyqnm3w08",
+     *         "10000000u64",
+     *     ],
+     * });
+     *
+     * console.log("Getting execution id");
+     *
+     * // Derive the execution ID and base fee.
+     * const executionId = authorization.toExecutionId().toString();
+     *
+     * console.log("Estimating fee");
+     *
+     * // Get the base fee in microcredits.
+     * const baseFeeMicrocredits = await programManager.estimateFeeForAuthorization(authorization, "credits.aleo");
+     * const baseFeeCredits = Number(baseFeeMicrocredits)/1000000;
+     *
+     * console.log("Building fee authorization");
+     *
+     * // Build a credits.aleo/fee_public `Authorization`.
+     * const feeAuthorization = await programManager.buildFeeAuthorization({
+     *     deploymentOrExecutionId: executionId,
+     *     baseFeeCredits,
+     *     privateKey
+     * });
+     *
+     * console.log("Executing authorizations");
+     *
+     * // Build and execute the transaction.
+     * const tx = await programManager.buildTransactionFromAuthorization({
+     *     programName: "credits.aleo",
+     *     authorization,
+     *     feeAuthorization,
+     * });
+     *
+     * // Submit the transaction to the network.
+     * await programManager.networkClient.submitTransaction(tx.toString());
+     *
+     * // Verify the transaction was successful.
+     * setTimeout(async () => {
+     *     const transaction = await programManager.networkClient.getTransaction(tx.id());
+     *     console.log(transaction);
+     * }, 10000);
+     */
+    buildTransactionFromAuthorization(options: ExecuteAuthorizationOptions): Promise<Transaction>;
     /**
      * Builds a SnarkVM `Authorization` for a specific function.
      *
@@ -381,7 +493,6 @@ declare class ProgramManager {
      * const provingRequest = await programManager.provingRequest({
      *   programName: "credits.aleo",
      *   functionName: "transfer_public",
-     *   baseFee: 100000,
      *   priorityFee: 0,
      *   privateFee: false,
      *   inputs: [
@@ -411,14 +522,14 @@ declare class ProgramManager {
      * const programManager = new ProgramManager("https://api.explorer.provable.com/v1", keyProvider, recordProvider);
      *
      * // Build a credits.aleo/fee_public `Authorization`.
-     * const feePublicAuthorization = await programManager.authorizeFee({
+     * const feePublicAuthorization = await programManager.buildFeeAuthorization({
      *   deploymentOrExecutionId: "2423957656946557501636078245035919227529640894159332581642187482178647335171field",
      *   baseFeeCredits: 0.1,
      * });
      *
      * // Build a credits.aleo/fee_private `Authorization`.
      * const record = "{ owner: aleo1j7qxyunfldj2lp8hsvy7mw5k8zaqgjfyr72x2gh3x4ewgae8v5gscf5jh3.private, microcredits: 1500000000000000u64.private, _nonce: 3077450429259593211617823051143573281856129402760267155982965992208217472983group.public }";
-     * const feePrivateAuthorization = await programManager.authorizeFee({
+     * const feePrivateAuthorization = await programManager.buildFeeAuthorization({
      *   deploymentOrExecutionId: "2423957656946557501636078245035919227529640894159332581642187482178647335171field",
      *   baseFeeCredits: 0.1,
      *   feeRecord: record,
@@ -1069,15 +1180,6 @@ declare class ProgramManager {
      * assert(isValid);
      */
     verifyExecution(executionResponse: ExecutionResponse, blockHeight: number, imports?: ImportedPrograms, importedVerifyingKeys?: ImportedVerifyingKeys): boolean;
-    /**
-     * Set the inclusion key bytes.
-     *
-     * @param {executionResponse} executionResponse The response from an offline function execution (via the `programManager.run` method)
-     * @param {ImportedPrograms} imports The imported programs used in the execution. Specified as { "programName": "programSourceCode", ... }
-     * @param {ImportedVerifyingKeys} importedVerifyingKeys The verifying keys in the execution. Specified as { "programName": [["functionName", "verifyingKey"], ...], ... }
-     * @returns {boolean} True if the proof is valid, false otherwise
-     *
-
     /**
      * Create a program object from a program's source code
      *
@@ -1097,6 +1199,86 @@ declare class ProgramManager {
      * @param {string} program The program source code
      */
     verifyProgram(program: string): boolean;
+    /**
+     * Estimate the execution fee for an authorization.
+     *
+     * @param {FeeEstimateOptions} options Options for fee estimate.
+     *
+     * @example
+     * import { AleoKeyProvider, PrivateKey, initThreadPool, ProgramManager } from "@provablehq/sdk";
+     *
+     * await initThreadPool();
+     *
+     * // Create a new KeyProvider.
+     * const keyProvider = new AleoKeyProvider();
+     * keyProvider.useCache(true);
+     *
+     * // Initialize a program manager with the key provider to automatically fetch keys for executions.
+     * const programManager = new ProgramManager("https://api.explorer.provable.com/v1", keyProvider);
+     *
+     * // Build the `Authorization`.
+     * const privateKey = new PrivateKey(); // Change this to a private key that has an aleo credit balance.
+     * const authorization = await programManager.buildAuthorization({
+     *     programName: "credits.aleo",
+     *     functionName: "transfer_public",
+     *     privateKey,
+     *     inputs: [
+     *         "aleo1vwls2ete8dk8uu2kmkmzumd7q38fvshrht8hlc0a5362uq8ftgyqnm3w08",
+     *         "10000000u64",
+     *     ],
+     * });
+     *
+     * console.log("Getting execution id");
+     *
+     * // Derive the execution ID and base fee.
+     * const executionId = authorization.toExecutionId().toString();
+     *
+     * console.log("Estimating fee");
+     *
+     * // Get the base fee in microcredits.
+     * const baseFeeMicrocredits = await programManager.estimateFeeForAuthorization({
+     *      authorization,
+     *      programName: "credits.aleo"
+     * });
+     * const baseFeeCredits = Number(baseFeeMicrocredits)/1000000;
+     *
+     * console.log("Building fee authorization");
+     *
+     * // Build a credits.aleo/fee_public `Authorization`.
+     * const feeAuthorization = await programManager.buildFeeAuthorization({
+     *     deploymentOrExecutionId: executionId,
+     *     baseFeeCredits,
+     *     privateKey
+     * });
+     */
+    estimateFeeForAuthorization(options: FeeEstimateOptions): Promise<bigint>;
+    /**
+     * Estimate the execution fee for an Aleo function.
+     *
+     * @param {FeeEstimateOptions} options Options for the fee estimate.
+     *
+     * @returns {Promise<bigint>} Execution fee in microcredits for the authorization.
+     *
+     * @example
+     * import { AleoKeyProvider, PrivateKey, initThreadPool, ProgramManager } from "@provablehq/sdk";
+     *
+     * // Initialize a program manager with the key provider to automatically fetch keys for executions.
+     * const programManager = new ProgramManager("https://api.explorer.provable.com/v1", keyProvider);
+     *
+     * // Get the base fee in microcredits.
+     * const baseFeeMicrocredits = await programManager.estimateExecutionFee({programName: "credits.aleo"});
+     * const baseFeeCredits = Number(baseFeeMicrocredits)/1000000;
+     *
+     * console.log("Building fee authorization");
+     *
+     * // Build a credits.aleo/fee_public `Authorization`.
+     * const baseFeeMicrocredits = await programManager.estimateFeeForAuthorization({
+     *      programName: "credits.aleo",
+     *      functionName: "transfer_public",
+     * });
+     * const baseFeeCredits = Number(baseFeeMicrocredits)/1000000;
+     */
+    estimateExecutionFee(options: FeeEstimateOptions): Promise<bigint>;
     getCreditsRecord(amount: number, nonces: string[], record?: RecordPlaintext | string, params?: RecordSearchParams): Promise<OwnedRecord>;
 }
 export { ProgramManager, AuthorizationOptions, FeeAuthorizationOptions, ExecuteOptions, ProvingRequestOptions };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@provablehq/sdk",
-  "version": "0.9.10-testnet-rc",
+  "version": "0.9.11",
   "description": "A Software Development Kit (SDK) for Zero-Knowledge Transactions",
   "collaborators": [
     "The Provable Team"
@@ -21,6 +21,10 @@
     "./mainnet.js": {
       "node": "./dist/mainnet/node.js",
       "default": "./dist/mainnet/browser.js"
+    },
+    "./dynamic.js": {
+      "node": "./dist/dynamic/node.js",
+      "default": "./dist/dynamic/browser.js"
     }
   },
   "files": [
@@ -47,7 +51,8 @@
   },
   "homepage": "https://github.com/ProvableHQ/sdk#readme",
   "dependencies": {
-    "@provablehq/wasm": "^0.9.10-testnet-rc",
+    "@provablehq/wasm": "^0.9.11",
+    "@scure/base": "^2.0.0",
     "comlink": "^4.4.2",
     "core-js": "^3.40.0",
     "mime": "^4.0.6",