Switching Networks

By default, an Algorand installation is configured to run on MainNet. For most users, this is the desired outcome. Developers, however, need access to TestNet, BetaNet, and other networks. This guide describes switching between networks.

Replacing the Genesis File

Every Algorand node has a data directory that is used to store the ledger and other configuration information. As part of this configuration, a genesis.json file is used. The genesis.json file defines the initial state of the blockchain, its ‘genesis block’. This is a JSON formatted file with the schema for the blockchain. It contains the network name and ID, the protocol version, and the list of allocated addresses to start the chain with. Each address contains a list of things like address status and the amount of Algo owned by the address.

As part of the installer, a genesis directory is created under the node’s installed location for binaries. This directory contains additional directories for each of the Algorand networks: BetaNet, TestNet, MainNet, etc. These directories each contain the genesis.json file for that instance of the public Algorand networks (eg ~/var/lib/algorand/genesis/mainnet/genesis.json).

The genesis file for Debian and RPM installs are stored in the /var/lib/algorand/genesis/ directory.

The network can be switched by either replacing the current genesis file located in the data directory with the specific network genesis.json or by creating a new data directory and copying the specific network genesis.json file to the new data directory. Replacing the current genesis file will not destroy the current network data, but will prevent running multiple networks on the same node. To run multiple networks at the same time, multiple data directories are required.

Using a New Data Directory

Below are instructions for creating and using a new data directory (the recommended method). Follow the steps based on how your node is installed and managed.

Unmanaged (Command-Line Only) Install

This category includes:

• Other Linux Distributions using the updater script without systemd
• macOS installs without a launchctl service

Assumptions:

• Node binaries are in ~/node.
• Current data directory is ~/node/data.

1. Stop the current node

   cd ~/node

./goal node stop -d data

2. Create a New Directory and Copy the Genesis File (Adjust paths as needed, e.g. betanet/genesis.json for BetaNet.)

   mkdir data_testnet

cp ~/node/genesis/testnet/genesis.json ~/node/data_testnet

3. Start the Node on the New Network

   ./goal node start -d ~/node/data_testnet

4. Check Sync Status

   ./goal node status -d ~/node/data_testnet

The node will restart and begin communicating with the TestNet network. It will need to sync with the network which will take time.

At this point, it’s possible to run the original network again by starting the node with its original data directory on a different port.

Managed on Linux (systemd)

Applies typically to Debian or RPM installs or any Linux environment where Algorand is managed as a system service.

1. Create a New Data Directory

   export ALGORAND_DATA=/var/lib/algorand_testnet

sudo mkdir -p ${ALGORAND_DATA}

2. Copy the Genesis and System Files

   sudo cp -p /var/lib/algorand/genesis/testnet/genesis.json ${ALGORAND_DATA}/genesis.json

sudo cp -p /var/lib/algorand/system.json ${ALGORAND_DATA}/system.json

sudo chown -R algorand:algorand ${ALGORAND_DATA}

3. Enable and Start the New Service

   sudo systemctl enable algorand@$(systemd-escape ${ALGORAND_DATA})

sudo systemctl start algorand@$(systemd-escape ${ALGORAND_DATA})

4. Check sync status

   sudo -u algorand -E goal node status -d ${ALGORAND_DATA}

5. Stopping or Disabling

   sudo systemctl stop algorand@$(systemd-escape ${ALGORAND_DATA})

sudo systemctl disable algorand@$(systemd-escape ${ALGORAND_DATA})

Managed on macOS (launchctl)

This applies if the node is configured to run as a .plist service on macOS. If your macOS node is run purely via command line, follow the unmanaged installation process instead.

1. Unload the Current Service (Adjust path and filename as needed.)

   sudo launchctl bootout system /Library/LaunchDaemons/com.algorand.plist

2. Create a New Data Directory

   cd ~/node

mkdir data_testnet

cp ~/node/genesis/testnet/genesis.json ~/node/data_testnet

3. Update the .plist to reference the new data directory, for example:

   <key>EnvironmentVariables</key>

<dict>

<key>ALGORAND_DATA</key>

<string>/Users/USERNAME/node/data_testnet</string>

</dict>

4. Load the Updated Service

   sudo launchctl bootstrap system /Library/LaunchDaemons/com.algorand.plist

sudo launchctl start com.algorand

5. Check sync status (Wait until Sync Time: 0.0s indicates the node is fully caught up.)

   ./goal node status -d /Users/USERNAME/node/data_testnet

DNS Configuration for BetaNet

For the BetaNet network, when installing a new node or repeater, make the following modification to the config.json file located in the node’s data directory. Replace the line:

"DNSBootstrapID": "<network>.algorand.network",

with

"DNSBootstrapID": "<network>.algodev.network",

If former line is not present, just add the latter line. If there is no config.json in the Algorand data folder, just create a new one with the following content:

{

"DNSBootstrapID": "<network>.algodev.network"

}

This modification to the DNSBootstrapID is only necessary for the BetaNet network.