1️⃣Run a Validator

Instructions on how to stake/unstake $DESO and run a validator

Video Walkthroughs

Getting Started

Resources

Staking Your $DESO

Some info about staking with Revolution Proof of Stake:

  • 20% APY to start. The APY for staking your $DESO starts at 20% and adjusts depending on how much $DESO is staked on the network. You can always see an updated APY on the validators page on the block explorer (mainnet, testnet)

  • Revolution Proof of Stake makes a lot of improvements over state-of-the-art PoS systems, including Cosmos, Solana, and Ethereum. Some benefits of staking with Revolution are listed below:

    • No slashing. Revolution does not require slashing of stake. Instead, validators who are unresponsive are automatically “jailed” for a period of time, preventing them from harming consensus until they have resolved their issues. The only risk of staking to a bad validator is that you will miss out on rewards if they have downtime.

    • Quick unlocks. Unlocking one’s stake takes only two hours, compared to weeks to months with other protocols. And this amount will be decreased even further in the future.

    • Fully permissionless and decentralized. Revolution is permissionless and does not require a minimum amount of stake to become a validator. The idea was to reproduce the level of permission-lessness of Proof of Work systems, but in a Proof of Stake context.

  • Learn more about Revolution and its many other breakthroughs by reading the docs here.

Staking your $DESO:

  • For Testnet only:

    • Pick up some free testnet $DESO

      • Visit https://test.deso.org

      • Create an account

      • When creating an account you can enter your phone number to get 1 free testnet $DESO from the faucet

      • Note that testnet $DESO does not have any value outside of the test environment!

  • Now that you have $DESO, head to the block explorer

  • Login to the block explorer by hitting “Login” in the top-right and selecting the account that holds your $DESO

  • After logging in, select Validators > Stats from the top menu

    • Note the APY at the top. This amount will change depending on how many people are staking

  • Choose a validator to stake to and click on their username

    • Note that you can sort validators by their Commission percentage, the number of stakers, and their total staked

  • Once on the validator’s page, click “Stake” and fill in the amount you want to stake

  • That’s it!

Unstaking your $DESO

  • Go back to the main validator page on the block explorer

  • Make sure you are logged in with the account that originally staked the $DESO

  • Click “Unstake” on the /validators page

  • Select the amount of stake you want to remove

  • Hit “Update Stake”

  • After you unstake, your stake appears as a “Locked Stake Entry” and is locked for a 3 hour cooldown period. This prevents anyone from gaming the leader selection algorithm. You can see how much time is left before you can unlock by clicking “View Details.”

    • Note that other protocols require weeks or months of cooldown, but Revolution PoS only requires three hours, and we aim to decrease this even further over time.

  • After the cooldown period is over, you just hit “Unlock” on the locked stake entry to get your $DESO

Running a Node

A node on the DeSo network is any machine that has a full copy of the blockchain, and that other nodes can sync from. When you run a node, you start by syncing data from other nodes on the network until you have a full copy of the network’s “state.” Once you’re up-to-date, you stay online and get new blocks as they’re proposed. Note that you don’t need to participate in consensus in order to run a node. You just need to stay up to date by downloading all the new blocks as they’re proposed.

A validator is a node that participates in consensus. With Revolution, validators vote on each new block that is proposed and propose blocks when it’s their turn to be “leader.” Being a validator means that you take on the responsibility of validating blocks but it also means you can earn a commission from anyone who stakes to you.

Minimum Requirements

  • Mainnet

    • Minimum:

      • RAM: 32GB

      • CPU: 4 cores (less may be OK)

      • Disk: 200GB

      • Notes

        • If you are running the minimum configuration, you must use --sync-type=blocksync. This is because using --sync-type=hypersync or --sync-type=hypersync-archival will cause you to exceed your RAM requirements

    • Recommended:

      • RAM: 64GB - 256GB

        • 128GB will be the safest bet, and will allow you to run with --sync-type=hypersync and --sync-type=hypersync-archival, which will sync your node much faster. However, if you’re building a machine from scratch to be a validator, we’d recommend you make it upgrade-able to 256GB in case we decide to increase requirements in the future. We have a recommended build below that achieves this.

      • CPU: 8 cores (less may be OK)

      • Disk: 500GB (less may be OK)

      • Recommended build (premium):

  • Testnet

    • Minimum and recommended:

      • RAM: 32gb

      • CPU: 2 cores

      • Disk: 50gb

    • Notes

      • Testnet currently requires --sync-type=blocksync, but this should be fixed soon.

  • Validator Requirements

    • In order to be a validator, your node must have a static IP and, ideally, a human-readable domain attached to that IP. We walk through setting that up in the video tutorial.

