Signer Quickstart

Current Signer and Stacks Node Versions

Stacks Signer - 3.1.0.0.5.0

• Docker Image

• GitHub Release

Stacks Node - 3.1.0.0.5

• Docker Image

• GitHub Release

If you want to get up and running as an active signer as quickly as possible, here is a list of the commands you need to run and actions to take.

If you are not familiar with how signing works yet, be sure to check out the Stackers and Signing concept guide.

If you would like a more detailed walkthrough of all of these steps, take a look at the Running a Signer guide.

Step 1 - Prerequisites

Mainnet

# Create the required directories
mkdir -p ~/stacks-signer/data
mkdir -p ~/stacks-node/data

# Install needed packages
sudo apt install -y npm wget unzip jq tar

# Install Stacks CLI globally
npm install --global @stacks/cli

# Generate a new account and store details in a file
stx make_keychain | jq > ~/stacks-signer/keychain.json

Testnet

# Create the required directories
mkdir -p ~/stacks-signer/data
mkdir -p ~/stacks-node/data

# Install needed packages
sudo apt install -y npm wget unzip jq tar

# Install Stacks CLI globally
npm install --global @stacks/cli

# Generate a new account and store details in a file
# '-t' option makes this a testnet account
stx make_keychain -t | jq > ~/stacks-signer/keychain.json

The account file previously created looks like this:

{
  "mnemonic": "aaa bbb ccc ddd ...",
  "keyInfo": {
    "privateKey": "65f3...",
    "publicKey": "03a3...",
    "address": "SP1G...",
    "btcAddress": "19tg...",
    "wif": "Kzdt...",
    "index": 0
  }
}

From this file, you'll need the privateKey value.

Step 2 - Set Up Your Stacks Signer

Download the stacks-signer binary

Official binaries are available from the Stacks Core releases page on Github. Each release includes pre-built binaries. Download the latest signer release ZIP file for your server’s architecture and decompress it. Inside of that folder is a stacks-signer binary.

Assuming a Linux x64 glibc machine, the commands to download and uncompress the signer binary look like this:

# Enter the signer directory
cd ~/stacks-signer

# Download the signer binary zip
wget https://github.com/stacks-network/stacks-core/releases/download/signer-3.1.0.0.5.0/linux-glibc-x64.zip

# Unzip the signer binary archive
unzip linux-glibc-x64.zip

Create the configuration file

Create the configuration file required to start the signer (be sure to replace <your_token> and <your_private_key> with your auth token and private key values):

Mainnet

# Set environment variables
AUTH_TOKEN=<your_token> # Used for signer-node authentication
PRIVATE_KEY=<your_private_key> # privateKey from Step 1, this is the signer's private key

# Create the signer's configuration file
cat <<EOF> ~/stacks-signer/signer-config.toml
node_host = "127.0.0.1:20443"
endpoint = "127.0.0.1:30000"
network = "mainnet"
db_path = "$HOME/stacks-signer/data/signer.sqlite"
auth_password = "$AUTH_TOKEN"
stacks_private_key = "$PRIVATE_KEY"
metrics_endpoint = "127.0.0.1:9154"
block_proposal_timeout_ms = 180000
tenure_idle_timeout_secs = 120
EOF

Testnet

# Set environment variables
AUTH_TOKEN=<your_token> # Used for signer-node authentication
PRIVATE_KEY=<your_private_key> # privateKey from Step 1, this is the signer's private key

# Create the signer's configuration file
cat <<EOF> ~/stacks-signer/signer-config.toml
node_host = "127.0.0.1:20443"
endpoint = "127.0.0.1:30000"
network = "testnet"
db_path = "$HOME/stacks-signer/data/signer.sqlite"
auth_password = "$AUTH_TOKEN"
stacks_private_key = "$PRIVATE_KEY"
metrics_endpoint = "127.0.0.1:9154"
block_proposal_timeout_ms = 180000
EOF

Verify the setup

To ensure the signer has been set up correctly, you can run the following commands:

# Verify the signer's version
~/stacks-signer/stacks-signer --version

# Output:
stacks-signer stacks-signer signer-3.1.0.0.5.0 (release/signer-3.1.0.0.5.0:513dbc5, release build, linux [x86_64])

# Verify the config file
~/stacks-signer/stacks-signer check-config -c ~/stacks-signer/signer-config.toml 

