Setting up a Stacks Node

Supporting STX and BTC together.

Table of Contents

Setting up a Stacks Node

Note: this documentation is an alternate version of and may vary slightly from the official Stacks documentation.

Stacks Node System Requirements

The official Stacks Documentation states:

Running a node has no specialized hardware requirements. People were successful at running a node on Raspberry Pis, for instance. Minimum requirements are moving targets due to the nature of the project and some factors should be considered:

  • compiling node sources locally requires computing and storage resources
  • as the chain grows, the on-disk state will grow over time

We suggest hardware based on a general-purpose specification, similarly to GCP E2 machine standard 2 or AWS EC2 t3.large standard:

  • 2 vCPUs
  • 8 GB memory
  • ~50-GB disk (preferably SSDs)

It is also recommended to run the node with a publicly routable IP, that way other peers in the network will be able to connect to it.

Stacks Documentation: Running a mainnet node

Note: With this in mind, I can report personal success with a virtual machine allocated 1 vCPU, 2gb Memory, and 500gb allocated disk space that grows with the data (currently occupying 54gb on disk). I did have to change the swap size to 8gb in order to be able to import Stacks 1.0 data and avoid OOM errors.

Downloading the Release

Stacks mining is currently available using the stacks-node executable from the stacks-blockchain repo.

There are two ways to obtain the software.

  1. Download the latest release from GitHub , which contains a ready-to-run program for your operating system.
  2. Build the code directly from GitHub, which requires more prerequisites but gives access to the latest fixes.

Option 1 is the fastest way to get things running, and preferable if you do not have experience with compiling software.

Option 2 is more advanced, requiring Rust, Git, and the correct build tools for your OS.

For this tutorial, we will focus on Option 1 for simplicity.

Once downloaded, the software must be extracted from the zip file into a folder, and the location of that folder must be used when running commands.

For example, on Linux:

cd linux-x64
./stacks-node mainnet

For example, on Windows:

  • right click and extract the file to a folder
  • open the command prompt (cmd)
  • navigate to the directory with that folder
cd %userprofile%\Downloads\windows-x64
stacks-node.exe mainnet

Testing the Release

The best way to test that the software is working before starting to mine is to start the node as a follower and check the output.

The examples above use stacks-node mainnet to start the node, which automatically starts as a follower attached to the Stacks 2.0 mainnet.

If you see output similar to the text below, then you are ready to move on to setting up a miner.

INFO [1609701802.653224] [testnet/stacks-node/src/run_loop/] [ThreadId(1)] Follower node: starting up

Mining with a Stacks Node

To convert the follower into a miner, we have to use a TOML formatted configuration file with the settings both for our local bitcoind node and our stacks keychain.

Stacks Node Configuration File

A default configuration file for stacks-node is below, copy and paste this into a text editor and save it as mainnet-miner.conf in the same folder as stacks-node from the steps above.

rpc_bind = ""
p2p_bind = ""
seed = "your-private-key-seed"
local_peer_seed = "your-private-key-seed"
miner = true
# uncomment to mine microblocks
# mine_microblocks = true
# uncomment to change wait time for microblocks
# wait_time_for_microblocks = 30000
bootstrap_node = ",,"
# uncomment working_dir line below to change the directory
# where the stacks blockchain data is stored.
# NOTE: if this gets corrupted, your node will not start
# working_dir = "/home/username/stacks-blockchain-data"

chain = "bitcoin"
mode = "mainnet"
peer_host = ""
rpc_port = 8332
peer_port = 8333
username = "your-bitcoind-username"
password = "your-bitcoind-password"
# NOTE: adjust values below based on your strategy
satoshis_per_byte = 100
burn_fee_cap = 20000

Note: Remember to replace the seed and local_peer_seed values with the private key from your keychain, and replace username and password values with the same values you used in your bitcoin.conf file.

A full reference for the stacks node configuration file can be found as part of the official Stacks documentation.

Starting Stacks Node as a Miner

In order to use the configuration file created in the last step, you have to run stacks-node with a slightly different command:

stacks-node start --config=mainnet-miner.conf

Note: if both stacks-node and mainnet-miner.conf are in the same folder, the command above will work, however if you have your .toml configuration file in another folder you must include that path after --config=. Absolute paths are supoprted.

If you see output similar to the text below, then your miner is starting up and running correctly!

INFO [1609703751.604620] [testnet/stacks-node/src/run_loop/] [ThreadId(1)] Miner node: checking UTXOs at address: your-btc-address
INFO [1609703751.680088] [testnet/stacks-node/src/run_loop/] [ThreadId(1)] Miner node: starting up, UTXOs found.

Note that your miner does not show Miner node: starting up, UTXOs found. when it first starts up then it is not configured correctly. Please review the instructions from the beginning, and if you need help, ask others in the Discord #mining channel.

Other Resources

Bitcoin Node

A walkthrough for setting up and interacting with bitcoind for use with stacks-node.

Stacks Keychain

A walkthrough of setting up a stacks keychain using various tools.

Stacks Node

A walkthrough for setting up stacks-node and configuring it for mining.