@tetherto/wdk-wallet-spark
Note: This package is currently in beta. Please test thoroughly in development environments before using in production.
A simple and secure package to manage BIP-44 wallets for the Spark blockchain. This package provides a clean API for creating, managing, and interacting with Spark wallets using BIP-39 seed phrases and Liquid Bitcoin (LBTC) derivation paths.
🔍 About WDK
This module is part of the WDK (Wallet Development Kit) project, which empowers developers to build secure, non-custodial wallets with unified blockchain access, stateless architecture, and complete user control.
For detailed documentation about the complete WDK ecosystem, visit docs.wallet.tether.io.
🌟 Features
- Liquid Bitcoin (LBTC) Derivation Paths: Support for BIP-44 standard derivation paths (m/44'/998')
- Multi-Account Management: Create and manage multiple accounts from a single seed phrase
- Transaction Management: Send transactions and get fee estimates with zero fees
- Lightning Network Integration: Create invoices, pay Lightning invoices, and manage Lightning payments
⬇️ Installation
To install the @tetherto/wdk-wallet-spark package, follow these instructions:
You can install it using npm:
🚀 Quick Start
Importing from @tetherto/wdk-wallet-spark
- WalletManagerSpark: Main class for managing wallets
- WalletAccountSpark: Use this for full access accounts
- WalletAccountReadOnlySpark: Use this for read-only accounts
Creating a New Wallet
Note: The Spark wallet integrates with the Spark network using the @buildonspark/spark-sdk. Network configuration is limited to predefined networks, and there's no custom RPC provider option.
Managing Multiple Accounts
Important Note: Custom derivation paths via getAccountByPath() are not supported on the Spark blockchain. Only indexed accounts using the standard BIP-44 pattern are available.
Checking Balances
Sending Transactions
Important Notes:
- Spark transactions have zero fees (
fee: 0)
- Memo/description functionality is not supported in
sendTransaction
- All amounts are specified in satoshis (1 BTC = 100,000,000 satoshis)
- Addresses should be valid Spark network addresses
Message Signing and Verification
Memory Management
📚 API Reference
Table of Contents
WalletManagerSpark
The main class for managing Spark wallets.
Extends WalletManager from @tetherto/wdk-wallet.
Constructor
Parameters:
seed (string | Uint8Array): BIP-39 mnemonic seed phrase or seed bytesconfig (object, optional): Configuration object
network (string, optional): 'MAINNET', 'TESTNET', or 'REGTEST' (default: 'MAINNET')
Methods
| Method | Description | Returns |
|---|
getAccount(index) | Returns a wallet account at the specified index | Promise<WalletAccountSpark> |
getFeeRates() | Returns current fee rates for transactions (always zero for Spark) | Promise<FeeRates> |
dispose() | Disposes all wallet accounts, clearing private keys from memory | void |
getAccount(index)
Returns a Spark wallet account at the specified index using BIP-44 derivation path.
Parameters:
index (number, optional): The index of the account to get (default: 0)
Returns: Promise<WalletAccountSpark> - The Spark wallet account
Example:
Note: Uses derivation path pattern m/44'/998'/{network}'/0/{index} where 998 is the coin type for Liquid Bitcoin and {network} is the network number (MAINNET=0, TESTNET=1, REGTEST=2).
getAccountByPath(path)
Not supported on Spark blockchain. This method throws an error when called. Use getAccount(index) instead.
getFeeRates()
Returns current fee rates for Spark transactions from the network.
Returns: Promise<FeeRates> - Object containing fee rates in satoshis
normal: Standard fee rate for normal confirmation speed (always 0)fast: Higher fee rate for faster confirmation (always 0)
Example:
dispose()
Disposes all Spark wallet accounts and clears sensitive data from memory.
Returns: void
Example:
Important Notes:
- All Spark transactions have zero fees
- Network configuration is limited to predefined values
- Uses BIP-44 derivation paths with coin type 998 for Liquid Bitcoin
WalletAccountReadOnlySpark
A read-only Spark wallet account for querying wallet data without needing private keys. Uses the SparkReadonlyClient from @buildonspark/spark-sdk for all queries.
Constructor
Parameters:
address (string): The account's Spark addressconfig (object, optional): Configuration object
network (string, optional): 'MAINNET', 'TESTNET', or 'REGTEST' (default: 'MAINNET')
Example:
Methods
| Method | Description | Returns |
|---|
getBalance() | Returns the available (spendable) bitcoin balance in satoshis | Promise<bigint> |
getTokenBalance(tokenAddress) | Returns the available-to-send balance for a specific token | Promise<bigint> |
getTransactionReceipt(hash) | Gets a Spark transfer by its ID | Promise<Object | null> |
getIdentityKey() | Returns the account's identity public key | Promise<string> |
verify(message, signature) | Verifies a message's signature | Promise<boolean> |
quoteSendTransaction(tx) | Estimates transaction fee (always 0) | Promise<{fee: bigint}> |
quoteTransfer(options) | Quotes the costs of a transfer operation | Promise<{fee: bigint}> |
getTransfers(options?) | Returns the account's Spark transfer history | Promise<SparkTransfer[]> |
getUnusedDepositAddresses(options?) | Returns unused single-use deposit addresses | Promise<{depositAddresses: Array, offset: number}> |
getStaticDepositAddresses() | Returns all static deposit addresses | Promise<Array> |
getUtxosForDepositAddress(options) | Returns confirmed UTXOs for a deposit address | Promise<{utxos: Array<{txid: string, vout: number}>, offset: number}> |
getSparkInvoices(params) | Queries the status of Spark invoices | Promise<{invoiceStatuses: Array, offset: number}> |
getBalance()
Returns the account's available (spendable) bitcoin balance in satoshis. This excludes sats that are locked in pending outgoing transfers.
Returns: Promise<bigint> - Available balance in satoshis
Example:
getTokenBalance(tokenAddress)
Returns the available-to-send balance for a specific token.
Parameters:
tokenAddress (string): Token identifier (Bech32m, e.g., btkn1...)
Returns: Promise<bigint> - Token balance (returns 0n if token not found)
Example:
getTransactionReceipt(hash)
Gets a Spark transfer by its ID. Only returns Spark transfers, not on-chain Bitcoin transactions.
Parameters:
hash (string): The Spark transfer ID
Returns: Promise<Object | null> - The Spark transfer object, or null if not found
Example:
getIdentityKey()
Returns the account's identity public key (hex-encoded), derived from the Spark address.
Returns: Promise<string> - The identity public key
Example:
verify(message, signature)
Verifies a message's signature against the account's identity key.
Parameters:
message (string): The original messagesignature (string): The signature to verify (hex-encoded, DER or compact)
Returns: Promise<boolean> - True if the signature is valid
Example:
getTransfers(options?)
Returns the account's Spark transfer history with filtering and pagination options. Only returns Spark transfers, not on-chain Bitcoin transactions.
Parameters:
options (object, optional): Filter options
direction (string): 'all', 'incoming', or 'outgoing' (default: 'all')limit (number): Maximum transfers to return (default: 10)skip (number): Number of transfers to skip (default: 0)
Returns: Promise<Array> - Array of Spark transfer objects
Example:
getUnusedDepositAddresses(options?)
Returns unused single-use deposit addresses for the account.
Parameters:
options (object, optional): Pagination options
limit (number): Maximum number of addresses to return (default: 100)offset (number): Pagination offset (default: 0)
Returns: Promise<{depositAddresses: Array, offset: number}> - Unused deposit addresses with pagination offset
Example:
getStaticDepositAddresses()
Returns all static deposit addresses for the account.
Returns: Promise<Array> - Array of static deposit address objects
Example:
getUtxosForDepositAddress(options)
Returns confirmed UTXOs for a specific deposit address.
Parameters:
options (object): Query options
depositAddress (string): The Bitcoin deposit address to querylimit (number, optional): Maximum number of UTXOs to return (default: 100)offset (number, optional): Pagination offset (default: 0)excludeClaimed (boolean, optional): If true, excludes already-claimed UTXOs
Returns: Promise<{utxos: Array<{txid: string, vout: number}>, offset: number}> - UTXOs with pagination offset
Example:
getSparkInvoices(params)
Queries the status of Spark invoices.
Parameters:
params (object): Query parameters
invoices (string[]): Array of Spark invoice strings to querylimit (number, optional): Maximum number of results to return (default: 100)offset (number, optional): Pagination offset (default: 0)
Returns: Promise<{invoiceStatuses: Array, offset: number}> - Invoice statuses with pagination offset
Example:
WalletAccountSpark
Represents an individual Spark wallet account with full write access. Implements IWalletAccount from @tetherto/wdk-wallet. Extends WalletAccountReadOnlySpark, inheriting all read-only methods.
Note: WalletAccountSpark instances are created internally by WalletManagerSpark.getAccount() and are not intended to be constructed directly.
Methods
All methods from WalletAccountReadOnlySpark are inherited. The following additional methods are available:
| Method | Description | Returns |
|---|
getAddress() | Returns the account's Spark address | Promise<SparkAddressFormat> |
sign(message) | Signs a message using the account's identity key | Promise<string> |
sendTransaction(tx) | Sends a Spark transaction | Promise<{hash: string, fee: bigint}> |
transfer(options) | Transfers tokens to another address | Promise<{hash: string, fee: bigint}> |
getSingleUseDepositAddress() | Generates a single-use Bitcoin deposit address | Promise<string> |
claimDeposit(txId) | Claims a Bitcoin deposit to the wallet | Promise<WalletLeaf[] | undefined> |
claimStaticDeposit(txId) | Claims a static Bitcoin deposit to the wallet | Promise<WalletLeaf[] | undefined> |
refundStaticDeposit(options) | Refunds a static deposit back to a Bitcoin address | Promise<string> |
quoteWithdraw(options) | Gets a fee quote for withdrawing funds | Promise<CoopExitFeeQuote> |
withdraw(options) | Withdraws funds to a Bitcoin address | Promise<CoopExitRequest | null | undefined> |
createLightningInvoice(options) | Creates a Lightning invoice | Promise<LightningReceiveRequest> |
getLightningReceiveRequest(invoiceId) | Gets Lightning receive request by id | Promise<LightningReceiveRequest | null> |
getLightningSendRequest(requestId) | Gets Lightning send request by id | Promise<LightningSendRequest | null> |
payLightningInvoice(options) | Pays a Lightning invoice | Promise<LightningSendRequest> |
quotePayLightningInvoice(options) |
getAddress()
Returns the account's Spark network address.
Returns: Promise<SparkAddressFormat> - The account's Spark address
Example:
sign(message)
Signs a message using the account's identity key.
Parameters:
message (string): Message to sign
Returns: Promise<string> - Signature as hex string
Example:
getIdentityKey()
Returns the account's identity public key (hex-encoded).
Returns: Promise<string> - The identity public key
Example:
sendTransaction(tx)
Sends a Spark transaction and broadcasts it to the network.
Parameters:
tx (object): The transaction object
to (string): Recipient's Spark addressvalue (number): Amount in satoshis
Returns: Promise<{hash: string, fee: bigint}> - Object containing hash and fee (fee is always 0)
Example:
quoteSendTransaction(tx)
Estimates the fee for a Spark transaction without broadcasting it.
Parameters:
tx (object): Same as sendTransaction parameters
to (string): Recipient's Spark addressvalue (number): Amount in satoshis
Returns: Promise<{fee: bigint}> - Object containing estimated fee (always 0)
Example:
transfer(options)
Transfers tokens to another address.
Parameters:
options (TransferOptions): Transfer options object
token (string): Token identifier (Bech32m token identifier, e.g., btkn1...)amount (bigint): Amount of tokens to transferrecipient (string): Recipient Spark address
Returns: Promise<{hash: string, fee: bigint}> - Transfer result containing transaction details
Example:
quoteTransfer(options)
Quotes the costs of a transfer operation without executing it.
Parameters:
options (TransferOptions): Transfer options object
Returns: Promise<{fee: bigint}> - Transfer quote without transaction hash
Example:
getBalance()
Returns the account's total owned bitcoin balance in satoshis. This includes both available (spendable) sats and sats locked in pending outgoing transfers. This differs from WalletAccountReadOnlySpark.getBalance(), which only returns the available balance.
Returns: Promise<bigint> - Total owned balance in satoshis
Example:
getTokenBalance(tokenAddress)
Returns the available-to-send balance for a specific token. Inherited from WalletAccountReadOnlySpark; both classes return the same available-to-send value.
Parameters:
tokenAddress (string): Token identifier (Bech32m token identifier, e.g., btkn1...)
Returns: Promise<bigint> - Token balance in base unit (available to send)
Example:
getTransactionReceipt(hash)
Gets a Spark transfer by its ID. Inherited from WalletAccountReadOnlySpark. Only returns Spark transfers, not on-chain Bitcoin transactions.
Parameters:
hash (string): The Spark transfer ID
Returns: Promise<Object | null> - The Spark transfer object, or null if not found
Example:
getSingleUseDepositAddress()
Generates a single-use Bitcoin deposit address for funding the Spark wallet.
Returns: Promise<string> - Bitcoin deposit address
Example:
claimDeposit(txId)
Claims a Bitcoin deposit to add funds to the Spark wallet.
Parameters:
txId (string): Bitcoin transaction ID of the deposit
Returns: Promise<WalletLeaf[] | undefined> - Wallet leaves created from the deposit
Example:
claimStaticDeposit(txId)
Claims a static Bitcoin deposit to add funds to the Spark wallet.
Parameters:
txId (string): Bitcoin transaction ID of the deposit
Returns: Promise<WalletLeaf[] | undefined> - Wallet leaves created from the deposit
Example:
refundStaticDeposit(options)
Refunds a deposit made to a static deposit address back to a specified Bitcoin address. The minimum fee is 300 satoshis.
Parameters:
options (object): Refund options
depositTransactionId (string): The transaction ID of the original depositoutputIndex (number): The output index of the depositdestinationAddress (string): The Bitcoin address to send the refund tosatsPerVbyteFee (number): The fee rate in sats per vbyte for the refund transaction
Returns: Promise<string> - The refund transaction as a hex string that needs to be broadcast
Example:
quoteWithdraw(options)
Gets a fee quote for withdrawing funds from Spark cooperatively to an on-chain Bitcoin address.
Parameters:
options (object): Withdrawal quote options
withdrawalAddress (string): The Bitcoin address where the funds should be sentamountSats (number): The amount in satoshis to withdraw
Returns: Promise<CoopExitFeeQuote> - The withdrawal fee quote
Example:
withdraw(options)
Withdraws funds from the Spark network to an on-chain Bitcoin address.
Parameters:
options (WithdrawOptions): Withdrawal options object
onchainAddress (string): Bitcoin address to withdraw toamountSats (number): Amount in satoshis to withdraw- Additional options from
WithdrawParams may be supported
Returns: Promise<CoopExitRequest | null | undefined> - Withdrawal request details
Example:
Note: The fee quote is automatically fetched internally by the withdraw() method. Use quoteWithdraw() if you want to preview the fees before initiating a withdrawal.
createLightningInvoice(options)
Creates a Lightning invoice for receiving payments.
Parameters:
options (CreateLightningInvoiceParams): Invoice options object
amountSats (number, optional): Amount in satoshismemo (string, optional): Invoice description- Additional options from
CreateLightningInvoiceParams may be supported
Returns: Promise<LightningReceiveRequest> - Lightning invoice details
Example:
getLightningReceiveRequest(invoiceId)
Gets details of a previously created Lightning receive request.
Parameters:
invoiceId (string): Invoice ID
Returns: Promise<{id: string, invoice: string, status: string, value: number, memo?: string} | null> - Invoice details, or null if not found
Example:
getLightningSendRequest(requestId)
Gets a Lightning send request by id.
Parameters:
requestId (string): The id of the Lightning send request
Returns: Promise<LightningSendRequest | null> - The Lightning send request
Example:
payLightningInvoice(options)
Pays a Lightning invoice.
Parameters:
options (PayLightningInvoiceParams): Payment options object
encodedInvoice (string): BOLT11 Lightning invoicemaxFeeSats (number, optional): Maximum fee willing to pay in satoshis- Additional options from
PayLightningInvoiceParams may be supported
Returns: Promise<LightningSendRequest> - Payment details
Example:
quotePayLightningInvoice(options)
Estimates the fee for paying a Lightning invoice.
Parameters:
options (LightningSendFeeEstimateInput): Fee estimation options
encodedInvoice (string): BOLT11 Lightning invoice- Additional options may be supported
Returns: Promise<bigint> - Estimated fee in satoshis
Example:
createSparkSatsInvoice(options)
Creates a Spark invoice for receiving a sats payment.
Parameters:
options (object): Invoice options
amount (number, optional): The amount of sats to receive (optional for open invoices)memo (string, optional): Optional memo/description for the paymentsenderSparkAddress (SparkAddressFormat, optional): Optional Spark address of the expected senderexpiryTime (Date, optional): Optional expiry time for the invoice
Returns: Promise<SparkAddressFormat> - A Spark invoice that can be paid by another Spark wallet
Example:
createSparkTokensInvoice(options)
Creates a Spark invoice for receiving a token payment.
Parameters:
options (object): Invoice options
tokenIdentifier (string, optional): The Bech32m token identifier (e.g., btkn1...)amount (bigint, optional): The amount of tokens to receivememo (string, optional): Optional memo/description for the paymentsenderSparkAddress (SparkAddressFormat, optional): Optional Spark address of the expected senderexpiryTime (Date, optional): Optional expiry time for the invoice
Returns: Promise<SparkAddressFormat> - A Spark invoice that can be paid by another Spark wallet
Example:
paySparkInvoice(invoices)
Fulfills one or more Spark invoices by paying them.
Parameters:
invoices (SparkInvoice[]): Array of invoices to fulfill
- Each invoice has:
invoice (SparkAddressFormat): The Spark invoice to payamount (bigint, optional): Amount to pay (required for invoices without encoded amount)
Returns: Promise<FulfillSparkInvoiceResponse> - Response containing transaction results and errors
Example:
toReadOnlyAccount()
Creates a read-only version of this account that can query data but not sign transactions.
Returns: Promise<WalletAccountReadOnlySpark> - Read-only account instance
Example:
cleanupConnections()
Cleans up network connections and resources.
Returns: Promise<void>
Example:
dispose()
Disposes the wallet account, securely erasing the private key from memory.
Returns: void
Example:
Properties
| Property | Type | Description |
|---|
index | number | The derivation path index of this account |
path | string | The full BIP-44 derivation path |
keyPair | KeyPair | The account's public and private key pair |
🌐 Supported Networks
This package works with the Spark blockchain through the @buildonspark/spark-sdk. The following networks are supported:
- MAINNET - Spark production network
- TESTNET - Spark test network
- REGTEST - Spark regression test network (for development)
Network Configuration
Networks are configured using the network parameter in the wallet configuration:
Important Notes:
- Network connections are handled internally by the Spark SDK
- No custom RPC endpoints are supported - the SDK manages all network communication
- Network selection affects derivation paths and transaction routing
- Default network is
'MAINNET' if not specified
🔒 Security Considerations
🛠️ Development
Building
Testing
📜 License
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
🆘 Support
For support, please open an issue on the GitHub repository.
