edit p2p discovery process and tutorials

Signed-off-by: Alexandra Tran <[email protected]>
hyperledger · Jul 3, 2024 · a7e21cf · a7e21cf
1 parent 821040b
commit a7e21cf
Show file tree

Hide file tree

Showing 3 changed files with 65 additions and 43 deletions.
diff --git 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
@@ -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=<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         \
+  --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.
@@ -95,15 +91,16 @@ teku \
   --ee-jwt-secret-file=<path to jwtsecret.hex> \
   --metrics-enabled=true                       \
   --rest-api-enabled=true                      \
-  --rest-api-host-allowlist=127.0.0.1          \
-  --p2p-advertised-ip=<YOUR PUBLIC IP>         \
+  --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=127.0.0.1   \
   --rpc-http-cors-origins="*" \
   --rpc-ws-enabled=true       \
-  --p2p-host=<YOUR PUBLIC IP> \
+  --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=127.0.0.1   \
   --rpc-http-cors-origins="*" \
   --rpc-ws-enabled=true       \
-  --p2p-host=<YOUR PUBLIC IP> \  
+  --p2p-host=<your public IP> \  
   --host-allowlist="*"        \
   --engine-host-allowlist="*" \
   --engine-rpc-enabled        \
@@ -124,8 +122,7 @@ teku \
   --ee-jwt-secret-file=<path to jwtsecret.hex> \
   --metrics-enabled=true                       \
   --rest-api-enabled=true                      \
-  --rest-api-host-allowlist=127.0.0.1          \
-  --p2p-advertised-ip=<YOUR PUBLIC IP>         \  
+  --p2p-advertised-ip=<your public IP>         \  
   --checkpoint-sync-url=<checkpoint sync URL>
 ```
 
@@ -140,8 +137,7 @@ teku \
   --ee-jwt-secret-file=<path to jwtsecret.hex> \
   --metrics-enabled=true                       \
   --rest-api-enabled=true                      \
-  --rest-api-host-allowlist=127.0.0.1          \
-  --p2p-advertised-ip=<YOUR PUBLIC IP>         \  
+  --p2p-advertised-ip=<your public IP>         \  
   --checkpoint-sync-url=<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=<path to jwtsecret.hex>              \
   --metrics-enabled=true                                    \
   --rest-api-enabled=true                                   \
-  --rest-api-host-allowlist=127.0.0.1                       \
-  --p2p-advertised-ip=<YOUR PUBLIC IP>                      \  
+  --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>,...]
@@ -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