Add P2P concept page and QUIC support

docs/concepts/p2p-networking.md

@@ -0,0 +1,95 @@
+---
+title: Peer-to-peer networking
+description: Learn how Teku connects to the consensus-layer P2P network using the TCP and QUIC transports, peer discovery, ports, IPv6, advertised addresses, and multiaddresses.
+sidebar_position: 7
+---
+
+# Peer-to-peer networking
+
+Teku connects to the consensus-layer peer-to-peer (P2P) network using two transports to exchange data
+and a discovery protocol to find peers.
+This page explains how the transports, discovery, ports, and address configuration fit together.
+
+:::note
+If you encounter peering issues, see the [network troubleshooting guide](../how-to/troubleshoot/network.md#resolve-peering-issues).
+:::
+
+## Transports
+
+Teku supports two P2P transports, both enabled by default:
+
+- **TCP** - The original libp2p transport.
+- **QUIC** - A transport that runs over UDP.
+
+When QUIC is enabled, Teku advertises both its TCP and QUIC addresses to the network, and remote
+peers can connect over either transport.
+When Teku dials a peer, it uses QUIC if both the local node and the peer support it, and otherwise
+falls back to TCP.
+
+## Peer discovery and ENR
+
+Teku uses [discovery v5](https://github.com/ethereum/devp2p/tree/master/discv5) over UDP to find
+peers on the network.
+Discovery starts from a set of [bootnodes](../how-to/find-and-connect/run-a-bootnode.md) and lets nodes
+locate each other dynamically.
+
+Teku identifies itself on the discovery network using an
+[Ethereum Node Record (ENR)](https://eips.ethereum.org/EIPS/eip-778), which advertises the node's IP
+address and ports.
+The UDP discovery address is used only to find peers; it is not a connectable transport address.
+
+:::note
+Instead of relying on automatic discovery, you can also
+[connect Teku to specific peers](../how-to/find-and-connect/connect-to-specific-peers.md), such as nodes
+you operate, using static or direct peers.
+:::
+
+## Node identity and private key
+
+The P2P private key identifies the beacon node on the network and secures the communication channel
+between nodes.
+Teku generates a key automatically on first startup, or you can supply your own using the
+[`--p2p-private-key-file`](../reference/cli/index.md#p2p-private-key-file) option.
+
+Using a persistent private key file gives the node a stable ENR, which is useful for
+[bootnodes](../how-to/find-and-connect/run-a-bootnode.md) and other nodes that you want peers to
+reconnect to reliably.
+
+## P2P port options
+
+Teku exposes a listening port and an advertised port for each transport and for peer discovery:
+
+| Purpose | Protocol | Listening option | Advertised option |
+| --- | --- | --- | --- |
+| TCP transport | TCP | [`--p2p-port`](../reference/cli/index.md#p2p-port) | [`--p2p-advertised-port`](../reference/cli/index.md#p2p-advertised-port) |
+| Peer discovery | UDP | [`--p2p-udp-port`](../reference/cli/index.md#p2p-udp-port) | [`--p2p-advertised-udp-port`](../reference/cli/index.md#p2p-advertised-udp-port) |
+| QUIC transport | UDP | [`--p2p-quic-port`](../reference/cli/index.md#p2p-quic-port) | [`--p2p-advertised-quic-port`](../reference/cli/index.md#p2p-advertised-quic-port) |
+
+Each option has an `-ipv6` counterpart (for example,
+[`--p2p-quic-port-ipv6`](../reference/cli/index.md#p2p-quic-port-ipv6) and
+[`--p2p-advertised-quic-port-ipv6`](../reference/cli/index.md#p2p-advertised-quic-port-ipv6)) that
+adds a second address family for dual-stack operation.
+The listening mode (IPv4, IPv6, or dual-stack) depends on how you combine these options with the
+[`--p2p-interface`](../reference/cli/index.md#p2p-interface-p2p-interfaces) option.
+By default, Teku listens over IPv4.
+For IPv6 or dual-stack, see [Configure IPv6](../how-to/find-and-connect/configure-ipv6.md).
+
+The address Teku advertises to peers can differ from the address it listens on, which matters when
+the node is behind a NAT or router.
+Teku autodetects the advertised address by default; you can configure it with
+[`--p2p-advertised-ip`](../reference/cli/index.md#p2p-advertised-ip-p2p-advertised-ips).
+You can also [specify NAT methods](../how-to/find-and-connect/specify-nat.md).
+
+## Multiaddresses
+
+Teku identifies peers using [multiaddresses](https://libp2p.io/concepts/fundamentals/addressing/).
+A multiaddress includes the transport and port, so the TCP and QUIC addresses for the same node
+differ:
+
+- TCP - `/ip4/<ip>/tcp/9000/p2p/<peer_id>`
+- QUIC - `/ip4/<ip>/udp/9001/quic-v1/p2p/<peer_id>`
+
+The `p2p_addresses` field returned by the
+[`/eth/v1/node/identity`](https://consensys.github.io/teku/#tag/Node/operation/getNetworkIdentity)
+API endpoint lists the TCP and QUIC transport addresses.
+The `discovery_addresses` field lists the UDP discovery address.

docs/get-started/install/run-docker-image.md

@@ -29,6 +29,7 @@ You can specify [Teku environment variables](../../reference/cli/index.md#specif
 docker run -d                             \
   -p 9000:9000/tcp                        \
   -p 9000:9000/udp                        \
+  -p 9001:9001/udp                        \
   -p 5051:5051                            \
   -e TEKU_REST_API_ENABLED=true           \
   -e TEKU_P2P_PORT=9000                   \
@@ -59,6 +60,7 @@ Use the UID because the username may not exist inside the docker container.
 docker run                                \
   -p 9000:9000/tcp                        \
   -p 9000:9000/udp                        \
+  -p 9001:9001/udp                        \
   --user 1001:1001                        \
   --mount type=bind,source=/Users/user1/teku/,target=/var/lib/teku consensys/teku:latest \
   --data-base-path=/var/lib/teku          \
@@ -73,9 +75,13 @@ Expose ports for P2P peer discovery, metrics, and REST APIs. Expose the default
 
 - [`--metrics-port`](../../reference/cli/index.md#metrics-port)
 - [`--p2p-port`](../../reference/cli/index.md#p2p-port)
+- [`--p2p-quic-port`](../../reference/cli/index.md#p2p-quic-port)
 - [`--p2p-advertised-port`](../../reference/cli/index.md#p2p-advertised-port)
+- [`--p2p-advertised-quic-port`](../../reference/cli/index.md#p2p-advertised-quic-port)
 - [`--rest-api-port`](../../reference/cli/index.md#rest-api-port).
 
+Teku uses the [QUIC transport](../../concepts/p2p-networking.md) on `9001/udp` by default, so expose this port in addition to the TCP transport and discovery ports.
+
 To run Teku exposing local ports for access:
 
 ```bash
@@ -171,9 +177,10 @@ services:
     volumes:
       - ./teku:/var/lib/teku/data
     ports:
-      # Map the p2p port(9000) and REST API port(5051)
+      # Map the TCP transport and discovery port(9000), QUIC transport port(9001), and REST API port(5051)
       - "9000:9000/tcp"
       - "9000:9000/udp"
+      - "9001:9001/udp"
       - "5051:5051"
 ```
 
@@ -230,9 +237,10 @@ services:
     volumes:
       - ./teku:/var/lib/teku/data
     ports:
-      # Map the p2p port(9000) and REST API port(5051)
+      # Map the TCP transport and discovery port(9000), QUIC transport port(9001), and REST API port(5051)
       - "9000:9000/tcp"
       - "9000:9000/udp"
+      - "9001:9001/udp"
       - "5051:5051"
 ```
 
@@ -286,9 +294,10 @@ services:
     volumes:
       - ./teku:/var/lib/teku/data
     ports:
-      # Map the p2p port(9000) and REST API port(5051)
+      # Map the TCP transport and discovery port(9000), QUIC transport port(9001), and REST API port(5051)
       - "9000:9000/tcp"
       - "9000:9000/udp"
+      - "9001:9001/udp"
       - "5051:5051"
 ```
 

docs/how-to/find-and-connect/configure-ipv6.md

@@ -5,46 +5,57 @@ sidebar_position: 3
 
 # Configure IPv6
 
-You can configure Teku to listen over IPv4, [IPv6](#listen-over-only-ipv6), or
+In [peer-to-peer (P2P) networking](../../concepts/p2p-networking.md), Teku listens over IPv4 by default.
+You can configure it to listen over [IPv6](#listen-over-only-ipv6) or
 [both (dual-stack)](#listen-over-both-ipv4-and-ipv6-dual-stack).
 
 ## Listen over only IPv6
 
 To configure Teku to listen only on IPv6, set the
 [`--p2p-interface`](../../reference/cli/index.md#p2p-interface-p2p-interfaces) CLI option to `::`.
-The [`--p2p-port`](../../reference/cli/index.md#p2p-port) and
-[`--p2p-udp-port`](../../reference/cli/index.md#p2p-udp-port) CLI options are used for the P2P and
-discovery ports, similar to listening over IPv4 only.
+The [`--p2p-port`](../../reference/cli/index.md#p2p-port), [`--p2p-udp-port`](../../reference/cli/index.md#p2p-udp-port),
+and [`--p2p-quic-port`](../../reference/cli/index.md#p2p-quic-port) CLI options are used for the TCP
+transport, discovery, and QUIC transport ports.
+
+In single-stack mode, Teku uses port `9000` for TCP and UDP, and `9001` for QUIC (UDP) by default.
 
 ## Listen over both IPv4 and IPv6 (dual-stack)
 
 To configure Teku to listen over both IPv4 and IPv6, also known as dual-stack support, set the
 [`--p2p-interface`](../../reference/cli/index.md#p2p-interface-p2p-interfaces) CLI option to
-`0.0.0.0,::` for both IPv4 and IPv6 listening addresses. 
-In this setup, the [`--p2p-port`](../../reference/cli/index.md#p2p-port) and
-[`--p2p-udp-port`](../../reference/cli/index.md#p2p-udp-port) options apply to the IPv4 address.
-The [`--p2p-port-ipv6`](../../reference/cli/index.md#p2p-port-ipv6) and
-[`--p2p-udp-port-ipv6`](../../reference/cli/index.md#p2p-udp-port-ipv6) options apply to the IPv6 address.
+`0.0.0.0,::` for both IPv4 and IPv6 listening addresses.
+In this setup, the [`--p2p-port`](../../reference/cli/index.md#p2p-port),
+[`--p2p-udp-port`](../../reference/cli/index.md#p2p-udp-port), and
+[`--p2p-quic-port`](../../reference/cli/index.md#p2p-quic-port) options apply to the IPv4 address.
+The [`--p2p-port-ipv6`](../../reference/cli/index.md#p2p-port-ipv6),
+[`--p2p-udp-port-ipv6`](../../reference/cli/index.md#p2p-udp-port-ipv6), and
+[`--p2p-quic-port-ipv6`](../../reference/cli/index.md#p2p-quic-port-ipv6) options apply to the IPv6 address.
+
+After dual-stack support is enabled, Teku uses the following ports by default:
 
-After dual-stack support is enabled, Teku uses port `9000` for both TCP and UDP on IPv4, and port
-`9090` for both TCP and UDP on IPv6 by default.
+- On IPv4: `9000` for TCP and UDP, and `9001` for QUIC (UDP)
+- On IPv6: `9090` for TCP and UDP, and `9091` for QUIC (UDP)
 
 ## Advertise only the IPv6 address
 
 To advertise only the IPv6 public address to the network, use the
-[`--p2p-advertised-ip`](../../reference/cli/index.md#p2p-advertised-ip-p2p-advertised-ips) CLI option. 
+[`--p2p-advertised-ip`](../../reference/cli/index.md#p2p-advertised-ip-p2p-advertised-ips) CLI option.
 This is similar to advertising an IPv4 address.
-Configure the advertised port using the
-[`--p2p-advertised-port`](../../reference/cli/index.md#p2p-advertised-port) CLI option. 
-It uses the value set in [`--p2p-port`](../../reference/cli/index.md#p2p-port) by default.
+
+You can configure the advertised ports using the
+[`--p2p-advertised-port`](../../reference/cli/index.md#p2p-advertised-port) and
+[`--p2p-advertised-quic-port`](../../reference/cli/index.md#p2p-advertised-quic-port) options.
 
 ## Advertise both IPv4 and IPv6 addresses (dual-stack)
 
 To advertise both the IPv4 and IPv6 public addresses to the network, use the
 [`--p2p-advertised-ips`](../../reference/cli/index.md#p2p-advertised-ip-p2p-advertised-ips) CLI
-option and provide the two addresses, separated by a comma. 
-Configure the advertised port for the IPv4 address using the
-[`--p2p-advertised-port`](../../reference/cli/index.md#p2p-advertised-port) option. 
-Configure the advertised port for the IPv6 address using the
-[`--p2p-advertised-port-ipv6`](../../reference/cli/index.md#p2p-advertised-port-ipv6) option. 
-This port is set to the value of [`--p2p-port-ipv6`](../../reference/cli/index.md#p2p-port-ipv6) by default.
+option and provide the two addresses, separated by a comma.
+
+You can configure the advertised ports for the IPv4 address using the
+[`--p2p-advertised-port`](../../reference/cli/index.md#p2p-advertised-port) and
+[`--p2p-advertised-quic-port`](../../reference/cli/index.md#p2p-advertised-quic-port) options.
+
+You can configure the advertised port for the IPv6 address using the
+[`--p2p-advertised-port-ipv6`](../../reference/cli/index.md#p2p-advertised-port-ipv6) and
+[`--p2p-advertised-quic-port-ipv6`](../../reference/cli/index.md#p2p-advertised-quic-port-ipv6) options.

docs/how-to/find-and-connect/connect-to-specific-peers.md

@@ -6,7 +6,7 @@ sidebar_position: 4
 
 # Connect to specific peers
 
-By default, Teku uses [discovery](../run-a-bootnode.md) to find and connect to peers automatically.
+By default, Teku uses [discovery](../../concepts/p2p-networking.md#peer-discovery-and-enr) to find and connect to peers automatically.
 In some cases, you might want Teku to connect to specific peers, such as nodes you operate across different
 regions.
 
@@ -16,13 +16,12 @@ Teku provides multiple mechanisms to connect to specific peers:
 - [Direct peers](#direct-peers) - Static peers that always exchange full messages, configured reciprocally.
 - [The `add_peer` API](#add-a-static-peer-at-runtime) - Add a static peer at runtime without restarting Teku.
 
-:::info Use the TCP address
+:::info
 
-Teku connects to peers over TCP.
-When you specify a peer, use its TCP [multiaddress](https://libp2p.io/concepts/fundamentals/addressing/),
-not its UDP discovery address.
-Get a node's TCP multiaddress from the `p2p_addresses` field of the
-[`/eth/v1/node/identity`](https://consensys.github.io/teku/#tag/Node/operation/getNetworkIdentity) API endpoint.
+When you specify a peer, use one of its transport
+[multiaddresses](https://libp2p.io/concepts/fundamentals/addressing/) from the `p2p_addresses` field
+of the [`/eth/v1/node/identity`](https://consensys.github.io/teku/#tag/Node/operation/getNetworkIdentity)
+API endpoint.
 
 :::
 

docs/how-to/find-and-connect/improve-connectivity.md

@@ -6,7 +6,7 @@ sidebar_position: 1
 
 # Improve peer-to-peer connectivity
 
-The consensus layer relies on peer-to-peer (P2P) networking.
+The consensus layer relies on [peer-to-peer (P2P) networking](../../concepts/p2p-networking.md).
 By having a good peer count you increase the performance and health of your node.
 When a Teku node starts up, it looks for participants on the P2P network by listening for incoming connections, and finds and connects to peers.
 
@@ -27,9 +27,16 @@ Check the [`ip4.me`](http://ip4.me/) website to view your public IP address.
 
 ## Configure ports
 
-By default, Teku listens for connections on port `9000` for TCP and UDP. You can configure the port number with the [`--p2p-port`](../../reference/cli/index.md#p2p-port) option.
+By default, Teku uses two [P2P ports](../../concepts/p2p-networking.md#p2p-port-options) across three
+protocols:
 
-Configure port forwarding on your router and firewall to allow incoming and outgoing connections on the listening port for the TCP and UDP protocols.
+- `9000/tcp` and `9000/udp` for the TCP transport and peer discovery (configured with
+  [`--p2p-port`](../../reference/cli/index.md#p2p-port)).
+- `9001/udp` for the QUIC transport (configured with
+  [`--p2p-quic-port`](../../reference/cli/index.md#p2p-quic-port)).
+
+Configure port forwarding on your router and firewall to allow incoming and outgoing connections on
+these ports and protocols.
 
 View your router or firewall documentation to configure port-forwarding.
 

docs/how-to/run-a-bootnode.md → docs/how-to/find-and-connect/run-a-bootnode.md

@@ -1,6 +1,6 @@
 ---
 description: Run Teku as a bootnode.
-sidebar_position: 13
+sidebar_position: 5
 ---
 
 import Tabs from '@theme/Tabs';
@@ -18,7 +18,7 @@ as bootnodes, that are hard coded into Ethereum clients. The Discovery protocol
 exchange information about active peers, enabling them to dynamically join the network without needing a
 full list of known nodes.
 
-You can specify additional bootnodes using the [`--p2p-discovery-bootnodes`](../reference/cli/index.md#p2p-discovery-bootnodes) option.
+You can specify additional bootnodes using the [`--p2p-discovery-bootnodes`](../../reference/cli/index.md#p2p-discovery-bootnodes) option.
 
 :::note
 Any Teku instance running as a beacon node already participates in the Discovery protocol and can serve
@@ -40,7 +40,7 @@ In this mode, Teku only runs its Discovery service and doesn't:
 - Validate or produce blocks
 - Respond to Beacon API queries.
 
-To run Teku in bootnode-only mode, start Teku with the [`bootnode`](../reference/cli/subcommands/bootnode.md) subcommand:
+To run Teku in bootnode-only mode, start Teku with the [`bootnode`](../../reference/cli/subcommands/bootnode.md) subcommand:
 
 ```bash
 teku bootnode <extra_options>
@@ -59,9 +59,9 @@ teku bootnode \
 This example configures a bootnode for Ethereum mainnet. It sets:
 
 - The network to `mainnet`
-- The external communication port using [`--p2p-port`](../reference/cli/index.md#p2p-port)
-- The public IP address using [`--p2p-advertised-ip`](../reference/cli/index.md#p2p-advertised-ip-p2p-advertised-ips)
-- A persistent private key file using [`--p2p-private-key-file`](../reference/cli/index.md#p2p-private-key-file)
+- The external communication port using [`--p2p-port`](../../reference/cli/index.md#p2p-port)
+- The public IP address using [`--p2p-advertised-ip`](../../reference/cli/index.md#p2p-advertised-ip-p2p-advertised-ips)
+- A persistent private key file using [`--p2p-private-key-file`](../../reference/cli/index.md#p2p-private-key-file)
 
 Using a persistent private key ensures the bootnode has a stable Ethereum Node Record (ENR), which others
 can use to connect reliably.