Skip to content
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

Jump to bottom

BOLT #7: Make channel_update always have htlc_maximum_msat. #996

Closed
wants to merge 2 commits into from
Closed

BOLT #7: Make channel_update always have htlc_maximum_msat. #996

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
466317a
BOLT #7: Make channel_update always have htlc_maximum_msat.
rustyrussell May 31, 2022
f99b549
BOLT #7: rename `message_flags` to `must_be_one`.
rustyrussell Jun 1, 2022
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
47 changes: 13 additions & 34 deletions 07-routing-gossip.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -407,13 +407,13 @@ of *relaying* payments, not *sending* payments. When making a payment
* [`chain_hash`:`chain_hash`]
* [`short_channel_id`:`short_channel_id`]
* [`u32`:`timestamp`]
* [`byte`:`message_flags`]
* [`byte`:`must_be_one`]
* [`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)
* [`u64`:`htlc_maximum_msat`]

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
Expand All @@ -425,19 +425,6 @@ individual bits:
| 0 | `direction` | Direction this update refers to. |
| 1 | `disable` | Disable the channel. |

The `message_flags` bitfield is used to indicate the presence of optional
fields in the `channel_update` message:

| Bit Position | Name | Field |
| ------------- | ------------------------- | -------------------------------- |
| 0 | `option_channel_htlc_max` | `htlc_maximum_msat` |

Note that the `htlc_maximum_msat` field is static in the current
t-bast marked this conversation as resolved.
Show resolved Hide resolved
protocol over the life of the channel: it is *not* designed to be
indicative of real-time channel capacity in each direction, which
would be both a massive data leak and uselessly spam the network (it
takes an average of 30 seconds for gossip to propagate each hop).

The `node_id` for the signature verification is taken from the corresponding
`channel_announcement`: `node_id_1` if the least-significant bit of flags is 0
or `node_id_2` otherwise.
Expand All @@ -462,15 +449,12 @@ The origin node:
- MUST set the `direction` bit of `channel_flags` to 0.
- otherwise:
- MUST set the `direction` bit of `channel_flags` to 1.
- if the `htlc_maximum_msat` field is present:
- MUST set the `option_channel_htlc_max` bit of `message_flags` to 1.
- MUST set `htlc_maximum_msat` to the maximum value it will send through this channel for a single HTLC.
- MUST set this to less than or equal to the channel capacity.
- MUST set this to less than or equal to `max_htlc_value_in_flight_msat`
it received from the peer.
- otherwise:
- MUST set the `option_channel_htlc_max` bit of `message_flags` to 0.
- MUST set bits in `channel_flags` and `message_flags `that are not assigned a meaning to 0.
- MUST set `must_be_one` to 1.
- MUST set `htlc_maximum_msat` to the maximum value it will send through this channel for a single HTLC.
- MUST set this to less than or equal to the channel capacity.
- MUST set this to less than or equal to `max_htlc_value_in_flight_msat`
it received from the peer.
- MUST set bits in `channel_flags`that are not assigned a meaning to 0.
- MAY create and send a `channel_update` with the `disable` bit set to 1, to
signal a channel's temporary unavailability (e.g. due to a loss of
connectivity) OR permanent unavailability (e.g. prior to an on-chain
Expand Down Expand Up @@ -521,10 +505,7 @@ The receiving node:
- otherwise:
- SHOULD queue the message for rebroadcasting.
- MAY choose NOT to for messages longer than the minimum expected length.
- if the `option_channel_htlc_max` bit of `message_flags` is 0:
- MUST consider `htlc_maximum_msat` not to be present.
- otherwise:
- if `htlc_maximum_msat` is not present or greater than channel capacity:
- if `htlc_maximum_msat` is greater than channel capacity:
- MAY blacklist this `node_id`
- SHOULD ignore this channel during route considerations.
- otherwise:
Expand All @@ -549,12 +530,6 @@ message can rebroadcast it just by changing the `s` component of signature with
This should however not result in the blacklist of the `node_id` from where
the message originated.

The explicit `option_channel_htlc_max` flag to indicate the presence
of `htlc_maximum_msat` (rather than having `htlc_maximum_msat` implied
by the message length) allows us to extend the `channel_update`
with different fields in future. Since channels are limited to 2^32-1
millisatoshis in Bitcoin, the `htlc_maximum_msat` has the same restriction.

The recommendation against redundant `channel_update`s minimizes spamming the network,
however it is sometimes inevitable. For example, a channel with a
peer which is unreachable will eventually cause a `channel_update` to
Expand All @@ -563,6 +538,10 @@ the channel when the peer reestablishes contact. Because gossip
messages are batched and replace previous ones, the result may be a
single seemingly-redundant update.

The `must_be_one` field was previously used for message flags, and only
the lower bit was defined. It's now a constant value, and ignored by
receivers.

## Query Messages

Negotiating the `gossip_queries` option via `init` enables a number
Expand Down