Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

First stab at changes to add lnaddress #433

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
+221 −166
Open

First stab at changes to add lnaddress #433

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
fac6026
First stab at changes to add lnaddress
brianoflondon Jan 21, 2023
9733638
Add details for bare endpoint
brianoflondon Feb 22, 2023
66f4446
Merge branch 'Podcastindex-org:main' into brianoflondon-lightning-val…
brianoflondon Feb 22, 2023
5446154
More formal language to describe api returns
brianoflondon Feb 26, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
219 changes: 219 additions & 0 deletions value/lightning_value_spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 `<podcast:value>` 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 `<podcast:valueRecipient>` tag, the following attributes MUST be used:

- `type`: "node"
- `address`: \<the destination node's pubkey\>
- `split`: \<the number of shares\>
- `lnaddress` (optional): \<the destination node's Lightning Address\>


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 `<podcast:value>` 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 `<podcast:valueRecipient>` tag, the following attributes MUST be used:

- `type`: "node"
- `address`: \<the destination node's pubkey\>
- `split`: \<the number of shares\>

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`: \<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

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 `<channel>` level, it applies to every podcast episode.

```xml
...
<channel>
<podcast:value type="lightning" method="keysend" suggested="0.00000015000">
<podcast:valueRecipient
name="Adam Curry (Podcaster)"
type="node"
address="02d5c1bf8b940dc9cadca86d1b0a3c37fbe39cee4c7e839e33bef9174531d27f52"
split="49"
/>
<podcast:valueRecipient
name="Dave Jones (Podcaster)"
type="node"
address="032f4ffbbafffbe51726ad3c164a3d0d37ec27bc67b29a159b0f49ae8ac21b8508"
split="46"
/>
<podcast:valueRecipient
name="Dreb Scott (Chapter Creation)"
type="node"
address="02dd306e68c46681aa21d88a436fb35355a8579dd30201581cefa17cb179fc4c15"
split="5"
/>
<podcast:valueRecipient
name="Podcastindex.org (Donation)"
type="node"
address="03ae9f91a0cb8ff43840e3c322c4c61f019d8c1c3cea15a25cfc425ac605e61a4a"
split="1"
fee="true"
/>
</podcast:value>
...
<item>...</item>
<item>...</item>
...
</channel>
```

To use Atomic Multipath Payments (AMP) instead of `keysend`, simply set the
payment `method` to `amp`:

```xml
...
<channel>
<podcast:value type="lightning" method="amp" suggested="0.00000015000">
...
</podcast:value>
</channel>
```

##### Example: `<Item>` Override

To set up different payment splits for individual episodes, a value block has to
be defined on the `<item>` level. This will override the value settings set on
the `<channel>` 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
...
<channel>
<podcast:value type="lightning" method="keysend" suggested="0.00000021000">
<podcast:valueRecipient
name="John Vallis (Host)"
type="node"
address="02a9cd2bca29dd7e29bdfdf485a8e78b8ccf9327517afa03a59be8f62a58792e1b"
split="100"
/>
</podcast:value>
...
<item>
<title>#00 - John's Solo Episode</title>
...
</item>
<item>
<title>#01 - John and Gigi</title>
<podcast:value type="lightning" method="keysend" suggested="0.00000021000">
<podcast:valueRecipient
name="John Vallis (Host)"
type="node"
address="02a9cd2bca29dd7e29bdfdf485a8e78b8ccf9327517afa03a59be8f62a58792e1b"
split="50"
/>
<podcast:valueRecipient
name="Gigi (Guest)"
type="node"
address="02e12fea95f576a680ec1938b7ed98ef0855eadeced493566877d404e404bfbf52"
split="50"
/>
</podcast:value>
...
</item>
<item>
<title>#02 - John and Paul</title>
<podcast:value type="lightning" method="keysend" suggested="0.00000021000">
<podcast:valueRecipient
name="John Vallis (Host)"
type="node"
address="02a9cd2bca29dd7e29bdfdf485a8e78b8ccf9327517afa03a59be8f62a58792e1b"
split="50"
/>
<podcast:valueRecipient
name="Paul Itoi (Guest)"
type="node"
address="03a9a8d953fe747d0dd94dd3c567ddc58451101e987e2d2bf7a4d1e10a2c89ff38"
split="50"
/>
</podcast:value>
...
</item>
...
</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.
168 changes: 2 additions & 166 deletions value/value.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/

<br>

#### Lightning

For the `<podcast:value>` 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 `<podcast:valueRecipient>` tag, the following attributes MUST be used:

- `type`: "node"
- `address`: \<the destination node's pubkey\>
- `split`: \<the number of shares\>

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`: \<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

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 `<channel>` level, it applies to every podcast episode.

