Skip to main content

How to Install and Run a Stacks Node

Updated on
Jul 3, 2023
Stacks
Infrastructure
Stacks CLI

7 min read

Overview​

Stacks 2.0 is an open-source layer-1 blockchain that allows developers to build smart contracts and decentralized blockchain applications. This guide will demonstrate how to install the Stacks client and start running a mainnet node on Linux and macOS. Once our mainnet node is synced, we will use the Stacks CLI and cURL to query data from the Stacks blockchain.

What You Will Do​

  • Install and run a Stacks 2.0 mainnet node
  • Query blockchain data with the Stacks CLI and your local mainnet node
  • Query blockchain data with cURL and your local mainnet node
  • Review additional node configurations

What You Will Need​

Why Stacks?​

Stacks utilizes a consensus mechanism called Proof of Transfer ("PoX"). This consensus mechanism allows Stacks to leverage Bitcoin's security while enabling fast and cost-efficient transactions. Additionally, here are some features that Stacks offers:

  • Smart Contracts: Smart contracts can be written in the Clarity programming language. Smart contracts allow developers to build various decentralized applications such as DAOs, Non-fungible tokens (NFTs), Fungible tokens (similar to ERC-20 tokens), and payment services.
  • Mining: You can become a miner and receive Stacks fees for transactions mined in a block you help produce.
  • Stacking: You can lock your STX tokens for a certain amount of time and earn bitcoin.

Stacks Node Set Up​

Note: This guide demonstrates how to run Stacks on Unix-like operating systems (Linux and macOS).

We will be using Docker to bootstrap our Stacks mainnet node quickly. Make sure you have Docker running, then open up your terminal and run the following commands: 

docker pull blockstack/stacks-blockchain

The response should look like this:

Docker Pull Command

Then, we will create a directory that will hold our Stacks node's persistent data. Run the following command in your terminal: 

mkdir -p ./stacks-node/{persistent-data/stacks-blockchain/mainnet,config/mainnet} && cd stacks-node

Next, we will create a configuration file that will hold our Stacks node configuration. Run the following command to create a .toml file with the following configuration: 

tee -a ./config/mainnet/Config.toml <<EOF

[node]
working_dir = "/root/stacks-node/data"
rpc_bind = "0.0.0.0:20443"
p2p_bind = "0.0.0.0:20444"
bootstrap_node = "02da7a464ac770ae8337a343670778b93410f2f3fef6bea98dd1c3e9224459d36b@seed-0.mainnet.stacks.co:20444,02afeae522aab5f8c99a00ddf75fbcb4a641e052dd48836408d9cf437344b63516@seed-1.mainnet.stacks.co:20444,03652212ea76be0ed4cd83a25c06e57819993029a7b9999f7d63c36340b34a4e62@seed-2.mainnet.stacks.co:20444"
wait_time_for_microblocks = 10000

[burnchain]
chain = "bitcoin"
mode = "mainnet"
peer_host = "bitcoin.blockstack.com"
username = "blockstack"
password = "blockstacksystem"
rpc_port = 8332
peer_port = 8333

[connection_options]
read_only_call_limit_write_length = 0
read_only_call_limit_read_length = 100000
read_only_call_limit_write_count = 0
read_only_call_limit_read_count = 30
read_only_call_limit_runtime = 1000000000
EOF

Time to boot up the Stacks mainnet node! Run the following command in the same terminal window: 

docker run -d --rm \
  --name stacks-blockchain \
  -v $(pwd)/persistent-data/stacks-blockchain/mainnet:/root/stacks-node/data \
  -v $(pwd)/config/mainnet:/src/stacks-node \
  -p 20443:20443 \
  -p 20444:20444 \
  blockstack/stacks-blockchain \
/bin/stacks-node start --config /src/stacks-node/Config.toml

Note: If you are using an M1 mac, you'll need to add the config flag --platform linux/amd64 in your command: docker run --platform linux/amd64 --name stacks-blockchain.

You should see a hash output if the last command ran successfully. To make sure Docker is running our Stacks container, run the following command in your terminal: 

docker ps --filter name=stacks-blockchain

The output should look like this:

Docker Filter Command

To check the syncing progress, run the following command: 

docker logs stacks-blockchain

You may receive an error if the initial burnchain header is not synced. If so, wait 5-10 minutes, then try to run the command again. Once you see progress similar to the output below, we're in business! 

INFO [1659079212.635694] [testnet/stacks-node/src/run_loop/neon.rs:341] [main] Start syncing Bitcoin headers, feel free to grab a cup of coffee, this can take a while
INFO [1659079223.189890] [src/burnchains/bitcoin/spv.rs:923] [main] Syncing Bitcoin headers: 0.3% (2000 out of 747045)
INFO [1659079224.609923] [src/burnchains/bitcoin/spv.rs:923] [main] Syncing Bitcoin headers: 0.5% (4000 out of 747045)
INFO [1659079227.038602] [src/burnchains/bitcoin/spv.rs:923] [main] Syncing Bitcoin headers: 0.8% (6000 out of 747045)
INFO [1659079234.098386] [src/burnchains/bitcoin/spv.rs:923] [main] Syncing Bitcoin headers: 1.1% (8000 out of 747045)
INFO [1659079235.686547] [src/burnchains/bitcoin/spv.rs:923] [main] Syncing Bitcoin headers: 1.3% (10000 out of 747045)
INFO [1659079237.309671] [src/burnchains/bitcoin/spv.rs:923] [main] Syncing Bitcoin headers: 1.6% (12000 out of 747045)
INFO [1659079239.138133] [src/burnchains/bitcoin/spv.rs:923] [main] Syncing Bitcoin headers: 1.9% (14000 out of 747045)
INFO [1659079241.008169] [src/burnchains/bitcoin/spv.rs:923] [main] Syncing Bitcoin headers: 2.1% (16000 out of 747045)
...

