From 9c5b4d51a91f29265acfe0b6c24c306bf3420335 Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Sun, 15 Jan 2023 21:11:34 -0500 Subject: [PATCH 1/7] populate multistream-select --- .../introduction/protocols/multistream.md | 64 ++++++++++++++++++- 1 file changed, 62 insertions(+), 2 deletions(-) diff --git a/content/concepts/introduction/protocols/multistream.md b/content/concepts/introduction/protocols/multistream.md index 77d6a62f..7002523a 100644 --- a/content/concepts/introduction/protocols/multistream.md +++ b/content/concepts/introduction/protocols/multistream.md @@ -1,7 +1,67 @@ --- title: "Multistream Select" -description: "" +description: "Multistream Select is used to negotiate and upgrade the protocol of a connection between two peers in libp2p." weight: 26 --- -Coming soon! +## Overview + +[Multistream Select](https://github.com/multiformats/multistream-select) is +a protocol for friendly protocol multiplexing that allows for the negotiation +of a [multicodec](https://github.com/multiformats/multicodec) between two entities. + +> Multicodecs are codecs that can handle multiple different encoding formats. +> They are used to decode data and are self-describing, meaning they can identify +> the data format they are decoding. This capability allows nodes to support multiple +> protocols and efficiently switch between them depending on the task. + +Multistream is a general concept and refers to the ability +to [multiplex multiple streams](../../multiplex/overview.md) of data over a single +connection. This allows for multiple independent channels of communication to be +established over a single connection rather than needing to open a separate +connection for each channel. + +Multistream Select is a specific protocol built on top of the general +concept of Multistream. It is used to negotiate and upgrade the protocol of a +connection between two peers and to integrate new protocols as +they become available. The actual protocol is fairly simple - it is a Multistream +protocol with a Multistream header. + +The header refers to the initial message sent by a peer to initiate the protocol +negotiation process. This message includes the protocol ID, `/multistream/1.0.0.`, +which indicates to the listening peer that a protocol negotiation process is about +to take place. Upon receiving this header, the listening peer responds with their +desired protocol header. + +After both peers have sent their headers, both peers need to agree on the version +of the Multistream Select protocol to use for the connection. Both peers can exchange +protocol information and select the protocols to use for the connection, including +protocols for [security](../../secure-comm/overview.md) and +[stream multiplexing](../../multiplex/overview.md) if necessary. The +[protocol negotiation](../core-abstractions/connections#protocol-negotiation) +and [upgrade process](../core-abstractions/connections#upgrading-connections) +is explained further in the [connections document](../core-abstractions/connections.md). + +## Protocol Select + +[Protocol Select](https://github.com/libp2p/specs/pull/349) is a new +negotiation protocol that aims to improve and replace Multistream Select. +Multistream Select is prone to downgrade attacks and censorship, which is why +Protocol Select is being developed. Some other improvements include eliminating +the need for negotiating security protocols and reducing the number of round-trips +needed for stream multiplexer negotiation. Protocol Select also uses a binary +data format defined in a machine parseable schema language, making protocol +evolution and implementation more manageable and efficient. + +{{< alert icon="" context="warning">}} +Protocol Select is in active development and has yet to be fully implemented in +libp2p. Follow the official specification development +[here](https://github.com/libp2p/specs/pull/349). +{{< /alert >}} + +> Protocol Select will not be compatible with Multistream Select in its semantics +> as well as on the wire. Live libp2p-based networks, currently using Multistream Select, +> would need to follow a multiphased roll-out strategy detailed below to guarantee a +> smooth transition. + +{{< alert icon="💡" context="note" text="See the multistream-select technical specification for more details." />}} From 7b6059610b367c27d680307244fb9585dab27d14 Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Tue, 17 Jan 2023 05:21:34 -0500 Subject: [PATCH 2/7] edits --- content/concepts/introduction/protocols/multistream.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/content/concepts/introduction/protocols/multistream.md b/content/concepts/introduction/protocols/multistream.md index 7002523a..56e96b2c 100644 --- a/content/concepts/introduction/protocols/multistream.md +++ b/content/concepts/introduction/protocols/multistream.md @@ -48,7 +48,7 @@ is explained further in the [connections document](../core-abstractions/connecti negotiation protocol that aims to improve and replace Multistream Select. Multistream Select is prone to downgrade attacks and censorship, which is why Protocol Select is being developed. Some other improvements include eliminating -the need for negotiating security protocols and reducing the number of round-trips +the need for negotiating security protocols and reducing the number of roundtrips needed for stream multiplexer negotiation. Protocol Select also uses a binary data format defined in a machine parseable schema language, making protocol evolution and implementation more manageable and efficient. @@ -60,8 +60,7 @@ libp2p. Follow the official specification development {{< /alert >}} > Protocol Select will not be compatible with Multistream Select in its semantics -> as well as on the wire. Live libp2p-based networks, currently using Multistream Select, -> would need to follow a multiphased roll-out strategy detailed below to guarantee a -> smooth transition. +> as well as on the wire. Live libp2p-based networks currently using Multistream Select +> would need to follow a multiphased roll-out strategy to guarantee a smooth transition. {{< alert icon="💡" context="note" text="See the multistream-select technical specification for more details." />}} From ad6b88072767b6e4e55fea689be608710141693e Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Wed, 25 Jan 2023 13:58:53 -0500 Subject: [PATCH 3/7] incorporate PR feedback and simplify --- .../introduction/protocols/multistream.md | 71 ++++--------------- 1 file changed, 14 insertions(+), 57 deletions(-) diff --git a/content/concepts/introduction/protocols/multistream.md b/content/concepts/introduction/protocols/multistream.md index 56e96b2c..610c30d1 100644 --- a/content/concepts/introduction/protocols/multistream.md +++ b/content/concepts/introduction/protocols/multistream.md @@ -1,66 +1,23 @@ --- title: "Multistream Select" -description: "Multistream Select is used to negotiate and upgrade the protocol of a connection between two peers in libp2p." +description: "Multistream Select is used to negotiate the protocol of a connection between two peers in libp2p." weight: 26 --- ## Overview -[Multistream Select](https://github.com/multiformats/multistream-select) is -a protocol for friendly protocol multiplexing that allows for the negotiation -of a [multicodec](https://github.com/multiformats/multicodec) between two entities. - -> Multicodecs are codecs that can handle multiple different encoding formats. -> They are used to decode data and are self-describing, meaning they can identify -> the data format they are decoding. This capability allows nodes to support multiple -> protocols and efficiently switch between them depending on the task. - -Multistream is a general concept and refers to the ability -to [multiplex multiple streams](../../multiplex/overview.md) of data over a single -connection. This allows for multiple independent channels of communication to be -established over a single connection rather than needing to open a separate -connection for each channel. - -Multistream Select is a specific protocol built on top of the general -concept of Multistream. It is used to negotiate and upgrade the protocol of a -connection between two peers and to integrate new protocols as -they become available. The actual protocol is fairly simple - it is a Multistream -protocol with a Multistream header. - -The header refers to the initial message sent by a peer to initiate the protocol -negotiation process. This message includes the protocol ID, `/multistream/1.0.0.`, -which indicates to the listening peer that a protocol negotiation process is about -to take place. Upon receiving this header, the listening peer responds with their -desired protocol header. - -After both peers have sent their headers, both peers need to agree on the version -of the Multistream Select protocol to use for the connection. Both peers can exchange -protocol information and select the protocols to use for the connection, including -protocols for [security](../../secure-comm/overview.md) and -[stream multiplexing](../../multiplex/overview.md) if necessary. The -[protocol negotiation](../core-abstractions/connections#protocol-negotiation) -and [upgrade process](../core-abstractions/connections#upgrading-connections) -is explained further in the [connections document](../core-abstractions/connections.md). - -## Protocol Select - -[Protocol Select](https://github.com/libp2p/specs/pull/349) is a new -negotiation protocol that aims to improve and replace Multistream Select. -Multistream Select is prone to downgrade attacks and censorship, which is why -Protocol Select is being developed. Some other improvements include eliminating -the need for negotiating security protocols and reducing the number of roundtrips -needed for stream multiplexer negotiation. Protocol Select also uses a binary -data format defined in a machine parseable schema language, making protocol -evolution and implementation more manageable and efficient. - -{{< alert icon="" context="warning">}} -Protocol Select is in active development and has yet to be fully implemented in -libp2p. Follow the official specification development -[here](https://github.com/libp2p/specs/pull/349). -{{< /alert >}} - -> Protocol Select will not be compatible with Multistream Select in its semantics -> as well as on the wire. Live libp2p-based networks currently using Multistream Select -> would need to follow a multiphased roll-out strategy to guarantee a smooth transition. +[Multistream Select](https://github.com/multiformats/multistream-select) is a protocol for +protocol multiplexing that allows for the negotiation of different protocols between two +entities. It is a specific protocol built on top of the general concept of Multistream. +It is used to negotiate the protocol of a connection between two peers and to integrate +new protocols as they become available. Every multistream message is prefixed with a +header, `/multistream/1.0.0`. + +Peers use Multistream Select at various places to select the protocols to use for a +libp2p connection, including [transports](../../transports/overview.md), +[security](../../secure-comm/overview.md), and [stream multiplexing](../../multiplex/overview.md) +as necessary. The [protocol negotiation](../core-abstractions/connections#protocol-negotiation) +and [upgrade process](../core-abstractions/connections#upgrading-connections) are explained +further in the [connections document](../core-abstractions/connections.md). {{< alert icon="💡" context="note" text="See the multistream-select technical specification for more details." />}} From e6b6fdbcd22b01f79c4bdc541458e20e6df22e1a Mon Sep 17 00:00:00 2001 From: Prithvi Shahi <50885601+p-shahi@users.noreply.github.com> Date: Mon, 13 Feb 2023 10:53:30 -0800 Subject: [PATCH 4/7] Apply suggestions from code review Co-authored-by: Marten Seemann --- content/concepts/introduction/protocols/multistream.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/content/concepts/introduction/protocols/multistream.md b/content/concepts/introduction/protocols/multistream.md index 610c30d1..e857749a 100644 --- a/content/concepts/introduction/protocols/multistream.md +++ b/content/concepts/introduction/protocols/multistream.md @@ -8,13 +8,10 @@ weight: 26 [Multistream Select](https://github.com/multiformats/multistream-select) is a protocol for protocol multiplexing that allows for the negotiation of different protocols between two -entities. It is a specific protocol built on top of the general concept of Multistream. -It is used to negotiate the protocol of a connection between two peers and to integrate -new protocols as they become available. Every multistream message is prefixed with a -header, `/multistream/1.0.0`. +peers. Peers use Multistream Select at various places to select the protocols to use for a -libp2p connection, including [transports](../../transports/overview.md), +libp2p connection, including [security](../../secure-comm/overview.md), and [stream multiplexing](../../multiplex/overview.md) as necessary. The [protocol negotiation](../core-abstractions/connections#protocol-negotiation) and [upgrade process](../core-abstractions/connections#upgrading-connections) are explained From 67d6f208015706173542352fc820aacc57fcd8bd Mon Sep 17 00:00:00 2001 From: Max Inden Date: Fri, 24 Feb 2023 19:13:13 +0100 Subject: [PATCH 5/7] Rephrase title and include stream negotiation --- content/concepts/introduction/protocols/multistream.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/concepts/introduction/protocols/multistream.md b/content/concepts/introduction/protocols/multistream.md index e857749a..fdf18f80 100644 --- a/content/concepts/introduction/protocols/multistream.md +++ b/content/concepts/introduction/protocols/multistream.md @@ -1,6 +1,6 @@ --- title: "Multistream Select" -description: "Multistream Select is used to negotiate the protocol of a connection between two peers in libp2p." +description: "Multistream Select is used to negotiate the protocol to be spoken on a connection or stream." weight: 26 --- From 6fd10159fb2610496a4b96b5d9b19e165cb8b6d4 Mon Sep 17 00:00:00 2001 From: Max Inden Date: Fri, 24 Feb 2023 19:14:25 +0100 Subject: [PATCH 6/7] Fix multistream select not being a multiplexing protocol --- content/concepts/introduction/protocols/multistream.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/concepts/introduction/protocols/multistream.md b/content/concepts/introduction/protocols/multistream.md index fdf18f80..62f27bd3 100644 --- a/content/concepts/introduction/protocols/multistream.md +++ b/content/concepts/introduction/protocols/multistream.md @@ -6,9 +6,9 @@ weight: 26 ## Overview -[Multistream Select](https://github.com/multiformats/multistream-select) is a protocol for -protocol multiplexing that allows for the negotiation of different protocols between two -peers. +[Multistream Select](https://github.com/multiformats/multistream-select) is a +protocol negotiation protocol. It allows two peers to negotiate the next spoken +protocol on a connection or stream. Peers use Multistream Select at various places to select the protocols to use for a libp2p connection, including From 0fb3637f4964885ceb6ddc74236f36c666b46ef5 Mon Sep 17 00:00:00 2001 From: Max Inden Date: Fri, 24 Feb 2023 19:18:53 +0100 Subject: [PATCH 7/7] Rephrase central paragraph, mentioning stream protocol negotiation --- .../concepts/introduction/protocols/multistream.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/content/concepts/introduction/protocols/multistream.md b/content/concepts/introduction/protocols/multistream.md index 62f27bd3..cb2d8328 100644 --- a/content/concepts/introduction/protocols/multistream.md +++ b/content/concepts/introduction/protocols/multistream.md @@ -10,11 +10,14 @@ weight: 26 protocol negotiation protocol. It allows two peers to negotiate the next spoken protocol on a connection or stream. -Peers use Multistream Select at various places to select the protocols to use for a -libp2p connection, including -[security](../../secure-comm/overview.md), and [stream multiplexing](../../multiplex/overview.md) -as necessary. The [protocol negotiation](../core-abstractions/connections#protocol-negotiation) -and [upgrade process](../core-abstractions/connections#upgrading-connections) are explained +Peers use Multistream Select at various places to select the protocols to use on +a libp2p connection or stream. Most prominently Multistream Select is used to +select the [security](../../secure-comm/overview.md) followed by [stream +multiplexing](../../multiplex/overview.md) protocol spoken on a connection. In +addition it is used to select the application protocol (e.g. Kademlia) on each +new stream on a given connection. The [protocol +negotiation](../core-abstractions/connections#protocol-negotiation) and [upgrade +process](../core-abstractions/connections#upgrading-connections) are explained further in the [connections document](../core-abstractions/connections.md). {{< alert icon="💡" context="note" text="See the multistream-select technical specification for more details." />}}