Best Practices

Recommendations for Balance

Filter Ordinals

Set filterOrdinals to true when querying balances to ensure the result reflects only spendable satoshis, excluding any UTXOs that contain ordinal inscriptions.

Batch Requests

When querying more than one address, use getBalances() to fetch all balances in a single request rather than calling getBalance() in a loop.

Cache Results

Cache balance results locally and invalidate on new block confirmations to minimize redundant RPC calls, especially in applications that query the same addresses frequently.

For multiple distinct method calls on the same contract instance, use Promise.all() to execute them concurrently instead of awaiting each one sequentially.

Handle Errors

Balance queries can fail due to network timeouts, RPC unavailability, or invalid addresses. Always wrap calls in try-catch blocks and handle failures gracefully.

Format for Users

When displaying balances to users, convert satoshis to BTC.

Recommendations for Transaction

Always Buffer for Fees

When fetching UTXOs, request an amount slightly higher than the intended transfer value to ensure there are enough satoshis to cover the transaction fees. Without this buffer, the transaction may fail due to insufficient funds after fee deduction.

Track UTXO State

After a successful broadcast, call spentUTXO() on the UTXOManager to mark the consumed UTXOs as spent. This keeps your local UTXO state in sync with the network and prevents double-spend attempts in subsequent transactions.

Handle Broadcast Errors

Always inspect the broadcast response for errors before proceeding. A successful HTTP response does not guarantee the transaction was accepted by the network. The response may contain rejection reasons such as insufficient fees, invalid signatures, or conflicting inputs.

Use Appropriate Fee Rates

Query current network conditions via gasParameters() before sending time-sensitive transactions. Fee rates fluctuate with mempool congestion, and using outdated estimates may result in delayed confirmation or overpayment.

Avoid Dust Outputs

The Bitcoin network enforces a minimum output value known as the dust threshold. Outputs below 330 satoshis are rejected by nodes as uneconomical to spend. Ensure all transfer amounts and change outputs exceed this limit.

Consolidate Regularly

Wallets that accumulate many small UTXOs produce larger transactions with higher fees. Periodically consolidate small UTXOs into fewer, larger outputs during low-fee periods to reduce costs on future transactions.

Split for Concurrency

When sending multiple transactions in parallel, each one requires its own set of input UTXOs. Split a large UTXO into several smaller outputs beforehand so that each parallel transaction can draw from an independent input without conflicting.

Recommendations for UTXOs

Track Spent UTXOs

Always call spentUTXO() immediately after broadcasting a transaction to keep the local UTXO state accurate and prevent double-spend attempts in subsequent operations.

Use Optimization

Enable optimize: true when fetching UTXOs to let the manager select fewer, larger UTXOs — producing smaller transactions with lower fees.

Handle Chain Limits

OP_NET enforces a 25 unconfirmed transaction chain limit. Track your pending transaction count and wait for confirmations before exceeding this threshold.

Clean Periodically

Call clean() after transactions are confirmed to discard stale cached data and ensure subsequent queries reflect the current blockchain state.

Batch Queries

Use getMultipleUTXOs() to fetch UTXOs for multiple addresses in a single request instead of querying each address individually.

Recommendations for UTXOs Consolidation

Monitor UTXO Count

Keep the total number of UTXOs in your wallet at a manageable level, ideally below 50. A high UTXO count inflates transaction sizes and fees.

Consolidate During Low Fees

Perform consolidation transactions during periods of low network fees to minimize the cost of merging multiple inputs.

Avoid Dust Creation

Ensure all outputs exceed the 330 satoshi dust threshold. Outputs below this value are rejected by the network and cannot be spent.

Split for Parallel Operations

Split UTXOs into separate outputs before running batch operations, so each parallel transaction has its own independent input.

Regular Maintenance

Periodically analyze your wallet's UTXO distribution and consolidate when fragmentation increases beyond acceptable levels.

Track UTXO State

Always call spentUTXO() after broadcasting transactions to keep the local UTXO state in sync and prevent double-spend errors.