Install

---

Danger

Do not follow this guide if you are running an existing Algorand node on the same server, at it will likely overwrite your Algorand installation.

You will need to have some $VOI balance to complete this guide

You will need $VOI because:

• Transacting on the VOI network requires a small fee (0.001 $VOI)
• Participating in consensus is proportional to your balance

The last step of this guide includes “going online”, i.e. registering to participate in consensus. This is an on-chain transaction that costs 0.001 $VOI.

If you do not have $VOI yet, you can still complete all steps until that point while you wait to get some $VOI.

You can get 1 VOI to participate by running the command /voi-testnet-faucet on #node-runners on the Voi Discord.

Latest Version Tag

Install dependencies

Update system and install build tools

sudo apt -q update
sudo apt -qy install curl git jq lz4 build-essential
sudo apt -qy upgrade

Install file2ban

more here and here

# set and copy the config that will have higher priority
sudo apt install fail2ban -y && \
sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local && \
sudo nano /etc/fail2ban/jail.local

# uncomment and add your IP: ignoreip = 127.0.0.1.1/8 ::1 [ip]
sudo systemctl restart fail2ban

# check status
sudo systemctl status fail2ban

# check which jails are active (by default only sshd)
sudo fail2ban-client status

# check sshd statistics
sudo fail2ban-client status sshd

# look at the logs
sudo tail /var/log/fail2ban.log

# stop work and remove from autoloading
#sudo systemctl stop fail2ban && sudo systemctl disable fail2ban

Install Algorand node software

Danger

Do not follow this guide if you are running an existing Algorand node on the same server, at it will likely overwrite your Algorand installation.

Set up repository

1. Run the following commands to download some requirements and add the algorand repository, from which you will be getting your node software and its updates:

sudo apt install -y jq bc gnupg2 curl software-properties-common
curl -o - https://releases.algorand.com/key.pub | sudo tee /etc/apt/trusted.gpg.d/algorand.asc
sudo add-apt-repository "deb [arch=amd64] https://releases.algorand.com/deb/ stable main"

You will see a long output that ends in this prompt

-----END PGP PUBLIC KEY BLOCK-----
Repository: 'deb [arch=amd64] https://releases.algorand.com/deb/ stable main'
Description:
Archive for codename: stable components: main
More info: https://releases.algorand.com/deb/
Adding repository.
Press [ENTER] to continue or Ctrl-c to cancel.

2. As the prompt indicates, press ENTER to continue.

Install the node

Run this command to install the node:

sudo apt update && sudo apt install -y algorand && echo OK

Expected output will be similar to this:

The following NEW packages will be installed:
  algorand
0 upgraded, 1 newly installed, 0 to remove and 0 not upgraded.
Need to get 0 B/108 MB of archives.
After this operation, 0 B of additional disk space will be used.
Selecting previously unselected package algorand.
(Reading database ... 33854 files and directories currently installed.)
Preparing to unpack .../algorand_3.17.0_amd64.deb ...
Unpacking algorand (3.17.0) ...
Setting up algorand (3.17.0) ...
Created symlink /etc/systemd/system/multi-user.target.wants/algorand.service → /lib/systemd/system/algorand.service.
OK

Stop the node

By default, the algorand node will auto-start, which we do not want. Stop it with:

sudo systemctl stop algorand && sudo systemctl disable algorand && echo OK

Expected output: OK

Set up your shell to run goal

Run this command to help goal run properly on your shell:

echo -e "\nexport ALGORAND_DATA=/var/lib/algorand/" >> ~/.bashrc && source ~/.bashrc && echo OK

Set up your user

sudo adduser $(whoami) algorand && echo OK

Expected last line of output: OK

Configure your node for voi

1. Run these commands:

sudo algocfg set -p DNSBootstrapID -v "<network>.voi.network" -d /var/lib/algorand/ &&\
sudo algocfg set -p EnableCatchupFromArchiveServers -v true -d /var/lib/algorand/ &&\
sudo chown algorand:algorand /var/lib/algorand/config.json &&\
sudo chmod g+w /var/lib/algorand/config.json &&\
echo OK

Expected output: OK

2. Run this command to fetch the genesis file:

sudo curl -s -o /var/lib/algorand/genesis.json https://testnet-api.voi.nodly.io/genesis &&\
sudo chown algorand:algorand /var/lib/algorand/genesis.json &&\
echo OK

Expected output: OK

3. Rename the algorand service to voi:

sudo cp /lib/systemd/system/algorand.service /etc/systemd/system/voi.service &&\
sudo sed -i 's/Algorand daemon/Voi daemon/g' /etc/systemd/system/voi.service &&\
echo OK

