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 -> feat: add hold invoices support for LND & LDK getAlby/hub#1298
• dart NDK -> [NWC] add hold invoice support relaystr/ndk#147
• Bitblik -> NWC support for hold invoices bitblik/coordinator#9

[Semisol]

see review

[rolznz]

Implemented in Alby JS SDK: getAlby/js-sdk#382