Skip to content

Update ldk-node dependency & expose bolt12 proofs #258

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
benthecarman wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Update ldk-node dependency & expose bolt12 proofs #258

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c086dbb
Update ldk-node dependency
benthecarman Aug 13, 2026
3340900
Expose BOLT 12 payer proofs
benthecarman Aug 13, 2026
fba0e98
Use ldk-node payment pagination
benthecarman Aug 19, 2026
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
84 changes: 51 additions & 33 deletions Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

55 changes: 37 additions & 18 deletions docs/api-guide.md
View file
Open in desktop
Comment thread
benthecarman marked this conversation as resolved.
Original file line number Diff line number Diff line change
Expand Up @@ -113,8 +113,8 @@ These RPCs support a manual claim/fail workflow for held payments. See
| RPC | Description |
|------------------------|--------------------------------------------------------------------|
| `Bolt11ReceiveForHash` | Create an invoice for a given payment hash (manual claim required) |
| `Bolt11ClaimForHash` | Claim a held payment by providing the preimage |
| `Bolt11FailForHash` | Reject a held payment |
| `Bolt11ClaimForId` | Claim a held payment by its payment ID and preimage |
| `Bolt11FailForId` | Reject a held payment by its payment ID |

### BOLT11 JIT Channels (LSPS2)

Expand All @@ -128,12 +128,13 @@ when the invoice is paid.

### BOLT12 Offers and Refunds

| RPC | Description |
|-----------------------|-------------------------------------------------------------------------|
| `Bolt12Receive` | Create a BOLT12 offer (fixed or variable amount) |
| `Bolt12Send` | Pay a BOLT12 offer (with optional quantity, payer note, routing config) |
| `Bolt12SendRefund` | Create a BOLT12 refund that this node will pay |
| `Bolt12ReceiveRefund` | Request an incoming payment for a BOLT12 refund |
| RPC | Description |
|--------------------------|-------------------------------------------------------------------------|
| `Bolt12Receive` | Create a BOLT12 offer (fixed or variable amount) |
| `Bolt12Send` | Pay a BOLT12 offer (with optional quantity, payer note, routing config) |
| `Bolt12SendRefund` | Create a BOLT12 refund that this node will pay |
| `Bolt12ReceiveRefund` | Request an incoming payment for a BOLT12 refund |
| `Bolt12CreatePayerProof` | Create a BOLT 12 payer proof from a successful payment |

### Spontaneous and Unified Send

