@provablehq/sdk 0.9.10-testnet-rc → 0.9.10

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.
@@ -301,6 +324,65 @@ 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 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();
+     * 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 authorization = await programManager.buildAuthorization({
+     *   programName: "credits.aleo",
+     *   functionName: "transfer_public",
+     *   inputs: [
+     *     "aleo1vwls2ete8dk8uu2kmkmzumd7q38fvshrht8hlc0a5362uq8ftgyqnm3w08",
+     *     "10000000u64",
+     *   ],
+     * });
+     *
+     * // Derive the execution ID and base fee.
+     * const executionId = authorization.toExecutionId().toString();
+     *
+     * // Get the base fee in microcredits.
+     * const baseFeeMicrocredits = ProgramManager.estimateFeeForAuthorization(authorization, "credits.aleo");
+     * const baseFeeCredits = baseFeeMicrocredits/1000000;
+     *
+     * // Build a credits.aleo/fee_public `Authorization`.
+     * const feeAuthorization = await programManager.buildFeeAuthorization({
+     *   deploymentOrExecutionId: executionId,
+     *   baseFeeCredits,
+     * });
+     *
+     * // Build and execute the transaction
+     * const tx = await programManager.buildTransactionFromAuthorization({
+     *   programName: "hello_hello.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());
+     *  assert(transaction.id() === tx.id());
+     * }, 10000);
+     */
+    buildTransactionFromAuthorization(options: ExecuteAuthorizationOptions): Promise<Transaction>;
     /**
      * Builds a SnarkVM `Authorization` for a specific function.
      *
@@ -411,14 +493,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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@provablehq/sdk",
-  "version": "0.9.10-testnet-rc",
+  "version": "0.9.10",
   "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.10",
+    "@scure/base": "^2.0.0",
     "comlink": "^4.4.2",
     "core-js": "^3.40.0",
     "mime": "^4.0.6",