Stacks Node Configuration

Arguments

--config: relative or absolute path to the TOML config file. Required.

Example:

stacks-node start --config=/path/to/config.tomlstacks-node start --config=/path/to/config.toml

See Configuration File Options for more information.

version

Displays information about the current version and the release cycle.

Example:

stacks-node versionstacks-node version

help

Displays a help message.

Example:

stacks-node helpstacks-node help

working_dir (optional)

Absolute path to the directory which the stacks-node will use for storing various data. Until issue 1576 is resolved, this option is unsupported -- use at your own risk.

Example:

working_dir = "/root/stacks-node"working_dir = "/root/stacks-node"

rpc_bind

Address and port stacks-node should bind to for RPC connections.

Example:

rpc_bind = "0.0.0.0:20443"rpc_bind = "0.0.0.0:20443"

p2p_bind

Address and port stacks-node should bind to for P2P connections.

Example:

p2p_bind = "0.0.0.0:20444"p2p_bind = "0.0.0.0:20444"

data_url (optional)

Address and port from which the stacks-node will be receiving incoming rpc connections.

Example:

data_url = "1.2.3.4:20443"data_url = "1.2.3.4:20443"

p2p_address (optional)

Address and port from which the stacks-node will be receiving incoming p2p connections.

Example:

p2p_address = "1.2.3.4:20444"p2p_address = "1.2.3.4:20444"

bootstrap_node (optional)

Public key, address, and port stacks-node should use to pull transaction data from when starting.

Example:

bootstrap_node = "047435c194e9b01b3d7f7a2802d6684a3af68d05bbf4ec8f17021980d777691f1d51651f7f1d566532c804da506c117bbf79ad62eea81213ba58f8808b4d9504ad@xenon.blockstack.org:20444"bootstrap_node = "047435c194e9b01b3d7f7a2802d6684a3af68d05bbf4ec8f17021980d777691f1d51651f7f1d566532c804da506c117bbf79ad62eea81213ba58f8808b4d9504ad@xenon.blockstack.org:20444"

wait_time_for_microblocks (optional)

The amount of time (in milliseconds) that a node will wait before trying to mine a block, after catching up to the anchored chain tip. This gives the current leader time to broadcast microblocks that will get included in that mined block.

Example:

wait_time_for_microblocks = 15000wait_time_for_microblocks = 15000

seed (optional)

The private key to use for mining. Only needed if miner is set to true.

See this page for information on how to generate a private key.

Example:

seed = "replace-with-your-private-key"seed = "replace-with-your-private-key"

local_peer_seed (optional)

The private key to use for signing P2P messages in the networking stack. It differentiates network peers and is used even by non-mining nodes.

See this page for information on how to generate a private key.

Example:

local_peer_seed = "replace-with-your-private-key"local_peer_seed = "replace-with-your-private-key"

miner (optional)

Determines whether the stacks-node is running a follower (false) or a miner (true). Defaults to false if omitted.

See this page for information on how to run a miner.

Example:

miner = trueminer = true

mine_microblocks (optional)

Determines whether the stacks-node will mine microblocks. Will only take effect if miner is set to true.

See this page for information on how to run a miner.

Example:

mine_microblocks = truemine_microblocks = true

prometheus_bind (optional)

Address and port stacks-node should open for Prometheus metrics collection.

Example:

prometheus_bind = "0.0.0.0:9153"prometheus_bind = "0.0.0.0:9153"

endpoint

Address and port to a stacks-node-api to watch for events.

Example:

endpoint = "address-to-my-local.stacks-node-api.com:3700"endpoint = "address-to-my-local.stacks-node-api.com:3700"

retry_count

Number of times to retry sending events to the endpoint before failing.

Example:

retry_count = 255retry_count = 255

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.

Examples:

events_keys = ["*"]events_keys = ["*"]

events_keys = [
    "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.store::print",
    "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.ft-token",
    "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.nft-token",
    "stx"
]events_keys = [    "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.store::print",    "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.ft-token",    "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.nft-token",    "stx"]

public_ip_address

The advertised public IP of this stacks-node.

Example:

public_ip_address = "1.2.3.4:20444"public_ip_address = "1.2.3.4:20444"

download_interval

Time (in seconds) between attempts to download blocks.

Example:

download_interval = 60download_interval = 60

walk_interval

Time (in seconds) between attempts to walk the neighborhood.

Example:

walk_interval = 30walk_interval = 30

read_only_call_limit_read_length

Total number of bytes allowed to be read by an individual read-only function call.

Example:

read_only_call_limit_read_length = 100000read_only_call_limit_read_length = 100000

read_only_call_limit_read_count

Total number of independent read operations permitted for an individual read-only function call.

Example:

read_only_call_limit_read_count = 30read_only_call_limit_read_count = 30

read_only_call_limit_runtime

Runtime cost limit for an individual read-only function call.

Example:

read_only_call_limit_runtime = 1000000000read_only_call_limit_runtime = 1000000000

chain

The blockchain stacks-node binds to on the backend for proof-of-transfer. Only value supported: "bitcoin".

Example:

chain = "bitcoin"chain = "bitcoin"

mode

The profile or test phase of which to run stacks-node. Valid values are "mocknet", "helium", "neon", "argon", "krypton", "xenon".

Example:

mode = "xenon"mode = "xenon"

peer_host

Domain name of the host running the backend Bitcoin blockchain. It's required to either run a personal Bitcoin node locally, or to use a publicly hosted Bitcoin node.

Example:

peer_host = "your.bitcoind.node.org"peer_host = "your.bitcoind.node.org"

rpc_port

peer_host's port stacks-node will connect to for RPC connections.

Example:

rpc_port = 8332rpc_port = 8332

peer_port

peer_host's port stacks-node will connect to for P2P connections.

Example:

peer_port = 8333peer_port = 8333

burn_fee_cap (optional)

Maximum amount (in Satoshis) of "burn commitment" to broadcast for the next block's leader election.

Example:

burn_fee_cap = 30000burn_fee_cap = 30000

satoshis_per_byte (optional)

Amount (in Satoshis) per virtual byte. This is used to compute the transaction fees.

Example:

satoshis_per_byte = 50satoshis_per_byte = 50

So total transaction cost would be (estimated_tx_size * satoshis_per_byte) + burn_fee_cap.

commit_anchor_block_within (optional)

Sets the time period (in milliseconds) for commitments. Only used when mode is set to "helium".

Example:

commit_anchor_block_within = 10000commit_anchor_block_within = 10000

address

Address which maintains a micro-STX balance.

Example:

address = "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6"address = "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6"

amount

The balance of micro-STX given to the address at the start of the node.

Example:

amount = 10000000000000000amount = 10000000000000000