Node Setup (Using Docker)

  • Get a machine. First, you need to provision a machine with the minimum requirements. We walk through that in the video tutorial.

    • We recommend you run your machine from your house for maximum decentralization (and fun!). But provisioning a node on AWS or Google Cloud works great too.

    • Whatever you do, we recommend you run Ubuntu to minimize issues, but note that many members of the core team run nodes on Mac OS.

    • We have not tested thoroughly on Windows, but it should work. And if you run into issues you can always run your node from an Ubuntu virtual machine on Windows, e.g. using VirtualBox.

  • Clone the run repo. The “run” repo here contains everything you need to get a node running with, a frontend interface attached. Some notes on using the run repo:

    • Start by cloning the run repo onto your node.

    • This branch has several docker-compose files. Let’s take a look at testnet.docker-compose.yml:

      • It sets up a service named backend. This is the service that will connect to the rest of the network and sync data from it. The backend service has two ports: a “protocol” port 18000, where other nodes connect to it, and an “API” port 18001, which exposes a bunch of convenience endpoints and powers the frontend.

      • It also sets up a service called “frontend” and “nginx” service. This allows you to visually manipulate your node.

  • Run your node! To run your node, all you have to do is type “make testnet” (if you have a permission error, use “sudo make testnet”). This will automatically run the testnet.docker-compose.yml and set up the backend+frontend+nginx services.

    • If you run into issues or you want to start “from scratch”, the Makefile also defines a command called “make testnet-wipe”, which will wipe everything your node has done and start over.

    • To run a mainnet node, simply run “make mainnet” instead of “make testnet”.

      • Note that this will leverage the mainnet.docker-compose.yml instead.

  • Access your node’s frontend. Once your docker-compose is running, you can access your node using its reference frontend at yournodesdomain.com:8080. To properly access your frontend, you need to visit this address and set a key-value in local storage that tells your frontend the address of your node’s API endpoint. The key is “lastLocalNodeV2” and the value should be "yournodesdomain.com:18001" if you ran make testnet and "yournodesdomain.com:17001" if you ran make mainnet. See screenshot below for an example from the video. Once you set this, you can access your node’s frontend at yournodesdomain.com:8080 and tweak it via the Admin panel. We will have improved docs on this soon!

Node Setup (From Source)

TODO: Make this more clear and show a video doing this on a new node from scratch.

  • Go through this tutorial and checkout all the repos listed

  • After that you should have *at least* the following repos locally:

    • core

    • backend

    • frontend

  • cd backend/scripts/nodes

  • For mainnet run ./n0. For testnet run ./n0_test

  • If you want, you can play with all the flags in those files to get different behavior.

If you’re interested in a walkthrough of the code, check out our Architecture Overview

Running a Validator

A validator on the DeSo network is responsible for voting on new blocks as they’re proposed, and for proposing valid blocks when it’s their turn to be leader. Validators can be staked to by anyone on the network, and they earn a commission on the rewards that accrue to all of the $DESO that is staked to them.

