Instructions to Launch a Node in DOS Network

DOS Network was successfully launched on ethereum mainnet in July 2020. Since then, we have seen tremendous support from the DOS community, with many users discussing and inquiring about how to become a node runner. Today, the DOS Network team would like to provide the official guide on how to do so.

Being a node runner not only helps our oracle service network become more decentralized and improve our quality of service, but it also earns you more rewards compared to normal delegators. However, it also comes with additional requirements and risks. Before setting up your own node in DOS Network, make sure you go through the detailed guide below.

What Do Nodes and Groups Do in DOS Network

Nodes are the backbone of DOS Network and are responsible for serving data feeds and random oracle requests. Nodes will be put into groups and registered in the system contract. For each oracle request, a working group will be randomly selected to fulfill it. Each working group also has a maturity period, after which the group expires and dissolves into a list of pending nodes, and then to be selected to form new working groups again. For more technical details, please refer to the DOS Network technical whitepaper.

Eligibility to Launch a New Node

Currently, one needs to bond at least 800,000 DOS tokens in order to start a node. This high threshold is set during the network bootstrapping stage in order to encourage mid-to-long term stakeholders to get involved and grow with the project, in addition to helping to provide stable services.

We are well aware that decentralization is extremely important, so we have plans to lower the threshold for future node runners, including but not limited to the following:

• Gathering constructive feedback from the community and gradually lowering this threshold, potentially through voting mechanisms
• Distributing DropBurn tokens to early and future node runners/developers for them to reduce (up to 30%) the amount of DOS tokens needed to start a node
• Onboarding professional node and staking service providers

With that said, let’s talk about how to create your own node!

Creating Your Node

1. Choose your cloud server provider and operating system

There’s no slashing when a node is down, yet, but it stops generating staking rewards for both the node runner and tokens delegated to this node. Also, this offline status will be reflected on the dashboard, so delegators can choose to redelegate to another node or unbond.

In order to ensure near 100% uptime and quality of services provided, it is recommended to run the node on a Linux cloud server. There are a couple of cloud servers/VPS providers to choose from, and we have listed several below, plus the minimum system requirements to run a node on each platform:

• AWS Lightsail — Linux virtual server (1 cpu, 1GB memory, 40GB ssd, 2TB bandwidth)
• Google Cloud Platform — Compute Engine General purpose (N2)
• Vultr — Cloud Compute (1 cpu, 1GB memory, 25GB ssd, 1TB bandwidth)
• Digital Ocean — Droplet (1 cpu, 25GB ssd, 1TB bandwidth)
• Linode — Shared virtual Instances (1 cpu, 1GB memory, 25GB ssd, 1TB bandwidth)

⚠️ In the sections below, we will be using AWS Lightsail as an example to demonstrate how to start a node.

2. Network and port settings

⚠️ It is recommended that you reserve a static IPv4 address for your node from your cloud server provider, and many of them do not charge extra money for this (such as AWS Lightsail, Vultr, etc.)

Go to https://lightsail.aws.amazon.com/ls/webapp/home/networking, and click “Create Static IP”:

Then, attach it to your newly created node:

After that, select the newly created node and click ‘Network’. First, remove the “TCP 80” port, then you need to configure 3 additional port rules, as indicated below:

3. Install docker and node image:

Run the following commands:

$ sudo dpkg --configure -a
$ sudo apt-get update
$ sudo apt-get upgrade
$ sudo apt install docker.io
$ sudo usermod -aG docker $USER

The last command is to run docker as a non-privileged (non-root) user, and you need to logout then login again to for it to take effect.

Install the DOS node docker image:

$ docker pull dosnetwork/dosnode:v1.0.4-m

4. Setup the config and node runtime environment

Run the following commands:

$ mkdir ~/vault
$ wget https://raw.githubusercontent.com/DOSNetwork/core/master/config.json -O config.json

Open config.json. There are 2 fields that need to be replaced with your own settings:

“NodeIP”: this should be filled in with static IP you got from your cloud server provider.

“ChainNodePool”:

• If you have your own Ethereum node (geth, parity) running locally or remotely, you can simply put the Ethereum node RPC endpoint here
• Otherwise, for most other developers, you can simply use the Ethereum API services provided by Infura: register an account and replace with your own infura APIKEY (or Project ID as Infura calls it) there. The free plan suffices what the node needs

5. Create the node wallet keystore file

A node wallet is required to send necessary transactions to the Ethereum blockchain, but since the node wallet is connected to the internet (think of it like a ‘hot wallet’), it is recommended to create a new one with password protection, and only send necessary funds (gas fees) to it. (Node wallet and the wallet you hold DOS tokens with should be different ones for your own safety)

Create the keystore file using the node software by running the following:

$ docker run -it --mount type=bind,source=/home/$USER/vault,target=/vault dosnetwork/dosnode:v1.0.4-m /dosclient wallet create

It will prompt you for a password, which is used to encrypt the node wallet keystore, and you should remember this password as it will be used to decrypt the node wallet when running the node. Also, remember to backup your node wallet keystore file in a secure location.

