diff --git a/321.md b/321.md new file mode 100644 index 0000000..47f80f2 --- /dev/null +++ b/321.md @@ -0,0 +1,160 @@ +NWC-321 +====== + +BIP-321 Lightning Payments +-------------------------- + +`draft` `optional` + +## Summary + +This specification defines two optional Nostr Wallet Connect methods for BIP-321: + +- `pay` pays a Lightning payment instruction from a BIP-321 URI. +- `receive` creates a BIP-321 URI that contains one or more Lightning payment instructions. + +## Motivation + +BIP-321 can put multiple payment instructions in one Bitcoin payment URI. + +This format lets a client use one payment interface for BOLT11 invoices and BOLT12 offers. The wallet selects the instruction that it supports. + +These methods are separate from the NWC core because BIP-321 and BOLT12 support are not available in all wallets. + +## Dependencies + +Implementations of this specification use: + +- [BIP-321](https://github.com/bitcoin/bips/blob/master/bip-0321.mediawiki) for Bitcoin payment URIs. +- [BOLT11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md) for `lightning` instructions. +- [BOLT12](https://github.com/lightning/bolts/blob/master/12-offer-encoding.md) for `lno` instructions. + +## Discovery + +A wallet service advertises each supported method in its NWC info event and `get_info` response. + +A wallet service can implement `pay`, `receive`, or both methods. An implementation of `pay` MUST support `lightning` or `lno` instructions. + +An implementation of `receive` MUST return at least one `lightning` or `lno` instruction. + +## BIP-321 processing + +The wallet service MUST parse the URI according to BIP-321. + +The wallet service MUST make sure that the Bitcoin network matches before payment. It MUST reject a payment instruction for a different network. + +A URI can contain `lightning`, `lno`, or both instruction types. + +If the URI contains multiple supported instructions, the wallet service MUST select and pay only one instruction. + +The wallet service MUST report the selected instruction in `instruction_type`. + +The wallet service can support other BIP-321 payment instructions. Support for other instructions is outside this specification. + +The wallet service MUST reject a URI if it cannot select a supported payment instruction. It MUST also reject unknown required parameters as BIP-321 specifies. + +The wallet service MUST apply the BIP-321 rules for `pop` and `req-pop`. The NWC response does not replace a required proof-of-payment callback. + +If the wallet service cannot safely open a `req-pop` URI, it MUST reject the request before payment. + +## Methods + +### `pay` + +Pays one Lightning payment instruction from a BIP-321 URI. + +Request: + +```yaml +{ + "method": "pay", + "params": { + "payment": "bitcoin:?lno=lno1...", // BIP-321 URI, required + "amount": 123000, // amount in msats, required if the selected instruction has no amount + "payer_note": "string", // payer-provided message, optional + "metadata": {} // optional metadata as defined in 06.md + } +} +``` + +The wallet service MUST reject conflicting or invalid amounts before payment. + +If `payer_note` is not empty, the selected instruction MUST support payer-provided messages. The wallet service MUST deliver the note or reject the request before payment. + +For a BOLT12 offer, the wallet service performs the invoice request and invoice retrieval. + +Response: + +```yaml +{ + "result_type": "pay", + "result": { + "transaction_id": "string", // wallet-scoped transaction identifier + "state": "settled", // "pending", "settled", or "failed" + "instruction_type": "bolt12", // "bolt11" or "bolt12" + "amount": 123000, // paid amount in msats + "fees_paid": 1000, // paid fees in msats + "payment_hash": "string", // optional if unavailable + "preimage": "string", // optional if unavailable + "payer_proof": "lnp1...", // BOLT12 payer proof, optional if unavailable + "txid": "string", // on-chain transaction identifier, optional if unavailable + "failure_reason": "string", // optional unless state is "failed" + "created_at": unixtimestamp, + "settled_at": unixtimestamp // optional unless state is "settled" + } +} +``` + +The `transaction_id` MUST identify the same transaction in later wallet records. + +Errors: + +- `BAD_REQUEST`: The URI or another parameter is invalid. +- `UNSUPPORTED_PAYMENT_INSTRUCTION`: The wallet cannot select a supported payment instruction. +- `UNSUPPORTED_NETWORK`: The selected instruction uses a different Bitcoin network. +- `PAYMENT_FAILED`: The wallet attempted the payment, but the payment failed. + +The wallet service can also return applicable NWC core errors. + +### `receive` + +Creates a BIP-321 URI that the client can give to a payer. + +Request: + +```yaml +{ + "method": "receive", + "params": { + "amount": 123000, // amount in msats, optional; omit or use null for a variable amount + "description": "string", // optional + "metadata": {} // optional metadata as defined in 06.md + } +} +``` + +The wallet service selects the receive instruction or instructions. A client that needs a specific instruction type uses a method for that type. + +Response: + +```yaml +{ + "result_type": "receive", + "result": { + "bip321": "bitcoin:?lightning=lnbc...&lno=lno1...", // BIP-321 URI + "transaction_id": "string", // wallet-scoped transaction identifier, optional + } +} +``` + +The `bip321` value MUST contain one or more wallet-selected receive instructions. Each instruction MUST use the wallet service Bitcoin network. + +If `amount` is absent or null, the returned URI MUST accept an amount from the payer. + +If `description` is present, the wallet service MUST include it in each selected instruction that supports descriptions. + +Errors: + +- `BAD_REQUEST`: A parameter is invalid. + +The wallet service can also return applicable NWC core errors. diff --git a/README.md b/README.md index 12841d7..e09c998 100644 --- a/README.md +++ b/README.md @@ -14,3 +14,4 @@ The core NWC protocol is tracked in NIP-47 for now. This repository reserves `01 | [05](05.md) | Transaction History | Defines the `list_transactions` method for optional transaction history listing. | | [06](06.md) | Metadata Conventions | Defines common metadata keys and limits used by optional NWC features. | | [07](07.md) | Deep Links | Defines optional mobile deep-link conventions for NWC pairing flows. | +| [321](321.md) | BIP-321 Lightning Payments | Defines the `pay` and `receive` methods for BIP-321 Lightning payment instructions. |