[Documentation] Fixing ambiguous language in network identity section. (

aptos-labs#873) [Documentation] Fixing ambiguous language in network identity section. [Documentation] Fixing ambiguous language in network identity section. [Documentation] Fixing ambiguous language in network identity section. [Documentation] Fixing ambiguous language in network identity section. [Documentation] Fixing typos. [Documentation] Working in review comments. [Documentation] Working in review comments. [Documentation] Fixing list numbering.
talk2nil · May 12, 2022 · 5a4e035 · 5a4e035
1 parent 8ec7751
commit 5a4e035
Showing 1 changed file with 81 additions and 49 deletions.
diff --git a/developer-docs-site/docs/tutorials/full-node/network-identity-fullnode.md b/developer-docs-site/docs/tutorials/full-node/network-identity-fullnode.md
@@ -6,10 +6,21 @@ sidebar_position: 12
 
 # Network Identity For FullNode
 
+FullNodes will automatically start up with a randomly generated network identity. This works well for regular FullNodes. However:
+
+- You may want your FullNode to be added to a specific upstream FullNode's allowlist (i.e., another FullNode participant in the Aptos network), because:
+
+  - You might require specific permissions for your FullNode on this specific upstream FullNode, or
+  - This upstream FullNode only allows known identities to connect to it, or
+  - You may wish to advertise your FullNode for other Aptos FullNodes to connect to (to help support the Aptos network).
+
+In such cases, it helps if you run your FullNode with a static network identity, instead of a randomly generated network identity that keeps changing every time you start up your FullNode.
+
 This guide will show you how to:
+
 - Create a static network identity for your FullNode.
-- Retrieve the public network identity.
-- Start a node with (or without) a static network identity.
+- Start a node with a static network identity.
+- Allow other FullNodes to connect to your FullNode.
 
 ## Before you proceed
 
@@ -23,7 +34,13 @@ Docker container is currently supported only on Linux x86-64 platform. If you ar
 
 ## Creating a static identity for a FullNode
 
-FullNodes will automatically start up with a randomly generated network identity (a `PeerId` and a public key pair). This works well for regular FullNodes, but you may wish to be added to another node's allowlist, provide specific permissions or run your FullNode with the same identity. In this case, creating a static network identity can help.
+To create a static identity for your FullNode:
+
+1. You first create a private key, public key pair for your FullNode.
+2. Next you derive the `peer_id` from the public key.
+3. Finally, you use the `peer_id` in your `public_full_node.yaml` to create a static network identity for your FullNode.
+
+Follow the below detailed steps:
 
 1. Fork and clone the [aptos-labs/aptos-core](https://github.com/aptos-labs/aptos-core) repo. For example:
 
@@ -36,7 +53,9 @@ FullNodes will automatically start up with a randomly generated network identity
 
     **Using Docker**
 
-    Alternatively, if you are on Linux x86-64 platform, you can use Aptos Docker image. `cd` into the directory for your local public FullNode and start a Docker container with the latest tools, for example:
+    Alternatively, if you are on Linux x86-64 platform, you can use the Aptos Docker image.
+
+    `cd` into the directory for your local public FullNode and start a Docker container with the latest tools, for example:
 
     ```
     $ cd ~/my-full-node
@@ -51,23 +70,12 @@ FullNodes will automatically start up with a randomly generated network identity
 
   :::
 
-    ```
-    aptos key generate --key-type x25519 --output-file /path/to/private-key.txt
-
-    ```
-
-    **Using Docker**
-
-    From inside the `aptoslab/tools` Docker container. Open a new terminal and `cd` into the directory where you started the Docker container for your FullNode. Making sure to provide the full path to where you want the private key TXT file to be stored, run the command as below:
+  ```
+  aptos key generate --key-type x25519 --output-file /path/to/private-key.txt
 
-    ```
-    aptos-operational-tool generate-key \
-        --encoding hex \
-        --key-type x25519 \
-        --key-file /path/to/private-key.txt
-    ```
+  ```
 
-Example `private-key.txt` and the associated `private-key.txt.pub` files are shown below:
+  Example `private-key.txt` and the associated `private-key.txt.pub` files are shown below:
 
   ```
   $ cat ~/private-key.txt
@@ -77,41 +85,56 @@ Example `private-key.txt` and the associated `private-key.txt.pub` files are sho
   B881EA2C174D8211C123E5A91D86227DB116A44BB345A6E66874F83D8993F813%
   ```
 
-## Retrieve the public network identity
-
-As shown above, when you use Aptos-core source to generate a private key, the associated public identity key will also be generated.
-
   **Using Docker**
 
-  From inside the `aptoslab/tools` Docker container:
+  Run this step from inside the `aptoslab/tools` Docker container. Open a new terminal and `cd` into the directory where you started the Docker container for your FullNode. Making sure to provide the full path to where you want the private key TXT file to be stored, run the command as below:
 
   ```
-  $ aptos-operational-tool extract-peer-from-file \
+  aptos-operational-tool generate-key \
       --encoding hex \
-      --key-file /path/to/private-key.txt \
-      --output-file /path/to/peer-info.yaml
+      --key-type x25519 \
+      --key-file /path/to/private-key.txt
   ```
 
-This will create a YAML file that will have your public identity in it. This is useful if you want to connect your FullNode to a specific upstream FullNode, and that FullNode only allows known identities to connect to them.
+3. Retrieve the peer identity
 
-Example output `peer-info.yaml`:
+  When you use Aptos-core source to generate a private key, use the below Aptos CLI command to generate the `peer_id`:
 
- ```
- ---
- 2a873fd3fb4e334b729966dc5aa68118fb5ba7c2c0c39d9860e709fd6589214b:
-   addresses: []
-   keys:
-     - "0x2a873fd3fb4e334b729966dc5aa68118fb5ba7c2c0c39d9860e709fd6589214b"
- role: Upstream
   ```
+  aptos key extract-peer  --private-key-file private-key.txt  \
+      --output-file peer-info.yaml
+  ```
+
+    **Using Docker**
 
-  In this example, `2a873fd3fb4e334b729966dc5aa68118fb5ba7c2c0c39d9860e709fd6589214b` is the peer ID as well as the public key, which is derived from the private key you generated from the previous step.
+    From inside the `aptoslab/tools` Docker container:
 
+    ```
+    $ aptos-operational-tool extract-peer-from-file \
+        --encoding hex \
+        --key-file /path/to/private-key.txt \
+        --output-file /path/to/peer-info.yaml
+    ```
+
+  This will create a YAML file that will have your `peer_id` corresponding to the `private-key.txt` you provided.
+
+  Example output `peer-info.yaml`:
+
+   ```
+   ---
+   B881EA2C174D8211C123E5A91D86227DB116A44BB345A6E66874F83D8993F813:
+     addresses: []
+     keys:
+       - "0xB881EA2C174D8211C123E5A91D86227DB116A44BB345A6E66874F83D8993F813"
+   role: Upstream
+    ```
+
+  In this example, `B881EA2C174D8211C123E5A91D86227DB116A44BB345A6E66874F83D8993F813` is the `peer_id`. Use this in the `peer_id` field of your `public_full_node.yaml` to create a static identity for your FullNode.
 
 
 ## Start a node with a static network identity
 
-Once you have the static identity you can startup the FullNode by modifying the configuration file `public_full_node.yaml`:
+After you generated the public identity key you can startup the FullNode with a static network identity by using the public key in the `peer_id` field of the configuration file `public_full_node.yaml`:
 
 ```
 full_node_networks:
@@ -123,25 +146,34 @@ full_node_networks:
     peer_id: "<PEER_ID>"
 ```
 
-In our example, we'd specify:
+In our example, you would specify the above-generated `peer_id` in place of the `<PEER_ID>`:
 
 ```
 full_node_networks:
 - network_id: "public"
   discovery_method: "onchain"
   identity:
     type: "from_config"
-    key: "B8BD811A91D8E6E0C6DAC991009F189337378760B55F3AD05580235325615C74"
-    peer_id: "ca3579457555c80fc7bb39964eb298c414fd60f81a2f8eedb0244ec07a26e575"
+    key: "C83110913CBE4583F820FABEB7514293624E46862FAE1FD339B923F0CACC647D"
+    peer_id: "B881EA2C174D8211C123E5A91D86227DB116A44BB345A6E66874F83D8993F813"
 ```
 
 ## Allowing other FullNodes to connect
 
-Once you start your FullNode with a static identity you can allow others to connect to devnet through your node. Follow these recommendations:
+Once you start your FullNode with a static identity you can allow others to connect to devnet through your node.
+
+:::note
 
-- Make sure you open port `6180` (or `6182`, depending on which port your node is listening to) and that you open your firewall.
+In the below steps, the port numbers used are for illustration only. You can use your choice of port numbers.
+
+:::
+
+- Make sure you open port `6180` (or `6182`, for example, depending on which port your node is listening to) and that you open your firewall.
 - If you are using Docker, simply add `- "6180:6180"` or `- "6182:6182"` under ports in your ``docker-compose.yaml`` file.
-- You'll need to share your FullNode info for others to use as `seeds` in their configurations (e.g., `peer-info.yaml`):
+- Share your FullNode static network identity with others. They can then use it in the `seeds` key of their `public_full_node.yaml` file to connect to your FullNode.
+- Make sure the port number you put in the `addresses` matches the one you have in the FullNode configuration file `public_full_node.yaml` (for example, `6180` or `6182`).
+
+Share your FullNode static network identity in the following format in the Discord channel `advertise-full-nodes`:
 
   ```
   <Peer_ID>:
@@ -156,16 +188,16 @@ Once you start your FullNode with a static identity you can allow others to conn
     role: Upstream
   ```
 
-- Make sure the port number you put in the `addressses` matches the one you have in the FullNode config (`6180` or `6182`). For example:
+ For example:
 
   ```
-  bb14af025d226288a3488b4433cf5cb54d6a710365a2d95ac6ffbd9b9198a86a:
+  B881EA2C174D8211C123E5A91D86227DB116A44BB345A6E66874F83D8993F813:
     addresses:
-    - "/dns4/pfn0.node.devnet.aptoslabs.com/tcp/6182/ln-noise-ik/bb14af025d226288a3488b4433cf5cb54d6a710365a2d95ac6ffbd9b9198a86a/ln-handshake/0"
+    - "/dns4/pfn0.node.devnet.aptoslabs.com/tcp/6182/ln-noise-ik/B881EA2C174D8211C123E5A91D86227DB116A44BB345A6E66874F83D8993F813/ln-handshake/0"
     role: "Upstream"
-  bb14af025d226288a3488b4433cf5cb54d6a710365a2d95ac6ffbd9b9198a86a:
+  B881EA2C174D8211C123E5A91D86227DB116A44BB345A6E66874F83D8993F813:
     addresses:
-    - "/ip4/100.20.221.187/tcp/6182/ln-noise-ik/bb14af025d226288a3488b4433cf5cb54d6a710365a2d95ac6ffbd9b9198a86a/ln-handshake/0"
+    - "/ip4/100.20.221.187/tcp/6182/ln-noise-ik/B881EA2C174D8211C123E5A91D86227DB116A44BB345A6E66874F83D8993F813/ln-handshake/0"
     role: "Upstream"
   ```