Updated podcast:value specification for custom records

This commit makes the usage of customKey and customValue more specific.

The change to the spec was made based on the known users for these
attributes (LNPay and HIVE gateway), but it is not necessarily backwards
compatible.

Why is this change neccessary?

Client applications that use the information on the podcast:value
tag must know what to with its content.

Imagine one receiver sets customValue to raw binary data encoded in
hex, and expects it to be sent in the payment as raw binary
data.

Imagine another receiver sets customValue to raw binary data encoded in
base64, and expects it to be sent in the payment as raw binary
data.

Imagine now that other receiver sets customerValue to a string, and
expects it to be sent in the payment as a string encoded in UTF-8 (which
currently known users do).

There is no way a client could know what do to with customValue (how to
decode it an re-encode it), without specific knowledge about how each
receiver uses this field.

Although this is possible, it is counter productive for client
development, as clients should have to know as little as possible
about different application specific protocols used by the receivers.
pull/307/head
Guilherme Dellagustin 2021-10-16 15:08:10 +02:00
rodzic 24e447a16a
commit ebd5df5ab5
1 zmienionych plików z 20 dodań i 4 usunięć

Wyświetl plik

@ -290,16 +290,22 @@ For the `<podcast:valueRecipient>` tag, the following attributes MUST be used:
- `address`: \<the destination node's pubkey\>
- `split`: \<the number of shares\>
If the receiving Lightning node, or service, requires a custom record or meta-data of some sort to be passed along with the payment
the `customKey` and `customValue` can be utilized as follows:
If the receiving Lightning node, or service, requires application specific data to be sent with the payment in the lightning message `extension` (a _TLV stream_, see the Appendix section), the `customKey` and `customValue` can be utilized as follows:
- `type`: "node"
- `method`: "keysend" or "amp"
- `customKey`: \<key name\>
- `customValue`: \<value\>
- `customKey`: \<tlv record type, a 64 bit integer greater than or equal to 2^16\>
- `customValue`: \<tlv record value, a string\>
- `address`: \<the destination node's pubkey\>
- `split`: \<the number of shares\>
When sending a payment containing application specific data, the client must use UTF-8 as encoding for `customValue`.
**Remarks:**
- `customValue` is specified as a string due to the emergence of known users for this field (see Appendix). If we decide to support raw binary data in the future, a new attribute can be introduced to indicate the different behavior
- There is at least one known shared node ([satoshis.stream](https://satoshis.stream/)) that requires, in addition to this specification, the inclusion of the TLV record with type `7629169`, as defined [here](https://github.com/satoshisstream/satoshis.stream/blob/main/TLV_registry.md#field-7629169), in order to correctly route the payment to the corresponding receiver
<br>
##### Example
@ -423,3 +429,13 @@ and guest.
...
</channel>
```
<br>
##### Appendix
Lightning payments are performed using lightning messages as specified in [BOLT #1: Base Protocol](https://github.com/lightningnetwork/lightning-rfc/blob/master/01-messaging.md).
One part of the message is the `extension`, a TLV (Type-Length-Value) stream. Application specific data can be added to transactions using _custom records_ on the TLV Stream.
A community maintained registry of known custom record types and formats, governed by satoshis.stream, can be found at the document [TLV record registry](https://github.com/satoshisstream/satoshis.stream/blob/main/TLV_registry.md). In special, the section _Fields used in customKey / customValue Pairs_ documents the known use cases for the `customKey` and `customValue` attributes.