Expand Down Expand Up @@ -229,27 +230,45 @@ GET /metrics
Returns Prometheus-format text. Requires `[metrics] enabled = true` in the config. Supports
optional Basic Auth. See [Configuration](configuration.md#metrics) for setup.

## BOLT 12 Payer-Proof Lifecycle

Subscribe with `SubscribeEvents` before you send a BOLT 12 payment. Events are not replayed.

When `PaymentSuccessful` arrives, retain its `payment_id`, `payment_preimage`, and
`bolt12_invoice`. Pass these values to `Bolt12CreatePayerProof`. The request can also select the
optional invoice fields that the proof discloses.

The `bolt12_invoice` field is absent for static-invoice payments. These asynchronous payments
cannot produce payer proofs.

## Hodl Invoice Lifecycle

Hodl invoices allow you to inspect and conditionally accept incoming payments:

1. **Create the invoice:** Call `Bolt11ReceiveForHash` with a payment hash you control.
2. **Wait for payment:** Subscribe to events via `SubscribeEvents` and watch for a
`PaymentClaimable` event matching your payment hash.
3. **Decide:**
- **Accept:** Call `Bolt11ClaimForHash` with the preimage corresponding to the payment hash.
- **Reject:** Call `Bolt11FailForHash` with the payment hash.
1. **Subscribe:** Call `SubscribeEvents` before you create or share the invoice. Events are not
replayed.
2. **Create the invoice:** Generate a new payment hash. Call `Bolt11ReceiveForHash` with this hash.
Never reuse a payment hash. Reuse is unsafe and can cause loss of funds.
3. **Handle each payment:** Save the payment ID from each `PaymentClaimable` event. A payer can pay
the same invoice more than once. Each payment has a separate event and payment ID.
4. **Decide before `claim_deadline`:**
- **Accept an expected payment:** Call `Bolt11ClaimForId` with its payment ID and preimage.
- **Reject an unexpected payment:** Call `Bolt11FailForId` with its payment ID. Reject duplicate
and late payments instead of ignoring or claiming them.

The payment is held in a pending state until you explicitly claim or fail it. **You must
always call one of these.** If you do neither, the HTLC will eventually time out, which
can cause a force-closure of the channel.
always handle each event.** If you do not, the HTLC will eventually time out. This can cause a
force-closure of the channel.
Comment on lines 259 to +261

@tankyleo tankyleo Sep 5, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Somewhat related to the above discussion, also landed on this update here:

-The payment is held in a pending state until you explicitly claim or fail it. **You must
-always handle each event.** If you do not, the HTLC will eventually time out. This can cause a
-force-closure of the channel.
+The payment is held in a pending state until you claim it, fail it, or its `claim_deadline` is
+reached. `PaymentClaimable` notifications are best-effort and are not replayed. If you miss the
+event or do not act before the deadline, LDK Node automatically fails the HTLC backward and the
+payment can no longer be claimed. Keep the subscriber healthy and resolve reported persistence
+errors before accepting further payments.


## Pagination

`ListPayments` and `ListForwardedPayments` support cursor-based pagination:

1. Make the first request with your desired `number_of_payments` page size.
1. Make the first request without a `page_token`. The server controls the page size.
2. If the response includes a `next_page_token`, pass it as `page_token` in the next request.
3. When `next_page_token` is absent, you have reached the end of the results.

Results are ordered by creation time (most recent first).
The page token is one opaque string. Do not parse or modify it. Results are ordered by creation
time (most recent first).

The CLI `--number-of-payments` option combines multiple pages. It does not set the gRPC page size.
9 changes: 5 additions & 4 deletions docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -209,11 +209,12 @@ Two resolution methods are supported via the `mode` field:
<network>/ # e.g., bitcoin/, regtest/, signet/
api_key # API key
ldk-server.log # Log file
ldk_node_data.sqlite # LDK Node state (channels, on-chain wallet)
ldk_server_data.sqlite # Payment and forwarding history
ldk_node_data.sqlite # LDK Node state (channels, wallet, payments)
ldk_server_data.sqlite # Forwarded-payment history
```

The mnemonic is the node's master secret, required to recover on-chain funds. On first start,
ldk-server generates a fresh 24-word BIP39 mnemonic at `<storage_dir>/keys_mnemonic` if the file
does not already exist. `ldk_node_data.sqlite` holds channel state, both are required to recover
channel funds. See [Operations - Backups](operations.md#backups) for backup guidance.
does not already exist. `ldk_node_data.sqlite` holds channel state and payment history. Both files
are required to recover channel funds. See [Operations - Backups](operations.md#backups) for backup
guidance.
4 changes: 2 additions & 2 deletions docs/operations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,8 +53,8 @@ the following config to `/etc/logrotate.d/ldk-server` (adjust the log path to ma
| File | Priority | Description |
| -------------------------------------- | ------------ | -------------------------------------------------------------------------- |
| `<storage_dir>/keys_mnemonic` | **Critical** | BIP39 mnemonic. Required to recover on-chain funds. Default for new installs. |
| `<network_dir>/ldk_node_data.sqlite` | **Critical** | Channel state and on-chain wallet data. Required to recover channel funds. |
| `<network_dir>/ldk_server_data.sqlite` | Nice-to-have | Payment and forwarding history |
| `<network_dir>/ldk_node_data.sqlite` | **Critical** | Channel state, on-chain wallet data, and payment history. Required to recover channel funds. |
| `<network_dir>/ldk_server_data.sqlite` | Nice-to-have | Forwarded-payment history |

### What is Reconstructable

Expand Down
Loading