[piotr-iohk]

Closes #1812

Companion: synonymdev/bitkit-e2e-tests#298, synonymdev/bitkit-e2e-tests#300

This PR refreshes Lightning channel capacity before preparing a send, so a newly received payment immediately has the correct spending limit.

Description

• Refreshes channels before trusting a cached usable channel, preventing invoice preparation from replacing a fresh 9,000-sat limit with a stale zero limit after a 10,000-sat receipt.
• Preserves lifecycle checks, polling, unavailable-channel feedback and the existing last-known-snapshot fallback when a refresh fails, without an additional full balance read.
• Adds regression coverage for capacity growth/reduction, lost usability, removed channels, a node stopping during refresh and failed-refresh compatibility, plus a receipt-to-send journey and changelog entry.

Out of Scope

• E2E action/outcome migration and remaining RBF/Receive/staging-funding investigations are tracked in Migrate the 13-case iOS gate to selector action/outcome waits bitkit-e2e-tests#298. This PR preserves the existing E2E assertions and timeout configuration.
• Journey root parity/capability documentation: tracked in #1809, following the review thread.
• Stop-during-refresh test precision: tracked in #1810, following the review thread. The current test checks stopped-state behavior but does not independently detect the new post-refresh lifecycle guard.
• Duplicate initial channel read on the unusable-channel polling path: tracked in #1811, following the review summary. Existing polling order is preserved.

Design

N/A — no UI changes.

Preview

Existing Send amount UI; the over-limit digit now consistently triggers the existing warning and leaves the accepted prefix unchanged. Local Send2 observed 1000 retained when entering 10001 against a 10,000-sat Spending balance.

QA Notes

Setup

Use the local-regtest Send2 fixture from synonymdev/bitkit-e2e-tests at e560ece2b7cc1fb5bbc1b72e8205abea544e7ae3. It funds Savings, opens a private channel from local LND to Bitkit, then pays Bitkit 10,000 sats. This does not purchase a Blocktank connection.

Build this app with E2E=true E2E_BACKEND=local ./gradlew assembleDevDebug; place its universal debug APK at the E2E checkout's aut/bitkit_e2e.apk. With Node 22, dependencies installed, a Pixel 6/API33 emulator booted, the checkout's Docker stack running and LND credentials ready, run BACKEND=local ./ci_run_android.sh --mochaOpts.grep '@send_2 '. The checked-in fixture pins Bitcoin26.0, electrs0.10.2 and LND0.18.0-beta. UI waits remain 30s. The targeted CI run builds app b5ff8114b and checks out that exact E2E commit.

For J1, retain the running app and channel after receipt: do not restart or manually refresh before opening the amountless invoice.

Journeys

• J1: new send-spending-after-receive.xml — a fresh Lightning receipt keeps its correct Send cap; the first over-limit key is rejected with a warning and normal amount entry/reentry still works.

Manual Tests

N/A

Automated Checks

• updated LightningRepoTest.kt — six regression cases cover fresh capacity, usability, removal, lifecycle changes and failed-refresh fallback; all 11 focused wait-path cases pass.
• ran send.e2e.ts — unchanged rewritten Send2 passes against the fixed app with every financial, fee, invoice, history and negative-validation assertion retained.

Evidence

• Original APK at app ebe9bc09850704d1e96a2bb1697fd5d5a664fd1a: old Send2 (849806e) accepted 10,001 with 9,000 available, then passed after its internal extra-digit fallback. Rewritten Send2 (e560ece) exposed the same failure. Both used the identical APK/device/runtime/backend configuration.

• A logging-only local diagnostic build confirmed fresh cap 9,000 → cached usable-channel cap 0 → unrestricted amount input until periodic correction. Receive and Send used different amount-input VMs. Diagnostic logging is absent from this PR.

• At app 8d0fcabfe8bcc5c1b7e3ddbe39506f11b8940401 and E2E e560ece, full local Send2 passed on its first case attempt: 90/90 recorded outcomes, retained 1,000 and observed the warning in 820ms, no case retry. Pixel 6/API33 ARM64, Node 22.23.4,30s UI waits, fresh isolated backend. The local build additionally enabled TREZOR_BRIDGE=true; Send2 uses no hardware-wallet flow. The only later source delta is the changelog fragment.

