🛠️
Stacks Documentation
  • Start Here
  • 🧠Concepts
    • Stacks 101
      • What Is Stacks?
      • Bitcoin Connection
      • Proof of Transfer
      • Stacks Among Other Layers
      • Financial Incentive and Security Budget
    • Network Fundamentals
      • Network Basics
      • Mainnet and Testnets
      • Accounts
      • Authentication
      • Bitcoin Name System
      • SIPs
      • Technical Specifications
    • Block Production
      • Mining
      • Signing
      • Bitcoin Finality
      • Bitcoin Reorgs
      • Stacking
    • Transactions
      • How Transactions Work
      • Post Conditions
    • Clarity
      • Overview
      • Decidability
    • sBTC
      • Core Features
      • sBTC Operations
        • Deposit
        • Withdrawal
        • Deposit vs Withdrawal Times
      • Emily API
      • Peg Wallet UTXO
      • Clarity Contracts
        • sBTC Registry
        • sBTC Token
        • sBTC Deposit
        • sBTC Withdrawal
      • Auxiliary Features
        • Transaction Fee Sponsorship
        • Signer Wallet Rotation
      • Walkthroughs
        • Signer Process Walkthrough
        • sBTC Transaction Walkthrough
      • sBTC FAQ
    • Gaia
      • Configuration
      • Deploy Gaia Hub
      • Amazon EC2
      • Linux
      • Mac OS
  • 🛠️Guides & Tutorials
    • Developer Quickstart
    • Clarity Crash Course
    • Build a Borrowing & Lending Protocol
    • Bitcoin Integration
      • Sending Bitcoin with Leather Wallet
      • Verifying a Bitcoin Transaction
      • Parsing a Bitcoin Transaction
    • Create Tokens
      • Creating a NFT
      • Creating a Fungible Token
    • Build a Frontend
      • Post Conditions with Stacks.js
      • Authentication with Stacks.js
      • Sending Transactions with Stacks.js
    • Testing Smart Contracts
      • Fuzz Testing
    • Run a Node
      • Run a Node with Docker
      • Run a Node with Digital Ocean
      • Run a Node with a Hosted Provider
      • Run a Node with Quicknode
      • Run a Bitcoin Node
      • Run a Pruned Bitcoin Node
    • Run a Miner
      • Miner Prerequisites
      • Miner Costs and Fees
      • Mine Testnet Stacks Tokens
      • Mine Mainnet Stacks Tokens
      • Verify Miner
    • Run a Signer
      • Signer Quickstart
      • How to Read Signer Logs
      • How to Monitor a Signer
      • Best practices for running a Signer
      • OpSec Best Practices
    • sBTC
      • How to Run an sBTC Signer
      • Best practices for running an sBTC Signer
      • How to Use the sBTC Bridge
      • Earn sBTC Rewards
    • Stack STX
      • Solo Stack
      • Operate a Pool
      • Stack with a Pool
      • Increase Stacked Position
      • Stop Stacking
    • Oracles
    • Community Tutorials
  • 📚Reference
    • API
    • Clarity Types
    • Clarity Functions
    • Clarity Keywords
    • Stacks Node Configuration
    • Signer Configuration
    • Stacks Tooling
  • 🏗️Example Contracts
    • Audited Starter Contracts
    • Stacking
    • BNS
    • Multi Send
  • 🧡Press & Top Links
    • 🔶2024
      • 🔸January 2024
      • 🔸February 2024
      • 🔸March 2024
      • 🔸April 2024
      • 🔸May 2024
      • 🔸June 2024
      • 🔸July 2024
      • 🔸August 2024
      • 🔸September 2024
      • 🔸October 2024
      • 🔸November 2024
      • 🔸December 2024
    • 🔶2025
      • 🔸January 2025
      • 🔸February 2025
      • 🔸March 2025
      • 🔸April 2025
      • 🔸May 2025
  • 🧡Bitcoin Theses and Reports
    • 🟠Bitcoin Theses
    • 📙Bitcoin Reports
  • Contribute
Powered by GitBook
On this page
  • Usage
  • Configuration File Options
  • Example Mainnet Follower Configuration
  • Example Testnet Follower Configuration

Was this helpful?

  1. Reference

Stacks Node Configuration

PreviousClarity KeywordsNextSigner Configuration

Last updated 3 months ago

Was this helpful?

Note that these config fields are for a Stacks follower node. If you are running a signer alongside your Stacks node, you'll want to use the sample file found on the page as it contains additional parameters needed for your signer and Stacks node to function properly.

Usage

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

Subcommands

  • mocknet: start a mocknet instance using defaults

  • testnet: start a testnet instance using defaults (chainstate is not persistent)

  • mainnet: start a mainnet instance using defaults (chainstate is not persistent)

  • start: combined with --config, starts an instance with a specified configuration file

  • version: displays binary version

  • help: displays the help message

Configuration File Options

The Stacks Blockchain configuration file has multiple sections under which an option may be placed.

  • node

  • events_observer

  • connection_options

  • burnchain

  • ustx_balance

  • miner

node

Contains various configuration options for the stacks-node binary.

Name
Required
Description

rpc_bind

✓

IPv4 address and port to open for RPC connections

