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.
  • 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

:::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.
| 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

:::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.
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
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

  • 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 :::
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: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 = ["*"]