Connect to Aptos Network

This document describes how to connect your running validator node and validator fullnode to an Aptos network. Follow these instructions only if your validator has met the minimal staking requirement.

Minimum staking requirement

The current required minimum for staking is 1M APT tokens.

Initializing the stake pool

First, you need to initialize the stake pool.

To initialize a staking pool, follow the instructions in staking pool operations.

To initialize a delegation pool, follow the instructions in delegation pool operations.

Bootstrapping validator node

After initializing the stake pool, make sure the validator node is bootstrapped with the correct genesis blob and waypoint for the corresponding network.

1. Follow the steps for joining the validator set.
2. Bring up the validator fullnode (VFN) only. It will connect to other nodes and fast sync.
3. Once the VFN is synced, bring up the validator. It will sync from the VFN and then connect to other validators and start participating in consensus.

To bootstrap your node, first you need to know the pool address to use:

aptos node get-stake-pool \
  --owner-address <owner_address>

Using source code

1. Stop your node and remove the data directory.
   • Make sure you remove the secure-data.json file also. View validator.yaml to see the location of the secure-data.json file.
2. Download the genesis.blob and waypoint.txt files published by Aptos.
   • See Node Files for your network (mainnet, testnet, or devnet) for the locations and commands to download these files.
3. Update your account_address in the validator-identity.yaml and validator-fullnode-identity.yaml files to your pool address. Do not change anything else. Keep the keys as they are.
4. Pull the latest changes from the associated (ex. mainnet) branch.
5. Close the metrics port 9101 and the REST API port 80 on your validator (you can leave it open for public fullnode).
6. Restart the validator node and validator fullnode.

Using Docker

1. Stop your node and remove the data volumes: docker compose down --volumes.
   • Make sure you remove the secure-data.json file too. See this validator.yaml line for the location of the secure-data.json file.
2. Download the genesis.blob and waypoint.txt files published by Aptos.
   • See Node Files for locations and commands to download these files.
3. Update your account_address in the validator-identity.yaml and validator-fullnode-identity.yaml files to your pool address.
4. Update your Docker image to the latest release of the network branch (e.g. mainnet, testnet).
5. Close the metrics port 9101 and the REST API port 80 on your validator (remove it from the Docker compose file). You can leave it open for the public fullnode.
6. Restart the node with: docker compose up

Using Terraform

1. Increase the era number in your Terraform configuration. When this configuration is applied, it will wipe the data.

2. Update chain_id to 1 (for mainnet). The chain IDs for other Aptos networks are in Aptos Blockchain Networks.

3. Update your Docker image to the latest release of the network branch (e.g. mainnet, testnet).

4. Close the metrics port and the REST API port for validator.

5. Add monitoring components

Supported only using Terraform

This is currently only supported using Terraform.

1. Set the enable_monitoring variable in your terraform module. For example:

   module "aptos-node" {
     ...
     enable_monitoring           = true
     utility_instance_num        = 3  # this will add one more utility instance to run monitoring component
   }

2. Apply the changes with: terraform apply

3. You will see a new pod getting created. Run kubectl get pods to check.

4. Access the dashboard.

   First, find the IP/DNS for the monitoring load balancer.

   kubectl get svc ${WORKSPACE}-mon-aptos-monitoring --output jsonpath='{.status.loadBalancer.ingress[0]}'

   You can access the dashboard on http://<ip/DNS>.

5. Pull latest of the terraform module terraform get -update, and then apply Terraform: terraform apply.

6. Download the genesis.blob and waypoint.txt files published by Aptos.

   • See Node Files for locations and commands to download these files.

7. Update your account_address in the validator-identity.yaml and validator-fullnode-identity.yaml files to your pool address. Do not change anything else. Keep the keys as they are.

8. Recreate the secrets. Make sure the secret name matches your era number, e.g. if you have era = 3, then you should replace the secret name to be:

${WORKSPACE}-aptos-node-0-genesis-e3

export WORKSPACE=<your workspace name>

kubectl create secret generic ${WORKSPACE}-aptos-node-0-genesis-e2 \
    --from-file=genesis.blob=genesis.blob \
    --from-file=waypoint.txt=waypoint.txt \
    --from-file=validator-identity.yaml=keys/validator-identity.yaml \
    --from-file=validator-full-node-identity.yaml=keys/validator-full-node-identity.yaml

Joining Validator Set

Next, follow the below steps to set up the validator node using the operator account and join the validator set. This is required for your validator and validator fullnode to start syncing.

Mainnet vs Testnet

The below CLI command examples use mainnet. Change the --network value for testnet and devnet. View the values in Aptos Blockchain Networks to see how profiles can be configured based on the network.

1. Initialize Aptos CLI

aptos init --profile mainnet-operator \
--network mainnet \
--private-key <operator_account_private_key> \
--skip-faucet

tip

The account_private_key for the operator can be found in the private-keys.yaml file under ~/$WORKSPACE/keys folder.