p2p_bind

✓

IPv4 address and port to open for P2P connections

working_dir

Absolute path to the directory where chainstate data will be stored

data_url

IPv4 address and port for incoming RPC connections

p2p_address

IPv4 address and port for incoming P2P connections

bootstrap_node

Public key, IPv4 address, and port to bootstrap the chainstate

wait_time_for_microblocks

The amount of time in ms to wait before trying to mine a block after catching up to the anchored chain tip

seed

The private key to use for mining. Only needed if miner is set to true

local_peer_seed

The private key to use for signing P2P messages in the networking stack

miner

Determines whether the node is running a follower (false) or a miner (true). Defaults to false

mock_mining

Simulates running a miner (typically used for debugging)

mock_mining_output_dir

Folder for mock mining data

mine_microblocks

Determines whether the node will mine microblocks. Will only take effect if miner is set to true

prometheus_bind

Address and port for Prometheus metrics collection.

deny_nodes

List of ip addresses of nodes that should be ignored

stacker

Determines whether the node is running a stacker (true) that issues events for signer binary

events_observer

This section is optional and not required

However, if this section is added, all fields are required.

Name
Required
Description

endpoint

✓

events_keys

✓

Event keys for which to watch. The emitted node events can be restricted by account, function name and event type. Asterix ("*") can be used to emit all events.

connection_options

This section is optional and not required.

Specifies configuration options for others connecting to the stacks node.

Name
Required
Description

public_ip_address

Public IPv4 to advertise to other nodes

download_interval

Time (in seconds) between attempts to download blocks

walk_interval

Time (in seconds) between attempts to walk the list of neighbors

private_neighbors

If false, this node won't announce or accept neighbors that are behind private networks. Defaults to true.

read_only_call_limit_read_length

Total number of bytes allowed to be read by an individual read-only function call

read_only_call_limit_read_count

Total number of independent read operations permitted for an individual read-only function call

read_only_call_limit_runtime

burnchain

This section contains configuration options pertaining to the blockchain the stacks-node binds to on the backend for proof-of-transfer (BTC).

Name
Required
Description

chain

✓

The blockchain stacks-node binds to on the backend for proof-of-transfer. Only value supported: bitcoin

mode

✓

The profile or test phase of which to run stacks-node. Valid values are [ mocknet, testnet, xenon, mainnet ]

peer_host

FQDN of the host running the backend Bitcoin blockchain

rpc_port

RPC port of peer_host

peer_port

P2P port of peer_host

Mining

Name
Required
Description

burn_fee_cap

✓

Maximum amount (in sats) of "burn commitment" to broadcast for the next block's leader election

satoshis_per_byte

✓

commit_anchor_block_within

Sets the time period (in milliseconds) for commitments. Only used when mode is set to mocknet.

tenure_extend_cost_threshold

Percentage of block budget that must be used before attempting a time-based tenure extend

block_rejection_timeout_steps

Define the timeout to apply while waiting for signers responses, based on the amount of rejections

ustx_balance

This section is only required for the testnet and mocknet networks.

However, if this section is added, all fields are required.

This section contains configuration options allocating microSTX per address in the genesis block

This section can repeat multiple times, but each section can only define a single address.

Name
Required
Description

address

✓

Address which maintains a microSTX balance

amount

✓

The balance of microSTX given to the address at the start of the node

Example Mainnet Follower Configuration

[node]
working_dir = "/stacks-blockchain"
rpc_bind = "0.0.0.0:30443"
p2p_bind = "0.0.0.0:20444"
bootstrap_node = "02196f005965cebe6ddc3901b7b1cc1aa7a88f305bb8c5893456b8f9a605923893@seed.mainnet.hiro.so:20444,02539449ad94e6e6392d8c1deb2b4e61f80ae2a18964349bc14336d8b903c46a8c@cet.stacksnodes.org:20444,02ececc8ce79b8adf813f13a0255f8ae58d4357309ba0cedd523d9f1a306fcfb79@sgt.stacksnodes.org:20444,0303144ba518fe7a0fb56a8a7d488f950307a4330f146e1e1458fc63fb33defe96@est.stacksnodes.org:20444"

[burnchain]
chain = "bitcoin"
mode = "mainnet"
peer_host = "localhost"
peer_port = 8333

[[events_observer]]
endpoint = "localhost:3700"
events_keys = ["*"]

Example Testnet Follower Configuration

[node]

rpc_bind = "0.0.0.0:20443"
p2p_bind = "0.0.0.0:20444"
bootstrap_node = "029266faff4c8e0ca4f934f34996a96af481df94a89b0c9bd515f3536a95682ddc@seed.testnet.hiro.so:30444"
prometheus_bind = "127.0.0.1:9153"
working_dir = "/stacks-blockchain"

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

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

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

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

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

[fee_estimation]
fee_estimator = "fuzzed_weighted_median_fee_rate"

[[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

For reference, several configuration file examples are .

Contains options for sending events emitted to the service.

Address and port to a service

limit for an individual read-only function call

- Used to calculate the transaction fees

📚
Signer Configuration
available here
stacks-blockchain-api
stacks-blockchain-api
Runtime cost
Amount (in sats) per byte