stacks-node-configuration.md

Stacks Node Configuration

{% hint style="info" %} 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. {% endhint %}

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

For reference, several configuration file examples are available here

• Example mainnet follower configuration

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_miner		Simulates running a miner (typically used for debugging)
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.

events_observer

{% hint style="info" %} This section is optional and not required

However, if this section is added, all fields are required. {% endhint %}

Contains options for sending events emitted to the stacks-blockchain-api service.

Name	Required	Description
endpoint	✓	Address and port to a stacks-blockchain-api service
retry_count	✓	Number of times to retry sending events to the endpoint before failing
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

{% hint style="info" %} This section is optional and not required. {% endhint %}

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		Runtime cost limit 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).

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	✓	Amount (in sats) per byte - Used to calculate the transaction fees
commit_anchor_block_within		Sets the time period (in milliseconds) for commitments. Only used when mode is set to mocknet.

ustx_balance

{% hint style="info" %} This section is only required for the testnet and mocknet networks.

However, if this section is added, all fields are required. {% endhint %}

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"
username = "user"
password = "pass"
rpc_port = 8332
peer_port = 8333

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