• just compile, just test (4,944 tests; zero failures/errors/skips) and just lint (detekt + Android lint) passed at 8d0fcab. Independent implementation review is complete with no remaining findings; signed commits verified locally. The changelog-only publication delta is checked separately.

• Android CI Send2 passed on its first attempt: 1/1 cases and 90/90 recorded outcomes, with attempts 2/3 skipped. App b5ff8114be9a1392adc2caef371d5b367868c7dd, E2E e560ece2b7cc1fb5bbc1b72e8205abea544e7ae3, workflow dbd0ae8be421b7be3f68451c77af1b83a7eb5632; Node 22.23.4, Pixel 6/API33 x86_64, 30s UI waits, standard local E2E build flags. The single over-limit digit retained 1 000 and observed SendAmountExceededToast in 717ms. Reported suite time 8m 25.6s; worker 8m 44s. All three PR commits are GitHub Verified. The temporary workflow only pins both sources and selects Send2; it is not part of this PR.

• Ready-for-review CI run 42580213587 passes build, unit and Compose UI tests at the same b5ff8114b head. Default full local E2E run 42580213958, attempt 1, using E2E main at 849806e70784da0960f44da6206e2346b1e0ba3e, failed: 27/39 first-attempt and 35/39 eventual passes. All 22 failure screenshots and sampled frames from all 22 recordings show an undismissed USDT introduction covering Home; device logs and missing balance/menu/backup selectors agree. See the artifact-backed diagnosis. Default Send2 uses its historical extra-key fallback, so its pass does not replace the separate clean pinned Send2 evidence.

• Full local Android workflow 42580213958, attempt 2 passed with E2E 407d4a05fdcf6796960df0afbda552f575c93e97: 39/39 first-attempt cases, all seven shards, no case retries and no legacy toast fallback invocation. App merge checkout 2353ee4c30a71c7c09c709cc3403f3231080f94b and app head b5ff8114b share tree 813c7ff6e9aac702bd0be30422812c0dfb528936. The shared fixture was independently reviewed and passes 70 repository tests plus 4 boundary probes on Node22.23.4, TypeScript and scoped lint. See the validated correction.

• Independent device review at b5ff8114b: J1 amount-limits/send-spending-after-receive.xml passed 11/11 actions on Gate_Throwaway with local Docker regtest and a private LND channel. After the 10,000-sat receipt without a restart, Spending showed 8,998; the single over-limit digit after 1,000 raised the warning, and 2,000 reached review. The reviewer reports an empty crash buffer and send-preparation medians of 0.70s for this PR versus 0.60s on master 74c8b2cdf, five runs each with overlapping 0.58–0.95s ranges. These are reviewer-published results, separate from this chat's pinned Send2 execution.

• Historical fba9a6e paired Android CI pass: workflow 42580213958, attempt 5 completed 39/39 cases on their first attempt at exact E2E fba9a6efde8fdd9066a0408e3f5f1fe1b5ec23ac; every shard checkout is confirmed, all 14 retry steps skipped, and no legacy toast fallback ran. It reused the successful app build of merge 2353ee4c30a71c7c09c709cc3403f3231080f94b (same source tree as app head b5ff8114b).

• Current paired Android CI passes: workflow 42580213958, attempt 6, exact E2E 7f61681bb8d4b0d31dc836a1c03a8488170baf66 paired with unchanged app b5ff8114be9a1392adc2caef371d5b367868c7dd. All seven checkouts are verified: 38/39 first-attempt cases, 39/39 eventual passes, one built-in retry and 13 retry steps skipped; no legacy toast fallback ran. The fresh app build checked out merge 2353ee4c30a71c7c09c709cc3403f3231080f94b, whose tree matches b5ff8114b.

  The retried multi_address_3 case timed out waiting for ReceivedTransaction. Its failure screenshot and sampled recording show uncovered Home, and the device log records an incremental Electrum on-chain sync timeout during that wait. The same case passed on its built-in retry with unchanged sources. The artifact-backed disposition is flake, with the underlying sync-timeout cause unisolated; this is not proof of staging VSS causality. The exported app log starts after the next reinstall. Three recording samples and the failure screenshot were inspected; a fourth requested frame did not decode.

