From 7d449ca23182290177129dd0d917072423220d10 Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Sun, 8 Jan 2023 22:40:12 -0500 Subject: [PATCH 01/11] add identify content --- .../introduction/protocols/identify.md | 37 ++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/content/concepts/introduction/protocols/identify.md b/content/concepts/introduction/protocols/identify.md index 63026035..9cd09a3c 100644 --- a/content/concepts/introduction/protocols/identify.md +++ b/content/concepts/introduction/protocols/identify.md @@ -4,4 +4,39 @@ description: "A way for nodes in libp2p to query and inform other nodes about th weight: 23 --- -Coming soon! +The libp2p identify protocol is a way for nodes to query and inform other nodes +about their metadata, such as their public key and the protocols they support. + +There are two variations of the protocol: `identify` and `identify/push`. + +The identify protocol, identified by the protocol ID `/ipfs/id/1.0.0`, is used +to query a remote node for its metadata. To do so, a node opens a stream to the +remote node and the remote node responds with an `Identify` message containing +its metadata and closes the stream. + +The identify/push protocol, identified by the protocol ID `/ipfs/id/push/1.0.0`, +is used to inform other nodes about changes in a node's metadata. When a +node's metadata changes, it can "push" the new information to other nodes by opening +a stream to each of the nodes to be updated, and sending an `Identify` message +containing the updated metadata. Upon receiving the pushed `Identify` message, the +remote node can update its local metadata repository with the information from the +message, taking into account that missing fields should be ignored as the message may +contain only partial updates. + +The `Identify` message contains several fields: + +- `protocolVersion`: (optional) identifies the family of protocols used by the node. + It is recommended for debugging and statistic purposes, but previous specification versions + required connections to be closed on version mismatch. This requirement has been revoked to + allow interoperability between different protocol families and networks. +- `agentVersion`: a free-form string identifying the node's implementation, usually + in the format agent-name/version. +- `publicKey`: the node's public key, marshaled in binary form. +- `listenAddrs`: the addresses on which the node is listening, as multi-addresses. +- `observedAddr`: (optional) the connection source address of the stream-initiating node + as observed by the node being identified. It can be used to infer the existence of NAT + and its public address. +- `protocols`: a list of protocols supported by the node. A node should only advertise a + protocol if it is willing to receive inbound streams on that protocol. + +{{< alert icon="💡" context="note" text="See the Identify technical specification for more details." />}} From 470712bf70707d075ab9ba2557c308226391cff7 Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Thu, 12 Jan 2023 04:48:15 -0500 Subject: [PATCH 02/11] incorporate PR feedback and simplify --- .../introduction/protocols/identify.md | 28 +++++++------------ 1 file changed, 10 insertions(+), 18 deletions(-) diff --git a/content/concepts/introduction/protocols/identify.md b/content/concepts/introduction/protocols/identify.md index 9cd09a3c..3dbf3e32 100644 --- a/content/concepts/introduction/protocols/identify.md +++ b/content/concepts/introduction/protocols/identify.md @@ -4,8 +4,16 @@ description: "A way for nodes in libp2p to query and inform other nodes about th weight: 23 --- -The libp2p identify protocol is a way for nodes to query and inform other nodes -about their metadata, such as their public key and the protocols they support. +The libp2p identify protocol is a way for nodes in a peer-to-peer network to share +and query information about each other. This information includes: + +- the user agent: a free-form string identifying the node's implementation, usually + in the format "agent-name/version". +- the public IP address: the address of the node on the network, as seen by other nodes. +- the list of multiaddresses that the node is listening on: the various network addresses + and ports that the node can be reached at. +- the list of protocols that the node supports: the different communication methods that + the node can understand and use to communicate with other nodes. There are two variations of the protocol: `identify` and `identify/push`. @@ -23,20 +31,4 @@ remote node can update its local metadata repository with the information from t message, taking into account that missing fields should be ignored as the message may contain only partial updates. -The `Identify` message contains several fields: - -- `protocolVersion`: (optional) identifies the family of protocols used by the node. - It is recommended for debugging and statistic purposes, but previous specification versions - required connections to be closed on version mismatch. This requirement has been revoked to - allow interoperability between different protocol families and networks. -- `agentVersion`: a free-form string identifying the node's implementation, usually - in the format agent-name/version. -- `publicKey`: the node's public key, marshaled in binary form. -- `listenAddrs`: the addresses on which the node is listening, as multi-addresses. -- `observedAddr`: (optional) the connection source address of the stream-initiating node - as observed by the node being identified. It can be used to infer the existence of NAT - and its public address. -- `protocols`: a list of protocols supported by the node. A node should only advertise a - protocol if it is willing to receive inbound streams on that protocol. - {{< alert icon="💡" context="note" text="See the Identify technical specification for more details." />}} From 07414c68f526abd6aaf757debd324e7fb757aa50 Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Fri, 13 Jan 2023 02:57:54 -0500 Subject: [PATCH 03/11] edits --- content/concepts/introduction/protocols/identify.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/concepts/introduction/protocols/identify.md b/content/concepts/introduction/protocols/identify.md index 3dbf3e32..95caa8a6 100644 --- a/content/concepts/introduction/protocols/identify.md +++ b/content/concepts/introduction/protocols/identify.md @@ -4,7 +4,7 @@ description: "A way for nodes in libp2p to query and inform other nodes about th weight: 23 --- -The libp2p identify protocol is a way for nodes in a peer-to-peer network to share +The libp2p Identify protocol is a way for nodes in the libp2p network to share and query information about each other. This information includes: - the user agent: a free-form string identifying the node's implementation, usually From 9fa2e443ee579d22bcb5e1bb644a38c72951ffb2 Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Fri, 13 Jan 2023 07:00:35 -0500 Subject: [PATCH 04/11] edits --- content/concepts/introduction/protocols/identify.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/content/concepts/introduction/protocols/identify.md b/content/concepts/introduction/protocols/identify.md index 95caa8a6..62d5a801 100644 --- a/content/concepts/introduction/protocols/identify.md +++ b/content/concepts/introduction/protocols/identify.md @@ -9,7 +9,7 @@ and query information about each other. This information includes: - the user agent: a free-form string identifying the node's implementation, usually in the format "agent-name/version". -- the public IP address: the address of the node on the network, as seen by other nodes. +- the node's public IP address: the address of the node on the network, as seen by other nodes. - the list of multiaddresses that the node is listening on: the various network addresses and ports that the node can be reached at. - the list of protocols that the node supports: the different communication methods that @@ -17,11 +17,13 @@ and query information about each other. This information includes: There are two variations of the protocol: `identify` and `identify/push`. -The identify protocol, identified by the protocol ID `/ipfs/id/1.0.0`, is used +The Identify protocol, identified by the protocol ID `/ipfs/id/1.0.0`, is used to query a remote node for its metadata. To do so, a node opens a stream to the remote node and the remote node responds with an `Identify` message containing its metadata and closes the stream. + + The identify/push protocol, identified by the protocol ID `/ipfs/id/push/1.0.0`, is used to inform other nodes about changes in a node's metadata. When a node's metadata changes, it can "push" the new information to other nodes by opening @@ -31,4 +33,6 @@ remote node can update its local metadata repository with the information from t message, taking into account that missing fields should be ignored as the message may contain only partial updates. + + {{< alert icon="💡" context="note" text="See the Identify technical specification for more details." />}} From fa2a36079707b0bb71ceaabcb226affd517004df Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Wed, 25 Jan 2023 14:19:49 -0500 Subject: [PATCH 05/11] add note on identify delta --- content/concepts/introduction/protocols/identify.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/content/concepts/introduction/protocols/identify.md b/content/concepts/introduction/protocols/identify.md index 62d5a801..03d62650 100644 --- a/content/concepts/introduction/protocols/identify.md +++ b/content/concepts/introduction/protocols/identify.md @@ -33,6 +33,11 @@ remote node can update its local metadata repository with the information from t message, taking into account that missing fields should be ignored as the message may contain only partial updates. +{{< alert icon="" context="note">}} +It's worth noting that go-libp2p included a feature called 'Identify Delta' for some time, +but it has since been deprecated due to its complexity outweighing its usefulness. +{{< /alert >}} + {{< alert icon="💡" context="note" text="See the Identify technical specification for more details." />}} From 746de9155f4883e447623977ab37ff054470da83 Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Wed, 1 Feb 2023 08:34:36 -0500 Subject: [PATCH 06/11] Apply suggestions from code review Co-authored-by: Marten Seemann --- .../introduction/protocols/identify.md | 29 +++++++++---------- 1 file changed, 13 insertions(+), 16 deletions(-) diff --git a/content/concepts/introduction/protocols/identify.md b/content/concepts/introduction/protocols/identify.md index 03d62650..cf9709d9 100644 --- a/content/concepts/introduction/protocols/identify.md +++ b/content/concepts/introduction/protocols/identify.md @@ -5,37 +5,34 @@ weight: 23 --- The libp2p Identify protocol is a way for nodes in the libp2p network to share -and query information about each other. This information includes: +and query information about each other. It is usually run right after a new libp2p connection has been established, and at certain times during the lifetime of the connection. + +The information exchanged includes: - the user agent: a free-form string identifying the node's implementation, usually in the format "agent-name/version". - the node's public IP address: the address of the node on the network, as seen by other nodes. - the list of multiaddresses that the node is listening on: the various network addresses and ports that the node can be reached at. -- the list of protocols that the node supports: the different communication methods that - the node can understand and use to communicate with other nodes. +- the list of protocols that the node supports There are two variations of the protocol: `identify` and `identify/push`. -The Identify protocol, identified by the protocol ID `/ipfs/id/1.0.0`, is used -to query a remote node for its metadata. To do so, a node opens a stream to the -remote node and the remote node responds with an `Identify` message containing -its metadata and closes the stream. +The Identify protocol, for historical reasons identified by the protocol ID `/ipfs/id/1.0.0`, is used +to actively query a remote node for its metadata. The identify/push protocol, identified by the protocol ID `/ipfs/id/push/1.0.0`, -is used to inform other nodes about changes in a node's metadata. When a -node's metadata changes, it can "push" the new information to other nodes by opening -a stream to each of the nodes to be updated, and sending an `Identify` message -containing the updated metadata. Upon receiving the pushed `Identify` message, the -remote node can update its local metadata repository with the information from the -message, taking into account that missing fields should be ignored as the message may -contain only partial updates. +allows a node to push Identify data to the other node without having been queried. +This is used whenever changes to the data sent in Identify happen, e.g. when the node +starts listening on a new address, and when the node adds or removes support for +a protocol. {{< alert icon="" context="note">}} -It's worth noting that go-libp2p included a feature called 'Identify Delta' for some time, -but it has since been deprecated due to its complexity outweighing its usefulness. +It's worth noting that go-libp2p used to include a feature called 'Identify Delta' () for some time. +This protocol was used to reduce the size of Identify Pushes, but proved to be less useful (and a lot more complex) than expected. +It has since been deprecated, but a lot of nodes on the IPFS network still support this protocol. {{< /alert >}} From cdc2aeeb571290500d2dba87b46053dada1201d6 Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Wed, 1 Feb 2023 08:39:42 -0500 Subject: [PATCH 07/11] edits --- .../introduction/protocols/identify.md | 37 ++++++++++--------- 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/content/concepts/introduction/protocols/identify.md b/content/concepts/introduction/protocols/identify.md index cf9709d9..b4b07cb4 100644 --- a/content/concepts/introduction/protocols/identify.md +++ b/content/concepts/introduction/protocols/identify.md @@ -4,37 +4,38 @@ description: "A way for nodes in libp2p to query and inform other nodes about th weight: 23 --- -The libp2p Identify protocol is a way for nodes in the libp2p network to share -and query information about each other. It is usually run right after a new libp2p connection has been established, and at certain times during the lifetime of the connection. +The libp2p Identify protocol allows nodes in the libp2p network to share +and query information about each other. It is usually run right after a new libp2p +connection has been established and, at certain times, during the lifetime of the +connection. The information exchanged includes: - the user agent: a free-form string identifying the node's implementation, usually in the format "agent-name/version". -- the node's public IP address: the address of the node on the network, as seen by other nodes. +- the node's public IP address: the node's address on the network, as seen by other nodes. - the list of multiaddresses that the node is listening on: the various network addresses - and ports that the node can be reached at. -- the list of protocols that the node supports + and ports at which the node can be reached. +- the list of [protocols](/concepts/introduction/protocols/overview) that the + node supports. There are two variations of the protocol: `identify` and `identify/push`. -The Identify protocol, for historical reasons identified by the protocol ID `/ipfs/id/1.0.0`, is used -to actively query a remote node for its metadata. +The Identify protocol, for historical reasons identified by the protocol ID `/ipfs/id/1.0.0`, +is used to actively query a remote node for its metadata. The identify/push protocol, identified +by the protocol ID `/ipfs/id/push/1.0.0`, allows a node to push Identify data to the other node +without querying. This is used whenever changes to the data sent in Identify happen, +e.g., when the node starts listening on a new address and adds or removes support +for a protocol. -The identify/push protocol, identified by the protocol ID `/ipfs/id/push/1.0.0`, -allows a node to push Identify data to the other node without having been queried. -This is used whenever changes to the data sent in Identify happen, e.g. when the node -starts listening on a new address, and when the node adds or removes support for -a protocol. - {{< alert icon="" context="note">}} -It's worth noting that go-libp2p used to include a feature called 'Identify Delta' () for some time. -This protocol was used to reduce the size of Identify Pushes, but proved to be less useful (and a lot more complex) than expected. -It has since been deprecated, but a lot of nodes on the IPFS network still support this protocol. +It's worth noting that go-libp2p used to include a feature called 'Identify Delta' +() for some time. This protocol was used to reduce the size of +Identify Pushes, but proved to be less useful (and a lot more complex) than expected. +It has since been deprecated, but many nodes on the IPFS network still support +this protocol. {{< /alert >}} - - {{< alert icon="💡" context="note" text="See the Identify technical specification for more details." />}} From d66708096f90c87c67d1a230342bea4873603dab Mon Sep 17 00:00:00 2001 From: Max Inden Date: Mon, 20 Feb 2023 09:56:58 +0100 Subject: [PATCH 08/11] Mention protocol version --- content/concepts/introduction/protocols/identify.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/concepts/introduction/protocols/identify.md b/content/concepts/introduction/protocols/identify.md index b4b07cb4..1fe20f59 100644 --- a/content/concepts/introduction/protocols/identify.md +++ b/content/concepts/introduction/protocols/identify.md @@ -11,6 +11,7 @@ connection. The information exchanged includes: +- the protocol version: a network identifier, e.g. `/my-network/0.1.0`. - the user agent: a free-form string identifying the node's implementation, usually in the format "agent-name/version". - the node's public IP address: the node's address on the network, as seen by other nodes. From 3800c1d75594de7dbea05bf6189e173285a2cd62 Mon Sep 17 00:00:00 2001 From: Max Inden Date: Mon, 20 Feb 2023 10:00:18 +0100 Subject: [PATCH 09/11] Stress difference between local and remote node information --- content/concepts/introduction/protocols/identify.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/content/concepts/introduction/protocols/identify.md b/content/concepts/introduction/protocols/identify.md index 1fe20f59..562486e4 100644 --- a/content/concepts/introduction/protocols/identify.md +++ b/content/concepts/introduction/protocols/identify.md @@ -1,6 +1,6 @@ --- title: "Identify" -description: "A way for nodes in libp2p to query and inform other nodes about their metadata." +description: "A way for nodes in libp2p to query and inform remote nodes about their metadata." weight: 23 --- @@ -12,19 +12,18 @@ connection. The information exchanged includes: - the protocol version: a network identifier, e.g. `/my-network/0.1.0`. -- the user agent: a free-form string identifying the node's implementation, usually +- the user agent: a free-form string identifying the local node's implementation, usually in the format "agent-name/version". -- the node's public IP address: the node's address on the network, as seen by other nodes. -- the list of multiaddresses that the node is listening on: the various network addresses - and ports at which the node can be reached. +- the observed address: the remote node's public IP address as observed by the local node. +- the listen addresses: the multiaddresses at which the local node can be reached. - the list of [protocols](/concepts/introduction/protocols/overview) that the - node supports. + local node supports. There are two variations of the protocol: `identify` and `identify/push`. The Identify protocol, for historical reasons identified by the protocol ID `/ipfs/id/1.0.0`, is used to actively query a remote node for its metadata. The identify/push protocol, identified -by the protocol ID `/ipfs/id/push/1.0.0`, allows a node to push Identify data to the other node +by the protocol ID `/ipfs/id/push/1.0.0`, allows a node to push Identify data to the remote node without querying. This is used whenever changes to the data sent in Identify happen, e.g., when the node starts listening on a new address and adds or removes support for a protocol. From f50d03f82f9ce8067c9bb6287dc2ae423370fbf8 Mon Sep 17 00:00:00 2001 From: Max Inden Date: Mon, 20 Feb 2023 10:02:32 +0100 Subject: [PATCH 10/11] Remove TODO for diagram --- content/concepts/introduction/protocols/identify.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/content/concepts/introduction/protocols/identify.md b/content/concepts/introduction/protocols/identify.md index 562486e4..331d1a00 100644 --- a/content/concepts/introduction/protocols/identify.md +++ b/content/concepts/introduction/protocols/identify.md @@ -28,8 +28,6 @@ without querying. This is used whenever changes to the data sent in Identify hap e.g., when the node starts listening on a new address and adds or removes support for a protocol. - - {{< alert icon="" context="note">}} It's worth noting that go-libp2p used to include a feature called 'Identify Delta' () for some time. This protocol was used to reduce the size of From 5b2edc306823426b266aab5799ff322f01407ce0 Mon Sep 17 00:00:00 2001 From: Max Inden Date: Mon, 20 Feb 2023 10:04:59 +0100 Subject: [PATCH 11/11] Mention public key --- content/concepts/introduction/protocols/identify.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/concepts/introduction/protocols/identify.md b/content/concepts/introduction/protocols/identify.md index 331d1a00..db00d771 100644 --- a/content/concepts/introduction/protocols/identify.md +++ b/content/concepts/introduction/protocols/identify.md @@ -14,6 +14,7 @@ The information exchanged includes: - the protocol version: a network identifier, e.g. `/my-network/0.1.0`. - the user agent: a free-form string identifying the local node's implementation, usually in the format "agent-name/version". +- the public key: cryptographic identifier of the local node in the format of a peer ID. - the observed address: the remote node's public IP address as observed by the local node. - the listen addresses: the multiaddresses at which the local node can be reached. - the list of [protocols](/concepts/introduction/protocols/overview) that the