Marketplace has launched, further enabling blockchain developers! Learn more

How to Install and Run a Stacks Node

September 09, 2022

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:

stacks node set up

Copy
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:

stacks node set up

Copy
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:

stacks node set up

Copy
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 = "02d[email protected]seed-0.mainnet.stacks.co:20444,02a[email protected]seed-1.mainnet.stacks.co:20444,036[email protected]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:

stacks node set up

Copy
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:

stacks node set up

Copy
docker ps --filter name=stacks-blockchain

The output should look like this:

Docker Filter Command

To check the syncing progress, run the following command:

stacks node set up

Copy
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!

stacks node set up

Copy
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:

stacks node set up

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

You should see something similar to the following output:

stacks node set up

Copy
{
  "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:

stacks node set up

Copy
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:

querying blockchain data with the stacks cli and curl

Copy
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:

querying blockchain data with the stacks cli and curl

Copy
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.

querying blockchain data with the stacks cli and curl

Copy
{
  "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:

querying blockchain data with the stacks cli and curl

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

This will return:

querying blockchain data with the stacks cli and curl

Copy
{
    "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:

additional node configurations

Copy
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.

Related articles 11

Ethereum Full Node vs Archive Node
Published: Apr 8, 2021
Updated: Sep 20, 2022

Ethereum runs on a network of computers (also known as nodes) that verify transactions based on a consensus protocol and ledger, which make up the blockchain. In this guide, you will learn...

Continue reading
How to setup a Chainlink node
Published: Jul 6, 2020
Updated: Sep 21, 2022

Smart-contracts are the heart and soul of all the development happening on the Ethereum blockchain, and as more and more people develop on Ethereum, smart contracts are becoming more...

Continue reading
Introduction to Ethereum Rollups
Published: Dec 28, 2021
Updated: Sep 9, 2022

Ethereum, the most popular blockchain, has seen scaling issues for quite a long time now. With high gas fees due to congestion being the primary pain point. With the increasing cost to use the...

Continue reading
How to run a Hyperledger Besu node
Published: May 18, 2021
Updated: Sep 9, 2022

As the Ethereum network continues to grow, the need for an enterprise-ready Ethereum client arises. Hyperledger Besu is an enterprise-friendly Ethereum client that can implement both public...

Continue reading
How to Run a Binance Smart Chain Node
Published: Jul 2, 2021
Updated: Oct 11, 2022

Binance Smart Chain, BSC for short, is a blockchain that seeks to provide both an alternative and extension to the Ethereum Blockchain. It has done this through several clever implementations...

Continue reading
How to install and run a Geth node
Published: Apr 5, 2020
Updated: Sep 12, 2022

Ethereum nodes are computers participating in Ethereum blockchain network. These nodes are actual computers running software that verifies, stores, and sometimes creates blocks. The actual...

Continue reading
How to run Nethermind node
Published: May 18, 2021
Updated: Nov 18, 2022

To run an Ethereum node without any problems, it is essential to choose a good node client. Nethermind is one of the oldest and most trusted Ethereum node clients. In this guide, let’s see how...

Continue reading
How to Use Laika with QuickNode
Published: Apr 22, 2022
Updated: Sep 9, 2022

Developers spend most of their time writing code, testing, and fixing bugs. A lot of the time spent with these tasks can be simplified by using a tool like Laika. Laika is a Web3 development...

Continue reading