Gaps

• Android master has additionally advanced to 36a2c4d, adding USDT first-sync receipt celebration/restore-window handling and loaded-account on-chain address search. These do not alter this PR's Lightning capacity refresh or Progress cards #300's Home-introduction controls. Existing CI remains pinned to the actual app merge 2353ee4c / head b5ff8114b; the combination with the newer master changes has not been rerun.

• Companion fix: handle late usdt introductions during home checks bitkit-e2e-tests#300 is conflict-free at signed/Verified 7f61681bb8d4b0d31dc836a1c03a8488170baf66, with current main 0e83ea6 integrated. Its 82 local checks, static validation, four independent implementation reviews, current-head Talos review and full paired Android attempt 6 pass. Fresh current-head approvals on Progress cards #300 are now present from ben-kaufman and pwltr; GitHub reports APPROVED/CLEAN. Android fix: refresh lightning capacity before send #1808 already has current-head approvals. The historical attempt-5 result remains pinned to fba9a6e.

• Companion fix: handle late usdt introductions during home checks bitkit-e2e-tests#300 now incorporates main's Move-to-Spark recovery in signed conflict-resolution head fba9a6efde8fdd9066a0408e3f5f1fe1b5ec23ac. Independent full reassessment and 78 repository tests plus 4 boundary probes pass. Full workflow attempt 3 previously finished failure in all seven shards against the combined helper; it remains historical alongside the later 39/39 attempt-5 pass at the same E2E head. All seven shard logs confirm E2E fba9a6e. Eleven Settings cases passed; setup-hook failures prevented a complete 39-case execution. All seven failed-shard artifacts, 13 screenshots and sampled frames from all 13 recordings were inspected. Later reinstalled app processes stall in VSS-backed node construction; saved read-only staging VSS GET probes also time out. External dependency trouble is likely, but the first receipt failures are not fully isolated. The older 407d4a0 runtime result below remains historical. Previously assessed Android master 3f2009e: its delta from the originally tested base consists of release 3.1.0 version/changelog bookkeeping and test: drop blocktank-dependent tests #1817 instrumentation-test/local-regtest workflow changes. No production app source, dependencies or standard local E2E workflow changed. Those new instrumentation fixtures are outside this Appium cohort. The rerun does not execute current-master version metadata, migration behavior or those new instrumentation fixtures.

• Historical shared-fixture correction fix: handle late usdt introductions during home checks bitkit-e2e-tests#300 was validated at 407d4a05fdcf6796960df0afbda552f575c93e97. Workflow 42580213958 attempt 2 passes 39/39 cases on their first case attempt, all seven shards, with all 14 retry steps skipped. No legacy toast fallback message occurred. Every shard's checkout SHA is confirmed. The normal PR merge checkout 2353ee4c has the exact same source tree as app head b5ff8114b.

• Historical workflow attempt 1 remains a failed result at E2E main/849806e: lnurl_1, security_1, send_3 and onchain_2 were still failed with the USDT intro covering Home. Its 27/39 first-attempt and 35/39 eventual outcomes and all inspected failure evidence remain attributed to that test revision; the corrected attempt 2 is recorded separately.

• The separate successful pinned Send2 run covers only that case at app b5ff8114b / E2E e560ece. The later full-suite success uses E2E 407d4a0; neither one first-attempt pass nor one full cohort establishes a durable reliability rate. Experimental E2E adoption gaps remain separate.

• This chat's earlier J1 coverage came through Send2 and XML parsing; the later independent device review above closes the separate manual J1 execution gap at b5ff8114b. No new iOS run is claimed.

Models used

• Planning/scoping: gpt-6.1-sol (reasoning: high)
• Implementation: gpt-6.1-sol (reasoning: high)
• Review: gpt-6.1-sol (reasoning: high)
• Review rounds: 3

[github-actions]

