From ebd5df5ab59504c055fe697c6fe55d45b97cd06d Mon Sep 17 00:00:00 2001 From: Guilherme Dellagustin Date: Sat, 16 Oct 2021 15:08:10 +0200 Subject: [PATCH] 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. --- value/value.md | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/value/value.md b/value/value.md index df4be9f..d745ea0 100644 --- a/value/value.md +++ b/value/value.md @@ -290,16 +290,22 @@ For the `` tag, the following attributes MUST be used: - `address`: \ - `split`: \ -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`: \ - - `customValue`: \ + - `customKey`: \ + - `customValue`: \ - `address`: \ - `split`: \ + 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 +
##### Example @@ -423,3 +429,13 @@ and guest. ... ``` + +
+ +##### 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. \ No newline at end of file