Merge pull request #6000 from Jiloc/chore/document-node-config

chore: document NodeConfig parameters

Author: Jiloc

stackslib/src/config/mod.rs

@@ -1972,52 +1972,230 @@ impl BurnchainConfigFile {
 
 #[derive(Clone, Debug)]
 pub struct NodeConfig {
+    /// Human-readable name for the node. Primarily used for identification in testing environments
+    /// (e.g., deriving log file names, temporary directory names).
+    ///
+    /// Default: `"helium-node"`
     pub name: String,
+    /// The node's Bitcoin wallet private key, provided as a hex string in the config file.
+    /// Used to initialize the node's keychain for signing operations.
+    /// If `miner.mining_key` is not set, this seed may also be used for mining-related signing.
+    /// Required if [`NodeConfig::miner`] is `true` and [`MinerConfig::mining_key`] is absent.
+    ///
+    /// Default: Randomly generated 32 bytes.
     pub seed: Vec<u8>,
+    /// The file system absolute path to the node's working directory.
+    /// All persistent data, including chainstate, burnchain databases, and potentially other stores,
+    /// will be located within this directory.
+    /// This path can be overridden by setting the `STACKS_WORKING_DIR` environment variable.
+    /// Note: For persistent mainnet or testnet nodes, this path must be explicitly
+    /// configured to a non-temporary location in the configuration file.
+    ///
+    /// Default: `/tmp/stacks-node-{current_timestamp}`.
     pub working_dir: String,
+    /// The IPv4 address and port (e.g., "0.0.0.0:20443") on which the node's HTTP RPC server
+    /// should bind and listen for incoming API requests.
+    ///
+    /// Default: `"0.0.0.0:20443"`
     pub rpc_bind: String,
+    /// The IPv4 address and port (e.g., "0.0.0.0:20444") on which the node's P2P networking
+    /// service should bind and listen for incoming connections from other peers.
+    ///
+    /// Default: `"0.0.0.0:20444"`
     pub p2p_bind: String,
+    /// The publicly accessible URL that this node advertises to peers during the P2P handshake
+    /// as its HTTP RPC endpoint. Other nodes or services might use this URL to query the node's API.
+    ///
+    /// Default: `http://{rpc_bind}` (e.g., "http://0.0.0.0:20443" if rpc_bind is default).
     pub data_url: String,
+    /// The publicly accessible IPv4 address and port that this node advertises to peers for P2P connections.
+    /// This might differ from `p2p_bind` if the node is behind NAT or a proxy.
+    /// Note: The default value derivation might be unexpected, potentially using the `rpc_bind` address; explicit configuration is recommended if needed.
+    ///
+    /// Default: Derived from `rpc_bind` (e.g., "0.0.0.0:20443" if rpc_bind is default).
     pub p2p_address: String,
+    /// The private key seed, provided as a hex string in the config file, used specifically for the
+    /// node's identity and message signing within the P2P networking layer.
+    /// This is separate from the main [`NodeConfig::seed`].
+    ///
+    /// Default: Randomly generated 32 bytes.
     pub local_peer_seed: Vec<u8>,
+    /// A list of initial peer nodes used to bootstrap connections into the Stacks P2P network.
+    /// Peers are specified in a configuration file as comma-separated strings in the
+    /// format `"PUBKEY@IP:PORT"` or `"PUBKEY@HOSTNAME:PORT"`. DNS hostnames are resolved
+    /// during configuration loading.
+    ///
+    /// Default: Empty vector `[]`.
     pub bootstrap_node: Vec<Neighbor>,
+    /// A list of peer addresses that this node should explicitly deny connections from.
+    /// Peers are specified as comma-separated strings in the format "IP:PORT" or "HOSTNAME:PORT"
+    /// in the configuration file. DNS hostnames are resolved during configuration loading.
+    ///
+    /// Default: Empty vector `[]`.
     pub deny_nodes: Vec<Neighbor>,
+    /// Flag indicating whether this node should activate its mining logic and attempt to produce Stacks blocks.
+    /// Setting this to `true` typically requires providing necessary private keys (either [`NodeConfig::seed`] or [`MinerConfig::mining_key`]).
+    /// It also influences default behavior for settings like [`NodeConfig::require_affirmed_anchor_blocks`].
+    ///
+    /// Default: `false`
     pub miner: bool,
+    /// Setting this to `true` enables the node to replicate the miner and signer Stacker DBs
+    /// required for signing, and is required if the node is connected to a signer.
+    ///
+    /// Default: `false`
     pub stacker: bool,
+    /// Enables a simulated mining mode, primarily for local testing and development.
+    /// When `true`, the node may generate blocks locally without participating in the
+    /// real bitcoin consensus or P2P block production process.
+    ///
+    /// Only relevant if [`NodeConfig::miner`] is `true`.
+    ///
+    /// Default: `false`
     pub mock_mining: bool,
-    /// Where to output blocks from mock mining
+    /// If [`NodeConfig::mock_mining`] is enabled, this specifies an optional directory path where the
+    /// generated mock Stacks blocks will be saved. (pre-Nakamoto)
+    /// The path is canonicalized on load.
+    ///
+    /// Default: `None`
+    /// Deprecated: This setting was only used in the neon node and is ignored in Epoch 3.0+.
     pub mock_mining_output_dir: Option<PathBuf>,
+    /// Enable microblock mining.
+    ///
+    /// Default: `true`
+    /// Deprecated: This setting is ignored in Epoch 2.5+.
     pub mine_microblocks: bool,
+    /// How often to attempt producing microblocks, in milliseconds.
+    /// Only applies when [`NodeConfig::mine_microblocks`] is true and before Epoch 2.5.
+    ///
+    /// Default: `30_000` ms (30 seconds)
+    /// Deprecated: This setting is ignored in Epoch 2.5+.
     pub microblock_frequency: u64,
+    /// The maximum number of microblocks allowed per Stacks block.
+    ///
+    /// Default: `65535` (u16::MAX)
+    /// Deprecated: This setting is ignored in Epoch 2.5+.
     pub max_microblocks: u64,
+    /// Cooldown period after a microblock is produced, in milliseconds.
+    /// Only applies when [`NodeConfig::mine_microblocks`] is true and before Epoch 2.5.
+    ///
+    /// Default: `30_000` ms (30 seconds)
+    /// Deprecated: This setting is ignored in Epoch 2.5+.
     pub wait_time_for_microblocks: u64,
+    /// When operating as a miner, this specifies the maximum time (in milliseconds)
+    /// the node waits after detecting a new burnchain block to synchronize corresponding
+    /// Stacks block data from the network before resuming mining attempts.
+    /// If synchronization doesn't complete within this duration, mining resumes anyway
+    /// to prevent stalling. This setting is loaded by all nodes but primarily affects
+    /// miner behavior within the relayer thread.
+    ///
+    /// Default: `30_000` ms (30 seconds)
     pub wait_time_for_blocks: u64,
-    /// Controls how frequently, in milliseconds, the nakamoto miner's relay thread acts on its own initiative
-    /// (as opposed to responding to an event from the networking thread, etc.). This is roughly
-    /// how frequently the miner checks if a new burnchain block has been processed.
+    /// Controls how frequently, in milliseconds, the Nakamoto miner's relay thread polls for work
+    /// or takes periodic actions when idle (e.g., checking for new burnchain blocks).
+    /// Default value of 10 seconds is reasonable in mainnet (where bitcoin blocks are ~10 minutes)
+    /// A lower value might be useful in other environments with faster burn blocks.
     ///
-    /// Default value of 10 seconds is reasonable in mainnet (where bitcoin blocks are ~10 minutes),
-    /// but environments where burn blocks are more frequent may want to decrease this value.
+    /// Default: `10_000` ms (10 seconds)
     pub next_initiative_delay: u64,
+    /// Optional network address and port (e.g., "127.0.0.1:9153") for binding the Prometheus metrics server.
+    /// If set, the node will start an HTTP server on this address to expose internal metrics
+    /// for scraping by a Prometheus instance.
+    ///
+    /// Default: `None` (Prometheus server disabled).
     pub prometheus_bind: Option<String>,
+    /// The strategy to use for MARF trie node caching in memory.
+    /// Controls the trade-off between memory usage and performance for state access.
+    ///
+    /// Possible values:
+    /// - `"noop"`: No caching (least memory).
+    /// - `"everything"`: Cache all nodes (most memory, potentially fastest).
+    /// - `"node256"`: Cache only larger `TrieNode256` nodes.
+    ///
+    /// If the value is `None` or an unrecognized string, it defaults to `"noop"`.
+    ///
+    /// Default: `None` (effectively `"noop"`).
     pub marf_cache_strategy: Option<String>,
+    /// Controls the timing of hash calculations for MARF trie nodes.
+    /// - If `true`, hashes are calculated only when the MARF is flushed to disk (deferred hashing).
+    /// - If `false`, hashes are calculated immediately as leaf nodes are inserted or updated (immediate hashing).
+    /// Deferred hashing might improve write performance.
+    ///
+    /// Default: `true`
     pub marf_defer_hashing: bool,
+    /// Sampling interval in seconds for the PoX synchronization watchdog thread (pre-Nakamoto).
+    /// Determines how often the watchdog checked PoX state consistency in the Neon run loop.
+    ///
+    /// Default: `30` seconds
+    /// Deprecated: Unused after the Nakamoto upgrade. This setting is ignored in Epoch 3.0+.
     pub pox_sync_sample_secs: u64,
+    /// If set to `true`, the node initializes its state using an alternative test genesis block definition,
+    /// loading different initial balances, names, and lockups than the standard network genesis.
+    /// This is intended strictly for testing purposes and is disallowed on mainnet.
+    ///
+    /// Default: `None` (uses standard network genesis).
     pub use_test_genesis_chainstate: Option<bool>,
+    /// Controls if Stacks Epoch 2.1+ affirmation map logic should be applied even before Epoch 2.1.
+    /// - If `true` (default), the node consistently uses the newer (Epoch 2.1) rules for PoX anchor block
+    ///   validation and affirmation-based reorg handling, even in earlier epochs.
+    /// - If `false`, the node strictly follows the rules defined for the specific epoch it is currently
+    ///   processing, only applying 2.1+ logic from Epoch 2.1 onwards.
+    /// Differences in this setting between nodes prior to Epoch 2.1 could lead to consensus forks.
+    ///
+    /// Default: `true`
     pub always_use_affirmation_maps: bool,
+    /// Controls if the node must wait for locally missing but burnchain-affirmed PoX anchor blocks.
+    /// If an anchor block is confirmed by the affirmation map but not yet processed by this node:
+    /// - If `true`: Burnchain processing halts until the affirmed block is acquired. Ensures strict
+    ///   adherence to the affirmed canonical chain, typical for followers.
+    /// - If `false`: Burnchain processing continues without waiting. Allows miners to operate optimistically
+    ///   but may necessitate unwinding later if the affirmed block alters the chain state.
+    ///
+    /// Default: `true` for followers, `false` for miners (when not explicitly configured).
     pub require_affirmed_anchor_blocks: bool,
+    /// Controls if the node must strictly wait for any PoX anchor block selected by the core consensus mechanism.
+    /// - If `true`: Halts burnchain processing immediately whenever a selected anchor block is missing locally
+    ///   (`SelectedAndUnknown` status), regardless of affirmation status. This is always true in Nakamoto (Epoch 3.0+)
+    /// and runs *before* affirmation checks.
+    /// - If `false` (primarily for testing): Skips this immediate halt, allowing processing to proceed to
+    ///   affirmation map checks.
+    /// Normal operation requires this to be `true`; setting to `false` will likely break consensus adherence.
+    /// This parameter cannot be set via the configuration file; it must be modified programmatically.
+    ///
+    /// Default: `true`
     pub assume_present_anchor_blocks: bool,
-    /// Fault injection for failing to push blocks
+    /// Fault injection setting for testing purposes. If set to `Some(p)`, where `p` is between 0 and 100,
+    /// the node will have a `p` percent chance of intentionally *not* pushing a newly processed block
+    /// to its peers.
+    ///
+    /// Default: `None` (no fault injection).
     pub fault_injection_block_push_fail_probability: Option<u8>,
-    // fault injection for hiding blocks.
-    // not part of the config file.
+    /// Fault injection setting for testing purposes. If `true`, the node's chainstate database
+    /// access layer may intentionally fail to retrieve block data, even if it exists,
+    /// simulating block hiding or data unavailability.
+    /// This parameter cannot be set via the configuration file; it must be modified programmatically.
+    ///
+    /// Default: `false`
     pub fault_injection_hide_blocks: bool,
-    /// At most, how often should the chain-liveness thread
-    ///  wake up the chains-coordinator. Defaults to 300s (5 min).
+    /// The polling interval, in seconds, for the background thread that monitors chain liveness.
+    /// This thread periodically wakes up the main coordinator to check for chain progress or
+    /// other conditions requiring action.
+    ///
+    /// Default: `300` seconds (5 minutes)
     pub chain_liveness_poll_time_secs: u64,
-    /// stacker DBs we replicate
+    /// A list of specific StackerDB contracts (identified by their qualified contract identifiers,
+    /// e.g., "SP000000000000000000002Q6VF78.pox-3") that this node should actively replicate.
+    ///
+    /// Default: The initial list depends on the [`NodeConfig::miner`] and [`NodeConfig::stacker`] settings:
+    /// - If `miner = true` or `stacker = true`: Relevant system contracts (like `.miners`
+    ///   and `.signers-*`) are automatically added during configuration loading, in addition
+    ///   to any contracts specified in the configuration file.
+    /// - If `miner = false` and `stacker = false`: Empty vector `[]`.
     pub stacker_dbs: Vec<QualifiedContractIdentifier>,
-    /// enable transactions indexing
+    /// Enables the transaction index, which maps transaction IDs to the blocks containing them.
+    /// Setting this to `true` allows the use of RPC endpoints that look up transactions by ID
+    /// (e.g., `/extended/v1/tx/{txid}`), but requires substantial additional disk space for the index database.
+    ///
+    /// Default: `false`
     pub txindex: bool,
 }