From 44490c33decdfe840c8f333ba1fa1f361c03dc17 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Thu, 18 Jul 2019 16:49:32 +0930 Subject: [PATCH 1/3] BOLT 11: Add feature bits. Most obviously, we want this for BASE AMP, but it's useful in future. Even though even bits won't cause existing implementations to know they can't pay the invoice, it will allow it in future once everyone has upgraded. Signed-off-by: Rusty Russell --- 11-payment-encoding.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/11-payment-encoding.md b/11-payment-encoding.md index 0db670636..a9917aebc 100644 --- a/11-payment-encoding.md +++ b/11-payment-encoding.md @@ -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) @@ -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 bytes containing features + supported or required for receiving this payment. + See [Feature Bits](#feature-bits). ### Requirements @@ -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. @@ -175,6 +182,10 @@ 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: + - SHOULD use the minimum `data_length` possible. + - 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. @@ -182,6 +193,10 @@ A writer: 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. - MUST check that the SHA2 256-bit hash in the `h` field exactly matches the hashed description. - if a valid `n` field is provided: @@ -253,6 +268,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, From a76d61dc9893eec75b2e9c4a361354c356c46894 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Thu, 18 Jul 2019 16:49:34 +0930 Subject: [PATCH 2/3] BOLT 11: Add test vectors for feature bitfield. Signed-off-by: Rusty Russell --- 11-payment-encoding.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/11-payment-encoding.md b/11-payment-encoding.md index a9917aebc..ddeee7013 100644 --- a/11-payment-encoding.md +++ b/11-payment-encoding.md @@ -533,6 +533,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 + +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 + +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: ] From 9becc963b208a782edbebe145407f7e80073388a Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Wed, 28 Aug 2019 10:50:02 +0930 Subject: [PATCH 3/3] fixup! BOLT 11: Add test vectors for feature bitfield. --- 11-payment-encoding.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/11-payment-encoding.md b/11-payment-encoding.md index ddeee7013..d22d4de8a 100644 --- a/11-payment-encoding.md +++ b/11-payment-encoding.md @@ -141,7 +141,7 @@ 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 bytes containing features +* `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). @@ -196,7 +196,8 @@ A reader: - 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. + - MUST fail the payment. + - 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: