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.

NameRequiredDescription

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

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

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

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_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).

NameRequiredDescription

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

NameRequiredDescription

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

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.

NameRequiredDescription

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

Last updated