Skip to content

Commit 3595c00

Browse files
simone-stackssimone-stacks
authored
Merge pull request stacks-network#6936 from simone-stacks/docs/miner-signer-settings
docs: comprehensive miner and signer configuration reference
2 parents faa4b28 + 0d0b61c commit 3595c00

13 files changed

+1370
-83
lines changed

‎docs/follower.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Running a Stacks Follower Node
2+
3+
A follower (or "full node") syncs the Stacks blockchain without mining or signing.
4+
Use cases include serving RPC/API requests, running a stacks-blockchain-api instance,
5+
or monitoring the chain.
6+
7+
## Quick Start
8+
9+
```toml
10+
[node]
11+
working_dir = "/stacks-data/mainnet"
12+
rpc_bind = "0.0.0.0:20443"
13+
p2p_bind = "0.0.0.0:20444"
14+
miner = false
15+
stacker = false
16+
17+
[burnchain]
18+
mode = "mainnet"
19+
peer_host = "127.0.0.1"
20+
```
21+
22+
Start the node:
23+
24+
```bash
25+
stacks-node start --config=mainnet-follower-conf.toml
26+
```
27+
28+
## Bitcoin Node
29+
30+
A follower needs a Bitcoin node to sync burnchain data. For mainnet, the default
31+
ports (`rpc_port = 8332`, `peer_port = 8333`) are used. If your Bitcoin node requires
32+
RPC authentication, add credentials to `[burnchain]`:
33+
34+
```toml
35+
[burnchain]
36+
username = "your-bitcoin-rpc-user"
37+
password = "your-bitcoin-rpc-password"
38+
```
39+
40+
## API Integration
41+
42+
To run a stacks-blockchain-api service alongside the follower, enable the events
43+
observer and transaction indexing:
44+
45+
```toml
46+
[node]
47+
txindex = true
48+
49+
[[events_observer]]
50+
endpoint = "localhost:3700"
51+
events_keys = ["*"]
52+
timeout_ms = 60_000
53+
```
54+
55+
## Upgrading to a Signer Node
56+
57+
A follower can be upgraded to also serve a signer by adding three settings.
58+
See [signing.md](signing.md) for full details.
59+
60+
```toml
61+
[node]
62+
stacker = true
63+
64+
[[events_observer]]
65+
endpoint = "127.0.0.1:30000"
66+
events_keys = ["stackerdb", "block_proposal", "burn_blocks"]
67+
68+
[connection_options]
69+
auth_token = "your-secret-token"
70+
```
71+
72+
## Local Development (Mocknet)
73+
74+
For local development without a Bitcoin node, use mocknet mode:
75+
76+
```bash
77+
stacks-node start --config=mocknet.toml
78+
```
79+
80+
Mocknet runs a simulated burnchain in-process, removes execution cost limits,
81+
and requires pre-funded test accounts via `[[ustx_balance]]` entries.
82+
See [`mocknet.toml`](../sample/conf/mocknet.toml).
83+
84+
## Environment Variables
85+
86+
These environment variables affect node behavior and cannot be set via TOML:
87+
88+
| Variable | Purpose |
89+
| --- | --- |
90+
| `STACKS_EVENT_OBSERVER` | Add an event observer endpoint (all events) |
91+
| `STACKS_WORKING_DIR` | Override `node.working_dir` |
92+
| `STACKS_LOG_JSON` | Enable JSON-formatted logging |
93+
| `STACKS_LOG_DEBUG` | Enable debug-level logging |
94+
| `STACKS_LOG_TRACE` | Enable trace-level logging |
95+
96+
## Configuration Files
97+
98+
| File | Purpose |
99+
| --- | --- |
100+
| [`mainnet-follower-conf.toml`](../sample/conf/mainnet-follower-conf.toml) | Mainnet follower |
101+
| [`testnet-follower-conf.toml`](../sample/conf/testnet-follower-conf.toml) | Testnet follower |
102+
| [`mocknet.toml`](../sample/conf/mocknet.toml) | Local mocknet development |
103+
104+
## Further Reading
105+
106+
- [Mining documentation](mining.md)
107+
- [Signing documentation](signing.md)

