bitcoindevkit / bitcoindevkit/bdk-dart

bdk_demo: Home shows pending funds as balance; add pending tx summary under Send/Receive

Open
#119 3 comments 0 reactions 1 assignee Claimed by @Shamsudeen12 View on GitHub
enhancement
Dominant language
Dart
Stars
13
Forks
20
Avg merge
24m
Merged PRs (30d)
3

Description

## Summary

On `bdk_demo` Home, an incoming **unconfirmed** transaction bumps the main **Balance** figure (BDK `total`) even though **Trusted spendable** stays at `0`. Transaction History already labels the row as `pending` / "Awaiting confirmation", but Home has no pending-transaction affordance under Send/Receive.

Expected UX: keep the primary balance at confirmed/spendable `0` (or explicitly confirmed), and surface pending activity below Send/Receive until confirmation.

## Current behavior

Reproduced on Testnet 3 with a fresh wallet that just received `2000` sats (unconfirmed):

| Surface | Observed |
|---------|----------|
| Home Balance | `2000 sat` |
| Home Trusted spendable | `0 sat` |
| Sync | green / up to date |
| Transaction History | `+2000 sat` with **pending** / "Awaiting confirmation" |
| Transaction Detail | status **pending** |

Home balance is wired to `WalletBalanceSnapshot.totalSat` (`wallet.balance().total`), which includes untrusted pending. Pending breakdown fields (`trustedPendingSat` / `untrustedPendingSat`) are already captured in the snapshot but not shown as a Home pending section.

Relevant code today:

- `bdk_demo/lib/features/home/home_page.dart` — `_BalanceCard` displays `totalSat`
- `bdk_demo/lib/providers/blockchain_providers.dart` — `applyFromWallet` stores total + pending buckets
- `bdk_demo/lib/features/transactions/*` — pending mapping/UI already exists for history/detail

## Expected behavior

1. **Primary Home balance** reflects confirmed / trusted-spendable funds (so it stays `0` while the only UTXO is untrusted pending).
2. **Pending transaction display** below the Send/Receive row when `trustedPending` / `untrustedPending` (or pending txs) are non-zero — e.g. "+2000 sat pending" with link into Transaction History/detail.
3. After confirmation + sync, pending section clears and primary balance updates.

## Why this matters

Users read the large Balance number as spendable. Showing pending as the hero balance contradicts Trusted spendable `0` and the pending labels already used in history/detail.

## Suggested approach (non-binding)

- Drive the hero figure from `confirmedSat` and/or `trustedSpendableSat` (product choice; document which).
- Optionally show a secondary line for total including pending.
- Add a compact pending summary under Send/Receive fed by balance pending buckets and/or a short list from `transactionsRepository` filtered to `pending == true`.
- Invalidate/refresh that Home section after sync (same gap as history not auto-reloading after sync).

## Related

- Continues the real wallet history work in https://github.com/bitcoindevkit/bdk-dart/pull/102 (pending rows already work in history; Home UX does not).
- Note: `tb1…` is shared by Signet and Testnet 3 — cross-network sends look valid but will not appear on the other chain; unrelated to this UX issue but easy to confuse while testing.

## Acceptance criteria

- [ ] With only an unconfirmed receive, Home hero balance stays `0` (confirmed/spendable semantics).
- [ ] Home shows a pending indicator/summary below Send/Receive for that receive.
- [ ] After the tx confirms and the wallet syncs, pending UI clears and hero balance includes the funds.
- [ ] Widget coverage for Home with untrusted-pending-only snapshot.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.