adding in some details re the peering process (#1643)

* adding in some details re the peering process Signed-off-by: Joshua Fernandes <[email protected]> * edit p2p discovery process and tutorials Signed-off-by: Alexandra Tran <[email protected]> * Update docs/public-networks/how-to/connect/manage-peers.md Signed-off-by: Alexandra Carrillo <[email protected]> --------- Signed-off-by: Joshua Fernandes <[email protected]> Signed-off-by: Alexandra Tran <[email protected]> Signed-off-by: Alexandra Carrillo <[email protected]> Co-authored-by: Alexandra Tran <[email protected]> Co-authored-by: Alexandra Carrillo <[email protected]>
hyperledger · Jul 5, 2024 · 42b7710 · 42b7710
1 parent 5caba7a
commit 42b7710
Show file tree

Hide file tree

Showing 3 changed files with 68 additions and 22 deletions.
diff --git a/docs/public-networks/how-to/connect/manage-peers.md b/docs/public-networks/how-to/connect/manage-peers.md
@@ -9,17 +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.
 
 :::info
+You can use [`admin_addPeer`](../../reference/cli/options.md#admin_addpeer) to attempt a specific
+connection, but this isn't P2P discovery.
+:::
 
-You can use [`admin_addPeer`](../../reference/cli/options.md#admin_addpeer) to attempt a specific connection, but this isn't P2P discovery.
+In private networks, we recommend
+[using bootnodes](../../../private-networks/how-to/configure/bootnodes.md) to initially discover peers.
 
-:::
+## P2P discovery process
+
+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.
+
+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.
+
+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 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).
+
+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
@@ -53,31 +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="0.0.0.0"    \
-  --rpc-ws-enabled=true        \
-  --rpc-ws-host="0.0.0.0"      \
-  --host-allowlist=<IP of Besu node>,127.0.0.1,localhost        \
-  --engine-host-allowlist=<IP of Besu node>,127.0.0.1,localhost \
-  --engine-rpc-enabled         \
+  --sync-mode=SNAP                                             \
+  --data-storage-format=BONSAI                                 \
+  --rpc-http-enabled=true                                      \
+  --p2p-host=<your public IP>                                  \
+  --host-allowlist=<your public IP>,127.0.0.1,localhost        \
+  --engine-host-allowlist=<your public IP>,127.0.0.1,localhost \
+  --engine-rpc-enabled                                         \
   --engine-jwt-secret=<path to jwtsecret.hex>
 ```
 
 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.
@@ -96,13 +91,16 @@ teku \
   --ee-jwt-secret-file=<path to jwtsecret.hex> \
   --metrics-enabled=true                       \
   --rest-api-enabled=true                      \
+  --p2p-advertised-ip=<your public IP>         \
   --checkpoint-sync-url=<checkpoint sync URL>
 ```
 
 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
@@ -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=0.0.0.0     \
   --rpc-http-cors-origins="*" \
   --rpc-ws-enabled=true       \
-  --rpc-ws-host=0.0.0.0       \
+  --p2p-host=<your public IP> \
   --host-allowlist="*"        \
   --engine-host-allowlist="*" \
   --engine-rpc-enabled        \
@@ -87,10 +86,9 @@ besu \
 besu \
   --network=sepolia           \
   --rpc-http-enabled=true     \
-  --rpc-http-host=0.0.0.0     \
   --rpc-http-cors-origins="*" \
   --rpc-ws-enabled=true       \
-  --rpc-ws-host=0.0.0.0       \
+  --p2p-host=<your public IP> \  
   --host-allowlist="*"        \
   --engine-host-allowlist="*" \
   --engine-rpc-enabled        \
@@ -124,6 +122,7 @@ teku \
   --ee-jwt-secret-file=<path to jwtsecret.hex> \
   --metrics-enabled=true                       \
   --rest-api-enabled=true                      \
+  --p2p-advertised-ip=<your public IP>         \  
   --checkpoint-sync-url=<checkpoint sync URL>
 ```
 
@@ -138,6 +137,7 @@ teku \
   --ee-jwt-secret-file=<path to jwtsecret.hex> \
   --metrics-enabled=true                       \
   --rest-api-enabled=true                      \
+  --p2p-advertised-ip=<your public IP>         \  
   --checkpoint-sync-url=<checkpoint sync URL>
 ```
 
@@ -149,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.
 
@@ -169,6 +171,7 @@ teku \
   --ee-jwt-secret-file=<path to jwtsecret.hex>              \
   --metrics-enabled=true                                    \
   --rest-api-enabled=true                                   \
+  --p2p-advertised-ip=<your public IP>                      \  
   --checkpoint-sync-url=<checkpoint sync URL>               \
   --validators-proposer-default-fee-recipient=<ETH address> \
   --validator-keys=<path to key file>:<path to password file>[,<path to key file>:<path to password file>,...]
@@ -188,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