Expected output: OK

Start your node

Time to start your node! Run this command to start your Voi node & configure it to restart automatically after a reboot:

sudo systemctl start voi && sudo systemctl enable voi && echo OK

Expected last line of output: OK

Check your status

Check the status of your node with the following command:

goal node status

Expected output should look like this:

Last committed block: 7
Time since last block: 1.0s
Sync Time: 3.5s
Last consensus protocol: https://github.com/algorandfoundation/specs/tree/abd3d4823c6f77349fc04c3af7b1e99fe4df699f
Next consensus protocol: https://github.com/algorandfoundation/specs/tree/abd3d4823c6f77349fc04c3af7b1e99fe4df699f
Round for next consensus protocol: 8
Next consensus protocol supported: true
Last Catchpoint:
Genesis ID: voitest-v1
Genesis hash: IXnoWtviVVJW5LGivNFc0Dq14V3kqaXuK2u5OQrdVZo=

It is important to check the Genesis ID and hash lines match:

Genesis ID: voitest-v1

and

Genesis hash: IXnoWtviVVJW5LGivNFc0Dq14V3kqaXuK2u5OQrdVZo=

Fast catch up with the network

Run the following command:

goal node catchup $(curl -s https://testnet-api.voi.nodly.io/v2/status|jq -r '.["last-catchpoint"]') &&\
echo OK

Expected last line of output: OK

Error?

If you encounter an error in this step, check the error carefully. If it includes already catching up towards the end, then everything is OK and you can proceed to the next step.

If you get an error that includes unable to start catchpoint service for requested catchpoint then try restarting the voi service and attempt to catch up again.

To restart the service use:

sudo systemctl restart voi && echo OK

Expected output: OK.

Then you should retry the catchup command. If you try the restart-catchup a few times and if it still doesn’t work, reach out on the Discord.

Check the node’s status

Check status with this command:

goal node status

There should now be several “Catchpoint: …” lines, like so:

Last committed block: 33069
Sync Time: 181.3s
Catchpoint: 30000#33ABPU3KRJEQIX4NCTMK4CSBNXWDXSN36X47OHDKJEVW7MPSK3ZA
Catchpoint total accounts: 33
Catchpoint accounts processed: 33
Catchpoint accounts verified: 33
Catchpoint total KVs: 0
Catchpoint KVs processed: 0
Catchpoint KVs verified: 0
Catchpoint total blocks: 1321
Catchpoint downloaded blocks: 796
Genesis ID: voitest-v1
Genesis hash: IXnoWtviVVJW5LGivNFc0Dq14V3kqaXuK2u5OQrdVZo=

If this does not happen, start over from the start of this section (“Fast catchup with the network”) or seek help on the Voi Discord.

If it does, it means that your node is processing a fast catchup to the latest state, which can save a lot of time.

Wait for fast catchup to complete

Run this command and wait until the “Catchpoint” lines disappear:

goal node status -w 1000

When the checkpoint lines disappear, wait for “Sync Time” to be 0.0s

After this you can exit the status command with Ctrl + C. You are now all synced up!

[Optional] Enable Telemetry

You can optionally enable node telemetry which will report stats and errors in order to detect issues and improve the blockchain.

Note

The initial node runners seed/airdrop will depend on telemetry data. If you want to receive it, you need to enable telemetry. Beyond that, block rewards will not depend on telemetry being enabled.

The following command will attach a friendly name to your telemetry. Replace “XXX” with your desired name, something like your NFD or nickname.

sudo ALGORAND_DATA=/var/lib/algorand diagcfg telemetry name -n XXX

Then you can enable telemetry and restart the voi service with this command:

sudo ALGORAND_DATA=/var/lib/algorand diagcfg telemetry enable &&\
sudo systemctl restart voi

You can check if the telemetry is working correctly by checking the Node Health section of the Monitoring web interface.

Reduced logging interferes with telemetry

If you have manually disabled or reduced logging on your node, telemetry will not work.

Your config.json must have BaseLoggerDebugLevel set to 4 (or not set at all.)

If you are following this guide without modifications, you can ignore this tip.

Join the node runners channel

To access the #node-runners channel on the Voi Discord, you need to:

1. Join the server and visit the #roles channel.
2. Emote with a running emoji 🏃 to the message there.
3. You should be able to access the #node-runners channel.

You can get 1 VOI to participate by running the command /voi-testnet-faucet in the #node-runners channel.

Participation

This part of the guide will walk you through adding an address via mnemonic to your node, generating participation keys and going online.

Create a node wallet container

The current recommendation is to use your node to sign transactions that will take your account online (participating) or offline (not participating.)

For this you will need to create an encrypted container (“wallet”) that is secured by a password. Your seed phrase(s) will be encrypted with this password, so pick something long and unpredictable. In the event that your node is compromised, this password will be all that stands between the attacker and your seed phrases.

You will need to enter this password whenever you need to sign transactions on your node.

How to generate a random 12 character password on your node

You can generate a random 12 character password on your node with this command:

tr -dc A-Z0-9 </dev/urandom | head -c 12 ; echo ''

You can then use this password in the next step.

Make sure to save this either on paper or in a password manager.

When you have decided on a very strong password, run this command to create the encrypted wallet container:

goal wallet new voi

You will be prompted to enter a password. Note the warnings above and enter one.

Expected output:

Please choose a password for wallet 'voi':
Please confirm the password:
Creating wallet...
Created wallet 'voi'
Your new wallet has a backup phrase that can be used for recovery.
Keeping this backup phrase safe is extremely important.
Would you like to see it now? (Y/n):

You will then be prompted to view your backup seed phrase. Press Y and ENTER to view it. Save it somewhere securely.

Create or import your participating address

In this step you can import your Voi account mnemonic on your node. You can either create a new account, or import an existing one.

Caution

We strongly recommend creating a new account for Voi. If you use an account that exists on Algorand, a potential compromise would affect you on both networks.

Choose your preferred method and expand it to view the instructions. You only need to do one of these.

Create a new account

Step 1:

You can create a new account in the container you just created with the following command:

goal account new

You will be prompted for your wallet container password that you created earlier.

Expected output:

Please enter the password for wallet 'voi':
Created new account with address AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA

Copy the newly created address, as we will use it in the next step.

Step2:

To display your new account’s mnemonic, use this command:

echo -ne "\nEnter your voi address: " && read addr &&\
goal account export -a $addr

It will prompt you for 1) the address generated in step 1, and 2) the password you created earlier. Expected output:

