feat: watcher emits persistence-ready watch-only activities

[coreyphillips]

Summary

Subtask 2 of #107, reworked per @ovitrif's review. The onchain xpub watcher now emits persistence-ready Core activity data that Bitkit stores through the existing activity APIs — rather than the app hand-reconstructing activities per-platform (and drifting).

What it does

Watcher builds the payload (where the data still exists). WatcherEvent::TransactionsChanged now carries:

• activities: Vec<Activity>
• transaction_details: Vec<TransactionDetails>

…instead of Vec<HistoryTransaction>. They're built inside the watcher using the BDK Wallet, raw txs (list_transactions(true)), confirmation time, fee/vsize, and is_mine ownership — the decode path is shared with get_transaction_detail via the extracted map_bdk_tx_to_detail.

Wallet boundary = the watched address type. WatcherParams gains wallet_id. One activity per tx, scoped to that wallet; the same txid under two address types becomes two wallet-scoped activities (no cross-address-type merge).

Persistence-compatible semantics, from the watched wallet's perspective:

case	value	fee	address
Received	received	0 (sender paid it)	owned output
Sent	sent - received - fee	fee	destination (non-owned) output
SelfTransfer	0	fee	owned output

Self-transfer is value = 0, fee = fee so Bitkit's value + fee total isn't doubled. Unconfirmed txs get a positive (now) timestamp so rows are DB-valid and sort to the top while pending.

Upsert hardening so watcher refreshes don't clobber user/first-seen state: contact is preserved when the incoming value is None (COALESCE), and an unconfirmed tx keeps its existing timestamp until it confirms. (seen_at and tags were already preserved.)

Also: HistoryTransaction keeps the new fee_rate field for get_transaction_history consumers; both that path and the watcher now use list_transactions(true). The earlier standalone watch_only_activity_from_history mapper is removed.

Tests

cargo test --lib modules::onchain:: (55) and modules::activity:: (167) pass. New coverage:

• watch_only_activity_from_detail: received-drops-sender-fee, sent value/fee split, self-transfer zero-value, unconfirmed now timestamp, matching TransactionDetails.
• test_upsert_preserves_contact_and_unconfirmed_timestamp.

Swift + Python bindings regenerated (iOS xcframework / Android Kotlin / dylib rebuilt at release via build.sh, per repo convention).

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 55ee1fc3f6

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[coreyphillips]

Update: aligned with bitkit-ios / bitkit-android conventions

Checked how both apps key and build onchain activities to settle the open id question:

• id = tx_id — confirmed. iOS CoreService.createSentOnchainActivityFromSendResult uses id: txid, and Android HwWalletRepo.toOnchainActivity uses id = first.txid. The activity table's PK is (wallet_id, id), so keying on the bare txid is collision-safe across wallets. No change needed.
• address = "" — matches Android's watch-only mapping exactly.

While there I found the apps do one more thing the 1:1 mapper didn't: they merge HistoryTransaction rows by txid (Android toMergedActivities). A hardware device has multiple accounts/script-types watched separately, so the same txid can surface once per account (e.g. an internal send→receive). With id = tx_id, two un-merged rows would collapse under upsert to last-wins and lose the combined picture. The mapper now:

• groups rows by txid, sums received/sent, and classifies the whole tx via core's classify_tx (the canonical direction/amount logic);
• keeps the real fee/fee_rate from the account that paid (received-only rows carry none);
• preserves first-seen txid order; produces exactly one activity per tx.

So the mapper is now a faithful drop-in for the per-platform logic rather than just a field copy. Tests cover received / sent / self-transfer / same-txid merge / ordering / unconfirmed defaults / deterministic id.

[ovitrif]

Thanks, I hope the fact that we didn't share the full context why the 2 apps differ in implementation is not going to cause a lot of trouble to get this PR in its merge-able state.

The reason Android works more in-memory is mainly because it didn't have the later #103 PR at the time of the implementation.

The scope of that task actually surfaced as an idea during the Android implementation of Trezor subtask 1:

• Issue: Home Screen hardware-wallet updates bitkit-android#1024
• PR: feat: home screen hardware wallet ui bitkit-android#999

Since iOS had the primitives in place, Joao and myself synced to make sure iOS doesn't have to carry over this requirement to refactor later, which Android's first PR (ported by iOS' PR) embedded.

After #103 was merged, I updated the Android epic and its subtask (6) for optimisation with specs that came as a result of investigation how to levarage the walletId/wallet-scoped activities.

Links:

• Android Epic: epic: Trezor Hardware Wallet UI bitkit-android#998 (see info in issue description for subtask 6)
• Issue of Subtask 6: Bitkit Core support for hardware wallet activities bitkit-android#1029

[ovitrif]

The deterministic id = tx_id choice should be confirmed against how Bitkit already keys onchain activities; easy to switch to wallet_id:tx_id if cross-wallet collisions are a concern.

TxId might be problematic for cases where we send coins from Trezor to app's onchain wallet. My understanding is that activities for such actions will both have the same txId. This is one of the reasons we had to include more discriminators in the walletId PR #103

[ovitrif]

Leaving these together so the intended direction is clear. The watcher does not need to persist into the DB itself, but the watcher payload should be normal Core activity data that Bitkit can persist.

[coreyphillips]

@ovitrif thanks for the thorough review — this was exactly the right call. Pushed a redesign in 540f894 that moves activity-building into the watcher and emits persistence-ready activities + transaction_details, with per-address-type wallet_id scoping (no merge), correct value/fee semantics (self-transfer = value 0 + fee; receive-only drops the sender's fee), real decoded addresses, positive unconfirmed timestamps, and upsert hardening so refreshes preserve contact + first-seen timestamp. Replied inline on each point. Note this makes WatcherEvent / WatcherParams a breaking change vs the previous shape.

[ben-kaufman]

Review comments from local pass.

[coreyphillips]

@ovitrif on the tx_id point (a Trezor send to the app's own onchain wallet producing the same txid in both): the redesign keys activities on the composite primary key (wallet_id, id) with id = tx_id, and each watcher is scoped to a specific address-type wallet_id. So the Trezor-side activity (wallet_id = trezor:...) and the app-wallet-side activity (its own wallet_id) are distinct rows even with the same txid, no collision. That matches the wallet-scoping direction from #103. Thanks also for the context on why Android went in-memory (pre-#103) and the epic/subtask links, that lines up with this approach.

[ben-kaufman]

Full review looks good. I rechecked the watcher/activity flow, generated surfaces, and the resolved threads.

[ovitrif]

LGTM, reviewed after merge. Thanks everyone for the help 🙏🏻