Beginner’s guide to setting up and operating a masternode

In a previous article, I discussed three options for earning passive income in the crypto space, one of which was the running of a masternode.

When I first got into crypto, running a masternode seemed like something beyond my level of expertise. What I eventually discovered, though, was that the problem wasn’t my level of expertise; instead, it was knowledge assumptions made by tutorial authors, and the glossing over of important concepts and details.

In this article, I’m going to explain the basic concepts, and walk the reader through the detailed setup of a masternode, such that he or she will hopefully be able to do the same with minimal assistance.

In short, this is the article I wish I’d had, when getting started!

Fundamental concepts

A masternode provides services to its blockchain network. For example, PIVX masternodes facilitate transactions that are private. Operators of masternodes are required to stake, or lock-up, a specific number of coins. As compensation, masternode operators receive periodic rewards.

Since a masternode is an operational component, and therefore needs to be available at all times, it’s usually best to run a masternode on a virtual private server, or “VPS”.

Since storing your coins on an internet-connected server wouldn’t be a good idea, masternoding allows you to store your locked-up coins offline on your local machine, in the project’s wallet.

Overview of the process

Following is a high-level overview of the procedure for setting up a masternode:

  1. Setup a VPS — Create a VPS, and install the blockchain project’s node software.
  2. Setup a local wallet — Download and install the project’s wallet on your local computer.
  3. Send some coins to yourself — Transfer the project’s minimum required coins into the local wallet. In the case of PIVX, that’s 10,000 coins. Within the local wallet, create a new receive address, and send the required number of coins to that address. By sending precisely this number of coins to a new address in the local wallet, it will recognize the availability of those coins for masternoding.
  4. Generate a private key — Within the local wallet, generate a masternode private key.
  5. Tell the local wallet about the server — Add your masternode private key, along with some other data, to your local masternode configuration file.
  6. Tell the server about the local wallet — Add some information, including your masternode private key, to the server’s configuration file.
  7. Restart everything — Restart the server software and local wallet, and enable the masternode.

Conceptually, that’s it! We’ll now walk through the detailed process of setting up a PIVX masternode. Once you’ve done this for one project, it’s almost trivial to do it for any other.

Before moving on, here’s a couple additional points to mention:

  • While masternoding, your staked coins will be locked up in your local wallet, unavailable for spending.
  • If your project supports staking, like PIVX does, any surplus coins in your local wallet can still be used for staking. (That would require your local wallet to be permanently online, however.)
  • You can support multiple masternodes with a single local wallet, by following the same procedure outlined here, but on a new receive address, and a new VPS.

Setup a VPS

To run a masternode, you need a VPS with at least 1GB of memory, which means you can select the $5/month option at a provider like DigitalOcean.

Two important points when setting up your server:

  1. Be sure to choose Ubuntu as the OS, so we can connect it to ServerPilot.
  2. Be sure to include your SSH key in the process of creating the server, so you can later login as root without a password. (For my masternodes, I just use the root user.)
  3. Be sure to enable automatic backups. This adds about 20% to the server cost, but is worth it.

Connect the VPS to ServerPilot

ServerPilot is a great service, which connects to all your VPSs, and maintains them with security updates and patches for free, allowing people like me, with little system administration skills, to operate servers. (Beyond security updates, you can use ServerPilot to setup and mangage WordPress and PHP sites, and the paid version gets you SSL, graphs and other features.)

Although ServerPilot promotes their integration with DigitalOcean, they actually can manage any Ubuntu server, such that if you choose another VPS provider, as long as you install Ubuntu, you can have ServerPilot manage it.

When connecting a new server at ServerPilot, you’ll see the following screen. If you added your SSH key to your DigitalOcean server, then by default root password login will be disabled, so you’ll need to check that box.

Submitting the form, you’ll then see a screen containing some unix commands:

Copy the complete contents of the unix commands to your local computer’s clipboard, and then paste them into your VPS, after logging in as root:

ssh [email protected]<vps_ip_address>

After pasting in your ServerPilot commands, you’ll soon see the ServerPilot website screen come to life with an indication that your server has successfully phoned home, and you’ll watch as ServerPilot completes its setup.

BTW, if you decide to use ServerPilot, and like this article, consider signing up with my referral link, and I’ll get a small credit on my account there.

Install a local SFTP client

For local editing of the remove VPS files, we’ll want to use a local SFTP client. On my Mac, I use Transmit. Be sure to create and test a connection to your VPS, logging in as root.

Install and setup the local wallet

Download and install your project’s local wallet software, which, as a general curiosity, is usually based on the “Qt” framework. Launch it and do the following:

  • Allow it to fully synchronize with the network.

  • Encrypt your wallet by going to the menu Settings → Encrypt Wallet

  • In the wallet options area of the settings, enable the “Show Masternode Tab” and “Coin Control”:

  • Be sure to backup your wallet file with the menu File → Backup Wallet.... Remember that most Qt wallets are not hierarchically deterministic, so you’ll need to create a new backup whenever you create a new receive address.

  • Finally, be sure that your wallet has, at least, slightly more than the minimum required coins for your masternode, e.g. 10,001 for PIVX (which requires 10,000).

