nips/89.md
ATXMJ 9ec2090b1b
Update NIP-89
Add examples of client steps for broadcasting and observing `"payto"` events
2023-02-17 16:18:14 -07:00

95 lines
6.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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