fix: refresh receive after payment

[ben-kaufman]

Description

• Invalidate a settled wallet Lightning invoice before publishing its payment event so stale invoices are not restored.
• Carry settlement metadata with the exact node event instead of shared mutable state, preventing adjacent events from taking another receive request context.
• Persist the cached BOLT11 payment hash with the invoice so settlement correlation does not depend on decoding during event handling; migrated cache entries fall back to direct BOLT11 parsing.
• Correlate on-chain transaction outputs with the exact cached receive address, then invalidate and rotate only that address and its BIP21 request.
• Track the exact invoice and on-chain address shown by each receive sheet so a paid sheet closes before received-payment presentation without dismissing a replacement sheet.
• Process a received Lightning payment once using its payment ID, while still notifying activity observers after the core update.
• Coordinate notification and in-app presentation through one synchronous in-process claim and a shared presentation helper, then mark the activity seen only after presentation is handed off.

Preview

Not applicable; this fixes receive-state lifecycle behavior without changing the UI layout. The existing Android sheet animation remains unchanged, as discussed in review.

QA Notes

• ./gradlew compileDevDebugKotlin
• ./gradlew testDevDebugUnitTest
• ./gradlew detekt --rerun-tasks (passes with the repository baseline findings)
• git diff --check
• Regression coverage in AppCacheDataTest.kt, CacheStoreTest.kt, LightningRepoTest.kt, WalletRepoTest.kt, AppViewModelSendFlowTest.kt, LightningNodeServiceTest.kt, and NotifyPaymentReceivedHandlerTest.kt

[greptile-apps]

Greptile Summary

This PR updates receive state after Lightning and on-chain payments. The main changes are:

• Invalidates a settled Lightning invoice before publishing its event.
• Carries settlement metadata on each node event.
• Preserves replacement invoices during cache and memory updates.
• Tracks the invoice associated with each receive sheet.
• Defers payment marking until notification or sheet presentation.
• Refreshes reusable receive requests after payment.

Confidence Score: 4/5

The foreground/background payment handoff can omit both notification and in-app presentation.

• Activity transitions can make the service and UI both decline the same payment.
• Activity-store failures suppress the sheet without retrying.
• Decode failures leave a settled receive request active.

LightningNodeService.kt, AppViewModel.kt, and LightningRepo.kt

Important Files Changed

Filename	Overview
app/src/main/java/to/bitkit/androidServices/LightningNodeService.kt	Rechecks foreground state before marking and posting a payment notification, leaving a handoff race with the UI.
app/src/main/java/to/bitkit/domain/commands/NotifyPaymentReceivedHandler.kt	Separates presentation eligibility from marking the payment as seen.
app/src/main/java/to/bitkit/repositories/LightningRepo.kt	Invalidates matching cached invoices and publishes settlement metadata with each event.
app/src/main/java/to/bitkit/repositories/WalletRepo.kt	Conditionally clears only the matching in-memory invoice and preserves replacements.
app/src/main/java/to/bitkit/viewmodels/AppViewModel.kt	Tracks receive-sheet invoice identity and defers sheet display until the payment is marked.
app/src/main/java/to/bitkit/data/CacheStore.kt	Adds atomic expected-invoice invalidation while preserving unrelated receive data.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Node as LightningRepo
    participant Service as LightningNodeService
    participant Activity as CurrentActivity
    participant UI as AppViewModel
    Node->>Service: PaymentReceived
    Service->>Activity: Check foreground state
    Activity-->>Service: Foreground
    Service-->>Node: Skip notification
    Activity-->>Activity: Pause and clear current activity
    Node->>UI: NodeEventUpdate
    UI->>Activity: Check foreground state
    Activity-->>UI: Background
    UI-->>UI: Skip sheet
    Note over Service,UI: Neither path presents the payment

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Node as LightningRepo
    participant Service as LightningNodeService
    participant Activity as CurrentActivity
    participant UI as AppViewModel
    Node->>Service: PaymentReceived
    Service->>Activity: Check foreground state
    Activity-->>Service: Foreground
    Service-->>Node: Skip notification
    Activity-->>Activity: Pause and clear current activity
    Node->>UI: NodeEventUpdate
    UI->>Activity: Check foreground state
    Activity-->>UI: Background
    UI-->>UI: Skip sheet
    Note over Service,UI: Neither path presents the payment

Loading

_{Reviews (1): Last reviewed commit: "fix: correlate receive settlement events" | Re-trigger Greptile}

[jvsena42]

Nothing blocking so far, still haven't tested

[piotr-iohk]

Nice fix overall — the LN receive settlement / refresh path brings Android closer to iOS and feels much more consistent.

Tested LN + on-chain receive on this branch (foreground, receive sheet open). Compared behavior with iOS.

LN receive (foreground)

Works as expected: paid receive sheet closes and the received-payment UI shows. Replacement / refresh path looks good for Lightning.

On-chain receive (foreground) — gap vs LN / iOS

With the receive sheet open, after an on-chain payment:

1. The receive sheet does not dismiss (LN does; iOS dismisses/replaces for both).
2. The on-chain address / BIP21 request stays the same on the still-open receive sheet.

On iOS, showing receivedTx replaces the single sheet stack, so receive goes away for both LN and on-chain. On Android, hideSheet() is only wired for PaymentReceived + matching settled invoice — OnchainTransactionReceived never clears Sheet.Receive.

Would be good also to close/refresh the receive sheet for on-chain the same way as LN (or otherwise match iOS), and confirm the reusable address rotates after the current one is used.

Screen.Recording.2026-07-22.at.13.13.39.mov

UX nit (non-blocking)

iOS slides receive away before showing received; Android drops the receive sheet abruptly. Nice-to-have parity, not blocking if the on-chain dismiss/refresh above is fixed.

Screen.Recording.2026-07-22.at.13.15.24.mov

[jvsena42]

iOS slides receive away before showing received; Android drops the receive sheet abruptly. Nice-to-have parity, not blocking if the on-chain dismiss/refresh above is fixed.

This is Android native behavior. Better wait for a improvement on sheet library

[ben-kaufman]

@piotr-iohk Fixed in ff8ac68. On-chain receive events now match the exact cached receive address against transaction outputs, invalidate and rotate only that address/BIP21 request, and dismiss the matching receive sheet before the received-payment handoff. Unrelated or newly opened replacement sheets are preserved. Regression coverage was added across CacheStoreTest, LightningRepoTest, WalletRepoTest, and AppViewModelSendFlowTest.

The optional animation change is intentionally not included, following the note that the current transition is native behavior of the Android sheet library.