feat: anchor-fill UTXO selector for consolidation withdrawals

[karim-en]

Summary

Adds choose_utxos_anchor_fill — a new UTXO selector for bridge withdrawals
that picks the maximum number of inputs allowed by max_gas_fee rather
than the minimum. Each withdrawal then doubles as a consolidation step, so
the pool drifts toward fewer, larger UTXOs over time instead of fragmenting
with every change output.

Lives alongside the existing choose_utxos_random; callers opt in by name.

How it works

Every selection has the shape K-1 fillers + 1 anchor:

• fillers — K-1 smaller UTXOs we want to consume (smallest-first
  maximises consolidation).
• anchor — one larger UTXO sized so sum_inputs ≈ net_amount, leaving a
  valid single change in [min_change_amount, min(max_change_amount, min_filler)).

For each K from K_max down to 1:

1. Skip if even the best-case fee (get_gas_fee(K, 1, …)) exceeds the budget.
2. Slide a (K-1)-wide filler window across the sorted pool; binary-search the
   tail for an anchor that lands the total in the valid window (either exact
   absorption or single-piece change).
3. Compute the actual fee using the real output count produced (1 target +
   0-or-1 change) and reject if it exceeds max_gas_fee.

The "max within budget" strategy is the opposite of the existing min-fee
random selector. Used together with active utxo management, it keeps the
pool consolidated as a side-effect of normal withdrawals.

Constraints honored

• 1 target + ≤1 change — never splits change into multiple pieces.
  valid_change_max = min(max_change_amount, min_filler). No split_change
  calls; selector rejects K/anchor combos whose change would need to split.
• change_i < min_input — enforced by the anchor window.
• change_i ∈ [min_change_amount, max_change_amount) — same.
• HIGH zone (pool_size > passive_management_upper_limit) — pool is
  filtered to balance ≤ net_amount upfront so the input_num > change_num
  rule is structurally satisfied.
• LOW zone (pool_size < passive_management_lower_limit) — selector
  returns Err upfront. LOW zone requires input_num < change_num, which is
  unreachable when change_num ≤ 1; caller should run active utxo management
  instead.

Trade-offs vs choose_utxos_random

Sweep on a 100-UTXO tiered pool, amount 1.5M sat, fee_rate 3000:

max_gas_fee	inputs	outputs	actual fee
200000	23	2	4939
100000	23	2	4939
50000	23	2	4939
20000	23	2	4939
10000	23	2	4939
5000	23	2	4939
3000	13	2	2947
2000	8	2	1951
1000	3	2	955
500	(infeasible — best-case 1-input fee exceeds budget)

choose_utxos_random typically picks 1 input + 1 change for the same setup
regardless of budget. With anchor-fill, an over-funded max_gas_fee actually
gets used to consume small UTXOs.

Test plan

• anchor_fill_sweep_input_count_vs_budget — table sweep showing input
  counts climb with budget; every selection passes invariant checks
  (uniqueness, balance equation, single-piece change, fee ≤ budget).
• anchor_fill_picks_more_inputs_at_larger_budget — monotonicity smoke
  test.
• anchor_fill_accepts_budget_that_pessimistic_bound_would_reject —
  regression test pinning the per-candidate fee check (an earlier
  upfront worst_case_num_output = 1 + max_change_number bound would
  silently reject budgets that real 2-output selections fit easily).
• anchor_fill_errors_when_budget_too_small — too-tight budget returns
  a clear error.
• anchor_fill_rejects_low_zone — LOW-zone calls must Err with a
  pointer to active utxo management.
• anchor_fill_never_produces_more_than_two_outputs — invariant sweep
  across budget range.
• cargo build + cargo clippy -p utxo-utils clean.

[frolvanya]

We could add something like if max_gas_fee < 5000 * num_output + orchard_offset { return 0; } here

[olga24912]

What I don’t like is that on small transactions — where we already significantly increased the gas fee to avoid transactions getting stuck — we’re now also replacing a single input with 25 inputs. At that point, the fee becomes disproportionately large compared to the transaction itself.

[olga24912]

Also, it would be good to simulate how often our UTXO selection would run into conflicts during parallel selection.

[karim-en]

What I don’t like is that on small transactions — where we already significantly increased the gas fee to avoid transactions getting stuck — we’re now also replacing a single input with 25 inputs. At that point, the fee becomes disproportionately large compared to the transaction itself.

The relayer can pass the adjusted max_gas_fee, for example 0.75 or 0.5 of it, not the real max_gas_fee

[karim-en]

@copilot resolve the merge conflicts in this pull request

[Copilot]

@copilot resolve the merge conflicts in this pull request

Done. Merged origin/main into this branch (commit 9b6f6a9). The four conflict regions in omni_connector.rs were resolved by combining both sides:

• near_submit_btc_transfer: signature now takes max_gas_fee, change_reserve, and memo; all three are forwarded to extract_utxo
• near_submit_btc_transfer_with_tx_hash: passes memo from main alongside the existing None for change_reserve
• extract_utxo: signature takes all three new parameters; anchor-fill dispatch + memo/orchard handling are both preserved

Build and tests are clean.