Skip to content

Commit 2e93a41

Browse files
rustyrussellrustyrussell
committed
BOLT lightning#7: More complex proposal, using three separate message types.
Contents stolen from Christian's draft. Signed-off-by: Rusty Russell <[email protected]>
1 parent a15f3f9 commit 2e93a41

File tree

2 files changed

+262
-0
lines changed

2 files changed

+262
-0
lines changed

‎02-peer-protocol.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -229,6 +229,7 @@ This message indicates that the funding transaction has reached the `minimum-dep
229229
* [8:temporary-channel-id]
230230
* [8:channel-id]
231231
* [33:next-per-commitment-point]
232+
* [33:announcement-signature]
232233

233234
The `channel-id` is the unique description of the funding transaction.
234235
It is constructed with the most significant 3 bytes as the block
@@ -239,10 +240,19 @@ index which pays to the channel.
239240
This `channel-id` is used in all messages referring to the channel
240241
from this point onwards.
241242

243+
`announcement-signature` is the optional signature for `channel_announcement` as described in [BOLT #7](07-routing-gossip.md#the-channel_announcement-message).
244+
242245
#### Requirements
243246

244247
FIXME: Describe
245248

249+
The sender MUST set `announcement-signature` to the signature for the
250+
channel_announcement message, or all zeroes if it does not want the
251+
channel announced.
252+
253+
The recipient SHOULD queue the `channel_announcement` message for its
254+
peers if it has sent and received a non-zero `announcement-signature`.
255+
246256
#### Future
247257

248258
We could add an SPV proof, and route block hashes in separate

‎07-routing-gossip.md

Lines changed: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,252 @@
1+
# BOLT #7: P2P Node and Channel Discovery
2+
3+
This specification describes simple node discovery, channel discovery and channel update mechanisms which do not rely on a third-party to disseminate the information.
4+
5+
Node and channel discovery serve two different purposes:
6+
7+
- Channel discovery allows the creation and maintenance of a local view of the network's topology such that the node can discover routes to desired destination.
8+
- Node discovery allows nodes to broadcast their ID, host and port, such that other nodes can open connections and establish payment channels.
9+
10+
Peers in the network exchange `channel_announcement` messages that contain information about new channels between two nodes. They can also exchange `node_announcement` messages which supply additional information about nodes, and `channel_update` messages which update information about a channel.
11+
12+
There can only be one valid `channel_announcement` for any channel,
13+
but multiple `node_announcement` messages are possible (to update node
14+
information), and at least two `channel_update` messages are expected.
15+
16+
## The `channel_announcement` message
17+
18+
This message contains ownership information about a channel. It ties each
19+
on-chain bitcoin key to the lightning node key, and vice-versa.
20+
21+
The channel is not really usable until at least one side has announced
22+
its fee levels and expiry using `channel_update`.
23+
24+
1. type: 256 (`MSG_CHANNEL_ANNOUNCEMENT`)
25+
2. data:
26+
* [4:blockheight]
27+
* [3:blockindex]
28+
* [1:outputindex]
29+
* [33:node-id-1]
30+
* [33:node-id-2]
31+
* [33:bitcoin-key-1]
32+
* [33:bitcoin-key-2]
33+
* [64:bitcoin-signature-1]
34+
* [64:bitcoin-signature-2]
35+
* [64:node-signature-1]
36+
* [64:node-signature-2]
37+
38+
### Requirements
39+
40+
The creating node MUST set `blockheight` to the block number
41+
containing the confirmed funding transaction, `blockindex` to the
42+
transaction number within the block, and `outputindex` to the output
43+
number which funds the channel. The corresponding output MUST be a
44+
P2WSH as described in [BOLT #3](03-transactions.md#funding-transaction-output).
45+
46+
The creating node MUST set `node-id-1` and `node-id-2` to the public
47+
keys of the two nodes who are operating the channel, such that
48+
`node-id-1` is the numerically-lesser of the two DER encoded keys.
49+
ascending numerical order, and MUST set `bitcoin-key-1` and
50+
`bitcoin-key-2` to `funding-pubkey`s of `node-id-1` and `node-id-2`
51+
respectively.
52+
53+
The creating node MUST set `bitcoin-signature-1` to the signature of
54+
the double-SHA of `node-id-1` using `bitcoin-key-1`, and set
55+
`bitcoin-signature-2` to the signature of the double-SHA of
56+
`node-id-2` using `bitcoin-key-2`
57+
58+
The creating node MUST set `node-signature-1` to the signature of the
59+
double-SHA of every data field up to and including
60+
`bitcoin-signature-2` using `node-id-1`, and `node-signature-2` to the
61+
signature of the double-SHA of every data field up to and including
62+
`bitcoin-signature-2` using `node-id-2`.
63+
64+
The receiving node MUST ignore the message if the output `outputindex`
65+
in block `blockheight` transaction number `blockindex` does not
66+
correspond to a P2WSH using `bitcoin-key-1` and `bitcoin-key-2` as
67+
specified in [BOLT #3](03-transactions.md#funding-transaction-output).
68+
The receiving node MUST ignore the message if this output is spent.
69+
70+
Otherwise, the receiving node SHOULD fail the connection if
71+
`bitcoin-signature-1`, `bitcoin-signature-2`, `node-signature-1` or
72+
`node-signature-2` are invalid or not correct.
73+
74+
Otherwise, if `node-id-1` or `node-id-2` are blacklisted, it SHOULD
75+
ignore the message.
76+
77+
Otherwise, if the transaction referred to was not previously announced
78+
as a channel, the receiving node SHOULD queue the message for
79+
rebroadcasting. If it has previously received a valid
80+
`channel_announcement` for the same transaction in the same block, but
81+
different `node-id-1` or `node-id-2`, it SHOULD blacklist the the
82+
previous message's `node-id-1` and `node-id-2` as well as this
83+
`node-id-1` and `node-id-2` and forget channels conntected to them,
84+
otherwise it SHOULD store this `channel_announcement`.
85+
86+
The receiving node SHOULD forget a channel once its funding output has
87+
been spent or reorganized out.
88+
89+
## Rationale
90+
91+
Requiring both nodes to sign indicates they are both willing to route
92+
other payments via this node (ie. take part of the public network).
93+
Requiring the bitcoin signatures proves they control the channel.
94+
95+
The blacklisting of conflicting nodes means that we disallow multiple
96+
different announcements: no node should ever do this, as it implies
97+
that keys have leaked.
98+
99+
While channels shouldn't be advertised before they are sufficiently
100+
deep, the requirement against rebroadcasting only applies if the
101+
transaction hasn't moved to a different block.
102+
103+
## The `node_announcement` message
104+
105+
This allows a node to indicate extra data associated with it, in
106+
addition to its public key. To avoid trivial denial of service attacks,
107+
nodes for which a channel is not already known are ignored.
108+
109+
1. type: 257 (`MSG_NODE_ANNOUNCEMENT`)
110+
2. data:
111+
* [64:signature]
112+
* [4:timestamp]
113+
* [16:ipv6]
114+
* [2:port]
115+
* [33:node-id]
116+
* [3:rgb-color]
117+
* [2:pad]
118+
* [4:len]
119+
* [len:alias]
120+
121+
The `timestamp` allows ordering in the case of multiple announcements;
122+
the `ipv6` and `port` allow the node to announce its willingness to
123+
accept incoming network connections, the `rgb-color` and `alias` allow
124+
intelligence services to give their nodes cool monikers like IRATEMONK
125+
and WISTFULTOLL and use the color black.
126+
127+
### Requirements
128+
129+
The creating node MUST set `timestamp` to be greater than any previous
130+
`node_announcement` it has created. It MAY base it on a UNIX
131+
timestamp. It MUST set the `ipv6` and `port` fields to all zeroes, or
132+
a non-zero `port` and `ipv6` set to a valid IPv6 address or an IPv4-Mapped IPv6 Address format as defined in [RFC 4291 section 2.5.5.2](https://tools.ietf.org/html/rfc4291#section-2.5.5.2). It MUST set `signature` to the signature of
133+
the double-SHA of the entire remaining packet after `signature` using the
134+
key given by `node-id`. It MUST set `pad` to zero. It MAY set `alias` and `rgb-color` to customize their node's appearance in maps and graphs, where the first byte of `rgb` is the red value, the second byte is the green value and the last byte is the blue value. It MUST set `alias` to a valid UTF-8 string.
135+
136+
The receiving node SHOULD fail the connection if the message is of
137+
insufficent length to contain `alias`.
138+
139+
The receiving node SHOULD fail the connection if `signature` is
140+
invalid or incorrect for the entire message including unknown fields
141+
following `alias`, and MUST NOT further process the message. The
142+
receiving node SHOULD ignore `ipv6` if `port` is zero. It MUST ignore
143+
the contents of `pad`.
144+
145+
The receiving node SHOULD ignore the message if `node-id` is not
146+
previously known from a `channel_announcement` message, or if
147+
`timestamp` is not greater than than the last-received
148+
`node_announcement` from this `node-id`. Otherwise, if the
149+
`timestamp` is greater than the last-received `node_announcement` from
150+
this `node-id` the receiving node SHOULD queue the message for
151+
rebroadcasting.
152+
153+
The receiving node MAY use `rgb` and `alias` to reference nodes in interfaces, but SHOULD insinuate their self-signed origin.
154+
155+
### Rationale
156+
157+
RFC 4291 section 2.5.5.2 described IPv4 addresses like so:
158+
159+
```
160+
| 80 bits | 16 | 32 bits |
161+
+--------------------------------------+--------------------------+
162+
|0000..............................0000|FFFF| IPv4 address |
163+
+--------------------------------------+----+---------------------+
164+
```
165+
166+
## The `channel_update` message
167+
168+
After a channel has been initially announced, each side independently
169+
announces its fees and minimum expiry for HTLCs. It uses the 8-byte
170+
channel shortid which matches the `channel_announcement` and one byte
171+
to indicate which end this is. It can do this multiple times, if
172+
it wants to change fees.
173+
174+
1. type: 258 (`MSG_CHANNEL_UPDATE`)
175+
2. data:
176+
* [64:signature]
177+
* [4:blockheight]
178+
* [3:blockindex]
179+
* [1:outputindex]
180+
* [4:timestamp]
181+
* [1:side]
182+
* [1:pad]
183+
* [2:expiry]
184+
* [4:htlc-minimum-msat]
185+
* [4:fee-base-msat]
186+
* [4:fee-proportional-millionths]
187+
188+
### Requirements
189+
190+
The creating node MUST set `signature` to the signature of the
191+
double-SHA of the entire remaining packet after `signature` using its own `node-id`.
192+
193+
The creating node MUST set `blockheight`, `blockindex` and `outputindex` to
194+
match those in the already-sent `channel_announcement` message, and MUST set `side` to 0 if the creating node is `node-id-1` in that message, otherwise 1.
195+
196+
The creating node MUST set `timestamp` to greater than zero, and MUST set it to greater than any previously-sent `channel_update` for this channel, and MUST set `pad` to zero.
197+
198+
It MUST set `expiry` to the number of blocks it will subtract from an incoming HTLC's `expiry`. It MUST set `htlc-minimum-msat` to the minimum HTLC value it will accept, in millisatoshi. It MUST set `fee-base-msat` to the base fee it will charge for any HTLC, in millisatoshi, and `fee-proportional-millionths` to the amount it will charge per millionth of a satoshi.
199+
200+
The node SHOULD accept HTLCs which pay a fee equal or greater than:
201+
202+
fee-base-msat + htlc-amount-msat * fee-proportional-millionths / 1000000
203+
204+
The receiving node SHOULD fail the connection if `side` is not 0 or 1.
205+
It MUST ignore the contents of `pad`. The receiving node SHOULD fail
206+
the connection if `signature` is invalid or incorrect for the entire
207+
message including unknown fields following `signature`, and MUST NOT
208+
further process the message. The receiving node SHOULD ignore `ipv6`
209+
if `port` is zero. It SHOULD ignore the message if `blockheight`,
210+
`blockindex` and `outputindex` do not correspond to a previously
211+
known, unspent channel from `channel_announcement` or if `timestamp`
212+
is not greater than than the last-received `channel_announcement` for
213+
this channel and `side`. Otherwise, if the `timestamp` is equal to
214+
the last-received `channel_announcement` and the fields other than
215+
`signature` differ, the node MAY blacklist this node-id and forget all
216+
channels associated with it. Otherwise the receiving node SHOULD
217+
queue the message for rebroadcasting.
218+
219+
## Rebroadcasting
220+
221+
Nodes receiving an announcement verify that this is the latest update from the announcing node by comparing the included timestamp and update their local view of the network's topology accordingly.
222+
223+
Once the announcement has been processed it is added to a list of outgoing announcements to the processing node's peers, which will be flushed at regular intervals.
224+
This store and delayed forward broadcast is called a _staggered broadcast_
225+
226+
If, after applying the changes from the announcement, there are no channels associated with the announcing node, then the receiving node MAY purge the announcing node from the set of known nodes.
227+
Otherwise the receiving node updates the metadata and stores the signature associated with the announcement.
228+
This will later allow the receiving node to rebuild the announcement for its peers.
229+
230+
After processing the announcement the receiving node adds the announcement to a list of outgoing announcements.
231+
232+
### Requirements
233+
234+
Each node SHOULD flush outgoing announcements once every 60 seconds, independently of the arrival times of announcements, resulting in a staggered announcement and deduplication of announcements.
235+
236+
Nodes MAY re-announce their channels regularly, however this is discouraged in order to keep the resource requirements low.
237+
238+
Nodes SHOULD send all `channel_announcement` messages followed by the
239+
latest `node_announcement` and `channel_update` messages upon
240+
connection establishment.
241+
242+
### Rationale
243+
244+
Batching announcements form a natural ratelimit with low overhead.
245+
246+
The sending of all announcements on reconnection is naive, but simple,
247+
and allows bootstrap for new nodes as well as updating for nodes which
248+
have been offline for some time.
249+
250+
## References
251+
252+
- [RFC 4291](https://tools.ietf.org/html/rfc4291)

0 commit comments

Comments
 (0)