feat(wallet): add support for bip-431 rules 4 and 5

[yan-pi]

partially addresses #477
depends on #478
solves #484
solves #485

Description

Enforces BIP-431 Rules 4 and 5 inside create_tx, before returning a PSBT:

• Rule 4: rejects any TRUC (nVersion=3) transaction with sigop-adjusted vsize over 10,000 vB
• Rule 5: tightens the cap to 1,000 vB when the transaction has an unconfirmed TRUC ancestor

Without this, build_tx().version(3).finish() can hand back a PSBT that bitcoind rejects at broadcast.

When the cap is exceeded, create_tx returns the new CreateTxError::TrucSizeExceeded { cap_vb, actual_vb }, so callers can tell which rule fired and by how much.

Adding a variant to the public CreateTxError is a breaking change, this is acceptable since the PR targets the 4.0 release.

This adds estimate_truc_vsize as a private helper and reuses the is_truc helper introduced in #478.

This does not address Rules 1–3 (topology / package limits), that's a separate concern tracked in #477 and #478.

Notes to the reviewers

The check runs after coin_select and before complete_transaction.

CoinSelection::coin_select consumes Vec<WeightedUtxo> and returns Vec<Utxo>, so the per-input satisfaction_weight is gone by the time we'd want it.

We pre-collect a HashMap<OutPoint, Weight> from the WeightedUtxo list before handing it to the selector.
The map is only allocated when version == 3.

For the Rule 5 ancestor check, foreign UTXOs are conservatively treated as non-TRUC.
Same posture as the existing TRUC filter in filter_utxos.

We use plain weight / 4. Bitcoind's TRUC check uses sigop-adjusted vsize (max(weight, sigops * 20) / 4), which matches plain weight/4 for P2WPKH, P2TR and ordinary P2WSH.

#477 should have a follow-up to track proper sigop accounting.

Changelog notice

Added CreateTxError::TrucSizeExceeded { cap_vb, actual_vb }.
`create_tx` now enforces BIP-431 Rules 4 and 5 (vsize caps) for nVersion=3 transactions.

Checklists

All Submissions:

• I've signed all my commits
• I followed the contribution guidelines
• I ran just p before pushing

New Features:

• I've added tests for the new feature
• I've added docs for the new feature

Bugfixes:

• This pull request breaks the existing API
• I've added tests to reproduce the issue which are now passing
• I'm linking the issue being fixed by this PR

[codecov]

Codecov Report

❌ Patch coverage is 89.28571% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.91%. Comparing base (7982b6e) to head (eff5481).
⚠️ Report is 30 commits behind head on master.

Files with missing lines	Patch %	Lines
src/wallet/error.rs	0.00%	4 Missing ⚠️
src/wallet/mod.rs	96.15%	0 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #493      +/-   ##
==========================================
+ Coverage   81.22%   81.91%   +0.68%     
==========================================
  Files          24       25       +1     
  Lines        5565     6529     +964     
  Branches      248      301      +53     
==========================================
+ Hits         4520     5348     +828     
- Misses        969     1081     +112     
- Partials       76      100      +24     

Flag	Coverage Δ
rust	81.91% <89.28%> (+0.68%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[oleonardolima]

@yan-pi I updated my branch to remove the bdk_testenv dependency, you can rebase this one to get a green CI (though you might need to update your tests).

[oleonardolima]

@yan-pi the CI still failing

[yan-pi]

Rebased this on top of the updated #478 branch.

I dropped the old bdk_testenv e2e test and kept the TRUC Rule 4/5 coverage in-memory.

[oleonardolima]

@yan-pi did you manage to do it as a non-breaking change ? I agree that having the error would be the right approach, though it would only land in the next major release.

[yan-pi]

I dropped the new variant and mapped the TRUC size-cap rejection to the existing CreateTxError::CoinSelection(InsufficientFunds { .. }) instead.

This one seems to be the best one to handle the current error without the breaking change.

[yan-pi]

rebased on top of 7982b6e

[yan-pi]

Since this moved to 4.0, I want to check if I understood the direction.

coin-select#51 now has Target::max_weight and MaxWeightExceeded. The current wallet CoinSelectionAlgorithm does not use bdk_coin_select or take a weight limit though, so bringing that here would mean changing the public trait and built-in selectors. bdk-tx#47 seems to be handling something similar in the new path.

@ValuedMammal is that what you had in mind for #493: change the current coin-selection API, or keep the final Rules 4/5 check here and leave max-weight-aware selection for bdk_tx?

I also noticed the cap isn't fixed: it's 10k without an unconfirmed ancestor and 1k when the selection has one, so I think we may need two selection attempts.

btw, I used AI while researching this, mostly to understand how the current coin-selection work fits together across the repos.

[ValuedMammal]

@yan-pi I would say bring back the error you had originally designed for and keep the TRUC_MAX_VSIZE_VB validation logic the same.

[yan-pi]

Ive restored the dedicated CreateTxError::TrucSizeExceeded { cap_vb, actual_vb } variant. I Think its ready for another review round, or ready to be merged.

[110CodingP]

@oleonardolima @ValuedMammal we were planning to remove the TxBuilder in 4.0 right? so these changes should be done to create_psbt instead?