2. Check your validator account balance

Make sure you have enough APT to pay for gas. You can check for this either on the Aptos Explorer or using the CLI:

• On the Aptos Explorer https://explorer.aptoslabs.com/account/<account-address>?network=Mainnet, or

• Use the CLI:

  aptos account list --profile mainnet-operator

This will show you the coin balance you have in the validator account. You will see an output like below:

"coin": {
    "value": "5000"
  }

Already in validator set? Skip to Step 6

If you know you are already in the validator set, then skip steps 3, 4, and 5 and go directly to step 6 to confirm it.

3. Update validator network addresses on-chain

aptos node update-validator-network-addresses  \
  --pool-address <pool-address> \
  --operator-config-file ~/$WORKSPACE/$USERNAME/operator.yaml \
  --profile mainnet-operator

Important notes

The network address updates and the consensus key rotation will be applied only at the end of the current epoch. Note that the validator need not leave the validator set to make these updates. You can run the commands for address and key changes. For the remaining duration of the current epoch your validator will still use the old key and addresses but when the epoch ends it will switch to the new key and addresses.

4. Rotate the validator consensus key on-chain

aptos node update-consensus-key  \
  --pool-address <pool-address> \
  --operator-config-file ~/$WORKSPACE/$USERNAME/operator.yaml \
  --profile mainnet-operator

5. Join the validator set

aptos node join-validator-set \
  --pool-address <pool-address> \
  --profile mainnet-operator

The validator set is updated at every epoch change. You will see your validator node joining the validator set only in the next epoch. Both validator and validator fullnode will start syncing once your validator is in the validator set.

When is next epoch?

You can see it on the Aptos Explorer or by running the command aptos node get-stake-pool as shown in Checking your stake pool information.

6. Check the validator set

When you join the validator set, your validator node will be in "Pending Active" state until the next epoch occurs. During this time you might see errors like "No connected AptosNet peers". This is normal. Run the below command to look for your validator in the "pending_active" list.

aptos node show-validator-set --profile mainnet-operator | jq -r '.Result.pending_active' | grep <pool_address>

When the next epoch happens, the node will be moved into "active_validators" list. Run the below command to see your validator in the "active_validators" list:

aptos node show-validator-set --profile mainnet-operator | jq -r '.Result.active_validators' | grep <pool_address>

You should expect the active value for your StakePool to keep increasing. It is updated at every epoch.

Verify Node Correctness

Now that you have joined the validator set, you should verify your node correctness.

First time syncing?

Note that in some environments, e.g., testnet, your validator fullnode will begin syncing first (before your validator is able to sync). This is normal behaviour. Once your validator fullnode has finished syncing, your validator node will start syncing and eventually start participating in consensus.

Node Liveness Definition

See node liveness criteria for details.

After your validator node has joined the validator set, you can validate its correctness by following these steps:

1. Check if your node is state syncing. Replace 127.0.0.1 with your validator IP/DNS if deployed on the cloud.

   curl 127.0.0.1:9101/metrics 2> /dev/null | grep "aptos_state_sync_version"

   You should expect to see the synced or synced_states versions increasing. The versions should start increasing for your validator fullnode first, then eventually your validator node will start syncing.

2. Verify that your validator is connecting to other peers on the network.

   curl 127.0.0.1:9101/metrics 2> /dev/null | grep "aptos_connections{.*\"Validator\".*}"

   The command will output the number of inbound and outbound connections of your validator node. For example:

   aptos_connections{direction="inbound",network_id="Validator",peer_id="f326fd30",role_type="validator"} 5
   aptos_connections{direction="outbound",network_id="Validator",peer_id="f326fd30",role_type="validator"} 2

   As long as one of the metrics is greater than zero, your validator node is connected to at least one of the peers on the network. If your validator is not connected to any peers, make sure your validator fullnode has completed syncing first. Once your validator fullnode has finished syncing, your validator node will start syncing and eventually be able to connect to other peers.

3. You can also check if your node is connected to an Aptos node: replace <Aptos Peer ID> with the peer ID shared by Aptos team.

   curl 127.0.0.1:9101/metrics 2> /dev/null | grep "aptos_network_peer_connected{.*remote_peer_id=\"<Aptos Peer ID>\".*}"

4. After your node state syncs to the latest version, you can also check if consensus is making progress, and your node is proposing.

   curl 127.0.0.1:9101/metrics 2> /dev/null | grep "aptos_consensus_current_round"
   
   curl 127.0.0.1:9101/metrics 2> /dev/null | grep "aptos_consensus_proposals_count"

   You should expect to see this number keep increasing.

5. Finally, the most straight forward way to see if your node is functioning properly is to check if it is making staking reward. You can check it on the Aptos Explorer: https://explorer.aptoslabs.com/account/<owner-account-address>?network=Mainnet:

   0x1::stake::StakePool
   
   "active": {
     "value": "100009129447462"
   }