Throughout this guide, numbers
highlighted in purple can be configured
@@ -142,7 +148,7 @@ performs functions to help maintain the network of full-message peerings.
+between two peers”.](../assets/publish-subscribe/metadata_only_network.png)
## Grafting and pruning
@@ -163,7 +169,7 @@ on the right. In the following step, the line becomes thick, dark and is now
labelled “Full-message peering”. The second process is the reverse of the first
process; two dots are connected by a thick, dark line which becomes a thin,
light line labelled “Metadata-only peering”. The speech bubble reads “I’m
-pruning our connection back to a metadata-only peering.”](graft_prune.png)
+pruning our connection back to a metadata-only peering.”](../assets/publish-subscribe/graft_prune.png)
When a peer has too few full-message peerings it will randomly graft some of its
metadata-only peerings to become full-message peerings:
@@ -182,7 +188,7 @@ now highlighted lines. Four circles in the series are also highlighted green, up
to the circle labelled “Ideal”. The panel is titled “Select more peers to graft
to get to the ideal number”. In the final panel the highlighted green lines and
dots have become dark to indicate they have become full-content peerings. The
-title reads “Grafting complete”.](maintain_graft.png)
+title reads “Grafting complete”.](../assets/publish-subscribe/maintain_graft.png)
Conversely, when a peer has too many full-message peerings it will randomly
prune some of them back to metadata-only:
@@ -203,7 +209,7 @@ series are also highlighted pink, from the end down to the circle labelled
“Ideal”. The panel is titled “Select peers to prune to get the ideal number”. In
the final panel the highlighted pink lines and dots have become light to
indicate they have become metadata-only peerings. The title reads “Pruning
-complete”.](maintain_prune.png)
+complete”.](../assets/publish-subscribe/maintain_prune.png)
In libp2p’s implementation, each peer performs a series of checks every
1 second. These checks are called the
@@ -224,7 +230,7 @@ from “Topic 1” to “Topic 5”. The shaded areas fade out with distance fro
large, central dot indicating that the peer’s perspective has limited range.
One of the smaller dots that does not share a shaded area with the large dot is
labelled “Peers keep track of other’s subscriptions even if not subscribed to
-the same topics as them”.](subscriptions_local_view.png)
+the same topics as them”.](../assets/publish-subscribe/subscriptions_local_view.png)
Keeping track of subscriptions happens by sending **subscribe** and
**unsubscribe** messages. When a new connection is established between two peers
@@ -234,7 +240,7 @@ they start by sending each other the list of topics they are subscribed to:
speech bubble emanating from it with an arrow showing it moving along the
connecting line towards the other dot. The left dot’s speech bubble says “I am
subscribed to: Topic 1, Topic 2, Topic 3”. The right dot’s speech bubble says “I
-am subscribed to: Topic 1, Topic 5”.](subscription_list_first_connect.png)
+am subscribed to: Topic 1, Topic 5”.](../assets/publish-subscribe/subscription_list_first_connect.png)
Then over time, whenever a peer subscribes or unsubscribes from a topic, it will
send each of its peers a subscribe or unsubscribe message. These messages are
@@ -244,7 +250,7 @@ subscribed to the topic in question:
+subscribed to: Topic 5. I am unsubscribed from: Topic 2, Topic 3.”](../assets/publish-subscribe/subscription_list_change.png)
Subscribe and unsubscribe messages go hand-in-hand with graft and prune
messages. When a peer subscribes to a topic it will pick some peers that will
@@ -261,7 +267,7 @@ subscribed to Topic 3. Also, I’m grafting our connection into a full-message
peering.” The next panel shows the same three dots, however the central dot is
now inside the shaded area labelled “Topic 3” and the line connecting the
central and right dots has become thick and dark indicating a full-message
-peering.](subscribe_graft.png)
+peering.](../assets/publish-subscribe/subscribe_graft.png)
When a peer unsubscribes from a topic it will notify its full-message peers that
their connection has been pruned at the same time as sending their unsubscribe
@@ -280,7 +286,7 @@ pruning our connection back to a metadata-only peering.” The next panel shows
the same three dots, however the central dot is no longer inside the area
labelled “Topic 3” and the line connecting the central and right dots has become
thin and light like the left line to indicate a metadata-only
-peering.](unsubscribe_prune.png)
+peering.](../assets/publish-subscribe/unsubscribe_prune.png)
## Sending messages
@@ -292,7 +298,7 @@ panel is titled “Peer creates new message of its own”. A small, unlabelled
speech bubble emanates from a dot. The dot has four thick, dark lines radiating
outward from it. The second panel is titled “Message sent to all other
full-message peers”. It shows four copies of the speech bubble now moving away
-from the dot along each of the four lines.](full_message_send.png)
+from the dot along each of the four lines.](../assets/publish-subscribe/full_message_send.png)
Similarly, when a peer receives a new message from another peer, it stores the
message and forwards a copy to all other full-message peers it is connected to:
@@ -305,7 +311,7 @@ thick, dark lines radiating outward from the dot. The second panel is titled
outward. The speech bubble is now centred above the dot. The final panel is
titled “Message forwarded to all other full-message peers”. It shows three
copies of the speech bubble now moving away from the dot along the three lines
-that the speech bubble has not appeared on yet.](full_message_forward.png)
+that the speech bubble has not appeared on yet.](../assets/publish-subscribe/full_message_forward.png)
In the [gossipsub specification](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md#controlling-the-flood),
peers are also known as *routers* because of this function they have in routing
@@ -340,7 +346,7 @@ from the central dot. The six speech bubbles are identical and read “I have
seen:” followed by three small speech bubble symbols inside the larger speech
bubble, in different shades of purple to indicate three different messages.
One of the small purple speech bubbles is labelled “Seen messages specify the
-sender and sequence number, but not the full message contents”.](gossip_deliver.png)
+sender and sequence number, but not the full message contents”.](../assets/publish-subscribe/gossip_deliver.png)
Gossiping gives peers a chance to notice in case they missed a message on the
full-message network. If a peer notices it is repeatedly missing messages then
@@ -377,7 +383,7 @@ now a purple speech bubble travelling along the line connecting the two dots
from left to right. The final panel is titled “Newly received message is
broadcast to full-content peers”. There are now three copies of the purple
speech bubble travelling outwards from the right dot along the three thick, dark
-lines connected to it.](request_gossiped_message.png)
+lines connected to it.](../assets/publish-subscribe/request_gossiped_message.png)
In the [gossipsub specification](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md#control-messages),
gossip announcing recently seen messages are called *IHAVE* messages and
@@ -407,7 +413,7 @@ connecting the outside dot to dots inside the shaded area have become blue and
now have arrowheads at the end pointing towards the peer inside the shaded area
they are connected to. These lines represent fan-out peerings. A dice symbol is
present indicating random selection of which metadata-only peerings became
-fan-out peerings.](fanout_initial_pick.png)
+fan-out peerings.](../assets/publish-subscribe/fanout_initial_pick.png)
Unlike the other types of peering, fan-out peerings are unidirectional; they
always point from the peer outside the topic to a peer subscribed to the topic.
@@ -427,7 +433,7 @@ peers subscribed to the topic. The second panel is titled “Once inside the
topic, the message is forwarded to all other subscribers as usual”. The purple
speech bubbles have moved from outside the shaded area to inside out. Now there
is a copy of the speech bubble above every dot in the shaded
-area.](fanout_message_send.png)
+area.](../assets/publish-subscribe/fanout_message_send.png)
If the sender goes to send a message but notices some of their fan-out peers
went away since last time, they will randomly select additional fan-out peers
@@ -450,7 +456,7 @@ peer that was previously outside the shaded area is now inside it, representing
that it is now subscribed to the topic. The three previously-blue arrows have
become thick, dark lines representing former fan-out peerings becoming
full-message peerings. The other lines from the dot are still thin and light as
-before.](fanout_grafting_preference.png)
+before.](../assets/publish-subscribe/fanout_grafting_preference.png)
After 2 minutes of not sending any messages to
a topic, all the fan-out peers for that topic are forgotten:
@@ -463,7 +469,7 @@ minutes…” There is a stopwatch above the single dot indicating the passage o
time. The second panel is titled “All fan-out peerings revert to metadata-only
peerings”. In this panel the three previously blue, arrowed lines connecting
the single dot to dots inside the shaded area have become thin and light,
-representing the peer’s fan-out peerings becoming metadata-only peerings.](fanout_forget.png)
+representing the peer’s fan-out peerings becoming metadata-only peerings.](../assets/publish-subscribe/fanout_forget.png)
## Network packets
@@ -507,7 +513,7 @@ columns, similar to the previous table. The first column is titled “For this
topic…”, however the second column is titled “You have been…” with the choice of
grafted or pruned. There are three rows in this table. Two of the topics
have been grafted and one has been pruned (no particular connection to the
-previous table).](network_packet_structure.png)
+previous table).](../assets/publish-subscribe/network_packet_structure.png)
See the [specification](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md#protobuf) for the exact [Protocol Buffers](https://developers.google.com/protocol-buffers)
schema used to encode network packets.
@@ -560,7 +566,7 @@ the full message column is empty. These rows only have the sender (Peer ID),
sequence number and time first seen columns populated. The table rows are
listed in order of time first seen, from 1 second ago in the top row to 90
seconds ago in the bottom row. Some of the sequence numbers are shared between
-messages, but only where the sender is different.](state.png)
+messages, but only where the sender is different.](../assets/publish-subscribe/state.png)
## More information
diff --git a/content/concepts/secure-comm/_index.md b/content/concepts/secure-comm/_index.md
new file mode 100644
index 00000000..c9a1d105
--- /dev/null
+++ b/content/concepts/secure-comm/_index.md
@@ -0,0 +1,17 @@
+---
+title: "Secure Communication"
+weight: 3
+pre: ' '
+chapter: true
+summary: Before two peers can transmit data, the communication channel they established with a transport protocol should be secure. Learn about secure channels in libp2p.
+---
+
+# Secure bytes
+
+Before two peers can transmit data, the communication channel they established
+with a transport protocol should be secure. A transport protocol like QUIC provides
+security guarantees out-of-the-box, but other transports in libp2p do not provide the
+logic to secure their channel. This requires an upgrade to the transport using an upgrader.
+Security is always established first over the raw connection.
+
+{{% children description="true"%}}
diff --git a/content/concepts/secure-comm/noise.md b/content/concepts/secure-comm/noise.md
new file mode 100644
index 00000000..ab126a6f
--- /dev/null
+++ b/content/concepts/secure-comm/noise.md
@@ -0,0 +1,13 @@
+---
+title: "Noise"
+weight: 1
+pre: ' '
+chapter: true
+summary: Learn about Noise in libp2p.
+---
+
+# Noise
+
+{{% notice "note" %}}
+Coming soon!
+{{% /notice %}}
diff --git a/content/concepts/secure-comm/tls.md b/content/concepts/secure-comm/tls.md
new file mode 100644
index 00000000..5aa05ff7
--- /dev/null
+++ b/content/concepts/secure-comm/tls.md
@@ -0,0 +1,13 @@
+---
+title: "TLS"
+weight: 2
+pre: ' '
+chapter: true
+summary: Learn about TLS 1.3 in libp2p.
+---
+
+# TLS
+
+{{% notice "note" %}}
+Coming soon!
+{{% /notice %}}
diff --git a/content/concepts/secure-comms.md b/content/concepts/secure-comms.md
deleted file mode 100644
index c6512a46..00000000
--- a/content/concepts/secure-comms.md
+++ /dev/null
@@ -1,8 +0,0 @@
----
-title: Secure Communication
-weight: 2
----
-
-This article is coming soon!
-
-Please [refer to this issue](https://github.com/libp2p/docs/issues/19) to track the progress and make suggestions.
diff --git a/content/concepts/security-considerations.md b/content/concepts/security/security-considerations.md
similarity index 94%
rename from content/concepts/security-considerations.md
rename to content/concepts/security/security-considerations.md
index ce845d9b..5b2944a1 100644
--- a/content/concepts/security-considerations.md
+++ b/content/concepts/security/security-considerations.md
@@ -1,10 +1,15 @@
---
-title: 'Security Considerations'
-weight: 12
+title: "Security Considerations"
+weight: 10
+pre: ' '
+chapter: true
+summary: libp2p makes it simple to establish encrypted, authenticated communication channels between two peers, but there are other important security issues to consider when building robust peer-to-peer systems.
---
-libp2p makes it simple to establish [encrypted, authenticated communication
-channels](../secure-comms/) between two peers, but there are other important
+# Secure Data
+
+libp2p makes it simple to establish encrypted, authenticated communication
+channels between two peers, but there are other important
security issues to consider when building robust peer-to-peer systems.
Many of the issues described here have no known "perfect solution," and the
diff --git a/content/concepts/stream-multiplexing.md b/content/concepts/stream-multiplexing.md
deleted file mode 100644
index d467286d..00000000
--- a/content/concepts/stream-multiplexing.md
+++ /dev/null
@@ -1,68 +0,0 @@
----
-title: Stream Multiplexing
----
-
-Stream Multiplexing (_stream muxing_) is a way of sending multiple streams of data over one communication link. It combines multiple signals into one unified signal so it can be transported 'over the wires', then it is demulitiplexed (_demuxed_) so it can be output and used by separate applications.
-
-## Multiplexing
-
-Multiplexing is by no means unique to libp2p. Most communication networks involve some kind of multiplexing, as the transport medium is generally scarce and needs to be shared by many participants.
-
-This is done to share a single TCP connection using unique port numbers to distinguish streams, between the multiple proceeses (such as kademlia and gossipsub) used by applications (such as ipfs) to make connection and transmission more efficient. With muxing, libp2p applications may have many separate streams of communication between peers, as well as have multiple concurrent streams open at the same time with a peer.
-
-Stream multiplexing allows us to initialize and use the same [transport](/concepts/transport/) connection across the lifetime of our interaction with a peer. With muxing, we also only need to deal with [NAT traversal](nat) once to be able to open as many streams as we need, since they will all share the same underlying transport connection.
-
-libp2p provides a common [interface](#interface) for stream multiplexers with several [implementations](#implementations) available. Applications can enable support for multiple multiplexers, which will allow you to fall back to a widely-supported multiplexer if a preferred choice is not supported by a remote peer.
-
-## Where it fits in the libp2p stack
-
-libp2p's multiplexing happens at the "application layer", meaning it's not provided by the operating system's network stack. However, developers writing libp2p applications rarely need to interact with stream multiplexers directly, except during initial configuration to control which modules are enabled.
-
-### Switch / swarm
-
-libp2p maintains some state about known peers and existing connections in a component known as the switch (or "swarm", depending on the implementation). The switch provides a dialing and listening interface that abstracts the details of which stream multiplexer is used for a given connection.
-
-When configuring libp2p, applications enable stream muxing modules, which the switch will use when dialing peers and listening for connections. If the remote peers support any of the same stream muxing implementations, the switch will select and use it when establishing the connection. If you dial a peer that the switch already has an open connection to, the new stream will automatically be multiplexed over the existing connection.
-
-Reaching agreement on which stream multiplexer to use happens early in the connection establishment process. Peers use [protocol negotiation](/concepts/protocols/#protocol-negotiation/) to agree on a commonly supported multiplexer, which upgrades a "raw" transport connection into a muxed connection capable of opening new streams.
-
-## Interface and Implementations
-
-### Interface
-The [stream multiplexing interface][interface-stream-muxing] defines how a stream muxing module can be applied to a connection and what operations are supported by a multiplexed connection.
-
-### Implementations
-
-There are several stream multiplexing modules available in libp2p. Please note that not all stream muxers are supported by every libp2p language implementation.
-
-#### mplex
-
-mplex is a protocol developed for libp2p. The [spec](https://github.com/libp2p/specs/tree/master/mplex) defines a simple protocol for multiplexing that is widely supported across libp2p language implementations:
-
-- Go: [go-mplex](https://github.com/libp2p/go-mplex)
-- Javascript: [js-mplex](https://github.com/libp2p/js-libp2p-mplex)
-- Rust: [rust-libp2p mplex module](https://github.com/libp2p/rust-libp2p/tree/master/muxers/mplex)
-
-#### yamux
-
-[yamux](https://github.com/hashicorp/yamux) is a multiplexing protocol designed by [Hashicorp](https://www.hashicorp.com/).
-
-yamux offers more sophisticated flow control than mplex, and can scale to thousands of multiplexed streams over a single connection.
-
-yamux is currently supported in go and rust:
-
-- Go: [go-smux-yamux](https://github.com/whyrusleeping/go-smux-yamux)
-- Rust: [rust-libp2p yamux module](https://github.com/libp2p/rust-libp2p/tree/master/muxers/yamux).
-
-#### quic
-
-[QUIC][wiki-quic] is a [transport](/concepts/transport/) protocol that contains a "native" stream multiplexer. libp2p will automatically use the native multiplexer for streams using a quic transport.
-
-quic is currently supported in go via [go-libp2p-quic-transport](https://github.com/libp2p/go-libp2p/tree/master/p2p/transport/quic).
-
-
-[interface-stream-muxing]: https://github.com/libp2p/js-libp2p-interfaces/tree/master/packages/interface-stream-muxer
-
-[repo-multistream-select]: https://github.com/multiformats/multistream-select
-
-[wiki-quic]: https://en.wikipedia.org/wiki/QUIC
diff --git a/content/concepts/transport.md b/content/concepts/transport.md
deleted file mode 100644
index 6a9b967b..00000000
--- a/content/concepts/transport.md
+++ /dev/null
@@ -1,307 +0,0 @@
----
-title: Transport
-weight: 1
----
-
-When you make a connection from your computer to a machine on the internet,
-chances are pretty good you're sending your bits and bytes using TCP/IP, the
-wildly successful combination of the Internet Protocol, which handles addressing
-and delivery of data packets, and the Transmission Control Protocol, which
-ensures that the data that gets sent over the wire is received completely and in
-the right order.
-
-Because TCP/IP is so ubiquitous and well-supported, it's often the default
-choice for networked applications. In some cases, TCP adds too much overhead,
-so applications might use [UDP](https://en.wikipedia.org/wiki/User_Datagram_Protocol),
-a much simpler protocol with no guarantees about reliability or ordering.
-
-While TCP and UDP (together with IP) are the most common protocols in use today,
-they are by no means the only options. Alternatives exist at lower levels
-(e.g. sending raw ethernet packets or bluetooth frames), and higher levels
-(e.g. QUIC, which is layered over UDP).
-
-In libp2p, we call these foundational protocols that move bits around
-**transports**, and one of libp2p's core requirements is to be
-*transport agnostic*. This means that the decision of what transport protocol
-to use is up to the developer, and in fact one application can support many
-different transports at the same time.
-
-## Listening and Dialing
-Transports are defined in terms of two core operations, **listening** and
-**dialing**.
-
-Listening means that you can accept incoming connections from other peers,
-using whatever facility is provided by the
-transport implementation. For example, a TCP transport on a unix platform could
-use the `bind` and `listen` system calls to have the operating system route
-traffic on a given TCP port to the application.
-
-Dialing is the process of opening an outgoing connection to a listening peer.
-Like listening, the specifics are determined by the implementation, but every
-transport in a libp2p implementation will share the same programmatic interface.
-
-## Addresses
-
-Before you can dial up a peer and open a connection, you need to know how to
-reach them. Because each transport will likely require its own address scheme,
-libp2p uses a convention called a "multiaddress" or `multiaddr` to encode
-many different addressing schemes.
-
-The [addressing doc](/concepts/addressing/) goes into more detail, but an overview of
-how multiaddresses work is helpful for understanding the dial and listen
-interfaces.
-
-Here's an example of a multiaddr for a TCP/IP transport:
-
-```
-/ip4/7.7.7.7/tcp/6543
-```
-
-This is equivalent to the more familiar `7.7.7.7:6543` construction, but it
-has the advantage of being explicit about the protocols that are being
-described. With the multiaddr, you can see at a glance that the `7.7.7.7`
-address belongs to the IPv4 protocol, and the `6543` belongs to TCP.
-
-For more complex examples, see [Addressing](/concepts/addressing/).
-
-Both dial and listen deal with multiaddresses. When listening, you give the
-transport the address you'd like to listen on, and when dialing you provide the
-address to dial to.
-
-When dialing a remote peer, the multiaddress should include the
-[PeerId](/concepts/peers/) of the peer you're trying to reach.
-This lets libp2p establish a [secure communication channel](/concepts/secure-comms/)
-and prevents impersonation.
-
-An example multiaddress that includes a `PeerId`:
-
-```
-/ip4/1.2.3.4/tcp/4321/p2p/QmcEPrat8ShnCph8WjkREzt5CPXF2RwhYxYBALDcLC1iV6
-```
-
-The `/p2p/QmcEPrat8ShnCph8WjkREzt5CPXF2RwhYxYBALDcLC1iV6` component uniquely
-identifies the remote peer using the hash of its public key.
-For more, see [Peer Identity](/concepts/peers/).
-
-{{% notice "tip" %}}
-
-When [peer routing](/concepts/peer-routing/) is enabled, you can dial peers
-using just their PeerId, without needing to know their transport addresses
-before hand.
-
-{{% /notice %}}
-
-## Supporting multiple transports
-
-libp2p applications often need to support multiple transports at once. For
-example, you might want your services to be usable from long-running daemon
-processes via TCP, while also accepting websocket connections from peers running
-in a web browser.
-
-The libp2p component responsible for managing the transports is called the
-[switch][definition_switch], which also coordinates
-[protocol negotiation](/concepts/protocols/#protocol-negotiation),
-[stream multiplexing](/concepts/stream-multiplexing),
-[establishing secure communication](/concepts/secure-comms/) and other forms of
-"connection upgrading".
-
-The switch provides a single "entry point" for dialing and listening, and frees
-up your application code from having to worry about the specific transports
-and other pieces of the "connection stack" that are used under the hood.
-
-{{% notice "note" %}}
-The term "swarm" was previously used to refer to what is now called the "switch",
-and some places in the codebase still use the "swarm" terminology.
-{{% /notice %}}
-
-[definition_switch]: /reference/glossary/#switch
-
-## QUIC
-
-QUIC is a new transport protocol that provides an always-encrypted, stream-multiplexed
-connection built on top of UDP. It started as an experiment by Google between Google
-services and Chrome in 2014, and was later standardized by the IETF in
-[RFC 9000](https://datatracker.ietf.org/doc/html/rfc9000),
-[RFC 9001](https://datatracker.ietf.org/doc/html/rfc9001), and
-[RFC 9002](https://datatracker.ietf.org/doc/html/rfc9002).
-
-### Key challenges with TCP
-
-1. Head-of-line blocking (HoL blocking): TCP is a single byte stream exposed by the
- kernel, so streams layered on top of TCP experience head-of-line (HoL) blocking.
-
- {{% notice "info" %}}
- In TCP, head-of-line blocking occurs when a single packet is lost, and packets delivered
- after that need to wait in the kernel buffer until a retransmission for the lost packet
- is received.
- {{% /notice %}}
-
-2. Ossification: Because the header of TCP packet is not encrypted, middleboxes can
- inspect and modify TCP header fields and may break unexpectedly when they encounter
- anything they don’t understand. This makes it practically impossible to deploy any
- changes to the TCP protocol that change the wire format.
-
-3. Handshake inefficiency: TCP spends one network round-trip (RTT) on verifying the
- client's address. Only after this can TLS start the cryptographic handshake, consuming
- another RTT. Setting up an encrypted connection therefore always takes 2 RTTs.
-
-QUIC was designed with the following goals in mind:
-
-- Making the transport layer aware of streams, so that packet loss doesn't cause HoL blocking
- between streams.
-- Reducing the latency of connection establishment to a single RTT for new connections, and to
- allow sending of 0 RTT application data for resumed connections.
-- Encrypting as much as possible. This eliminates the ossification risk, as middleboxes aren't
- able to read any encrypted fields. This allows future evolution of the protocol.
-
-### Comparing HTTP/2 and HTTP/3
-
-In addition to defining the QUIC transport, the IETF also standardized a new version of HTTP that runs on top of QUIC: HTTP/3 (
-[RFC 9114](https://datatracker.ietf.org/doc/html/rfc9114)). HTTP/3 combines the advantages
-of the existing transfer protocols HTTP/2 and HTTP over QUIC in one standard for faster and
-more stable data transmission.
-
-The following diagram illustrates the OSI model for HTTP/2 and HTTP/3 [1]:
-
-
-
-A web browser connection typically entails the following **(TCP+TLS+HTTP/2)**:
-
-1. Transport layer: TCP runs on top of the IP layer to provide a reliable
- byte stream.
- - TCP provides a reliable, bidirectional connection between two end systems.
-2. Security layer: A TLS handshake runs on top of TCP to
- establish an encrypted and authenticated connection.
- - Standard TLS over TCP requires 3 RTT. A typical TLS 1.3 handshake takes 1 RTT.
-3. Application layer: HTTP runs on a secure transport connection to transfer
- information and applies a stream muxer to serve multiple requests.
- - Application data starts to flow.
-
-In contrast, HTTP/3 runs over [QUIC](##what-is-quic), where QUIC is similar to
-TCP+TLS+HTTP/2 and runs over UDP. Building on UDP allows HTTP/3 to bypass the challenges
-found in TCP and use all the advantages of HTTP/2 and HTTP over QUIC.
-
-### What is QUIC?
-
-QUIC combines the functionality of these layers. Instead of TCP, it builds on UDP.
-When a UDP datagram is lost, it is not automatically retransmitted by the kernel.
-QUIC therefore takes responsibility for loss detection and repair itself. By using
-encryption, QUIC avoids ossified middleboxes. The TLS 1.3 handshake is performed in
-the first flight, removing the cost of verifying the client’s address and saving an
-RTT. QUIC also exposes multiple streams (and not just a single byte stream), so
-no stream multiplexer is needed at the application layer. Part of the application
-layer is also built directly into QUIC.
-
-In addition, a client can make use of QUIC's 0 RTT feature for subsequent connections
-when it has already communicated with a certain server. The client can then send
-(encrypted) application data even before the QUIC handshake has finished.
-
-### QUIC in libp2p
-
-libp2p only supports bidirectional streams and uses TLS 1.3 by default.
-Since QUIC already provides an encrypted, stream-multiplexed connection,
-libp2p directly uses QUIC streams, without any additional framing.
-
-To authenticate each others' peer IDs, peers encode their peer ID into a self-signed
-certificate, which they sign using their host's private key. This is the same way peer
-IDs are authenticated in the
-[libp2p TLS handshake](https://github.com/libp2p/specs/blob/master/tls/tls.md).
-
-{{% notice "note" %}}
-
-To be clear, there is no additional security handshake and stream muxer needed as QUIC
-provides all of this by default. This also means that establishing a libp2p connection between
-two nodes using QUIC only takes a single RTT.
-
-{{% /notice %}}
-
-Following the multiaddress format described earlier, a standard QUIC connection will
-look like: `/ip4/127.0.0.1/udp/65432/quic/`.
-
-## WebTransport
-
-While browsers perform HTTP request using HTTP/3, so far they don't offer an API to allow applications
-to gain access to the underlying QUIC stream.
-WebTransport is a new specification that uses QUIC to offer an alternative to
-WebSocket. Conceptually, it can be considered WebSocket over QUIC.
-It allows browsers to establish a stream-multiplexed and bidirectional connection
-to servers, and use streams to send and receive application data.
-
-While WebSocket provides a single bidirectional, full-duplex communication between a
-browser and a server over a TCP connection, WebTransport exposes allows the endpoints to use multiple
-streams in parallel.
-
-When connecting to a WebSocket server, browsers require the server to present a
-TLS certificate signed by a trusted CA (certificate authority). Few nodes have such
-a certificate, which is the reason that WebSocket never saw widespread adoption in the
-libp2p network. libp2p WebTransport offers a browser API that includes a way to
-accept the server's certificate by checking the (SHA-256) hash of the certificate
-(using the
-[`serverCertificateHashes` option](https://www.w3.org/TR/webtransport/#dom-webtransportoptions-servercertificatehashes)),
-even if the certificate is "just" a self-signed certificate. This allows us to connect
-any browser node to any server node, as long as the browser knows the certificate hash in
-advance (see [WebTransport in libp2p](#webtransport-in-libp2p) for how WebTransport addresses
-achieve this).
-
-Therefore, WebTransport exhibits all the advantages of QUIC over TCP, that being
-faster handshakes, no HoL blocking, and being future-proof.
-
-{{% notice "caution" %}}
-
-There is an experimental WebTransport transport in go-libp2p that is part
-of the [v0.23 release](https://github.com/libp2p/go-libp2p/releases/tag/v0.23.0).
-The implementation should be used experimentally and is not recommended for production
-environments.
-
-js-libp2p also plans to release
-[WebTransport support](https://github.com/libp2p/js-libp2p-webtransport) very soon.
-
-There are currently no concrete plans to support WebTransport beyond the Go and JS
-implementations.
-
-{{% /notice %}}
-
-For network stacks like libp2p, WebTransport is a pluggable
-protocol that fits well with a modular network design.
-
-For a standard WebSocket connection, the roundtrips required are as follows:
-
-- 1 RTT for TCP handshake
-- 1 RTT for TLS 1.3 handshake
-- 1 RTT for WebSocket upgrade
-- 1 RTT for multistream security negotiation (Noise or TLS 1.3)
-- 1 RTT for security handshake (Noise or TLS 1.3)
-- 1 RTT for multistream muxer negotiation (mplex or yamux)
-
-In total, 6 RTTs.
-
-WebTransport running over QUIC only requires 3 RTTs, as:
-
-- 1 RTT for QUIC handshake
-- 1 RTT for WebTransport handshake
-- 1 RTT for libp2p handshake; one for multistream and one for authentication
- (with a Noise handshake)
-
-In principle, the WebTransport protocol would even allow running the WebTransport
-handshake and the Noise handshake in parallel. However, this is currently not
-possible since the [browser API doesn't allow that yet](https://github.com/w3c/webtransport/issues/409).
-
-### WebTransport in libp2p
-
-WebTransport multiaddresses are composed of a QUIC multiaddr, followed
-by `/webtransport` and a list of multihashes of the node certificates that the server uses.
-
-For instance, for multiaddress `/ip4/127.0.0.1/udp/123/quic/webtransport/certhash/