Stacks Node Configuration
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 Signer Configuration page as it contains additional parameters needed for your signer and Stacks node to function properly.
Usage
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
For reference, several configuration file examples are available here
Example mainnet follower configuration
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
This section is optional and not required
However, if this section is added, all fields are required.
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
This section is optional and not required.
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
.
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.
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
Last updated