Regtest APK

Built from b5ff811 (run).

Download bitkit-dev-debug universal APK (expires in 30 days).

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge; no actionable issues were found.

Summary

Refreshes Lightning channels before Send trusts a cached usable channel, so a recent receipt updates the spending limit.

• Send checks current Lightning capacity before applying the spending limit.

No actionable issues found. Checks in this review were source-based; no tests were run.

_{Reviews (1) · Last reviewed commit: "docs: add lightning spending limit chang..." · Reviewed by Greptile}

[talosmachina]

No findings. waitForUsableChannels now re-reads channels and peers on every call instead of returning early on a cached usable channel, so a send prepared right after a receipt derives its Spending cap from the current nextOutboundHtlcLimitMsat. Reviewed b5ff8114be9a1392adc2caef371d5b367868c7dd, full tier, statically.

What I checked, and 4 candidates I ruled out

Read in full: waitForUsableChannels, awaitUsableChannels, waitForChannelsToLoadIfNeeded, refreshChannelsAndPeers, syncState, canSend in LightningRepo.kt; WalletRepo.refreshMaxSendLightning; the six new cases in LightningRepoTest.kt.
Call sites traced: AppViewModel.waitForUsableChannels (unified invoice, Paykit request, bolt11, LNURL pay) all call walletRepo.refreshMaxSendLightning() right after, which reads the channels this refresh publishes, so the cap and canSend see the same snapshot; payInvoice calls it before onBeforeSend.
Build: not built here. Bitkit Android reviews are static on this side: Gradle would run the branch's own build scripts. lint, detekt and build are green; build-and-test and compose-ui were still pending at review time.

Ruled out

• Empty-channel path lost syncState(): the old branch also refreshed balances, nodeStatus and scheduled the ordinary follow-up retry. The callers only need channels (refreshMaxSendLightning, canSend read channels), syncState() still runs after every send, and avoiding the balance read is the stated intent of 8d0fcabfe.
• Refresh while the node is starting: refreshChannelsAndPeers returns success without reading when the lifecycle is not running, so a cached-channel state behaves as before.
• Refresh failure: the exception is caught inside refreshChannelsAndPeers and the last snapshot stays published, covered by keeps the last usable snapshot when refreshing fails.
• Node stopping mid-refresh: the lifecycle is rechecked after the refresh and takes the feedback-delay path, covered by rechecks lifecycle when the node stops during refresh.

Merge confidence: 4/5, no findings and the change is covered by the new LightningRepoTest.kt cases, but build-and-test had not finished and the branch was not built here.

Reviewer model: claude-opus-5-5
Reasoning effort: Not exposed (the runtime does not report it to the reviewer)

[coreyphillips]

Two independent reviews, nothing blocking a merge.

worth doing, does not block

• Android-only journey not in cross-platform table and needs unlisted capability (journeys/amount-limits/send-spending-after-receive.xml:1)

nits

• Node-stop test passes without the new post-refresh lifecycle check (app/src/test/java/to/bitkit/repositories/LightningRepoTest.kt:1664)
• Unusable-channel path reads channels twice back to back (app/src/main/java/to/bitkit/repositories/LightningRepo.kt:1467). When the new refresh returns non-empty channels with none usable, awaitUsableChannels() calls refreshChannelsAndPeers() again before its first delay. Every wait now starts with two consecutive node reads of the same data. Harmless; the loop could start with the delay since the caller has just refreshed.

[piotr-iohk]

For the duplicate-read nit in the review summary: out of scope: tracked in #1811 for 3.2.0, because this is a LOW redundant-read optimization. Source inspection confirms that a refreshed nonempty/unusable snapshot enters awaitUsableChannels(), which refreshes once more before the first delay. It does not establish an incorrect spending cap; changing polling order deserves its own focused call-count, recovery and lifecycle checks. Deferred under AGENTS.md Review Findings, with current polling/error behavior and every existing assertion preserved.

The journey-documentation and stop-test findings are answered in their original inline threads and tracked in #1809 and #1810.

[piotr-iohk]

Ready-for-review CI follow-up

