diff --git a/89.md b/89.md new file mode 100644 index 00000000..9e09ef25 --- /dev/null +++ b/89.md @@ -0,0 +1,76 @@ +# NIP-89 + +## payto: Payment Targets + +`draft` `optional` `author:atxmj` + +### payto: event broadcasting + +Clients *may* allow users to specify a list (one or many) of "payment targets" as specified in the [RFC-8905 (payto:) URI scheme](https://www.rfc-editor.org/rfc/rfc8905.html) standard, each consisting of a pair of values, `payment_target_type` and `authority` (to be labeled as preferred by the client), in order to generate an event of kind `0` (`set_metadata`) specifying "payment targets" that *may* be used for payment or tip invocation from a user's profile, posts, chats, or elsewhere. + +The client *may* allow the user to input and perform validation on the `payment_target_type` and `authority` fields (labeled as preferred by the client) as they see fit. + +### Example of broadcasting a "payto" event + +The client allows the user to add multiple pairs of "payment network" and "address" values to a list of "payment options" in their profile. + +The client performs validation on the inputs and warns the user that the "payment network" for the third "payment option" with value `unknowntype` is [not recognized](#recommended-payment-target-types), but allows them to submit it regardless. + +The client then broadcasts an event such as + +```json +{ + "pubkey": "afc93622eb4d79c0fb75e56e0c14553f7214b0a466abeba14cb38968c6755e6a", + "kind": 0, + "content": "{\"payto\": [{\"payment_target_type\": \"bitcoin\", \"authority\": \"bc1qxq66e0t8d7ugdecwnmv58e90tpry23nc84pg9k\"}, {\"payment_target_type\": \"nano\", \"authority\": \"nano_1dctqbmqxfppo9pswbm6kg9d4s4mbraqn8i4m7ob9gnzz91aurmuho48jx3c\"}, {\"payment_target_type\": \"unknowntype\", \"authority\": \"l7tbta5b9xze6ckkfc99uohzxd009b0r\"}]}" + ... +} +``` + +### Recommended Payment Target Types + +This is a list of recommended payment target types for clients to recognize and store icons and stylization configurations for. + +| Payment Target Type | Long Stylization | Short Stylization | Symbol | References | +| :------------------ | :---------------- | :---------------- | :----- | :--------- | +| bitcoin | Bitcoin | BTC | ₿ | https://bitcoin.design/ | +| lightning | Lightning Network | LBTC | — | https://github.com/shocknet/bitcoin-lightning-logo | +| cashme | Cash App | Cash App | – | https://cash.app/press | +| nano | Nano | XNO | Ӿ | https://nano.org/en/currency | + +### payto: event observation + +On observation of events of kind `0` (`set_metadata`), the event *may* specify the key `"payto"` with a value consisting of a list (one or many) of "payment target" values, each specified as a pair of values `payment_target_type` and `authority` as specified in the [RFC-8905 (payto:) URI scheme](https://www.rfc-editor.org/rfc/rfc8905.html) for payment targets. + +For each pair of values in the list, the client *should* assemble a full `payto://` deep link URI and render it as a button or link in the user's profile, posts, chats, or elsewhere, in the format of `payto:///`. + +The client *should* store a map of [recognized payment target types](#recommended-payment-target-types) along with a corresponding icon and/or stylization configuration (to be defined by the client). + +For ***recognized*** `payment_target_type` values, the client *should* render a button or link using the associated icon and/or stylization. + +For ***unrecognized*** `payment_target_type` values, the client *may* chose to either ignore them or use a generic stylization, perhaps using the `payment_target_type` value directly for the button or link. + +If a user has specified multiple payment targets, the client *may* choose to render only the first one, render multiple buttons or links, or render a dropdown to select the payment target of choice. + +### Example of observing a "payto" event + +If a client sees an event like this: + +```json +{ + "pubkey": "afc93622eb4d79c0fb75e56e0c14553f7214b0a466abeba14cb38968c6755e6a", + "kind": 0, + "content": "{\"payto\": [{\"payment_target_type\": \"bitcoin\", \"authority\": \"bc1qxq66e0t8d7ugdecwnmv58e90tpry23nc84pg9k\"}, {\"payment_target_type\": \"nano\", \"authority\": \"nano_1dctqbmqxfppo9pswbm6kg9d4s4mbraqn8i4m7ob9gnzz91aurmuho48jx3c\"}, {\"payment_target_type\": \"unknowntype\", \"authority\": \"l7tbta5b9xze6ckkfc99uohzxd009b0r\"}]}" + ... +} +``` + +for each payment target it will assemble a deep link payment invocation URI, as + +`payto://bitcoin/bc1qxq66e0t8d7ugdecwnmv58e90tpry23nc84pg9k` (*recognized*) +`payto://nano/nano_1dctqbmqxfppo9pswbm6kg9d4s4mbraqn8i4m7ob9gnzz91aurmuho48jx3c` (*recognized*) +`payto://unknowntype/l7tbta5b9xze6ckkfc99uohzxd009b0r` (*unrecognized*) + +The client chooses to ignore the third *unrecognized* `payment_target_type`, and only embeds the first two payment target deep links in the user's profile, posts, chats, or elsewhere as buttons, links, or a dropdown selector using the corresponding icons or stylizations for the [*recognized* payment target types](#recommended-payment-target-types). + + diff --git a/README.md b/README.md index e45c531b..efd753f7 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,7 @@ NIPs stand for **Nostr Implementation Possibilities**. They exist to document wh - [NIP-56: Reporting](56.md) - [NIP-57: Lightning Zaps](57.md) - [NIP-65: Relay List Metadata](65.md) +- [NIP-89: payto: Payment Targets](89.md) ## Event Kinds | kind | description | NIP |