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.

9 thoughts on “Beginner’s guide to setting up and operating a masternode”

  1. Hi Gabriel,
    thanks a lot for the nice guide. I am already having 2 MN and during the reading of your guide I was found one difference.
    During setuping one of my MNs I was generating masternode private key from the VPS and not from the local wallet and everything is working correctly. In your guide you are saying that this should be done on the local wallet so not on the VPS.
    And now my question is if it depends on where you generate the master key or not. Can you please explain it to me little bit? Thanks a lot for your time.
    BR
    Marian

    1. Hi Marian,

      No, in theory it shouldn’t matter if you generate the private key in the local wallet or the VPS. I had difficulties getting a MN setup once, and had generated the key on the server. Starting from scratch, I generated the key in the local wallet, and everything worked, but it’s perfectly possible (and likely) the change of key generation wasn’t the issue. Glad you enjoyed the article!

  2. Very clear explanation but I have a silly question:
    In “Step 1: Generate a new receive address” – in the local wallet (I suppose in my desktop), I generate a new receive address.

    Then, in “Step 2: Send coins to yourself” – I paste the address generate from step one in the “Pay To” box of the “same” local wallet.
    It seems to me that the receiving address generated from the same wallet is put into the “pay to” address of the same wallet?? Am I missing something? What is the purpose for this? To my understanding, the crypto is transferred from one wallet to another wallet! Is it special requirement for setting up Masternode? Thank you.

    1. Hi Cha, each time funds are received at an address they are received on a different “input”. So a single address can have many inputs. A masternode requires that its collateral is on a single input, and that’s the reason for the self-transaction, to create a single input with precisely the collateral amount.

      1. Still confused. So in practice, can I understand the setup of MN as follows:
        1. Before “step 1” of your guide above, I first send the 10,000 PIVX to my local wallet with address different from the MN address (which create later) in “Step 1”. Say I call it as pre-MN address.

        2. After confirming my pre-MN address receiving my 10,000 PIVX. Then I continue to step 1 (i.e. setup my_mn_address and send the 10,000 PIVX from pre-MN address to my_mn_address. Both pre-MN address and my_mn_address are generated from the SAME local wallet?

        1. Hi Cha,

          Your local wallet needs to have 10k PIVX on a single “input”, associated with a single transaction. If you haven’t done that, the local wallet won’t return anything when you issue the “masternode genkey” command in a later step.

          It doesn’t matter how you get 10k PIVX on a single input. If you have 10k in your local wallet, you can do a self-send transaction as I described. If your local wallet has no PIVX in it (or less than 10k PIVX) in it, you could send in 10k from another wallet, on your MN address, as long as it’s precisely 10K, and sent in a single transaction.

          Does that make sense? At the end of the day, your local needs to see 10k from a single transaction, whether that’s sent internally or arriving from somewhere externally.

  3. Hi Gabriel, great article with great formatting and easy to read. PIVX is expensive though.

    The altcoin market pricing has dropped so significantly that doing multiple masternodes can be very affordable. For example, my Digiwage freelance platform altcoin masternode costs $38 (12000 coins).

    Here is my question. But first, I am able to get 20 Digiwage masternodes running at the same time on the $5 per month Vultr server (1 GIG RAM, 25 GIG HD) - this maxes out the 4 GIG swap RAM. But, I use their instructions for IPv6, and have to make an individual user for each master node (and when you get 20, that’s too much work when I have to reboot because I have 20 logins to stop the masternoding then 20 logins to start them up). 

    Can you show us how to do a multi masternode Vultr setup using IPv6 that is simpler? Like root login only?

Leave a Reply to Cha Icy Cancel reply

Your email address will not be published. Required fields are marked *