mirrors/lightning-bolts
1
0
Fork 0
mirror of https://github.com/lightning/bolts.git synced 2024-11-19 01:50:03 +01:00
Code Issues Projects Releases Wiki Activity

Revert "Bolt 1: Specify that extensions to existing messages must use TLV (#714)" (#753)

Browse Source 
This reverts commit 6ac177f95c.
This commit is contained in:
Bastien Teinturier 2020-02-29 15:00:42 +01:00 committed by GitHub
parent 6ac177f95c
commit f38f559244
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 35 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
01-messaging.md
View File

@ -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 ]

38
02-peer-protocol.md
View File

@ -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
corresponding to the commitment transaction the sender would use to unilaterally close).
- 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
- 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
@ -1239,7 +1230,8 @@ A node:
- otherwise:
- 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: