Add Target::max_weight, built on the metric-decides-change refactor (#49)

[evanlinjin]

Alternative to #48 for capping transaction weight during coin selection — e.g. TRUC / BIP-431 packages limited to 10,000 / 1,000 vB.

The key design choice: this is built on the metric-decides-change refactor (#49), because that's what keeps the weight cap from breaking LowestFee's branch-and-bound bound (see Why build on #49).

Four commits: (1) logic, (2) tests, (3) a pure rename of the value-feasibility predicates, (4) an optional bound speedup.

Approach

• Target::max_weight: Option<u64> — a feasibility constraint that mirrors the value target: value is a lower bound, max_weight an upper bound.
• These two have opposite monotonicity, so they stay separate predicates: the value check stays monotone (is_funded), the cap is a distinct anti-monotone check (is_within_max_weight). That separation is what preserves the monotonicity the BnB bounds rely on.
• The cap is enforced only where a selection is committed:
  • LowestFee (which owns the change decision post-feat!: BnB metrics decide the change output themselves #49): refuses change that would bust the cap, rejects any over-cap selection, and prunes subtrees whose lightest (no-drain) form already busts it.
  • select_until_target_met now returns SelectError::MaxWeightExceeded instead of silently returning an over-cap selection.

Why build on #49

LowestFee's branch-and-bound rests on one claim about its bound: a selection with a worthwhile change output can't be beaten by a descendant that adds inputs to become changeless. Whether that holds depends on who decides the change policy.

Before #49, the change policy is decoupled from the metric, so a selection can carry a change output that doesn't actually minimize the fee. Pile non-effective inputs onto it — each costs more in fee than it adds in value, shrinking the excess — until the change vanishes, and the resulting changeless selection can score better. The bound trusted the with-change score as a floor for the subtree; now it's too high, BnB prunes the branch holding the real optimum, and you get a suboptimal selection. (This is the inadmissibility #48 runs into.)

After #49, the metric owns the decision: change is added only when it strictly lowers the long-term fee (change_value > spend_fee). Now dropping a worthwhile change can never help. With A a worthwhile-change selection and B = A + inputs (added value v ≥ 0) made changeless:

LTF_A = (selected_A − target − change_value) + spend_fee   // recovers the change
LTF_B =  selected_B − target                               // burns the excess
LTF_B − LTF_A = v + change_value − spend_fee  >  0         // change_value > spend_fee, v ≥ 0

B always costs more, so the bound stays admissible.

And that's exactly what max_weight needs. The cap enforces itself by refusing a change output that would bust it — i.e. it can force a descendant to be changeless. The proof never asks why B is changeless, only that A's change was worthwhile. So on the #49 base the cap needs nothing more than a weight hard-prune — no bound rewrite, no lost optimality. Fold it into the value predicate on the old base instead, and the suboptimality above comes right back.

Commit 3: renamed predicates

Target now carries two constraints of opposite monotonicity, so the value-only predicates are renamed to say so — "funded/fundable" is money-centric and naturally excludes weight, and -ed/-able distinguishes "this selection covers the value" from "these candidates can cover it":

is_target_met → is_funded, is_target_met_with_drain → is_funded_with_drain, is_selection_possible → is_fundable.

Commit 4: cap-aware bound (optional speedup)

Correctness only needs the hard-prune above. Commit 4 additionally teaches the bound about the cap — pruning subtrees that are still under-cap but provably can't reach the value target without busting it. It never changes the result (and stays admissible — the ensure_bound_is_not_too_tight proptest passes), but it's a large win in the tight-cap regime a safety rail actually lives in.

Measured BnB rounds to completion on a variable-weight pool, cap-aware bound off → on:

max_weight	rounds off → on
too tight (infeasible)	whole tree (millions, never terminates) → 0
binds the optimum	~13.5k → 33–359
tight, optimum still fits	~5.3k → ~2.4k
loose (cap doesn't bite)	~5.3k → ~5.3k (no-op)

The headline is the first row: for a too-tight cap the bound proves infeasibility instantly, instead of enumerating the entire subtree before giving up.

Testing

• max_weight is threaded through the LowestFee proptests, so BnB is checked against exhaustive search with the cap active.
• A new bnb_respects_max_weight proptest cross-checks BnB feasibility against an independent exhaustive oracle — this is what validates the weight hard-prune.

Breaking changes

• Target { .. } literals now require a max_weight field.
• The predicates renamed above (is_target_met → is_funded, etc.).

🤖 Generated with Claude Code