Running a testnet node

Learn how to set up and run a testnet node
beginners
15 minutes

Introduction

This tutorial will walk you through the following steps:

  • Download and install the node software
  • Run the node against testnet
  • Mine Stacks token

Requirements

In order to run a node, some software and hardware requirements need to be considered.

Hardware

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

With these considerations in mind, 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.

Software

If you use Linux, you may need to manually install libssl-dev and other packages. In your command line, run the following to get all packages:

sudo apt-get install build-essential cmake libssl-dev pkg-configsudo apt-get install build-essential cmake libssl-dev pkg-config

Ensure that you have Rust installed. If you are using macOS, Linux, or another Unix-like OS, run the following. If you are on a different OS, follow the official Rust installation guide.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -ycurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y

In case you just installed Rust, you will be prompted to run the following command to make the cargo command available:

source $HOME/.cargo/envsource $HOME/.cargo/env

Installing the node from pre-built binary

Step 1: Get the distributable

Download and unzip the distributable which cooresponds to your environment from the latest release.

If you're running on Windows, please follow our instructions from installing a node on Windows.

Step 2: Run the binary

To run the stacks-node binary, execute the following:

./stacks-node xenon./stacks-node xenon

Awesome. Your node is now connected to the testnet network.

Your node will receive new blocks when they are produced, and you can use the Stacks Node RPC API to send transactions, fetch information for contracts and accounts, and more.

Installing the node from source

You might want to build and install from source if there are some updates in the main branch which aren't yet released, or if there is no pre-built binary for your environment.

Step 1: Install the node

Clone this repository:

git clone https://github.com/blockstack/stacks-blockchain.git; cd stacks-blockchaingit clone https://github.com/blockstack/stacks-blockchain.git; cd stacks-blockchain

Change the below values to reflect the version, branch, and git commit of the source code being built for accuracy:

# The following values are just an example export STACKS_NODE_VERSION=2.0.9 export GIT_BRANCH=master export GIT_COMMIT=e7f178b# The following values are just an exampleexport STACKS_NODE_VERSION=2.0.9export GIT_BRANCH=masterexport GIT_COMMIT=e7f178b

Install the Stacks node by running:

cargo build --workspace --release --bin stacks-node # binary will be in target/release/stacks-nodecargo build --workspace --release --bin stacks-node# binary will be in target/release/stacks-node

To install Stacks node with extra debugging symbols, run:

cargo build --workspace --bin stacks-node # binary will be in target/debug/stacks-nodecargo build --workspace --bin stacks-node# binary will be in target/debug/stacks-node

Step 2: Run the node

You're all set to run a node that connects to the testnet network.

If installed without debugging symbols, run:

target/release/stacks-node xenontarget/release/stacks-node xenon

If installed with debugging symbols, run:

target/debug/stacks-node xenontarget/debug/stacks-node xenon

The first time you run this, you'll see some logs indicating that the Rust code is being compiled. Once that's done, you should see some logs that look something like the this:

INFO [1588108047.585] [src/chainstate/stacks/index/marf.rs:732] First-ever block 0f9188f13cb7b2c71f2a335e3a4fc328bf5beb436012afca590b1a11466e2206INFO [1588108047.585] [src/chainstate/stacks/index/marf.rs:732] First-ever block 0f9188f13cb7b2c71f2a335e3a4fc328bf5beb436012afca590b1a11466e2206

Running the testnet node on Windows

Prerequisites

Before you begin, check that you have the below necessary softwares installed on your PC

Optional Dependencies

Download the Binary and run the follower node

First, Visit the Stacks Github releases repo. From the various binary list, click to download the Windows binary. Refer the image below.

BinaryList

Next, click on save file and Press Ok in the popup window.

Windowspopup

Once saved, Extract the binary. Open the command prompt from the folder where binary is extracted and execute the below command:

stacks-node xenon # This command will start the testnet follower node.stacks-node xenon# This command will start the testnet follower node.

To execute Stacks node with extra debugging enabled, run:

set RUST_BACKTRACE=full set STACKS_LOG_DEBUG=1 stacks-node xenon # This command will execute the binary and start the follower node with debug enabled.set RUST_BACKTRACE=fullset STACKS_LOG_DEBUG=1stacks-node xenon# This command will execute the binary and start the follower node with debug enabled.

The first time you run this, you'll see some logs indicating that the Rust code is being compiled. Once that's done, you should see some logs that look something like the this:

INFO [1588108047.585] [src/chainstate/stacks/index/marf.rs:732] First-ever block 0f9188f13cb7b2c71f2a335e3a4fc328bf5beb436012afca590b1a11466e2206INFO [1588108047.585] [src/chainstate/stacks/index/marf.rs:732] First-ever block 0f9188f13cb7b2c71f2a335e3a4fc328bf5beb436012afca590b1a11466e2206

Awesome. Your node is now connected to the testnet network.

Optional: Running with Docker

Alternatively, you can run the testnet node with Docker.

docker run -d \ --name stacks_follower \ -p 20443:20443 \ -p 20444:20444 \ blockstack/stacks-blockchain \ stacks-node xenondocker run -d \ --name stacks_follower \ -p 20443:20443 \ -p 20444:20444 \ blockstack/stacks-blockchain \ stacks-node xenon

You can review the node logs with this command:

docker logs -f stacks_followerdocker logs -f stacks_follower

Optional: Running in Kubernetes with Helm

In addition, you're also able to run a testnet node in a Kubernetes cluster using the stacks-blockchain Helm chart.

Ensure you have the following prerequisites installed on your machine:

To install the chart with the release name my-release and run the node as a follower:

minikube start # Only run this if standing up a local Kubernetes cluster helm repo add blockstack https://charts.blockstack.xyz helm install my-release blockstack/stacks-blockchainminikube start # Only run this if standing up a local Kubernetes clusterhelm repo add blockstack https://charts.blockstack.xyzhelm install my-release blockstack/stacks-blockchain

You can review the node logs with this command:

kubectl logs -l app.kubernetes.io/name=stacks-blockchainkubectl logs -l app.kubernetes.io/name=stacks-blockchain

For more information on the Helm chart and configuration options, please refer to the chart's homepage.

Optional: Mining Stacks token

Now that you have a running testnet node, you can easily set up a miner.

Graphic for: Mine testnet Stacks tokens
Mine testnet Stacks tokens
tutorial
Set up and run a miner on the Stacks 2.0 testnet
Previous
Running a mainnet node
Next
Running a regtest node
Powered by