Stacks Node Configuration
Usage
stacks-node sub-command [--subcommand-option <value>]
Subcommands
mocknet
: start a mocknet instance using defaultstestnet
: 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 fileversion
: displays binary versionhelp
: 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
For reference, several configuration file examples are available here.
node
Contains various configuration options for the stacks-node binary.
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
Contains options for sending events emitted to the stacks-blockchain-api service.
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
Specifies configuration options for others connecting to the stacks node.
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
burnchain
This section contains configuration options pertaining to the blockchain the stacks-node binds to on the backend for proof-of-transfer (BTC).
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
burn_fee_cap
✓
Maximum amount (in sats) of "burn commitment" to broadcast for the next block's leader election
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 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.
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
Last updated
Was this helpful?