BIP 0155 - Revision history

934: Update BIP text with latest version from https://github.com/bitcoin/bips/blob/49ec00afae54b54b/bip-0155.mediawiki

2024-04-26T22:59:40Z

Update BIP text with latest version from https://github.com/bitcoin/bips/blob/49ec00afae54b54b/bip-0155.mediawiki

← Older revision		Revision as of 22:59, 26 April 2024
Line 121:		Line 121:
	\| 16		\| 16
	\| Cjdns overlay network address		\| Cjdns overlay network address
			\|-
			\| <code>0x07</code>
			\| <code>YGGDRASIL</code>
			\| 16
			\| Yggdrasil overlay network address
	\|}		\|}

Line 187:		Line 192:

	Cjdns addresses are simply IPv6 addresses in the <code>fc00::/8</code> range<ref>[https://github.com/cjdelisle/cjdns/blob/6e46fa41f5647d6b414612d9d63626b0b952746b/doc/Whitepaper.md#pulling-it-all-together Cjdns whitepaper: Pulling It All Together]</ref>. They MUST be sent with the <code>CJDNS</code> network ID.		Cjdns addresses are simply IPv6 addresses in the <code>fc00::/8</code> range<ref>[https://github.com/cjdelisle/cjdns/blob/6e46fa41f5647d6b414612d9d63626b0b952746b/doc/Whitepaper.md#pulling-it-all-together Cjdns whitepaper: Pulling It All Together]</ref>. They MUST be sent with the <code>CJDNS</code> network ID.

			==Appendix E: Yggdrasil address encoding==

			Yggdrasil addresses are simply IPv6 addresses in the <code>0200::/7</code> range<ref>[https://yggdrasil-network.github.io/faq.html#will-yggdrasil-conflict-with-my-network-routing Yggdrasil FAQ]</ref>. They MUST be sent with the <code>YGGDRASIL</code> network ID.

	==References==		==References==

	<references/>		<references/>

934: Update BIP text with latest version from https://github.com/bitcoin/bips/blob/edffe529056f6dfd/bip-0155.mediawiki

2021-12-15T15:48:14Z

Update BIP text with latest version from https://github.com/bitcoin/bips/blob/edffe529056f6dfd/bip-0155.mediawiki

← Older revision		Revision as of 15:48, 15 December 2021
Line 135:		Line 135:
	==Signaling support and compatibility==		==Signaling support and compatibility==

	Introduce a new message type <code>sendaddrv2</code>. Sending such a message indicates that a node can understand and prefers to receive <code>addrv2</code> messages instead of <code>addr</code> messages. I.e. "Send me addrv2".		Introduce a new message type <code>sendaddrv2</code>. Sending such a message indicates that a node can understand and prefers to receive <code>addrv2</code> messages instead of <code>addr</code> messages. I.e. "Send me addrv2". Sending or not sending this message does not imply any preference with respect to receiving unrequested address messages.

	The <code>sendaddrv2</code> message MUST only be sent in response to the <code>version</code> message from a peer and prior to sending the <code>verack</code> message.		The <code>sendaddrv2</code> message MUST only be sent in response to the <code>version</code> message from a peer and prior to sending the <code>verack</code> message.

934: Update BIP text with latest version from https://github.com/bitcoin/bips/blob/19c429ee2831d898/bip-0155.mediawiki

2021-02-12T21:27:58Z

Update BIP text with latest version from https://github.com/bitcoin/bips/blob/19c429ee2831d898/bip-0155.mediawiki

← Older revision		Revision as of 21:27, 12 February 2021
Line 48:		Line 48:
	The <code>addrv2</code> message is defined as a message where <code>pchCommand == "addrv2"</code>.		The <code>addrv2</code> message is defined as a message where <code>pchCommand == "addrv2"</code>.
	It is serialized in the standard encoding for P2P messages.		It is serialized in the standard encoding for P2P messages.
	Its format is similar to the current <code>addr</code> message format		Its format is similar to the current <code>addr</code> message format, with the difference that the
	~~<ref>[https://bitcoin.org/en/developer-reference#addr Bitcoin Developer Reference: addr message]</ref>~~, with the difference that the
	fixed 16-byte IP address is replaced by a network ID and a variable-length address, and the services format has been changed to [https://en.bitcoin.it/wiki/Protocol_documentation#Variable_length_integer CompactSize].		fixed 16-byte IP address is replaced by a network ID and a variable-length address, and the services format has been changed to [https://en.bitcoin.it/wiki/Protocol_documentation#Variable_length_integer CompactSize].

934: Update BIP text with latest version from https://github.com/bitcoin/bips/blob/cf0b529e78860fa2/bip-0155.mediawiki

2021-01-01T10:05:11Z

Update BIP text with latest version from https://github.com/bitcoin/bips/blob/cf0b529e78860fa2/bip-0155.mediawiki

← Older revision		Revision as of 10:05, 1 January 2021
Line 50:		Line 50:
	Its format is similar to the current <code>addr</code> message format		Its format is similar to the current <code>addr</code> message format
	<ref>[https://bitcoin.org/en/developer-reference#addr Bitcoin Developer Reference: addr message]</ref>, with the difference that the		<ref>[https://bitcoin.org/en/developer-reference#addr Bitcoin Developer Reference: addr message]</ref>, with the difference that the
	fixed 16-byte IP address is replaced by a network ID and a variable-length address, and the ~~time and~~ services format has been changed to ~~VARINT~~.		fixed 16-byte IP address is replaced by a network ID and a variable-length address, and the services format has been changed to [https://en.bitcoin.it/wiki/Protocol_documentation#Variable_length_integer CompactSize].

	This means that the message contains a serialized <code>std::vector</code> of the following structure:		This means that the message contains a serialized <code>std::vector</code> of the following structure:
Line 59:		Line 59:
	!Description		!Description
	\|-		\|-
	\| <code>~~VARINT~~</code> ~~(unsigned)~~		\| <code>uint32_t</code>
	\| <code>time</code>		\| <code>time</code>
	\| Time that this node was last seen as connected to the network. A time in Unix epoch time format~~, up to 64 bits wide~~.		\| Time that this node was last seen as connected to the network. A time in Unix epoch time format.
	\|-		\|-
	\| <code>~~VARINT~~</code> ~~(unsigned)~~		\| <code>CompactSize</code>
	\| <code>services</code>		\| <code>services</code>
	\| Service bits. A 64-wide ~~bit field~~.		\| Service bits. A bit field that is 64 bits wide, encoded in [https://en.bitcoin.it/wiki/Protocol_documentation#Variable_length_integer CompactSize].
	\|-		\|-
	\| <code>uint8_t</code>		\| <code>uint8_t</code>
Line 82:		Line 82:
	One message can contain up to 1,000 addresses. Clients SHOULD reject messages with more addresses.		One message can contain up to 1,000 addresses. Clients SHOULD reject messages with more addresses.

	Field <code>addr</code> has a variable length, with a maximum of 32 bytes (~~256~~ bits). Clients SHOULD reject		Field <code>addr</code> has a variable length, with a maximum of 512 bytes (4096 bits).
	longer addresses.		Clients SHOULD reject messages with longer addresses, irrespective of the network ID.

	The list of reserved network IDs is as follows:		The list of reserved network IDs is as follows:
Line 124:		Line 124:
	\|}		\|}

	~~To allow for future extensibility, clients MUST ignore address types that~~ they do not ~~know about~~.		Clients are RECOMMENDED to gossip addresses from all known networks even if they are currently not connected to some of them. That could help multi-homed nodes and make it more difficult for an observer to tell which networks a node is connected to.
	~~Client MAY store~~ and ~~gossip address formats that they do not know about. Further network ID numbers MUST be reserved in~~ a ~~new BIP document~~.

	Clients SHOULD reject addresses that have a different length than specified in this table for a specific ~~address~~ ID, as these are meaningless.		Clients SHOULD NOT gossip addresses from unknown networks because they have no means to validate those addresses and so can be tricked to gossip invalid addresses.

			Further network ID numbers MUST be reserved in a new BIP document.

			Clients SHOULD reject messages that contain addresses that have a different length than specified in this table for a specific network ID, as these are meaningless.

	See the appendices for the address encodings to be used for the various networks.		See the appendices for the address encodings to be used for the various networks.

	==~~Compatibility~~==		==Signaling support and compatibility==

	~~Send~~ <code>addrv2</code> messages ~~only, and exclusively, when the peer has a certain protocol version (or higher):~~		Introduce a new message type <code>sendaddrv2</code>. Sending such a message indicates that a node can understand and prefers to receive <code>addrv2</code> messages instead of <code>addr</code> messages. I.e. "Send me addrv2".
	<~~source lang=~~"~~c++~~">
	//~~! gossiping using `addrv2` messages starts with this version~~		The <code>sendaddrv2</code> message MUST only be sent in response to the <code>version</code> message from a peer and prior to sending the <code>verack</code> message.
	~~static const int GOSSIP_ADDRV2_VERSION = 70016;~~
	</~~source~~>		For older peers, that did not emit <code>sendaddrv2</code>, keep sending the legacy <code>addr</code> message, ignoring addresses with the newly introduced address types.
	For older peers keep sending the legacy <code>addr</code> message, ignoring addresses with the newly introduced address types.

	==Reference implementation==		==Reference implementation==
Line 146:		Line 148:
	==Acknowledgements==		==Acknowledgements==

	- Jonas Schnelli: change <code>services</code> field to ~~VARINT~~, to make the message more compact in the likely case instead of always using 8 bytes.		- Jonas Schnelli: change <code>services</code> field to [https://en.bitcoin.it/wiki/Protocol_documentation#Variable_length_integer CompactSize], to make the message more compact in the likely case instead of always using 8 bytes.

	~~- Luke-Jr: change <code>time</code> field to VARINT, for post-2038 compatibility~~.

	- Gregory Maxwell: various suggestions regarding extensibility		- Gregory Maxwell: various suggestions regarding extensibility
Line 154:		Line 154:
	==Appendix A: Tor v2 address encoding==		==Appendix A: Tor v2 address encoding==

	The new message introduces a separate network ID for <code>TORV2</code>.		The new message introduces a separate network ID for <code>TORV2</code>.

	Clients MUST send Tor hidden service addresses with this network ID, with the 80-bit hidden service ID in the address field. This is the same as the representation in the legacy <code>addr</code> message, minus the 6 byte prefix of the OnionCat wrapping.		Clients MUST send Tor hidden service addresses with this network ID, with the 80-bit hidden service ID in the address field. This is the same as the representation in the legacy <code>addr</code> message, minus the 6 byte prefix of the OnionCat wrapping.
Line 168:		Line 168:

	where:		where:
	- PUBKEY is the 32 bytes ed25519 master pubkey of the hidden service.		- PUBKEY is the 32 bytes ed25519 master pubkey of the hidden service
	- VERSION is an one byte version field (default value '\x03')		- VERSION is a one byte version field (default value '\x03')
	- ".onion checksum" is a constant string		- ".onion checksum" is a constant string
	- CHECKSUM is truncated to two bytes before inserting it in onion_address		- CHECKSUM is truncated to two bytes before inserting it in onion_address
			- H() is the SHA3-256 cryptographic hash function
	</pre>		</pre>

934: Update BIP text with latest version from https://github.com/bitcoin/bips/blob/b5723035e23896d0/bip-0155.mediawiki

2019-09-24T17:59:13Z

Update BIP text with latest version from https://github.com/bitcoin/bips/blob/b5723035e23896d0/bip-0155.mediawiki

New page

{{bip}}
{{BipMoved|bip-0155.mediawiki}}

<pre>
BIP: 155
Layer: Peer Services
Title: addrv2 message
Author: Wladimir J. van der Laan <laanwj@gmail.com>
Comments-Summary: No comments yet.
Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0155
Status: Draft
Type: Standards Track
Created: 2019-02-27
License: BSD-2-Clause
</pre>

==Introduction==

===Abstract===

This document proposes a new P2P message to gossip longer node addresses over the P2P network.
This is required to support new-generation Onion addresses, I2P, and potentially other networks
that have longer endpoint addresses than fit in the 128 bits of the current <code>addr</code> message.

===Copyright===

This BIP is licensed under the 2-clause BSD license.

===Motivation===

Tor v3 hidden services are part of the stable release of Tor since version 0.3.2.9. They have
various advantages compared to the old hidden services, among which better encryption and privacy
<ref>[https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt Tor Rendezvous Specification - Version 3]</ref>.
These services have 256 bit addresses and thus do not fit in the existing <code>addr</code> message, which encapsulates onion addresses in OnionCat IPv6 addresses.

Other transport-layer protocols such as I2P have always used longer
addresses. This change would make it possible to gossip such addresses over the
P2P network, so that other peers can connect to them.

==Specification==

<blockquote>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
interpreted as described in RFC 2119<ref>[https://tools.ietf.org/html/rfc2119 RFC 2119]</ref>.
</blockquote>

The <code>addrv2</code> message is defined as a message where <code>pchCommand == "addrv2"</code>.
It is serialized in the standard encoding for P2P messages.
Its format is similar to the current <code>addr</code> message format
<ref>[https://bitcoin.org/en/developer-reference#addr Bitcoin Developer Reference: addr message]</ref>, with the difference that the
fixed 16-byte IP address is replaced by a network ID and a variable-length address, and the time and services format has been changed to VARINT.

This means that the message contains a serialized <code>std::vector</code> of the following structure:

{| class="wikitable" style="width: auto; text-align: center; font-size: smaller; table-layout: fixed;"
!Type
!Name
!Description
|-
| <code>VARINT</code> (unsigned)
| <code>time</code>
| Time that this node was last seen as connected to the network. A time in Unix epoch time format, up to 64 bits wide.
|-
| <code>VARINT</code> (unsigned)
| <code>services</code>
| Service bits. A 64-wide bit field.
|-
| <code>uint8_t</code>
| <code>networkID</code>
| Network identifier. An 8-bit value that specifies which network is addressed.
|-
| <code>std::vector<uint8_t></code>
| <code>addr</code>
| Network address. The interpretation depends on networkID.
|-
| <code>uint16_t</code>
| <code>port</code>
| Network port. If not relevant for the network this MUST be 0.
|}

One message can contain up to 1,000 addresses. Clients SHOULD reject messages with more addresses.

Field <code>addr</code> has a variable length, with a maximum of 32 bytes (256 bits). Clients SHOULD reject
longer addresses.

The list of reserved network IDs is as follows:

{| class="wikitable" style="width: auto; text-align: center; font-size: smaller; table-layout: fixed;"
!Network ID
!Enumeration
!Address length (bytes)
!Description
|-
| <code>0x01</code>
| <code>IPV4</code>
| 4
| IPv4 address (globally routed internet)
|-
| <code>0x02</code>
| <code>IPV6</code>
| 16
| IPv6 address (globally routed internet)
|-
| <code>0x03</code>
| <code>TORV2</code>
| 10
| Tor v2 hidden service address
|-
| <code>0x04</code>
| <code>TORV3</code>
| 32
| Tor v3 hidden service address
|-
| <code>0x05</code>
| <code>I2P</code>
| 32
| I2P overlay network address
|-
| <code>0x06</code>
| <code>CJDNS</code>
| 16
| Cjdns overlay network address
|}

To allow for future extensibility, clients MUST ignore address types that they do not know about.
Client MAY store and gossip address formats that they do not know about. Further network ID numbers MUST be reserved in a new BIP document.

Clients SHOULD reject addresses that have a different length than specified in this table for a specific address ID, as these are meaningless.

See the appendices for the address encodings to be used for the various networks.

==Compatibility==

Send <code>addrv2</code> messages only, and exclusively, when the peer has a certain protocol version (or higher):
<source lang="c++">
//! gossiping using `addrv2` messages starts with this version
static const int GOSSIP_ADDRV2_VERSION = 70016;
</source>
For older peers keep sending the legacy <code>addr</code> message, ignoring addresses with the newly introduced address types.

==Reference implementation==

The reference implementation is available at (to be done)

==Acknowledgements==

- Jonas Schnelli: change <code>services</code> field to VARINT, to make the message more compact in the likely case instead of always using 8 bytes.

- Luke-Jr: change <code>time</code> field to VARINT, for post-2038 compatibility.

- Gregory Maxwell: various suggestions regarding extensibility

==Appendix A: Tor v2 address encoding==

The new message introduces a separate network ID for <code>TORV2</code>.

Clients MUST send Tor hidden service addresses with this network ID, with the 80-bit hidden service ID in the address field. This is the same as the representation in the legacy <code>addr</code> message, minus the 6 byte prefix of the OnionCat wrapping.

Clients SHOULD ignore OnionCat (<code>fd87:d87e:eb43::/48</code>) addresses on receive if they come with the <code>IPV6</code> network ID.

==Appendix B: Tor v3 address encoding==

According to the spec <ref>[https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt Tor Rendezvous Specification - Version 3: Encoding onion addresses]</ref>, next-gen <code>.onion</code> addresses are encoded as follows:
<pre>
onion_address = base32(PUBKEY | CHECKSUM | VERSION) + ".onion"
CHECKSUM = H(".onion checksum" | PUBKEY | VERSION)[:2]

where:
- PUBKEY is the 32 bytes ed25519 master pubkey of the hidden service.
- VERSION is an one byte version field (default value '\x03')
- ".onion checksum" is a constant string
- CHECKSUM is truncated to two bytes before inserting it in onion_address
</pre>

Tor v3 addresses MUST be sent with the <code>TORV3</code> network ID, with the 32-byte PUBKEY part in the address field. As VERSION will always be '\x03' in the case of v3 addresses, this is enough to reconstruct the onion address.

==Appendix C: I2P address encoding==

Like Tor, I2P naming uses a base32-encoded address format<ref>[https://geti2p.net/en/docs/naming#base32 I2P: Naming and address book]</ref>.

I2P uses 52 characters (256 bits) to represent the full SHA-256 hash, followed by <code>.b32.i2p</code>.

I2P addresses MUST be sent with the <code>I2P</code> network ID, with the decoded SHA-256 hash as address field.

==Appendix D: Cjdns address encoding==

Cjdns addresses are simply IPv6 addresses in the <code>fc00::/8</code> range<ref>[https://github.com/cjdelisle/cjdns/blob/6e46fa41f5647d6b414612d9d63626b0b952746b/doc/Whitepaper.md#pulling-it-all-together Cjdns whitepaper: Pulling It All Together]</ref>. They MUST be sent with the <code>CJDNS</code> network ID.

==References==

<references/>