Skip to main content

Stacks Node Configuration

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.

For reference, several configuration file examples are available here

node

Contains various configuration options for the stacks-node binary.

NameRequiredDescription
rpc_bindIPv4 address and port to open for RPC connections
p2p_bindIPv4 address and port to open for P2P connections
working_dirAbsolute path to the directory where chainstate data will be stored
data_urlIPv4 address and port for incoming RPC connections
p2p_addressIPv4 address and port for incoming P2P connections
bootstrap_nodePublic key, IPv4 address, and port to bootstrap the chainstate
wait_time_for_microblocksThe amount of time in ms to wait before trying to mine a block after catching up to the anchored chain tip
seedThe private key to use for mining. Only needed if miner is set to true
local_peer_seedThe private key to use for signing P2P messages in the networking stack
minerDetermines whether the node is running a follower (false) or a miner (true). Defaults to false
mock_minerSimulates running a miner (typically used for debugging)
mine_microblocksDetermines whether the node will mine microblocks. Will only take effect if miner is set to true
prometheus_bindAddress and port for Prometheus metrics collection.

events_observer

info

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.

NameRequiredDescription
endpointAddress and port to a stacks-blockchain-api service
retry_countNumber of times to retry sending events to the endpoint before failing
events_keysEvent 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

info

This section is optional and not required.

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

Specifies configuration options for others connecting to the stacks node.

NameRequiredDescription
public_ip_addressPublic IPv4 to advertise to other nodes
download_intervalTime (in seconds) between attempts to download blocks
walk_intervalTime (in seconds) between attempts to walk the list of neighbors
read_only_call_limit_read_lengthTotal number of bytes allowed to be read by an individual read-only function call
read_only_call_limit_read_countTotal number of independent read operations permitted for an individual read-only function call
read_only_call_limit_runtimeRuntime 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).

NameRequiredDescription
chainThe blockchain stacks-node binds to on the backend for proof-of-transfer. Only value supported: bitcoin
modeThe profile or test phase of which to run stacks-node. Valid values are [ mocknet, testnet, xenon, mainnet ]
peer_hostFQDN of the host running the backend Bitcoin blockchain
rpc_portRPC port of peer_host
peer_portP2P port of peer_host

Mining

NameRequiredDescription
burn_fee_capMaximum amount (in sats) of "burn commitment" to broadcast for the next block's leader election
satoshis_per_byteAmount (in sats) per byte - Used to calculate the transaction fees
commit_anchor_block_withinSets the time period (in milliseconds) for commitments. Only used when mode is set to mocknet.

ustx_balance

  • mocknet/testnet only

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.

info

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

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

NameRequiredDescription
addressAddress which maintains a microSTX balance
amountThe 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:20443"
p2p_bind = "0.0.0.0:20444"
bootstrap_node = "02da7a464ac770ae8337a343670778b93410f2f3fef6bea98dd1c3e9224459d36b@seed-0.mainnet.stacks.co:20444,02afeae522aab5f8c99a00ddf75fbcb4a641e052dd48836408d9cf437344b63516@seed-1.mainnet.stacks.co:20444,03652212ea76be0ed4cd83a25c06e57819993029a7b9999f7d63c36340b34a4e62@seed-2.mainnet.stacks.co:20444"

[burnchain]
chain = "bitcoin"
mode = "mainnet"
peer_host = "localhost"
username = "user"
password = "pass"
rpc_port = 8332
peer_port = 8333

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