Setup the masternode

Now we get to the fun part! I’m going to walk you through the process of setting up a PIVX masternode. Although the terminology may slightly differ in other projects, the approach should be nearly identical.

Step 1: Generate a new receive address

In the local wallet, enter the “Receive” tab and create a new receive address by entering any label you like, and clicking the “Request Payment” button.

On the next screen, click the “Copy Address” button, to copy your new address to your clipboard.

Step 2: Send coins to yourself

In the local wallet, enter the “Send” tab, and paste your receive address into the “Pay to” field. If you copied and pasted it correctly, the label you previously created will appear in the label field.

Step 3: Generate your private key, transaction hash and index

In this step, you’re going to generate three pieces of data you’ll need related to your new masternode. For all of these, you’ll need to be in the local wallet’s “Debug Console” which you can get to from the menu, Tools → Debug Console

First, generate your masternode private key, with this command:

masternode genkey

…after which you should see a long string appear, which is your private key:

Note down the private key, as you’ll need it later.

Next, generate the transaction hash and index that serve as proof of the transfer of coins you made to yourself:

masternode outputs

You’ll then see something like this:

Note down the transaction hash and the index, as you’ll need them in the next step.

Step 4: Update your local masternode configuration file

We’re now going to enter some information into our local masternode configuration file, that will allow our wallet and the server software to recognize each other.

To open the masternode configuration file for editing, access the menu Tools → Open Masternode Configuration File. In that file, you’ll want to add a single line (for each masternode you run), in the following format, with all fields separated by a space:

<mn_name> <vps_ip>:<port> <private_key> <trans_hash> <index>

Where:

  • mn_name — is any name you want.
  • vps_ip — is the IP address of your VPS.
  • port — is the port on which your masternode will communicate with others. This will be project specific; for PIVX it’s 51472.
  • private_key — is the masternode private key you generated earlier.
  • trans_hash — is the transaction hash you generated earlier.
  • index — is the transaction index you generated earlier.

For PIVX, my masternode configuration file might have a line like this:

mn1 123.456.789.012:51472 Lkj23lkj438s9d78sdf879sd0980fsdf0s98sad9a87dadsa9ds Dfg98d7f9d7f9g79d7gd97gdfs09d8f0s8df6d876sd87fs8s8df8df8g0d8s08d 0

Before moving on to the next step, be sure to also do the following:

  • Quit and restart your local wallet.
  • Unlock your local wallet with the menu item Settings → Unlock Wallet...

Step 5: Install the project node software on your VPS

We’re now going to download the project’s node software to our VPS. After logging in as root, make sure you’re in your home directory:

cd ~

Now we need to download the software. You’ll want to find the URL to the x86_64 linux version, for the latest release of the project’s software. You can find that by visiting the project’s GitHub repository, and navigating into the “Releases” area.

Once you have the URL, use the unix wget utility to download it. The command will look something like this:

wget https://github.com/project/releases/download/project-x86_64-linux-gnu.tar.gz

When the download finishes, unpack it with a command like this:

tar -zxvf project-x86_64-linux-gnu.tar.gz

Step 6: Understanding the project’s software

Before moving on, let’s quickly overview some relevant bits and pieces of what you just downloaded. Once you’ve unpacked and run your project’s node software—and don’t worry, I know we haven’t run it yet!—we’ll be working with the following directories, utilities and files:

  • Executables directory — This is where the project’s application software resides. For the current version of PIVX, it’s:

~/pivx-3.0.6/bin/

  • Server daemon — Located in the executables directory, this is the actual server application, and almost always end in ‘d’, since it’s known as a daemon. For PIVX, it’s:

pivxd

  • Command-line interface — We’ll use this application to interact with the daemon, e.g. telling it to shut down, or asking for its status:

pivx-cli

  • Data directory — This is where the software’s configuration files and local data are stored. For PIVX, it’s:

~/.pivx/

  • Project configuration file — Located in the data directory, this is the file that contains the configuration for the application software. For PIVX, it’s:

pivx.conf

There are many other files in the data directory, but for masternoding according to this procedure, we won’t be interacting with them.

Step 7: Configuring the server software

We’ll now configure the server software.

Since we haven’t yet run the software, we’ll start it, so that it will create its data directory:

~/pivx-3.0.6/bin/pivxd

This should fail, since the data directory wasn’t present, and therefore no configuration file would have been found. If it doesn’t, you can quit the server software with ctrl d

We’ll now use our local SFTP clientTransmit, in my case) to connect to the server, and open the project configuration file for editing:

~/.pivx/pivx.conf

What goes in the configuration file might vary slightly from project to project, but here’s the PIVX contents (with some placeholders):

rpcuser=<random_string>
rpcpassword=<longer_random_string>
rpcallowip=127.0.0.1
listen=0
server=1
daemon=1
logtimestamps=1
maxconnections=256
masternode=1
externalip=<vps_ip_address>
bind=<vps_ip_address>
masternodeaddr=<vps_ip_address>:<port>
masternodeprivkey=<masternode_private_key>

