Package org.ldk.structs

Class CoinSelectionSource

  • public class CoinSelectionSource
extends Object
    An abstraction over a bitcoin wallet that can perform coin selection over a set of UTXOs and can sign for them. The coin selection method aims to mimic Bitcoin Core's `fundrawtransaction` RPC, which most wallets should be able to satisfy. Otherwise, consider implementing [`WalletSource`], which can provide a default implementation of this trait when used with [`Wallet`].

    • Method Detail

      • destroy

        public void destroy()
        Destroys the object, freeing associated resources. After this call, any access to this object may result in a SEGFAULT or worse. You should generally NEVER call this method. You should let the garbage collector do this for you when it finalizes objects. However, it may be useful for types which represent locks and should be closed immediately to avoid holding locks until the GC runs.

      • select_confirmed_utxos

        public Result_CoinSelectionNoneZ select_confirmed_utxos​(byte[] claim_id,
                                                        Input[] must_spend,
                                                        TxOut[] must_pay_to,
                                                        int target_feerate_sat_per_1000_weight)
        Performs coin selection of a set of UTXOs, with at least 1 confirmation each, that are available to spend. Implementations are free to pick their coin selection algorithm of choice, as long as the following requirements are met: 1. `must_spend` contains a set of [`Input`]s that must be included in the transaction throughout coin selection, but must not be returned as part of the result. 2. `must_pay_to` contains a set of [`TxOut`]s that must be included in the transaction throughout coin selection. In some cases, like when funding an anchor transaction, this set is empty. Implementations should ensure they handle this correctly on their end, e.g., Bitcoin Core's `fundrawtransaction` RPC requires at least one output to be provided, in which case a zero-value empty OP_RETURN output can be used instead. 3. Enough inputs must be selected/contributed for the resulting transaction (including the inputs and outputs noted above) to meet `target_feerate_sat_per_1000_weight`. Implementations must take note that [`Input::satisfaction_weight`] only tracks the weight of the input's `script_sig` and `witness`. Some wallets, like Bitcoin Core's, may require providing the full input weight. Failing to do so may lead to underestimating fee bumps and delaying block inclusion. The `claim_id` must map to the set of external UTXOs assigned to the claim, such that they can be re-used within new fee-bumped iterations of the original claiming transaction, ensuring that claims don't double spend each other. If a specific `claim_id` has never had a transaction associated with it, and all of the available UTXOs have already been assigned to other claims, implementations must be willing to double spend their UTXOs. The choice of which UTXOs to double spend is left to the implementation, but it must strive to keep the set of other claims being double spent to a minimum.

      • sign_tx

        public Result_TransactionNoneZ sign_tx​(byte[] tx)
        Signs and provides the full witness for all inputs within the transaction known to the trait (i.e., any provided via [`CoinSelectionSource::select_confirmed_utxos`]).