From 64233a5999a3c54c5cdb890748a662aba77d9c22 Mon Sep 17 00:00:00 2001 From: t-bast Date: Sat, 29 Feb 2020 14:57:48 +0100 Subject: [PATCH] Revert "Bolt 1: Specify that extensions to existing messages must use TLV (#714)" This reverts commit 6ac177f95cd588bcbf05ac7b1c36faa66626bc69. --- 01-messaging.md | 56 ++++++++++++--------------------------------- 02-peer-protocol.md | 48 ++++++++++++++++---------------------- 2 files changed, 35 insertions(+), 69 deletions(-) diff --git a/01-messaging.md b/01-messaging.md index 0ae9d3e62..ef4768220 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -22,7 +22,6 @@ All data fields are unsigned big-endian unless otherwise specified. * [The `ping` and `pong` Messages](#the-ping-and-pong-messages) * [Appendix A: BigSize Test Vectors](#appendix-a-bigsize-test-vectors) * [Appendix B: Type-Length-Value Test Vectors](#appendix-b-type-length-value-test-vectors) - * [Appendix C: Message Extension](#appendix-c-message-extension) * [Acknowledgments](#acknowledgments) * [References](#references) * [Authors](#authors) @@ -38,12 +37,20 @@ After decryption, all Lightning messages are of the form: 1. `type`: a 2-byte big-endian field indicating the type of message 2. `payload`: a variable-length payload that comprises the remainder of the message and that conforms to a format matching the `type` -3. `extension`: an optional [TLV stream](#type-length-value-format) The `type` field indicates how to interpret the `payload` field. The format for each individual type is defined by a specification in this repository. The type follows the _it's ok to be odd_ rule, so nodes MAY send _odd_-numbered types without ascertaining that the recipient understands it. +A sending node: + - MUST NOT send an evenly-typed message not listed here without prior negotiation. + +A receiving node: + - upon receiving a message of _odd_, unknown type: + - MUST ignore the received message. + - upon receiving a message of _even_, unknown type: + - MUST fail the channels. + The messages are grouped logically into five groups, ordered by the most significant bit that is set: - Setup & Control (types `0`-`31`): messages related to connection setup, control, supported features, and error reporting (described below) @@ -54,9 +61,10 @@ The messages are grouped logically into five groups, ordered by the most signifi The size of the message is required by the transport layer to fit into a 2-byte unsigned int; therefore, the maximum possible size is 65535 bytes. -A sending node: - - MUST NOT send an evenly-typed message not listed here without prior negotiation. - - MUST NOT send evenly-typed TLV records in the `extension` without prior negotiation. +A node: + - MUST ignore any additional data within a message beyond the length that it expects for that type. + - upon receiving a known message with insufficient length for the contents: + - MUST fail the channels. - that negotiates an option in this specification: - MUST include all the fields annotated with that option. - When defining custom messages: @@ -67,18 +75,6 @@ A sending node: - SHOULD pick an even `type` identifiers when regular nodes should reject the message and close the connection. -A receiving node: - - upon receiving a message of _odd_, unknown type: - - MUST ignore the received message. - - upon receiving a message of _even_, unknown type: - - MUST fail the channels. - - upon receiving a known message with insufficient length for the contents: - - MUST fail the channels. - - upon receiving a message with an `extension`: - - MAY ignore the `extension`. - - Otherwise, if the `extension` is invalid: - - MUST fail the channels. - ### Rationale By default `SHA2` and Bitcoin public keys are both encoded as @@ -89,9 +85,8 @@ Length is limited to 65535 bytes by the cryptographic wrapping, and messages in the protocol are never more than that length anyway. The _it's ok to be odd_ rule allows for future optional extensions -without negotiation or special coding in clients. The _extension_ field -similarly allows for future expansion by letting senders include additional -TLV data. +without negotiation or special coding in clients. The "ignore +additional data" rule similarly allows for future expansion. Implementations may prefer to have message data aligned on an 8-byte boundary (the largest natural alignment requirement of any type here); @@ -901,27 +896,6 @@ failure: 1. Invalid stream: 0xffffffffffffffffff 00 00 00 2. Reason: valid TLV records but invalid ordering -## Appendix C: Message Extension - -This section contains examples of valid and invalid extensions on the `init` -message. The base `init` message (without extensions) for these examples is -`0x001000000000` (all features turned off). - -The following `init` messages are valid: - -- `0x001000000000`: no extension provided -- `0x00100000000001012a030104`: the extension contains two _odd_ TLV records (with types `0x01` and `0x03`) - -The following `init` messages are invalid: - -- `0x00100000000001`: the extension is present but truncated -- `0x00100000000002012a`: the extension contains unknown _even_ TLV records (assuming that TLV type `0x02` is unknown) -- `0x001000000000010101010102`: the extension TLV stream is invalid (duplicate TLV record type `0x01`) - -Note that when messages are signed, the _extension_ is part of the signed bytes. -Nodes should store the _extension_ bytes even if they don't understand them to -be able to correctly verify signatures. - ## Acknowledgments [ TODO: (roasbeef); fin ] diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 922f9c676..66d539e5e 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -123,13 +123,8 @@ the funding transaction and both versions of the commitment transaction. * [`point`:`htlc_basepoint`] * [`point`:`first_per_commitment_point`] * [`byte`:`channel_flags`] - * [`open_channel_tlvs`:`tlvs`] - -1. tlvs: `open_channel_tlvs` -2. types: - 1. type: 0 (`upfront_shutdown_script`) - 2. data: - * [`...*byte`:`shutdown_scriptpubkey`] + * [`u16`:`shutdown_len`] (`option_upfront_shutdown_script`) + * [`shutdown_len*byte`:`shutdown_scriptpubkey`] (`option_upfront_shutdown_script`) The `chain_hash` value denotes the exact blockchain that the opened channel will reside within. This is usually the genesis hash of the respective blockchain. @@ -212,11 +207,9 @@ The sending node: - MUST set `channel_reserve_satoshis` greater than or equal to `dust_limit_satoshis`. - MUST set undefined bits in `channel_flags` to 0. - if both nodes advertised the `option_upfront_shutdown_script` feature: - - MUST include `upfront_shutdown_script` with either a valid `shutdown_scriptpubkey` as required by `shutdown` `scriptpubkey`, or a zero-length `shutdown_scriptpubkey`. + - MUST include either a valid `shutdown_scriptpubkey` as required by `shutdown` `scriptpubkey`, or a zero-length `shutdown_scriptpubkey`. - otherwise: - - MAY include `upfront_shutdown_script`. - - if it includes `open_channel_tlvs`: - - MUST include `upfront_shutdown_script`. + - MAY include a`shutdown_scriptpubkey`. The sending node SHOULD: - set `to_self_delay` sufficient to ensure the sender can irreversibly spend a commitment transaction output, in case of misbehavior by the receiver. @@ -298,13 +291,8 @@ funding transaction and both versions of the commitment transaction. * [`point`:`delayed_payment_basepoint`] * [`point`:`htlc_basepoint`] * [`point`:`first_per_commitment_point`] - * [`accept_channel_tlvs`:`tlvs`] - -1. tlvs: `accept_channel_tlvs` -2. types: - 1. type: 0 (`upfront_shutdown_script`) - 2. data: - * [`...*byte`:`shutdown_scriptpubkey`] + * [`u16`:`shutdown_len`] (`option_upfront_shutdown_script`) + * [`shutdown_len*byte`:`shutdown_scriptpubkey`] (`option_upfront_shutdown_script`) #### Requirements @@ -1139,8 +1127,8 @@ messages are), they are independent of requirements here. * [`channel_id`:`channel_id`] * [`u64`:`next_commitment_number`] * [`u64`:`next_revocation_number`] - * [`32*byte`:`your_last_per_commitment_secret`] - * [`point`:`my_current_per_commitment_point`] + * [`32*byte`:`your_last_per_commitment_secret`] (option_data_loss_protect,option_static_remotekey) + * [`point`:`my_current_per_commitment_point`] (option_data_loss_protect,option_static_remotekey) `next_commitment_number`: A commitment number is a 48-bit incrementing counter for each commitment transaction; counters @@ -1148,6 +1136,7 @@ are independent for each peer in the channel and start at 0. They're only explicitly relayed to the other node in the case of re-establishment, otherwise they are implicit. + ### Requirements A funding node: @@ -1189,14 +1178,16 @@ The sending node: next `revoke_and_ack` message it expects to receive. - if `option_static_remotekey` applies to the commitment transaction: - MUST set `my_current_per_commitment_point` to a valid point. - - otherwise: + - otherwise, if it supports `option_data_loss_protect`: - MUST set `my_current_per_commitment_point` to its commitment point for - the last signed commitment it received from its channel peer (i.e. the commitment_point + the last signed commitment it received from its channel peer (i.e. the commitment_point corresponding to the commitment transaction the sender would use to unilaterally close). - - if `next_revocation_number` equals 0: - - MUST set `your_last_per_commitment_secret` to all zeroes - - otherwise: - - MUST set `your_last_per_commitment_secret` to the last `per_commitment_secret` it received + - if `option_static_remotekey` applies to the commitment transaction, or the sending node supports `option_data_loss_protect`: + - if `next_revocation_number` equals 0: + - MUST set `your_last_per_commitment_secret` to all zeroes + - otherwise: + - MUST set `your_last_per_commitment_secret` to the last `per_commitment_secret` + it received A node: - if `next_commitment_number` is 1 in both the `channel_reestablish` it @@ -1237,9 +1228,10 @@ A node: - MUST NOT broadcast its commitment transaction. - SHOULD fail the channel. - otherwise: - - if `your_last_per_commitment_secret` does not match the expected values: + - if `your_last_per_commitment_secret` does not match the expected values: - SHOULD fail the channel. - - otherwise, if it supports `option_data_loss_protect`: + - otherwise, if it supports `option_data_loss_protect`, AND the `option_data_loss_protect` + fields are present: - if `next_revocation_number` is greater than expected above, AND `your_last_per_commitment_secret` is correct for that `next_revocation_number` minus 1: