@buildonspark/issuer-sdk 0.0.13 → 0.0.14

package/dist/spark-sdk/src/spark-sdk.d.ts

@@ -0,0 +1,353 @@
+import { CoopExitFeeEstimateInput, CoopExitFeeEstimateOutput, LeavesSwapRequest, LightningReceiveFeeEstimateInput, LightningReceiveFeeEstimateOutput, LightningSendFeeEstimateInput, LightningSendFeeEstimateOutput } from "./graphql/objects/index.js";
+import { LeafWithPreviousTransactionData, QueryAllTransfersResponse, Transfer, TreeNode } from "./proto/spark.js";
+import { WalletConfigService } from "./services/config.js";
+import { ConnectionManager } from "./services/connection.js";
+import { TransferService } from "./services/transfer.js";
+import { ConfigOptions } from "./services/wallet-config.js";
+import { LRC20WalletApiConfig, LRCWallet } from "@buildonspark/lrc20-sdk";
+import { SparkSigner } from "./signer/signer.js";
+export type CreateLightningInvoiceParams = {
+    amountSats: number;
+    memo: string;
+    expirySeconds?: number;
+};
+export type PayLightningInvoiceParams = {
+    invoice: string;
+};
+export type TransferParams = {
+    amountSats: number;
+    receiverSparkAddress: string;
+};
+export type InitWalletResponse = {
+    mnemonic?: string | undefined;
+};
+export interface SparkWalletProps {
+    mnemonicOrSeed?: Uint8Array | string;
+    signer?: SparkSigner;
+    options?: ConfigOptions;
+    lrc20WalletApiConfig?: LRC20WalletApiConfig;
+}
+/**
+ * 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 declare class SparkWallet {
+    protected config: WalletConfigService;
+    protected connectionManager: ConnectionManager;
+    protected lrc20Wallet: LRCWallet | undefined;
+    private depositService;
+    protected transferService: TransferService;
+    private treeCreationService;
+    private lightningService;
+    private coopExitService;
+    private tokenTransactionService;
+    private claimTransferMutex;
+    private leavesMutex;
+    private optimizationInProgress;
+    private sspClient;
+    private wasmModule;
+    protected leaves: TreeNode[];
+    protected tokenLeaves: Map<string, LeafWithPreviousTransactionData[]>;
+    protected constructor(options?: ConfigOptions, signer?: SparkSigner);
+    static create({ mnemonicOrSeed, signer, options, lrc20WalletApiConfig, }: SparkWalletProps): Promise<{
+        mnemonic?: string | undefined;
+        wallet: SparkWallet;
+    }>;
+    private initWasm;
+    private initializeWallet;
+    private getLeaves;
+    private selectLeaves;
+    private selectLeavesForSwap;
+    private areLeavesInefficient;
+    private optimizeLeaves;
+    private syncWallet;
+    private withLeaves;
+    /**
+     * Gets the identity public key of the wallet.
+     *
+     * @returns {Promise<string>} The identity public key as a hex string.
+     */
+    getIdentityPublicKey(): Promise<string>;
+    /**
+     * Gets the Spark address of the wallet.
+     *
+     * @returns {Promise<string>} The Spark address as a hex string.
+     */
+    getSparkAddress(): Promise<string>;
+    /**
+     * 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
+     * @private
+     */
+    protected initWallet(mnemonicOrSeed?: Uint8Array | string, lrc20WalletApiConfig?: LRC20WalletApiConfig): Promise<InitWalletResponse | undefined>;
+    /**
+     * 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
+     */
+    private initWalletFromSeed;
+    /**
+     * 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
+     */
+    requestLeavesSwap({ targetAmount, leaves, }: {
+        targetAmount?: number;
+        leaves?: TreeNode[];
+    }): Promise<LeavesSwapRequest>;
+    /**
+     * 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
+     */
+    getTransfers(limit?: number, offset?: number): Promise<QueryAllTransfersResponse>;
+    /**
+     * 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=true] - 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
+     */
+    getBalance(forceRefetch?: boolean): Promise<{
+        balance: bigint;
+        tokenBalances: Map<string, {
+            balance: bigint;
+        }>;
+    }>;
+    /**
+     * 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
+     */
+    getDepositAddress(): Promise<string>;
+    /**
+     * Generates a deposit address for receiving funds.
+     *
+     * @returns {Promise<string>} A deposit address
+     * @private
+     */
+    private generateDepositAddress;
+    /**
+     * 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
+     */
+    private finalizeDeposit;
+    /**
+     * Gets all unused deposit addresses for the wallet.
+     *
+     * @returns {Promise<string[]>} The unused deposit addresses
+     */
+    getUnusedDepositAddresses(): Promise<string[]>;
+    /**
+     * Claims a deposit to the wallet.
+     *
+     * @param {string} txid - The transaction ID of the deposit
+     * @returns {Promise<TreeNode[] | undefined>} The nodes resulting from the deposit
+     */
+    claimDeposit(txid: string): Promise<TreeNode[] | undefined>;
+    /**
+     * 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
+     */
+    private transferDepositToSelf;
+    /**
+     * Sends a transfer to another Spark user.
+     *
+     * @param {TransferParams} 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
+     */
+    transfer({ amountSats, receiverSparkAddress }: TransferParams): Promise<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
+     */
+    private refreshTimelockNodes;
+    /**
+     * Gets all pending transfers.
+     *
+     * @returns {Promise<Transfer[]>} The pending transfers
+     */
+    getPendingTransfers(): Promise<Transfer[]>;
+    /**
+     * Claims a specific transfer.
+     *
+     * @param {Transfer} transfer - The transfer to claim
+     * @returns {Promise<Object>} The claim result
+     */
+    claimTransfer(transfer: Transfer): Promise<TreeNode[]>;
+    /**
+     * Claims all pending transfers.
+     *
+     * @returns {Promise<boolean>} True if any transfers were claimed
+     */
+    claimTransfers(): Promise<boolean>;
+    /**
+     * Cancels all sender-initiated transfers.
+     *
+     * @returns {Promise<void>}
+     * @private
+     */
+    private cancelAllSenderInitiatedTransfers;
+    /**
+     * 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
+     * @param {number} [params.expirySeconds] - Optional expiry time in seconds
+     * @returns {Promise<string>} BOLT11 encoded invoice
+     */
+    createLightningInvoice({ amountSats, memo, expirySeconds, }: CreateLightningInvoiceParams): Promise<string>;
+    /**
+     * 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
+     */
+    payLightningInvoice({ invoice }: PayLightningInvoiceParams): Promise<import("./graphql/objects/LightningSendRequest.js").default>;
+    /**
+     * 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
+     */
+    getLightningReceiveFeeEstimate({ amountSats, network, }: LightningReceiveFeeEstimateInput): Promise<LightningReceiveFeeEstimateOutput | null>;
+    /**
+     * 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
+     */
+    getLightningSendFeeEstimate({ encodedInvoice, }: LightningSendFeeEstimateInput): Promise<LightningSendFeeEstimateOutput | null>;
+    /**
+     * 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
+     */
+    private generateDepositAddressForTree;
+    /**
+     * 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
+     */
+    private createTree;
+    /**
+     * 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
+     */
+    withdraw({ onchainAddress, targetAmountSats, }: {
+        onchainAddress: string;
+        targetAmountSats?: number;
+    }): Promise<import("./graphql/objects/CoopExitRequest.js").default | null | undefined>;
+    /**
+     * 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
+     */
+    private coopExit;
+    /**
+     * 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
+     */
+    getCoopExitFeeEstimate({ leafExternalIds, withdrawalAddress, }: CoopExitFeeEstimateInput): Promise<CoopExitFeeEstimateOutput | null>;
+    /**
+     * Synchronizes token leaves for the wallet.
+     *
+     * @returns {Promise<void>}
+     * @private
+     */
+    protected syncTokenLeaves(): Promise<void>;
+    /**
+     * Gets all token balances.
+     *
+     * @returns {Promise<Map<string, { balance: bigint }>>} Map of token balances and leaf counts
+     * @private
+     */
+    private getAllTokenBalances;
+    /**
+     * Transfers tokens to another user.
+     *
+     * @param {Object} params - Parameters for the token transfer
+     * @param {string} params.tokenPublicKey - The public key of the token to transfer
+     * @param {bigint} params.tokenAmount - The amount of tokens to transfer
+     * @param {string} params.receiverSparkAddress - The recipient's public key
+     * @param {LeafWithPreviousTransactionData[]} [params.selectedLeaves] - Optional specific leaves to use for the transfer
+     * @returns {Promise<string>} The transaction ID of the token transfer
+     */
+    transferTokens({ tokenPublicKey, tokenAmount, receiverSparkAddress, selectedLeaves, }: {
+        tokenPublicKey: string;
+        tokenAmount: bigint;
+        receiverSparkAddress: string;
+        selectedLeaves?: LeafWithPreviousTransactionData[];
+    }): Promise<string>;
+    /**
+     * 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
+     */
+    private selectTokenLeaves;
+    withdrawTokens(tokenPublicKey: string, receiverPublicKey?: string, leafIds?: string[]): Promise<{
+        txid: string;
+    } | undefined>;
+}