diff --git a/.travis.yml b/.travis.yml index c1a88c555..c48abcd55 100644 --- a/.travis.yml +++ b/.travis.yml @@ -9,5 +9,5 @@ python: - "3.5" - "3.6" script: - - (set -e; for i in 0?-*.md; do echo "Extracting $i"; python3 tools/extract-formats.py --message-types --message-fields $i; done) + - (set -e; for i in 0?-*.md; do echo "Extracting $i"; python3 tools/extract-formats.py $i; done) - tools/spellcheck.sh --check [0-9][0-9]-*.md diff --git a/01-messaging.md b/01-messaging.md index 5475b6d68..bffd3eaab 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -14,6 +14,7 @@ All data fields are unsigned big-endian unless otherwise specified. * [Connection Handling and Multiplexing](#connection-handling-and-multiplexing) * [Lightning Message Format](#lightning-message-format) * [Type-Length-Value Format](#type-length-value-format) + * [Fundamental Types](#fundamental-types) * [Setup Messages](#setup-messages) * [The `init` Message](#the-init-message) * [The `error` Message](#the-error-message) @@ -83,6 +84,7 @@ however, adding a 6-byte padding after the type field was considered wasteful: alignment may be achieved by decrypting the message into a buffer with 6-bytes of pre-padding. +<<<<<<< HEAD ## Type-Length-Value Format @@ -171,6 +173,31 @@ follow. On the other hand, if a `tlv_record` contains multiple, variable-length elements then this would not be considered redundant, and is needed to allow the receiver to parse individual elements from `value`. +## Fundamental Types + +Various fundamental types are referred to in the message specifications: + +* `byte`: an 8-bit byte +* `u16`: a 2 byte unsigned integer +* `u32`: a 4 byte unsigned integer +* `u64`: an 8 byte unsigned integer + +Inside TLV records which contain a single value, leading zeros in +integers can be omitted: + +* `tu16`: a 0 to 2 byte unsigned integer +* `tu32`: a 0 to 4 byte unsigned integer +* `tu64`: a 0 to 8 byte unsigned integer + +The following convenience types are also defined: + +* `chain_hash`: a 32-byte chain identifier (see [BOLT #0](00-introduction.md#glossary-and-terminology-guide)) +* `channel_id`: a 32-byte channel_id (see [BOLT #2](02-peer-protocol.md#definition-of-channel-id) +* `sha256`: a 32-byte SHA2-256 hash +* `signature`: a 64-byte bitcoin Elliptic Curve signature +* `point`: a 33-byte Elliptic Curve point (compressed encoding as per [SEC 1 standard](http://www.secg.org/sec1-v2.pdf#subsubsection.2.3.3)) +* `short_channel_id`: an 8 byte value identifying a channel (see [BOLT #7](07-routing-gossip.md#definition-of-short-channel-id)) + ## Setup Messages ### The `init` Message @@ -183,10 +210,10 @@ Both fields `globalfeatures` and `localfeatures` MUST be padded to bytes with 0s 1. type: 16 (`init`) 2. data: - * [`2`:`gflen`] - * [`gflen`:`globalfeatures`] - * [`2`:`lflen`] - * [`lflen`:`localfeatures`] + * [`u16`:`gflen`] + * [`gflen*byte`:`globalfeatures`] + * [`u16`:`lflen`] + * [`lflen*byte`:`localfeatures`] The 2-byte `gflen` and `lflen` fields indicate the number of bytes in the immediately following field. @@ -223,9 +250,9 @@ For simplicity of diagnosis, it's often useful to tell a peer that something is 1. type: 17 (`error`) 2. data: - * [`32`:`channel_id`] - * [`2`:`len`] - * [`len`:`data`] + * [`channel_id`:`channel_id`] + * [`u16`:`len`] + * [`len*byte`:`data`] The 2-byte `len` field indicates the number of bytes in the immediately following field. @@ -283,9 +310,9 @@ application level. Such messages also allow obfuscation of traffic patterns. 1. type: 18 (`ping`) 2. data: - * [`2`:`num_pong_bytes`] - * [`2`:`byteslen`] - * [`byteslen`:`ignored`] + * [`u16`:`num_pong_bytes`] + * [`u16`:`byteslen`] + * [`byteslen*byte`:`ignored`] The `pong` message is to be sent whenever a `ping` message is received. It serves as a reply and also serves to keep the connection alive, while @@ -295,8 +322,8 @@ included within the data payload of the `pong` message. 1. type: 19 (`pong`) 2. data: - * [`2`:`byteslen`] - * [`byteslen`:`ignored`] + * [`u16`:`byteslen`] + * [`byteslen*byte`:`ignored`] #### Requirements diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 775426e8f..b05cb1d1b 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -6,6 +6,7 @@ operation, and closing. # Table of Contents * [Channel](#channel) + * [Definition of `channel_id`](#definition-of-channel-id) * [Channel Establishment](#channel-establishment) * [The `open_channel` Message](#the-open_channel-message) * [The `accept_channel` Message](#the-accept_channel-message) @@ -28,6 +29,27 @@ operation, and closing. # Channel +## Definition of `channel_id` + +Some messages use a `channel_id` to identify the channel. It's +derived from the funding transaction by combining the `funding_txid` +and the `funding_output_index`, using big-endian exclusive-OR +(i.e. `funding_output_index` alters the last 2 bytes). + +Prior to channel establishment, a `temporary_channel_id` is used, +which is a random nonce. + +Note that as duplicate `temporary_channel_id`s may exist from different +peers, APIs which reference channels by their channel id before the funding +transaction is created are inherently unsafe. The only protocol-provided +identifier for a channel before funding_created has been exchanged is the +(source_node_id, destination_node_id, temporary_channel_id) tuple. Note that +any such APIs which reference channels by their channel id before the funding +transaction is confirmed are also not persistent - until you know the script +pubkey corresponding to the funding output nothing prevents duplicative channel +ids. + + ## Channel Establishment After authenticating and initializing a connection ([BOLT #8](08-transport.md) @@ -83,26 +105,26 @@ the funding transaction and both versions of the commitment transaction. 1. type: 32 (`open_channel`) 2. data: - * [`32`:`chain_hash`] - * [`32`:`temporary_channel_id`] - * [`8`:`funding_satoshis`] - * [`8`:`push_msat`] - * [`8`:`dust_limit_satoshis`] - * [`8`:`max_htlc_value_in_flight_msat`] - * [`8`:`channel_reserve_satoshis`] - * [`8`:`htlc_minimum_msat`] - * [`4`:`feerate_per_kw`] - * [`2`:`to_self_delay`] - * [`2`:`max_accepted_htlcs`] - * [`33`:`funding_pubkey`] - * [`33`:`revocation_basepoint`] - * [`33`:`payment_basepoint`] - * [`33`:`delayed_payment_basepoint`] - * [`33`:`htlc_basepoint`] - * [`33`:`first_per_commitment_point`] - * [`1`:`channel_flags`] - * [`2`:`shutdown_len`] (`option_upfront_shutdown_script`) - * [`shutdown_len`:`shutdown_scriptpubkey`] (`option_upfront_shutdown_script`) + * [`chain_hash`:`chain_hash`] + * [`32*byte`:`temporary_channel_id`] + * [`u64`:`funding_satoshis`] + * [`u64`:`push_msat`] + * [`u64`:`dust_limit_satoshis`] + * [`u64`:`max_htlc_value_in_flight_msat`] + * [`u64`:`channel_reserve_satoshis`] + * [`u64`:`htlc_minimum_msat`] + * [`u32`:`feerate_per_kw`] + * [`u16`:`to_self_delay`] + * [`u16`:`max_accepted_htlcs`] + * [`point`:`funding_pubkey`] + * [`point`:`revocation_basepoint`] + * [`point`:`payment_basepoint`] + * [`point`:`delayed_payment_basepoint`] + * [`point`:`htlc_basepoint`] + * [`point`:`first_per_commitment_point`] + * [`byte`:`channel_flags`] + * [`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. @@ -242,18 +264,6 @@ are above both `dust_limit_satoshis`. Details for how to handle a channel failure can be found in [BOLT 5:Failing a Channel](05-onchain.md#failing-a-channel). -#### Practical Considerations for temporary_channel_id - -Note that as duplicate `temporary_channel_id`s may exist from different -peers, APIs which reference channels by their channel id before the funding -transaction is created are inherently unsafe. The only protocol-provided -identifier for a channel before funding_created has been exchanged is the -(source_node_id, destination_node_id, temporary_channel_id) tuple. Note that -any such APIs which reference channels by their channel id before the funding -transaction is confirmed are also not persistent - until you know the script -pubkey corresponding to the funding output nothing prevents duplicative channel -ids. - #### Future It would be easy to have a local feature bit which indicated that a @@ -268,22 +278,22 @@ funding transaction and both versions of the commitment transaction. 1. type: 33 (`accept_channel`) 2. data: - * [`32`:`temporary_channel_id`] - * [`8`:`dust_limit_satoshis`] - * [`8`:`max_htlc_value_in_flight_msat`] - * [`8`:`channel_reserve_satoshis`] - * [`8`:`htlc_minimum_msat`] - * [`4`:`minimum_depth`] - * [`2`:`to_self_delay`] - * [`2`:`max_accepted_htlcs`] - * [`33`:`funding_pubkey`] - * [`33`:`revocation_basepoint`] - * [`33`:`payment_basepoint`] - * [`33`:`delayed_payment_basepoint`] - * [`33`:`htlc_basepoint`] - * [`33`:`first_per_commitment_point`] - * [`2`:`shutdown_len`] (`option_upfront_shutdown_script`) - * [`shutdown_len`:`shutdown_scriptpubkey`] (`option_upfront_shutdown_script`) + * [`32*byte`:`temporary_channel_id`] + * [`u64`:`dust_limit_satoshis`] + * [`u64`:`max_htlc_value_in_flight_msat`] + * [`u64`:`channel_reserve_satoshis`] + * [`u64`:`htlc_minimum_msat`] + * [`u32`:`minimum_depth`] + * [`u16`:`to_self_delay`] + * [`u16`:`max_accepted_htlcs`] + * [`point`:`funding_pubkey`] + * [`point`:`revocation_basepoint`] + * [`point`:`payment_basepoint`] + * [`point`:`delayed_payment_basepoint`] + * [`point`:`htlc_basepoint`] + * [`point`:`first_per_commitment_point`] + * [`u16`:`shutdown_len`] (`option_upfront_shutdown_script`) + * [`shutdown_len*byte`:`shutdown_scriptpubkey`] (`option_upfront_shutdown_script`) #### Requirements @@ -313,10 +323,10 @@ signature, via `funding_signed`, it will broadcast the funding transaction. 1. type: 34 (`funding_created`) 2. data: - * [`32`:`temporary_channel_id`] - * [`32`:`funding_txid`] - * [`2`:`funding_output_index`] - * [`64`:`signature`] + * [`32*byte`:`temporary_channel_id`] + * [`sha256`:`funding_txid`] + * [`u16`:`funding_output_index`] + * [`signature`:`signature`] #### Requirements @@ -351,8 +361,8 @@ This message introduces the `channel_id` to identify the channel. It's derived f 1. type: 35 (`funding_signed`) 2. data: - * [`32`:`channel_id`] - * [`64`:`signature`] + * [`channel_id`:`channel_id`] + * [`signature`:`signature`] #### Requirements @@ -373,8 +383,8 @@ This message indicates that the funding transaction has reached the `minimum_dep 1. type: 36 (`funding_locked`) 2. data: - * [`32`:`channel_id`] - * [`33`:`next_per_commitment_point`] + * [`channel_id`:`channel_id`] + * [`point`:`next_per_commitment_point`] #### Requirements @@ -437,9 +447,9 @@ along with the `scriptpubkey` it wants to be paid to. 1. type: 38 (`shutdown`) 2. data: - * [`32`:`channel_id`] - * [`2`:`len`] - * [`len`:`scriptpubkey`] + * [`channel_id`:`channel_id`] + * [`u16`:`len`] + * [`len*byte`:`scriptpubkey`] #### Requirements @@ -513,9 +523,9 @@ the channel. 1. type: 39 (`closing_signed`) 2. data: - * [`32`:`channel_id`] - * [`8`:`fee_satoshis`] - * [`64`:`signature`] + * [`channel_id`:`channel_id`] + * [`u64`:`fee_satoshis`] + * [`signature`:`signature`] #### Requirements @@ -766,12 +776,12 @@ is destined, is described in [BOLT #4](04-onion-routing.md). 1. type: 128 (`update_add_htlc`) 2. data: - * [`32`:`channel_id`] - * [`8`:`id`] - * [`8`:`amount_msat`] - * [`32`:`payment_hash`] - * [`4`:`cltv_expiry`] - * [`1366`:`onion_routing_packet`] + * [`channel_id`:`channel_id`] + * [`u64`:`id`] + * [`u64`:`amount_msat`] + * [`sha256`:`payment_hash`] + * [`u32`:`cltv_expiry`] + * [`1366*byte`:`onion_routing_packet`] #### Requirements @@ -855,18 +865,18 @@ To supply the preimage: 1. type: 130 (`update_fulfill_htlc`) 2. data: - * [`32`:`channel_id`] - * [`8`:`id`] - * [`32`:`payment_preimage`] + * [`channel_id`:`channel_id`] + * [`u64`:`id`] + * [`32*byte`:`payment_preimage`] For a timed out or route-failed HTLC: 1. type: 131 (`update_fail_htlc`) 2. data: - * [`32`:`channel_id`] - * [`8`:`id`] - * [`2`:`len`] - * [`len`:`reason`] + * [`channel_id`:`channel_id`] + * [`u64`:`id`] + * [`u16`:`len`] + * [`len*byte`:`reason`] The `reason` field is an opaque encrypted blob for the benefit of the original HTLC initiator, as defined in [BOLT #4](04-onion-routing.md); @@ -878,10 +888,10 @@ For an unparsable HTLC: 1. type: 135 (`update_fail_malformed_htlc`) 2. data: - * [`32`:`channel_id`] - * [`8`:`id`] - * [`32`:`sha256_of_onion`] - * [`2`:`failure_code`] + * [`channel_id`:`channel_id`] + * [`u64`:`id`] + * [`sha256`:`sha256_of_onion`] + * [`u16`:`failure_code`] #### Requirements @@ -936,10 +946,10 @@ sign the resulting transaction (as defined in [BOLT #3](03-transactions.md)), an 1. type: 132 (`commitment_signed`) 2. data: - * [`32`:`channel_id`] - * [`64`:`signature`] - * [`2`:`num_htlcs`] - * [`num_htlcs*64`:`htlc_signature`] + * [`channel_id`:`channel_id`] + * [`signature`:`signature`] + * [`u16`:`num_htlcs`] + * [`num_htlcs*signature`:`htlc_signature`] #### Requirements @@ -997,9 +1007,9 @@ The description of key derivation is in [BOLT #3](03-transactions.md#key-derivat 1. type: 133 (`revoke_and_ack`) 2. data: - * [`32`:`channel_id`] - * [`32`:`per_commitment_secret`] - * [`33`:`next_per_commitment_point`] + * [`channel_id`:`channel_id`] + * [`32*byte`:`per_commitment_secret`] + * [`point`:`next_per_commitment_point`] #### Requirements @@ -1041,8 +1051,8 @@ given in [BOLT #3](03-transactions.md#fee-calculation). 1. type: 134 (`update_fee`) 2. data: - * [`32`:`channel_id`] - * [`4`:`feerate_per_kw`] + * [`channel_id`:`channel_id`] + * [`u32`:`feerate_per_kw`] #### Requirements @@ -1104,11 +1114,11 @@ messages are), they are independent of requirements here. 1. type: 136 (`channel_reestablish`) 2. data: - * [`32`:`channel_id`] - * [`8`:`next_local_commitment_number`] - * [`8`:`next_remote_revocation_number`] - * [`32`:`your_last_per_commitment_secret`] (option_data_loss_protect) - * [`33`:`my_current_per_commitment_point`] (option_data_loss_protect) + * [`channel_id`:`channel_id`] + * [`u64`:`next_local_commitment_number`] + * [`u64`:`next_remote_revocation_number`] + * [`32*byte`:`your_last_per_commitment_secret`] (option_data_loss_protect) + * [`point`:`my_current_per_commitment_point`] (option_data_loss_protect) `next_local_commitment_number`: A commitment number is a 48-bit incrementing counter for each commitment transaction; counters diff --git a/04-onion-routing.md b/04-onion-routing.md index f6e63af3f..e7c668c89 100644 --- a/04-onion-routing.md +++ b/04-onion-routing.md @@ -153,10 +153,10 @@ The overall structure of the packet is as follows: 1. type: `onion_packet` 2. data: - * [`1`:`version`] - * [`33`:`public_key`] - * [`20*65`:`hops_data`] - * [`32`:`hmac`] + * [`byte`:`version`] + * [`point`:`public_key`] + * [`1300*byte`:`hops_data`] + * [`32*byte`:`hmac`] For this specification (_version 0_), `version` has a constant value of `0x00`. @@ -166,9 +166,9 @@ and has the following structure: 1. type: `hops_data` 2. data: - * [`1`:`realm`] - * [`32`:`per_hop`] - * [`32`:`HMAC`] + * [`byte`:`realm`] + * [`32*byte`:`per_hop`] + * [`32*byte`:`HMAC`] * ... * `filler` @@ -183,10 +183,10 @@ The `realm` byte determines the format of the `per_hop` field; currently, only ` 1. type: `per_hop` (for `realm` 0) 2. data: - * [`8`:`short_channel_id`] - * [`8`:`amt_to_forward`] - * [`4`:`outgoing_cltv_value`] - * [`12`:`padding`] + * [`short_channel_id`:`short_channel_id`] + * [`u64`:`amt_to_forward`] + * [`u32`:`outgoing_cltv_value`] + * [`12*byte`:`padding`] Using the `per_hop` field, the origin node is able to precisely specify the path and structure of the HTLCs forwarded at each hop. As the `per_hop` is protected @@ -637,11 +637,11 @@ The node generating the error message (_erring node_) builds a return packet consisting of the following fields: 1. data: - * [`32`:`hmac`] - * [`2`:`failure_len`] - * [`failure_len`:`failuremsg`] - * [`2`:`pad_len`] - * [`pad_len`:`pad`] + * [`32*byte`:`hmac`] + * [`u16`:`failure_len`] + * [`failure_len*byte`:`failuremsg`] + * [`u16`:`pad_len`] + * [`pad_len*byte`:`pad`] Where `hmac` is an HMAC authenticating the remainder of the packet, with a key generated using the above process, with key type `um`, `failuremsg` as defined @@ -726,26 +726,26 @@ The processing node has a required feature which was not in this onion. 1. type: BADONION|PERM|4 (`invalid_onion_version`) 2. data: - * [`32`:`sha256_of_onion`] + * [`sha256`:`sha256_of_onion`] The `version` byte was not understood by the processing node. 1. type: BADONION|PERM|5 (`invalid_onion_hmac`) 2. data: - * [`32`:`sha256_of_onion`] + * [`sha256`:`sha256_of_onion`] The HMAC of the onion was incorrect when it reached the processing node. 1. type: BADONION|PERM|6 (`invalid_onion_key`) 2. data: - * [`32`:`sha256_of_onion`] + * [`sha256`:`sha256_of_onion`] The ephemeral key was unparsable by the processing node. 1. type: UPDATE|7 (`temporary_channel_failure`) 2. data: - * [`2`:`len`] - * [`len`:`channel_update`] + * [`u16`:`len`] + * [`len*byte`:`channel_update`] The channel from the processing node was unable to handle this HTLC, but may be able to handle it, or others, later. @@ -766,27 +766,27 @@ leading from the processing node. 1. type: UPDATE|11 (`amount_below_minimum`) 2. data: - * [`8`:`htlc_msat`] - * [`2`:`len`] - * [`len`:`channel_update`] + * [`u64`:`htlc_msat`] + * [`u16`:`len`] + * [`len*byte`:`channel_update`] The HTLC amount was below the `htlc_minimum_msat` of the channel from the processing node. 1. type: UPDATE|12 (`fee_insufficient`) 2. data: - * [`8`:`htlc_msat`] - * [`2`:`len`] - * [`len`:`channel_update`] + * [`u64`:`htlc_msat`] + * [`u16`:`len`] + * [`len*byte`:`channel_update`] The fee amount was below that required by the channel from the processing node. 1. type: UPDATE|13 (`incorrect_cltv_expiry`) 2. data: - * [`4`:`cltv_expiry`] - * [`2`:`len`] - * [`len`:`channel_update`] + * [`u32`:`cltv_expiry`] + * [`u16`:`len`] + * [`len*byte`:`channel_update`] The `cltv_expiry` does not comply with the `cltv_expiry_delta` required by the channel from the processing node: it does not satisfy the following @@ -796,15 +796,15 @@ requirement: 1. type: UPDATE|14 (`expiry_too_soon`) 2. data: - * [`2`:`len`] - * [`len`:`channel_update`] + * [`u16`:`len`] + * [`len*byte`:`channel_update`] The CLTV expiry is too close to the current block height for safe handling by the processing node. 1. type: PERM|15 (`incorrect_or_unknown_payment_details`) 2. data: - * [`8`:`htlc_msat`] + * [`u64`:`htlc_msat`] The `payment_hash` is unknown to the final node or the amount for that `payment_hash` is incorrect. @@ -823,21 +823,21 @@ handling by the final node. 1. type: 18 (`final_incorrect_cltv_expiry`) 2. data: - * [`4`:`cltv_expiry`] + * [`u32`:`cltv_expiry`] The CLTV expiry in the HTLC doesn't match the value in the onion. 1. type: 19 (`final_incorrect_htlc_amount`) 2. data: - * [`8`:`incoming_htlc_amt`] + * [`u64`:`incoming_htlc_amt`] The amount in the HTLC doesn't match the value in the onion. 1. type: UPDATE|20 (`channel_disabled`) 2. data: - * [`2`: `flags`] - * [`2`:`len`] - * [`len`:`channel_update`] + * [`u16`: `flags`] + * [`u16`:`len`] + * [`len*byte`:`channel_update`] The channel from the processing node has been disabled. diff --git a/07-routing-gossip.md b/07-routing-gossip.md index 80116eef2..97363454e 100644 --- a/07-routing-gossip.md +++ b/07-routing-gossip.md @@ -20,6 +20,7 @@ multiple `node_announcement` messages, in order to update the node information. # Table of Contents + * [Definition of `short_channel_id`](#definition-of-short-channel-id) * [The `announcement_signatures` Message](#the-announcement_signatures-message) * [The `channel_announcement` Message](#the-channel_announcement-message) * [The `node_announcement` Message](#the-node_announcement-message) @@ -32,24 +33,7 @@ multiple `node_announcement` messages, in order to update the node information. * [Recommendations for Routing](#recommendations-for-routing) * [References](#references) -## The `announcement_signatures` Message - -This is a direct message between the two endpoints of a channel and serves as an opt-in mechanism to allow the announcement of the channel to the rest of the network. -It contains the necessary signatures, by the sender, to construct the `channel_announcement` message. - -1. type: 259 (`announcement_signatures`) -2. data: - * [`32`:`channel_id`] - * [`8`:`short_channel_id`] - * [`64`:`node_signature`] - * [`64`:`bitcoin_signature`] - -The willingness of the initiating node to announce the channel is signaled during channel opening by setting the `announce_channel` bit in `channel_flags` (see [BOLT #2](02-peer-protocol.md#the-open_channel-message)). - -### Requirements - -The `announcement_signatures` message is created by constructing a `channel_announcement` message, corresponding to the newly established channel, and signing it with the secrets matching an endpoint's `node_id` and `bitcoin_key`. After it's signed, the -`announcement_signatures` message may be sent. +## Definition of `short_channel_id` The `short_channel_id` is the unique description of the funding transaction. It is constructed as follows: @@ -66,6 +50,25 @@ For example, a `short_channel_id` might be written as `539268x845x1`, indicating a channel on the output 1 of the transaction at index 845 of the block at height 539268. +## The `announcement_signatures` Message + +This is a direct message between the two endpoints of a channel and serves as an opt-in mechanism to allow the announcement of the channel to the rest of the network. +It contains the necessary signatures, by the sender, to construct the `channel_announcement` message. + +1. type: 259 (`announcement_signatures`) +2. data: + * [`channel_id`:`channel_id`] + * [`short_channel_id`:`short_channel_id`] + * [`signature`:`node_signature`] + * [`signature`:`bitcoin_signature`] + +The willingness of the initiating node to announce the channel is signaled during channel opening by setting the `announce_channel` bit in `channel_flags` (see [BOLT #2](02-peer-protocol.md#the-open_channel-message)). + +### Requirements + +The `announcement_signatures` message is created by constructing a `channel_announcement` message, corresponding to the newly established channel, and signing it with the secrets matching an endpoint's `node_id` and `bitcoin_key`. After it's signed, the +`announcement_signatures` message may be sent. + A node: - if the `open_channel` message has the `announce_channel` bit set AND a `shutdown` message has not been sent: - MUST send the `announcement_signatures` message. @@ -135,18 +138,18 @@ announcement message: this is accomplished by having a signature from each 1. type: 256 (`channel_announcement`) 2. data: - * [`64`:`node_signature_1`] - * [`64`:`node_signature_2`] - * [`64`:`bitcoin_signature_1`] - * [`64`:`bitcoin_signature_2`] - * [`2`:`len`] - * [`len`:`features`] - * [`32`:`chain_hash`] - * [`8`:`short_channel_id`] - * [`33`:`node_id_1`] - * [`33`:`node_id_2`] - * [`33`:`bitcoin_key_1`] - * [`33`:`bitcoin_key_2`] + * [`signature`:`node_signature_1`] + * [`signature`:`node_signature_2`] + * [`signature`:`bitcoin_signature_1`] + * [`signature`:`bitcoin_signature_2`] + * [`u16`:`len`] + * [`len*byte`:`features`] + * [`chain_hash`:`chain_hash`] + * [`short_channel_id`:`short_channel_id`] + * [`point`:`node_id_1`] + * [`point`:`node_id_2`] + * [`point`:`bitcoin_key_1`] + * [`point`:`bitcoin_key_2`] ### Requirements @@ -247,15 +250,15 @@ nodes not associated with an already known channel are ignored. 1. type: 257 (`node_announcement`) 2. data: - * [`64`:`signature`] - * [`2`:`flen`] - * [`flen`:`features`] - * [`4`:`timestamp`] - * [`33`:`node_id`] - * [`3`:`rgb_color`] - * [`32`:`alias`] - * [`2`:`addrlen`] - * [`addrlen`:`addresses`] + * [`signature`:`signature`] + * [`u16`:`flen`] + * [`flen*byte`:`features`] + * [`u32`:`timestamp`] + * [`point`:`node_id`] + * [`3*byte`:`rgb_color`] + * [`32*byte`:`alias`] + * [`u16`:`addrlen`] + * [`addrlen*byte`:`addresses`] `timestamp` allows for the ordering of messages, in the case of multiple announcements. `rgb_color` and `alias` allow intelligence services to assign @@ -391,17 +394,17 @@ of *relaying* payments, not *sending* payments. When making a payment 1. type: 258 (`channel_update`) 2. data: - * [`64`:`signature`] - * [`32`:`chain_hash`] - * [`8`:`short_channel_id`] - * [`4`:`timestamp`] - * [`1`:`message_flags`] - * [`1`:`channel_flags`] - * [`2`:`cltv_expiry_delta`] - * [`8`:`htlc_minimum_msat`] - * [`4`:`fee_base_msat`] - * [`4`:`fee_proportional_millionths`] - * [`8`:`htlc_maximum_msat`] (option_channel_htlc_max) + * [`signature`:`signature`] + * [`chain_hash`:`chain_hash`] + * [`short_channel_id`:`short_channel_id`] + * [`u32`:`timestamp`] + * [`byte`:`message_flags`] + * [`byte`:`channel_flags`] + * [`u16`:`cltv_expiry_delta`] + * [`u64`:`htlc_minimum_msat`] + * [`u32`:`fee_base_msat`] + * [`u32`:`fee_proportional_millionths`] + * [`u64`:`htlc_maximum_msat`] (option_channel_htlc_max) The `channel_flags` bitfield is used to indicate the direction of the channel: it identifies the node that this update originated from and signals various options @@ -563,14 +566,14 @@ contents could decompress to more then 3669960 bytes. 1. type: 261 (`query_short_channel_ids`) (`gossip_queries`) 2. data: - * [`32`:`chain_hash`] - * [`2`:`len`] - * [`len`:`encoded_short_ids`] + * [`chain_hash`:`chain_hash`] + * [`u16`:`len`] + * [`len*byte`:`encoded_short_ids`] 1. type: 262 (`reply_short_channel_ids_end`) (`gossip_queries`) 2. data: - * [`32`:`chain_hash`] - * [`1`:`complete`] + * [`chain_hash`:`chain_hash`] + * [`byte`:`complete`] This is a general mechanism which lets a node query for the `channel_announcement` and `channel_update` messages for specific channels @@ -624,18 +627,18 @@ timeouts. It also causes a natural ratelimiting of queries. 1. type: 263 (`query_channel_range`) (`gossip_queries`) 2. data: - * [`32`:`chain_hash`] - * [`4`:`first_blocknum`] - * [`4`:`number_of_blocks`] + * [`chain_hash`:`chain_hash`] + * [`u32`:`first_blocknum`] + * [`u32`:`number_of_blocks`] 1. type: 264 (`reply_channel_range`) (`gossip_queries`) 2. data: - * [`32`:`chain_hash`] - * [`4`:`first_blocknum`] - * [`4`:`number_of_blocks`] - * [`1`:`complete`] - * [`2`:`len`] - * [`len`:`encoded_short_ids`] + * [`chain_hash`:`chain_hash`] + * [`u32`:`first_blocknum`] + * [`u32`:`number_of_blocks`] + * [`byte`:`complete`] + * [`u16`:`len`] + * [`len*byte`:`encoded_short_ids`] This allows a query for channels within specific blocks. @@ -674,9 +677,9 @@ which overlaps the ranges of the request. 1. type: 265 (`gossip_timestamp_filter`) (`gossip_queries`) 2. data: - * [`32`:`chain_hash`] - * [`4`:`first_timestamp`] - * [`4`:`timestamp_range`] + * [`chain_hash`:`chain_hash`] + * [`u32`:`first_timestamp`] + * [`u32`:`timestamp_range`] This message allows a node to constrain future gossip messages to a specific range. A node which wants any gossip messages would have diff --git a/tools/extract-formats.py b/tools/extract-formats.py index 2667f20db..1b6a754e8 100755 --- a/tools/extract-formats.py +++ b/tools/extract-formats.py @@ -3,94 +3,207 @@ # Released by Rusty Russell under CC0: # https://creativecommons.org/publicdomain/zero/1.0/ +# Outputs: +# +# Standard message types: +# msgtype,,[,