# Output:
Config: 
Stacks node host: 127.0.0.1:20443
Signer endpoint: 127.0.0.1:30000
Stacks address: SP1G... # address from keychain file
Public key: 03a3... # publicKey from keychain file
Network: mainnet # or testnet
Chain ID: 0x1 # or 0x80000000 for testnet
Database path: /home/admin/stacks-signer/data/signer.sqlite
Metrics endpoint: 127.0.0.1:9154

Start the signer

If the outputs of the previous commands are correct, you can proceed and start the signer:

~/stacks-signer/stacks-signer run -c ~/stacks-signer/signer-config.toml

Step 3a - Set up a Bitcoin node (Optional but strongly recommended)

In order to optimize signer health and performance, we highly recommend setting up your own Bitcoin node rather than relying on a third-party node.

We have created guides for running both a full Bitcoin node and a pruned Bitcoin node you can follow.

Step 3b - Set Up Your Stacks Node

Download the stacks-node binary

Official binaries are available from the Stacks Core releases page on Github. Each release includes pre-built binaries. Download the latest node release ZIP file for your server’s architecture and decompress it. Inside of that folder is a stacks-node binary.

Assuming a Linux x64 glibc machine, the commands to download and uncompress the node binary look like this:

# Enter the node directory
cd ~/stacks-node

# Download the node binary zip
wget https://github.com/stacks-network/stacks-core/releases/download/3.1.0.0.5/linux-glibc-x64.zip

# Unzip the node binary archive
unzip linux-glibc-x64.zip

Create the configuration file

Create the configuration file required to start the node (be sure to replace <your_token> with your auth token value):

Mainnet

For mainnet, we strongly recommended that you run your own bitcoin node (you can follow guides on how to run a full Bitcoin node or a pruned Bitcoin node) in order to ensure you have no connection issues when downloading bitcoin blocks. A hosted bitcoin node may cause your stacks node to fall behind tip and remain unsynced.

If you run your own bitcoin node, you'll have to update peer_host and optionally add rpc_port, peer_port, username and password fields under the [burnchain] section of the node's configuration file.

# Set environment variables
AUTH_TOKEN=<your_token> # Used for signer-node authentication, same token as the one set up in the signer configuration

# Create the node's configuration file
cat <<EOF> ~/stacks-node/node-config.toml
[node]
working_dir = "$HOME/stacks-node/data"
rpc_bind = "127.0.0.1:20443"
p2p_bind = "0.0.0.0:20444"
prometheus_bind = "127.0.0.1:9153" 
bootstrap_node = "02[e-mail]:20444,02[e-mail]:20444,02[e-mail]:20444,03[e-mail]:20444"
stacker = true

[burnchain]
chain = "bitcoin"
mode = "mainnet"
peer_host = "bitcoin.mainnet.stacks.org"

[connection_options]
auth_token = "$AUTH_TOKEN"

[[events_observer]]
endpoint = "127.0.0.1:30000"
events_keys = ["stackerdb", "block_proposal", "burn_blocks"]
EOF

Testnet

# Set environment variables
AUTH_TOKEN=<your_token> # Used for signer-node authentication, same token as the one set up in the signer configuration

# Create the node's configuration file
cat <<EOF> ~/stacks-node/node-config.toml
[node]
working_dir = "$HOME/stacks-node/data"
rpc_bind = "127.0.0.1:20443"
p2p_bind = "0.0.0.0:20444"
bootstrap_node = "02[e-mail]:30444"
prometheus_bind = "127.0.0.1:9153" 
stacker = true
pox_sync_sample_secs = 30
always_use_affirmation_maps = true
require_affirmed_anchor_blocks = true

[burnchain]
mode = "krypton"
peer_host = "bitcoin.regtest.hiro.so"
peer_port = 18444
pox_prepare_length = 100
pox_reward_length = 900

[connection_options]
auth_token = "$AUTH_TOKEN"
private_neighbors = false

[[events_observer]]
endpoint = "127.0.0.1:30000"
events_keys = ["stackerdb", "block_proposal", "burn_blocks"]

[[ustx_balance]]
address = "ST2QKZ4FKHAH1NQKYKYAYZPY440FEPK7GZ1R5HBP2"
amount = 10000000000000000

[[ustx_balance]]
address = "ST319CF5WV77KYR1H3GT0GZ7B8Q4AQPY42ETP1VPF"
amount = 10000000000000000