⚠️ Note 1: The node wallet is nothing special but a standard Ethereum wallet in keystore format. You can always use other tools (e.g. https://www.myetherwallet.com/create-wallet) to create the keystore file and then upload to the server and put it under the `~/vault` directory. MEW (https://www.myetherwallet.com/access-my-wallet) also supports to operate keystore formatted wallet directly, like one operates with MetaMask.

⚠️ Note 2: For more advanced users, you can generate keystore file from a private key; you can also dump private key out of the generated keystore file and then import private key into MetaMask. Please see https://github.com/ethereumjs/keythereum for more details.

⚠️ Note 3: After node wallet creation, you should send some Ether to it. According to current estimation 1 ether is enough to pay for gas fees for approximately 3 months on the Ethereum mainnet.

6. Bond enough DOS tokens

Go to https://dashboard.dos.network/staking, and click the ‘Create a Node’ button.

⚠️ Note that you should be using the wallet holding DOS tokens (not the node wallet) to send the bonding transaction, and the bonded tokens will be sent to the Staking smart contract.

You will see your node appearing in the dashboard but with “inactive” status. This is expected, because you haven’t started running the node and get it registered in the network yet.

7. Start and monitor node status

Before starting the node, please make sure you have sent some Ether to the node wallet as gas fees as described above. On mainnet, according to current estimates, 1 Ether is enough to pay for gas fees for 3 months. Please send at least 0.1 Ether to get node registered, as current Ethereum mainnet is congested and node registration consumes extra gas. Once Then type in 3 commands below:

$ export PASSWORD="xxx"   (replace xxx with password of your own keystore file, and of course remember the password.)
$ export DOSTAG="v1.0.4-m"
$ docker run -it -d -p 7946:7946 -p 8080:8080 -p 9501:9501 \
--mount type=bind,source=/home/"$USER"/,target=/config \
--mount type=bind,source=/home/"$USER"/vault,target=/vault \
--hostname dos \
--name dosclient \
--env CONFIGPATH=config \
--env PASSPHRASE="$PASSWORD" \
--env APPSESSION="$DOSTAG-mainnet" \
--env LOG_LEVEL=debug \
dosnetwork/dosnode:"$DOSTAG" /dosclient start

Logs files are kept in ~/vault, and you can quickly check logs using the command:

$ tail -n 1000 -f $(ls -l ~/vault/doslog.txt | cut -d '>' -f2)

Once you see some ASCII art below, it means that you have successfully launched your own node on DOS Network, and your node has started serving the network, as well as earning staking rewards! Congrats!

You can double check your node’s online status by going to https://dashboard.dos.network/staking. Also, if you check the node wallet activity on Etherscan, you will see that at least one transaction called ‘registerNewNode()’ has been sent to the system smart contract.

You are now done with node creation. You can leave it here, but if you would like to learn more, please continue reading.

8. Go down the rabbit hole (Optional)

Besides reading from logs, node status can also be checked by: `$ curl localhost:8080`, and you’ll see more info exposed below:

It is okay if your node remains in the “PendingNode” status, or you simply see “INFO — Node heartbeat …” in log files as once registered the node is still in stage 0 (pending and waiting for group key generation / registration stage.)

According to how nodes and groups work, newly registered nodes will be kept in pending node mode, until: 1. at least 3 (groupSize) new nodes get registered, and 2. at least 2 working groups have expired. Then pending nodes and dissolved working group nodes will be randomly mixed and formed into new working groups. This is called stage 1, and depending on system level configuration and stability considerations (e.g. number of upcoming nodes and group maturity period), it may take 10 ~ 14 days to transit from stage 0 to stage 1. (With more nodes registered and network expanded, fees will be amortized and this period gets shortened)

When stage 0 finishes and at the right beginning of stage 1, a new working group is formed and registered, you’ll see transactions called ‘registerGroupPubKey()’ like below:

* To ensure nodes running smoothly in stage 1 without downtime or weird issues, it’s recommended to put enough gas fees in the node wallet. 1 Eth should be enough to cover gas costs’ of 2~3 months according to current Ethereum network condition and our estimation.

Once your node has been formed into working group and selected to work, you would see more detailed working logs like below:

9. Unregister node and unbond stakes:

Before unregistering node and unbonding all stakes you need to first stop the node software, otherwise your node would always send reverted transactions until gas fees in your node wallet are depleted.

$ docker stop $(docker ps -a -q)
$ docker rm $(docker ps -a -q)

Before destroying the server, also remember to double check if you have backed up the node wallet keystore file or transferred out all the funds inside.

Then go to dashboard and select your node to unregister. Note that unregister would automatically unbond all your tokens and you can withdraw all of them after 7 days.

10. Congratulations! 🎉🎉🎉

Congratulations on all your effort and thanks for the interest of being a node runner, we’re proud of you!

You can always find us in Node Runner channel for any node questions or oracle usage inquiries. We’re also listening to the feedback, this tutorial and the node software monitoring module will keep being updated.

[Appendix] Upgrade node software to latest version (v1.0.4):

Please see https://github.com/DOSNetwork/core/blob/master/upgrade.md for detailed writeup.