Once the burnchain header is synced (i.e., 100%), we can run the following command to check the syncing status of the Stacks tip height: 

curl -sL localhost:20443/v2/info | jq

You should see something similar to the following output: 

{
  "peer_version": 402653189,
  "pox_consensus": "88659f1f1fa4f3c8f246ceb3b5648bf40def64cf",
  "burn_block_height": 666057,
  "stable_pox_consensus": "0000000000000000000000000000000000000000",
  "stable_burn_block_height": 666050,
  "server_version": "stacks-node 2.05.0.1.0 (master:de541f9, release build, linux [x86_64])",
  "network_id": 1,
  "parent_network_id": 3652501241,
  "stacks_tip_height": 4,
  "stacks_tip": "11c5d00aa3b99afd3e74d818164f1ef3c0aefe9f7b24b8d2a46e878e557d8eda",
  "stacks_tip_consensus_hash": "88659f1f1fa4f3c8f246ceb3b5648bf40def64cf",
  "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b",
  "unanchored_tip": null,
  "unanchored_seq": null,
  "exit_at_block_height": null
}

If the stacks_tip is 0000000000000000000000000000000000000000000000000000000000000000, wait a couple of minutes and run the command again. Eventually, you should see some progress. In our testing, it took around 14 days for the node to fully sync with the latest block of the network. Keep in mind that this will vary depending on your PC hardware and how many healthy peers your node is connected to.

To check if your Stacks mainnet node is fully synced, you can make the same cURL request to the public node (i.e., https://stacks-node-api.mainnet.stacks.co/) and verify if the stacks_tip_height and burn_block_height match your local node.

Stopping your Stacks Node​

To stop the Docker container that's running your Stacks mainnet node, run the following command in your terminal: 

docker stop stacks-blockchain

Querying Blockchain Data with the Stacks CLI and cURL​

Now that our Stacks mainnet node is synced, we can make requests to the Stacks blockchain. This section will demonstrate how to query blockchain data via the Stacks CLI and cURL. Only the v1 and v2 set of RPC methods are available on our mainnet node. If you want to query data from the extended set of methods, you'll need to run a Stacks API node (instructions can be found here) or use a service like QuickNode to manage and optimize the node infrastructure for you. More information about Stacks on QuickNode can be found here.

A list of all the supported v1 and v2 methods can be found on QuickNode's documentation page here.

Before we can use the Stacks CLI, we need to download it via npm. In your terminal, run the following command to install the Stacks CLI globally: 

npm install -g @stacks/cli

Once installed, we'll query the balance of an address on the Stacks blockchain. In your terminal, run the following command: 

stx balance SP21ZXQHV9EVNQERT3FF676S5RRFF77CHQ9TK5FE8 -I "http://localhost:20443"

You should see an output in the following format. You can verify the data is accurate by checking the same address on the Stacks Block Explorer. 

{
  "balance": "70570179407",
  "locked": "12224500000",
  "unlock_height": 747950,
  "nonce": 38
}

For additional Stacks CLI commands, check out the official Stacks documentation here.

You can also make requests to your synced node using cURL. For example, here's how you query the v2/accounts{principal} method with cURL: 

curl --location --request GET 'http://localhost:20443/v2/accounts/SPME0WF87C4HY7FYCEMVWSHK03FNNZQ45FAEJ1J5' \
--header 'Accept: application/json'

This will return: 

{
    "balance": "0x000000000000000000000000078283e8",
    "locked": "0x00000000000000000000000000000000",
    "unlock_height": 0,
    "nonce": 1657,
    "balance_proof": "0x0000000604eb000000..."
}

Remember that only v1 and v2 sets of RPC methods are available on Stacks nodes. You'll need to run a Stacks API node if you want to query the extended set of methods.

Additional Node Configurations​

If you want to run your Stacks node on another network, you can use one of the following sub-commands:

  • mocknet: A fast, local setup emulating a burnchain. Ideal for smart contract development.
  • krypton: A node that joins and streams blocks from the public krypton regtest, which is powered by Blockstack (via Proof of Transfer).
  • testnet: A node that joins and streams blocks from the public testnet.
  • mainnet: A node that joins and streams blocks from the public mainnet.

You can use the following syntax to run any of the sub-commands above: 

stacks-node sub-command [--subcommand-option <value>]

The configuration file (i.e., .toml file) can also be customized to adjust options pertaining to your Stacks node. A list of example configurations can be found here.

Final Thoughts​

Congratulations! You have learned how to run a Stacks mainnet node and successfully query blockchain data from it. Running a node helps make the Stacks network more resilient.

You can always skip and simplify this process by quickly booting up a Stacks node on Quicknode.com. 

We ❤️ Feedback!​

To learn more, check out some of our other tutorials here. If you have any feedback or questions on this guide, let us know, we’d love to hear from you!

Feel free to also reach out to us via Twitter or our Discord community server.

Written by

Ferhat Kochan

Last updated on
Share this guide