Enter your voi address:

Please enter the password for wallet 'voi':

Exported key for account AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA: "crystal sing shy patient toddler lady crouch frown salmon toilet token educate leader comic ignore harvest strike holiday twist pulse better result beyond absorb come"

Save this mnemonic securely. A paper backup or a password manager are good options.

You can now proceed to generating your participation keys

[Optional] Import an existing account using its mnemonic

Run this command:

goal account import

Enter your wallet password that you created above when prompted, then type or paste the mnemonic seed of the Voi account that you want to participate with. Press ENTER to import.

Please enter the password for wallet 'voi':
Please type your recovery mnemonic below, and hit return when you are done:
apple apple apple apple ...

It should output Imported [YOUR ADDRESS]

Generate your participation keys

Run this set of commands to generate the participation keys for your account.

It will prompt for:

1. your Voi address (in some cases) and
2. the participation duration, defaulting to 2000000 rounds (77 days at 3.3 second rounds.) Press ENTER to accept that.

getaddress() {
  if [ "$addr" == "" ]; then echo -ne "\nNote: Completing this will remember your address until you log out. "; else echo -ne "\nNote: Using previously entered address. "; fi; echo -e "To forget the address, press Ctrl+C and enter the command:\n\tunset addr\n";
  count=0; while ! (echo "$addr" | grep -E "^[A-Z2-7]{58}$" > /dev/null); do
    if [ $count -gt 0 ]; then echo "Invalid address, please try again."; fi
    echo -ne "\nEnter your voi address: "; read addr;
    addr=$(echo "$addr" | sed 's/ *$//g'); count=$((count+1));
  done; echo "Using address: $addr"
}
getaddress &&\
echo -ne "\nEnter duration in rounds [press ENTER to accept default)]: " && read duration &&\
start=$(goal node status | grep "Last committed block:" | cut -d\  -f4) &&\
duration=${duration:-2000000} &&\
end=$((start + duration)) &&\
dilution=$(echo "sqrt($end - $start)" | bc) &&\
goal account addpartkey -a $addr --roundFirstValid $start --roundLastValid $end --keyDilution $dilution

Error? Entered the wrong address?

If you see an error containing the words value too great for base, then you entered extra characters in the duration value.

Enter the number exactly without separators or suffixes like M, K, etc. Example: 2000000

This set of scripts will remember your address for future commands (until you log out).

If you entered the wrong address, you can reset it by running this command:

unset addr

Or by simply logging out and back in.