Below are the instructions for setting up a validator. We assume you’ve read through how to set up a node in the previous sections:

  • Testnet only:

    • First, pick up some free testnet $DESO

    • Visit https://test.deso.org

    • Create an account

    • When creating an account you can enter your phone number to get 1 free testnet $DESO from the faucet

    • Note that testnet $DESO does not have any value outside of the test environment!

  • Now that you have $DESO, head to the block explorer

  • Login to the block explorer by hitting “Login” in the top-right and selecting the account that holds your $DESO

  • After logging in, select Validators > Stats from the top menu

    • Note the APY at the top. This amount will change depending on how many people are staking

  • Register your validator. To register your validator, hit the “Run a Validator” button in the top right.

  • Registering your validator consists of broadcasting a transaction on-chain signed by your validator private key. The UI in the block explorer helps you form this transaction, but you can also do it permissionlessly with a script if you prefer. This tutorial will focus on using the UI to do it.

  • Getting all of the fields right. The registration transaction requires a bunch of fields shown on the “Run a Validator” page. We walk through each one and how to set it up below.

    • Add Domain.

      • Static IP (covered in the video tutorial). First, your validator must have a static IP address for your node and it should ideally have a domain associated with that IP address. AWS and Google Cloud make it very easy to have a static IP, but setting one up for your home is easy as well (and fun), although you will have to call your cable provider to do it.

      • Registering a domain (covered in the video tutorial). Once you have an IP address associated with your node, you can associate a domain with it simply by setting a single A record on your DNS settings just like you would for a normal website. See sirstakesalot.com for an example.

      • Default ports. By default, your testnet node will expose a protocol port on 18000 and an API port on 18001. For mainnet, the default ports are 17000 and 17001.

        • The protocol port is the one that matters for consensus, as it’s what nodes use to connect to you and send you blocks. The API port is mainly used to power a frontend that you can use to manage your node.

        • When you register your validator, you need to include the protocol port, and so your registration string will look like “example.com:18000” for testnet or “example.com:17000” for mainnet.

        • You can also change the ports to whatever you want, just as long as the string in your registration transaction matches what your node is actually doing.

      • Run your node and make sure it’s exposed to the outside world. Once you have your static IP and domain, you can use the validator registration UI to check your node’s connection. You can also use this curl command, but replace your domain and port with what your node is running on (for mainnet, node you must use port 17001):

    • Setting up your voting public key. Once your validator is reachable by the outside world, you need to set up your voting public key. This is the key that you’ll use to sign consensus messages like votes or block proposals. Below we explain how to generate this keypair.

      • First, generate a seed. Your validator keypair can be generated from an ordinary 12-word seed phrase, just like the one you get on any DeSo app. You can either use one that’s associated with an existing profile or a brand new one that you designate just for PoS messages.

      • Next, get the public key and authorization bytes. Once you have a seed phrase you like, you need to use this validator key generator script to generate a voting public key and a voting authorization, which you will enter into the UI.

        • Why is this necessary? The reason is that your validator keys are BLS keys, while your standard DeSo keys are ECDSA private keys. BLS keys allow for “signature aggregation,” which is needed by Revolution PoS, and hence even if you use the same seed for both your DeSo account and your validator, you will need to use this script to generate a voting public key that is distinct from your DeSo public key.

        • The other benefit of having a script to generate the pubkey+authorization is that it allows for totally offline generation of validator pubkey and authorization, which is needed by custodians and exchanges that want to stake.

      • Set POS_VALIDATOR_SEED in your config. Note that there is one missing step in the video, which is you need to set your POS_VALIDATOR_SEED in the testnet.docker-compose.yml or mainnet.docker-compose.yml file to be equal to the seed you used with the validator key generator. This is how your validator becomes capable of signing blocks with its bls keypair.

    • Commission. This is what percentage of the staking rewards you get to keep. A lower commission will attract more people to stake with you.

    • Delegated stake. If you disable this, nobody will be able to stake to your validator except you. This is useful if you just want to run a validator to manage your own stake.

    • Announcements and Discussion Telegrams. Please join these telegrams to get your passwords! You can register without joining these, but then you may miss out on critical updates.

  • Time to register! Once you’ve filled in all the fields, hit the “Register Validator” button. This will construct and submit a transaction that links your voting public key with your node’s public domain+port and your DeSo profile (the one that you’re logged-in with). Linking all of these together on-chain makes it so that 1. other nodes can connect to your validator node and 2. people can stake to your validator node. Exciting!

  • Keeping your validator up. If your validator is down for a 12-hour period, it will be “jailed.” You will see this in the validator UI. To unjail your validator, you will need to go back to the validator registration page after you’ve fixed your node and hit “Unjail Validator.” Note that there will be a cooldown of a few hours before your validator is able to vote in consensus again.

Once your validator is registered, it should appear immediately on the validators page. You can then stake to it following the prior instructions.

PreviousNode: FAQNextContact US

Last updated