From 821040b2d7ce5528c0cfa9940c144a4081618dc8 Mon Sep 17 00:00:00 2001 From: Joshua Fernandes Date: Tue, 2 Jul 2024 20:45:27 +1000 Subject: [PATCH 1/3] adding in some details re the peering process Signed-off-by: Joshua Fernandes --- .../how-to/connect/manage-peers.md | 17 +++++++++++++++++ .../tutorials/besu-teku-mainnet.md | 11 ++++++----- .../tutorials/besu-teku-testnet.md | 14 ++++++++++---- 3 files changed, 33 insertions(+), 9 deletions(-) diff --git a/docs/public-networks/how-to/connect/manage-peers.md b/docs/public-networks/how-to/connect/manage-peers.md index 35b225447ea..f5ebce304a5 100644 --- a/docs/public-networks/how-to/connect/manage-peers.md +++ b/docs/public-networks/how-to/connect/manage-peers.md @@ -13,6 +13,23 @@ Hyperledger Besu peer-to-peer (P2P) discovery happens periodically based on the The frequency of discovery isn't configurable, but you can [limit remote connections](#limit-remote-connections) in public networks and [randomly prioritize connections](../../reference/cli/options.md#random-peer-priority-enabled) in small, stable networks. +## The peering process + +The peering process requires the port (default 30303) to be open to UDP and TCP traffic to the world (0.0.0.0/0). The `discovery stack` uses UDP to keep things lightweight and quick and only +allows a node to find peers and connect to them, it does not have any additional overhead like error checking, retrys etc. Once peers have bonded, the actual data exchange between them is quite +complex and needs a more fully featured protocol that can support retries, error checking etc which is why TCP is used for the `devP2P stack`. It is important to remember that both stacks work +in parallel i.e the `discovery stack` adds new peers to the network, and the `devP2P` stack enables interactions and data flow between them. + +The proces starts starts with a client attempting to connect to as many peers as possible. The more peers it is connected to, the more confident it is of having an accurate view of the network. + +1. When Besu starts up it will adverstise its presence and details like the enode etc via UDP before establishing a more formal connection with any peer (log messages look like `Enode URL enode://....`) +2. Besu will attempt connect to the network's bootnodes (which are a list of predefined nodes whose sole functionality is to help a node join existing peers on the network) +3. Once a connection with the bootnode is established via TCP (`ping/pong` handshake messages in the debug and trace logs), Besu requests a list of peers from the bootnode (`find node` messages in the debug and trace logs) +4. Besu will then attempt to establish connections to each peer on that list via TCP and get status information from them - i.e. network details, what the peer believes to be the current chain head, it's list of peers, etc. It is also important to note that from this point on any traffic to that peer is only done via TCP. +5. Depending on the type of sync, a common block (the pivot block) is picked that all these connected peers (default of 5) have and we start syncing from that block till we get to chain head. Log messages look like `Downloading world state from peers for pivot block .......` +6. Besu also uses the peers from step 4, and will process each in the same manner as above +7. When new peers come along (regardless of client) the same process is repeated + :::info You can use [`admin_addPeer`](../../reference/cli/options.md#admin_addpeer) to attempt a specific connection, but this isn't P2P discovery. diff --git a/docs/public-networks/tutorials/besu-teku-mainnet.md b/docs/public-networks/tutorials/besu-teku-mainnet.md index 1b7866bdaca..412c994a22b 100644 --- a/docs/public-networks/tutorials/besu-teku-mainnet.md +++ b/docs/public-networks/tutorials/besu-teku-mainnet.md @@ -56,11 +56,10 @@ besu \ --sync-mode=SNAP \ --data-storage-format=BONSAI \ --rpc-http-enabled=true \ - --rpc-http-host="0.0.0.0" \ - --rpc-ws-enabled=true \ - --rpc-ws-host="0.0.0.0" \ - --host-allowlist=,127.0.0.1,localhost \ - --engine-host-allowlist=,127.0.0.1,localhost \ + --rpc-http-host=127.0.0.1 \ + --p2p-host= \ + --host-allowlist=,127.0.0.1,localhost \ + --engine-host-allowlist=,127.0.0.1,localhost \ --engine-rpc-enabled \ --engine-jwt-secret= ``` @@ -96,6 +95,8 @@ teku \ --ee-jwt-secret-file= \ --metrics-enabled=true \ --rest-api-enabled=true \ + --rest-api-host-allowlist=127.0.0.1 \ + --p2p-advertised-ip= \ --checkpoint-sync-url= ``` diff --git a/docs/public-networks/tutorials/besu-teku-testnet.md b/docs/public-networks/tutorials/besu-teku-testnet.md index 962225a223d..d6d60afb8dd 100644 --- a/docs/public-networks/tutorials/besu-teku-testnet.md +++ b/docs/public-networks/tutorials/besu-teku-testnet.md @@ -69,10 +69,10 @@ Run the following command or specify the options in a [configuration file](../ho besu \ --network=holesky \ --rpc-http-enabled=true \ - --rpc-http-host=0.0.0.0 \ + --rpc-http-host=127.0.0.1 \ --rpc-http-cors-origins="*" \ --rpc-ws-enabled=true \ - --rpc-ws-host=0.0.0.0 \ + --p2p-host= \ --host-allowlist="*" \ --engine-host-allowlist="*" \ --engine-rpc-enabled \ @@ -87,10 +87,10 @@ besu \ besu \ --network=sepolia \ --rpc-http-enabled=true \ - --rpc-http-host=0.0.0.0 \ + --rpc-http-host=127.0.0.1 \ --rpc-http-cors-origins="*" \ --rpc-ws-enabled=true \ - --rpc-ws-host=0.0.0.0 \ + --p2p-host= \ --host-allowlist="*" \ --engine-host-allowlist="*" \ --engine-rpc-enabled \ @@ -124,6 +124,8 @@ teku \ --ee-jwt-secret-file= \ --metrics-enabled=true \ --rest-api-enabled=true \ + --rest-api-host-allowlist=127.0.0.1 \ + --p2p-advertised-ip= \ --checkpoint-sync-url= ``` @@ -138,6 +140,8 @@ teku \ --ee-jwt-secret-file= \ --metrics-enabled=true \ --rest-api-enabled=true \ + --rest-api-host-allowlist=127.0.0.1 \ + --p2p-advertised-ip= \ --checkpoint-sync-url= ``` @@ -169,6 +173,8 @@ teku \ --ee-jwt-secret-file= \ --metrics-enabled=true \ --rest-api-enabled=true \ + --rest-api-host-allowlist=127.0.0.1 \ + --p2p-advertised-ip= \ --checkpoint-sync-url= \ --validators-proposer-default-fee-recipient= \ --validator-keys=:[,:,...] From a7e21cf2450ac643a060d4732cbc49b0ea3be195 Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Tue, 2 Jul 2024 22:52:24 -0700 Subject: [PATCH 2/3] edit p2p discovery process and tutorials Signed-off-by: Alexandra Tran --- .../how-to/connect/manage-peers.md | 64 +++++++++++++------ .../tutorials/besu-teku-mainnet.md | 25 ++++---- .../tutorials/besu-teku-testnet.md | 19 +++--- 3 files changed, 65 insertions(+), 43 deletions(-) diff --git a/docs/public-networks/how-to/connect/manage-peers.md b/docs/public-networks/how-to/connect/manage-peers.md index f5ebce304a5..176fb3f9cb2 100644 --- a/docs/public-networks/how-to/connect/manage-peers.md +++ b/docs/public-networks/how-to/connect/manage-peers.md @@ -9,34 +9,60 @@ tags: # Manage peers -Hyperledger Besu peer-to-peer (P2P) discovery happens periodically based on the number of peers in a network and the node's [peer limit](#limit-peers). +Hyperledger Besu peer-to-peer (P2P) discovery happens periodically based on the number of peers in a +network and the node's [peer limit](#limit-peers). -The frequency of discovery isn't configurable, but you can [limit remote connections](#limit-remote-connections) in public networks and [randomly prioritize connections](../../reference/cli/options.md#random-peer-priority-enabled) in small, stable networks. +The frequency of discovery isn't configurable, but you can +[limit remote connections](#limit-remote-connections) in public networks and +[randomly prioritize connections](../../reference/cli/options.md#random-peer-priority-enabled) in +small, stable networks. -## The peering process +:::info +You can use [`admin_addPeer`](../../reference/cli/options.md#admin_addpeer) to attempt a specific +connection, but this isn't P2P discovery. +::: -The peering process requires the port (default 30303) to be open to UDP and TCP traffic to the world (0.0.0.0/0). The `discovery stack` uses UDP to keep things lightweight and quick and only -allows a node to find peers and connect to them, it does not have any additional overhead like error checking, retrys etc. Once peers have bonded, the actual data exchange between them is quite -complex and needs a more fully featured protocol that can support retries, error checking etc which is why TCP is used for the `devP2P stack`. It is important to remember that both stacks work -in parallel i.e the `discovery stack` adds new peers to the network, and the `devP2P` stack enables interactions and data flow between them. +In private networks, we recommend +[using bootnodes](../../../private-networks/how-to/configure/bootnodes.md) to initially discover peers. -The proces starts starts with a client attempting to connect to as many peers as possible. The more peers it is connected to, the more confident it is of having an accurate view of the network. +## P2P discovery process -1. When Besu starts up it will adverstise its presence and details like the enode etc via UDP before establishing a more formal connection with any peer (log messages look like `Enode URL enode://....`) -2. Besu will attempt connect to the network's bootnodes (which are a list of predefined nodes whose sole functionality is to help a node join existing peers on the network) -3. Once a connection with the bootnode is established via TCP (`ping/pong` handshake messages in the debug and trace logs), Besu requests a list of peers from the bootnode (`find node` messages in the debug and trace logs) -4. Besu will then attempt to establish connections to each peer on that list via TCP and get status information from them - i.e. network details, what the peer believes to be the current chain head, it's list of peers, etc. It is also important to note that from this point on any traffic to that peer is only done via TCP. -5. Depending on the type of sync, a common block (the pivot block) is picked that all these connected peers (default of 5) have and we start syncing from that block till we get to chain head. Log messages look like `Downloading world state from peers for pivot block .......` -6. Besu also uses the peers from step 4, and will process each in the same manner as above -7. When new peers come along (regardless of client) the same process is repeated +The P2P discovery process requires [ports to be open to UDP and TCP traffic](configure-ports.md#p2p-networking). +If you have a firewall in place, keep those ports open to allow traffic in and out. +If you are running a node at home on your network, ensure that your router has those ports open. -:::info +The `discovery` stack uses UDP to keep peer discovery lightweight and quick. +It only allows a node to find peers and connect to them, without any additional overhead. +Once peers have bonded, the data exchange between them is complex and needs a fully featured +protocol to support error checking and retries, so the `devP2P` stack uses TCP. -You can use [`admin_addPeer`](../../reference/cli/options.md#admin_addpeer) to attempt a specific connection, but this isn't P2P discovery. +Both stacks work in parallel: the `discovery` stack adds new peers to the network, and the `devP2P` +stack enables interactions and data flow between them. +In detail, the P2P discovery process is as follows: -::: +1. When Besu starts up it advertises its presence and details (including the enode) using UDP before + establishing a formal connection with any peer (log messages look like `Enode URL enode://....`). + +2. Besu attempts to connect to the network's bootnodes (a set of predefined nodes used to help + bootstrap discovery). + +3. Once a connection with a bootnode is established using TCP (`ping/pong` handshake messages in the + debug and trace logs), Besu requests a list of neighbors (potential peers) from the bootnode + (`find node` messages in the debug and trace logs). + +4. Besu attempts to connect to each peer using TCP, and get status information from them – such + as network details, what the peer believes to be the current chain head, and its list of neighbors. + From this point on any traffic to that peer is only done using TCP. + +5. Depending on the [synchronization method](../../get-started/connect/sync-node.md), a common block + (the pivot block) is selected that all connected peers (default of 5) have, and Besu syncs from + that block till it gets to chain head. + Log messages look like `Downloading world state from peers for pivot block .......`. + +6. Besu repeats the same process for each peer in step 4, and any new peers that come along + (regardless of client). -In private networks, we recommend [using bootnodes](../../../private-networks/how-to/configure/bootnodes.md) to initially discover peers. +The more peers Besu is connected to, the more confident it is of having an accurate view of the network. ## Limit peers diff --git a/docs/public-networks/tutorials/besu-teku-mainnet.md b/docs/public-networks/tutorials/besu-teku-mainnet.md index 412c994a22b..56f567ae53a 100644 --- a/docs/public-networks/tutorials/besu-teku-mainnet.md +++ b/docs/public-networks/tutorials/besu-teku-mainnet.md @@ -53,30 +53,26 @@ Run the following command or specify the options in a [configuration file](../ho ```bash besu \ - --sync-mode=SNAP \ - --data-storage-format=BONSAI \ - --rpc-http-enabled=true \ - --rpc-http-host=127.0.0.1 \ - --p2p-host= \ - --host-allowlist=,127.0.0.1,localhost \ - --engine-host-allowlist=,127.0.0.1,localhost \ - --engine-rpc-enabled \ + --sync-mode=SNAP \ + --data-storage-format=BONSAI \ + --rpc-http-enabled=true \ + --p2p-host= \ + --host-allowlist=,127.0.0.1,localhost \ + --engine-host-allowlist=,127.0.0.1,localhost \ + --engine-rpc-enabled \ --engine-jwt-secret= ``` Specify: - The path to the `jwtsecret.hex` file generated in [step 2](#2-generate-the-shared-secret) using the [`--engine-jwt-secret`](../reference/cli/options.md#engine-jwt-secret) option. -- The IP address of your Besu node using the [`--host-allowlist`](../reference/cli/options.md#host-allowlist) and [`--engine-host-allowlist`](../reference/cli/options.md#engine-host-allowlist) options. +- The public IP address of your Besu node using the [`--host-allowlist`](../reference/cli/options.md#host-allowlist) and [`--engine-host-allowlist`](../reference/cli/options.md#engine-host-allowlist) options. Also, in the command: - [`--sync-mode`](../reference/cli/options.md#sync-mode) specifies using [snap sync](../get-started/connect/sync-node.md#snap-synchronization). - [`--data-storage-format`](../reference/cli/options.md#data-storage-format) specifies using [Bonsai Tries](../concepts/data-storage-formats.md#bonsai-tries). - [`--rpc-http-enabled`](../reference/cli/options.md#rpc-http-enabled) enables the HTTP JSON-RPC service. -- [`--rpc-http-host`](../reference/cli/options.md#rpc-http-host) is set to `0.0.0.0` to allow remote RPC connections. -- [`--rpc-ws-enabled`](../reference/cli/options.md#rpc-ws-enabled) enables the WebSocket JSON-RPC service. -- [`--rpc-ws-host`](../reference/cli/options.md#rpc-ws-host) is set to `0.0.0.0` to allow remote RPC connections. - [`--engine-rpc-enabled`](../reference/cli/options.md#engine-rpc-enabled) enables the [Engine API](../reference/engine-api/index.md). You can modify the option values and add other [command line options](../reference/cli/options.md) as needed. @@ -95,8 +91,7 @@ teku \ --ee-jwt-secret-file= \ --metrics-enabled=true \ --rest-api-enabled=true \ - --rest-api-host-allowlist=127.0.0.1 \ - --p2p-advertised-ip= \ + --p2p-advertised-ip= \ --checkpoint-sync-url= ``` @@ -104,6 +99,8 @@ Specify: - The path to the `jwtsecret.hex` file generated in [step 2](#2-generate-the-shared-secret) using the [`--ee-jwt-secret-file`](https://docs.teku.consensys.io/reference/cli#ee-jwt-secret-file) option. +- The public IP address of your Teku node using the + [`--p2p-advertised-ip`](https://docs.teku.consensys.io/reference/cli#p2p-advertised-ip) option. - The URL of a checkpoint sync endpoint using the [`--checkpoint-sync-url`](https://docs.teku.consensys.io/reference/cli#checkpoint-sync-url) option. diff --git a/docs/public-networks/tutorials/besu-teku-testnet.md b/docs/public-networks/tutorials/besu-teku-testnet.md index d6d60afb8dd..088121dc806 100644 --- a/docs/public-networks/tutorials/besu-teku-testnet.md +++ b/docs/public-networks/tutorials/besu-teku-testnet.md @@ -69,10 +69,9 @@ Run the following command or specify the options in a [configuration file](../ho besu \ --network=holesky \ --rpc-http-enabled=true \ - --rpc-http-host=127.0.0.1 \ --rpc-http-cors-origins="*" \ --rpc-ws-enabled=true \ - --p2p-host= \ + --p2p-host= \ --host-allowlist="*" \ --engine-host-allowlist="*" \ --engine-rpc-enabled \ @@ -87,10 +86,9 @@ besu \ besu \ --network=sepolia \ --rpc-http-enabled=true \ - --rpc-http-host=127.0.0.1 \ --rpc-http-cors-origins="*" \ --rpc-ws-enabled=true \ - --p2p-host= \ + --p2p-host= \ --host-allowlist="*" \ --engine-host-allowlist="*" \ --engine-rpc-enabled \ @@ -124,8 +122,7 @@ teku \ --ee-jwt-secret-file= \ --metrics-enabled=true \ --rest-api-enabled=true \ - --rest-api-host-allowlist=127.0.0.1 \ - --p2p-advertised-ip= \ + --p2p-advertised-ip= \ --checkpoint-sync-url= ``` @@ -140,8 +137,7 @@ teku \ --ee-jwt-secret-file= \ --metrics-enabled=true \ --rest-api-enabled=true \ - --rest-api-host-allowlist=127.0.0.1 \ - --p2p-advertised-ip= \ + --p2p-advertised-ip= \ --checkpoint-sync-url= ``` @@ -153,6 +149,8 @@ Specify: - The path to the `jwtsecret.hex` file generated in [step 2](#2-generate-the-shared-secret) using the [`--ee-jwt-secret-file`](https://docs.teku.consensys.io/reference/cli#ee-jwt-secret-file) option. +- The public IP address of your Teku node using the + [`--p2p-advertised-ip`](https://docs.teku.consensys.io/reference/cli#p2p-advertised-ip) option. - The URL of a checkpoint sync endpoint using the [`--checkpoint-sync-url`](https://docs.teku.consensys.io/reference/cli#checkpoint-sync-url) option. @@ -173,8 +171,7 @@ teku \ --ee-jwt-secret-file= \ --metrics-enabled=true \ --rest-api-enabled=true \ - --rest-api-host-allowlist=127.0.0.1 \ - --p2p-advertised-ip= \ + --p2p-advertised-ip= \ --checkpoint-sync-url= \ --validators-proposer-default-fee-recipient= \ --validator-keys=:[,:,...] @@ -194,6 +191,8 @@ Specify: - The path to the `jwtsecret.hex` file generated in [step 2](#2-generate-the-shared-secret) using the [`--ee-jwt-secret-file`](https://docs.teku.consensys.io/reference/cli#ee-jwt-secret-file) option. +- The public IP address of your Teku node using the + [`--p2p-advertised-ip`](https://docs.teku.consensys.io/reference/cli#p2p-advertised-ip) option. - The URL of a checkpoint sync endpoint using the [`--checkpoint-sync-url`](https://docs.teku.consensys.io/reference/cli#checkpoint-sync-url) option. - The test Ethereum address created in [step 3](#3-generate-validator-keys) as the default fee From b7e894b333aaf1eff41449db17c9d5f490ae9967 Mon Sep 17 00:00:00 2001 From: Alexandra Carrillo <12214231+alexandratran@users.noreply.github.com> Date: Fri, 5 Jul 2024 09:39:19 -0700 Subject: [PATCH 3/3] Update docs/public-networks/how-to/connect/manage-peers.md Signed-off-by: Alexandra Carrillo <12214231+alexandratran@users.noreply.github.com> --- docs/public-networks/how-to/connect/manage-peers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/public-networks/how-to/connect/manage-peers.md b/docs/public-networks/how-to/connect/manage-peers.md index 176fb3f9cb2..63831218b96 100644 --- a/docs/public-networks/how-to/connect/manage-peers.md +++ b/docs/public-networks/how-to/connect/manage-peers.md @@ -46,7 +46,7 @@ In detail, the P2P discovery process is as follows: 2. Besu attempts to connect to the network's bootnodes (a set of predefined nodes used to help bootstrap discovery). -3. Once a connection with a bootnode is established using TCP (`ping/pong` handshake messages in the +3. Once a connection with a bootnode is established using UDP (`ping/pong` handshake messages in the debug and trace logs), Besu requests a list of neighbors (potential peers) from the bootnode (`find node` messages in the debug and trace logs).