This BIP defines a peer-to-peer (P2P) message that can be used for\nannouncements and negotiation related to support of new peer-to-peer\nfeatures.
\nHistorically, new peer-to-peer protocol changes have been tied to\nbumping the protocol version, so that nodes know to only attempt\nfeature negotiation with peers that support the feature. Coordinating\nthe protocol version across implementations, when different clients may\nhave different priorities for features to implement, is an unnecessary\nburden in the upgrade process for P2P features that do not require\nuniversal support. And at a more philosophical level, having the P2P\nprotocol be permissionlessly extensible, with no\ncoordination required between implementations or developers, seems ideal\nfor a decentralized system.
\nMany earlier P2P protocol upgrades were implemented as new messages\nsent after a peer connection is set up (ie, after receipt of a verack\nmessage by both sides). See BIP 130 (sendheaders), BIP 133\n(feefilter), and BIP 152 (compact blocks) for some\nexamples. However, for some P2P upgrades, it is helpful to perform\nfeature negotiation prior to a connection being fully established\n(ie, prior to the verack being received by both sides). BIP 155\n(addrv2) and BIP 339 (wtxid-relay) are examples of\nthis approach, which involves sending and receiving a single new message\n(sendaddrv2 and wtxidrelay respectively), in between version and\nverack to indicate support of the new feature.
In all these cases, sending new messages on the network raises the\nquestion of what non-implementing software will do with such messages. The\ncommon behavior observed on the network was for software to ignore\nunknown messages received from a peer, so these proposals posed minimal\nrisk of potential network partitioning. In fact, supporting protocol\nextensibility in this manner was given as an explicit reason to ignore\nunknown messages in Bitcoin's first release.
\nHowever, if nodes respond to unknown messages by disconnecting, then\nthe network might partition in the future as incompatible software is\ndeployed. And in fact, some clients on the network have historically\ndiscouraged or disallowed unknown messages, both between version\nand verack (eg, Bitcoin Core discouraged such messages between\nPR#9720 and PR#19723, and btcd disallowed\nsuch messages until PR#1812, but see also discussion in\n#1661), as well as after verack.
To maximise compatibility with such clients, most of these BIPs require\nthat peers bump the protocol version:
\nAnd while BIP 155 does not specify a minimum protocol version,\nimplementations have added a de facto requirement of version\n70016 or higher.
\nIn this BIP, we propose codifying and generalising the mechanism used by\nBIP 339 for future P2P upgrades, by adding a single new feature\nnegotiation message that can be reused for advertising arbitrary new\nfeatures, and requiring that implementing software ignore unknown features\nthat might be advertised. This allows future upgrades to negotiate new\nfeatures by exchanging messages prior to exchanging verack messages,\nwithout concerns of being unnecessarily disconnected by a peer which\ndoesn't understand the messages, and without needing to coordinate\nupdating the protocol version.
The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT",\n"RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be\ninterpreted as described in RFC 2119.
\nFor the purposes of this section, CompactSize refers to the\nvariable-length integer encoding used across the existing P2P protocol\nto encode array lengths, among other things, in 1, 3, 5 or 9 bytes. Only\nCompactSize encodings which are minimally-encoded (ie the shortest\nlength possible) are used by this specification.
Nodes implementing this BIP:
\n>= 70017,feature messages to peers that advertise a protocol\nversion number < 70017,feature messages received after the version message\nand before the verack message, andfeature messages after sending the verack message.In addition, nodes implementing this BIP:
\nversion message\nand before the verack message,feature messages sent after verack, andfeature messages after verack.Feature specifications based on this BIP:
\nverack to a peer\nthat has not indicated support for the feature via a feature\nmessage.feature messageThe payload of the feature message contains exactly the following data:
| Type | \nName | \nDescription | \n
|---|---|---|
| string | \nfeatureid | \nUnique identifier for the feature | \n
| byte-vector | \nfeaturedata | \nFeature-specific configuration data | \n
The featureid is encoded in the usual way, that is, as a CompactSize\nspecifying the string length, followed by that many bytes. The string\nlength MUST be between 4[^feature-id-min] and 80[^feature-payload-max],\ninclusive. The string SHOULD include only printable ASCII characters\n(ie, each byte should have a value between 32 and 126, inclusive).
Likewise, featuredata is encoded as a CompactSize specifying the\nbyte-vector size, followed by that many bytes. How these bytes are\ninterpreted is part of the feature's specification. The byte-vector\nsize MUST NOT be more than 512 bytes[^feature-payload-max]. Note that\nthe featuredata field is not optional, so if no data is required,\nan empty vector should be provided, ie serialized as CompactSize of 0.
The featureid MUST be a globally unique identifier for the feature.
For features published as a BIP, the featureid SHOULD be the assigned\nBIP number, eg "BIP434", or be based on the BIP number (eg, "BIP434v2"\nwhere the "v2" suffix covers versioning, or "BIP434.3" where the ".3"\nsuffix covers part 3 of the BIP). For experimental features that do not\n(yet) have a BIP number assigned, some other unique identifier MUST be\nchosen, such as a URL to the repository where development is taking\nplace, or the sha256 digest of some longer reference.
Nodes implementing this BIP MUST ignore feature messages specifying a\nfeatureid they do not support, so long as the payload conforms to the\nrequirements above.
Nodes implementing this BIP MAY disconnect peers that send feature\nmessages where the feature message's payload cannot be correctly\nparsed (including having missing or additional data), even if they do\nnot recognise the featureid.
feature message 1-byte identifierNodes implementing both this BIP and BIP 324 (v2 P2P encrypted\ntransport) MUST treat a message with a 1-byte message_type\nequal to 37 that is received prior to verack as the feature message.
It is RECOMMENDED that feature negotiation be designed and implemented\nas follows:
\nfeature messages and the verack message should be sent\nimmediately on receipt of the peer's version messageverack messageThis structure is fairly easy to implement, and avoids introducing any\nsignificant latency that might result from more interactive negotiation\nmethods.
\nFeature specifications defining a featureid MAY make use of the\nfollowing approaches:
feature message advertising the featureid unconditionallyfeature message for the featureid.This approach is appropriate for many simple features that define\nnew messages, particularly where an implementation might only\nimplement sending or receiving a message, but not both, eg BIP 35\n(mempool).
\nfeature message advertising the featureid unconditionallyfeature message (or a compatible\none), and enable the feature for this peer if so.This approach is appropriate for upgrades to data encoding in\nP2P messages, eg BIP 339 (wtxidrelay) or BIP 155\n(addrv2).
\nfeature messages for multiple incompatible features, eg\nBIP434v3, BIP434v2, BIP434v1, ordered from most preferred\nto least.feature messages from your peer.BIP434v3, BIP434v2,\nBIP434v1, and the initiating peer sends BIP434v1, BIP434v2,\nthen the listening peer should select BIP434v2 when verack\nis received, and the initiating peer should select BIP434v2\nas soon as feature BIP434v2 is received.BIP434v3, BIP434v2,\nBIP434v1, and the listening peer sends BIP434v1, BIP434v2,\nthen the listening peer should select BIP434v1 when verack\nis received, and the initiating peer should select BIP434v1\nas soon as feature BIP434v1 is received.This approach may be appropriate when making substantial changes to a\ndeployed protocol and backwards compatibility is desirable on a short-term\nbasis, or when there is disagreement amongst implementations or users\nas to which approach is most desirable.
\nThe advantage this approach has over bumping the protocol version\nnumber when introducing new P2P messages or data structures, is that no\ncoordination is required (that is, there is no longer a question whether\nversion "n+1" belongs to Alice's new feature, or Bob's new feature),\nand there is no implication that supporting each new feature means all\nprior features are also supported.
\nThe advantage this approach has over defining new messages for each\nfeature is that the featureid can be much longer (at up to 80\nbytes) than a message type id (which are limited to 12 bytes). With a\nBIP 324 one-byte message_type, the overhead compared to that\napproach is also kept small.
This approach is largely equivalent to adding a payload to the verack\nmessage (eg, a vector of featureid, featuredata\npairs). It was chosen because:
verack\nto have no payload;verack payload.A mild disadvantage compared to using a verack payload is that this\napproach allows the possibility of interactive feature negotiation prior\nto verack, which would make negotiation more complex and increase\nlatency. However interactive feature negotiation is always possible\nsimply by having the initiating peer disconnect and reconnect after\ndiscovering the listening peer's supported features.
This specification attempts to maximise compatibility with implementations\nthat prefer to fully validate each message received:
\nfeature messages, even for unknown features, must always be fully\nparseable into a featureid and featuredataverack is only a recommendation,\nnot a requirement, so compliant implementations may disconnect on an\nunknown message that cannot be validated.verack is explicitly forbidden,\nin so far as that is possible.This feature was implemented in Bitcoin Core PR#35221,\nwhich may be used as a reference implementation.
\nClients specifying a version number prior to 70017 remain fully\ncompatible with this change.
Clients specifying a version number of 70017 or higher that do not\nimplement this BIP remain fully compatible provided they do not disconnect\npeers upon receiving unexpected messages received between version and\nverack.
Much of the logic here, and much of the text in the motivation section,\nis based on Suhas Daftuar's 2020 post on Generalizing feature\nnegotiation.
\nThis BIP is licensed under the 2-clause BSD license.
\n[^feature-id-min]: The minimum featureid length of 4 characters\ncorresponds with a "BIPx" string for BIPs in the range 1-9. Longer\nidentifiers than this will almost always be needed in order to meet the\n"globally unique" requirement.
[^feature-payload-max]: The maximum values for the featureid and\nfeaturedata lengths serve only to bound the volume of the feature\nmessage payload, particularly as this data will be automatically\nadvertised even to peers that do not support the features in question.