Trait CoinSelectionSource

pub trait CoinSelectionSource {
    // Required methods
    fn select_confirmed_utxos(
        &self,
        claim_id: ClaimId,
        must_spend: Vec<Input>,
        must_pay_to: &[TxOut],
        target_feerate_sat_per_1000_weight: u32,
    ) -> Result<CoinSelection, ()>;
    fn sign_tx(&self, tx: Transaction) -> Result<Transaction, ()>;
}

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.

Required Methods

fn select_confirmed_utxos( &self, claim_id: ClaimId, must_spend: Vec<Input>, must_pay_to: &[TxOut], target_feerate_sat_per_1000_weight: u32, ) -> Result<CoinSelection, ()>

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 Inputs 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 TxOuts 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.

fn sign_tx(&self, tx: Transaction) -> Result<Transaction, ()>

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).

Implementors

impl<W, L> CoinSelectionSource for Wallet<W, L>

where W: Deref, L: Deref, <W as Deref>::Target: WalletSource, <L as Deref>::Target: Logger,