Full local E2E run 42580213958, workflow attempt 1, finished failed at app b5ff8114be9a1392adc2caef371d5b367868c7dd. It used the normal E2E main revision 849806e70784da0960f44da6206e2346b1e0ba3e, independently of the pinned e560ece Send2 run already documented above.

• 27/39 first-attempt passes; 35/39 eventual passes. lnurl_1, security_1, send_3 and onchain_2 remain failed. Four shards fail; three recover on the workflow's built-in retries.
• All seven shard artifacts were downloaded. I inspected all 22 failure screenshots, sampled frames from all 22 failure recordings, and the corresponding job/device/available app logs. Every failure screenshot shows the New: USDT introduction covering Home. Transcripts wait for TotalBalance-primary/MoneyText, HeaderMenu or BackupIntroViewDescription; logcats record the timed USDT sheet opening during those flows.
• This is an E2E setup mismatch with expected optional-intro behavior. The root journey setup documentation requires resolving the intro before unrelated checks. E2E main observes it once during onboarding, then later balance/navigation operations can encounter the intro later. The UI/timed-sheet implementation is unchanged by this PR. The observation does not establish a new channel-capacity defect or a general full-suite flake classification.
• Default-suite Send2 passed after its old helper logged SendAmountExceededToast not triggered, trying again... and issued an extra keypress. That result is not another clean rejection check. The separate pinned Send2 run remains the one-key, retained-field, 90/90 first-attempt evidence at app b5ff8114b / E2E e560ece.

Fresh build/unit/Compose UI CI passes, and lint remains green at this head. Human approval is present, but required e2e-status is red, so the babysitting completion gate is not satisfied. No manual rerun was requested, no assertion was weakened, and no app code changed. The default E2E intro handling needs correction before an evidence-based rerun; the separate RBF/Receive/staging-funding investigations and companion synonymdev/bitkit-e2e-tests#298 adoption gaps remain outside this app fix.

[ovitrif]

Triage: in 3.2.0, a non-blocking bug found after the 3.1 cut. This PR closed no issue, so I filed #1812 to carry the milestone and added Closes at the top of the body. The issue is on the project at 👀 Review. No iOS twin.

[piotr-iohk]

The shared Home/USDT-intro fixture correction is now in standalone synonymdev/bitkit-e2e-tests#300, based on E2E main; #298 is unchanged. E2E head 407d4a05fdcf6796960df0afbda552f575c93e97 passed 70 repository unit tests, four independent boundary probes, TypeScript, scoped lint and two independent review rounds. Both commits are signed and GitHub Verified.

Workflow 42580213958 is running as attempt 2, with app head still b5ff8114be9a1392adc2caef371d5b367868c7dd. The branch-resolution job confirms the new matching E2E branch. All jobs were restarted so branch resolution can select the correction; the same seven-shard suite and 30s UI waits are retained. Exact test checkout SHA and final results are pending. The failed attempt 1 and its artifact-backed diagnosis remain preserved above.

[jvsena42]

Code scan at b5ff8114b: no findings.

Checked and clean:

• Root cause matches: DeriveBalanceStateUseCase sets the cap from live channels, then waitForUsableChannels → refreshMaxSendLightning re-derived it from the cached _lightningState.channels, so a stale nextOutboundHtlcLimitMsat = 0 snapshot zeroed it and setMaxAmount(0) fell back to MAX_AMOUNT. The refreshChannelsAndPeers() call at LightningRepo.kt:1441, before the usable check, closes that window. v3.1.0 still has the early return, so the fix is user-facing from 3.2.0.
• Overspend: canSend and refreshMaxSendLightning both sum totalNextOutboundHtlcLimitSats() over usable channels read live from the node, so the cap can only get closer to LDK's limit.
• Valid sends: cached-usable → live-usable returns immediately; cached-usable → live-unusable now waits up to 15 s behind the sync overlay instead of failing at send; a removed channel drops to the insufficient-balance path. Back during the wait still aborts through requireCurrentPaymentPreparation.
• Concurrency: refreshChannelsAndPeers and syncState both publish with updateAndGet from live reads; a concurrent stop() resolves to empty channels. No persisted state is touched.
• Dropping syncState() on the empty-channel branch: callers only read channels, and payInvoice still syncs after send.
• Journey send-spending-after-receive.xml: every tag it names exists at head, and the 10 001 sats keypress exceeds the cap only when the fix is present.
• iOS: no twin needed. BalanceManager derives max send straight from node channels, with no cached snapshot to overwrite it.