Here’s what you need to know:

  • rpcuser — This can be any random string, e.g. pivxmasternode
  • rpcpassword — This can be any random string, e.g. ju83FRT98Iuh64
  • masternodeaddr — Your VPS IP address is followed (after a colon) with your project’s port. This is the port on which your masternode will communicate with other members of the network.
  • masternodeprivkey — This is the masternode private key you generated earlier. It allows authentication between your local wallet and your masternode software.

Once you’ve finished editing your configuration file, save and close it.

Step 8: Start your masternode

We’ll now start the masternode on both the VPS, as well as our local wallet.

  • On the VPS, we start the daemon software:

~/pivx-3.0.6/bin/pivxd

  • In the local wallet, in the Masternodes tab, right-click on your masternode entry, and choose Start Alias.

Step 9: Check the masternode status

After step 8, you should allow some time, perhaps 20 minutes or so, for everything to sync and settle, after which you can check the status of things both on the server and the local wallet.

On the server, we’ll interact with the command-line utility:

~/pivx-3.0.6/bin/pivx-cli masternode status

If things are OK, we’ll see Masternode successfully started:

In the local wallet, in the Masternodes tab, we should see our masternode with a status of Enabled:

If everything looks good, congratulations, you’re now running a masternode!

  • You can now close your local wallet, as it doesn’t need to remain open.
  • Depending on the project, you should soon start to see rewards flowing into your local wallet. (For PIVX, it can take four or five days.)

Miscellaneous topics

Before concluding the article, here’s a couple of miscellaneous topics you should be aware of.

Remember, your coins are locked

If you click the “Coin Control” button in the “Send” tab of your local wallet, you’ll see that your masternode coins are locked, and will remain that way while your masternode is operational.

Unlocking your coins

If you want access to your coins again, you’ll need to do the following:

  • Stop the masternode software on the VPS:

~/pivx-3.0.6/bin/pivx-cli stop

  • In your local wallet, edit your masternode configuration file, removing the line you entered in step 4.
  • Restart your local wallet, at which point your coins will be available for spending.

Monitoring your masternode

I run several masternodes, and have created a Keyboard Maestro macro on my Mac that runs each 30 minutes, checking that my masternodes report correct status, and checking that they are running on the correct chain. (Chain checking is more relevant to new projects, that don’t have strong networks, and frequently fork.)

If you happen to run Keyboard Maestro, you can download my macros here. You’ll need to edit the server variable with the IP of your VPS.

If you don’t run Keyboard Maestro, and want to setup something yourself, here is the basic logic:

  • Query the server’s masternode status, and grep for the success string.

ssh [email protected]<server> "~/pivx-3.0.6/bin/pivx-cli masternode status"

  • Grab the current HTML from the PIVX block explorer:

curl http://www.presstab.pw/phpexplorer/PIVX/block.php

  • Grep to extract the hash of the latest block, using this regex:

Block\ Height:</th><td>([^<]+)<([^B]+)Block\ Hash:</th><td>([^<]+)

The latest hash will be found in \1 and the hash of the latest block will be found in \3.

  • Grab the hash of the latest block from my masternode.

ssh [email protected]<server> "~/pivx-3.0.6/bin/pivx-cli getblockhash <latest_block>"

  • Compare the two hashes. If they are different, then our masternode is off-chain, and needs to be re-synchronized, which involves stopping the server, deleting some files, and restarting. (My Keyboard Maestro macro handles that task as well.)

To re-sync, between stopping and starting the node software, here’s the command for deleting the files. (Thanks to moocowmoo of the Dash project for dramatically shortening the command I previously used):

ssh [email protected]<server> "cd ~/.pivx ; mv wallet{.dat,.k} ; rm -rf *.dat *.log blocks chainstate ; mv wallet{.k,.dat} ;"

Finally, if you ever need to confirm the version you’re running:

~/pivx-3.0.6/bin/pivx-cli --version

Troubleshooting

If this is your first time setting up a masternode, you’ll probably run into some hiccups. (Hopefully less than I did, with the available of this article!). If you need help, here’s two recommendations:

  • You can feel free to contact me, either by posting a comment on this article (which might help others), or emailing me through the contact form.
  • Most projects have a Discord online chat, with a #support channel in which you can ask questions. The PIVX project have paid personnel working in theirs, which have proven tremendously helpful in my experience.

Conclusion

As you’ll have noticed from my previous articles, I’m transitioning from the world of traditional investing, to the world of crypto investing, and in the process am doing a lot of hands-on learning to make sure I understand the ins and outs of this space.

Through this blog, and for the benefit of new entrants to this space, I hope to write articles that simplify some of the complex topics that I’ve struggled with, including details that many others have glossed over or left out entirely.

I hope you’ve enjoyed this one about operating a masternode, and if you have any questions or feedback, don’t hesitate to leave a comment below or email me through the contact form.