```xml
...
<channel>
<podcast:value type="lightning" method="keysend" suggested="0.00000015000">
<podcast:valueRecipient
name="Adam Curry (Podcaster)"
type="node"
address="02d5c1bf8b940dc9cadca86d1b0a3c37fbe39cee4c7e839e33bef9174531d27f52"
split="49"
/>
<podcast:valueRecipient
name="Dave Jones (Podcaster)"
type="node"
address="032f4ffbbafffbe51726ad3c164a3d0d37ec27bc67b29a159b0f49ae8ac21b8508"
split="46"
/>
<podcast:valueRecipient
name="Dreb Scott (Chapter Creation)"
type="node"
address="02dd306e68c46681aa21d88a436fb35355a8579dd30201581cefa17cb179fc4c15"
split="5"
/>
<podcast:valueRecipient
name="Podcastindex.org (Donation)"
type="node"
address="03ae9f91a0cb8ff43840e3c322c4c61f019d8c1c3cea15a25cfc425ac605e61a4a"
split="1"
fee="true"
/>
</podcast:value>
...
<item>...</item>
<item>...</item>
...
</channel>
```

To use Atomic Multipath Payments (AMP) instead of `keysend`, simply set the
payment `method` to `amp`:

```xml
...
<channel>
<podcast:value type="lightning" method="amp" suggested="0.00000015000">
...
</podcast:value>
</channel>
```

##### Example: `<Item>` Override

To set up different payment splits for individual episodes, a value block has to
be defined on the `<item>` level. This will override the value settings set on
the `<channel>` 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
...
<channel>
<podcast:value type="lightning" method="keysend" suggested="0.00000021000">
<podcast:valueRecipient
name="John Vallis (Host)"
type="node"
address="02a9cd2bca29dd7e29bdfdf485a8e78b8ccf9327517afa03a59be8f62a58792e1b"
split="100"
/>
</podcast:value>
...
<item>
<title>#00 - John's Solo Episode</title>
...
</item>
<item>
<title>#01 - John and Gigi</title>
<podcast:value type="lightning" method="keysend" suggested="0.00000021000">
<podcast:valueRecipient
name="John Vallis (Host)"
type="node"
address="02a9cd2bca29dd7e29bdfdf485a8e78b8ccf9327517afa03a59be8f62a58792e1b"
split="50"
/>
<podcast:valueRecipient
name="Gigi (Guest)"
type="node"
address="02e12fea95f576a680ec1938b7ed98ef0855eadeced493566877d404e404bfbf52"
split="50"
/>
</podcast:value>
...
</item>
<item>
<title>#02 - John and Paul</title>
<podcast:value type="lightning" method="keysend" suggested="0.00000021000">
<podcast:valueRecipient
name="John Vallis (Host)"
type="node"
address="02a9cd2bca29dd7e29bdfdf485a8e78b8ccf9327517afa03a59be8f62a58792e1b"
split="50"
/>
<podcast:valueRecipient
name="Paul Itoi (Guest)"
type="node"
address="03a9a8d953fe747d0dd94dd3c567ddc58451101e987e2d2bf7a4d1e10a2c89ff38"
split="50"
/>
</podcast:value>
...
</item>
...
</channel>
```
[AMP]: https://bitcoinops.org/en/topics/multipath-payments/

<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.