Generate a PFN Identity

Validators and VFNs have their identities initialized when first created and their identities are long-lived (immutable). PFN identities are more ephemeral and can be regenerated on demand. As such, generating an identity using this guide should only be done for PFNs, and not for validators or VFNs.

Ephemeral vs. Static Identities

Public fullnodes (PFNs) will automatically start up with a randomly generated (ephemeral) network identity unless a static identity is provided. This works well for regular PFNs. However, there are cases where you may want to generate and assign a static network identity to your PFN.

Ephemeral Identity

• Automatically generated on startup. The same ephemeral identity is used across restarts if the identity key file already exists.

• Stored at /opt/aptos/data/db/ephemeral_identity_key.

Static Identity

This is useful when:

• You wish to advertise your PFN as a seed (i.e., for other Aptos PFNs to connect to).

• You wish to add your PFN to an allowlist of known identities on an upstream PFN or VFN.

• You wish to fix the identity of your PFN across restarts and releases so that telemetry and other monitoring tools can track your PFN over time.

Before you proceed, make sure that you already know how to start your local PFN. See Run a PFN for detailed documentation.

Generate a static identity

To create a static identity for your PFN, you will first need to generate a private and public key pair. You will then need to derive the peer_id from the public key, and use the peer_id in your configuration file (e.g., fullnode.yaml) to configure the static network identity for your PFN.

The steps below will guide you through the process of generating a static identity for your PFN. The exact steps depend on whether you are using the aptos-core source code to run your PFN, or Docker.

Using the aptos-core source code

If you use the aptos-core source code to run your PFN, follow these steps:

1. Generate the private key

First, use the Aptos CLI (aptos) to produce a hex encoded static x25519 private key. This will be the private key for your network identity. Run the following aptos CLI command:

Terminal

aptos key generate --key-type x25519 --output-file /path/to/private-key.txt

This command will create a file private-key.txt with the private key in it, and a corresponding private-key.txt.pub file with the public key in it. An example private-key.txt file and private-key.txt.pub file are shown below:

Terminal

cat ~/private-key.txtC83110913CBE4583F820FABEB7514293624E46862FAE1FD339B923F0CACC647D% cat ~/private-key.txt.pubB881EA2C174D8211C123E5A91D86227DB116A44BB345A6E66874F83D8993F813%

1. Retrieve the peer identity

Next, retrieve the peer identity from the public key using the aptos CLI. The --host flag in the command will provide the host information to output a network address for your PFN. Run the following command (be sure to update the --host flag with your actual host information):

Terminal

aptos key extract-peer --host example.com:6180 \    --public-network-key-file private-key.txt.pub \    --output-file peer-info.yaml

This command will output the public identity information for your PFN to a file peer-info.yaml. For example:

{  "Result": {    "B881EA2C174D8211C123E5A91D86227DB116A44BB345A6E66874F83D8993F813": {      "addresses": [        "/dns/example.com/tcp/6180/noise-ik/0xB881EA2C174D8211C123E5A91D86227DB116A44BB345A6E66874F83D8993F813/handshake/0"      ],      "keys": [        "0xB881EA2C174D8211C123E5A91D86227DB116A44BB345A6E66874F83D8993F813"      ],      "role": "Upstream"    }  }}

In this example, B881EA2C174D8211C123E5A91D86227DB116A44BB345A6E66874F83D8993F813 is the peer_id.

1. Start a PFN with the identity

After extracting the peer identity from the public key, you can start your PFN with the identity using the public key in the peer_id field of the configuration file (e.g., fullnode.yaml). For example:

fullnode.yaml

full_node_networks:  - network_id: "public"discovery_method: "onchain"identity:  type: "from_config"  key: "<PRIVATE_KEY>"  peer_id: "<PEER_ID>"

In our example (from above), the configuration file (fullnode.yaml) should now have the following information:

fullnode.yaml

full_node_networks:  - network_id: "public"    discovery_method: "onchain"    identity:      type: "from_config"      key: "C83110913CBE4583F820FABEB7514293624E46862FAE1FD339B923F0CACC647D"      peer_id: "B881EA2C174D8211C123E5A91D86227DB116A44BB345A6E66874F83D8993F813"

Starting your PFN with this configuration will assign your PFN with the static network identity you generated.