Stacks Node Configuration
Usage
stacks-node sub-command [--subcommand-option <value>]
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.
For reference, several configuration file examples are available here
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
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
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/testnetonly
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.
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 = ["*"]