From b5602b9ba9beceeea9e9735822e1eb638242a82e Mon Sep 17 00:00:00 2001 From: Thomas Eizinger Date: Fri, 16 Jul 2021 14:02:16 +1000 Subject: [PATCH 1/5] Create dedicated document for identify v1.0.0 --- identify/{README.md => identify-v1.0.0.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename identify/{README.md => identify-v1.0.0.md} (100%) diff --git a/identify/README.md b/identify/identify-v1.0.0.md similarity index 100% rename from identify/README.md rename to identify/identify-v1.0.0.md From 31e053cccea1f694b706e7f64574ecfd3f0e4980 Mon Sep 17 00:00:00 2001 From: Thomas Eizinger Date: Fri, 16 Jul 2021 14:05:28 +1000 Subject: [PATCH 2/5] Introduce new README listing both protocols --- identify/README.md | 11 +++++++++++ identify/identify-v2.0.0.md | 1 + 2 files changed, 12 insertions(+) create mode 100644 identify/README.md create mode 100644 identify/identify-v2.0.0.md diff --git a/identify/README.md b/identify/README.md new file mode 100644 index 000000000..f3af68464 --- /dev/null +++ b/identify/README.md @@ -0,0 +1,11 @@ +# Identify + +> The identify protocol is used to exchange basic information with other peers +> in the network, including addresses, public keys, and capabilities. + +## Versions + +There are currently two versions of the identify protocol: + +- `/p2p/id/2.0.0`: [identify-v2.0.0.md](./identify-v2.0.0.md) +- `/ipfs/id/1.0.0`: [identify-v1.0.0.md](./identify-v1.0.0.md) diff --git a/identify/identify-v2.0.0.md b/identify/identify-v2.0.0.md new file mode 100644 index 000000000..c2e93e5cb --- /dev/null +++ b/identify/identify-v2.0.0.md @@ -0,0 +1 @@ +# Identify v2.0.0 From 1d715ffcb542a5eab9efdff12fbe89bd93a08715 Mon Sep 17 00:00:00 2001 From: Thomas Eizinger Date: Fri, 16 Jul 2021 14:27:21 +1000 Subject: [PATCH 3/5] Specify identify v2.0.0 --- identify/identify-v2.0.0.md | 97 +++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) diff --git a/identify/identify-v2.0.0.md b/identify/identify-v2.0.0.md index c2e93e5cb..bbfcffe5c 100644 --- a/identify/identify-v2.0.0.md +++ b/identify/identify-v2.0.0.md @@ -1 +1,98 @@ # Identify v2.0.0 + +| Lifecycle Stage | Maturity Level | Status | Latest Revision | +|-----------------|----------------|--------|-----------------| +| 1A | Draft | Active | r0, 2021-07-16 | + +Authors: [@thomaseizinger] + +Interest Group: [@yusefnapora], [@tomaka], [@richardschneider], [@Stebalien], [@bigs], [@vyzo] + +[@thomaseizinger]: https://github.com/bigs +[@vyzo]: https://github.com/vyzo +[@yusefnapora]: https://github.com/yusefnapora +[@tomaka]: https://github.com/tomaka +[@richardschneider]: https://github.com/richardschneider +[@Stebalien]: https://github.com/Stebalien +[@bigs]: https://github.com/bigs + +See the [lifecycle document][lifecycle-spec] for context about maturity level +and spec status. + +[lifecycle-spec]: https://github.com/libp2p/specs/blob/master/00-framework-01-spec-lifecycle.md + +## Table of Contents + +- [Identify v2.0.0](#identify-v200) + - [Table of Contents](#table-of-contents) + - [Overview](#overview) + - [`identify`](#identify) + - [`identify/push`](#identifypush) + - [The Identify Message](#the-identify-message) + - [signedPeerRecords](#signedpeerrecords) + - [observedAddr](#observedaddr) + - [protocols](#protocols) + - [protocolVersion](#protocolversion) + - [agentVersion](#agentversion) + +## Overview + +Version v2.0.0 of the identify protocol brings two minor changes. + +1. The use of a new protocol identifier in the spirit of decoupling libp2p protocols from ipfs. +2. Suppport for signed peer records instead of plain addresses. + +Same as for v1.0.0, there are two variations of the identify protocol, `identify` and `identify/push`. +The behaviour is equivalent to v1.0.0. + +### `identify` + +The `identify` protocol has the protocol id `/p2p/id/2.0.0`, and it is used +to query remote peers for their information. + +### `identify/push` + +The `identify/push` protocol has the protocol id `/p2p/id/push/2.0.0`, and it is used +to inform known peers about changes that occur at runtime. + +## The Identify Message + +```protobuf +message Identify { + optional string protocolVersion = 4; + optional string agentVersion = 5; + repeated bytes signedPeerRecord = 1; + optional bytes observedAddr = 3; + repeated string protocols = 2; +} +``` + +### Differences to `/ipfs/id/1.0.0` + +- `listenAddrs` is replaced with `signedPeerRecord` +- `publicKey` is removed because it is embedded within `signedPeerRecord` + +### signedPeerRecord + +A signed peer record that certifies the addresses a peer is listening on. + +### protocols + +Unchanged from `/ipfs/id/1.0.0`. + +### observedAddr + +Unchanged from `/ipfs/id/1.0.0`. + +### protocolVersion + +Unchanged from `/ipfs/id/1.0.0`. + +### agentVersion + +Unchanged from `/ipfs/id/1.0.0`. + +## Behaviour + +The public key embedded in the signed peer record MUST match the public key of +the connected peer as defined through the security protocol (e.g. noise). From d8c944dfbf9d3e40e7a4a6be8bf7e0feef4b8895 Mon Sep 17 00:00:00 2001 From: Thomas Eizinger Date: Fri, 16 Jul 2021 14:27:42 +1000 Subject: [PATCH 4/5] Deprecate 1.0.0 in favor of 2.0.0 --- identify/README.md | 2 ++ identify/identify-v1.0.0.md | 6 +++--- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/identify/README.md b/identify/README.md index f3af68464..f5345285e 100644 --- a/identify/README.md +++ b/identify/README.md @@ -9,3 +9,5 @@ There are currently two versions of the identify protocol: - `/p2p/id/2.0.0`: [identify-v2.0.0.md](./identify-v2.0.0.md) - `/ipfs/id/1.0.0`: [identify-v1.0.0.md](./identify-v1.0.0.md) + +`/ipfs/id/1.0.0` is considered deprecated. `/p2p/id/2.0.0` should be used instead. \ No newline at end of file diff --git a/identify/identify-v1.0.0.md b/identify/identify-v1.0.0.md index d83a85d05..fe702cfc1 100644 --- a/identify/identify-v1.0.0.md +++ b/identify/identify-v1.0.0.md @@ -3,9 +3,9 @@ > The identify protocol is used to exchange basic information with other peers > in the network, including addresses, public keys, and capabilities. -| Lifecycle Stage | Maturity Level | Status | Latest Revision | -|-----------------|----------------|--------|-----------------| -| 3A | Recommendation | Active | r0, 2019-05-01 | +| Lifecycle Stage | Maturity Level | Status | Latest Revision | +|-----------------|----------------|------------|-----------------| +| 3D | Recommendation | Deprecated | r0, 2019-05-01 | Authors: [@vyzo] From 7d2e40116a7fb37d04a4b0538ad4e47acc6bde83 Mon Sep 17 00:00:00 2001 From: Thomas Eizinger Date: Fri, 16 Jul 2021 14:31:12 +1000 Subject: [PATCH 5/5] fixup! Specify identify v2.0.0 --- identify/identify-v2.0.0.md | 1 + 1 file changed, 1 insertion(+) diff --git a/identify/identify-v2.0.0.md b/identify/identify-v2.0.0.md index bbfcffe5c..f5c4d76b7 100644 --- a/identify/identify-v2.0.0.md +++ b/identify/identify-v2.0.0.md @@ -29,6 +29,7 @@ and spec status. - [`identify`](#identify) - [`identify/push`](#identifypush) - [The Identify Message](#the-identify-message) + - [Differences to `/ipfs/id/1.0.0`](#differences-to-ipfsid100) - [signedPeerRecords](#signedpeerrecords) - [observedAddr](#observedaddr) - [protocols](#protocols)