NIP-89: payto: Payment Targets

89.md

@@ -0,0 +1,94 @@
+# NIP-89
+
+## payto: Payment Targets
+
+`draft` `optional` `author:atxmj`
+
+This NIP standardizes the approach to payment and tip invocations from user profiles, posts, chats, and elsewhere using the [RFC-8905 (payto:) URI scheme](https://www.rfc-editor.org/rfc/rfc8905.html) standard for "payment targets".
+
+### 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\"}]}"
+  ...
+}
+```
+
+#### Example of steps taken by the client on input
+
+- allow the user to specify a list of `payment_target_type` and `authority` value pairs (labeled as preferred by the client) of their choice
+- for each pair of `payment_target_type` and `authority` values specified by the user
+    - *optionally* do some minimal validation on those fields in a generalized way that applies to any payment network
+    - *optionally* warn users if a specifid `payment_target_type` is not [*recognized*](#recommended-payment-target-types) by the client
+- broadcast the event in the format specified above
+
+### 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 `payto` 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://<payment_target_type>/<authority>`. 
+
+The client *should* store a map of [recognized payment target types](#recommended-payment-target-types) along with a corresponding icon & 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 & 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 & stylizations for the [*recognized* payment target types](#recommended-payment-target-types).
+
+*Optionally*, the client may have chosen to render the third payment target using the text `unknowntype` rather than ignoring it.
+
+#### Example of steps taken by the client on observation
+
+- for each pair of `payment_target_type` and `authority` values in the `payto` list
+    - *optionally* do some minimal validation on those fields in a generalized way that applies to any payment network, and filter out invalid pairs
+    - *optionally* filter out any pairs with an [*unrecognized*](#recommended-payment-target-types) `payment_target_type`
+    - assemble a full `payto://` deep link URI in the format `payto://<payment_target_type>/<authority>`
+    - render a button, link, or dropdown in user profiles, posts, chats, and elsewhere using the assembled deep links and the corresponding icons & stylization configurations for *recognized* `payment_target_type` values

README.md

@@ -60,6 +60,7 @@ They exist to document what may be implemented by [Nostr](https://github.com/nos
 - [NIP-58: Badges](58.md)
 - [NIP-65: Relay List Metadata](65.md)
 - [NIP-78: Application-specific data](78.md)
+- [NIP-89: payto: Payment Targets](89.md)
 - [NIP-94: File Metadata](94.md)
 
 ## Event Kinds