diff --git a/value/lightning_value_spec.md b/value/lightning_value_spec.md new file mode 100644 index 0000000..18b9d39 --- /dev/null +++ b/value/lightning_value_spec.md @@ -0,0 +1,219 @@ +# Lightning Value Block Specification + +The *Lightning Network* (LN) was the first Value Block specification to see wide adoption. + +## Version 2.0.0 + +The following extensions to the Lightning Value Block Specification are added: + +For the `` tag, the following attributes MUST be used: + + - `type` (required): "lightning" + - `method` (required): "keysend" or "amp" + - `suggested` (optional): A float representing a BTC amount. + e.g. 0.00000005000 is 5 Sats. + - `version` (required): `"2.0.0"` + +For the `` tag, the following attributes MUST be used: + + - `type`: "node" + - `address`: \ + - `split`: \ + - `lnaddress` (optional): \ + + +Providers (say, `example.com`) supporting `.well-known/keysend` lookup scheme should implement the following: +## GET `https://example.com/.well-known/keysend` +GET request to `https://example.com/.well-known/keysend` should return HTTP status code 200 and a JSON with at least the following fields + +* `status` (required): "OK" +* `message` (required): string describing what information is returned through this lookup scheme + +## GET `https://example.com/.well-known/keysend/{lightningUsername}` +GET request to `https://example.com/.well-known/keysend/{lightningUsername}` should return the following based on the value of `{lightningUsername}`: + +* If Ligthning address `{lightningUsername}@example.com` exists, HTTP status code 200 and a JSON with at least the following fields should be returned: + + * `status` (required): "OK" + * `tag` (required): "keysend" + * `pubkey` (required): string representing destination node's public key + * `customData` (optional): array of `CustomData`, which has fields + + * `customKey` (required): number + * `customValue` (required): string + +* Optionally, if the syntax for the Lightning address at `example.com` does not allow username `{lightningUsername}`, HTTP status code 422 and a JSON with at least the following fields should be returned: + + * `status` (required): "UNPROCESSABLE_ENTITY" + * `tag` (required): "keysend" + * `message` (optional): string describing why the username is invalid + +* In any other case, HTTP status code 404 and a JSON with at least the following fields should be returned: + * `status` (required): "NOT_FOUND" + * `tag` (required): "keysend" + + +## Version 1.0.0 + +For the `` tag, the following attributes MUST be used: + + - `type` (required): "lightning" + - `method` (required): "keysend" or "amp" + - `suggested` (optional): A float representing a BTC amount. + e.g. 0.00000005000 is 5 Sats. + +For the `` tag, the following attributes MUST be used: + + - `type`: "node" + - `address`: \ + - `split`: \ + +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`: \ + - `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 + +This is a live, working example of a Lightning keysend value block in production. It designates four recipients for payment - two +podcast hosts at 49 and 46 shares respectively, a producer working on per episode chapter creation who gets a 5 share, and +a single share (effectively 1%) fee to the Podcastindex.org API. +Since the value block is defined at the `` level, it applies to every podcast episode. + +```xml +... + + + + + + + + ... + ... + ... + ... + +``` + +To use Atomic Multipath Payments (AMP) instead of `keysend`, simply set the +payment `method` to `amp`: + +```xml +... + + + ... + + +``` + +##### Example: `` Override + +To set up different payment splits for individual episodes, a value block has to +be defined on the `` level. This will override the value settings set on +the `` level. + +The following example defines different value blocks for each episode in order +to include the guests as value recipients. Payments are split 50/50 between host +and guest. + +```xml +... + + + + + ... + + #00 - John's Solo Episode + ... + + + #01 - John and Gigi + + + + + ... + + + #02 - John and Paul + + + + + ... + + ... + +``` + +
+ +##### 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. diff --git a/value/value.md b/value/value.md index 845fe8c..2d46ffa 100644 --- a/value/value.md +++ b/value/value.md @@ -279,172 +279,8 @@ Another method to send spontaneous payments via Lightning is AMP, atomic more robust and larger payments. However, it is still in beta and thus not widely implemented as of now. -[AMP]: https://bitcoinops.org/en/topics/multipath-payments/ - -
- -#### Lightning - -For the `` tag, the following attributes MUST be used: - - - `type` (required): "lightning" - - `method` (required): "keysend" or "amp" - - `suggested` (optional): A float representing a BTC amount. - e.g. 0.00000005000 is 5 Sats. - -For the `` tag, the following attributes MUST be used: - - - `type`: "node" - - `address`: \ - - `split`: \ - -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`: \ - - `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 - -This is a live, working example of a Lightning keysend value block in production. It designates four recipients for payment - two -podcast hosts at 49 and 46 shares respectively, a producer working on per episode chapter creation who gets a 5 share, and -a single share (effectively 1%) fee to the Podcastindex.org API. -Since the value block is defined at the `` level, it applies to every podcast episode. - -```xml -... - - - - - - - - ... - ... - ... - ... - -``` - -To use Atomic Multipath Payments (AMP) instead of `keysend`, simply set the -payment `method` to `amp`: - -```xml -... - - - ... - - -``` - -##### Example: `` Override - -To set up different payment splits for individual episodes, a value block has to -be defined on the `` level. This will override the value settings set on -the `` level. - -The following example defines different value blocks for each episode in order -to include the guests as value recipients. Payments are split 50/50 between host -and guest. +The specification for [Lightning Value Blocks can be found here.](value/lightning_value_spec.md) -```xml -... - - - - - ... - - #00 - John's Solo Episode - ... - - - #01 - John and Gigi - - - - - ... - - - #02 - John and Paul - - - - - ... - - ... - -``` +[AMP]: https://bitcoinops.org/en/topics/multipath-payments/
- -##### 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. -