[[ustx_balance]]
address = "ST221Z6TDTC5E0BYR2V624Q2ST6R0Q71T78WTAX6H"
amount = 10000000000000000

[[ustx_balance]]
address = "ST2TFVBMRPS5SSNP98DQKQ5JNB2B6NZM91C4K3P7B"
amount = 10000000000000000

[[burnchain.epochs]]
epoch_name = "1.0"
start_height = 0

[[burnchain.epochs]]
epoch_name = "2.0"
start_height = 0

[[burnchain.epochs]]
epoch_name = "2.05"
start_height = 1

[[burnchain.epochs]]
epoch_name = "2.1"
start_height = 2

[[burnchain.epochs]]
epoch_name = "2.2"
start_height = 3

[[burnchain.epochs]]
epoch_name = "2.3"
start_height = 4

[[burnchain.epochs]]
epoch_name = "2.4"
start_height = 5

[[burnchain.epochs]]
epoch_name = "2.5"
start_height = 6

[[burnchain.epochs]]
epoch_name = "3.0"
start_height = 1_900

[[burnchain.epochs]]
epoch_name = "3.1"
start_height = 2_000
EOF

Optional: Start the node with a data archive

You can download a chainstate archive in order to quickly sync your node, otherwise it will take a long time to get up-to-date with the other nodes.

Mainnet

# Enter the node's datadir
cd ~/stacks-node/data

# Download the archive
wget https://archive.hiro.so/mainnet/stacks-blockchain/mainnet-stacks-blockchain-latest.tar.gz

# Decompress the archive
tar -xvf mainnet-stacks-blockchain-latest.tar.gz

# Remove the archive
rm mainnet-stacks-blockchain-latest.tar.gz

Testnet

# Enter the node's datadir
cd ~/stacks-node/data

# Download the archive
wget https://archive.hiro.so/testnet/stacks-blockchain/testnet-stacks-blockchain-latest.tar.gz

# Decompress the archive
tar -xvf testnet-stacks-blockchain-latest.tar.gz

# Remove the archive
rm testnet-stacks-blockchain-latest.tar.gz

Verify the setup

To ensure the node has been set up correctly, you can run the following commands:

# Verify the node's version
~/stacks-node/stacks-node version

# Output:
INFO [1738695915.769633] [testnet/stacks-node/src/main.rs:278] [main] stacks-node 3.1.0.0.5 (release/3.1.0.0.5:513dbc5, release build, linux [x86_64])
stacks-node 3.1.0.0.5 (release/3.1.0.0.5:513dbc5, release build, linux [x86_64])

# Verify the node's config
~/stacks-node/stacks-node check-config --config ~/stacks-node/node-config.toml

# Output:
INFO [1738695915.769633] [testnet/stacks-node/src/main.rs:278] [main] stacks-node 3.1.0.0.5 (release/3.1.0.0.5:513dbc5, release build, linux [x86_64])
INFO [1729788064.913175] [testnet/stacks-node/src/main.rs:318] [main] Loading config at path /home/admin/stacks-node/node-config.toml
INFO [1729788064.969551] [testnet/stacks-node/src/main.rs:331] [main] Loaded config!

Start the node

If the outputs of the previous commands are correct, you can proceed and start the node:

~/stacks-node/stacks-node start --config ~/stacks-node/node-config.toml

Step 5 - Generate your signer signature

In order to stack, you'll need your signer signature. The fields required are further explained in the Generate a signer key signature guide.

The command to generate a signature looks like this:

~/stacks-signer/stacks-signer generate-stacking-signature \
  --method stack-stx \
  --max-amount 1000000000000 \
  --auth-id 195591226970828652622091037492597751808 \
  --period 12 \
  --reward-cycle 100 \
  --pox-address 19tg... \
  --config ~/stacks-signer/signer-config.toml \
  --json

The generated JSON can be then copy-pasted directly in the Leather Earn website mentioned in the next step.

Step 6 - Start stacking

The simplest route is to solo stack. You can do that by using Leather Earn. Click on the 'Stack Independently' button and follow the instructions there.

If you would like to learn more about solo stacking or running a pool operator, take a look at the Stack STX guide.

Step 7 - Monitoring

If you would like to learn more about monitoring your signer and its corresponding node, you can check the How to Monitor a Signer guide.