Connect to a Network

This document describes how to connect your validator and validator fullnode (VFN) to an Aptos network.

At a high-level, there are four steps required to connect your nodes to an Aptos network:

1. Initialize stake pool

   First, you will need to initialize the stake pool.

2. Update identities

   Second, you will need to update your node identity configurations to match the pool address.

3. Join validator set

   Third, you will need to join the validator set.

4. Bootstrap your nodes

   Finally, you will need to bootstrap your nodes, so they can connect to the network and start syncing.

We will go through each of these steps in detail below.

To begin, you will need to initialize the staking pool for your nodes. There are two types of pools you can initialize, a staking pool or a delegation pool. You can read more about the differences between these pools in the Staking and Delegated Staking sections.

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

Before joining the validator set, you will need to update your node identity configuration files to match the pool address. This is required to ensure that your nodes are able to connect to other peers in the network.

Follow the steps below to update your node identity configurations, depending on the deployment method you used.

If you used the source code to deploy your nodes, follow these steps:

1. Stop your validator and VFN and remove the data directory from both nodes. Make sure to remove the secure-data.json file on the validator, too. You can see the location of the secure-data.json file in your validator’s configuration file.
2. Update your account_address in the validator-identity.yaml and validator-fullnode-identity.yaml files to your pool address. Do not change anything else.
3. Restart the validator and VFN.

If you used Docker to deploy your nodes, follow these steps:

1. Stop your node and remove the data volumes: docker compose down --volumes. Make sure to remove the secure-data.json file on the validator, too. You can see the location of the secure-data.json file in your validator’s configuration file.
2. Update your account_address in the validator-identity.yaml and validator-fullnode-identity.yaml files to your pool address. Do not change anything else.
3. Restart the nodes with: docker compose up

If you used Terraform to deploy your nodes (e.g., for AWS, Azure or GCP), follow these steps:

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

2. 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
   }

3. Apply the changes with: terraform apply You will see a new pod getting created. Run kubectl get pods to check.

4. Find the IP/DNS for the monitoring load balancer, using:

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

   You will be able to access the Terraform dashboard on http://<ip/DNS>.

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

6. Download the genesis.blob and waypoint.txt files for your network. 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.

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

Next, you will need to join the validator set. Follow the steps below:

First, initialize the Aptos CLI with your operator account private key. This can be found in your private-keys.yaml file under the entry account_private_key.

Replace <operator_account_private_key> with the value from the file in the command below:

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

Next, make sure you have enough funds to pay for transaction gas on the network. You can check this using the CLI, by running the command below:

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"
}

Next, you will need to update the network addresses for your validator and VFN. This is required to ensure that your nodes are able to connect to other peers in the network. First, fetch the pool address for your nodes, by running the command below. Note: the owner address is the address of the account that owns the stake pool, and was used to initialize the stake pool.

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

Using the pool address from the command above, you will need to update the network addresses for your nodes. You can do this by running the command below. Note that it requires the operator.yaml file, which was created when you first deployed your nodes.

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

Next, you will need to update the consensus key for your nodes. This is required to ensure that your nodes are able to participate in consensus. You can do this by running the command below. Note that it requires the pool address and the operator.yaml file (similar to above).

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

Finally, you will need to join the validator set. You can do this by running the command below:

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

The validator set is updated at the end of every epoch. You will need to wait for the next epoch to begin before your validator node is able to join the validator set.

When you execute the command to join the validator set, your validator will be in a “Pending Active” state until the next epoch occurs. You can run the command below 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 occurs, the node will be moved into active_validators list. Run the command below 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>

After joining the validator set and updating your node identity configurations to match the pool address, you will need to bootstrap your nodes to connect to the network. To do this, follow the steps below:

1. Start the VFN. The VFN will connect to the network and start syncing. See State Synchronization for more information.
2. Once the VFN is synced, restart the validator. It will sync from the VFN and then connect to other validators in the network and start participating in consensus.

Once both of these steps are complete, your nodes will be connected to the network and participating in consensus.

Congratulations! You have successfully connected your nodes to the Aptos network. To verify that your nodes are running correctly, visit the Node Health document. This document describes how you can verify and monitor the health of your validator and VFN, including an initial node verification section.