Add apply_unconfirmed_txs_events and apply_evicted_txs_events

[notmandatory]

Description

fixes #374

Notes to the reviewers

To reduce duplicate code I also refactored all the _events functions to use new wallet_txs_to_map helper.

Changelog notice

• Add Wallet::apply_unconfirmed_txs_events
• Add Wallet::apply_evicted_txs_events
• Add Wallet::events_helper function for advanced users

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

[notmandatory]

Per discussion in #374 I'm happy to deprecate these _events functions and replace them with some sort of CanonicalView::diff once that feature is available in bdk_chain. But for now I expect we'll be shipping 3.0 with the current bdk_chain 0.23.

If we agree to go this direction for 3.0 then I'll finish adding tests and cherry-pick these commits back to the release/2.x branch.

[codecov]

Codecov Report

❌ Patch coverage is 78.57143% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.77%. Comparing base (c422104) to head (45f4e22).
⚠️ Report is 9 commits behind head on master.

Files with missing lines	Patch %	Lines
src/wallet/mod.rs	78.57%	9 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #388      +/-   ##
==========================================
+ Coverage   79.17%   79.77%   +0.60%     
==========================================
  Files          24       24              
  Lines        5311     5266      -45     
  Branches      242      241       -1     
==========================================
- Hits         4205     4201       -4     
+ Misses       1029      988      -41     
  Partials       77       77              

Flag	Coverage Δ
rust	79.77% <78.57%> (+0.60%)	⬆️

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

☔ View full report in Codecov by Sentry.
📢 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.

[notmandatory]

Added a couple simple tests. Ready for review.

[notmandatory]

Updated with a couple changes suggested by @ValuedMammal (and also by Claude, will get it to review patches before pushing next time 🤖 ).

• moved new helper function to impl Wallet since it's only used there
• removed unneeded Result return from new mempool _events functions

[reez]

LGTM

From bdk-ffi perspective,apply_unconfirmed_txs_events & apply_evicted_txs_events would be nice additions, so i made a note on our 3.0 tracking issue about this PR. I also will keep tabs on wallet_events & CanonicalView::diff timeline to see how we should go about exposing wallet_events if it looks like it will be deprecated quickly if CanonicalView::diff becomes available soon after.

[ValuedMammal]

In c4084ab

Looks like you're missing a newline in the commit message

Edit: Fixed in ab82463

[oleonardolima]

utACK 12c453f

It looks way better with the events_helper fn 🚀. I left a single nit (non-blocker), and a fix (blocker) suggestion.

[notmandatory]

Thanks @ValuedMammal for the cool helper function and extra tests. I've fixed the doc issues @oleonardolima found.

[notmandatory]

ACK 45f4e22

[nymius]

ACK 45f4e22

I've executed tests successfully.
Coverage output is confusing, but I think it's pointing to pre-existent uncovered code.

I summarized the context of these changes here, mainly as a helper for me, but hope it can help others too. Let me know if you spot any errors:

bdk_wallet 3.0.0 (Depends on bdk_chain 0.23)
├───Issue #6: Missing user facing events from wallet updates
|	└──── PR #319
|			├─ PR #310
|			|   ├─ WalletEvents { ChainTipChanged, TxConfirmed, TxUnconfirmed, TxReplaced, TxDropped}
|			|   ├─ wallet_events ("wallet diff")
|			|   └─ Wallet::apply_update_events: get events after applying updates
|			|
|			├─ PR #336 (release 2.2.0): block event variants
|			|   ├─ Wallet::apply_block_events
|			|   └─ Wallet::apply_block_connected_to_events
|			|   
|			└─ ADR 3: Return user-facing events when applying updates after syncing
|			
└───Issue #374: Missing user facing events from mempool changes
	└─ PR #388
	  ├─ Wallet::apply_unconfirmed_txs_events
	  ├─ Wallet::apply_evicted_txs_events
	  └─ Wallet::events_helper

I agree with the conclusions derived from #319 (comment). I think it is a more elegant solution.
It's going to deprecate 0003_events.md and merit a new ADR amending it and referencing a canonical view ADR.

This is a high level summary of what I extracted from the ongoing discussions about next steps:

bdk_wallet x.x.x (Depends on bdk_chain 0.24)
├─── Remove WalletEvents { ... }
├─── Add TransactionEvents { ChainTipChanged, TxConfirmed, TxUnconfirmed, TxReplaced, TxDropped}
├─── Add fn diff(self: &CanonicalView, other: &CanonicalView) -> TransactionEvents
├─── Add fn canonical_view(self: &Wallet) -> CanonicalView to produce wallet snapshots and compute events from CanonicalView::diff
├─── Deprecate ADR 003?
├─── Add ADR 004? Referencing changes due to new CanonicalView. Maybe add a bdk_chain ADR too?
└─── Add notice for *_events method deprecation in bdk_wallet x+1.x.x?

[110CodingP]

ACK 45f4e22

[oleonardolima]

ACK 45f4e22

[ValuedMammal]

ACK 45f4e22; ran the tests locally