@xchainjs/xchain-utxo/lib/client.d.ts

Genereic UTXO client for XChainJS

import { BaseXChainClient, ExplorerProviders, FeeEstimateOptions, FeeRate, FeeRates, Fees, FeesWithRates, Protocol, TxHash, TxHistoryParams } from '@xchainjs/xchain-client';
import { Address, Asset, Chain } from '@xchainjs/xchain-util';
import { UtxoOnlineDataProviders } from '@xchainjs/xchain-utxo-providers';
import { Balance, PreparedTx, Tx, TxParams, TxsPage, UTXO, UtxoClientParams } from './types';
import { UtxoSelectionPreferences, UtxoSelectionResult } from './strategies';
/**
 * Abstract base class for creating blockchain clients in the UTXO model.
 */
export declare abstract class Client extends BaseXChainClient {
    protected explorerProviders: ExplorerProviders;
    protected dataProviders: UtxoOnlineDataProviders[];
    /**
     * Constructor for creating a UTXO client instance.
     *
     * @param {Chain} chain The blockchain chain type.
     * @param {UtxoClientParams} params The parameters required for client initialization.
     */
    constructor(chain: Chain, params: UtxoClientParams);
    /**
     * Get the explorer URL based on the network.
     *
     * @returns {string} The explorer URL.
     */
    getExplorerUrl(): string;
    /**
     * Get the explorer URL for a given address based on the network.
     *
     * @param {string} address The address to query.
     * @returns {string} The explorer URL for the address.
     */
    getExplorerAddressUrl(address: string): string;
    /**
     * Get the explorer URL for a given transaction ID based on the network.
     *
     * @param {string} txID The transaction ID.
     * @returns {string} The explorer URL for the transaction.
     */
    getExplorerTxUrl(txID: string): string;
    /**
     * Get the transaction history of a given address with pagination options.
     *
     * @param {TxHistoryParams} params The options to get transaction history.
     * @returns {TxsPage} The transaction history.
     */
    getTransactions(params?: TxHistoryParams): Promise<TxsPage>;
    /**
     * Get the transaction details of a given transaction ID.
     *
     * @param {string} txId The transaction ID.
     * @returns {Tx} The transaction details.
     */
    getTransactionData(txId: string): Promise<Tx>;
    /**
     * Gets balance of a given address.
     *
     * @param {Address} address The address to get balances from
     * @param {undefined} Needed for legacy only to be in common with `XChainClient` interface - will be removed by a next version
     * @param {confirmedOnly} Flag to get balances of confirmed txs only
     *
     * @returns {Balance[]} BTC balances
     */
    getBalance(address: Address, _assets?: Asset[], _confirmedOnly?: boolean): Promise<Balance[]>;
    /**
     * Scan UTXOs for a given address.
     *
     * @param {string} address The address to scan.
     * @param {boolean} confirmedOnly Flag to scan only confirmed UTXOs.
     * @returns {UTXO[]} The UTXOs found.
     */
    protected scanUTXOs(address: string, confirmedOnly?: boolean): Promise<UTXO[]>;
    /**
     * Get UTXOs for a given address.
     * Public wrapper around the protected scanUTXOs method for coin control.
     *
     * @param {string} address The address to get UTXOs for.
     * @param {boolean} confirmedOnly Whether to only return confirmed UTXOs. Default: true.
     * @returns {Promise<UTXO[]>} The UTXOs for the address.
     */
    getUTXOs(address: string, confirmedOnly?: boolean): Promise<UTXO[]>;
    /**
     * Get estimated fees with fee rates.
     *
     * @param {FeeEstimateOptions} options Options for fee estimation.
     * @returns {Promise<FeesWithRates>} Estimated fees along with fee rates.
     */
    getFeesWithRates(options?: FeeEstimateOptions): Promise<FeesWithRates>;
    /**
     * Get estimated fees.
     *
     * @param {FeeEstimateOptions} options Options for fee estimation.
     * @returns {Promise<Fees>} Estimated fees.
     */
    getFees(options?: FeeEstimateOptions): Promise<Fees>;
    /**
     * Get fee rates
     * @param {Protocol} protocol Protocol to interact with. If there's no protocol provided, fee rates are retrieved from chain data providers
     *
     * @returns {FeeRates} The fee rates (average, fast, fastest) in `Satoshis/byte`
     */
    getFeeRates(protocol?: Protocol): Promise<FeeRates>;
    /**
     * Broadcast a transaction.
     *
     * @param {string} txHex The transaction hex string.
     * @returns {Promise<TxHash>} The transaction hash.
     */
    broadcastTx(txHex: string): Promise<TxHash>;
    /**
     * Round-robin method to get balance from data providers.
     * Throws error if no provider can get balance.
     *
     * @param {Address} address The address to get balance for.
     * @returns {Promise<Balance[]>} The balances.
     * @throws Error If no provider is able to get balance.
     */
    protected roundRobinGetBalance(address: Address): Promise<Balance[]>;
    /**
     * Round-robin method to get unspent transactions from data providers.
     * Throws error if no provider can get unspent transactions.
     *
     * @param {Address} address The address to get unspent transactions for.
     * @param {boolean} confirmed Flag to indicate whether to get confirmed transactions only.
     * @returns {Promise<UTXO[]>} The unspent transactions.
     * @throws Error If no provider is able to get unspent transactions.
     */
    protected roundRobinGetUnspentTxs(address: Address, confirmed: boolean): Promise<UTXO[]>;
    /**
     * Round-robin method to get transaction data from data providers.
     * Throws error if no provider can get transaction data.
     *
     * @param {string} txid The transaction ID to get data for.
     * @returns {Promise<Tx>} The transaction data.
     * @throws Error If no provider is able to get transaction data.
     */
    protected roundRobinGetTransactionData(txid: string): Promise<Tx>;
    /**
     * Round-robin method to get transactions from data providers.
     * Throws error if no provider can get transactions.
     *
     * @param {TxHistoryParams} params The parameters for fetching transactions.
     * @returns {Promise<TxsPage>} The transaction history.
     * @throws Error If no provider is able to get transactions.
     */
    protected roundRobinGetTransactions(params: TxHistoryParams): Promise<TxsPage>;
    /**
     * Broadcasts a transaction hex using a round-robin approach across multiple data providers.
     * @param {string} txHex The transaction hex to broadcast.
     * @returns {Promise<TxHash>} The hash of the broadcasted transaction.
     * @throws {Error} Throws an error if no provider is able to broadcast the transaction.
     */
    protected roundRobinBroadcastTx(txHex: string): Promise<string>;
    /**
     * Enhanced UTXO selection using the UtxoSelector with multiple strategies.
     * This method is available to all UTXO chain implementations.
     *
     * @param utxos Available UTXOs to select from
     * @param targetValue Target amount in satoshis
     * @param feeRate Fee rate in satoshis per byte
     * @param extraOutputs Number of extra outputs (default: 2 for recipient + change)
     * @param preferences Selection preferences
     * @returns Selection result with inputs, change, and fee
     */
    protected selectUtxosForTransaction(utxos: UTXO[], targetValue: number, feeRate: number, extraOutputs?: number, preferences?: UtxoSelectionPreferences): UtxoSelectionResult;
    /**
     * Validate transaction inputs using comprehensive validation.
     * Chain implementations can override to add chain-specific validation.
     *
     * @param params Transaction parameters including sender and feeRate
     */
    protected validateTransactionInputs(params: TxParams & {
        sender: Address;
        feeRate: FeeRate;
    }): void;
    /**
     * Calculate maximum sendable amount by using ALL available UTXOs.
     *
     * For a true sweep operation, we use all UTXOs to maximize the sent amount.
     * This is simpler and more correct than binary search with UTXO selection.
     *
     * @param utxos Available UTXOs
     * @param feeRate Fee rate in satoshis per byte
     * @param hasMemo Whether transaction has a memo
     * @param preferences UTXO selection preferences
     * @returns Maximum sendable amount, fee, and selected inputs
     */
    protected calculateMaxSendableAmount(utxos: UTXO[], feeRate: number, hasMemo: boolean, preferences?: UtxoSelectionPreferences): {
        amount: number;
        fee: number;
        inputs: UTXO[];
    };
    /**
     * Get and validate UTXOs for transaction building.
     *
     * @param sender Sender address
     * @param confirmedOnly Whether to only use confirmed UTXOs
     * @returns Validated UTXO array
     */
    protected getValidatedUtxos(sender: Address, confirmedOnly: boolean): Promise<UTXO[]>;
    /**
     * Prepare transaction with enhanced UTXO selection.
     * Chain implementations should override buildTxPsbt to provide chain-specific PSBT construction.
     *
     * @param params Transaction parameters
     * @returns Prepared transaction with UTXO details
     */
    prepareTxEnhanced({ sender, memo, amount, recipient, spendPendingUTXO, feeRate, utxoSelectionPreferences, selectedUtxos, }: TxParams & {
        sender: Address;
        feeRate: FeeRate;
        spendPendingUTXO?: boolean;
        utxoSelectionPreferences?: UtxoSelectionPreferences;
        selectedUtxos?: UTXO[];
    }): Promise<PreparedTx>;
    /**
     * Prepare maximum amount transfer (sweep transaction).
     *
     * @param params Send max parameters
     * @returns Prepared transaction with maximum sendable amount
     */
    prepareMaxTx({ sender, recipient, memo, feeRate, spendPendingUTXO, utxoSelectionPreferences, selectedUtxos, }: {
        sender: Address;
        recipient: Address;
        memo?: string;
        feeRate: FeeRate;
        spendPendingUTXO?: boolean;
        utxoSelectionPreferences?: UtxoSelectionPreferences;
        selectedUtxos?: UTXO[];
    }): Promise<PreparedTx & {
        maxAmount: number;
        fee: number;
    }>;
    /**
     * Abstract method to validate an address for this chain.
     * @param address The address to validate
     * @returns true if valid, false otherwise
     */
    abstract validateAddress(address: string): boolean;
    /**
     * Abstract method to compile a memo.
     * @param memo The memo string to compile.
     * @returns The compiled memo.
     */
    protected abstract compileMemo(memo: string): Buffer;
    /**
     * Build a PSBT for this chain.
     * Chain implementations should override this to provide chain-specific PSBT construction.
     * Default implementation throws - override in chain client to enable enhanced methods.
     *
     * @param params PSBT build parameters
     * @returns Base64-encoded PSBT string
     */
    protected buildTxPsbt(_params: {
        inputs: UTXO[];
        recipient: Address;
        amount: number;
        changeAmount: number;
        changeAddress: Address;
        memo: Buffer | null;
    }): Promise<string>;
    /**
     * Abstract method to calculate the fee from a list of UTXOs.
     * @param inputs The list of UTXOs.
     * @param feeRate The fee rate.
     * @param data Optional data buffer.
     * @returns The calculated fee.
     */
    protected abstract getFeeFromUtxos(inputs: UTXO[], feeRate: FeeRate, data: Buffer | null): number;
    /**
     * Retrieves fee rates using a round-robin approach across multiple data providers.
     * @returns {Promise<FeeRates>} The fee rates (average, fast, fastest) in `Satoshis/byte`.
     * @throws {Error} Throws an error if no provider is able to retrieve fee rates.
     */
    protected roundRobinGetFeeRates(): Promise<FeeRates>;
    abstract transfer(params: TxParams & {
        feeRate?: number;
    }): Promise<string>;
}