update: fundamentals protocols doc

[salmad3]

Context

• Adds one table to list protocols as opposed to different sections that summarize certain protocols. The section mentions the implementation page and includes the official spec in one of the table columns.
• General writing style updates.
• With the current content flow, it pushes the doc as the first concept doc part of "Core components" with a weight of "1".
• Part of Improve Protocol Documentation. #120

Latest preview

Please view the latest Fleek preview here.

[salmad3]

Thanks @p-shahi! Table has been updated.

What should we include for QUIC? Also, not too sure about the protocol IDs for QUIC, WebTransport, and GossipSub.

[p-shahi]

Thanks @p-shahi! Table has been updated.

What should we include for QUIC? Also, not too sure about the protocol IDs for QUIC, WebTransport, and GossipSub.

I couldn't find the protocol ID for QUIC or WebTransport either but it seems for GossipSub v1.1 peers advertise /meshsub/1.1.0 as the protocol string

[marten-seemann]

libp2p has been moving away from using versions in protocol IDs. It's not really clear how semver applies to protocols. In most cases, it just makes more sense to just define a new protocol ID, and test if the peer supports that one.

[marten-seemann]

Do we have a separate doc describing multistream? If so, it would be helpful to link to that document. If not, we should probably add a section explaining how multistream works. We use a lot of multistream concepts here without even mentioning multistream, which can be confusing.

[salmad3]

We don't have a specific doc for multistream, it is planned in this issue. But there is a protocol negotiation section on this doc which I added mention of multistream too

[filecorgi]

• Image optimization came back clean!
• Hugo build was successful!
  found div [

Protocols

This article is concerned with protocols that compose libp2p using core libp2p abstractions like the transport, peer identity, addressing abstractions to name a few.

What is a libp2p protocol?

A libp2p protocol is a network protocol that includes the key features mentioned below.

Protocol IDs

libp2p protocols have unique string identifiers, which are used in the protocol negotiation process when streams are first opened.

Historically, the IDs of many protocols in use by libp2p have a path-like structure, with a version number as the final component:

Breaking changes to a protocol’s wire format or semantics should result in a new version number. See the protocol negotiation section for more information about how version selection works during the dialing and listening.

Handler functions

A libp2p application will define a stream handler that takes over the stream after protocol negotiation. Everything sent and received after the negotiation phase is then defined by the application protocol.

The handler function is invoked when an incoming stream is received with the registered protocol ID. If you register a handler with a match function, you can choose whether to accept non-exact string matches for protocol ids, for example, to match on semantic major versions.

Binary streams

The “medium” over which a libp2p protocol transpires is a bi-directional binary stream with the following properties:

• Bidirectional, reliable delivery of binary data
  • Each side can read and write from the stream at any time
  • Data is read in the same order as it was written
  • Can be “half-closed”, that is, closed for writing and open for reading, or closed for reading and open for writing
• Supports backpressure
  • Eager writers can’t flood readers

Behind the scenes, libp2p will also ensure that the stream is secure and efficiently multiplexed. This is transparent to the protocol handler, which reads and writes unencrypted binary data over the stream.

The protocol determines the binary data format and the transport mechanics. For inspiration, some common patterns that are used in libp2p’s internal protocols are outlined below.

Life cycle of a stream

Libp2p streams are an abstraction Libp2p protocols can have sub-protocols or protocol-suites. It isn’t easy to select and route protocols, or even know which protocols are available.

Multistream-select is a protocol multiplexer that negotiates the application-layer protocol. When a new stream is created, it is run through multistream-select, which routes the stream to the appropriate protocol handler.

When dialing out to initiate a new stream, libp2p sends the protocol ID of the protocol you want to use. The listening peer on the other end checks the incoming protocol ID against the registered protocol handlers.

If the listening peer does not support the requested protocol, it will send “na” on the stream, and the dialing peer can try again with a different protocol or possibly a fallback version of the initially requested protocol.

If the protocol is supported, the listening peer will echo back the protocol ID as a signal that future data sent over the stream will use the agreed protocol semantics.

This process of reaching an agreement about what protocol to use for a given stream or connection is called protocol negotiation.

Not to be mistaken with stream multiplexers, which are solely responsible for the internal streams on a connection and aren’t concerned with underlying protocol being used.

Core libp2p protocols

In addition to the protocols written when developing a libp2p application, libp2p defines several foundational protocols used for core features.

Check out the libp2p implementations page for updates on all the libp2p implementations.

Specification	Protocol ID
AutoNAT	/libp2p/autonat/1.0.0
Circuit Relay v2 (hop)	/libp2p/circuit/relay/0.2.0/hop
Circuit Relay v2 (stop)	/libp2p/circuit/relay/0.2.0/stop
DCUtR	/libp2p/dcutr/1.0.0
Fetch	/libp2p/fetch/0.0.1
GossipSub v1.0	/libp2p/gossipsub/1.0.0
GossipSub v1.1	/libp2p/gossipsub/1.1.0
Identify	/ipfs/id/1.0.0
Identify (push)	/ipfs/id/push/1.0.0
Kademlia DHT	/ipfs/kad/1.0.0
Ping	/ipfs/ping/1.0.0
Rendezvous	/libp2p/rendezvous/1.0.0

]

[salmad3]

New reference replaces this PR.