@bitcoinerlab/coinselect/dist/coinselect.d.ts

A TypeScript library for Bitcoin transaction management, based on Bitcoin Descriptors for defining inputs and outputs. It facilitates optimal UTXO selection and transaction size calculation.

import type { OutputInstance } from '@bitcoinerlab/descriptors';
import { OutputWithValue } from './index';
/**
 * Selects UTXOs for a Bitcoin transaction.
 *
 * Sorts UTXOs by their descending net value
 * (each UTXO's value minus the fees needed to spend it).
 *
 * It initially attempts to find a solution using the
 * {@link avoidChange avoidChange} algorithm,
 * which aims to select UTXOs such that no change is required. If this is not
 * possible, it then applies the {@link addUntilReach addUntilReach} algorithm,
 * which adds UTXOs
 * until the total value exceeds the target value plus fees.
 * Change is added only if it's above the {@link dustThreshold dustThreshold}).
 *
 * UTXOs that do not provide enough value to cover their respective fee
 * contributions are automatically excluded.
 *
 * *NOTE:* When the descriptor in an input is `addr(address)`, it is assumed
 * that any `addr(SH_TYPE_ADDRESS)` is in fact a Segwit `SH_WPKH`
 * (Script Hash-Witness Public Key Hash).
 * For inputs using arbitrary scripts (not standard addresses),
 * use a descriptor in the format `sh(MINISCRIPT)`.
 *
 * @returns Object with selected UTXOs, targets, fee, and estimated vsize, or
 *          undefined if no solution is found.
 *
 * @example
 * ```
 * const { utxos, targets, fee, vsize } = coinselect({
 *   utxos: [
 *     { output: new Output({ descriptor: 'addr(...)' }), value: 2000n },
 *     { output: new Output({ descriptor: 'addr(...)' }), value: 4000n }
 *   ],
 *   targets: [
 *     { output: new Output({ descriptor: 'addr(...)' }), value: 3000n }
 *   ],
 *   remainder: new Output({ descriptor: 'addr(...)' }),
 *   feeRate: 1.34
 * });
 * ```
 *
 * @see {@link https://bitcoinerlab.com/modules/descriptors} for descriptor info.
 */
export declare function coinselect({ utxos, targets, remainder, feeRate, minimumFeeRate, dustRelayFeeRate }: {
    /**
     * Array of UTXOs for the transaction. Each UTXO includes an `OutputInstance`
     * and its value.
     */
    utxos: Array<OutputWithValue>;
    /**
     * Array of transaction targets. If specified, `remainder` is used
     * as the change address.
     */
    targets: Array<OutputWithValue>;
    /**
     * `OutputInstance` used as the change address when targets are specified,
     * or as the recipient address for maximum fund transactions.
     */
    remainder: OutputInstance;
    feeRate: number;
    /**
     * Minimum fee rate accepted for transaction fee validation. Defaults to the
     * standard relay floor and can be lowered for package relay use cases.
     * @defaultValue 0.1
     */
    minimumFeeRate?: number;
    /**
     * Fee rate used to calculate the dust threshold for transaction
     * outputs. Defaults to standard dust relay fee rate if not specified.
     * @defaultValue 3
     */
    dustRelayFeeRate?: number;
}): {
    utxos: OutputWithValue[];
    targets: OutputWithValue[];
    fee: bigint;
    vsize: number;
} | undefined;