[Bug]: Receive liquidity flow edge cases

[pwltr]

Receive Liquidity Behavior

This document describes how the receive flow decides whether to show a normal Lightning invoice or route the user into CJIT liquidity setup.

Cases

• Lightning receive unavailable because there is no ready channel or inbound liquidity is 0:

  • No Lightning invoice is created.
  • The normal QR remains Savings/onchain only.
  • The Spending tab shows CJIT onboarding.
  • Tapping receive spending routes to CJIT amount entry, or the CJIT geo-block screen when geo-blocked.
  • Editing the normal invoice amount only affects the Savings/onchain invoice; it does not create or route to CJIT.
  • When a channel already exists, later CJIT confirmation and learn-more screens use additional-liquidity copy.

• Ready channel, inbound liquidity greater than 0, zero/variable amount:

  • A Lightning invoice is allowed.
  • A zero/variable Lightning invoice is allowed when inbound liquidity is greater than 0, even though the sender could later choose an amount above the available inbound capacity.

• Ready channel, fixed amount less than or equal to inbound liquidity:

  • A normal BOLT11 invoice is created.
  • The unified QR includes Lightning.
  • The Spending tab shows the normal Lightning invoice.

• Ready channel, fixed amount greater than inbound liquidity but below CJIT minimum:

  • A normal Lightning invoice is not shown.
  • The edit flow routes to CJIT amount entry.
  • The user must choose at least the minimum CJIT amount.

• Ready channel, fixed amount greater than inbound liquidity and at or above CJIT minimum:

  • If the amount can be backed by a CJIT channel without exceeding Blocktank's maximum channel size, the edit flow creates additional CJIT.
  • The user gets CJIT confirmation and then a CJIT Lightning invoice QR.
  • If the amount is too large for CJIT, or the maximum cannot be calculated, the edit flow routes to CJIT amount entry.
  • The CJIT amount screen enforces the real maximum receivable amount, calculated from invoiceSat + defaultLspBalance(invoiceSat) <= maxChannelSizeSat.

• Geo-blocked and liquidity is needed:

  • The flow routes to the CJIT geo-block screen.
  • No CJIT invoice is created.