perf: relevant (adds list_peers + list_channels before every prepared Lightning send). To measure on device: AddressContinue tap → SendNumberField visible, PR vs master.

Device gate (partial): b5ff8114b — not run yet; amount-limits/send-spending-after-receive.xml and the send-prep timing are pending. Device result follows in a second review.

[piotr-iohk]

Shared fixture correction validated

Standalone synonymdev/bitkit-e2e-tests#300 is ready for review. Workflow 42580213958, workflow attempt 2, passed 39/39 cases on their first case attempt across all seven shards; all 14 retry steps were skipped. Every shard checked out E2E 407d4a05fdcf6796960df0afbda552f575c93e97. The legacy Send toast fallback logged zero invocations.

App PR head remains b5ff8114be9a1392adc2caef371d5b367868c7dd. Standard CI built PR merge ref 2353ee4c30a71c7c09c709cc3403f3231080f94b; its tree 813c7ff6e9aac702bd0be30422812c0dfb528936 is identical to the app head's tree. The passing LNURL/Transfer log shows two real USDT-intro presentations, each followed by one decline click for its new wallet, then both cases completing.

The failed attempt 1 (E2E main/849806e, 27/39 first and 35/39 eventual) remains historical evidence. The separate stricter Send2 result at app b5ff8114b / E2E e560ece remains 90/90 on one case attempt; this new full-suite result does not relabel that earlier execution. The Android source and its approval are unchanged. Experimental synonymdev/bitkit-e2e-tests#298 remains unchanged and stacked on synonymdev/bitkit-e2e-tests#296; no new iOS runtime result or broader reliability claim is made.

[pwltr]

Reviewed commit b5ff811. No findings.

Before a send, the usable-channel wait now re-reads channels and peers even when the cached channels are already usable, so the Lightning spending limit comes from the current outbound limits rather than a snapshot from before a receive. The re-read is a no-op while the node is not running and reads no balances.

Review details

General review
Model: Claude Opus 5.5
Reasoning effort: high

[jvsena42]

Device gate passed and the code scan was clean (see my earlier review). Approving.

Device gate: b5ff8114b — journeys: 1 passed (amount-limits/send-spending-after-receive.xml, 11/11 actions); perf: AddressContinue → SendNumberField median 0.70 s (master 74c8b2cdf 0.60 s, 5 runs each; the ranges overlap, 0.58–0.95 s); Figma: n/a; l10n: no UI text changed; iOS: no twin needed.

Setup: Gate_Throwaway emulator on local docker regtest (Electrum 10.0.2.2:60001). Fresh wallet with Savings 100 000, a private 100k channel from LND, and 10 000 received over it with no restart. On the amount screen Spending showed 8 998 available. The single N1 after 1 000 raised the exceeded toast, and 2 000 reached review. The crash buffer stayed empty.

The extra ~0.1 s is the list_peers + list_channels re-read before the amount screen, and it sits within run-to-run spread.

CI: build-local is still pending at b5ff8114b; everything else is green.

[piotr-iohk]

The companion fixture conflict is resolved in synonymdev/bitkit-e2e-tests#300 at signed/Verified fba9a6e, with both introduction recovery paths retained and 82 local tests plus static checks passing. Current-source independent and Talos reviews have no findings.

Full workflow attempt 3 finished red in all seven shards. All checkout SHAs are confirmed. Eleven Settings cases passed; setup-hook failures prevented a complete cohort execution. The artifact-backed investigation records probable external VSS dependency trouble with explicit limits on the initial receipt/Boost failures and an isolated onboarding-slide timeout. Merging remains blocked; the old 407d4a0 39/39 result is preserved at its actual source, not relabeled as validation of fba9a6e.