Signer Quickstart

Current Signer and Stacks Node Versions

Stacks Signer - latest

• Docker Image

• GitHub Release

Stacks Node - latest

• 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 Signing concept guide.

The CLI examples below may show outdated release versions. For the latest releases, always refer to the links above in the top info block.

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

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.

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:

# The CLI examples below may show outdated release versions.
# Enter the signer directory
cd ~/stacks-signer

# Download the signer binary zip
wget https://github.com/stacks-network/stacks-core/releases/latest/download/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

# The CLI examples below may show outdated release versions.
# 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

Verify the setup

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

# The CLI examples below may show outdated release versions.
# 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

3

Optional: Set up a Bitcoin node (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.

4

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:

# The CLI examples below may show outdated release versions.
# Enter the node directory
cd ~/stacks-node

# Download the node binary zip
wget https://github.com/stacks-network/stacks-core/releases/latest/download/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.

# The CLI examples below may show outdated release versions.
# 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

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

Verify the setup

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

# The CLI examples below may show outdated release versions.
# 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

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.

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.

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.