Then you can try again.

After entering your information, it will print Please stand by while generating keys. This might take a few minutes…

After a few minutes, you should see:

Participation key generation successful. Participation ID: CJOZKSLXZUNEPPOFLRU7JPISOPRVMBJASP2EIFP6CKIKJTAIEMNA
Generated with goal v3.17.0

Your node is almost ready to register online and start participating in consensus. One more step to go!

Check your participation status

Before and after performing key registration (online/offline) transactions, you may find it useful to check your account’s participation status with this command:

getaddress() {
  if [ "$addr" == "" ]; then echo -ne "\nNote: Completing this will remember your address until you log out. "; else echo -ne "\nNote: Using previously entered address. "; fi; echo -e "To forget the address, press Ctrl+C and enter the command:\n\tunset addr\n";
  count=0; while ! (echo "$addr" | grep -E "^[A-Z2-7]{58}$" > /dev/null); do
    if [ $count -gt 0 ]; then echo "Invalid address, please try again."; fi
    echo -ne "\nEnter your voi address: "; read addr;
    addr=$(echo "$addr" | sed 's/ *$//g'); count=$((count+1));
  done; echo "Using address: $addr"
}
getaddress &&\
goal account dump -a $addr | jq -r 'if (.onl == 1) then "You are online!" else "You are offline." end'

Error? Entered the wrong address?

This set of scripts will remember your address for future commands (until you log out).

If you entered the wrong address, you can reset it by running this command:

unset addr

Or by simply logging out and back in.

Then you can try again.

If you are online (participating in consensus) this should output You are online!. Otherwise, it will output You are offline..

Register to go online

Danger

Whenever you intend to take your node offline, make sure to register offline first (next section). Being registered to participate without a node running actively harms the network.

Note

You will need some $VOI to complete this step. If you do not have any, reach out on the Voi Discord. You can check your balance on the Explorer.

Check that you are not registered online using the command in the previous section. The output should be You are offline..

You can register your account as participating in the Voi consensus with the following command:

getaddress() {
  if [ "$addr" == "" ]; then echo -ne "\nNote: Completing this will remember your address until you log out. "; else echo -ne "\nNote: Using previously entered address. "; fi; echo -e "To forget the address, press Ctrl+C and enter the command:\n\tunset addr\n";
  count=0; while ! (echo "$addr" | grep -E "^[A-Z2-7]{58}$" > /dev/null); do
    if [ $count -gt 0 ]; then echo "Invalid address, please try again."; fi
    echo -ne "\nEnter your voi address: "; read addr;
    addr=$(echo "$addr" | sed 's/ *$//g'); count=$((count+1));
  done; echo "Using address: $addr"
}
getaddress &&\
goal account changeonlinestatus -a $addr -o=1 &&\
sleep 1 &&\
goal account dump -a $addr | jq -r 'if (.onl == 1) then "You are online!" else "You are offline." end'

You will see a prompt for your address (unless you entered it earlier) and your wallet password. After you enter it, you should see the following:

Please enter the password for wallet 'voi':
Transaction id for status change transaction: 5KYUOGQYKTVPN5RBFFKDNMYUIQZY5RK5VQIMEDZDE2FPIB32M3OA
Transaction 5KYUOGQYKTVPN5RBFFKDNMYUIQZY5RK5VQIMEDZDE2FPIB32M3OA still pending as of round 34820
Transaction 5KYUOGQYKTVPN5RBFFKDNMYUIQZY5RK5VQIMEDZDE2FPIB32M3OA still pending as of round 34821
Transaction 5KYUOGQYKTVPN5RBFFKDNMYUIQZY5RK5VQIMEDZDE2FPIB32M3OA committed in round 34822
You are online!

Register to go offline

If you need to stop your participation node, you must register your account as offline.

This can be done with the following:

1. Check that you are not registered online using the command in the relevant section. The output should be You are online!.
2. Send a transaction to mark your account as offline:

getaddress() {
  if [ "$addr" == "" ]; then echo -ne "\nNote: Completing this will remember your address until you log out. "; else echo -ne "\nNote: Using previously entered address. "; fi; echo -e "To forget the address, press Ctrl+C and enter the command:\n\tunset addr\n";
  count=0; while ! (echo "$addr" | grep -E "^[A-Z2-7]{58}$" > /dev/null); do
    if [ $count -gt 0 ]; then echo "Invalid address, please try again."; fi
    echo -ne "\nEnter your voi address: "; read addr;
    addr=$(echo "$addr" | sed 's/ *$//g'); count=$((count+1));
  done; echo "Using address: $addr"
}
getaddress &&\
goal account changeonlinestatus -a $addr -o=0 &&\
sleep 1 &&\
goal account dump -a $addr | jq -r 'if (.onl == 1) then "You are online!" else "You are offline." end'

