NIP-47 Add Hold Invoice Support

[frnandu]

Rendered

This PR introduces support for hold invoices in the Nostr Wallet Connect (NIP-47) protocol.

Hold invoices enable more advanced payment workflows where the receiver must explicitly settle or cancel the invoice using the preimage. This allows for enhanced control and coordination in payment flows, such as conditional payments or escrow-like behavior.

Summary of Changes:

• New RPC methods:

  • make_hold_invoice: Create a hold invoice using a pre-generated preimage and its payment hash.
  • settle_hold_invoice: Settle a hold invoice by providing the original preimage.
  • cancel_hold_invoice: Cancel a hold invoice using its payment hash.

• New notification:

  • hold_invoice_accepted: Emitted when a payer accepts a hold invoice (i.e., locks in payment).

• Extended example flow: A new section documents the end-to-end process for using hold invoices, including invoice creation, settlement, and cancellation.

Motivation:

Hold invoices are a key feature in Lightning-based applications that require more complex transaction logic, such as:

• Pay-to-unlock content
• Marketplace escrow systems
• Payment gating and tokenized actions

This addition expands the versatility and usability of NWC while maintaining backward compatibility with existing methods.

Implementations and usages:

• Alby Hub support for LND & LDK backends, PR in progress -> https://github.com/getAlby/hub/pull/1298
• JS-SDk -> https://github.com/getAlby/js-sdk/pull/382
• dart NDK -> https://github.com/relaystr/ndk/pull/147
• Bitblik -> https://github.com/bitblik/coordinator/issues/9

[rolznz]

Implemented in Alby JS SDK: https://github.com/getAlby/js-sdk/pull/382

[daywalker90]

Have you seen my reviews? I never get replies to these, i have a feeling github is shadowbanning me.

[frnandu]

https://blog.getalby.com/build-conditional-payment-logic-into-your-app/

[daywalker90]

I've implemented this PR for CLN in my nip47 plugin here https://github.com/daywalker90/cln-nip47/pull/4 with the necessary changes to the library i use here https://github.com/rust-nostr/nostr/pull/1019 and the necessary changes to my holdinvoice plugin here: https://github.com/daywalker90/holdinvoice/pull/2

Everything looks good to me so far. Is there a client other than myself to test this with already?

[frnandu]

Everything looks good to me so far. Is there a client other than myself to test this with already?

You can try https://github.com/relaystr/ndk there is even a demo app .apk in the releases

[frnandu]

LGTM. We should specify that all preimages and hashes are encoded as hex in the spec.

NIP-47 originally doesn't have such thing specified there. Are you saying change it globally?