Skip to content

docs: explain Bitcoin Connect payment flow lifecycle #24 #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
naveendhaterwal wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: explain Bitcoin Connect payment flow lifecycle #24 #26

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions references/bitcoin-connect/bitcoin-connect.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,41 @@ or
- Payment UI for accepting payments via QR code or connected wallet
- Supports multiple wallet connectors: Alby Hub, NWC, LNbits, Lightning Node Connect, and more

## Payment Flow Lifecycle

Understanding the transition between the button states and the payment modal is key to building a great user experience. The process follows a 4-stage flow:

```mermaid
graph TD
A[1. Start - Idle] -->|User Clicks Button| B[2. Requesting Invoice]
B -->|Invoice Set| C[3. Paying - Modal Opens]
C -->|WebLN Paid / External SetPaid| D[4. Success Screen]
D -->|Done| A
```

### 1. Start (Idle)
- The user sees a `<bc-pay-button>` or a custom button.
- The component is in an idle state, waiting for user interaction.

### 2. Requesting Invoice
- Triggered by the `click` event.
- The application fetches a BOLT-11 invoice (e.g., from your backend or using `@getalby/lightning-tools`).
- **Web Component**: Set the `invoice` attribute on `<bc-pay-button>`.
- **React**: Update the `invoice` prop on `PayButton`.

### 3. Paying
- The **Payment Modal** launches automatically (via `PayButton`) or programmatically (via `launchPaymentModal`).
- The user chooses a payment method:
- **Extension**: Uses an installed WebLN provider (like Alby).
- **NWC**: Uses Nostr Wallet Connect.
- **Scanner**: Shows a QR code for external wallets.
- If using WebLN, the payment is executed as `provider.sendPayment(invoice)`.

### 4. Showing Success Screen
- **Automatic**: For WebLN payments, the modal transitions to the success screen automatically.
- **Manual**: For QR code payments, the app must poll for payment status and then call `setPaid()` to show the success screen in the modal.
- **Completion**: The `onPaid` (React) or `bc:onpaid` (Web Components) event fires, providing the `preimage`.
Comment on lines +76 to +79
Copy link

@coderabbitai coderabbitai bot Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

# First, let's check if the file exists and read the relevant section
if [ -f "references/bitcoin-connect/bitcoin-connect.md" ]; then
  cat -n "references/bitcoin-connect/bitcoin-connect.md" | sed -n '70,85p'
else
  find . -name "*bitcoin-connect*" -type f | head -20
fi

Repository: getAlby/alby-agent-skill

Length of output: 941

🏁 Script executed:

# Search for all setPaid usage patterns in the repository
rg "setPaid" --context 3 -A 2 -B 2

Repository: getAlby/alby-agent-skill

Length of output: 2604

🏁 Script executed:

# Look for TypeScript definitions or type files that might define the API
fd -e "\.d\.ts" -e "\.ts" | xargs rg "setPaid" 2>/dev/null | head -20

Repository: getAlby/alby-agent-skill

Length of output: 686

🏁 Script executed:

# Search for SendPaymentResponse definition to understand the required payload
rg "SendPaymentResponse" --context 5

Repository: getAlby/alby-agent-skill

Length of output: 14945

🏁 Script executed:

# Check the full API documentation section in bitcoin-connect.md to see all examples
cat -n references/bitcoin-connect/bitcoin-connect.md | sed -n '40,120p'

Repository: getAlby/alby-agent-skill

Length of output: 3414

Clarify setPaid() requires a payload to match the API signature.

Line 78 says "call setPaid()," but the API requires passing a SendPaymentResponse object. The example at line 122 correctly shows setPaid({ preimage: "..." }). Update the text to match:

Suggested change 
-- **Manual**: For QR code payments, the app must poll for payment status and then call `setPaid()` to show the success screen in the modal.
+- **Manual**: For QR code payments, the app must poll for payment status and then call `setPaid({ preimage })` to show the success screen in the modal.
🤖 Prompt for AI Agents 
In `@references/bitcoin-connect/bitcoin-connect.md` around lines 76 - 79, Update
the documentation text to state that setPaid requires a SendPaymentResponse
object rather than being called without arguments; specifically, replace the
phrase "call setPaid()" with guidance to call setPaid(...) passing a
SendPaymentResponse (e.g., { preimage: "..." }) so it matches the API signature
and aligns with the example and the onPaid / bc:onpaid event behavior.


## Units

Unlike NWC, WebLN operates on sats, not millisats. (1000 millisats = 1 satoshi)
Expand Down