feat: add consolidation input selection strategy #557

IgnacioPorte · 2025-02-28T02:00:12Z

Add Consolidation Input Selection Strategy

Overview

This PR introduces a new input selection strategy for receivers that optimizes for UTXO consolidation. This enables receivers to use payjoins as an opportunity to consolidate their UTXOs efficiently, improving their wallet's long-term UTXO management.

Features

New SelectionStrategy::Consolidate option for receiver input selection
Configurable parameters to control consolidation behavior:
- max_consolidation_fee_rate: Only consolidate when fees are below this threshold
- max_inputs: Limit the number of inputs to add
- target_value: Optionally stop adding inputs after reaching a target amount
- dust_limit: Minimum value for inputs to be considered

Implementation Details

Inputs are sorted by value (ascending) and added until reaching either max_inputs or target_value
Consolidation only proceeds if current transaction fee rate is below the specified threshold
Maintains compatibility with existing privacy-preserving selection strategy
V2 receiver implementation delegates to V1 for actual consolidation logic

Considerations

Testing pending
CLI changes pending to expose consolidation strategy and its parameters
While providing numerous parameters could offer flexibility, it might also lead to unnecessary complexity. We need to strike the right balance between configurability and simplicity.

Related Issues

#460

coveralls · 2025-03-03T17:30:58Z

Pull Request Test Coverage Report for Build 13778844253

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

For more information on this, see Tracking coverage changes with pull request builds.
To avoid this issue with future PRs, see these Recommended CI Configurations.
For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

5 of 81 (6.17%) changed or added relevant lines in 3 files are covered.
11 unchanged lines in 1 file lost coverage.
Overall coverage decreased (-1.2%) to 78.547%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
payjoin/src/receive/error.rs	0	3	0.0%
payjoin/src/receive/v2/mod.rs	5	30	16.67%
payjoin/src/receive/v1/mod.rs	0	48	0.0%

Files with Coverage Reduction	New Missed Lines	%
payjoin/src/receive/v2/mod.rs	11	79.79%

Totals
Change from base Build 13751979319:	-1.2%
Covered Lines:	4562
Relevant Lines:	5808

💛 - Coveralls

payjoin/src/receive/v1/mod.rs

DanGould

This is neat and well thought out. Thank you for the change!

I'd lilke to see a docstring applied to the v2::try_consolidate function as well.

other than that, I believe the most important question left to decide is at what point this is clear enough to include in the API, and whether or not we want to list it as experimental. I will ask BullBitcoin what they think of it. Assuming our other API changes are on track time-wise that we have review capacity to get this into the next release, I welcome the addition.

payjoin/src/receive/v1/mod.rs

payjoin/src/receive/error.rs

Add a new input selection strategy that optimizes for consolidation when fees are low. This strategy allows receivers to combine multiple UTXOs in a payjoin, subject to configurable constraints: - Maximum fee rate threshold for consolidation - Maximum number of inputs to add - Optional target value to reach - Minimum input value (dust limit) The strategy sorts candidate inputs by value and adds them until reaching either the max inputs limit or target value, but only when the current fee rate is below the specified threshold.

IgnacioPorte mentioned this pull request Feb 28, 2025

Improve Coin Selection API #460

Open

DanGould added the enhancement New feature or request label Mar 3, 2025