Skip to content

Bolt11 feature bits #656

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

Merged
rustyrussell merged 3 commits into from
Sep 3, 2019
+64 −1
Merged

Bolt11 feature bits #656

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
44490c3
BOLT 11: Add feature bits.
rustyrussell Jul 18, 2019
a76d61d
BOLT 11: Add test vectors for feature bitfield.
rustyrussell Jul 18, 2019
9becc96
fixup! BOLT 11: Add test vectors for feature bitfield.
rustyrussell Aug 28, 2019
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
65 changes: 64 additions & 1 deletion 11-payment-encoding.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ over Lightning.
* [Human-Readable Part](#human-readable-part)
* [Data Part](#data-part)
* [Tagged Fields](#tagged-fields)
* [Feature Bits](#feature-bits)
* [Payer / Payee Interactions](#payer--payee-interactions)
* [Payer / Payee Requirements](#payer--payee-requirements)
* [Implementation](#implementation)
Expand Down Expand Up @@ -140,6 +141,9 @@ Currently defined tagged fields are:
* `fee_base_msat` (32 bits, big-endian)
* `fee_proportional_millionths` (32 bits, big-endian)
* `cltv_expiry_delta` (16 bits, big-endian)
* `9` (5): `data_length` variable. One or more 5-bit values containing features
supported or required for receiving this payment.
See [Feature Bits](#feature-bits).

### Requirements

Expand All @@ -156,10 +160,13 @@ A writer:
through some unspecified means.
- SHOULD use a complete description of the purpose of the payment.
- MAY include one `x` field.
- if `x` is included:
- SHOULD use the minimum `data_length` possible.
- MAY include one `c` field.
- MUST set `c` to the minimum `cltv_expiry` it will accept for the last
HTLC in the route.
- SHOULD use the minimum `data_length` possible for `x` and `c` fields.
- if `c` is included:
- SHOULD use the minimum `data_length` possible.
- MAY include one `n` field. (Otherwise performing signature recovery is required)
- MUST set `n` to the public key used to create the `signature`.
- MAY include one or more `f` fields.
Expand All @@ -175,13 +182,22 @@ A writer:
`fee_base_msat`, `fee_proportional_millionths`, and `cltv_expiry_delta` are as
specified in [BOLT #7](07-routing-gossip.md#the-channel_update-message).
- MAY include more than one `r` field to provide multiple routing options.
- if `9` contains non-zero bits:
Copy link
Copy Markdown
Contributor

@halseth halseth Aug 28, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be on the same format as the other fields? MAY include one 9 field.

Copy link
Copy Markdown
Collaborator Author

@rustyrussell rustyrussell Sep 3, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, it either MUST or MUST NOT.

- SHOULD use the minimum `data_length` possible.
Copy link
Copy Markdown
Collaborator

@cfromknecht cfromknecht Aug 26, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

might help to clarify that this encoded directly to base32

Copy link
Copy Markdown
Collaborator Author

@rustyrussell rustyrussell Aug 28, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

... this same language is used elsewhere for minimal encoding requirements.

But I did change:

-* `9` (5): `data_length` variable. One or more bytes containing features
+* `9` (5): `data_length` variable. One or more 5-bit values containing features

Copy link
Copy Markdown
Collaborator

@cfromknecht cfromknecht Aug 28, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

on the first pass i took minimally encoded to mean wire format, minimally encoded, but i think this resolves that ambiguity 👍

- otherwise:
- MUST omit the `9` field altogether.
- MUST pad field data to a multiple of 5 bits, using 0s.
- if a writer offers more than one of any field type, it:
- MUST specify the most-preferred field first, followed by less-preferred fields, in order.

A reader:
- MUST skip over unknown fields, OR an `f` field with unknown `version`, OR `p`, `h`, or
`n` fields that do NOT have `data_length`s of 52, 52, or 53, respectively.
- if the `9` field contains unknown _odd_ bits that are non-zero:
- MUST ignore the bit.
- if the `9` field contains unknown _even_ bits that are non-zero:
- MUST fail the payment.
Copy link
Copy Markdown
Contributor

@halseth halseth Aug 28, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"fail the payment" is perhaps ambiguous here. Instead maybe "MUST NOT pay the invoice"?

Copy link
Copy Markdown
Collaborator Author

@rustyrussell rustyrussell Sep 3, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's the same language used elsewhere, so I think this is a separate issue?

- SHOULD indicate the unknown bit to the user.
- MUST check that the SHA2 256-bit hash in the `h` field exactly matches the hashed
description.
- if a valid `n` field is provided:
Expand Down Expand Up @@ -253,6 +269,15 @@ engines that support SQL or other dynamically interpreted querying languages.

Don't be like the school of [Little Bobby Tables](https://xkcd.com/327/).

## Feature Bits

Feature bits allow forward and backward compatibility, and follow the
_it's ok to be odd_ rule.

The field is big-endian. The least-significant bit is numbered 0,
which is _even_, and the next most significant bit is numbered 1,
which is _odd_.

# Payer / Payee Interactions

These are generally defined by the rest of the Lightning BOLT series,
Expand Down Expand Up @@ -509,6 +534,44 @@ Breakdown:
* `6c6e626332306d0b25fe64570d0e496dbd9f8b0d000dbb44824f751380da37c6dba89b14f6f92047d63f576e304021a00008101820283038404800081018202830384048000810182028303840480810243500c318a1e0a628b34025e8c9019ab6d09b64c2b3c66a693d0dc63194b02481931000` hex of data for signing (prefix + data after separator up to the start of the signature)
* `399a8b167029fda8564fd2e99912236b0b8017e7d17e416ae17307812c92cf42` hex of SHA256 of the preimage

> ### Please send $30 for coffee beans to the same peer, which supports features 1 and 9
> lnbc25m1pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdq5vdhkven9v5sxyetpdees9qzsze992adudgku8p05pstl6zh7av6rx2f297pv89gu5q93a0hf3g7lynl3xq56t23dpvah6u7y9qey9lccrdml3gaqwc6nxsl5ktzm464sq73t7cl
Comment thread
cfromknecht marked this conversation as resolved.

Breakdown:

* `lnbc`: prefix, Lightning on Bitcoin mainnet
* `25m`: amount (25 milli-bitcoin)
* `1`: Bech32 separator
* `pvjluez`: timestamp (1496314658)
* `p`: payment hash...
* `d`: short description
* `q5`: `data_length` (`q` = 0, `5` = 20; 0 * 32 + 20 == 20)
* `vdhkven9v5sxyetpdees`: 'coffee beans'
* `9`: features
* `qz`: `data_length` (`q` = 0, `z` = 2; 0 * 32 + 2 == 2)
* `sz`: b1000000010
* `e992adudgku8p05pstl6zh7av6rx2f297pv89gu5q93a0hf3g7lynl3xq56t23dpvah6u7y9qey9lccrdml3gaqwc6nxsl5ktzm464sq`: signature
* `73t7cl`: Bech32 checksum

> # Same, but using invalid unknown feature 100
> lnbc25m1pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdq5vdhkven9v5sxyetpdees9q4pqqqqqqqqqqqqqqqqqqszk3ed62snp73037h4py4gry05eltlp0uezm2w9ajnerhmxzhzhsu40g9mgyx5v3ad4aqwkmvyftzk4k9zenz90mhjcy9hcevc7r3lx2sphzfxz7
Comment thread
cfromknecht marked this conversation as resolved.

Breakdown:

* `lnbc`: prefix, Lightning on Bitcoin mainnet
* `25m`: amount (25 milli-bitcoin)
* `1`: Bech32 separator
* `pvjluez`: timestamp (1496314658)
* `p`: payment hash...
* `d`: short description
* `q5`: `data_length` (`q` = 0, `5` = 20; 0 * 32 + 20 == 20)
* `vdhkven9v5sxyetpdees`: 'coffee beans'
* `9`: features
* `q4`: `data_length` (`q` = 0, `4` = 21; 0 * 32 + 21 == 21)
* `pqqqqqqqqqqqqqqqqqqsz`: b00001...(90 zeroes)...1000000010
* `k3ed62snp73037h4py4gry05eltlp0uezm2w9ajnerhmxzhzhsu40g9mgyx5v3ad4aqwkmvyftzk4k9zenz90mhjcy9hcevc7r3lx2sp`: signature
* `hzfxz7`: Bech32 checksum

# Authors

[ FIXME: ]
Expand Down