@buildonspark/spark-sdk 0.0.4 → 0.0.5

package/dist/spark-sdk.js

@@ -15,14 +15,21 @@ import { TransferService } from "./services/transfer.js";
 import { validateMnemonic } from "@scure/bip39";
 import { wordlist } from "@scure/bip39/wordlists/english";
 import { Mutex } from "async-mutex";
+import bitcoin from "bitcoinjs-lib";
 import { TreeCreationService, } from "./services/tree-creation.js";
 import { applyAdaptorToSignature, generateAdaptorFromSignature, generateSignatureFromExistingAdaptor, } from "./utils/adaptor-signature.js";
 import { computeTaprootKeyNoScript, getSigHashFromTx, getTxFromRawTxBytes, getTxFromRawTxHex, getTxId, } from "./utils/bitcoin.js";
 import { Network } from "./utils/network.js";
 import { calculateAvailableTokenAmount, checkIfSelectedLeavesAreAvailable, } from "./utils/token-transactions.js";
+import { getNextTransactionSequence } from "./utils/transaction.js";
 import { initWasm } from "./utils/wasm-wrapper.js";
 // Add this constant at the file level
 const MAX_TOKEN_LEAVES = 100;
+/**
+ * The SparkWallet class is the primary interface for interacting with the Spark network.
+ * It provides methods for creating and managing wallets, handling deposits, executing transfers,
+ * and interacting with the Lightning Network.
+ */
 export class SparkWallet {
     config;
     connectionManager;
@@ -139,21 +146,49 @@ export class SparkWallet {
         this.leaves = await this.getLeaves();
     }
     async syncWallet() {
-        await this.claimTransfers();
-        await this.claimDeposits();
-        await this.syncTokenLeaves();
+        await Promise.all([
+            this.claimTransfers(),
+            this.claimDeposits(),
+            this.syncTokenLeaves(),
+        ]);
         this.leaves = await this.getLeaves();
-        await this.optimizeLeaves();
+        await this.#refreshTimelockNodes();
+        // await this.optimizeLeaves();
     }
     isInitialized() {
         return this.sspClient !== null && this.wasmModule !== null;
     }
+    /**
+     * Gets the identity public key of the wallet.
+     *
+     * @returns {Promise<string>} The identity public key as a hex string.
+     */
     async getIdentityPublicKey() {
         return bytesToHex(await this.config.signer.getIdentityPublicKey());
     }
+    /**
+     * Gets the Spark address of the wallet.
+     *
+     * @returns {Promise<string>} The Spark address as a hex string.
+     */
     async getSparkAddress() {
         return bytesToHex(await this.config.signer.getIdentityPublicKey());
     }
+    /**
+     * Initializes the wallet using either a mnemonic phrase or a raw seed.
+     * initWallet will also claim any pending incoming lightning payment, spark transfer,
+     * or bitcoin deposit.
+     *
+     * @param {Uint8Array | string} [mnemonicOrSeed] - (Optional) Either:
+     *   - A BIP-39 mnemonic phrase as string
+     *   - A raw seed as Uint8Array or hex string
+     *   If not provided, generates a new mnemonic and uses it to create a new wallet
+     *
+     * @returns {Promise<Object>} Object containing:
+     *   - mnemonic: The mnemonic if one was generated (undefined for raw seed)
+     *   - balance: The wallet's initial balance in satoshis
+     *   - tokenBalance: Map of token balances and leaf counts
+     */
     async initWallet(mnemonicOrSeed) {
         const returnMnemonic = !mnemonicOrSeed;
         if (!mnemonicOrSeed) {
@@ -185,15 +220,31 @@ export class SparkWallet {
         };
     }
     async initWalletFromMnemonic(mnemonic) {
-        const identityPublicKey = await this.config.signer.createSparkWalletFromMnemonic(mnemonic);
+        const identityPublicKey = await this.config.signer.createSparkWalletFromMnemonic(mnemonic, this.config.getNetwork());
         await this.initializeWallet(identityPublicKey);
         return identityPublicKey;
     }
+    /**
+     * Initializes a wallet from a seed.
+     *
+     * @param {Uint8Array | string} seed - The seed to initialize the wallet from
+     * @returns {Promise<string>} The identity public key
+     * @private
+     */
     async initWalletFromSeed(seed) {
-        const identityPublicKey = await this.config.signer.createSparkWalletFromSeed(seed);
+        const identityPublicKey = await this.config.signer.createSparkWalletFromSeed(seed, this.config.getNetwork());
         await this.initializeWallet(identityPublicKey);
         return identityPublicKey;
     }
+    /**
+     * Requests a swap of leaves to optimize wallet structure.
+     *
+     * @param {Object} params - Parameters for the leaves swap
+     * @param {number} [params.targetAmount] - Target amount for the swap
+     * @param {TreeNode[]} [params.leaves] - Specific leaves to swap
+     * @returns {Promise<Object>} The completed swap response
+     * @private
+     */
     async requestLeavesSwap({ targetAmount, leaves, }) {
         if (targetAmount && targetAmount <= 0) {
             throw new Error("targetAmount must be positive");
@@ -320,9 +371,26 @@ export class SparkWallet {
             throw new Error(`Failed to request leaves swap: ${e}`);
         }
     }
+    /**
+     * Gets all transfers for the wallet.
+     *
+     * @param {number} [limit=20] - Maximum number of transfers to return
+     * @param {number} [offset=0] - Offset for pagination
+     * @returns {Promise<QueryAllTransfersResponse>} Response containing the list of transfers
+     */
     async getAllTransfers(limit = 20, offset = 0) {
         return await this.transferService.queryAllTransfers(limit, offset);
     }
+    /**
+     * Gets the current balance of the wallet.
+     * You can use the forceRefetch option to synchronize your wallet and claim any
+     * pending incoming lightning payment, spark transfer, or bitcoin deposit before returning the balance.
+     *
+     * @param {boolean} [forceRefetch=false] - Synchronizes the wallet before returning the balance
+     * @returns {Promise<Object>} Object containing:
+     *   - balance: The wallet's current balance in satoshis
+     *   - tokenBalances: Map of token balances and leaf counts
+     */
     async getBalance(forceRefetch = false) {
         if (forceRefetch) {
             await Promise.all([
@@ -330,7 +398,6 @@ export class SparkWallet {
                 this.claimDeposits(),
                 this.syncTokenLeaves(),
             ]);
-            await this.syncTokenLeaves();
             this.leaves = await this.getLeaves();
         }
         const tokenBalances = new Map();
@@ -347,9 +414,23 @@ export class SparkWallet {
         };
     }
     // ***** Deposit Flow *****
+    /**
+     * Generates a new deposit address for receiving bitcoin funds.
+     * Note that this function returns a bitcoin address, not a spark address.
+     * For Layer 1 Bitcoin deposits, Spark generates Pay to Taproot (P2TR) addresses.
+     * These addresses start with "bc1p" and can be used to receive Bitcoin from any wallet.
+     *
+     * @returns {Promise<string>} A Bitcoin address for depositing funds
+     */
     async getDepositAddress() {
         return await this.generateDepositAddress();
     }
+    /**
+     * Generates a deposit address for receiving funds.
+     *
+     * @returns {Promise<string>} A deposit address
+     * @private
+     */
     async generateDepositAddress() {
         const signingPubkey = await this.config.signer.getDepositSigningKey();
         const address = await this.depositService.generateDepositAddress({
@@ -360,6 +441,13 @@ export class SparkWallet {
         }
         return address.depositAddress.address;
     }
+    /**
+     * Finalizes a deposit to the wallet.
+     *
+     * @param {DepositParams} params - Parameters for finalizing the deposit
+     * @returns {Promise<TreeNode[] | undefined>} The nodes created from the deposit
+     * @private
+     */
     async finalizeDeposit({ signingPubKey, verifyingKey, depositTx, vout, }) {
         const response = await this.depositService.createTreeRoot({
             signingPubKey,
@@ -369,6 +457,12 @@ export class SparkWallet {
         });
         return await this.transferDepositToSelf(response.nodes, signingPubKey);
     }
+    /**
+     * Claims any pending deposits to the wallet.
+     *
+     * @returns {Promise<TreeNode[]>} The nodes created from the claimed deposits
+     * @private
+     */
     async claimDeposits() {
         const sparkClient = await this.connectionManager.createSparkClient(this.config.getCoordinatorAddress());
         const identityPublicKey = await this.config.signer.getIdentityPublicKey();
@@ -394,14 +488,27 @@ export class SparkWallet {
         }
         return depositNodes;
     }
+    /**
+     * Queries the mempool for transactions associated with an address.
+     *
+     * @param {string} address - The address to query
+     * @returns {Promise<{depositTx: Transaction, vout: number} | null>} Transaction details or null if none found
+     * @private
+     */
     async queryMempoolTxs(address) {
-        const baseUrl = "https://regtest-mempool.dev.dev.sparkinfra.net/api";
+        const network = getNetworkFromAddress(address) || this.config.getNetwork();
+        const baseUrl = network === BitcoinNetwork.REGTEST
+            ? "https://regtest-mempool.dev.dev.sparkinfra.net/api"
+            : "https://mempool.space/docs/api/rest";
         const auth = btoa("spark-sdk:mCMk1JqlBNtetUNy");
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (network === BitcoinNetwork.REGTEST) {
+            headers["Authorization"] = `Basic ${auth}`;
+        }
         const response = await fetch(`${baseUrl}/address/${address}/txs`, {
-            headers: {
-                Authorization: `Basic ${auth}`,
-                "Content-Type": "application/json",
-            },
+            headers,
         });
         const addressTxs = await response.json();
         if (addressTxs && addressTxs.length > 0) {
@@ -411,10 +518,7 @@ export class SparkWallet {
                 return null;
             }
             const txResponse = await fetch(`${baseUrl}/tx/${latestTx.txid}/hex`, {
-                headers: {
-                    Authorization: `Basic ${auth}`,
-                    "Content-Type": "application/json",
-                },
+                headers,
             });
             const txHex = await txResponse.text();
             const depositTx = getTxFromRawTxHex(txHex);
@@ -425,6 +529,14 @@ export class SparkWallet {
         }
         return null;
     }
+    /**
+     * Transfers deposit to self to claim ownership.
+     *
+     * @param {TreeNode[]} leaves - The leaves to transfer
+     * @param {Uint8Array} signingPubKey - The signing public key
+     * @returns {Promise<TreeNode[] | undefined>} The nodes resulting from the transfer
+     * @private
+     */
     async transferDepositToSelf(leaves, signingPubKey) {
         const leafKeyTweaks = await Promise.all(leaves.map(async (leaf) => ({
             leaf,
@@ -440,12 +552,27 @@ export class SparkWallet {
         return;
     }
     // ***** Transfer Flow *****
+    /**
+     * Sends a transfer to another Spark user.
+     *
+     * @param {Object} params - Parameters for the transfer
+     * @param {string} params.receiverSparkAddress - The recipient's Spark address
+     * @param {number} params.amountSats - Amount to send in satoshis
+     * @returns {Promise<Transfer>} The completed transfer details
+     */
     async sendSparkTransfer({ receiverSparkAddress, amountSats, }) {
         return await this._sendTransfer({
             receiverPubKey: receiverSparkAddress,
             amount: amountSats,
         });
     }
+    /**
+     * Internal method to send a transfer.
+     *
+     * @param {SendTransferParams} params - Parameters for the transfer
+     * @returns {Promise<Transfer>} The completed transfer details
+     * @private
+     */
     async _sendTransfer({ amount, receiverPubKey, leaves, expiryTime = new Date(Date.now() + 10 * 60 * 1000), }) {
         return await this.sendTransferMutex.runExclusive(async () => {
             let leavesToSend = [];
@@ -460,6 +587,7 @@ export class SparkWallet {
             else {
                 throw new Error("Must provide amount or leaves");
             }
+            await this.#refreshTimelockNodes();
             const leafKeyTweaks = await Promise.all(leavesToSend.map(async (leaf) => ({
                 leaf,
                 signingPubKey: await this.config.signer.generatePublicKey(sha256(leaf.id)),
@@ -471,6 +599,83 @@ export class SparkWallet {
             return transfer;
         });
     }
+    /**
+     * Internal method to refresh timelock nodes.
+     *
+     * @param {string} nodeId - The optional ID of the node to refresh. If not provided, all nodes will be checked.
+     * @returns {Promise<void>}
+     * @private
+     */
+    async #refreshTimelockNodes(nodeId) {
+        const nodesToRefresh = [];
+        const nodeIds = [];
+        if (nodeId) {
+            for (const node of this.leaves) {
+                if (node.id === nodeId) {
+                    nodesToRefresh.push(node);
+                    nodeIds.push(node.id);
+                    break;
+                }
+            }
+            if (nodesToRefresh.length === 0) {
+                throw new Error(`node ${nodeId} not found`);
+            }
+        }
+        else {
+            for (const node of this.leaves) {
+                const refundTx = getTxFromRawTxBytes(node.refundTx);
+                const nextSequence = getNextTransactionSequence(refundTx.getInput(0).sequence);
+                const needRefresh = nextSequence <= 0;
+                if (needRefresh) {
+                    nodesToRefresh.push(node);
+                    nodeIds.push(node.id);
+                }
+            }
+        }
+        if (nodesToRefresh.length === 0) {
+            return;
+        }
+        const sparkClient = await this.connectionManager.createSparkClient(this.config.getCoordinatorAddress());
+        const nodesResp = await sparkClient.query_nodes({
+            source: {
+                $case: "nodeIds",
+                nodeIds: {
+                    nodeIds,
+                },
+            },
+            includeParents: true,
+        });
+        const nodesMap = new Map();
+        for (const node of Object.values(nodesResp.nodes)) {
+            nodesMap.set(node.id, node);
+        }
+        for (const node of nodesToRefresh) {
+            if (!node.parentNodeId) {
+                throw new Error(`node ${node.id} has no parent`);
+            }
+            const parentNode = nodesMap.get(node.parentNodeId);
+            if (!parentNode) {
+                throw new Error(`parent node ${node.parentNodeId} not found`);
+            }
+            const { nodes } = await this.transferService.refreshTimelockNodes([node], parentNode, await this.config.signer.generatePublicKey(sha256(node.id)));
+            if (nodes.length !== 1) {
+                throw new Error(`expected 1 node, got ${nodes.length}`);
+            }
+            const newNode = nodes[0];
+            if (!newNode) {
+                throw new Error("Failed to refresh timelock node");
+            }
+            this.leaves = this.leaves.filter((leaf) => leaf.id !== node.id);
+            this.leaves.push(newNode);
+        }
+    }
+    /**
+     * Claims a specific transfer.
+     *
+     * @param {Transfer} transfer - The transfer to claim
+     * @returns {Promise<Object>} The claim result
+     * @private
+     */
     async claimTransfer(transfer) {
         return await this.claimTransferMutex.runExclusive(async () => {
             const leafPubKeyMap = await this.transferService.verifyPendingTransfer(transfer);
@@ -487,9 +692,18 @@ export class SparkWallet {
                     }
                 }
             }
-            return await this.transferService.claimTransfer(transfer, leavesToClaim);
+            const response = await this.transferService.claimTransfer(transfer, leavesToClaim);
+            this.leaves.push(...response.nodes);
+            await this.#refreshTimelockNodes();
+            return response;
         });
     }
+    /**
+     * Claims all pending transfers.
+     *
+     * @returns {Promise<boolean>} True if any transfers were claimed
+     * @private
+     */
     async claimTransfers() {
         const transfers = await this.transferService.queryPendingTransfers();
         let claimed = false;
@@ -506,6 +720,12 @@ export class SparkWallet {
         }
         return claimed;
     }
+    /**
+     * Cancels all sender-initiated transfers.
+     *
+     * @returns {Promise<void>}
+     * @private
+     */
     async cancelAllSenderInitiatedTransfers() {
         const transfers = await this.transferService.queryPendingTransfersBySender();
         for (const transfer of transfers.transfers) {
@@ -515,6 +735,14 @@ export class SparkWallet {
         }
     }
     // ***** Lightning Flow *****
+    /**
+     * Creates a Lightning invoice for receiving payments.
+     *
+     * @param {Object} params - Parameters for the lightning invoice
+     * @param {number} params.amountSats - Amount in satoshis
+     * @param {string} params.memo - Description for the invoice
+     * @returns {Promise<string>} BOLT11 encoded invoice
+     */
     async createLightningInvoice({ amountSats, memo, }) {
         const expirySeconds = 60 * 60 * 24 * 30;
         if (!this.sspClient) {
@@ -544,6 +772,13 @@ export class SparkWallet {
             invoiceCreator: requestLightningInvoice,
         });
     }
+    /**
+     * Pays a Lightning invoice.
+     *
+     * @param {Object} params - Parameters for paying the invoice
+     * @param {string} params.invoice - The BOLT11-encoded Lightning invoice to pay
+     * @returns {Promise<LightningSendRequest>} The Lightning payment request details
+     */
     async payLightningInvoice({ invoice }) {
         if (!this.sspClient) {
             throw new Error("SSP client not initialized");
@@ -561,6 +796,7 @@ export class SparkWallet {
         }
         // fetch leaves for amount
         const leaves = await this.selectLeaves(amountSats);
+        await this.#refreshTimelockNodes();
         const leavesToSend = await Promise.all(leaves.map(async (leaf) => ({
             leaf,
             signingPubKey: await this.config.signer.generatePublicKey(sha256(leaf.id)),
@@ -588,12 +824,26 @@ export class SparkWallet {
         this.leaves = this.leaves.filter((leaf) => !leavesToRemove.has(leaf.id));
         return sspResponse;
     }
+    /**
+     * Gets fee estimate for receiving Lightning payments.
+     *
+     * @param {LightningReceiveFeeEstimateInput} params - Input parameters for fee estimation
+     * @returns {Promise<LightningReceiveFeeEstimateOutput | null>} Fee estimate for receiving Lightning payments
+     * @private
+     */
     async getLightningReceiveFeeEstimate({ amountSats, network, }) {
         if (!this.sspClient) {
             throw new Error("SSP client not initialized");
         }
         return await this.sspClient.getLightningReceiveFeeEstimate(amountSats, network);
     }
+    /**
+     * Gets fee estimate for sending Lightning payments.
+     *
+     * @param {LightningSendFeeEstimateInput} params - Input parameters for fee estimation
+     * @returns {Promise<LightningSendFeeEstimateOutput | null>} Fee estimate for sending Lightning payments
+     * @private
+     */
     async getLightningSendFeeEstimate({ encodedInvoice, }) {
         if (!this.sspClient) {
             throw new Error("SSP client not initialized");
@@ -601,16 +851,53 @@ export class SparkWallet {
         return await this.sspClient.getLightningSendFeeEstimate(encodedInvoice);
     }
     // ***** Tree Creation Flow *****
+    /**
+     * Generates a deposit address for a tree.
+     *
+     * @param {number} vout - The vout index
+     * @param {Uint8Array} parentSigningPubKey - The parent signing public key
+     * @param {Transaction} [parentTx] - Optional parent transaction
+     * @param {TreeNode} [parentNode] - Optional parent node
+     * @returns {Promise<Object>} Deposit address information
+     * @private
+     */
     async generateDepositAddressForTree(vout, parentSigningPubKey, parentTx, parentNode) {
         return await this.treeCreationService.generateDepositAddressForTree(vout, parentSigningPubKey, parentTx, parentNode);
     }
+    /**
+     * Creates a tree structure.
+     *
+     * @param {number} vout - The vout index
+     * @param {DepositAddressTree} root - The root of the tree
+     * @param {boolean} createLeaves - Whether to create leaves
+     * @param {Transaction} [parentTx] - Optional parent transaction
+     * @param {TreeNode} [parentNode] - Optional parent node
+     * @returns {Promise<Object>} The created tree
+     * @private
+     */
     async createTree(vout, root, createLeaves, parentTx, parentNode) {
         return await this.treeCreationService.createTree(vout, root, createLeaves, parentTx, parentNode);
     }
     // ***** Cooperative Exit Flow *****
+    /**
+     * Initiates a withdrawal to move funds from the Spark network to an on-chain Bitcoin address.
+     *
+     * @param {Object} params - Parameters for the withdrawal
+     * @param {string} params.onchainAddress - The Bitcoin address where the funds should be sent
+     * @param {number} [params.targetAmountSats] - The amount in satoshis to withdraw. If not specified, attempts to withdraw all available funds
+     * @returns {Promise<CoopExitRequest | null | undefined>} The withdrawal request details, or null/undefined if the request cannot be completed
+     */
     async withdraw({ onchainAddress, targetAmountSats, }) {
         return this.coopExit(onchainAddress, targetAmountSats);
     }
+    /**
+     * Internal method to perform a cooperative exit (withdrawal).
+     *
+     * @param {string} onchainAddress - The Bitcoin address where the funds should be sent
+     * @param {number} [targetAmountSats] - The amount in satoshis to withdraw
+     * @returns {Promise<Object | null | undefined>} The exit request details
+     * @private
+     */
     async coopExit(onchainAddress, targetAmountSats) {
         let leavesToSend = [];
         if (targetAmountSats) {
@@ -621,7 +908,6 @@ export class SparkWallet {
                 ...leaf,
             }));
         }
-        const pubkey = await this.config.signer.getIdentityPublicKey();
         const leafKeyTweaks = await Promise.all(leavesToSend.map(async (leaf) => ({
             leaf,
             signingPubKey: await this.config.signer.generatePublicKey(sha256(leaf.id)),
@@ -635,18 +921,22 @@ export class SparkWallet {
             throw new Error("Failed to request coop exit");
         }
         const connectorTx = getTxFromRawTxHex(coopExitRequest.rawConnectorTransaction);
-        const coopExitTxId = getTxId(connectorTx);
+        const coopExitTxId = connectorTx.getInput(0).txid;
+        const connectorTxId = getTxId(connectorTx);
+        if (!coopExitTxId) {
+            throw new Error("Failed to get coop exit tx id");
+        }
         const connectorOutputs = [];
         for (let i = 0; i < connectorTx.outputsLength - 1; i++) {
             connectorOutputs.push({
-                txid: hexToBytes(coopExitTxId),
+                txid: hexToBytes(connectorTxId),
                 index: i,
             });
         }
         const sspPubIdentityKey = await this.config.signer.getSspIdentityPublicKey(this.config.getNetwork());
         const transfer = await this.coopExitService.getConnectorRefundSignatures({
             leaves: leafKeyTweaks,
-            exitTxId: hexToBytes(coopExitTxId),
+            exitTxId: coopExitTxId,
             connectorOutputs,
             receiverPubKey: sspPubIdentityKey,
         });
@@ -656,6 +946,13 @@ export class SparkWallet {
         });
         return completeResponse;
     }
+    /**
+     * Gets fee estimate for cooperative exit (on-chain withdrawal).
+     *
+     * @param {CoopExitFeeEstimateInput} params - Input parameters for fee estimation
+     * @returns {Promise<CoopExitFeeEstimateOutput | null>} Fee estimate for the withdrawal
+     * @private
+     */
     async getCoopExitFeeEstimate({ leafExternalIds, withdrawalAddress, }) {
         if (!this.sspClient) {
             throw new Error("SSP client not initialized");
@@ -666,6 +963,12 @@ export class SparkWallet {
         });
     }
     // ***** Token Flow *****
+    /**
+     * Synchronizes token leaves for the wallet.
+     *
+     * @returns {Promise<void>}
+     * @private
+     */
     async syncTokenLeaves() {
         this.tokenLeaves.clear();
         const trackedPublicKeys = await this.config.signer.getTrackedPublicKeys();
@@ -685,6 +988,12 @@ export class SparkWallet {
         });
         this.tokenLeaves = groupedLeaves;
     }
+    /**
+     * Gets all token balances.
+     *
+     * @returns {Promise<Map<string, { balance: bigint, leafCount: number }>>} Map of token balances and leaf counts
+     * @private
+     */
     async getAllTokenBalances() {
         await this.syncTokenLeaves();
         const balances = new Map();
@@ -696,6 +1005,15 @@ export class SparkWallet {
         }
         return balances;
     }
+    /**
+     * Transfers tokens to another user.
+     *
+     * @param {string} tokenPublicKey - The public key of the token to transfer
+     * @param {bigint} tokenAmount - The amount of tokens to transfer
+     * @param {string} recipientPublicKey - The recipient's public key
+     * @param {LeafWithPreviousTransactionData[]} [selectedLeaves] - Optional specific leaves to use for the transfer
+     * @returns {Promise<string>} The transaction ID of the token transfer
+     */
     async transferTokens(tokenPublicKey, tokenAmount, recipientPublicKey, selectedLeaves) {
         await this.syncTokenLeaves();
         if (!this.tokenLeaves.has(tokenPublicKey)) {
@@ -717,8 +1035,38 @@ export class SparkWallet {
         const tokenTransaction = await this.tokenTransactionService.constructTransferTokenTransaction(selectedLeaves, recipientPublicKeyBytes, tokenPublicKeyBytes, tokenAmount);
         return await this.tokenTransactionService.broadcastTokenTransaction(tokenTransaction, selectedLeaves.map((leaf) => leaf.leaf.ownerPublicKey), selectedLeaves.map((leaf) => leaf.leaf.revocationPublicKey));
     }
+    /**
+     * Selects token leaves for a transfer.
+     *
+     * @param {string} tokenPublicKey - The public key of the token
+     * @param {bigint} tokenAmount - The amount of tokens to select leaves for
+     * @returns {LeafWithPreviousTransactionData[]} The selected leaves
+     * @private
+     */
     selectTokenLeaves(tokenPublicKey, tokenAmount) {
         return this.tokenTransactionService.selectTokenLeaves(this.tokenLeaves.get(tokenPublicKey), tokenAmount);
     }
 }
+/**
+ * Utility function to determine the network from a Bitcoin address.
+ *
+ * @param {string} address - The Bitcoin address
+ * @returns {BitcoinNetwork | null} The detected network or null if not detected
+ */
+function getNetworkFromAddress(address) {
+    try {
+        const decoded = bitcoin.address.fromBech32(address);
+        // HRP (human-readable part) determines the network
+        if (decoded.prefix === "bc") {
+            return BitcoinNetwork.MAINNET;
+        }
+        else if (decoded.prefix === "bcrt") {
+            return BitcoinNetwork.REGTEST;
+        }
+    }
+    catch (err) {
+        throw new Error("Invalid Bitcoin address");
+    }
+    return null;
+}
 //# sourceMappingURL=spark-sdk.js.map