‎docs/mining.md‎

Lines changed: 42 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,11 @@ you should make sure to add the following config fields to your [config file](..
66
```toml
77
[node]
88
# Run as a miner
9-
miner = True
9+
miner = true
1010
# Bitcoin private key to spend
1111
seed = "YOUR PRIVATE KEY"
12-
# Run as a mock-miner, to test mining without spending BTC. Needs miner=True.
13-
#mock_mining = True
12+
# Enable stacker support (required for signer coordination)
13+
stacker = true
1414

1515
[miner]
1616
# Time to spend mining a Nakamoto block, in milliseconds.
@@ -25,8 +25,45 @@ satoshis_per_byte = 50
2525
rbf_fee_increment = 5
2626
# Maximum percentage of satoshis_per_byte to allow in RBF fee (default: 150)
2727
max_rbf = 150
28+
29+
[connection_options]
30+
# Must match signer's auth_password
31+
auth_token = "your-secret-token"
32+
33+
[[events_observer]]
34+
# Must match signer's endpoint
35+
endpoint = "127.0.0.1:30000"
36+
events_keys = ["stackerdb", "block_proposal", "burn_blocks"]
2837
```
2938

39+
> To test mining without spending BTC, add `mock_mining = true` to the `[node]`
40+
> section. See also [`mainnet-mockminer-conf.toml`](../sample/conf/mainnet-mockminer-conf.toml).
41+
42+
For a comprehensive reference of **all** miner settings including signer coordination
43+
timeouts, tenure management, mempool configuration, and cost limits, see
44+
[`mainnet-miner-conf.toml`](../sample/conf/mainnet-miner-conf.toml).
45+
46+
## Signer Setup
47+
48+
Nakamoto mining requires a co-located signer. See [signing.md](signing.md) for
49+
signer configuration and the critical miner-signer coordination settings.
50+
51+
## Configuration Files
52+
53+
| File | Purpose |
54+
| ---------------------------------------------------------------------------- | ------------------------------------------------------- |
55+
| [`mainnet-miner-conf.toml`](../sample/conf/mainnet-miner-conf.toml) | Comprehensive miner reference (all settings documented) |
56+
| [`mainnet-signer-conf.toml`](../sample/conf/signer/mainnet-signer-conf.toml) | Signer binary config reference |
57+
| [`mainnet-signer.toml`](../sample/conf/mainnet-signer.toml) | Node-side signer config |
58+
| [`testnet-miner-conf.toml`](../sample/conf/testnet-miner-conf.toml) | Testnet miner config |
59+
| [`mainnet-mockminer-conf.toml`](../sample/conf/mainnet-mockminer-conf.toml) | Mock miner (test mining without spending BTC) |
60+
| [`mainnet-follower-conf.toml`](../sample/conf/mainnet-follower-conf.toml) | Mainnet follower (read-only node) |
61+
| [`testnet-follower-conf.toml`](../sample/conf/testnet-follower-conf.toml) | Testnet follower |
62+
| [`testnet-signer.toml`](../sample/conf/testnet-signer.toml) | Testnet node-side signer config |
63+
| [`mocknet.toml`](../sample/conf/mocknet.toml) | Local mocknet development |
64+
65+
## RBF Configuration
66+
3067
NOTE: Ensuring that your miner can successfully use RBF (Replace-by-Fee) is
3168
critical for reliable block production. If a miner fails to replace an outdated
3269
block commit with a higher-fee transaction, it risks committing to an incorrect
@@ -81,5 +118,7 @@ Estimates are then randomly "fuzzed" using uniform random fuzz of size up to
81118

82119
## Further Reading
83120

121+
- [Signing documentation](signing.md)
122+
- [Follower documentation](follower.md)
84123
- [stacksfoundation/miner-docs](https://github.com/stacksfoundation/miner-docs)
85124
- [Mining Documentation](https://docs.stacks.co/stacks-in-depth/nodes-and-miners/mine-mainnet-stacks-tokens)

‎docs/signing.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# Stacks Signing
2+
3+
Stacks signers validate and co-sign blocks produced by miners. Running a signer
4+
requires two configuration files:
5+
6+
1. **Signer binary config** — configures the `stacks-signer` process
7+
2. **Signer node config** — configures the `stacks-node` that the signer connects to
8+
9+
## Configuration Files
10+
11+
| File | Binary | Purpose |
12+
| ---------------------------------------------------------------------------- | --------------- | ----------------------------------------------------------- |
13+
| [`mainnet-signer-conf.toml`](../sample/conf/signer/mainnet-signer-conf.toml) | `stacks-signer` | Signer process settings (keys, timeouts, tenure management) |
14+
| [`mainnet-signer.toml`](../sample/conf/mainnet-signer.toml) | `stacks-node` | Node-side settings (events, auth, networking) |
15+
16+
For testnet, use [`testnet-signer.toml`](../sample/conf/testnet-signer.toml) for the node-side config.
17+
18+
## Quick Start
19+
20+
### 1. Configure the Stacks Node
21+
22+
Use [`mainnet-signer.toml`](../sample/conf/mainnet-signer.toml) as a starting point for your node config.
23+
Key settings:
24+
25+
```toml
26+
[node]
27+
stacker = true
28+
29+
[[events_observer]]
30+
endpoint = "127.0.0.1:30000"
31+
events_keys = ["stackerdb", "block_proposal", "burn_blocks"]
32+
33+
[connection_options]
34+
auth_token = "your-secret-token"
35+
```
36+
37+
### 2. Configure the Signer
38+
39+
Use [`mainnet-signer-conf.toml`](../sample/conf/signer/mainnet-signer-conf.toml) as a starting point.
40+
Key settings:
41+
42+
```toml
43+
stacks_private_key = "<YOUR_SIGNER_PRIVATE_KEY_HEX>"
44+
node_host = "127.0.0.1:20443"
45+
endpoint = "0.0.0.0:30000"
46+
network = "mainnet"
47+
auth_password = "your-secret-token"
48+
db_path = "/var/lib/stacks-signer/signerdb.sqlite"
49+
```
50+
51+
### 3. Verify Coordination
52+
53+
These settings **must** match between the node and signer configs:
54+
55+
| Signer Config | Node Config | Must Match |
56+
| --------------- | --------------------------------- | ----------------------------- |
57+
| `auth_password` | `[connection_options] auth_token` | Exact string match |
58+
| `endpoint` | `[[events_observer]] endpoint` | Same host:port |
59+
| `node_host` | `[node] rpc_bind` | Signer connects to node's RPC |
60+
61+
## Miner-Signer Interactions
62+
63+
If you are running both a miner and a signer, several timeout settings must be
64+
coordinated to avoid block rejections. See the WARNING comments in
65+
[`mainnet-miner-conf.toml`](../sample/conf/mainnet-miner-conf.toml) and
66+
[`mainnet-signer-conf.toml`](../sample/conf/signer/mainnet-signer-conf.toml) for details.
67+
68+
Key interactions:
69+
70+
- **`tenure_extend_wait_timeout_ms`** (miner) must be >= **`block_proposal_timeout_ms`** (signer).
71+
The signer waits `block_proposal_timeout_ms` before marking an unresponsive miner as inactive.
72+
If the miner extends before the signer invalidates the new winner, the extend is rejected.
73+
74+
- **`tenure_timeout_secs`** (miner) should be > signer's **`tenure_idle_timeout_secs + tenure_idle_timeout_buffer_secs`** (default 62s).
75+
The signer computes an extend timestamp from the last block time + idle timeout + buffer.
76+
The miner must wait at least this long before time-based extends.
77+
78+
- **`min_time_between_blocks_ms`** (miner) must be >= 1000ms.
79+
Blocks with same-second timestamps as their parent are rejected network-wide.
80+
81+
## Running
82+
83+
```bash
84+
# Start the node
85+
stacks-node start --config mainnet-signer.toml
86+
87+
# Start the signer
88+
stacks-signer run --config mainnet-signer-conf.toml
89+
```
90+
91+
## Further Reading
92+
93+
- [Comprehensive signer config reference](../sample/conf/signer/mainnet-signer-conf.toml)
94+
- [Comprehensive miner config reference](../sample/conf/mainnet-miner-conf.toml)
95+
- [Mining documentation](mining.md)
96+
- [Follower documentation](follower.md)

‎sample/conf/mainnet-follower-conf.toml‎

Lines changed: 44 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,61 @@
1+
# ============================================================
2+
# STACKS FOLLOWER NODE - MAINNET CONFIGURATION
3+
# ============================================================
4+
#
5+
# A follower is a read-only node that syncs the Stacks chain without
6+
# mining or signing. Use this to run an API node, monitor the chain,
7+
# or serve RPC requests.
8+
#
9+
# For mining, see mainnet-miner-conf.toml.
10+
# For signing, see signer/mainnet-signer-conf.toml + mainnet-signer.toml.
11+
112
[node]
2-
# working_dir = "/dir/to/save/chainstate" # defaults to: /tmp/stacks-node-[0-9]*
13+
# IMPORTANT: For production, set this to a persistent path.
14+
# The default (/tmp/stacks-node-<timestamp>) is lost on reboot.
15+
# working_dir = "/stacks-data/mainnet"
16+
317
rpc_bind = "0.0.0.0:20443"
418
p2p_bind = "0.0.0.0:20444"
5-
prometheus_bind = "0.0.0.0:9153"
19+
prometheus_bind = "0.0.0.0:9153"
20+
21+
# Explicitly not a miner or signer.
22+
miner = false
23+
stacker = false
24+
25+
# Mainnet bootstrap nodes (4 seeds) are auto-populated when mode = "mainnet".
26+
# Only override if you need custom seeds (replaces all 4 defaults):
27+
# bootstrap_node = "02196f005965cebe6ddc3901b7b1cc1aa7a88f305bb8c5893456b8f9a605923893@seed.mainnet.hiro.so:20444"
28+
29+
# Enable transaction indexing for API queries.
30+
# Required if running stacks-blockchain-api.
31+
# Default: false
32+
# txindex = true
633

734
[burnchain]
835
mode = "mainnet"
936
peer_host = "127.0.0.1"
37+
# rpc_port = 8332 # Bitcoin mainnet RPC (default)
38+
# peer_port = 8333 # Bitcoin mainnet P2P (default)
39+
40+
# Bitcoin RPC credentials (required by most bitcoind instances).
41+
# username = "your-bitcoin-rpc-user"
42+
# password = "your-bitcoin-rpc-password"
1043

11-
# Used for sending events to a local stacks-blockchain-api service
44+
# Optional: stacks-blockchain-api event observer.
1245
# [[events_observer]]
1346
# endpoint = "localhost:3700"
1447
# events_keys = ["*"]
1548
# timeout_ms = 60_000
1649

17-
# Used if running a local stacks-signer service
50+
# To upgrade this node to also serve a signer, you need:
51+
# 1. Set stacker = true in [node]
52+
# 2. Uncomment the signer events_observer below
53+
# 3. Uncomment the [connection_options] auth_token below
54+
# 4. See mainnet-signer.toml for the full signer node config
55+
#
1856
# [[events_observer]]
1957
# endpoint = "127.0.0.1:30000"
2058
# events_keys = ["stackerdb", "block_proposal", "burn_blocks"]
21-
22-
# Used if running a local stacks-signer service
59+
#
2360
# [connection_options]
24-
# auth_token = "" # fill with a unique password
61+
# auth_token = "your-secret-token"

0 commit comments

Comments
 (0)