Skip to content

Commit 9697b2b

Browse files
ajtownsajtowns
committed
BIP???: p2p feature negotiation
1 parent e2f9fe0 commit 9697b2b

File tree

1 file changed

+314
-0
lines changed

1 file changed

+314
-0
lines changed

‎bip-peer-feature-negotiation.md‎

Lines changed: 314 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,314 @@
1+
```
2+
BIP: ?
3+
Layer: Peer Services
4+
Title: Peer Feature Negotiation
5+
Author: Anthony Towns <aj@erisian.com.au>
6+
Comments-Summary: No comments yet.
7+
Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-XXXX
8+
Status: Draft
9+
Type: Standards Track
10+
Created: 2025-12-06
11+
License: BSD-3-Clause
12+
Post-History: https://gnusha.org/pi/bitcoindev/aUUXLgEUCgGb122o@erisian.com.au/T/#u
13+
https://gnusha.org/pi/bitcoindev/20200821023647.7eat4goqqrtaqnna@erisian.com.au/
14+
```
15+
16+
## Abstract
17+
18+
This BIP defines a peer-to-peer message that can be used for announcements
19+
and negotiation related to support of new peer-to-peer features.
20+
21+
## Motivation
22+
23+
Historically, new peer-to-peer protocol changes have been tied to
24+
bumping the protocol version, so that peers know to only attempt feature
25+
negotiation with other peers that may have been upgraded to support the
26+
feature. Coordinating the protocol version across implementations, when
27+
different clients may have different priorities for features to implement,
28+
is an unnecessary burden in the upgrade process for P2P features that do
29+
not require universal support. And at a more philosophical level, having
30+
the P2P protocol be [permissionlessly extensible][permless-extensible],
31+
with no coordination required between implementations or developers
32+
seems ideal for a decentralized system.
33+
34+
Many earlier P2P protocol upgrades were implemented as new messages
35+
sent after a peer connection is setup (ie, after receipt of a `verack`
36+
message by both sides). See [BIP 130 (sendheaders)][BIP130], [BIP 133
37+
(feefilter)][BIP133], [BIP 152 (compact blocks)][BIP152] for some
38+
examples. However, for some P2P upgrades, it is helpful to perform
39+
feature negotiation prior to a connection being fully established
40+
(ie, prior to the `verack` being received by both sides). [BIP 155
41+
(addrv2)][BIP155] and [BIP 339 (wtxid-relay)][BIP339] are examples of
42+
this approach, which involves sending and receiving a single new message
43+
(`sendaddrv2` and `wtxidrelay` respectively), in between `version` and
44+
`verack` to indicate support of the new feature.
45+
46+
In all these cases, sending new messages on the network raises the
47+
question of what non-implementing software will do with such messages. The
48+
common behavior observed on the network was for software to ignore
49+
unknown messages received from a peer, so these proposals posed small
50+
risk to potential network partitioning. In fact, supporting protocol
51+
extensibility in this manner was given as an explicit reason to ignore
52+
unknown messages in Bitcoin's [first release][0.1-extensibility].
53+
54+
However, if nodes respond to unknown messages by disconnecting, then
55+
the network might partition in the future as incompatible software is
56+
deployed. And in fact, some clients on the network have historically
57+
discouraged or disallowed unknown messages, both between `version`
58+
and `verack` (eg, Bitcoin Core discouraged such messages between
59+
[PR#9720][PR#9720] and [PR#19723][PR#19723], and btcd disallowed
60+
such messages until [PR#1812][btcd#1812], but see also discussion in
61+
[#1661][btcd#1661]), as well as after `verack`.
62+
63+
To maximise compatibility with such clients, most of these BIPs require
64+
that peers bump the protocol version:
65+
66+
* [BIP 130][BIP130] requires version 70012 or higher,
67+
* [BIP 133][BIP133] requires version 70013 or higher,
68+
* [BIP 152][BIP152] recommends version 70014/70015 or higher, and
69+
* [BIP 339][BIP339] requires version 70016 or higher.
70+
71+
And while [BIP 155][BIP155] does not specify a minimum protocol version,
72+
implementations have [added][PR#20564] a de facto requirement of version
73+
70016 or higher.
74+
75+
In this BIP, we propose codifying and generalising the mechanism used by
76+
[BIP 339][BIP339] for future P2P upgrades, by adding a single new feature
77+
negotiation message that can be reused for advertising arbitrary new
78+
features, and requiring that implementing software ignore unknown features
79+
that might be advertised. This allows future upgrades to negotiate new
80+
features by exchanging messages prior to exchanging `verack` messages,
81+
without concerns of being unnecessarily disconnected by a peer which
82+
doesn't understand the messages, and without needing to coordinate
83+
updating the protocol version.
84+
85+
## Specification
86+
87+
The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT",
88+
"RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
89+
interpreted as described in RFC 2119.
90+
91+
Nodes implementing this BIP:
92+
93+
* MUST advertise a protocol version number `>= 70017`,
94+
* MUST NOT send `feature` messages to peers that advertise a protocol
95+
version number `< 70017`,
96+
* MUST accept `feature` messages received after the `version` message
97+
and before the `verack` message, and
98+
* MUST NOT send `feature` messages after sending the `verack` message.
99+
100+
In addition, nodes implementing this BIP:
101+
102+
* SHOULD ignore unknown messages received after the `version` message
103+
and before the `verack` message,
104+
* MAY ignore `feature` messages sent after `verack`, and
105+
* MAY disconnect peers who send `feature` messages after `verack`.
106+
107+
Feature specifications based on this BIP:
108+
109+
* MUST forbid sending messages it introduces after `verack` to a peer
110+
that has not indicated support for the feature via a `feature`
111+
message.
112+
113+
### `feature` message
114+
115+
The payload of the `feature` message contains exactly the following data:
116+
117+
| Type | Name | Description |
118+
| ----------- | ------------- | ----------- |
119+
| string | `featureid` | Unique identifier for the feature |
120+
| byte-vector | `featuredata` | Feature-specific configuration data |
121+
122+
The `featureid` is encoded in the usual way, that is as a `CompactSize`
123+
specifying the string length, followed by that many bytes. The string
124+
length MUST be between 4 and 80, inclusive. The string SHOULD include
125+
only printable ASCII characters (ie, each byte should have a value between 32 and
126+
126, inclusive).
127+
128+
Likewise, `featuredata` is encoded as a `CompactSize` specifying the
129+
byte-vector size, followed by that many bytes. How these bytes are
130+
interpreted is part of the feature's specification. The byte-vector size
131+
MUST NOT be more than 512 bytes. Note that the `featuredata` field is not
132+
optional, so if no data is required, an empty vector should be provided,
133+
ie serialized as a `CompactSize` of 0.
134+
135+
Nodes implementing this BIP MAY disconnect peers that send `feature`
136+
messages where the `feature` message's payload cannot be correctly
137+
parsed (including having missing or additional data), even if they do
138+
not recognise the `featureid`.
139+
140+
Nodes implementing this BIP MUST ignore `feature` messages specifying a
141+
`featureid` they do not support, so long as the payload conforms to the
142+
requirements above.
143+
144+
The `featureid` MUST be a globally unique identifier for the feature.
145+
For features published as a BIP, the `featureid` SHOULD be the assigned
146+
BIP number, eg "BIP339", or be based on the BIP number (eg, including
147+
a "v2" suffix for versioning, or a "p3" suffix for different parts of
148+
the BIP). For experimental features that do not (yet) have a BIP number
149+
assigned, some other unique identifier MUST be chosen, such as a URL to
150+
the repository where development is taking place, or the sha256 digest
151+
of some longer reference.
152+
153+
Nodes implementing both this BIP and [BIP 324 (v2 P2P encrypted
154+
transport)][BIP324] MUST treat a message with a 1-byte `message_type`
155+
equal to `129` that is received prior to `verack` as the `feature` message.
156+
157+
### Feature negotiation
158+
159+
It is RECOMMENDED that feature negotiation be designed and implemented
160+
as follows:
161+
162+
* all `feature` messages and the `verack` message should be sent
163+
immediately on receipt of the peer's `version` message
164+
* any negotiation calculations should be performed immediately on
165+
receipt of the peer's `verack` message
166+
167+
This structure is fairly easy to implement, and avoids introducing any
168+
significant latency that might result from more interactive negotiation
169+
methods.
170+
171+
Feature specifications defining a `featureid` MAY make use of the
172+
following approaches:
173+
174+
#### Feature advertisement:
175+
176+
1. Send a `feature` message advertising the `featureid` unconditionally
177+
2. Accept messages related to the feature unconditionally
178+
3. Only send messages defined by the feature if the peer sent
179+
a valid `feature` message for the `featureid`.
180+
181+
This approach is appropriate for many simple features that define
182+
new messages, particularly where an implementation might only
183+
implement sending or receiving a message, but not both, eg [BIP 35
184+
(mempool)][BIP35].
185+
186+
#### Feature coordination:
187+
188+
1. Send a `feature` message advertising the `featureid` unconditionally
189+
2. Check if the peer sends the same `feature` message (or a compatible
190+
one), and enable the feature for this peer if so.
191+
3. Only send/accept messages or encode data items according to the
192+
feature's specification if the feature is enabled for this peer.
193+
194+
This approach is appropriate for upgrades to data encoding in
195+
P2P messages, eg [BIP 339 (wtxidrelay)][BIP339] or [BIP 155
196+
(addrv2)][BIP155].
197+
198+
#### Feature versioning:
199+
200+
1. Send `feature` messages for multiple incompatible features, eg
201+
`BIP339v3`, `BIP339v2`, `BIP339v1`. Send in order from most preferred
202+
to least.
203+
2. Track the corresponding `feature` messages from your peer.
204+
3. If you were the listening peer, enable your highest preference feature
205+
that your peer also supports.
206+
4. If you were the initiating peer, enable the first feature that your
207+
peer announced, that you also support.
208+
5. For example if the listening peer sends `BIP339v3`, `BIP339v2`,
209+
`BIP339v1`, and the initiating peer sends `BIP339v1`, `BIP339v2`,
210+
then the listening peer should select `BIP339v2` when `verack`
211+
is received, and the initiating peer should select `BIP339v2`
212+
as soon as `feature BIP339v2` is received.
213+
6. Conversely, if the initiating peer sends `BIP339v3`, `BIP339v2`,
214+
`BIP339v1`, and the listening peer sends `BIP339v1`, `BIP339v2`,
215+
then the listening peer should select `BIP339v1` when `verack`
216+
is received, and the initiating peer should select `BIP339v1`
217+
as soon as `feature BIP339v1` is received.
218+
7. In most cases, implementations should simply advertise incompatible
219+
features in order from most recent to oldest, on the basis that
220+
the only reason to make incompatible updates is because there are
221+
significant improvements. Exceptions to that may occur when two
222+
incompatible features are both receiving active development, or
223+
when an implementation has only partially implemented the latest
224+
spec, and the older spec is better supported (and thus should be
225+
listed first, as the preferred protocol to adopt).
226+
227+
This approach may be appropriate when making substantial changes to a
228+
deployed protocol and backwards compatibility is desirable on a short-term
229+
basis, or when there is disagreement amongst implementations or users
230+
as to which approach is most desirable.
231+
232+
## Considerations
233+
234+
The advantage this approach has over bumping the protocol version
235+
number when introducing new P2P messages or data structures, is that no
236+
coordination is required (that is, there is no longer a question whether
237+
version "n+1" belong to Alice's new feature, or Bob's new feature),
238+
and there is no implication that supporting each new feature means all
239+
prior features are also supported.
240+
241+
The advantage this approach has over defining new messages for each
242+
feature is that the `featureid` can be much longer (at up to 80
243+
bytes) than a message type id (which are limited to 12 bytes). With a
244+
[BIP 324][BIP324] one-byte `message_type`, the overhead compared to that
245+
approach is also kept small.
246+
247+
This approach is largely equivalent to adding a [payload to the `verack`
248+
message][verack-payload] (eg, a vector of `featureid`, `featuredata`
249+
pairs). It was chosen because:
250+
251+
* it retains compatibility with any implementations that expect `verack`
252+
to have no payload;
253+
* it allows peers to process each feature request individually, rather than
254+
having to first load the configuration information for all features into
255+
memory at once (in order to validate the message's checksum), and then
256+
deal with each feature's configuration;
257+
* limiting the maximum message payload size you accept (eg to 4MB)
258+
does not limit the number of features you can accept; and
259+
* we have experience with negotiating features with individual messages,
260+
but no experience with doing so via `verack` payload.
261+
262+
A mild disadvantage compared to using a `verack` payload is that this
263+
approach allows the possibility of interactive feature negotiation prior
264+
to `verack`. However interactive feature negotiation is always possible
265+
simply by having the initiating peer disconnect and reconnect after
266+
discovering the listening peer's supported features.
267+
268+
This specification attempts to maximise compatibility with implementations
269+
that prefer to fully validate each message received:
270+
271+
* `feature` messages, even for unknown features, must always be fully
272+
parseable into a `featureid` and `featuredata`
273+
* Ignoring unknown messages prior to `verack` is only a recommendation
274+
nor a requirement, so compliant implementations may disconnect on an
275+
unknown message that cannot be validated.
276+
* Sending unknown messages after `verack` is explicitly forbidden,
277+
in so far as that is possible.
278+
279+
## Backward compatibility
280+
281+
Clients specifying a version number prior to `70017` remain fully
282+
compatible with this change.
283+
284+
Clients specifying a version number of `70017` or higher that do not
285+
implement this BIP remain fully compatible provided they do not disconnect
286+
peers upon receiving unexpected messages received between `version` and
287+
`verack`.
288+
289+
## Acknowledgements
290+
291+
Much of the logic here, and much of the text in the motivation section,
292+
is based on Suhas Daftuar's 2020 post on [Generalizing feature
293+
negotiation][suhas-draft].
294+
295+
## Copyright
296+
297+
This BIP is licensed under the 2-clause BSD license.
298+
299+
[BIP130]: https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki
300+
[BIP133]: https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki
301+
[BIP152]: https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki
302+
[BIP155]: https://github.com/bitcoin/bips/blob/master/bip-0155.mediawiki
303+
[BIP339]: https://github.com/bitcoin/bips/blob/master/bip-0339.mediawiki
304+
[BIP35]: https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki
305+
[BIP324]: https://github.com/bitcoin/bips/blob/master/bip-0324.mediawiki
306+
[verack-payload]: https://gnusha.org/pi/bitcoindev/B514142F-382B-4D49-B68D-0115ECBD1D79@voskuil.org/
307+
[PR#20564]: https://github.com/bitcoin/bitcoin/pull/20564
308+
[PR#9720]: https://github.com/bitcoin/bitcoin/pull/9720
309+
[PR#19723]: https://github.com/bitcoin/bitcoin/pull/19723
310+
[btcd#1812]: https://github.com/btcsuite/btcd/pull/1812
311+
[btcd#1661]: https://github.com/btcsuite/btcd/issues/1661
312+
[permless-extensible]: https://github.com/bitcoin/bitcoin/pull/20564#issuecomment-738456560
313+
[0.1-extensibility]: https://github.com/benjiqq/bitcoinArchive/blob/master/bitcoin0.1/src/main.cpp#L2035-L2039
314+
[suhas-draft]: https://gnusha.org/pi/bitcoindev/CAFp6fsE=HPFUMFhyuZkroBO_QJ-dUWNJqCPg9=fMJ3Jqnu1hnw@mail.gmail.com/

0 commit comments

Comments
 (0)