You will see a prompt for your wallet password. After you enter it, you should see the following:

Please enter the password for wallet 'voi':
Transaction id for status change transaction: 5KYUOGQYKTVPN5RBFFKDNMYUIQZY5RK5VQIMEDZDE2FPIB32M3OA
Transaction 5KYUOGQYKTVPN5RBFFKDNMYUIQZY5RK5VQIMEDZDE2FPIB32M3OA still pending as of round 34820
Transaction 5KYUOGQYKTVPN5RBFFKDNMYUIQZY5RK5VQIMEDZDE2FPIB32M3OA still pending as of round 34821
Transaction 5KYUOGQYKTVPN5RBFFKDNMYUIQZY5RK5VQIMEDZDE2FPIB32M3OA committed in round 34822
You are offline.

Renew your participation keys

Your participation keys will expire at some point. The default values above (2 million round validity) currently correspond to 77 days. This section explains how to renew your participation keys.

You can renew your expired participation key with this command:

getaddress() {
  if [ "$addr" == "" ]; then echo -ne "\nNote: Completing this will remember your address until you log out. "; else echo -ne "\nNote: Using previously entered address. "; fi; echo -e "To forget the address, press Ctrl+C and enter the command:\n\tunset addr\n";
  count=0; while ! (echo "$addr" | grep -E "^[A-Z2-7]{58}$" > /dev/null); do
    if [ $count -gt 0 ]; then echo "Invalid address, please try again."; fi
    echo -ne "\nEnter your voi address: "; read addr;
    addr=$(echo "$addr" | sed 's/ *$//g'); count=$((count+1));
  done; echo "Using address: $addr"
}
getaddress &&\
echo -ne "\nEnter duration in rounds [press ENTER to accept default)]: " && read duration &&\
start=$(goal node status | grep "Last committed block:" | cut -d\  -f4) &&\
duration=${duration:-2000000} &&\
end=$((start + duration)) &&\
dilution=$(echo "sqrt($end - $start)" | bc) &&\
goal account renewpartkey -a $addr --roundLastValid $end --keyDilution $dilution

It will:

• Prompt you for your address (unless you have entered it earlier)
• Prompt you for your desired participation key duration (just press enter to accept default - 2M / 77 days)
• It will generate the keys (which may take a few minutes)
• It will ask you for your wallet password, and
• Submit the online transaction.

Possible Errors

• Account already has a participation key valid at least until roundLastValid

This will happen if you try to renew your current participation key with one that expires sooner, e.g. i your current participation key expires in 1 million rounds, and your renewal is attempting to last until 500K rounds.

Select a larger duration value and this error should go away.

• roundLastValid needs to be well after the current round

This happens if your duration is too short.

Select a larger duration value and this error should go away.

Expected output: (your values will differ)

Using address: WEAKNODEZXOBMGNQ56UIBFSGYHJLFPBTGQ7LJJYQFFYCZTDZ4AMRUYYFLU

Enter duration in rounds [press ENTER to accept default)]: 10000
Please stand by while generating keys. This might take a few minutes...
Participation key generation successful
Please enter the password for wallet 'voi':
Transaction id for status change transaction: TXDDH4VLD2N57Y4TAN4BSD5XUCYRUNIEBC6EL2ZZQHGTJSYGE25Q
Transaction TXDDH4VLD2N57Y4TAN4BSD5XUCYRUNIEBC6EL2ZZQHGTJSYGE25Q still pending as of round 482881
Transaction TXDDH4VLD2N57Y4TAN4BSD5XUCYRUNIEBC6EL2ZZQHGTJSYGE25Q still pending as of round 482882
Transaction TXDDH4VLD2N57Y4TAN4BSD5XUCYRUNIEBC6EL2ZZQHGTJSYGE25Q committed in round 482883
Participation key installed successfully, Participation ID: JX5GJ3ZYTJMXINMIOUNYKI6S37RPQ3JCQQR5XZ47QBPGWZPWWC5A

Generated with goal v3.18.0

You should now be online and participating in consensus! You can check this with the status command in the “Check your participation status” section.

Monitoring

Community member Boeieruurd has set up a monitoring interface here where you can see how your node is performing.

It may take a while to have your participating address listed there depending on your Voi balance.

Scores over 9 are very good. Scores under 5 are considered “failing”.