From e84fb4e0d7d4cf6d0f857c570f88e7d51607b56e Mon Sep 17 00:00:00 2001 From: Francesco Leacche Date: Tue, 3 Jun 2025 15:26:25 +0100 Subject: [PATCH 1/8] Enhance documentation for config structs for easier parsing --- stackslib/src/config/mod.rs | 1448 +++++++++++++++++++---------------- 1 file changed, 778 insertions(+), 670 deletions(-) diff --git a/stackslib/src/config/mod.rs b/stackslib/src/config/mod.rs index 141fcd72db..97d974cab2 100644 --- a/stackslib/src/config/mod.rs +++ b/stackslib/src/config/mod.rs @@ -1236,115 +1236,121 @@ impl std::default::Default for Config { #[derive(Clone, Debug, Default, Deserialize, PartialEq)] pub struct BurnchainConfig { /// The underlying blockchain used for Proof-of-Transfer. - /// Currently, only `"bitcoin"` is supported. - /// - /// Default: `"bitcoin"` + /// --- + /// @default: `"bitcoin"` + /// @notes: + /// - Currently, only `"bitcoin"` is supported. pub chain: String, /// The operational mode or network profile for the Stacks node. /// This setting determines network parameters (like chain ID, peer version), /// default configurations, genesis block definitions, and overall node behavior. /// /// Supported values: - /// ```text - /// | Mode | Network Type | - /// |-----------------|--------------| - /// | "mainnet" | mainnet | - /// | "xenon" | testnet | - /// | "mocknet" | regtest | - /// | "helium" | regtest | - /// | "neon" | regtest | - /// | "argon" | regtest | - /// | "krypton" | regtest | - /// | "nakamoto-neon" | regtest | - /// ``` - /// - /// Default: `"mocknet"` + /// - `"mainnet"` → mainnet + /// - `"xenon"` → testnet + /// - `"mocknet"` → regtest + /// - `"helium"` → regtest + /// - `"neon"` → regtest + /// - `"argon"` → regtest + /// - `"krypton"` → regtest + /// - `"nakamoto-neon"` → regtest + /// --- + /// @default: `"mocknet"` pub mode: String, /// The network-specific identifier used in P2P communication and database initialization. - /// Derived from `mode` during config load, unless explicitly overridden (for test purposes). - /// - /// **Warning:** Do not modify this unless you really know what you're doing. - /// This is intended strictly for testing purposes. - /// - /// Default: Derived from [`BurnchainConfig::mode`] ([`CHAIN_ID_MAINNET`] for `mainnet`, [`CHAIN_ID_TESTNET`] otherwise). + /// --- + /// @default: + /// - [`CHAIN_ID_MAINNET`] if [`BurnchainConfig::mode`] is `"mainnet"` + /// - [`CHAIN_ID_TESTNET`] otherwise + /// @notes: + /// - **Warning:** Do not modify this unless you really know what you're doing. + /// - This is intended strictly for testing purposes. pub chain_id: u32, /// The peer protocol version number used in P2P communication. /// This parameter cannot be set via the configuration file. - /// - /// **Warning:** Do not modify this unless you really know what you're doing. - /// - /// Default: Derived from [`BurnchainConfig::mode`] ([`PEER_VERSION_MAINNET`] for `mainnet`, [`PEER_VERSION_TESTNET`] otherwise). + /// --- + /// @default: + /// - [`PEER_VERSION_MAINNET`] if [`BurnchainConfig::mode`] is `"mainnet"` + /// - [`PEER_VERSION_TESTNET`] otherwise + /// @notes: + /// - **Warning:** Do not modify this unless you really know what you're doing. pub peer_version: u32, /// Specifies a mandatory wait period (in milliseconds) after receiving a burnchain tip /// before the node attempts to build the anchored block for the new tenure. /// This duration effectively schedules the start of the block-building /// process relative to the tip's arrival time. - /// - /// This is intended strictly for testing purposes. - /// - /// Default: `5000` milliseconds. - /// `10000` milliseconds when launched with the `helium` or `mocknet` subcommands. + /// --- + /// @default: `5_000` (milliseconds) + /// @notes: + /// - This is intended strictly for testing purposes. + /// - Units: milliseconds. pub commit_anchor_block_within: u64, /// The maximum amount (in sats) of "burn commitment" to broadcast for the next block's leader election. /// Acts as a safety cap to limit the maximum amount spent on mining. /// It serves as both the target fee and a fallback if dynamic fee calculations fail or cannot be performed. /// /// This setting can be hot-reloaded from the config file, allowing adjustment without restarting. - /// - /// Only relevant if [`NodeConfig::miner`] is `true`. - /// - /// Default: `20000` satoshis + /// --- + /// @default: `20_000` (satoshis) + /// @notes: + /// - Only relevant if [`NodeConfig::miner`] is `true`. + /// - Units: satoshis. pub burn_fee_cap: u64, /// The hostname or IP address of the bitcoin node peer. /// /// This field is required for all node configurations as it specifies where to find the underlying /// bitcoin node to interact with for PoX operations, block validation, and mining. - /// - /// Default: `"0.0.0.0"` + /// --- + /// @default: `"0.0.0.0"` pub peer_host: String, /// The P2P network port of the bitcoin node specified by [`BurnchainConfig::peer_host`]. - /// - /// Default: `8333` + /// --- + /// @default: `8333` pub peer_port: u16, /// The RPC port of the bitcoin node specified by [`BurnchainConfig::peer_host`]. - /// - /// Default: `8332` + /// --- + /// @default: `8332` pub rpc_port: u16, /// Flag indicating whether to use SSL/TLS when connecting to the bitcoin node's RPC interface. - /// - /// Default: `false` + /// --- + /// @default: `false` pub rpc_ssl: bool, /// The username for authenticating with the bitcoin node's RPC interface. /// Required if the bitcoin node requires RPC authentication. - /// - /// Only relevant if [`NodeConfig::miner`] is `true`. - /// - /// Default: `None` + /// --- + /// @default: `None` + /// @notes: + /// - Only relevant if [`NodeConfig::miner`] is `true`. pub username: Option, /// The password for authenticating with the bitcoin node's RPC interface. /// Required if the bitcoin node requires RPC authentication. - /// - /// Only relevant if [`NodeConfig::miner`] is `true`. - /// - /// Default: `None` + /// --- + /// @default: `None` + /// @notes: + /// - Only relevant if [`NodeConfig::miner`] is `true`. pub password: Option, /// Timeout duration, in seconds, for RPC calls made to the bitcoin node. /// Configures the timeout on the underlying HTTP client. - /// - /// Default: `60` seconds + /// --- + /// @default: `60` (seconds) + /// @notes: + /// - Units: seconds pub timeout: u32, - /// The network "magic bytes" used to identify packets for the specific bitcoin network instance - /// (e.g., mainnet, testnet, regtest). Must match the magic bytes of the connected bitcoin node. + /// The network "magic bytes" used to identify packets for the specific bitcoin network + /// instance (e.g., mainnet, testnet, regtest). Must match the magic bytes of the connected + /// bitcoin node. /// - /// These two-byte identifiers help ensure that nodes only connect to peers on the same network type. - /// Common values include: + /// These two-byte identifiers help ensure that nodes only connect to peers on the same + /// network type. Common values include: /// - "X2" for mainnet /// - "T2" for testnet (xenon) /// - Other values for specific test networks /// /// Configured as a 2-character ASCII string (e.g., "X2" for mainnet). - /// - /// Default: [`BLOCKSTACK_MAGIC_MAINNET`] (corresponds to "X2") unless overridden by [`BurnchainConfig::mode`] (e.g., "T2" for testnet (xenon)). + /// --- + /// @default: + /// - `"T2"` if [`BurnchainConfig::mode`] is `"xenon"` + /// - `"X2"` otherwise pub magic_bytes: MagicBytes, /// The public key associated with the local mining address for the underlying Bitcoin regtest node. /// Provided as a hex string representing an uncompressed public key. @@ -1355,106 +1361,104 @@ pub struct BurnchainConfig { /// /// The key is used to derive the Bitcoin address that receives the coinbase rewards /// when generating blocks on the regtest network. - /// - /// Mandatory if [`BurnchainConfig::mode`] is "helium". - /// This is intended strictly for testing purposes. - /// - /// Default: `None` + /// --- + /// @default: `None` + /// @notes: + /// - Mandatory if [`BurnchainConfig::mode`] is "helium". + /// - This is intended strictly for testing purposes. pub local_mining_public_key: Option, /// Optional bitcoin block height at which the Stacks node process should gracefully exit. /// When bitcoin reaches this height, the node logs a message and initiates a graceful shutdown. - /// - /// Applied only if [`BurnchainConfig::mode`] is not "mainnet". - /// This is intended strictly for testing purposes. - /// - /// Default: `None` + /// --- + /// @default: `None` + /// @notes: + /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". + /// - This is intended strictly for testing purposes. pub process_exit_at_block_height: Option, /// The interval, in seconds, at which the node polls the bitcoin node for new blocks and state updates. /// /// The default value of 10 seconds is mainly intended for testing purposes. /// It's suggested to set this to a higher value for mainnet, e.g., 300 seconds (5 minutes). - /// - /// Default: `10` seconds + /// --- + /// @default: `10` (seconds) + /// @notes: + /// - Units: seconds pub poll_time_secs: u64, /// The default fee rate in satoshis per virtual byte (sats/vB) to use when estimating fees for miners /// to submit bitcoin transactions (like block commits or leader key registrations). - /// - /// Only relevant if [`NodeConfig::miner`] is `true`. - /// - /// Default: [`DEFAULT_SATS_PER_VB`] (currently 50 satoshis per virtual byte) + /// --- + /// @default: [`DEFAULT_SATS_PER_VB`] (satoshis per virtual byte) + /// @notes: + /// - Only relevant if [`NodeConfig::miner`] is `true`. + /// - Units: satoshis per virtual byte. pub satoshis_per_byte: u64, /// Maximum fee rate multiplier allowed when using Replace-By-Fee (RBF) for bitcoin transactions. /// Expressed as a percentage of the original [`BurnchainConfig::satoshis_per_byte`] rate (e.g., /// 150 means the fee rate can be increased up to 1.5x). Used in mining logic for RBF decisions /// to cap the replacement fee rate. - /// - /// Only relevant if [`NodeConfig::miner`] is `true`. - /// - /// Default: [`DEFAULT_MAX_RBF_RATE`] (currently 150, i.e., 1.5x) + /// --- + /// @default: [`DEFAULT_MAX_RBF_RATE`] (%) + /// @notes: + /// - Only relevant if [`NodeConfig::miner`] is `true`. pub max_rbf: u64, /// Estimated size (in virtual bytes) of a leader key registration transaction on bitcoin. - /// Used for fee calculation in mining logic by multiplying with the fee rate [`BurnchainConfig::satoshis_per_byte`]. - /// - /// Only relevant if [`NodeConfig::miner`] is `true`. - /// - /// Default: [`OP_TX_LEADER_KEY_ESTIM_SIZE`] (currently 290) + /// Used for fee calculation in mining logic by multiplying with the fee rate + /// [`BurnchainConfig::satoshis_per_byte`]. + /// --- + /// @default: [`OP_TX_LEADER_KEY_ESTIM_SIZE`] (virtual bytes) + /// @notes: + /// - Only relevant if [`NodeConfig::miner`] is `true`. + /// - Units: virtual bytes. pub leader_key_tx_estimated_size: u64, /// Estimated size (in virtual bytes) of a block commit transaction on bitcoin. - /// Used for fee calculation in mining logic by multiplying with the fee rate [`BurnchainConfig::satoshis_per_byte`]. - /// - /// Only relevant if [`NodeConfig::miner`] is `true`. - /// - /// Default: [`OP_TX_BLOCK_COMMIT_ESTIM_SIZE`] (currently 380) + /// Used for fee calculation in mining logic by multiplying with the fee rate + /// [`BurnchainConfig::satoshis_per_byte`]. + /// --- + /// @default: [`OP_TX_BLOCK_COMMIT_ESTIM_SIZE`] (virtual bytes) + /// @notes: + /// - Only relevant if [`NodeConfig::miner`] is `true`. + /// - Units: virtual bytes. pub block_commit_tx_estimated_size: u64, /// The incremental amount (in Sats/vByte) to add to the previous transaction's /// fee rate for RBF bitcoin transactions. - /// - /// Only relevant if [`NodeConfig::miner`] is `true`. - /// - /// Default: [`DEFAULT_RBF_FEE_RATE_INCREMENT`] (currently 5 satoshis per virtual byte) + /// --- + /// @default: [`DEFAULT_RBF_FEE_RATE_INCREMENT`] (satoshis per virtual byte) + /// @notes: + /// - Only relevant if [`NodeConfig::miner`] is `true`. + /// - Units: satoshis per virtual byte. pub rbf_fee_increment: u64, /// Overrides the default starting bitcoin block height for the node. /// Allows starting synchronization from a specific historical point in test environments. - /// Should be used together with [`BurnchainConfig::first_burn_block_timestamp`] and [`BurnchainConfig::first_burn_block_hash`] for proper operation. - /// - /// Applied only if [`BurnchainConfig::mode`] is not "mainnet". - /// This is intended strictly for testing purposes. - /// - /// Default: `None` (uses the burnchain's default starting height for the mode). + /// --- + /// @default: `None` (uses the burnchain's default starting height for the mode) + /// @notes: + /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". + /// - This is intended strictly for testing purposes. + /// - Should be used together with [`BurnchainConfig::first_burn_block_timestamp`] and + /// [`BurnchainConfig::first_burn_block_hash`] for proper operation. pub first_burn_block_height: Option, /// Overrides the default starting block timestamp of the burnchain. - /// Should be used together with [`BurnchainConfig::first_burn_block_height`] and [`BurnchainConfig::first_burn_block_hash`] for proper operation. - /// - /// Applied only if [`BurnchainConfig::mode`] is not "mainnet". - /// This is intended strictly for testing purposes. - /// - /// Default: `None` (uses the burnchain's default starting timestamp). + /// --- + /// @default: `None` (uses the burnchain's default starting timestamp) + /// @notes: + /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". + /// - This is intended strictly for testing purposes. + /// - Should be used together with [`BurnchainConfig::first_burn_block_height`] and + /// [`BurnchainConfig::first_burn_block_hash`] for proper operation. pub first_burn_block_timestamp: Option, /// Overrides the default starting block hash of the burnchain. - /// Should be used together with [`BurnchainConfig::first_burn_block_timestamp`] and [`BurnchainConfig::first_burn_block_height`] for proper operation. - /// - /// Applied only if [`BurnchainConfig::mode`] is not "mainnet". - /// This is intended strictly for testing purposes. - /// - /// Default: `None` (uses the burnchain's default starting block hash). + /// --- + /// @default: `None` (uses the burnchain's default starting block hash) + /// @notes: + /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". + /// - This is intended strictly for testing purposes. + /// - Should be used together with [`BurnchainConfig::first_burn_block_height`] and + /// [`BurnchainConfig::first_burn_block_timestamp`] for proper operation. pub first_burn_block_hash: Option, /// Custom override for the definitions of Stacks epochs (start/end burnchain heights, consensus rules). /// This setting allows testing specific epoch transitions or custom consensus rules by defining exactly /// when each epoch starts on bitcoin. /// - /// **Configuration:** - /// Configured as a list `[[burnchain.epochs]]` in TOML, each with: - /// - `epoch_name`: A string identifying the epoch (e.g., `"1.0"`, `"2.05"`, `"3.1"`). - /// - `start_height`: The Bitcoin block height at which this epoch becomes active. - /// - /// Example TOML entry: - /// ```toml - /// [[burnchain.epochs]] - /// epoch_name = "2.1" - /// start_height = 150 - /// ``` - /// - /// **Details:** /// Epochs define distinct protocol rule sets (consensus rules, execution costs, capabilities). /// When configured, the list must include all epochs sequentially from "1.0" up to the /// highest desired epoch, without skipping any intermediate ones. @@ -1466,11 +1470,21 @@ pub struct BurnchainConfig { /// - `start_height` values must be non-decreasing across the list. /// - Epoch `"1.0"` must have `start_height = 0`. /// - The number of defined epochs cannot exceed the maximum supported by the node software. - /// - /// Applied only if [`BurnchainConfig::mode`] is not "mainnet". - /// This is intended strictly for testing purposes. - /// - /// Default: `None` (uses the standard epoch definitions for the selected `mode`). + /// --- + /// @default: `None` (uses the standard epoch definitions for the selected [`BurnchainConfig::mode`]) + /// @notes: + /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". + /// - This is intended strictly for testing purposes. + /// - Configured as a list `[[burnchain.epochs]]` in TOML, each with `epoch_name` (string) + /// and `start_height` (integer Bitcoin block height). + /// @toml_example: | + /// [[burnchain.epochs]] + /// epoch_name = "2.1" + /// start_height = 150 + /// + /// [[burnchain.epochs]] + /// epoch_name = "2.2" + /// start_height = 200 pub epochs: Option>, /// Sets a custom burnchain height for PoX-2 activation (for testing). /// @@ -1479,102 +1493,101 @@ pub struct BurnchainConfig { /// 2. The block height from which PoX reward set calculations switch to PoX v2 rules. /// /// **Behavior:** - /// - This value directly sets the auto unlock height for PoX v1 lockups before transition to PoX v2. This - /// also defines the burn height at which PoX reward sets are calculated using PoX v2 rather than v1. + /// - This value directly sets the auto unlock height for PoX v1 lockups before transition to PoX v2. + /// This also defines the burn height at which PoX reward sets are calculated using PoX v2 rather than v1. /// - If custom [`BurnchainConfig::epochs`] are provided: /// - This value is used to validate that Epoch 2.1's start height is ≤ this value. /// - However, the height specified in `epochs` for Epoch 2.1 takes precedence. - /// - /// Applied only if [`BurnchainConfig::mode`] is not "mainnet". - /// This is intended strictly for testing purposes. - /// - /// Default: `None`. + /// --- + /// @default: `None` + /// @notes: + /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". + /// - This is intended strictly for testing purposes. pub pox_2_activation: Option, /// Overrides the length (in bitcoin blocks) of the PoX reward cycle. - /// - /// Applied only if [`BurnchainConfig::mode`] is not "mainnet". - /// This is intended strictly for testing purposes. - /// - /// Default: `None` (uses the standard reward cycle length for the mode). + /// --- + /// @default: `None` (uses the standard reward cycle length for the mode) + /// @notes: + /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". + /// - This is intended strictly for testing purposes. + /// - Units: bitcoin blocks. pub pox_reward_length: Option, /// Overrides the length (in bitcoin blocks) of the PoX prepare phase. - /// - /// Applied only if [`BurnchainConfig::mode`] is not "mainnet". - /// This is intended strictly for testing purposes. - /// - /// Default: `None` (uses the standard prepare phase length for the mode). + /// --- + /// @default: `None` (uses the standard prepare phase length for the mode) + /// @notes: + /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". + /// - This is intended strictly for testing purposes. + /// - Units: bitcoin blocks. pub pox_prepare_length: Option, /// Overrides the bitcoin height at which the PoX sunset period begins in epochs before 2.1. /// The sunset period represents a planned phase-out of the PoX mechanism. During this period, /// stacking rewards gradually decrease, eventually ceasing entirely. This parameter allows /// testing the PoX sunset transition by explicitly setting its start height. - /// - /// Applied only if [`BurnchainConfig::mode`] is not "mainnet". - /// This is intended strictly for testing purposes. - /// - /// Default: `None` (uses the standard sunset start height for the mode). - /// Deprecated: The sunset phase was removed in Epoch 2.1. This parameter can still be used for testing purposes for epochs before 2.1. + /// --- + /// @default: `None` (uses the standard sunset start height for the mode) + /// @deprecated: The sunset phase was removed in Epoch 2.1. This parameter can still be used for + /// testing purposes for epochs before 2.1. + /// @notes: + /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". + /// - This is intended strictly for testing purposes. pub sunset_start: Option, - /// /// Overrides the bitcoin height, non-inclusive, at which the PoX sunset period ends in epochs before 2.1. /// After this height, Stacking rewards are disabled completely. This parameter works together /// with `sunset_start` to define the full sunset transition period for PoX. - /// - /// Applied only if [`BurnchainConfig::mode`] is not "mainnet". - /// This is intended strictly for testing purposes. - /// - /// Default: `None` (uses the standard sunset end height for the mode). - /// Deprecated: The sunset phase was removed in Epoch 2.1. This parameter can still be used for testing purposes for epochs before 2.1. + /// --- + /// @default: `None` (uses the standard sunset end height for the mode) + /// @deprecated: The sunset phase was removed in Epoch 2.1. This parameter can still be used for + /// testing purposes for epochs before 2.1. + /// @notes: + /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". + /// - This is intended strictly for testing purposes. pub sunset_end: Option, /// Specifies the name of the Bitcoin wallet to use within the connected bitcoin node. /// Used to interact with a specific named wallet if the bitcoin node manages multiple wallets. /// - /// If the specified wallet doesn't exist, the node will attempt to create it via the createwallet RPC call. - /// This is particularly useful for miners who need to manage separate wallets. - /// - /// Primarily relevant for miners interacting with multi-wallet Bitcoin nodes. - /// - /// Default: `""` (empty string, implying the default wallet or no specific wallet needed). + /// If the specified wallet doesn't exist, the node will attempt to create it via the + /// `createwallet` RPC call. This is particularly useful for miners who need to manage + /// separate wallets. + /// --- + /// @default: `""` (empty string, implying the default wallet or no specific wallet needed) + /// @notes: + /// - Primarily relevant for miners interacting with multi-wallet Bitcoin nodes. pub wallet_name: String, /// Override for the burnchain height activating stricter AST size checks pre-epoch 3.0 for testing purposes. /// /// Used pre-epoch 3.0 to control activation before it became standard (at burn height `752000`). - /// Ignored in standard production builds as the underlying mechanism is disabled unless the `testing` feature is active. - /// - /// Default: `None`. - /// Deprecated: This setting is ignored in Epoch 3.0+. + /// Ignored in standard production builds as the underlying mechanism is disabled unless the `testing` + /// feature is active. + /// --- + /// @default: `None` + /// @deprecated: This setting is ignored in Epoch 3.0+. pub ast_precheck_size_height: Option, /// Overrides for the burnchain block affirmation map for specific reward cycles. /// Allows manually setting the miner affirmation ('p'resent/'n'ot-present/'a'bsent) map for a /// given cycle, bypassing the map normally derived from sortition results. /// - /// **Configuration:** - /// Configured as a list `[[burnchain.affirmation_overrides]]` in TOML, each with: - /// - `reward_cycle`: The cycle number to override. - /// - `affirmation`: The 'p'/'n'/'a' sequence representing the map. Must have length `reward_cycle - 1`. - /// - /// Example TOML: - /// ```toml - /// [[burnchain.affirmation_overrides]] - /// reward_cycle = 413 - /// affirmation = "pna..." # Must be 412 chars long - /// ``` - /// - /// **Details:** - /// Special defaults are added when [`BurnchainConfig::mode`] is "xenon" or the node - /// is launched with the `testnet` subcommand, but config entries take precedence. + /// Special defaults are added when [`BurnchainConfig::mode`] is "xenon", but config entries take precedence. /// At startup, these overrides are written to the `BurnchainDB` (`overrides` table). - /// Primarily used for testing or recovering from network issues. - /// - /// Default: Empty `HashMap`. - /// Deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. + /// --- + /// @default: Empty map + /// @deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. + /// @notes: + /// - Primarily used for testing or recovering from network issues. + /// - Configured as a list `[[burnchain.affirmation_overrides]]` in TOML, each with + /// `reward_cycle` (integer) and `affirmation` (string of 'p'/'n'/'a', length `reward_cycle - 1`). + /// @toml_example: | + /// [[burnchain.affirmation_overrides]] + /// reward_cycle = 413 + /// affirmation = "pna..." # Must be 412 chars long pub affirmation_overrides: HashMap, /// Fault injection setting for testing. Introduces an artificial delay (in milliseconds) /// before processing each burnchain block download. Simulates a slow burnchain connection. - /// - /// This is intended strictly for testing purposes. - /// - /// Default: `0` (no delay). + /// --- + /// @default: `0` (no delay) + /// @notes: + /// - This is intended strictly for testing purposes. + /// - Units: milliseconds. pub fault_injection_burnchain_block_delay: u64, /// The maximum number of unspent transaction outputs (UTXOs) to request from the bitcoin node. /// @@ -1586,12 +1599,11 @@ pub struct BurnchainConfig { /// nodes with a very large number of UTXOs. Conversely, setting it too low might prevent /// the miner from finding enough UTXOs in a single query to meet the required funding amount /// for a transaction, even if sufficient funds exist across more UTXOs not returned by the limited query. - /// - /// This value must be `<= 1024`. - /// - /// Only relevant if [`NodeConfig::miner`] is `true`. - /// - /// Default: `Some(1024)` + /// --- + /// @default: `1024` + /// @notes: + /// - This value must be `<= 1024`. + /// - Only relevant if [`NodeConfig::miner`] is `true`. pub max_unspent_utxos: Option, } @@ -1996,112 +2008,125 @@ impl BurnchainConfigFile { 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"` + /// --- + /// @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. + /// If [`MinerConfig::mining_key`] is not set, this seed may also be used for mining-related signing. + /// --- + /// @default: Randomly generated 32 bytes + /// @notes: + /// - Required if [`NodeConfig::miner`] is `true` and [`MinerConfig::mining_key`] is absent. pub seed: Vec, /// 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}`. + /// --- + /// @default: `/tmp/stacks-node-{current_timestamp}` + /// @notes: + /// - For persistent mainnet or testnet nodes, this path must be explicitly configured to + /// a non-temporary location. 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"` + /// --- + /// @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"` + /// --- + /// @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). + /// --- + /// @default: `http://{rpc_bind}` (e.g., "http://0.0.0.0:20443" if [`NodeConfig::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). + /// This might differ from [`NodeConfig::p2p_bind`] if the node is behind NAT or a proxy. + /// --- + /// @default: Derived from [`NodeConfig::rpc_bind`] (e.g., "0.0.0.0:20443" if [`NodeConfig::rpc_bind`] is default). + /// @notes: + /// - The default value derivation might be unexpected, potentially using the + /// [`NodeConfig::rpc_bind`] address; explicit configuration is recommended if needed. 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. + /// --- + /// @default: Randomly generated 32 bytes pub local_peer_seed: Vec, /// 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 `[]`. + /// --- + /// @default: `[]` (empty vector) + /// @toml_example: | + /// bootstrap_node = "029266faff4c8e0ca4f934f34996a96af481df94a89b0c9bd515f3536a95682ddc@seed.testnet.hiro.so:30444,02196f005965cebe6ddc3901b7b1cc1aa7a88f305bb8c5893456b8f9a605923893@seed.mainnet.hiro.so:20444" pub bootstrap_node: Vec, /// 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 `[]`. + /// --- + /// @default: `[]` (empty vector) + /// @toml_example: | + /// deny_nodes = "192.168.1.100:20444,badhost.example.com:20444" pub deny_nodes: Vec, /// 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` + /// 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` + /// --- + /// @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` + /// --- + /// @default: `false` + /// @notes: + /// - Only relevant if [`NodeConfig::miner`] is `true`. pub mock_mining: bool, /// 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+. + /// --- + /// @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, /// Enable microblock mining. - /// - /// Default: `true` - /// Deprecated: This setting is ignored in Epoch 2.5+. + /// --- + /// @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+. + /// --- + /// @default: `30_000` (milliseconds, 30 seconds) + /// @deprecated: This setting is ignored in Epoch 2.5+. + /// @notes: + /// - Only applies when [`NodeConfig::mine_microblocks`] is true and before Epoch 2.5. + /// - Units: milliseconds. 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+. + /// --- + /// @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+. + /// --- + /// @default: `30_000` (milliseconds, 30 seconds) + /// @deprecated: This setting is ignored in Epoch 2.5+. + /// @notes: + /// - Only applies when [`NodeConfig::mine_microblocks`] is true and before Epoch 2.5. + /// - Units: milliseconds. 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 @@ -2109,21 +2134,25 @@ pub struct NodeConfig { /// 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) + /// --- + /// @default: `30_000` (milliseconds, 30 seconds) + /// @notes: + /// - Units: milliseconds. pub wait_time_for_blocks: u64, /// 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: `10_000` ms (10 seconds) + /// --- + /// @default: `10_000` (milliseconds, 10 seconds) + /// @notes: + /// - Units: milliseconds. 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). + /// --- + /// @default: `None` (Prometheus server disabled) pub prometheus_bind: Option, /// The strategy to use for MARF trie node caching in memory. /// Controls the trade-off between memory usage and performance for state access. @@ -2134,27 +2163,31 @@ pub struct NodeConfig { /// - `"node256"`: Cache only larger `TrieNode256` nodes. /// /// If the value is `None` or an unrecognized string, it defaults to `"noop"`. - /// - /// Default: `None` (effectively `"noop"`). + /// --- + /// @default: `None` (effectively `"noop"`) pub marf_cache_strategy: Option, /// 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` + /// --- + /// @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+. + /// --- + /// @default: `30` (seconds) + /// @deprecated: Unused after the Nakamoto upgrade. This setting is ignored in Epoch 3.0+. + /// @notes: + /// - Units: seconds. 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). + /// --- + /// @default: `None` (uses standard network genesis) + /// @notes: + /// - This is intended strictly for testing purposes and is disallowed on mainnet. pub use_test_genesis_chainstate: Option, /// 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 @@ -2162,8 +2195,8 @@ pub struct NodeConfig { /// - 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` + /// --- + /// @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: @@ -2171,53 +2204,65 @@ pub struct NodeConfig { /// 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). + /// --- + /// @default: + /// - `true` if [`NodeConfig::miner`] is `false` + /// - `false` if [`NodeConfig::miner`] is `true` 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. + /// 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` + /// --- + /// @default: `true` + /// @notes: + /// - This parameter cannot be set via the configuration file; it must be modified programmatically. pub assume_present_anchor_blocks: bool, /// 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). + /// --- + /// @default: `None` (no fault injection) + /// @notes: + /// - Values: 0-100 (percentage). pub fault_injection_block_push_fail_probability: Option, /// 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` + /// --- + /// @default: `false` + /// @notes: + /// - This parameter cannot be set via the configuration file; it must be modified programmatically. pub fault_injection_hide_blocks: bool, /// 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) + /// --- + /// @default: `300` (seconds, 5 minutes) + /// @notes: + /// - Units: seconds. pub chain_liveness_poll_time_secs: u64, /// 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 `[]`. + /// --- + /// @default: + /// - If [`NodeConfig::miner`] is `true` or [`NodeConfig::stacker`] is `true`, relevant system contracts + /// (like `.miners`, `.signers-*`) are automatically added in addition to any contracts + /// specified in the configuration file. + /// - Otherwise, defaults to an empty list `[]` if not specified in the TOML. + /// @notes: + /// - Values are strings representing qualified contract identifiers. + /// @toml_example: | + /// stacker_dbs = ["SP000000000000000000002Q6VF78.pox-3", "SP2C2YFP12AJZB4M4KUPSTMZQR0SNHNPH204SCQJM.stx-oracle-v1"] pub stacker_dbs: Vec, /// 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` + /// --- + /// @default: `false` pub txindex: bool, } @@ -2647,26 +2692,34 @@ impl NodeConfig { #[derive(Clone, Debug, PartialEq)] pub struct MinerConfig { /// Time to wait (in milliseconds) before the first attempt to mine a block. - /// - /// Default: `10` ms - /// Deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. + /// --- + /// @default: `10` (ms) + /// @deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. + /// @notes: + /// - Units: milliseconds. pub first_attempt_time_ms: u64, /// Time to wait (in milliseconds) for subsequent attempts to mine a block, /// after the first attempt fails. - /// - /// Default: `120_000` ms (2 minutes) - /// Deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. + /// --- + /// @default: `120_000` (ms, 2 minutes) + /// @deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. + /// @notes: + /// - Units: milliseconds. pub subsequent_attempt_time_ms: u64, - /// Time to wait (in milliseconds) to mine a microblock, - /// - /// Default: `30_000` ms (30 seconds) - /// Deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. + /// Time to wait (in milliseconds) to mine a microblock. + /// --- + /// @default: `30_000` (ms, 30 seconds) + /// @deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. + /// @notes: + /// - Units: milliseconds. pub microblock_attempt_time_ms: u64, /// Maximum time (in milliseconds) the miner spends selecting transactions from the mempool /// when assembling a Nakamoto block. Once this duration is exceeded, the miner stops /// adding transactions and finalizes the block with those already selected. - /// - /// Default: `5_000` ms (5 seconds) + /// --- + /// @default: `5_000` (ms, 5 seconds) + /// @notes: + /// - Units: milliseconds. pub nakamoto_attempt_time_ms: u64, /// Strategy for selecting the next transaction candidate from the mempool. /// Controls prioritization between maximizing immediate fee capture vs. ensuring @@ -2678,8 +2731,8 @@ pub struct MinerConfig { /// - `"GlobalFeeRate"`: Selects the transaction with the highest fee rate globally. /// - `"NextNonceWithHighestFeeRate"`: Selects the highest-fee transaction among those /// matching the next expected nonce for sender/sponsor accounts. - /// - /// Default: `"GlobalFeeRate"` + /// --- + /// @default: `"GlobalFeeRate"` pub mempool_walk_strategy: MemPoolWalkStrategy, /// Probability (percentage, 0-100) of prioritizing a transaction without a known fee rate /// during candidate selection. @@ -2688,25 +2741,27 @@ pub struct MinerConfig { /// transactions lacking fee estimates are periodically considered alongside high-fee ones, /// preventing potential starvation. A value of 0 means never prioritize them first, /// 100 means always prioritize them first (if available). - /// - /// Default: `25` (25% chance) + /// --- + /// @default: `25` (25% chance) + /// @notes: + /// - Values: 0-100. pub probability_pick_no_estimate_tx: u8, /// Optional recipient for the coinbase block reward, overriding the default miner address. /// /// By default (`None`), the reward is sent to the miner's primary address ([`NodeConfig::seed`]). - /// If set to some principal address *and* the current Stacks epoch is 2.1+, + /// If set to some principal address *and* the current Stacks epoch is > 2.1, /// the reward will be directed to the specified address instead. - /// - /// Default: `None` + /// --- + /// @default: `None` pub block_reward_recipient: Option, /// If possible, mine with a p2wpkh address. - /// - /// Default: `false` + /// --- + /// @default: `false` pub segwit: bool, /// Wait for a downloader pass before mining. /// This can only be disabled in testing; it can't be changed in the config file. - /// - /// Default: `true` + /// --- + /// @default: `true` pub wait_for_block_download: bool, /// Max size (in bytes) of the in-memory cache for storing expected account nonces. /// @@ -2714,13 +2769,14 @@ pub struct MinerConfig { /// the anticipated next nonce for accounts, reducing expensive lookups into the node's /// state (MARF trie). A larger cache can improve performance for workloads involving /// many unique accounts but increases memory consumption. - /// - /// Must be configured to a value greater than 0. - /// - /// Default: `1048576` bytes (1 MiB) + /// --- + /// @default: `1048576` (bytes, 1 MiB) + /// @notes: + /// - Must be configured to a value greater than 0. + /// - Units: bytes. pub nonce_cache_size: usize, /// Max size (in *number* of items) of transaction candidates to hold in the in-memory - /// retry cache. Each element [`MemPoolTxInfoPartial`] is currently 112 bytes. + /// retry cache. /// /// This cache stores transactions encountered during a `GlobalFeeRate` mempool walk /// whose nonces are currently too high for immediate processing. These candidates @@ -2729,38 +2785,42 @@ pub struct MinerConfig { /// /// A larger cache retains more potentially valid future candidates but uses more memory. /// This setting is primarily relevant for the `GlobalFeeRate` strategy. - /// - /// Default: `1048576` items (112 bytes * 1048576 = 112 MB) + /// --- + /// @default: `1048576` (items) + /// @notes: + /// - Units: number of items (Each element [`crate::core::mempool::MemPoolTxInfoPartial`] is currently 112 bytes). pub candidate_retry_cache_size: usize, /// Amount of time (in seconds) to wait for unprocessed blocks before mining a new block. - /// - /// Default: `30` - /// Deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. + /// --- + /// @default: `30` (seconds) + /// @deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. + /// @notes: + /// - Units: seconds. pub unprocessed_block_deadline_secs: u64, /// The private key (Secp256k1) used for signing blocks, provided as a hex string. /// /// This key must be present at runtime for mining operations to succeed. - /// - /// Default: The effective default depends on: - /// - If the `[miner]` section *is present* in the config file, the [`NodeConfig::seed`] is used. - /// - If the `[miner]` section *is not present* in the config file, `None`. Mining operations will fail at runtime. + /// --- + /// @default: + /// - [`NodeConfig::seed`] if the `[miner]` section *is present* in the config file + /// - `None` if the `[miner]` section *is not present* pub mining_key: Option, - /// Amount of time while mining in nakamoto to wait in between mining interim blocks - /// - /// Default: `None` - /// Deprecated: use [`MinerConfig::min_time_between_blocks_ms`] instead. + /// Amount of time while mining in nakamoto to wait in between mining interim blocks. + /// --- + /// @default: `None` + /// @deprecated: Use `min_time_between_blocks_ms` instead. pub wait_on_interim_blocks: Option, /// Minimum number of transactions that must be in a block if we're going to replace a pending - /// block-commit with a new block-commit - /// - /// Default: `0` - /// Deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. + /// block-commit with a new block-commit. + /// --- + /// @default: `0` + /// @deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. pub min_tx_count: u64, /// If true, requires subsequent mining attempts for the same block height /// to have a transaction count >= the previous best attempt. - /// - /// Default: `false` - /// Deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. + /// --- + /// @default: `false` + /// @deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. pub only_increase_tx_count: bool, /// Optional path to an external helper script for fetching unconfirmed block-commits. /// Used to inform the miner's dynamic burn fee bidding strategy with off-chain data. @@ -2772,11 +2832,11 @@ pub struct MinerConfig { /// (see [`stacks::config::chain_data::UnconfirmedBlockCommit`] struct) to stdout. /// - Exit with code 0 on success. /// - /// Look at [`test_get_unconfirmed_commits`](stackslib/src/config/chain_data.rs) for an example script. - /// - /// Default: `None` (feature disabled). - /// Deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode and - /// by the `get-spend-amount` cli subcommand. + /// Look at `test_get_unconfirmed_commits` in `stackslib/src/config/chain_data.rs` for an example script. + /// --- + /// @default: `None` (feature disabled). + /// @deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode and by the + /// `get-spend-amount` cli subcommand. pub unconfirmed_commits_helper: Option, /// The minimum win probability this miner aims to achieve in block sortitions. /// @@ -2786,9 +2846,9 @@ pub struct MinerConfig { /// cease spending in subsequent sortitions (returning a burn fee cap of 0) to conserve resources. /// /// Setting this value close to 0.0 effectively disables the underperformance check. - /// - /// Default: `0.0` - /// Deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. + /// --- + /// @default: `0.0` + /// @deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. pub target_win_probability: f64, /// Path to a file for storing and loading the currently active, registered VRF leader key. /// @@ -2799,8 +2859,8 @@ pub struct MinerConfig { /// if this path is set, the node saves the details of the newly activated [`RegisteredKey`] to this file. /// This allows the miner to persist its active VRF key across restarts. /// If the file doesn't exist during load, or the path is `None`, the node proceeds with a new registration. - /// - /// Default: `None` + /// --- + /// @default: `None` pub activated_vrf_key_path: Option, /// Controls how the miner estimates its win probability when checking for underperformance. /// @@ -2813,24 +2873,22 @@ pub struct MinerConfig { /// based on anticipated competition changes. /// - If `false`: The win probability estimation uses the currently observed spend distribution /// for the next block. - /// - /// Default: `false` - /// Deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode and - /// by the `get-spend-amount` cli subcommand. + /// --- + /// @default: `false` + /// @deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode and by the + /// `get-spend-amount` cli subcommand. pub fast_rampup: bool, /// The maximum number of consecutive Bitcoin blocks the miner will tolerate underperforming /// (i.e., having a calculated win probability below [`MinerConfig::target_win_probability`]) /// before temporarily pausing mining efforts. /// /// This check is only active after an initial startup phase (6 blocks past the mining start height). - /// If the miner underperforms for this number of consecutive blocks, the [`BlockMinerThread::get_mining_spend_amount`] - /// function will return 0, effectively preventing the miner from submitting a block commit - /// for the current sortition to conserve funds. - /// - /// If set to `None`, this underperformance check is disabled. - /// - /// Default: `None` - /// Deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. + /// If the miner underperforms for this number of consecutive blocks, the + /// [`BlockMinerThread::get_mining_spend_amount`] function will return 0, effectively preventing the + /// miner from submitting a block commit for the current sortition to conserve funds. + /// --- + /// @default: `None` (underperformance check is disabled). + /// @deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. pub underperform_stop_threshold: Option, /// Specifies which types of transactions the miner should consider including in a block /// during the mempool walk process. Transactions of types not included in this set will be skipped. @@ -2842,19 +2900,23 @@ pub struct MinerConfig { /// - `"TokenTransfer"` /// - `"SmartContract"` /// - `"ContractCall"` - /// - /// Default: all transaction types are considered. + /// --- + /// @default: All transaction types are considered (equivalent to [`MemPoolWalkTxTypes::all()`]). + /// @toml_example: | + /// txs_to_consider = "TokenTransfer,ContractCall" pub txs_to_consider: HashSet, - /// A whitelist of Stacks addresses whose transactions should be exclusively considered during - /// the mempool walk for block building. If this list is non-empty, any transaction whose - /// origin address is *not* in this set will be skipped. + /// A comma separated list of Stacks addresses to whitelist so that only transactions from + /// these addresses should be considered during the mempool walk for block building. If this + /// list is non-empty, any transaction whose origin address is *not* in this set will be skipped. /// /// This allows miners to prioritize transactions originating from specific accounts that are /// important to them. /// Configured as a comma-separated string of standard Stacks addresses (e.g., "ST123...,ST456...") /// in the configuration file. - /// - /// Default: `HashSet::new()` (empty set, meaning all origins are considered). + /// --- + /// @default: Empty set (all origins are considered). + /// @toml_example: | + /// filter_origins = "ST2QKZ4FKHAH1NQKYKYAYZPY440FEPK7GZ1R5HBP2,ST319CF5WV77KYR1H3GT0GZ7B8Q4AQPY42ETP1VPF" pub filter_origins: HashSet, /// Defines the maximum depth (in Stacks blocks) the miner considers when evaluating /// potential chain tips when selecting the best tip to mine the next block on. @@ -2865,10 +2927,10 @@ pub struct MinerConfig { /// while a higher value considers deeper potential reorganizations. /// /// This setting influences which fork the miner chooses to build upon if multiple valid tips exist. - /// - /// Default: `3` - /// Deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode and - /// the `pick-best-tip` cli subcommand. + /// --- + /// @default: `3` + /// @deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode and the + /// `pick-best-tip` cli subcommand. pub max_reorg_depth: u64, /// Enables a mock signing process for testing purposes, specifically designed for use during Epoch 2.5 /// before the activation of Nakamoto consensus. @@ -2876,11 +2938,11 @@ pub struct MinerConfig { /// When set to `true` and [`MinerConfig::mining_key`] is provided, the miner will interact /// with the `.miners` and `.signers` contracts via the stackerdb to send and receive mock /// proposals and signatures, simulating aspects of the Nakamoto leader election and block signing flow. - /// - /// This is intended strictly for testing purposes for Epoch 2.5 conditions. - /// - /// Default: `false` - /// Deprecated: This setting is ignored in Epoch 3.0+. + /// --- + /// @default: `false` (Should only default true if [`MinerConfig::mining_key`] is set). + /// @deprecated: This setting is ignored in Epoch 3.0+. + /// @notes: + /// - This is intended strictly for testing purposes for Epoch 2.5 conditions. pub pre_nakamoto_mock_signing: bool, /// The minimum time to wait between mining blocks in milliseconds. The value must be greater /// than or equal to 1000 ms because if a block is mined within the same second as its parent, @@ -2888,31 +2950,39 @@ pub struct MinerConfig { /// /// This check ensures compliance with signer rules that prevent blocks with identical timestamps /// (at second resolution) to their parents. If a lower value is configured, 1000 ms is used instead. - /// - /// Default: [`DEFAULT_MIN_TIME_BETWEEN_BLOCKS_MS`] (currently 1000 ms) + /// --- + /// @default: [`DEFAULT_MIN_TIME_BETWEEN_BLOCKS_MS`] (ms) + /// @notes: + /// - Units: milliseconds. pub min_time_between_blocks_ms: u64, /// The amount of time in milliseconds that the miner should sleep in between attempts to /// mine a block when the mempool is empty. /// /// This prevents the miner from busy-looping when there are no pending transactions, /// conserving CPU resources. During this sleep, the miner still checks burnchain tip changes. - /// - /// Default: [`DEFAULT_EMPTY_MEMPOOL_SLEEP_MS`] (currently 2500 ms) + /// --- + /// @default: [`DEFAULT_EMPTY_MEMPOOL_SLEEP_MS`] (ms) + /// @notes: + /// - Units: milliseconds. pub empty_mempool_sleep_time: Duration, /// Time in milliseconds to pause after receiving the first threshold rejection, before proposing a new block. /// /// When a miner's block proposal fails to gather enough signatures from the signers for the first time /// at a given height, the miner will pause for this duration before attempting to mine and propose again. - /// - /// Default: [`DEFAULT_FIRST_REJECTION_PAUSE_MS`] (currently 5000 ms) + /// --- + /// @default: [`DEFAULT_FIRST_REJECTION_PAUSE_MS`] (ms) + /// @notes: + /// - Units: milliseconds. pub first_rejection_pause_ms: u64, /// Time in milliseconds to pause after receiving subsequent threshold rejections, before proposing a new block. /// /// If a miner's block proposal is rejected multiple times at the same height (after the first rejection), /// this potentially longer pause duration is used before retrying. This gives more significant time /// for network state changes or signer coordination. - /// - /// Default: [`DEFAULT_SUBSEQUENT_REJECTION_PAUSE_MS`] (currently 10_000 ms) + /// --- + /// @default: [`DEFAULT_SUBSEQUENT_REJECTION_PAUSE_MS`] (ms) + /// @notes: + /// - Units: milliseconds. pub subsequent_rejection_pause_ms: u64, /// Time in milliseconds to wait for a Nakamoto block after seeing a burnchain block before submitting a block commit. /// @@ -2922,8 +2992,10 @@ pub struct MinerConfig { /// Waiting helps avoid situations where the relayer immediately submits a commit that needs /// to be replaced via RBF if a new Stacks block appears shortly after. /// This delay is skipped if the new burnchain blocks leading to the tip contain no sortitions. - /// - /// Default: [`DEFAULT_BLOCK_COMMIT_DELAY_MS`] (currently 40_000 ms) + /// --- + /// @default: [`DEFAULT_BLOCK_COMMIT_DELAY_MS`] (ms) + /// @notes: + /// - Units: milliseconds. pub block_commit_delay: Duration, /// The percentage of the remaining tenure cost limit to consume each block. /// @@ -2932,12 +3004,12 @@ pub struct MinerConfig { /// For example, if set to 25, a block can use at most 25% of the tenure's currently available cost limit. /// This allows miners to spread the tenure's total execution budget across multiple blocks rather than /// potentially consuming it all in the first block. - /// - /// A value of `100` (or setting this to `None`) effectively disables this per-block limit, allowing - /// a block to use the entire remaining tenure budget. - /// The value must be between 1 and 100, inclusive. - /// - /// Default: [`DEFAULT_TENURE_COST_LIMIT_PER_BLOCK_PERCENTAGE`] (currently 25 %) + /// --- + /// @default: [`DEFAULT_TENURE_COST_LIMIT_PER_BLOCK_PERCENTAGE`] (%) + /// @notes: + /// - The value must be between 1 and 100, inclusive, if specified. + /// - Setting to 100 effectively disables this per-block limit, allowing a block to use the + /// entire remaining tenure budget. pub tenure_cost_limit_per_block_percentage: Option, /// Duration to wait in-between polling the sortition DB to see if we need to /// extend the ongoing tenure (e.g. because the current sortition is empty or invalid). @@ -2945,8 +3017,10 @@ pub struct MinerConfig { /// After the relayer determines that a tenure extension might be needed but cannot proceed immediately /// (e.g., because a miner thread is already active for the current burn view), it will wait for this /// duration before re-checking the conditions for tenure extension. - /// - /// Default: [`DEFAULT_TENURE_EXTEND_POLL_SECS`] (currently 1 second) + /// --- + /// @default: [`DEFAULT_TENURE_EXTEND_POLL_SECS`] (seconds) + /// @notes: + /// - Units: seconds. pub tenure_extend_poll_timeout: Duration, /// Duration to wait before trying to continue a tenure because the next miner did not produce blocks. /// @@ -2955,8 +3029,10 @@ pub struct MinerConfig { /// This gives the new winner of the most recent sortition a grace period to produce their first block. /// Also used in scenarios with empty sortitions to give the winner of the *last valid* sortition time /// to produce a block before the current miner attempts an extension. - /// - /// Default: [`DEFAULT_TENURE_EXTEND_WAIT_MS`] (currently 120_000 ms) + /// --- + /// @default: [`DEFAULT_TENURE_EXTEND_WAIT_MS`] (ms) + /// @notes: + /// - Units: milliseconds. pub tenure_extend_wait_timeout: Duration, /// Duration to wait before attempting to issue a time-based tenure extend. /// @@ -2965,8 +3041,10 @@ pub struct MinerConfig { /// If the time elapsed since the last tenure change exceeds this value, and the signer coordinator /// indicates an extension is timely, and the cost usage threshold ([`MinerConfig::tenure_extend_cost_threshold`]) /// is met, the miner will include a tenure extension transaction in its next block. - /// - /// Default: [`DEFAULT_TENURE_TIMEOUT_SECS`] (currently 180 seconds) + /// --- + /// @default: [`DEFAULT_TENURE_TIMEOUT_SECS`] (seconds) + /// @notes: + /// - Units: seconds. pub tenure_timeout: Duration, /// Percentage of block budget that must be used before attempting a time-based tenure extend. /// @@ -2976,8 +3054,10 @@ pub struct MinerConfig { /// If the cost usage is below this threshold, a time-based extension will not be attempted, even if /// the [`MinerConfig::tenure_timeout`] duration has elapsed. /// This prevents miners from extending tenures very early if they have produced only low-cost blocks. - /// - /// Default: [`DEFAULT_TENURE_EXTEND_COST_THRESHOLD`] (currently 50 %) + /// --- + /// @default: [`DEFAULT_TENURE_EXTEND_COST_THRESHOLD`] (%) + /// @notes: + /// - Values: 0-100. pub tenure_extend_cost_threshold: u64, /// Defines adaptive timeouts for waiting for signer responses, based on the accumulated weight of rejections. /// @@ -2995,22 +3075,17 @@ pub struct MinerConfig { /// allowing the miner to abandon unviable proposals faster. /// /// A key for 0 (zero rejections) must be defined, representing the initial timeout when no rejections have been received. - /// - /// **Example TOML:** - /// ```toml - /// [miner] - /// # Keys are rejection counts, values are timeouts in seconds. - /// block_rejection_timeout_steps = { 0 = 180, 10 = 90, 20 = 45, 30 = 0 } - /// ``` - /// This example means: - /// - If rejection weight is 0 <= weight < 10, wait up to 180 seconds. - /// - If rejection weight is 10 <= weight < 20, wait up to 90 seconds. - /// - If rejection weight is 20 <= weight < 30, wait up to 45 seconds. - /// - If rejection weight is >= 30, timeout immediately (0 seconds). - /// - /// (Note: The actual rejection weight values depend on the specific signer set and their weights.) - /// - /// Default: `{ 0: 180s, 10: 90s, 20: 45s, 30: 0s }` + /// --- + /// @default: `{ 0: 180, 10: 90, 20: 45, 30: 0 }` (times in seconds) + /// @notes: + /// - Keys are rejection weight percentages (0-100). Values are timeout durations. + /// @toml_example: | + /// # Keys are rejection counts (as strings), values are timeouts in seconds. + /// [miner.block_rejection_timeout_steps] + /// "0" = 180 + /// "10" = 90 + /// "20" = 45 + /// "30" = 0 pub block_rejection_timeout_steps: HashMap, /// Defines the maximum execution time (in seconds) allowed for a single contract call transaction. /// @@ -3018,8 +3093,10 @@ pub struct MinerConfig { /// and the execution time exceeds this limit, the transaction processing fails with an `ExecutionTimeout` error, /// and the transaction is skipped. This prevents potentially long-running or infinite-loop transactions /// from blocking block production. - /// - /// Default: `None` (no execution time limit) + /// --- + /// @default: `None` (no execution time limit) + /// @notes: + /// - Units: seconds. pub max_execution_time_secs: Option, /// TODO: remove this option when its no longer a testing feature and it becomes default behaviour /// The miner will attempt to replay transactions that a threshold number of signers are expecting in the next block @@ -3086,56 +3163,67 @@ impl Default for MinerConfig { pub struct ConnectionOptionsFile { /// Maximum number of messages allowed in the per-connection incoming buffer. /// The limits apply individually to each established connection (both P2P and HTTP). - /// - /// Default: 100. + /// --- + /// @default: `100` pub inbox_maxlen: Option, /// Maximum number of messages allowed in the per-connection outgoing buffer. /// The limit applies individually to each established connection (both P2P and HTTP). - /// - /// Default: 100. + /// --- + /// @default: `100` pub outbox_maxlen: Option, /// Maximum duration (in seconds) a connection attempt is allowed to remain in the connecting state. /// /// This applies to both incoming P2P and HTTP connections. If a remote peer initiates a connection /// but does not complete the connection process (e.g., handshake for P2P) within this time, the node /// will consider it unresponsive and drop the connection attempt. - /// - /// Default: 10 seconds. + /// --- + /// @default: `10` (seconds) + /// @notes: + /// - Units: seconds. pub connect_timeout: Option, /// Maximum duration (in seconds) a P2P peer is allowed after connecting before completing the handshake. /// /// If a P2P peer connects successfully but fails to send the necessary handshake messages /// within this time, the node will consider it unresponsive and drop the connection. - /// - /// Default: 5 seconds. + /// --- + /// @default: `5` (seconds) + /// @notes: + /// - Units: seconds. pub handshake_timeout: Option, /// General communication timeout (in seconds). /// /// - For HTTP connections: Governs two timeout aspects: /// - Server-side: Defines the maximum allowed time since the last request was received from a client. - /// An idle connection is dropped if both this timeout and [`ConnectionOptionsFile::idle_timeout`] are exceeded. + /// An idle connection is dropped if both this timeout and [`ConnectionOptionsFile::idle_timeout`] are exceeded. /// - Client-side: Sets the timeout duration (TTL) for outgoing HTTP requests initiated by the node itself. /// - For P2P connections: Used as the specific timeout for NAT punch-through requests. - /// - /// Default: 15 seconds. + /// --- + /// @default: `15` (seconds) + /// @notes: + /// - Units: seconds. pub timeout: Option, /// Maximum idle time (in seconds) for HTTP connections. /// /// This applies only to HTTP connections. It defines the maximum allowed time since the /// last response was sent by the node to the client. An HTTP connection is dropped if - /// both this `idle_timeout` and the general [`ConnectionOptionsFile::timeout`] (time since last request received) - /// are exceeded. - /// - /// Default: 15 seconds. + /// both this `idle_timeout` and the general [`ConnectionOptionsFile::timeout`] (time since last + /// request received) are exceeded. + /// --- + /// @default: `15` (seconds) + /// @notes: + /// - Units: seconds. pub idle_timeout: Option, /// Interval (in seconds) at which this node expects to send or receive P2P keep-alive messages. /// /// During the P2P handshake, this node advertises this configured `heartbeat` value to its peers. /// Each peer uses the other's advertised heartbeat interval (plus a timeout margin) to monitor /// responsiveness and detect potential disconnections. This node also uses its own configured - /// value to proactively send Ping messages if the connection would otherwise be idle, helping to keep it active. - /// - /// Default: 3600 seconds (1 hour). + /// value to proactively send Ping messages if the connection would otherwise be idle, helping to + /// keep it active. + /// --- + /// @default: `3_600` (seconds, 1 hour) + /// @notes: + /// - Units: seconds. pub heartbeat: Option, /// Validity duration (in number of bitcoin blocks) for the node's P2P session private key. /// @@ -3144,11 +3232,13 @@ pub struct ConnectionOptionsFile { /// reaches or exceeds the key's expiry height, the node automatically generates a new random /// private key. /// The expiry block height for this new key is calculated by adding the configured - /// `private_key_lifetime` (in blocks) to the previous key's expiry block height. + /// [`ConnectionOptionsFile::private_key_lifetime`] (in blocks) to the previous key's expiry block height. /// The node then re-handshakes with peers to transition to the new key. /// This provides periodic key rotation for P2P communication. - /// - /// Default: `9223372036854775807` (i64::MAX, effectively infinite, disabling automatic re-keying). + /// --- + /// @default: `9223372036854775807` (i64::MAX, effectively infinite, disabling automatic re-keying). + /// @notes: + /// - Units: bitcoin blocks. pub private_key_lifetime: Option, /// Target number of peers for StackerDB replication. /// @@ -3157,24 +3247,24 @@ pub struct ConnectionOptionsFile { /// /// Note: Formerly (pre-Epoch 3.0), this also controlled the target peer count for /// inventory synchronization. - /// - /// Default: 32. + /// --- + /// @default: `32` pub num_neighbors: Option, /// Maximum number of allowed concurrent inbound P2P connections. /// /// This acts as a hard limit. If the node already has this many active inbound P2P /// connections, any new incoming P2P connection attempts will be rejected. /// Outbound P2P connections initiated by this node are not counted against this limit. - /// - /// Default: 750. + /// --- + /// @default: `750` pub num_clients: Option, /// Maximum total number of allowed concurrent HTTP connections. /// /// This limits the total number of simultaneous connections the node's RPC/HTTP server /// will accept. If this limit is reached, new incoming HTTP connection attempts /// will be rejected. - /// - /// Default: 1000. + /// --- + /// @default: `1000` pub max_http_clients: Option, /// Target number of outbound P2P connections the node aims to maintain. /// @@ -3182,8 +3272,8 @@ pub struct ConnectionOptionsFile { /// outbound P2P connections exceeds this value. Pruning aims to reduce the connection /// count back down to this target, ensuring the node maintains a baseline number /// of outbound peers for network connectivity. - /// - /// Default: 16. + /// --- + /// @default: `16` pub soft_num_neighbors: Option, /// Soft limit threshold for triggering inbound P2P connection pruning. /// @@ -3191,23 +3281,23 @@ pub struct ConnectionOptionsFile { /// the node will activate pruning logic to reduce the count, typically by applying /// per-host limits (see [`ConnectionOptionsFile::soft_max_clients_per_host`]). /// This helps manage the overall load from inbound peers. - /// - /// Default: 750. + /// --- + /// @default: `750` pub soft_num_clients: Option, - /// maximum number of neighbors per host we permit - /// - /// Default: 1. - /// Deprecated: it does not have any effect on the node's behavior. + /// Maximum number of neighbors per host we permit. + /// --- + /// @default: `1` + /// @deprecated: It does not have any effect on the node's behavior. pub max_neighbors_per_host: Option, - /// maximum number of inbound p2p connections per host we permit - /// - /// Default: 4. - /// Deprecated: it does not have any effect on the node's behavior. + /// Maximum number of inbound p2p connections per host we permit. + /// --- + /// @default: `4` + /// @deprecated: It does not have any effect on the node's behavior. pub max_clients_per_host: Option, - /// soft limit on the number of neighbors per host we permit - /// - /// Default: 1. - /// Deprecated: it does not have any effect on the node's behavior. + /// Soft limit on the number of neighbors per host we permit. + /// --- + /// @default: `1` + /// @deprecated: It does not have any effect on the node's behavior. pub soft_max_neighbors_per_host: Option, /// Soft limit on the number of outbound P2P connections per network organization (ASN). /// @@ -3215,10 +3305,11 @@ pub struct ConnectionOptionsFile { /// the node checks if any single network organization (identified by ASN) has more /// outbound connections than this limit. If so, it preferentially prunes the least /// healthy/newest connections from that overrepresented organization until its count - /// is reduced to this limit or the total outbound count reaches [`ConnectionOptionsFile::soft_num_neighbors`]. - /// This encourages connection diversity across different network providers. - /// - /// Default: 32. + /// is reduced to this limit or the total outbound count reaches + /// [`ConnectionOptionsFile::soft_num_neighbors`]. This encourages connection diversity across + /// different network providers. + /// --- + /// @default: `32` pub soft_max_neighbors_per_org: Option, /// Soft limit on the number of inbound P2P connections allowed per host IP address. /// @@ -3227,8 +3318,8 @@ pub struct ConnectionOptionsFile { /// If so, it preferentially prunes the newest connections originating from that /// specific IP address until its count is reduced to this limit. /// This prevents a single host from dominating the node's inbound connection capacity. - /// - /// Default: 4. + /// --- + /// @default: `4` pub soft_max_clients_per_host: Option, /// Maximum total number of concurrent network sockets the node is allowed to manage. /// @@ -3237,16 +3328,18 @@ pub struct ConnectionOptionsFile { /// and established HTTP connections. /// It serves as a hard limit to prevent the node from exhausting operating system /// resources related to socket descriptors. - /// - /// Default: 800. + /// --- + /// @default: `800` pub max_sockets: Option, /// Minimum interval (in seconds) between the start of consecutive neighbor discovery walks. /// /// The node periodically performs "neighbor walks" to discover new peers and maintain /// an up-to-date view of the P2P network topology. This setting controls how frequently /// these walks can be initiated, preventing excessive network traffic and processing. - /// - /// Default: 60 seconds. + /// --- + /// @default: `60` (seconds) + /// @notes: + /// - Units: seconds. pub walk_interval: Option, /// Probability (0.0 to 1.0) of forcing a neighbor walk to start from a seed/bootstrap peer. /// @@ -3255,15 +3348,17 @@ pub struct ConnectionOptionsFile { /// Normally, in this situation, the walk would start from a random inbound or outbound peer. /// However, with this probability, the walk is forced to start from a seed peer instead. /// This helps ensure the node periodically re-establishes its network view from trusted entry points. - /// - /// Default: 0.1 (10%). + /// --- + /// @default: `0.1` (10%) pub walk_seed_probability: Option, /// Frequency (in milliseconds) for logging the current P2P neighbor list at the DEBUG level. /// /// If set to a non-zero value, the node will periodically log details about its currently /// established P2P connections (neighbors). Setting this to 0 disables this periodic logging. - /// - /// Default: 60_000 ms (1 minute). + /// --- + /// @default: `60_000` (ms, 1 minute). + /// @notes: + /// - Units: milliseconds. pub log_neighbors_freq: Option, /// Maximum time (in milliseconds) to wait for a DNS query to resolve. /// @@ -3271,52 +3366,60 @@ pub struct ConnectionOptionsFile { /// or an Atlas attachment URL) into an IP address, it initiates a DNS lookup. /// This setting defines the maximum duration the node will wait for the DNS server /// to respond before considering the lookup timed out. - /// - /// Default: 15_000 ms, (15 seconds). + /// --- + /// @default: `15_000` (ms, 15 seconds). + /// @notes: + /// - Units: milliseconds. pub dns_timeout: Option, /// Maximum number of concurrent Nakamoto block download requests allowed. /// /// This limits how many separate block download processes for Nakamoto tenures /// (both confirmed and unconfirmed) can be active simultaneously. Helps manage /// network bandwidth and processing load during chain synchronization. - /// - /// Default: 6. + /// --- + /// @default: `6` pub max_inflight_blocks: Option, - /// Maximum number of concurrent Atlas attachment download requests allowed. + /// Maximum number of concurrent Atlas data attachment download requests allowed. /// /// This limits how many separate download requests for Atlas data attachments /// can be active simultaneously. Helps manage network resources when fetching /// potentially large attachment data. - /// - /// Default: 6. + /// --- + /// @default: `6` pub max_inflight_attachments: Option, /// Maximum total size (in bytes) of data allowed to be written during a read-only call. - /// Note: This limit is effectively forced to 0 by the API handler, ensuring read-only behavior. - /// Configuring a non-zero value has no effect on read-only call execution. - /// - /// Default: 0. + /// --- + /// @default: `0` + /// @notes: + /// - This limit is effectively forced to 0 by the API handler, ensuring read-only behavior. + /// - Configuring a non-zero value has no effect on read-only call execution. + /// - Units: bytes. pub read_only_call_limit_write_length: Option, /// Maximum total size (in bytes) of data allowed to be read from Clarity data space (variables, maps) /// during a read-only call. - /// - /// Default: 100_000 bytes (100 KB). + /// --- + /// @default: `100_000` (bytes, 100 KB). + /// @notes: + /// - Units: bytes. pub read_only_call_limit_read_length: Option, - /// Total number of independent read operations permitted for an individual write-only function call /// Maximum number of distinct write operations allowed during a read-only call. - /// Note: This limit is effectively forced to 0 by the API handler, ensuring read-only behavior. - /// Configuring a non-zero value has no effect on read-only call execution. - /// - /// Default: 0. + /// --- + /// @default: `0` + /// @notes: + /// - This limit is effectively forced to 0 by the API handler, ensuring read-only behavior. + /// - Configuring a non-zero value has no effect on read-only call execution. pub read_only_call_limit_write_count: Option, /// Maximum number of distinct read operations from Clarity data space allowed during a read-only call. - /// - /// Default: 30. + /// --- + /// @default: `30` pub read_only_call_limit_read_count: Option, /// Runtime cost limit for an individual read-only function call. This represents /// computation effort within the Clarity VM. - /// (https://github.com/stacksgov/sips/blob/main/sips/sip-006/sip-006-runtime-cost-assessment.md) - /// - /// Default: 1_000_000_000 units. + /// (See SIP-006: https://github.com/stacksgov/sips/blob/main/sips/sip-006/sip-006-runtime-cost-assessment.md) + /// --- + /// @default: `1_000_000_000` (units) + /// @notes: + /// - Units: Clarity VM cost units. pub read_only_call_limit_runtime: Option, /// Maximum size (in bytes) of the HTTP request body for read-only contract calls. /// @@ -3324,8 +3427,11 @@ pub struct ConnectionOptionsFile { /// `/v2/contracts/call-read-only/...` RPC endpoint. It prevents excessively large /// request bodies, which might contain numerous or very large hex-encoded function arguments, /// from overwhelming the node. - /// - /// Default: `83_886_080` bytes (80 MiB), calculated as 20 * [`clarity::vm::types::BOUND_VALUE_SERIALIZATION_HEX`]. + /// --- + /// @default: `83_886_080` (bytes, 80 MiB) + /// @notes: + /// - Calculated as 20 * [`clarity::vm::types::BOUND_VALUE_SERIALIZATION_HEX`]. + /// - Units: bytes. pub maximum_call_argument_size: Option, /// Minimum interval (in seconds) between consecutive block download scans in epoch 2.x. /// @@ -3333,70 +3439,82 @@ pub struct ConnectionOptionsFile { /// finding any new blocks to download, and if the known peer inventories had not changed, /// the node would wait at least this duration before initiating the next download scan. /// This throttled the downloader when the node was likely already synchronized. - /// - /// Default: 10 seconds. - /// Deprecated: This setting is ignored in Epoch 3.0+. + /// --- + /// @default: `10` (seconds) + /// @deprecated: This setting is ignored in Epoch 3.0+. + /// @notes: + /// - Units: seconds. pub download_interval: Option, /// Minimum interval (in seconds) between initiating inventory synchronization attempts with the same peer. /// /// Acts as a per-peer cooldown to throttle sync requests. A new sync cycle with a peer generally /// starts only after this interval has passed since the previous attempt began *and* the previous /// cycle is considered complete. - /// - /// Default: 45 seconds. + /// --- + /// @default: `45` (seconds) + /// @notes: + /// - Units: seconds. pub inv_sync_interval: Option, /// Deprecated: it does not have any effect on the node's behavior. + /// --- + /// @default: `None` + /// @deprecated: It does not have any effect on the node's behavior. pub full_inv_sync_interval: Option, /// Lookback depth (in PoX reward cycles) for Nakamoto inventory synchronization requests. /// /// When initiating an inventory sync cycle with a peer, the node requests data starting /// from `inv_reward_cycles` cycles before the current target reward cycle. This determines /// how much historical inventory information is requested in each sync attempt. - /// - /// Default: Derived from [`BurnchainConfig::mode`] 3 for `mainnet`, [`INV_REWARD_CYCLES_TESTNET`] otherwise (6). + /// --- + /// @default: + /// - `3` if [`BurnchainConfig::mode`] is `"mainnet"` + /// - [`INV_REWARD_CYCLES_TESTNET`] otherwise + /// @notes: + /// - Units: PoX reward cycles. pub inv_reward_cycles: Option, - /// The Public IPv4 address and port to advertise to other nodes. + /// The Public IPv4 address and port (e.g. "203.0.113.42:20444") to advertise to other nodes. /// - /// If this option is not set (`None`), the node will attemp to automatically discover its + /// If this option is not set (`None`), the node will attempt to automatically discover its /// public IP address. - /// - /// Default: `None` (triggers automatic discovery attempt). + /// --- + /// @default: `None` (triggers automatic discovery attempt) pub public_ip_address: Option, /// If true, disables the neighbor discovery mechanism from starting walks from inbound peers. /// Walks will only initiate from seed/bootstrap peers, outbound connections, or pingbacks. - /// - /// Primarily intended for testing or specific network debugging scenarios. - /// - /// Default: `false`. + /// --- + /// @default: `false` + /// @notes: + /// - Primarily intended for testing or specific network debugging scenarios. pub disable_inbound_walks: Option, /// If true, prevents the node from processing initial handshake messages from new inbound P2P connections. /// /// This effectively stops the node from establishing new authenticated inbound P2P sessions. /// Outbound connections initiated by this node are unaffected. - /// - /// Primarily intended for testing purposes. - /// - /// Default: `false`. + /// --- + /// @default: `false` + /// @notes: + /// - Primarily intended for testing purposes. pub disable_inbound_handshakes: Option, /// If true, completely disables the block download state machine. /// /// The node will not attempt to download Stacks blocks (neither Nakamoto tenures nor /// legacy blocks) from peers. - /// - /// Intended for testing or specialized node configurations. - /// - /// Default: `false`. + /// --- + /// @default: `false` + /// @notes: + /// - Intended for testing or specialized node configurations. pub disable_block_download: Option, /// Fault injection setting for testing purposes. Interval (in seconds) for forced disconnection of all peers. /// - /// If set to a positive value, the node will periodically disconnect all of its P2P peers at roughly this interval. - /// This simulates network churn or partitioning for testing node resilience. - /// - /// Note: The code enforcing this behavior is conditionally compiled using `cfg!(test)` and is - /// only active during test runs (e.g., via `cargo test`). This setting has no effect in - /// standard production builds. - /// - /// Default: `None` (feature disabled). + /// If set to a positive value, the node will periodically disconnect all of its P2P peers at + /// roughly this interval. This simulates network churn or partitioning for testing node resilience. + /// --- + /// @default: `None` (feature disabled) + /// @notes: + /// - The code enforcing this behavior is conditionally compiled using `cfg!(test)` and is + /// only active during test runs. + /// - This setting has no effect in standard production builds. + /// - Units: seconds. pub force_disconnect_interval: Option, /// Controls whether a node with public inbound connections should still push blocks, even if not NAT'ed. /// @@ -3405,9 +3523,9 @@ pub struct ConnectionOptionsFile { /// it would refrain from proactively pushing blocks and microblocks to peers. /// The assumption was that publicly reachable nodes should primarily serve downloads. /// If set to `true` (default), the node would push data regardless of its perceived reachability. - /// - /// Default: `true`. - /// Deprecated: This setting is ignored in Epoch 3.0+. + /// --- + /// @default: `true` + /// @deprecated: This setting is ignored in Epoch 3.0+. pub antientropy_public: Option, /// Whether to allow connections and interactions with peers having private IP addresses. /// @@ -3420,8 +3538,8 @@ pub struct ConnectionOptionsFile { /// /// Setting this to `true` disables these restrictions, which can be useful for local testing /// environments or fully private network deployments. - /// - /// Default: `false`. + /// --- + /// @default: `false` pub private_neighbors: Option, /// HTTP auth password to use when communicating with stacks-signer binary. /// @@ -3429,31 +3547,32 @@ pub struct ConnectionOptionsFile { /// Primarily, it secures the communication channel between this node and a connected /// `stacks-signer` instance. /// - /// **Requirement:** This field **must** be configured if the node needs to receive block - /// proposals from a configured `stacks-signer`event_observer via the `/v3/block_proposal` endpoint. The value - /// must match the token configured on the signer. - /// /// It is also used to authenticate requests to `/v2/blocks?broadcast=1`. - /// - /// Default: `None` (authentication disabled for relevant endpoints). + /// --- + /// @default: `None` (authentication disabled for relevant endpoints) + /// @notes: + /// - **Requirement:** This field **must** be configured if the node needs to receive + /// block proposals from a configured `stacks-signer` event_observer via the + /// `/v3/block_proposal` endpoint. The value must match the token configured on the signer. pub auth_token: Option, /// Minimum interval (in seconds) between attempts to run the Epoch 2.x anti-entropy data push mechanism. /// /// The Stacks 2.x anti-entropy protocol involves the node proactively pushing its known - /// Stacks blocks and microblocks to peers. This `antientropy_retry` value specifies the - /// cooldown period for this operation. + /// Stacks blocks and microblocks to peers. This value specifies the cooldown period for this operation. /// This prevents the node from excessively attempting to push data to its peers. - /// - /// Default: 3600 seconds (1 hour). - /// Deprecated: This setting is ignored in Epoch 3.0+. + /// --- + /// @default: `3_600` (seconds, 1 hour) + /// @deprecated: This setting is ignored in Epoch 3.0+. + /// @notes: + /// - Units: seconds. pub antientropy_retry: Option, /// Controls whether the node accepts Nakamoto blocks pushed proactively by peers. /// /// - If `true`: Pushed blocks are ignored (logged at DEBUG and discarded). The node will /// still process blocks that it actively downloads. /// - If `false`: Both pushed blocks and actively downloaded blocks are processed. - /// - /// Default: `false`. + /// --- + /// @default: `false` pub reject_blocks_pushed: Option, /// Static list of preferred replica peers for specific StackerDB contracts, provided as a JSON string. /// @@ -3465,44 +3584,34 @@ pub struct ConnectionOptionsFile { /// with a list of preferred neighbor addresses: /// `[[ContractIdentifier, [NeighborAddress, ...]], ...]` /// - /// 1. `ContractIdentifier`: A JSON object representing the `QualifiedContractIdentifier`. + /// 1. `ContractIdentifier`: A JSON object representing the [`QualifiedContractIdentifier`]. /// It must have the specific structure: /// `{"issuer": [version_byte, [byte_array_20]], "name": "contract-name"}` - /// - `version_byte`: The address version byte. - /// - `byte_array_20`: A 20-element array of bytes representing the address. - /// - `name`: The contract name string. - /// - /// 2. `NeighborAddress`: A JSON object specifying the peer details. - /// It must contain: - /// - `ip`: string (The peer's IP address) - /// - `port`: number (The peer's P2P port) - /// - `public_key_hash`: string (The peer's 20-byte public key hash, hex-encoded) - /// - /// Example JSON structure expected within the TOML string value: - /// ```toml - /// stackerdb_hint_replicas = ''' - /// [ + /// 2. `NeighborAddress`: A JSON object specifying the peer details: + /// `{"ip": "...", "port": ..., "public_key_hash": "..."}` + /// --- + /// @default: `None` (no hints provided) + /// @notes: + /// - Use this option with caution, primarily for advanced testing or bootstrapping. + /// @toml_example: | + /// stackerdb_hint_replicas = ''' /// [ - /// { - /// "issuer": [1, [1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1]], - /// "name": "my-contract" - /// }, /// [ /// { - /// "ip": "192.0.2.1", - /// "port": 20444, - /// "public_key_hash": "0102030405060708090a0b0c0d0e0f1011121314" - /// } + /// "issuer": [1, [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20]], + /// "name": "my-contract" + /// }, + /// [ + /// { + /// "ip": "192.0.2.1", + /// "port": 20444, + /// "public_key_hash": "0102030405060708090a0b0c0d0e0f1011121314" + /// } + /// ] /// ] /// ] - /// ] - /// ''' - /// ``` - /// - /// Use this option with caution, primarily for advanced testing or bootstrapping. - /// - /// Default: `None` (no hints provided). + /// ''' pub stackerdb_hint_replicas: Option, /// Maximum age (in seconds) allowed for a block proposal received via the `/v3/block_proposal` RPC endpoint. /// @@ -3510,8 +3619,10 @@ pub struct ConnectionOptionsFile { /// the current time minus this configured value, the node will reject the proposal /// with an HTTP 422 (Unprocessable Entity) error, considering it too stale. /// This prevents the node from spending resources validating outdated proposals. - /// - /// Default: 600 seconds (10 minutes). + /// --- + /// @default: [`DEFAULT_BLOCK_PROPOSAL_MAX_AGE_SECS`] (seconds) + /// @notes: + /// - Units: seconds. pub block_proposal_max_age_secs: Option, } @@ -3825,11 +3936,11 @@ pub struct FeeEstimationConfigFile { /// tracks the highest observed costs for each operation type and uses the average /// of the top 10 values as its estimate, providing a conservative approach to /// cost estimation. - /// - /// If not specified, or if [`FeeEstimationConfigFile::disabled`] is `true`, - /// the node will use the default cost estimator. - /// - /// Default: `"NaivePessimistic"` + /// --- + /// @default: `"NaivePessimistic"` + /// @notes: + /// - If [`FeeEstimationConfigFile::disabled`] is `true`, the node will + /// use the default unit cost estimator. pub cost_estimator: Option, /// Specifies the name of the fee estimator to use. /// This controls how the node calculates appropriate transaction fees based on costs. @@ -3840,11 +3951,11 @@ pub struct FeeEstimationConfigFile { /// - `"FuzzedWeightedMedianFeeRate"`: Fee estimation that adds controlled randomness /// to a weighted median rate calculator. This helps prevent fee optimization attacks /// by adding unpredictability to fee estimates while still maintaining accuracy. - /// - /// If not specified, or if [`FeeEstimationConfigFile::disabled`] is `true`, - /// the node will use the default fee estimator. - /// - /// Default: `"ScalarFeeRate"` + /// --- + /// @default: `"ScalarFeeRate"` + /// @notes: + /// - If [`FeeEstimationConfigFile::disabled`] is `true`, the node will + /// use the default unit fee estimator. pub fee_estimator: Option, /// Specifies the name of the cost metric to use. /// This controls how the node measures and compares transaction costs. @@ -3853,11 +3964,11 @@ pub struct FeeEstimationConfigFile { /// - `"ProportionDotProduct"`: The only currently supported cost metric. This metric /// computes a weighted sum of cost dimensions (runtime, read/write counts, etc.) /// proportional to how much of the block limit they consume. - /// - /// If not specified, or if [`FeeEstimationConfigFile::disabled`] is `true`, - /// the node will use the default cost metric. - /// - /// Default: `"ProportionDotProduct"` + /// --- + /// @default: `"ProportionDotProduct"` + /// @notes: + /// - If [`FeeEstimationConfigFile::disabled`] is `true`, the node will + /// use the default unit cost metric. pub cost_metric: Option, /// If `true`, all fee and cost estimation features are disabled. /// The node will use unit estimators and metrics, which effectively @@ -3870,16 +3981,16 @@ pub struct FeeEstimationConfigFile { /// 4. Consider only raw transaction fees (not fees per cost unit) when assembling blocks /// /// This setting takes precedence over individual estimator/metric configurations. - /// When `true`, the values for [`FeeEstimationConfigFile::cost_estimator`], - /// [`FeeEstimationConfigFile::fee_estimator`], and [`FeeEstimationConfigFile::cost_metric`] - /// are ignored and treated as `None`. - /// - /// Default: `false` + /// --- + /// @default: `false` + /// @notes: + /// - When `true`, the values for [`FeeEstimationConfigFile::cost_estimator`], + /// [`FeeEstimationConfigFile::fee_estimator`], and [`FeeEstimationConfigFile::cost_metric`] are ignored. pub disabled: Option, /// If `true`, errors encountered during cost or fee estimation will be logged. /// This can help diagnose issues with the fee estimation subsystem. - /// - /// Default: `false` + /// --- + /// @default: `false` pub log_error: Option, /// Specifies the fraction of random noise to add if using the `FuzzedWeightedMedianFeeRate` fee estimator. /// This value should be in the range [0, 1], representing a percentage of the base fee rate. @@ -3887,14 +3998,13 @@ pub struct FeeEstimationConfigFile { /// For example, with a value of 0.1 (10%), fee rate estimates will have random noise added /// within the range of ±10% of the original estimate. This randomization makes it difficult /// for users to precisely optimize their fees while still providing reasonable estimates. - /// - /// This setting is only relevant when [`FeeEstimationConfigFile::fee_estimator`] is set to - /// `"FuzzedWeightedMedianFeeRate"`. It controls how much randomness is introduced in the - /// fee estimation process to prevent fee optimization attacks. - /// - /// Default: `0.1` (10%) + /// --- + /// @default: `0.1` (10%) + /// @notes: + /// - This setting is only relevant when [`FeeEstimationConfigFile::fee_estimator`] is set to + /// `"FuzzedWeightedMedianFeeRate"`. pub fee_rate_fuzzer_fraction: Option, - /// Specifies the window size for the [`WeightedMedianFeeRateEstimator`]. + /// Specifies the window size for the `WeightedMedianFeeRateEstimator`. /// This determines how many historical fee rate data points are considered /// when calculating the median fee rate. /// @@ -3903,11 +4013,11 @@ pub struct FeeEstimationConfigFile { /// responsive to recent fee rate changes but potentially more volatile. A larger /// window size (e.g., 10) produces more stable estimates but may be slower to /// adapt to rapid network changes. - /// - /// This setting is primarily relevant when [`FeeEstimationConfigFile::fee_estimator`] is set to - /// `"FuzzedWeightedMedianFeeRate"`, as it's used by the underlying [`WeightedMedianFeeRateEstimator`]. - /// - /// Default: `5` + /// --- + /// @default: `5` + /// @notes: + /// - This setting is primarily relevant when [`FeeEstimationConfigFile::fee_estimator`] is set to + /// `"FuzzedWeightedMedianFeeRate"`, as it's used by the underlying [`WeightedMedianFeeRateEstimator`]. pub fee_rate_window_size: Option, } @@ -4171,16 +4281,16 @@ pub struct EventObserverConfigFile { /// specific event path (e.g., `/new_block`, `/new_mempool_tx`). /// Therefore, this value should be specified as `hostname:port` (e.g., "localhost:3700"). /// - /// **Do NOT include the `http://` scheme in this configuration value.** - /// /// This should point to a service capable of receiving and processing Stacks event data. - /// - /// Default: No default. This field is required. + /// --- + /// @default: No default. This field is required. + /// @notes: + /// - **Do NOT include the `http://` scheme in this configuration value.** + /// @toml_example: | + /// endpoint = "localhost:3700" pub endpoint: String, /// List of event types that this observer is configured to receive. /// - /// For a more detailed documentation check the event-dispatcher docs in the `/docs` folder. - /// /// Each string in the list specifies an event category or a specific event to subscribe to. /// For an observer to receive any notifications, this list must contain at least one valid key. /// Providing an invalid string that doesn't match any of the valid formats below will cause @@ -4189,67 +4299,63 @@ pub struct EventObserverConfigFile { /// All observers, regardless of their `events_keys` configuration, implicitly receive /// payloads on the `/attachments/new` endpoint. /// - /// **Valid Event Keys:** - /// + /// Valid Event Keys: /// - `"*"`: Subscribes to a broad set of common events. - /// - **Events delivered to:** + /// - Events delivered to: /// - `/new_block`: For blocks containing transactions that generate STX, FT, NFT, or smart contract events. - /// - `/new_microblocks`: For all new microblock streams. **Note:** Only until epoch 2.5. + /// - `/new_microblocks`: For all new microblock streams. Note: Only until epoch 2.5. /// - `/new_mempool_tx`: For new mempool transactions. /// - `/drop_mempool_tx`: For dropped mempool transactions. /// - `/new_burn_block`: For new burnchain blocks. - /// - **Note:** This key does NOT by itself subscribe to `/stackerdb_chunks` or `/proposal_response`. + /// - Note: This key does NOT by itself subscribe to `/stackerdb_chunks` or `/proposal_response`. /// /// - `"stx"`: Subscribes to STX token operation events (transfer, mint, burn, lock). - /// - **Events delivered to:** `/new_block`, `/new_microblocks`. - /// - **Payload details:** The "events" array in the delivered payloads will be filtered to include only STX-related events. + /// - Events delivered to: `/new_block`, `/new_microblocks`. + /// - Payload details: The "events" array in the delivered payloads will be filtered to include only STX-related events. /// /// - `"memtx"`: Subscribes to new and dropped mempool transaction events. - /// - **Events delivered to:** `/new_mempool_tx`, `/drop_mempool_tx`. + /// - Events delivered to: `/new_mempool_tx`, `/drop_mempool_tx`. /// /// - `"burn_blocks"`: Subscribes to new burnchain block events. - /// - **Events delivered to:** `/new_burn_block`. + /// - Events delivered to: `/new_burn_block`. /// /// - `"microblocks"`: Subscribes to new microblock stream events. - /// - **Events delivered to:** `/new_microblocks`. - /// - **Payload details:** + /// - Events delivered to: `/new_microblocks`. + /// - Payload details: /// - The "transactions" field will contain all transactions from the microblocks. /// - The "events" field will contain STX, FT, NFT, or specific smart contract events /// *only if* this observer is also subscribed to those more specific event types /// (e.g., via `"stx"`, `"*"`, a specific contract event key, or a specific asset identifier key). - /// - **Note:** Only until epoch 2.5. + /// - Note: Only until epoch 2.5. /// /// - `"stackerdb"`: Subscribes to StackerDB chunk update events. - /// - **Events delivered to:** `/stackerdb_chunks`. + /// - Events delivered to: `/stackerdb_chunks`. /// /// - `"block_proposal"`: Subscribes to block proposal response events (for Nakamoto consensus). - /// - **Events delivered to:** `/proposal_response`. + /// - Events delivered to: `/proposal_response`. /// - /// - **Smart Contract Event**: Subscribes to a specific smart contract event. - /// - **Format:** `"{contract_address}.{contract_name}::{event_name}"` + /// - Smart Contract Event: Subscribes to a specific smart contract event. + /// - Format: `"{contract_address}.{contract_name}::{event_name}"` /// (e.g., `ST0000000000000000000000000000000000000000.my-contract::my-custom-event`) - /// - **Events delivered to:** `/new_block`, `/new_microblocks`. - /// - **Payload details:** The "events" array in the delivered payloads will be filtered for this specific event. + /// - Events delivered to: `/new_block`, `/new_microblocks`. + /// - Payload details: The "events" array in the delivered payloads will be filtered for this specific event. /// - /// - **Asset Identifier for FT/NFT Events**: Subscribes to events (mint, burn, transfer) for a specific Fungible Token (FT) or Non-Fungible Token (NFT). - /// - **Format:** `"{contract_address}.{contract_name}.{asset_name}"` + /// - Asset Identifier for FT/NFT Events: Subscribes to events (mint, burn, transfer) for a specific Fungible Token (FT) or Non-Fungible Token (NFT). + /// - Format: `"{contract_address}.{contract_name}.{asset_name}"` /// (e.g., for an FT: `ST0000000000000000000000000000000000000000.my-ft-contract.my-fungible-token`) - /// - **Events delivered to:** `/new_block`, `/new_microblocks`. - /// - **Payload details:** The "events" array in the delivered payloads will be filtered for events related to the specified asset. - /// - /// **Configuration:** - /// - /// ```toml - /// # Example events_keys in TOML configuration: - /// events_keys = [ - /// "burn_blocks", - /// "memtx", - /// "ST0000000000000000000000000000000000000000.my-contract::my-custom-event", # Smart contract event - /// "ST0000000000000000000000000000000000000000.token-contract.my-ft" # Fungible token asset event - /// ] - /// ``` - /// - /// Default: No default. This field is required. + /// - Events delivered to: `/new_block`, `/new_microblocks`. + /// - Payload details: The "events" array in the delivered payloads will be filtered for events related to the specified asset. + /// --- + /// @default: No default. This field is required. + /// @notes: + /// - For a more detailed documentation check the event-dispatcher docs in the `/docs` folder. + /// @toml_example: | + /// events_keys = [ + /// "burn_blocks", + /// "memtx", + /// "ST0000000000000000000000000000000000000000.my-contract::my-custom-event", + /// "ST0000000000000000000000000000000000000000.token-contract.my-ft" + /// ] pub events_keys: Vec, /// Maximum duration (in milliseconds) to wait for the observer endpoint to respond. /// @@ -4257,8 +4363,10 @@ pub struct EventObserverConfigFile { /// for a successful HTTP response (status code 200) before considering the request timed out. /// If a timeout occurs and retries are enabled (see [`EventObserverConfig::disable_retries`]), /// the request will be attempted again according to the retry strategy. - /// - /// Default: `1_000` ms (1 second). + /// --- + /// @default: `1_000` (ms, 1 second) + /// @notes: + /// - Units: milliseconds. pub timeout_ms: Option, /// Controls whether the node should retry sending event notifications if delivery fails or times out. /// @@ -4271,12 +4379,10 @@ pub struct EventObserverConfigFile { /// - If `true`: The node will make only a single attempt to deliver each event notification. /// If this single attempt fails for any reason, the event is discarded, and no further retries /// will be made for that specific event. - /// - /// **Warning:** Setting this to `true` can lead to missed events if the observer endpoint is - /// temporarily unavailable or experiences issues. This setting should only be used for observers - /// where completeness of the event history is not critical. - /// - /// Default: `false` (retries are enabled). + /// --- + /// @default: `false` (retries are enabled) + /// @notes: + /// - **Warning:** Setting this to `true` can lead to missed events if the observer endpoint is temporarily unavailable or experiences issues. pub disable_retries: Option, } @@ -4381,13 +4487,15 @@ pub struct InitialBalance { pub struct InitialBalanceFile { /// The Stacks address to receive the initial STX balance. /// Must be a valid "non-mainnet" Stacks address (e.g., "ST2QKZ4FKHAH1NQKYKYAYZPY440FEPK7GZ1R5HBP2"). - /// - /// Default: No default. This field is required. + /// --- + /// @default: No default. This field is required. pub address: String, /// The amount of microSTX to allocate to the address at node startup. - /// 1 STX = 1_000_000 microSTX. - /// - /// Default: No default. This field is required. + /// 1 STX = 1,000,000 microSTX. + /// --- + /// @default: No default. This field is required. + /// @notes: + /// - Units: microSTX. pub amount: u64, } From e8cc2a20c5bb82d253cfc737509a6d1ab2da5217 Mon Sep 17 00:00:00 2001 From: Francesco Leacche Date: Wed, 4 Jun 2025 14:19:07 +0100 Subject: [PATCH 2/8] adopt new formatting --- stackslib/src/config/mod.rs | 423 +++++++++++++++++------------------- 1 file changed, 197 insertions(+), 226 deletions(-) diff --git a/stackslib/src/config/mod.rs b/stackslib/src/config/mod.rs index 97d974cab2..260605614e 100644 --- a/stackslib/src/config/mod.rs +++ b/stackslib/src/config/mod.rs @@ -1238,7 +1238,7 @@ pub struct BurnchainConfig { /// The underlying blockchain used for Proof-of-Transfer. /// --- /// @default: `"bitcoin"` - /// @notes: + /// @notes: | /// - Currently, only `"bitcoin"` is supported. pub chain: String, /// The operational mode or network profile for the Stacks node. @@ -1246,33 +1246,33 @@ pub struct BurnchainConfig { /// default configurations, genesis block definitions, and overall node behavior. /// /// Supported values: - /// - `"mainnet"` → mainnet - /// - `"xenon"` → testnet - /// - `"mocknet"` → regtest - /// - `"helium"` → regtest - /// - `"neon"` → regtest - /// - `"argon"` → regtest - /// - `"krypton"` → regtest - /// - `"nakamoto-neon"` → regtest + /// - `"mainnet"`: mainnet + /// - `"xenon"`: testnet + /// - `"mocknet"`: regtest + /// - `"helium"`: regtest + /// - `"neon"`: regtest + /// - `"argon"`: regtest + /// - `"krypton"`: regtest + /// - `"nakamoto-neon"`: regtest /// --- /// @default: `"mocknet"` pub mode: String, /// The network-specific identifier used in P2P communication and database initialization. /// --- - /// @default: + /// @default: | /// - [`CHAIN_ID_MAINNET`] if [`BurnchainConfig::mode`] is `"mainnet"` /// - [`CHAIN_ID_TESTNET`] otherwise - /// @notes: + /// @notes: | /// - **Warning:** Do not modify this unless you really know what you're doing. /// - This is intended strictly for testing purposes. pub chain_id: u32, /// The peer protocol version number used in P2P communication. /// This parameter cannot be set via the configuration file. /// --- - /// @default: + /// @default: | /// - [`PEER_VERSION_MAINNET`] if [`BurnchainConfig::mode`] is `"mainnet"` /// - [`PEER_VERSION_TESTNET`] otherwise - /// @notes: + /// @notes: | /// - **Warning:** Do not modify this unless you really know what you're doing. pub peer_version: u32, /// Specifies a mandatory wait period (in milliseconds) after receiving a burnchain tip @@ -1280,10 +1280,10 @@ pub struct BurnchainConfig { /// This duration effectively schedules the start of the block-building /// process relative to the tip's arrival time. /// --- - /// @default: `5_000` (milliseconds) - /// @notes: + /// @default: `5_000` + /// @units: milliseconds + /// @notes: | /// - This is intended strictly for testing purposes. - /// - Units: milliseconds. pub commit_anchor_block_within: u64, /// The maximum amount (in sats) of "burn commitment" to broadcast for the next block's leader election. /// Acts as a safety cap to limit the maximum amount spent on mining. @@ -1291,10 +1291,10 @@ pub struct BurnchainConfig { /// /// This setting can be hot-reloaded from the config file, allowing adjustment without restarting. /// --- - /// @default: `20_000` (satoshis) - /// @notes: + /// @default: `20_000` + /// @units: satoshis + /// @notes: | /// - Only relevant if [`NodeConfig::miner`] is `true`. - /// - Units: satoshis. pub burn_fee_cap: u64, /// The hostname or IP address of the bitcoin node peer. /// @@ -1319,22 +1319,21 @@ pub struct BurnchainConfig { /// Required if the bitcoin node requires RPC authentication. /// --- /// @default: `None` - /// @notes: + /// @notes: | /// - Only relevant if [`NodeConfig::miner`] is `true`. pub username: Option, /// The password for authenticating with the bitcoin node's RPC interface. /// Required if the bitcoin node requires RPC authentication. /// --- /// @default: `None` - /// @notes: + /// @notes: | /// - Only relevant if [`NodeConfig::miner`] is `true`. pub password: Option, /// Timeout duration, in seconds, for RPC calls made to the bitcoin node. /// Configures the timeout on the underlying HTTP client. /// --- - /// @default: `60` (seconds) - /// @notes: - /// - Units: seconds + /// @default: `60` + /// @units: seconds pub timeout: u32, /// The network "magic bytes" used to identify packets for the specific bitcoin network /// instance (e.g., mainnet, testnet, regtest). Must match the magic bytes of the connected @@ -1348,7 +1347,7 @@ pub struct BurnchainConfig { /// /// Configured as a 2-character ASCII string (e.g., "X2" for mainnet). /// --- - /// @default: + /// @default: | /// - `"T2"` if [`BurnchainConfig::mode`] is `"xenon"` /// - `"X2"` otherwise pub magic_bytes: MagicBytes, @@ -1363,7 +1362,7 @@ pub struct BurnchainConfig { /// when generating blocks on the regtest network. /// --- /// @default: `None` - /// @notes: + /// @notes: | /// - Mandatory if [`BurnchainConfig::mode`] is "helium". /// - This is intended strictly for testing purposes. pub local_mining_public_key: Option, @@ -1371,7 +1370,7 @@ pub struct BurnchainConfig { /// When bitcoin reaches this height, the node logs a message and initiates a graceful shutdown. /// --- /// @default: `None` - /// @notes: + /// @notes: | /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". /// - This is intended strictly for testing purposes. pub process_exit_at_block_height: Option, @@ -1380,58 +1379,58 @@ pub struct BurnchainConfig { /// The default value of 10 seconds is mainly intended for testing purposes. /// It's suggested to set this to a higher value for mainnet, e.g., 300 seconds (5 minutes). /// --- - /// @default: `10` (seconds) - /// @notes: - /// - Units: seconds + /// @default: `10` + /// @units: seconds pub poll_time_secs: u64, - /// The default fee rate in satoshis per virtual byte (sats/vB) to use when estimating fees for miners + /// The default fee rate in sats/vByte to use when estimating fees for miners /// to submit bitcoin transactions (like block commits or leader key registrations). /// --- - /// @default: [`DEFAULT_SATS_PER_VB`] (satoshis per virtual byte) - /// @notes: + /// @default: [`DEFAULT_SATS_PER_VB`] + /// @units: sats/vByte + /// @notes: | /// - Only relevant if [`NodeConfig::miner`] is `true`. - /// - Units: satoshis per virtual byte. pub satoshis_per_byte: u64, /// Maximum fee rate multiplier allowed when using Replace-By-Fee (RBF) for bitcoin transactions. /// Expressed as a percentage of the original [`BurnchainConfig::satoshis_per_byte`] rate (e.g., /// 150 means the fee rate can be increased up to 1.5x). Used in mining logic for RBF decisions /// to cap the replacement fee rate. /// --- - /// @default: [`DEFAULT_MAX_RBF_RATE`] (%) - /// @notes: + /// @default: [`DEFAULT_MAX_RBF_RATE`] + /// @units: percent + /// @notes: | /// - Only relevant if [`NodeConfig::miner`] is `true`. pub max_rbf: u64, /// Estimated size (in virtual bytes) of a leader key registration transaction on bitcoin. /// Used for fee calculation in mining logic by multiplying with the fee rate /// [`BurnchainConfig::satoshis_per_byte`]. /// --- - /// @default: [`OP_TX_LEADER_KEY_ESTIM_SIZE`] (virtual bytes) - /// @notes: + /// @default: [`OP_TX_LEADER_KEY_ESTIM_SIZE`] + /// @units: virtual bytes + /// @notes: | /// - Only relevant if [`NodeConfig::miner`] is `true`. - /// - Units: virtual bytes. pub leader_key_tx_estimated_size: u64, /// Estimated size (in virtual bytes) of a block commit transaction on bitcoin. /// Used for fee calculation in mining logic by multiplying with the fee rate /// [`BurnchainConfig::satoshis_per_byte`]. /// --- - /// @default: [`OP_TX_BLOCK_COMMIT_ESTIM_SIZE`] (virtual bytes) - /// @notes: + /// @default: [`OP_TX_BLOCK_COMMIT_ESTIM_SIZE`] + /// @units: virtual bytes + /// @notes: | /// - Only relevant if [`NodeConfig::miner`] is `true`. - /// - Units: virtual bytes. pub block_commit_tx_estimated_size: u64, - /// The incremental amount (in Sats/vByte) to add to the previous transaction's + /// The incremental amount (in sats/vByte) to add to the previous transaction's /// fee rate for RBF bitcoin transactions. /// --- - /// @default: [`DEFAULT_RBF_FEE_RATE_INCREMENT`] (satoshis per virtual byte) - /// @notes: + /// @default: [`DEFAULT_RBF_FEE_RATE_INCREMENT`] + /// @units: sats/vByte + /// @notes: | /// - Only relevant if [`NodeConfig::miner`] is `true`. - /// - Units: satoshis per virtual byte. pub rbf_fee_increment: u64, /// Overrides the default starting bitcoin block height for the node. /// Allows starting synchronization from a specific historical point in test environments. /// --- /// @default: `None` (uses the burnchain's default starting height for the mode) - /// @notes: + /// @notes: | /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". /// - This is intended strictly for testing purposes. /// - Should be used together with [`BurnchainConfig::first_burn_block_timestamp`] and @@ -1440,7 +1439,7 @@ pub struct BurnchainConfig { /// Overrides the default starting block timestamp of the burnchain. /// --- /// @default: `None` (uses the burnchain's default starting timestamp) - /// @notes: + /// @notes: | /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". /// - This is intended strictly for testing purposes. /// - Should be used together with [`BurnchainConfig::first_burn_block_height`] and @@ -1449,7 +1448,7 @@ pub struct BurnchainConfig { /// Overrides the default starting block hash of the burnchain. /// --- /// @default: `None` (uses the burnchain's default starting block hash) - /// @notes: + /// @notes: | /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". /// - This is intended strictly for testing purposes. /// - Should be used together with [`BurnchainConfig::first_burn_block_height`] and @@ -1472,7 +1471,7 @@ pub struct BurnchainConfig { /// - The number of defined epochs cannot exceed the maximum supported by the node software. /// --- /// @default: `None` (uses the standard epoch definitions for the selected [`BurnchainConfig::mode`]) - /// @notes: + /// @notes: | /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". /// - This is intended strictly for testing purposes. /// - Configured as a list `[[burnchain.epochs]]` in TOML, each with `epoch_name` (string) @@ -1500,25 +1499,25 @@ pub struct BurnchainConfig { /// - However, the height specified in `epochs` for Epoch 2.1 takes precedence. /// --- /// @default: `None` - /// @notes: + /// @notes: | /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". /// - This is intended strictly for testing purposes. pub pox_2_activation: Option, /// Overrides the length (in bitcoin blocks) of the PoX reward cycle. /// --- /// @default: `None` (uses the standard reward cycle length for the mode) - /// @notes: + /// @units: bitcoin blocks + /// @notes: | /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". /// - This is intended strictly for testing purposes. - /// - Units: bitcoin blocks. pub pox_reward_length: Option, /// Overrides the length (in bitcoin blocks) of the PoX prepare phase. /// --- /// @default: `None` (uses the standard prepare phase length for the mode) - /// @notes: + /// @units: bitcoin blocks + /// @notes: | /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". /// - This is intended strictly for testing purposes. - /// - Units: bitcoin blocks. pub pox_prepare_length: Option, /// Overrides the bitcoin height at which the PoX sunset period begins in epochs before 2.1. /// The sunset period represents a planned phase-out of the PoX mechanism. During this period, @@ -1528,7 +1527,7 @@ pub struct BurnchainConfig { /// @default: `None` (uses the standard sunset start height for the mode) /// @deprecated: The sunset phase was removed in Epoch 2.1. This parameter can still be used for /// testing purposes for epochs before 2.1. - /// @notes: + /// @notes: | /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". /// - This is intended strictly for testing purposes. pub sunset_start: Option, @@ -1539,7 +1538,7 @@ pub struct BurnchainConfig { /// @default: `None` (uses the standard sunset end height for the mode) /// @deprecated: The sunset phase was removed in Epoch 2.1. This parameter can still be used for /// testing purposes for epochs before 2.1. - /// @notes: + /// @notes: | /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". /// - This is intended strictly for testing purposes. pub sunset_end: Option, @@ -1551,7 +1550,7 @@ pub struct BurnchainConfig { /// separate wallets. /// --- /// @default: `""` (empty string, implying the default wallet or no specific wallet needed) - /// @notes: + /// @notes: | /// - Primarily relevant for miners interacting with multi-wallet Bitcoin nodes. pub wallet_name: String, /// Override for the burnchain height activating stricter AST size checks pre-epoch 3.0 for testing purposes. @@ -1572,7 +1571,7 @@ pub struct BurnchainConfig { /// --- /// @default: Empty map /// @deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. - /// @notes: + /// @notes: | /// - Primarily used for testing or recovering from network issues. /// - Configured as a list `[[burnchain.affirmation_overrides]]` in TOML, each with /// `reward_cycle` (integer) and `affirmation` (string of 'p'/'n'/'a', length `reward_cycle - 1`). @@ -1585,9 +1584,9 @@ pub struct BurnchainConfig { /// before processing each burnchain block download. Simulates a slow burnchain connection. /// --- /// @default: `0` (no delay) - /// @notes: + /// @units: milliseconds + /// @notes: | /// - This is intended strictly for testing purposes. - /// - Units: milliseconds. pub fault_injection_burnchain_block_delay: u64, /// The maximum number of unspent transaction outputs (UTXOs) to request from the bitcoin node. /// @@ -1601,7 +1600,7 @@ pub struct BurnchainConfig { /// for a transaction, even if sufficient funds exist across more UTXOs not returned by the limited query. /// --- /// @default: `1024` - /// @notes: + /// @notes: | /// - This value must be `<= 1024`. /// - Only relevant if [`NodeConfig::miner`] is `true`. pub max_unspent_utxos: Option, @@ -2016,7 +2015,7 @@ pub struct NodeConfig { /// If [`MinerConfig::mining_key`] is not set, this seed may also be used for mining-related signing. /// --- /// @default: Randomly generated 32 bytes - /// @notes: + /// @notes: | /// - Required if [`NodeConfig::miner`] is `true` and [`MinerConfig::mining_key`] is absent. pub seed: Vec, /// The file system absolute path to the node's working directory. @@ -2025,7 +2024,7 @@ pub struct NodeConfig { /// This path can be overridden by setting the `STACKS_WORKING_DIR` environment variable. /// --- /// @default: `/tmp/stacks-node-{current_timestamp}` - /// @notes: + /// @notes: | /// - For persistent mainnet or testnet nodes, this path must be explicitly configured to /// a non-temporary location. pub working_dir: String, @@ -2048,7 +2047,7 @@ pub struct NodeConfig { /// This might differ from [`NodeConfig::p2p_bind`] if the node is behind NAT or a proxy. /// --- /// @default: Derived from [`NodeConfig::rpc_bind`] (e.g., "0.0.0.0:20443" if [`NodeConfig::rpc_bind`] is default). - /// @notes: + /// @notes: | /// - The default value derivation might be unexpected, potentially using the /// [`NodeConfig::rpc_bind`] address; explicit configuration is recommended if needed. pub p2p_address: String, @@ -2065,7 +2064,7 @@ pub struct NodeConfig { /// --- /// @default: `[]` (empty vector) /// @toml_example: | - /// bootstrap_node = "029266faff4c8e0ca4f934f34996a96af481df94a89b0c9bd515f3536a95682ddc@seed.testnet.hiro.so:30444,02196f005965cebe6ddc3901b7b1cc1aa7a88f305bb8c5893456b8f9a605923893@seed.mainnet.hiro.so:20444" + /// bootstrap_node = "pubkey1@example.com:30444,pubkey2@192.168.1.100:20444" pub bootstrap_node: Vec, /// 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" @@ -2092,7 +2091,7 @@ pub struct NodeConfig { /// real bitcoin consensus or P2P block production process. /// --- /// @default: `false` - /// @notes: + /// @notes: | /// - Only relevant if [`NodeConfig::miner`] is `true`. pub mock_mining: bool, /// If [`NodeConfig::mock_mining`] is enabled, this specifies an optional directory path where the @@ -2109,11 +2108,11 @@ pub struct NodeConfig { pub mine_microblocks: bool, /// How often to attempt producing microblocks, in milliseconds. /// --- - /// @default: `30_000` (milliseconds, 30 seconds) + /// @default: `30_000` (30 seconds) /// @deprecated: This setting is ignored in Epoch 2.5+. - /// @notes: + /// @notes: | /// - Only applies when [`NodeConfig::mine_microblocks`] is true and before Epoch 2.5. - /// - Units: milliseconds. + /// @units: milliseconds pub microblock_frequency: u64, /// The maximum number of microblocks allowed per Stacks block. /// --- @@ -2122,11 +2121,11 @@ pub struct NodeConfig { pub max_microblocks: u64, /// Cooldown period after a microblock is produced, in milliseconds. /// --- - /// @default: `30_000` (milliseconds, 30 seconds) + /// @default: `30_000` (30 seconds) /// @deprecated: This setting is ignored in Epoch 2.5+. - /// @notes: + /// @notes: | /// - Only applies when [`NodeConfig::mine_microblocks`] is true and before Epoch 2.5. - /// - Units: milliseconds. + /// @units: milliseconds 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 @@ -2135,18 +2134,16 @@ pub struct NodeConfig { /// to prevent stalling. This setting is loaded by all nodes but primarily affects /// miner behavior within the relayer thread. /// --- - /// @default: `30_000` (milliseconds, 30 seconds) - /// @notes: - /// - Units: milliseconds. + /// @default: `30_000` (30 seconds) + /// @units: milliseconds pub wait_time_for_blocks: u64, /// 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: `10_000` (milliseconds, 10 seconds) - /// @notes: - /// - Units: milliseconds. + /// @default: `10_000` (10 seconds) + /// @units: milliseconds 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 @@ -2176,17 +2173,16 @@ pub struct NodeConfig { /// 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) + /// @default: `30` + /// @units: seconds /// @deprecated: Unused after the Nakamoto upgrade. This setting is ignored in Epoch 3.0+. - /// @notes: - /// - Units: seconds. 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) - /// @notes: + /// @notes: | /// - This is intended strictly for testing purposes and is disallowed on mainnet. pub use_test_genesis_chainstate: Option, /// Controls if Stacks Epoch 2.1+ affirmation map logic should be applied even before Epoch 2.1. @@ -2205,7 +2201,7 @@ pub struct NodeConfig { /// - 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: + /// @default: | /// - `true` if [`NodeConfig::miner`] is `false` /// - `false` if [`NodeConfig::miner`] is `true` pub require_affirmed_anchor_blocks: bool, @@ -2218,7 +2214,7 @@ pub struct NodeConfig { /// Normal operation requires this to be `true`; setting to `false` will likely break consensus adherence. /// --- /// @default: `true` - /// @notes: + /// @notes: | /// - This parameter cannot be set via the configuration file; it must be modified programmatically. pub assume_present_anchor_blocks: bool, /// Fault injection setting for testing purposes. If set to `Some(p)`, where `p` is between 0 and 100, @@ -2226,7 +2222,7 @@ pub struct NodeConfig { /// to its peers. /// --- /// @default: `None` (no fault injection) - /// @notes: + /// @notes: | /// - Values: 0-100 (percentage). pub fault_injection_block_push_fail_probability: Option, /// Fault injection setting for testing purposes. If `true`, the node's chainstate database @@ -2234,26 +2230,25 @@ pub struct NodeConfig { /// simulating block hiding or data unavailability. /// --- /// @default: `false` - /// @notes: + /// @notes: | /// - This parameter cannot be set via the configuration file; it must be modified programmatically. pub fault_injection_hide_blocks: bool, /// 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) - /// @notes: - /// - Units: seconds. + /// @default: `300` (5 minutes) + /// @units: seconds pub chain_liveness_poll_time_secs: u64, /// A list of specific StackerDB contracts (identified by their qualified contract identifiers, /// e.g., "SP000000000000000000002Q6VF78.pox-3") that this node should actively replicate. /// --- - /// @default: + /// @default: | /// - If [`NodeConfig::miner`] is `true` or [`NodeConfig::stacker`] is `true`, relevant system contracts /// (like `.miners`, `.signers-*`) are automatically added in addition to any contracts /// specified in the configuration file. /// - Otherwise, defaults to an empty list `[]` if not specified in the TOML. - /// @notes: + /// @notes: | /// - Values are strings representing qualified contract identifiers. /// @toml_example: | /// stacker_dbs = ["SP000000000000000000002Q6VF78.pox-3", "SP2C2YFP12AJZB4M4KUPSTMZQR0SNHNPH204SCQJM.stx-oracle-v1"] @@ -2693,33 +2688,29 @@ impl NodeConfig { pub struct MinerConfig { /// Time to wait (in milliseconds) before the first attempt to mine a block. /// --- - /// @default: `10` (ms) + /// @default: `10` + /// @units: milliseconds /// @deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. - /// @notes: - /// - Units: milliseconds. pub first_attempt_time_ms: u64, /// Time to wait (in milliseconds) for subsequent attempts to mine a block, /// after the first attempt fails. /// --- - /// @default: `120_000` (ms, 2 minutes) + /// @default: `120_000` (2 minutes) + /// @units: milliseconds /// @deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. - /// @notes: - /// - Units: milliseconds. pub subsequent_attempt_time_ms: u64, /// Time to wait (in milliseconds) to mine a microblock. /// --- - /// @default: `30_000` (ms, 30 seconds) + /// @default: `30_000` (30 seconds) + /// @units: milliseconds /// @deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. - /// @notes: - /// - Units: milliseconds. pub microblock_attempt_time_ms: u64, /// Maximum time (in milliseconds) the miner spends selecting transactions from the mempool /// when assembling a Nakamoto block. Once this duration is exceeded, the miner stops /// adding transactions and finalizes the block with those already selected. /// --- - /// @default: `5_000` (ms, 5 seconds) - /// @notes: - /// - Units: milliseconds. + /// @default: `5_000` (5 seconds) + /// @units: milliseconds pub nakamoto_attempt_time_ms: u64, /// Strategy for selecting the next transaction candidate from the mempool. /// Controls prioritization between maximizing immediate fee capture vs. ensuring @@ -2743,7 +2734,8 @@ pub struct MinerConfig { /// 100 means always prioritize them first (if available). /// --- /// @default: `25` (25% chance) - /// @notes: + /// @units: percent + /// @notes: | /// - Values: 0-100. pub probability_pick_no_estimate_tx: u8, /// Optional recipient for the coinbase block reward, overriding the default miner address. @@ -2770,10 +2762,10 @@ pub struct MinerConfig { /// state (MARF trie). A larger cache can improve performance for workloads involving /// many unique accounts but increases memory consumption. /// --- - /// @default: `1048576` (bytes, 1 MiB) - /// @notes: + /// @default: `1048576` (1 MiB) + /// @units: bytes + /// @notes: | /// - Must be configured to a value greater than 0. - /// - Units: bytes. pub nonce_cache_size: usize, /// Max size (in *number* of items) of transaction candidates to hold in the in-memory /// retry cache. @@ -2786,22 +2778,22 @@ pub struct MinerConfig { /// A larger cache retains more potentially valid future candidates but uses more memory. /// This setting is primarily relevant for the `GlobalFeeRate` strategy. /// --- - /// @default: `1048576` (items) - /// @notes: - /// - Units: number of items (Each element [`crate::core::mempool::MemPoolTxInfoPartial`] is currently 112 bytes). + /// @default: `1048576` + /// @units: items + /// @notes: | + /// - Each element [`crate::core::mempool::MemPoolTxInfoPartial`] is currently 112 bytes. pub candidate_retry_cache_size: usize, /// Amount of time (in seconds) to wait for unprocessed blocks before mining a new block. /// --- - /// @default: `30` (seconds) + /// @default: `30` + /// @units: seconds /// @deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. - /// @notes: - /// - Units: seconds. pub unprocessed_block_deadline_secs: u64, /// The private key (Secp256k1) used for signing blocks, provided as a hex string. /// /// This key must be present at runtime for mining operations to succeed. /// --- - /// @default: + /// @default: | /// - [`NodeConfig::seed`] if the `[miner]` section *is present* in the config file /// - `None` if the `[miner]` section *is not present* pub mining_key: Option, @@ -2941,7 +2933,7 @@ pub struct MinerConfig { /// --- /// @default: `false` (Should only default true if [`MinerConfig::mining_key`] is set). /// @deprecated: This setting is ignored in Epoch 3.0+. - /// @notes: + /// @notes: | /// - This is intended strictly for testing purposes for Epoch 2.5 conditions. pub pre_nakamoto_mock_signing: bool, /// The minimum time to wait between mining blocks in milliseconds. The value must be greater @@ -2951,9 +2943,8 @@ pub struct MinerConfig { /// This check ensures compliance with signer rules that prevent blocks with identical timestamps /// (at second resolution) to their parents. If a lower value is configured, 1000 ms is used instead. /// --- - /// @default: [`DEFAULT_MIN_TIME_BETWEEN_BLOCKS_MS`] (ms) - /// @notes: - /// - Units: milliseconds. + /// @default: [`DEFAULT_MIN_TIME_BETWEEN_BLOCKS_MS`] + /// @units: milliseconds pub min_time_between_blocks_ms: u64, /// The amount of time in milliseconds that the miner should sleep in between attempts to /// mine a block when the mempool is empty. @@ -2961,18 +2952,16 @@ pub struct MinerConfig { /// This prevents the miner from busy-looping when there are no pending transactions, /// conserving CPU resources. During this sleep, the miner still checks burnchain tip changes. /// --- - /// @default: [`DEFAULT_EMPTY_MEMPOOL_SLEEP_MS`] (ms) - /// @notes: - /// - Units: milliseconds. + /// @default: [`DEFAULT_EMPTY_MEMPOOL_SLEEP_MS`] + /// @units: milliseconds pub empty_mempool_sleep_time: Duration, /// Time in milliseconds to pause after receiving the first threshold rejection, before proposing a new block. /// /// When a miner's block proposal fails to gather enough signatures from the signers for the first time /// at a given height, the miner will pause for this duration before attempting to mine and propose again. /// --- - /// @default: [`DEFAULT_FIRST_REJECTION_PAUSE_MS`] (ms) - /// @notes: - /// - Units: milliseconds. + /// @default: [`DEFAULT_FIRST_REJECTION_PAUSE_MS`] + /// @units: milliseconds pub first_rejection_pause_ms: u64, /// Time in milliseconds to pause after receiving subsequent threshold rejections, before proposing a new block. /// @@ -2980,9 +2969,8 @@ pub struct MinerConfig { /// this potentially longer pause duration is used before retrying. This gives more significant time /// for network state changes or signer coordination. /// --- - /// @default: [`DEFAULT_SUBSEQUENT_REJECTION_PAUSE_MS`] (ms) - /// @notes: - /// - Units: milliseconds. + /// @default: [`DEFAULT_SUBSEQUENT_REJECTION_PAUSE_MS`] + /// @units: milliseconds pub subsequent_rejection_pause_ms: u64, /// Time in milliseconds to wait for a Nakamoto block after seeing a burnchain block before submitting a block commit. /// @@ -2993,9 +2981,8 @@ pub struct MinerConfig { /// to be replaced via RBF if a new Stacks block appears shortly after. /// This delay is skipped if the new burnchain blocks leading to the tip contain no sortitions. /// --- - /// @default: [`DEFAULT_BLOCK_COMMIT_DELAY_MS`] (ms) - /// @notes: - /// - Units: milliseconds. + /// @default: [`DEFAULT_BLOCK_COMMIT_DELAY_MS`] + /// @units: milliseconds pub block_commit_delay: Duration, /// The percentage of the remaining tenure cost limit to consume each block. /// @@ -3005,9 +2992,10 @@ pub struct MinerConfig { /// This allows miners to spread the tenure's total execution budget across multiple blocks rather than /// potentially consuming it all in the first block. /// --- - /// @default: [`DEFAULT_TENURE_COST_LIMIT_PER_BLOCK_PERCENTAGE`] (%) - /// @notes: - /// - The value must be between 1 and 100, inclusive, if specified. + /// @default: [`DEFAULT_TENURE_COST_LIMIT_PER_BLOCK_PERCENTAGE`] + /// @units: percent + /// @notes: | + /// - Values: 1-100. /// - Setting to 100 effectively disables this per-block limit, allowing a block to use the /// entire remaining tenure budget. pub tenure_cost_limit_per_block_percentage: Option, @@ -3018,9 +3006,8 @@ pub struct MinerConfig { /// (e.g., because a miner thread is already active for the current burn view), it will wait for this /// duration before re-checking the conditions for tenure extension. /// --- - /// @default: [`DEFAULT_TENURE_EXTEND_POLL_SECS`] (seconds) - /// @notes: - /// - Units: seconds. + /// @default: [`DEFAULT_TENURE_EXTEND_POLL_SECS`] + /// @units: seconds pub tenure_extend_poll_timeout: Duration, /// Duration to wait before trying to continue a tenure because the next miner did not produce blocks. /// @@ -3030,9 +3017,8 @@ pub struct MinerConfig { /// Also used in scenarios with empty sortitions to give the winner of the *last valid* sortition time /// to produce a block before the current miner attempts an extension. /// --- - /// @default: [`DEFAULT_TENURE_EXTEND_WAIT_MS`] (ms) - /// @notes: - /// - Units: milliseconds. + /// @default: [`DEFAULT_TENURE_EXTEND_WAIT_MS`] + /// @units: milliseconds pub tenure_extend_wait_timeout: Duration, /// Duration to wait before attempting to issue a time-based tenure extend. /// @@ -3042,9 +3028,8 @@ pub struct MinerConfig { /// indicates an extension is timely, and the cost usage threshold ([`MinerConfig::tenure_extend_cost_threshold`]) /// is met, the miner will include a tenure extension transaction in its next block. /// --- - /// @default: [`DEFAULT_TENURE_TIMEOUT_SECS`] (seconds) - /// @notes: - /// - Units: seconds. + /// @default: [`DEFAULT_TENURE_TIMEOUT_SECS`] + /// @units: seconds pub tenure_timeout: Duration, /// Percentage of block budget that must be used before attempting a time-based tenure extend. /// @@ -3055,8 +3040,9 @@ pub struct MinerConfig { /// the [`MinerConfig::tenure_timeout`] duration has elapsed. /// This prevents miners from extending tenures very early if they have produced only low-cost blocks. /// --- - /// @default: [`DEFAULT_TENURE_EXTEND_COST_THRESHOLD`] (%) - /// @notes: + /// @default: [`DEFAULT_TENURE_EXTEND_COST_THRESHOLD`] + /// @units: percent + /// @notes: | /// - Values: 0-100. pub tenure_extend_cost_threshold: u64, /// Defines adaptive timeouts for waiting for signer responses, based on the accumulated weight of rejections. @@ -3077,7 +3063,7 @@ pub struct MinerConfig { /// A key for 0 (zero rejections) must be defined, representing the initial timeout when no rejections have been received. /// --- /// @default: `{ 0: 180, 10: 90, 20: 45, 30: 0 }` (times in seconds) - /// @notes: + /// @notes: | /// - Keys are rejection weight percentages (0-100). Values are timeout durations. /// @toml_example: | /// # Keys are rejection counts (as strings), values are timeouts in seconds. @@ -3095,8 +3081,7 @@ pub struct MinerConfig { /// from blocking block production. /// --- /// @default: `None` (no execution time limit) - /// @notes: - /// - Units: seconds. + /// @units: seconds pub max_execution_time_secs: Option, /// TODO: remove this option when its no longer a testing feature and it becomes default behaviour /// The miner will attempt to replay transactions that a threshold number of signers are expecting in the next block @@ -3177,18 +3162,16 @@ pub struct ConnectionOptionsFile { /// but does not complete the connection process (e.g., handshake for P2P) within this time, the node /// will consider it unresponsive and drop the connection attempt. /// --- - /// @default: `10` (seconds) - /// @notes: - /// - Units: seconds. + /// @default: `10` + /// @units: seconds pub connect_timeout: Option, /// Maximum duration (in seconds) a P2P peer is allowed after connecting before completing the handshake. /// /// If a P2P peer connects successfully but fails to send the necessary handshake messages /// within this time, the node will consider it unresponsive and drop the connection. /// --- - /// @default: `5` (seconds) - /// @notes: - /// - Units: seconds. + /// @default: `5` + /// @units: seconds pub handshake_timeout: Option, /// General communication timeout (in seconds). /// @@ -3198,9 +3181,8 @@ pub struct ConnectionOptionsFile { /// - Client-side: Sets the timeout duration (TTL) for outgoing HTTP requests initiated by the node itself. /// - For P2P connections: Used as the specific timeout for NAT punch-through requests. /// --- - /// @default: `15` (seconds) - /// @notes: - /// - Units: seconds. + /// @default: `15` + /// @units: seconds pub timeout: Option, /// Maximum idle time (in seconds) for HTTP connections. /// @@ -3209,9 +3191,8 @@ pub struct ConnectionOptionsFile { /// both this `idle_timeout` and the general [`ConnectionOptionsFile::timeout`] (time since last /// request received) are exceeded. /// --- - /// @default: `15` (seconds) - /// @notes: - /// - Units: seconds. + /// @default: `15` + /// @units: seconds pub idle_timeout: Option, /// Interval (in seconds) at which this node expects to send or receive P2P keep-alive messages. /// @@ -3221,9 +3202,8 @@ pub struct ConnectionOptionsFile { /// value to proactively send Ping messages if the connection would otherwise be idle, helping to /// keep it active. /// --- - /// @default: `3_600` (seconds, 1 hour) - /// @notes: - /// - Units: seconds. + /// @default: `3_600` (1 hour) + /// @units: seconds pub heartbeat: Option, /// Validity duration (in number of bitcoin blocks) for the node's P2P session private key. /// @@ -3237,8 +3217,7 @@ pub struct ConnectionOptionsFile { /// This provides periodic key rotation for P2P communication. /// --- /// @default: `9223372036854775807` (i64::MAX, effectively infinite, disabling automatic re-keying). - /// @notes: - /// - Units: bitcoin blocks. + /// @units: bitcoin blocks pub private_key_lifetime: Option, /// Target number of peers for StackerDB replication. /// @@ -3337,9 +3316,8 @@ pub struct ConnectionOptionsFile { /// an up-to-date view of the P2P network topology. This setting controls how frequently /// these walks can be initiated, preventing excessive network traffic and processing. /// --- - /// @default: `60` (seconds) - /// @notes: - /// - Units: seconds. + /// @default: `60` + /// @units: seconds pub walk_interval: Option, /// Probability (0.0 to 1.0) of forcing a neighbor walk to start from a seed/bootstrap peer. /// @@ -3356,9 +3334,8 @@ pub struct ConnectionOptionsFile { /// If set to a non-zero value, the node will periodically log details about its currently /// established P2P connections (neighbors). Setting this to 0 disables this periodic logging. /// --- - /// @default: `60_000` (ms, 1 minute). - /// @notes: - /// - Units: milliseconds. + /// @default: `60_000` (1 minute) + /// @units: milliseconds pub log_neighbors_freq: Option, /// Maximum time (in milliseconds) to wait for a DNS query to resolve. /// @@ -3367,9 +3344,8 @@ pub struct ConnectionOptionsFile { /// This setting defines the maximum duration the node will wait for the DNS server /// to respond before considering the lookup timed out. /// --- - /// @default: `15_000` (ms, 15 seconds). - /// @notes: - /// - Units: milliseconds. + /// @default: `15_000` (15 seconds) + /// @units: milliseconds pub dns_timeout: Option, /// Maximum number of concurrent Nakamoto block download requests allowed. /// @@ -3390,22 +3366,21 @@ pub struct ConnectionOptionsFile { /// Maximum total size (in bytes) of data allowed to be written during a read-only call. /// --- /// @default: `0` - /// @notes: + /// @notes: | /// - This limit is effectively forced to 0 by the API handler, ensuring read-only behavior. /// - Configuring a non-zero value has no effect on read-only call execution. - /// - Units: bytes. + /// @units: bytes pub read_only_call_limit_write_length: Option, /// Maximum total size (in bytes) of data allowed to be read from Clarity data space (variables, maps) /// during a read-only call. /// --- - /// @default: `100_000` (bytes, 100 KB). - /// @notes: - /// - Units: bytes. + /// @default: `100_000` (100 KB). + /// @units: bytes pub read_only_call_limit_read_length: Option, /// Maximum number of distinct write operations allowed during a read-only call. /// --- /// @default: `0` - /// @notes: + /// @notes: | /// - This limit is effectively forced to 0 by the API handler, ensuring read-only behavior. /// - Configuring a non-zero value has no effect on read-only call execution. pub read_only_call_limit_write_count: Option, @@ -3417,9 +3392,8 @@ pub struct ConnectionOptionsFile { /// computation effort within the Clarity VM. /// (See SIP-006: https://github.com/stacksgov/sips/blob/main/sips/sip-006/sip-006-runtime-cost-assessment.md) /// --- - /// @default: `1_000_000_000` (units) - /// @notes: - /// - Units: Clarity VM cost units. + /// @default: `1_000_000_000` + /// @units: Clarity VM cost units pub read_only_call_limit_runtime: Option, /// Maximum size (in bytes) of the HTTP request body for read-only contract calls. /// @@ -3428,10 +3402,10 @@ pub struct ConnectionOptionsFile { /// request bodies, which might contain numerous or very large hex-encoded function arguments, /// from overwhelming the node. /// --- - /// @default: `83_886_080` (bytes, 80 MiB) - /// @notes: + /// @default: `83_886_080` (80 MiB) + /// @units: bytes + /// @notes: | /// - Calculated as 20 * [`clarity::vm::types::BOUND_VALUE_SERIALIZATION_HEX`]. - /// - Units: bytes. pub maximum_call_argument_size: Option, /// Minimum interval (in seconds) between consecutive block download scans in epoch 2.x. /// @@ -3440,10 +3414,9 @@ pub struct ConnectionOptionsFile { /// the node would wait at least this duration before initiating the next download scan. /// This throttled the downloader when the node was likely already synchronized. /// --- - /// @default: `10` (seconds) + /// @default: `10` + /// @units: seconds /// @deprecated: This setting is ignored in Epoch 3.0+. - /// @notes: - /// - Units: seconds. pub download_interval: Option, /// Minimum interval (in seconds) between initiating inventory synchronization attempts with the same peer. /// @@ -3451,9 +3424,8 @@ pub struct ConnectionOptionsFile { /// starts only after this interval has passed since the previous attempt began *and* the previous /// cycle is considered complete. /// --- - /// @default: `45` (seconds) - /// @notes: - /// - Units: seconds. + /// @default: `45` + /// @units: seconds pub inv_sync_interval: Option, /// Deprecated: it does not have any effect on the node's behavior. /// --- @@ -3466,11 +3438,10 @@ pub struct ConnectionOptionsFile { /// from `inv_reward_cycles` cycles before the current target reward cycle. This determines /// how much historical inventory information is requested in each sync attempt. /// --- - /// @default: + /// @default: | /// - `3` if [`BurnchainConfig::mode`] is `"mainnet"` /// - [`INV_REWARD_CYCLES_TESTNET`] otherwise - /// @notes: - /// - Units: PoX reward cycles. + /// @units: PoX reward cycles pub inv_reward_cycles: Option, /// The Public IPv4 address and port (e.g. "203.0.113.42:20444") to advertise to other nodes. /// @@ -3483,7 +3454,7 @@ pub struct ConnectionOptionsFile { /// Walks will only initiate from seed/bootstrap peers, outbound connections, or pingbacks. /// --- /// @default: `false` - /// @notes: + /// @notes: | /// - Primarily intended for testing or specific network debugging scenarios. pub disable_inbound_walks: Option, /// If true, prevents the node from processing initial handshake messages from new inbound P2P connections. @@ -3492,7 +3463,7 @@ pub struct ConnectionOptionsFile { /// Outbound connections initiated by this node are unaffected. /// --- /// @default: `false` - /// @notes: + /// @notes: | /// - Primarily intended for testing purposes. pub disable_inbound_handshakes: Option, /// If true, completely disables the block download state machine. @@ -3501,7 +3472,7 @@ pub struct ConnectionOptionsFile { /// legacy blocks) from peers. /// --- /// @default: `false` - /// @notes: + /// @notes: | /// - Intended for testing or specialized node configurations. pub disable_block_download: Option, /// Fault injection setting for testing purposes. Interval (in seconds) for forced disconnection of all peers. @@ -3510,11 +3481,11 @@ pub struct ConnectionOptionsFile { /// roughly this interval. This simulates network churn or partitioning for testing node resilience. /// --- /// @default: `None` (feature disabled) - /// @notes: + /// @notes: | /// - The code enforcing this behavior is conditionally compiled using `cfg!(test)` and is /// only active during test runs. /// - This setting has no effect in standard production builds. - /// - Units: seconds. + /// @units: seconds pub force_disconnect_interval: Option, /// Controls whether a node with public inbound connections should still push blocks, even if not NAT'ed. /// @@ -3550,7 +3521,7 @@ pub struct ConnectionOptionsFile { /// It is also used to authenticate requests to `/v2/blocks?broadcast=1`. /// --- /// @default: `None` (authentication disabled for relevant endpoints) - /// @notes: + /// @notes: | /// - **Requirement:** This field **must** be configured if the node needs to receive /// block proposals from a configured `stacks-signer` event_observer via the /// `/v3/block_proposal` endpoint. The value must match the token configured on the signer. @@ -3561,10 +3532,9 @@ pub struct ConnectionOptionsFile { /// Stacks blocks and microblocks to peers. This value specifies the cooldown period for this operation. /// This prevents the node from excessively attempting to push data to its peers. /// --- - /// @default: `3_600` (seconds, 1 hour) + /// @default: `3_600` (1 hour) /// @deprecated: This setting is ignored in Epoch 3.0+. - /// @notes: - /// - Units: seconds. + /// @units: seconds pub antientropy_retry: Option, /// Controls whether the node accepts Nakamoto blocks pushed proactively by peers. /// @@ -3592,7 +3562,7 @@ pub struct ConnectionOptionsFile { /// `{"ip": "...", "port": ..., "public_key_hash": "..."}` /// --- /// @default: `None` (no hints provided) - /// @notes: + /// @notes: | /// - Use this option with caution, primarily for advanced testing or bootstrapping. /// @toml_example: | /// stackerdb_hint_replicas = ''' @@ -3620,9 +3590,8 @@ pub struct ConnectionOptionsFile { /// with an HTTP 422 (Unprocessable Entity) error, considering it too stale. /// This prevents the node from spending resources validating outdated proposals. /// --- - /// @default: [`DEFAULT_BLOCK_PROPOSAL_MAX_AGE_SECS`] (seconds) - /// @notes: - /// - Units: seconds. + /// @default: [`DEFAULT_BLOCK_PROPOSAL_MAX_AGE_SECS`] + /// @units: seconds pub block_proposal_max_age_secs: Option, } @@ -3938,7 +3907,7 @@ pub struct FeeEstimationConfigFile { /// cost estimation. /// --- /// @default: `"NaivePessimistic"` - /// @notes: + /// @notes: | /// - If [`FeeEstimationConfigFile::disabled`] is `true`, the node will /// use the default unit cost estimator. pub cost_estimator: Option, @@ -3953,7 +3922,7 @@ pub struct FeeEstimationConfigFile { /// by adding unpredictability to fee estimates while still maintaining accuracy. /// --- /// @default: `"ScalarFeeRate"` - /// @notes: + /// @notes: | /// - If [`FeeEstimationConfigFile::disabled`] is `true`, the node will /// use the default unit fee estimator. pub fee_estimator: Option, @@ -3966,7 +3935,7 @@ pub struct FeeEstimationConfigFile { /// proportional to how much of the block limit they consume. /// --- /// @default: `"ProportionDotProduct"` - /// @notes: + /// @notes: | /// - If [`FeeEstimationConfigFile::disabled`] is `true`, the node will /// use the default unit cost metric. pub cost_metric: Option, @@ -3983,7 +3952,7 @@ pub struct FeeEstimationConfigFile { /// This setting takes precedence over individual estimator/metric configurations. /// --- /// @default: `false` - /// @notes: + /// @notes: | /// - When `true`, the values for [`FeeEstimationConfigFile::cost_estimator`], /// [`FeeEstimationConfigFile::fee_estimator`], and [`FeeEstimationConfigFile::cost_metric`] are ignored. pub disabled: Option, @@ -4000,7 +3969,7 @@ pub struct FeeEstimationConfigFile { /// for users to precisely optimize their fees while still providing reasonable estimates. /// --- /// @default: `0.1` (10%) - /// @notes: + /// @notes: | /// - This setting is only relevant when [`FeeEstimationConfigFile::fee_estimator`] is set to /// `"FuzzedWeightedMedianFeeRate"`. pub fee_rate_fuzzer_fraction: Option, @@ -4015,7 +3984,7 @@ pub struct FeeEstimationConfigFile { /// adapt to rapid network changes. /// --- /// @default: `5` - /// @notes: + /// @notes: | /// - This setting is primarily relevant when [`FeeEstimationConfigFile::fee_estimator`] is set to /// `"FuzzedWeightedMedianFeeRate"`, as it's used by the underlying [`WeightedMedianFeeRateEstimator`]. pub fee_rate_window_size: Option, @@ -4283,8 +4252,9 @@ pub struct EventObserverConfigFile { /// /// This should point to a service capable of receiving and processing Stacks event data. /// --- - /// @default: No default. This field is required. - /// @notes: + /// @default: No default. + /// @required: true + /// @notes: | /// - **Do NOT include the `http://` scheme in this configuration value.** /// @toml_example: | /// endpoint = "localhost:3700" @@ -4346,8 +4316,9 @@ pub struct EventObserverConfigFile { /// - Events delivered to: `/new_block`, `/new_microblocks`. /// - Payload details: The "events" array in the delivered payloads will be filtered for events related to the specified asset. /// --- - /// @default: No default. This field is required. - /// @notes: + /// @default: No default. + /// @required: true + /// @notes: | /// - For a more detailed documentation check the event-dispatcher docs in the `/docs` folder. /// @toml_example: | /// events_keys = [ @@ -4364,9 +4335,8 @@ pub struct EventObserverConfigFile { /// If a timeout occurs and retries are enabled (see [`EventObserverConfig::disable_retries`]), /// the request will be attempted again according to the retry strategy. /// --- - /// @default: `1_000` (ms, 1 second) - /// @notes: - /// - Units: milliseconds. + /// @default: `1_000` + /// @units: milliseconds pub timeout_ms: Option, /// Controls whether the node should retry sending event notifications if delivery fails or times out. /// @@ -4381,7 +4351,7 @@ pub struct EventObserverConfigFile { /// will be made for that specific event. /// --- /// @default: `false` (retries are enabled) - /// @notes: + /// @notes: | /// - **Warning:** Setting this to `true` can lead to missed events if the observer endpoint is temporarily unavailable or experiences issues. pub disable_retries: Option, } @@ -4488,14 +4458,15 @@ pub struct InitialBalanceFile { /// The Stacks address to receive the initial STX balance. /// Must be a valid "non-mainnet" Stacks address (e.g., "ST2QKZ4FKHAH1NQKYKYAYZPY440FEPK7GZ1R5HBP2"). /// --- - /// @default: No default. This field is required. + /// @default: No default. + /// @required: true pub address: String, /// The amount of microSTX to allocate to the address at node startup. /// 1 STX = 1,000,000 microSTX. /// --- - /// @default: No default. This field is required. - /// @notes: - /// - Units: microSTX. + /// @default: No default. + /// @required: true + /// @units: microSTX pub amount: u64, } From 060602395fbdce3ec202c7240a635fac7fd6af38 Mon Sep 17 00:00:00 2001 From: Francesco Leacche Date: Wed, 4 Jun 2025 14:30:31 +0100 Subject: [PATCH 3/8] improve example formatting --- stackslib/src/config/mod.rs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/stackslib/src/config/mod.rs b/stackslib/src/config/mod.rs index 260605614e..a8f8a799bb 100644 --- a/stackslib/src/config/mod.rs +++ b/stackslib/src/config/mod.rs @@ -2251,7 +2251,10 @@ pub struct NodeConfig { /// @notes: | /// - Values are strings representing qualified contract identifiers. /// @toml_example: | - /// stacker_dbs = ["SP000000000000000000002Q6VF78.pox-3", "SP2C2YFP12AJZB4M4KUPSTMZQR0SNHNPH204SCQJM.stx-oracle-v1"] + /// stacker_dbs = [ + /// "SP000000000000000000002Q6VF78.pox-3", + /// "SP2C2YFP12AJZB4M4KUPSTMZQR0SNHNPH204SCQJM.stx-oracle-v1" + /// ] pub stacker_dbs: Vec, /// 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 From 01b84467d84923ab8ca496cca3ea606270c0f657 Mon Sep 17 00:00:00 2001 From: Francesco Leacche Date: Mon, 9 Jun 2025 15:53:49 +0100 Subject: [PATCH 4/8] improve data_url and p2p_address docs --- stackslib/src/config/mod.rs | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/stackslib/src/config/mod.rs b/stackslib/src/config/mod.rs index a8f8a799bb..0518013818 100644 --- a/stackslib/src/config/mod.rs +++ b/stackslib/src/config/mod.rs @@ -2041,13 +2041,16 @@ pub struct NodeConfig { /// 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 [`NodeConfig::rpc_bind`] is default). + /// @default: Derived by adding "http://" prefix to [`NodeConfig::rpc_bind`] value. + /// @notes: | + /// - Example: For rpc_bind="0.0.0.0:20443", data_url becomes "http://0.0.0.0:20443". pub data_url: String, /// The publicly accessible IPv4 address and port that this node advertises to peers for P2P connections. /// This might differ from [`NodeConfig::p2p_bind`] if the node is behind NAT or a proxy. /// --- - /// @default: Derived from [`NodeConfig::rpc_bind`] (e.g., "0.0.0.0:20443" if [`NodeConfig::rpc_bind`] is default). + /// @default: Derived directly from [`NodeConfig::rpc_bind`] value. /// @notes: | + /// - Example: For rpc_bind="0.0.0.0:20443", p2p_address becomes "0.0.0.0:20443". /// - The default value derivation might be unexpected, potentially using the /// [`NodeConfig::rpc_bind`] address; explicit configuration is recommended if needed. pub p2p_address: String, From ad953414e17f52cd03ba3aaa34b39c301325d062 Mon Sep 17 00:00:00 2001 From: Francesco Leacche Date: Tue, 10 Jun 2025 12:21:37 +0200 Subject: [PATCH 5/8] enhanche some notes as per review comments --- stackslib/src/config/mod.rs | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/stackslib/src/config/mod.rs b/stackslib/src/config/mod.rs index 0518013818..143b2d205d 100644 --- a/stackslib/src/config/mod.rs +++ b/stackslib/src/config/mod.rs @@ -2210,15 +2210,18 @@ pub struct NodeConfig { 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. + /// (`SelectedAndUnknown` status), regardless of affirmation status. /// - 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. /// --- /// @default: `true` /// @notes: | - /// - This parameter cannot be set via the configuration file; it must be modified programmatically. + /// - This parameter cannot be set via the configuration file; + /// it must be modified programmatically. + /// - This is intended strictly for testing purposes. + /// - The halt check runs *before* affirmation checks. + /// - In Nakamoto (Epoch 3.0+), all prepare phase have anchor blocks. pub assume_present_anchor_blocks: bool, /// 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 @@ -2940,7 +2943,7 @@ pub struct MinerConfig { /// @default: `false` (Should only default true if [`MinerConfig::mining_key`] is set). /// @deprecated: This setting is ignored in Epoch 3.0+. /// @notes: | - /// - This is intended strictly for testing purposes for Epoch 2.5 conditions. + /// - This is intended strictly for testing Epoch 2.5 conditions. pub pre_nakamoto_mock_signing: bool, /// The minimum time to wait between mining blocks in milliseconds. The value must be greater /// than or equal to 1000 ms because if a block is mined within the same second as its parent, @@ -3070,7 +3073,8 @@ pub struct MinerConfig { /// --- /// @default: `{ 0: 180, 10: 90, 20: 45, 30: 0 }` (times in seconds) /// @notes: | - /// - Keys are rejection weight percentages (0-100). Values are timeout durations. + /// - Keys are rejection weight percentages (0-100). + /// - Values are timeout durations. /// @toml_example: | /// # Keys are rejection counts (as strings), values are timeouts in seconds. /// [miner.block_rejection_timeout_steps] @@ -3528,9 +3532,10 @@ pub struct ConnectionOptionsFile { /// --- /// @default: `None` (authentication disabled for relevant endpoints) /// @notes: | - /// - **Requirement:** This field **must** be configured if the node needs to receive - /// block proposals from a configured `stacks-signer` event_observer via the - /// `/v3/block_proposal` endpoint. The value must match the token configured on the signer. + /// - This field **must** be configured if the node needs to receive + /// block proposals from a configured `stacks-signer` [[events_observer]] + /// via the `/v3/block_proposal` endpoint. + /// - The value must match the token configured on the signer. pub auth_token: Option, /// Minimum interval (in seconds) between attempts to run the Epoch 2.x anti-entropy data push mechanism. /// From 9cc7294ef6de0d86aeb44c6c9d1f980030a25199 Mon Sep 17 00:00:00 2001 From: Francesco Leacche Date: Tue, 10 Jun 2025 12:23:53 +0200 Subject: [PATCH 6/8] remove pipe from notes (all have lists) --- stackslib/src/config/mod.rs | 128 ++++++++++++++++++------------------ 1 file changed, 64 insertions(+), 64 deletions(-) diff --git a/stackslib/src/config/mod.rs b/stackslib/src/config/mod.rs index 143b2d205d..cd818d38fe 100644 --- a/stackslib/src/config/mod.rs +++ b/stackslib/src/config/mod.rs @@ -1238,7 +1238,7 @@ pub struct BurnchainConfig { /// The underlying blockchain used for Proof-of-Transfer. /// --- /// @default: `"bitcoin"` - /// @notes: | + /// @notes: /// - Currently, only `"bitcoin"` is supported. pub chain: String, /// The operational mode or network profile for the Stacks node. @@ -1262,7 +1262,7 @@ pub struct BurnchainConfig { /// @default: | /// - [`CHAIN_ID_MAINNET`] if [`BurnchainConfig::mode`] is `"mainnet"` /// - [`CHAIN_ID_TESTNET`] otherwise - /// @notes: | + /// @notes: /// - **Warning:** Do not modify this unless you really know what you're doing. /// - This is intended strictly for testing purposes. pub chain_id: u32, @@ -1272,7 +1272,7 @@ pub struct BurnchainConfig { /// @default: | /// - [`PEER_VERSION_MAINNET`] if [`BurnchainConfig::mode`] is `"mainnet"` /// - [`PEER_VERSION_TESTNET`] otherwise - /// @notes: | + /// @notes: /// - **Warning:** Do not modify this unless you really know what you're doing. pub peer_version: u32, /// Specifies a mandatory wait period (in milliseconds) after receiving a burnchain tip @@ -1282,7 +1282,7 @@ pub struct BurnchainConfig { /// --- /// @default: `5_000` /// @units: milliseconds - /// @notes: | + /// @notes: /// - This is intended strictly for testing purposes. pub commit_anchor_block_within: u64, /// The maximum amount (in sats) of "burn commitment" to broadcast for the next block's leader election. @@ -1293,7 +1293,7 @@ pub struct BurnchainConfig { /// --- /// @default: `20_000` /// @units: satoshis - /// @notes: | + /// @notes: /// - Only relevant if [`NodeConfig::miner`] is `true`. pub burn_fee_cap: u64, /// The hostname or IP address of the bitcoin node peer. @@ -1319,14 +1319,14 @@ pub struct BurnchainConfig { /// Required if the bitcoin node requires RPC authentication. /// --- /// @default: `None` - /// @notes: | + /// @notes: /// - Only relevant if [`NodeConfig::miner`] is `true`. pub username: Option, /// The password for authenticating with the bitcoin node's RPC interface. /// Required if the bitcoin node requires RPC authentication. /// --- /// @default: `None` - /// @notes: | + /// @notes: /// - Only relevant if [`NodeConfig::miner`] is `true`. pub password: Option, /// Timeout duration, in seconds, for RPC calls made to the bitcoin node. @@ -1362,7 +1362,7 @@ pub struct BurnchainConfig { /// when generating blocks on the regtest network. /// --- /// @default: `None` - /// @notes: | + /// @notes: /// - Mandatory if [`BurnchainConfig::mode`] is "helium". /// - This is intended strictly for testing purposes. pub local_mining_public_key: Option, @@ -1370,7 +1370,7 @@ pub struct BurnchainConfig { /// When bitcoin reaches this height, the node logs a message and initiates a graceful shutdown. /// --- /// @default: `None` - /// @notes: | + /// @notes: /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". /// - This is intended strictly for testing purposes. pub process_exit_at_block_height: Option, @@ -1387,7 +1387,7 @@ pub struct BurnchainConfig { /// --- /// @default: [`DEFAULT_SATS_PER_VB`] /// @units: sats/vByte - /// @notes: | + /// @notes: /// - Only relevant if [`NodeConfig::miner`] is `true`. pub satoshis_per_byte: u64, /// Maximum fee rate multiplier allowed when using Replace-By-Fee (RBF) for bitcoin transactions. @@ -1397,7 +1397,7 @@ pub struct BurnchainConfig { /// --- /// @default: [`DEFAULT_MAX_RBF_RATE`] /// @units: percent - /// @notes: | + /// @notes: /// - Only relevant if [`NodeConfig::miner`] is `true`. pub max_rbf: u64, /// Estimated size (in virtual bytes) of a leader key registration transaction on bitcoin. @@ -1406,7 +1406,7 @@ pub struct BurnchainConfig { /// --- /// @default: [`OP_TX_LEADER_KEY_ESTIM_SIZE`] /// @units: virtual bytes - /// @notes: | + /// @notes: /// - Only relevant if [`NodeConfig::miner`] is `true`. pub leader_key_tx_estimated_size: u64, /// Estimated size (in virtual bytes) of a block commit transaction on bitcoin. @@ -1415,7 +1415,7 @@ pub struct BurnchainConfig { /// --- /// @default: [`OP_TX_BLOCK_COMMIT_ESTIM_SIZE`] /// @units: virtual bytes - /// @notes: | + /// @notes: /// - Only relevant if [`NodeConfig::miner`] is `true`. pub block_commit_tx_estimated_size: u64, /// The incremental amount (in sats/vByte) to add to the previous transaction's @@ -1423,14 +1423,14 @@ pub struct BurnchainConfig { /// --- /// @default: [`DEFAULT_RBF_FEE_RATE_INCREMENT`] /// @units: sats/vByte - /// @notes: | + /// @notes: /// - Only relevant if [`NodeConfig::miner`] is `true`. pub rbf_fee_increment: u64, /// Overrides the default starting bitcoin block height for the node. /// Allows starting synchronization from a specific historical point in test environments. /// --- /// @default: `None` (uses the burnchain's default starting height for the mode) - /// @notes: | + /// @notes: /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". /// - This is intended strictly for testing purposes. /// - Should be used together with [`BurnchainConfig::first_burn_block_timestamp`] and @@ -1439,7 +1439,7 @@ pub struct BurnchainConfig { /// Overrides the default starting block timestamp of the burnchain. /// --- /// @default: `None` (uses the burnchain's default starting timestamp) - /// @notes: | + /// @notes: /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". /// - This is intended strictly for testing purposes. /// - Should be used together with [`BurnchainConfig::first_burn_block_height`] and @@ -1448,7 +1448,7 @@ pub struct BurnchainConfig { /// Overrides the default starting block hash of the burnchain. /// --- /// @default: `None` (uses the burnchain's default starting block hash) - /// @notes: | + /// @notes: /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". /// - This is intended strictly for testing purposes. /// - Should be used together with [`BurnchainConfig::first_burn_block_height`] and @@ -1471,7 +1471,7 @@ pub struct BurnchainConfig { /// - The number of defined epochs cannot exceed the maximum supported by the node software. /// --- /// @default: `None` (uses the standard epoch definitions for the selected [`BurnchainConfig::mode`]) - /// @notes: | + /// @notes: /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". /// - This is intended strictly for testing purposes. /// - Configured as a list `[[burnchain.epochs]]` in TOML, each with `epoch_name` (string) @@ -1499,7 +1499,7 @@ pub struct BurnchainConfig { /// - However, the height specified in `epochs` for Epoch 2.1 takes precedence. /// --- /// @default: `None` - /// @notes: | + /// @notes: /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". /// - This is intended strictly for testing purposes. pub pox_2_activation: Option, @@ -1507,7 +1507,7 @@ pub struct BurnchainConfig { /// --- /// @default: `None` (uses the standard reward cycle length for the mode) /// @units: bitcoin blocks - /// @notes: | + /// @notes: /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". /// - This is intended strictly for testing purposes. pub pox_reward_length: Option, @@ -1515,7 +1515,7 @@ pub struct BurnchainConfig { /// --- /// @default: `None` (uses the standard prepare phase length for the mode) /// @units: bitcoin blocks - /// @notes: | + /// @notes: /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". /// - This is intended strictly for testing purposes. pub pox_prepare_length: Option, @@ -1527,7 +1527,7 @@ pub struct BurnchainConfig { /// @default: `None` (uses the standard sunset start height for the mode) /// @deprecated: The sunset phase was removed in Epoch 2.1. This parameter can still be used for /// testing purposes for epochs before 2.1. - /// @notes: | + /// @notes: /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". /// - This is intended strictly for testing purposes. pub sunset_start: Option, @@ -1538,7 +1538,7 @@ pub struct BurnchainConfig { /// @default: `None` (uses the standard sunset end height for the mode) /// @deprecated: The sunset phase was removed in Epoch 2.1. This parameter can still be used for /// testing purposes for epochs before 2.1. - /// @notes: | + /// @notes: /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". /// - This is intended strictly for testing purposes. pub sunset_end: Option, @@ -1550,7 +1550,7 @@ pub struct BurnchainConfig { /// separate wallets. /// --- /// @default: `""` (empty string, implying the default wallet or no specific wallet needed) - /// @notes: | + /// @notes: /// - Primarily relevant for miners interacting with multi-wallet Bitcoin nodes. pub wallet_name: String, /// Override for the burnchain height activating stricter AST size checks pre-epoch 3.0 for testing purposes. @@ -1571,7 +1571,7 @@ pub struct BurnchainConfig { /// --- /// @default: Empty map /// @deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. - /// @notes: | + /// @notes: /// - Primarily used for testing or recovering from network issues. /// - Configured as a list `[[burnchain.affirmation_overrides]]` in TOML, each with /// `reward_cycle` (integer) and `affirmation` (string of 'p'/'n'/'a', length `reward_cycle - 1`). @@ -1585,7 +1585,7 @@ pub struct BurnchainConfig { /// --- /// @default: `0` (no delay) /// @units: milliseconds - /// @notes: | + /// @notes: /// - This is intended strictly for testing purposes. pub fault_injection_burnchain_block_delay: u64, /// The maximum number of unspent transaction outputs (UTXOs) to request from the bitcoin node. @@ -1600,7 +1600,7 @@ pub struct BurnchainConfig { /// for a transaction, even if sufficient funds exist across more UTXOs not returned by the limited query. /// --- /// @default: `1024` - /// @notes: | + /// @notes: /// - This value must be `<= 1024`. /// - Only relevant if [`NodeConfig::miner`] is `true`. pub max_unspent_utxos: Option, @@ -2015,7 +2015,7 @@ pub struct NodeConfig { /// If [`MinerConfig::mining_key`] is not set, this seed may also be used for mining-related signing. /// --- /// @default: Randomly generated 32 bytes - /// @notes: | + /// @notes: /// - Required if [`NodeConfig::miner`] is `true` and [`MinerConfig::mining_key`] is absent. pub seed: Vec, /// The file system absolute path to the node's working directory. @@ -2024,7 +2024,7 @@ pub struct NodeConfig { /// This path can be overridden by setting the `STACKS_WORKING_DIR` environment variable. /// --- /// @default: `/tmp/stacks-node-{current_timestamp}` - /// @notes: | + /// @notes: /// - For persistent mainnet or testnet nodes, this path must be explicitly configured to /// a non-temporary location. pub working_dir: String, @@ -2042,14 +2042,14 @@ pub struct NodeConfig { /// as its HTTP RPC endpoint. Other nodes or services might use this URL to query the node's API. /// --- /// @default: Derived by adding "http://" prefix to [`NodeConfig::rpc_bind`] value. - /// @notes: | + /// @notes: /// - Example: For rpc_bind="0.0.0.0:20443", data_url becomes "http://0.0.0.0:20443". pub data_url: String, /// The publicly accessible IPv4 address and port that this node advertises to peers for P2P connections. /// This might differ from [`NodeConfig::p2p_bind`] if the node is behind NAT or a proxy. /// --- /// @default: Derived directly from [`NodeConfig::rpc_bind`] value. - /// @notes: | + /// @notes: /// - Example: For rpc_bind="0.0.0.0:20443", p2p_address becomes "0.0.0.0:20443". /// - The default value derivation might be unexpected, potentially using the /// [`NodeConfig::rpc_bind`] address; explicit configuration is recommended if needed. @@ -2094,7 +2094,7 @@ pub struct NodeConfig { /// real bitcoin consensus or P2P block production process. /// --- /// @default: `false` - /// @notes: | + /// @notes: /// - Only relevant if [`NodeConfig::miner`] is `true`. pub mock_mining: bool, /// If [`NodeConfig::mock_mining`] is enabled, this specifies an optional directory path where the @@ -2113,7 +2113,7 @@ pub struct NodeConfig { /// --- /// @default: `30_000` (30 seconds) /// @deprecated: This setting is ignored in Epoch 2.5+. - /// @notes: | + /// @notes: /// - Only applies when [`NodeConfig::mine_microblocks`] is true and before Epoch 2.5. /// @units: milliseconds pub microblock_frequency: u64, @@ -2126,7 +2126,7 @@ pub struct NodeConfig { /// --- /// @default: `30_000` (30 seconds) /// @deprecated: This setting is ignored in Epoch 2.5+. - /// @notes: | + /// @notes: /// - Only applies when [`NodeConfig::mine_microblocks`] is true and before Epoch 2.5. /// @units: milliseconds pub wait_time_for_microblocks: u64, @@ -2185,7 +2185,7 @@ pub struct NodeConfig { /// This is intended strictly for testing purposes and is disallowed on mainnet. /// --- /// @default: `None` (uses standard network genesis) - /// @notes: | + /// @notes: /// - This is intended strictly for testing purposes and is disallowed on mainnet. pub use_test_genesis_chainstate: Option, /// Controls if Stacks Epoch 2.1+ affirmation map logic should be applied even before Epoch 2.1. @@ -2216,7 +2216,7 @@ pub struct NodeConfig { /// Normal operation requires this to be `true`; setting to `false` will likely break consensus adherence. /// --- /// @default: `true` - /// @notes: | + /// @notes: /// - This parameter cannot be set via the configuration file; /// it must be modified programmatically. /// - This is intended strictly for testing purposes. @@ -2228,7 +2228,7 @@ pub struct NodeConfig { /// to its peers. /// --- /// @default: `None` (no fault injection) - /// @notes: | + /// @notes: /// - Values: 0-100 (percentage). pub fault_injection_block_push_fail_probability: Option, /// Fault injection setting for testing purposes. If `true`, the node's chainstate database @@ -2236,7 +2236,7 @@ pub struct NodeConfig { /// simulating block hiding or data unavailability. /// --- /// @default: `false` - /// @notes: | + /// @notes: /// - This parameter cannot be set via the configuration file; it must be modified programmatically. pub fault_injection_hide_blocks: bool, /// The polling interval, in seconds, for the background thread that monitors chain liveness. @@ -2254,7 +2254,7 @@ pub struct NodeConfig { /// (like `.miners`, `.signers-*`) are automatically added in addition to any contracts /// specified in the configuration file. /// - Otherwise, defaults to an empty list `[]` if not specified in the TOML. - /// @notes: | + /// @notes: /// - Values are strings representing qualified contract identifiers. /// @toml_example: | /// stacker_dbs = [ @@ -2744,7 +2744,7 @@ pub struct MinerConfig { /// --- /// @default: `25` (25% chance) /// @units: percent - /// @notes: | + /// @notes: /// - Values: 0-100. pub probability_pick_no_estimate_tx: u8, /// Optional recipient for the coinbase block reward, overriding the default miner address. @@ -2773,7 +2773,7 @@ pub struct MinerConfig { /// --- /// @default: `1048576` (1 MiB) /// @units: bytes - /// @notes: | + /// @notes: /// - Must be configured to a value greater than 0. pub nonce_cache_size: usize, /// Max size (in *number* of items) of transaction candidates to hold in the in-memory @@ -2789,7 +2789,7 @@ pub struct MinerConfig { /// --- /// @default: `1048576` /// @units: items - /// @notes: | + /// @notes: /// - Each element [`crate::core::mempool::MemPoolTxInfoPartial`] is currently 112 bytes. pub candidate_retry_cache_size: usize, /// Amount of time (in seconds) to wait for unprocessed blocks before mining a new block. @@ -2942,7 +2942,7 @@ pub struct MinerConfig { /// --- /// @default: `false` (Should only default true if [`MinerConfig::mining_key`] is set). /// @deprecated: This setting is ignored in Epoch 3.0+. - /// @notes: | + /// @notes: /// - This is intended strictly for testing Epoch 2.5 conditions. pub pre_nakamoto_mock_signing: bool, /// The minimum time to wait between mining blocks in milliseconds. The value must be greater @@ -3003,7 +3003,7 @@ pub struct MinerConfig { /// --- /// @default: [`DEFAULT_TENURE_COST_LIMIT_PER_BLOCK_PERCENTAGE`] /// @units: percent - /// @notes: | + /// @notes: /// - Values: 1-100. /// - Setting to 100 effectively disables this per-block limit, allowing a block to use the /// entire remaining tenure budget. @@ -3051,7 +3051,7 @@ pub struct MinerConfig { /// --- /// @default: [`DEFAULT_TENURE_EXTEND_COST_THRESHOLD`] /// @units: percent - /// @notes: | + /// @notes: /// - Values: 0-100. pub tenure_extend_cost_threshold: u64, /// Defines adaptive timeouts for waiting for signer responses, based on the accumulated weight of rejections. @@ -3072,7 +3072,7 @@ pub struct MinerConfig { /// A key for 0 (zero rejections) must be defined, representing the initial timeout when no rejections have been received. /// --- /// @default: `{ 0: 180, 10: 90, 20: 45, 30: 0 }` (times in seconds) - /// @notes: | + /// @notes: /// - Keys are rejection weight percentages (0-100). /// - Values are timeout durations. /// @toml_example: | @@ -3376,7 +3376,7 @@ pub struct ConnectionOptionsFile { /// Maximum total size (in bytes) of data allowed to be written during a read-only call. /// --- /// @default: `0` - /// @notes: | + /// @notes: /// - This limit is effectively forced to 0 by the API handler, ensuring read-only behavior. /// - Configuring a non-zero value has no effect on read-only call execution. /// @units: bytes @@ -3390,7 +3390,7 @@ pub struct ConnectionOptionsFile { /// Maximum number of distinct write operations allowed during a read-only call. /// --- /// @default: `0` - /// @notes: | + /// @notes: /// - This limit is effectively forced to 0 by the API handler, ensuring read-only behavior. /// - Configuring a non-zero value has no effect on read-only call execution. pub read_only_call_limit_write_count: Option, @@ -3414,7 +3414,7 @@ pub struct ConnectionOptionsFile { /// --- /// @default: `83_886_080` (80 MiB) /// @units: bytes - /// @notes: | + /// @notes: /// - Calculated as 20 * [`clarity::vm::types::BOUND_VALUE_SERIALIZATION_HEX`]. pub maximum_call_argument_size: Option, /// Minimum interval (in seconds) between consecutive block download scans in epoch 2.x. @@ -3464,7 +3464,7 @@ pub struct ConnectionOptionsFile { /// Walks will only initiate from seed/bootstrap peers, outbound connections, or pingbacks. /// --- /// @default: `false` - /// @notes: | + /// @notes: /// - Primarily intended for testing or specific network debugging scenarios. pub disable_inbound_walks: Option, /// If true, prevents the node from processing initial handshake messages from new inbound P2P connections. @@ -3473,7 +3473,7 @@ pub struct ConnectionOptionsFile { /// Outbound connections initiated by this node are unaffected. /// --- /// @default: `false` - /// @notes: | + /// @notes: /// - Primarily intended for testing purposes. pub disable_inbound_handshakes: Option, /// If true, completely disables the block download state machine. @@ -3482,7 +3482,7 @@ pub struct ConnectionOptionsFile { /// legacy blocks) from peers. /// --- /// @default: `false` - /// @notes: | + /// @notes: /// - Intended for testing or specialized node configurations. pub disable_block_download: Option, /// Fault injection setting for testing purposes. Interval (in seconds) for forced disconnection of all peers. @@ -3491,7 +3491,7 @@ pub struct ConnectionOptionsFile { /// roughly this interval. This simulates network churn or partitioning for testing node resilience. /// --- /// @default: `None` (feature disabled) - /// @notes: | + /// @notes: /// - The code enforcing this behavior is conditionally compiled using `cfg!(test)` and is /// only active during test runs. /// - This setting has no effect in standard production builds. @@ -3531,7 +3531,7 @@ pub struct ConnectionOptionsFile { /// It is also used to authenticate requests to `/v2/blocks?broadcast=1`. /// --- /// @default: `None` (authentication disabled for relevant endpoints) - /// @notes: | + /// @notes: /// - This field **must** be configured if the node needs to receive /// block proposals from a configured `stacks-signer` [[events_observer]] /// via the `/v3/block_proposal` endpoint. @@ -3573,7 +3573,7 @@ pub struct ConnectionOptionsFile { /// `{"ip": "...", "port": ..., "public_key_hash": "..."}` /// --- /// @default: `None` (no hints provided) - /// @notes: | + /// @notes: /// - Use this option with caution, primarily for advanced testing or bootstrapping. /// @toml_example: | /// stackerdb_hint_replicas = ''' @@ -3918,7 +3918,7 @@ pub struct FeeEstimationConfigFile { /// cost estimation. /// --- /// @default: `"NaivePessimistic"` - /// @notes: | + /// @notes: /// - If [`FeeEstimationConfigFile::disabled`] is `true`, the node will /// use the default unit cost estimator. pub cost_estimator: Option, @@ -3933,7 +3933,7 @@ pub struct FeeEstimationConfigFile { /// by adding unpredictability to fee estimates while still maintaining accuracy. /// --- /// @default: `"ScalarFeeRate"` - /// @notes: | + /// @notes: /// - If [`FeeEstimationConfigFile::disabled`] is `true`, the node will /// use the default unit fee estimator. pub fee_estimator: Option, @@ -3946,7 +3946,7 @@ pub struct FeeEstimationConfigFile { /// proportional to how much of the block limit they consume. /// --- /// @default: `"ProportionDotProduct"` - /// @notes: | + /// @notes: /// - If [`FeeEstimationConfigFile::disabled`] is `true`, the node will /// use the default unit cost metric. pub cost_metric: Option, @@ -3963,7 +3963,7 @@ pub struct FeeEstimationConfigFile { /// This setting takes precedence over individual estimator/metric configurations. /// --- /// @default: `false` - /// @notes: | + /// @notes: /// - When `true`, the values for [`FeeEstimationConfigFile::cost_estimator`], /// [`FeeEstimationConfigFile::fee_estimator`], and [`FeeEstimationConfigFile::cost_metric`] are ignored. pub disabled: Option, @@ -3980,7 +3980,7 @@ pub struct FeeEstimationConfigFile { /// for users to precisely optimize their fees while still providing reasonable estimates. /// --- /// @default: `0.1` (10%) - /// @notes: | + /// @notes: /// - This setting is only relevant when [`FeeEstimationConfigFile::fee_estimator`] is set to /// `"FuzzedWeightedMedianFeeRate"`. pub fee_rate_fuzzer_fraction: Option, @@ -3995,7 +3995,7 @@ pub struct FeeEstimationConfigFile { /// adapt to rapid network changes. /// --- /// @default: `5` - /// @notes: | + /// @notes: /// - This setting is primarily relevant when [`FeeEstimationConfigFile::fee_estimator`] is set to /// `"FuzzedWeightedMedianFeeRate"`, as it's used by the underlying [`WeightedMedianFeeRateEstimator`]. pub fee_rate_window_size: Option, @@ -4265,7 +4265,7 @@ pub struct EventObserverConfigFile { /// --- /// @default: No default. /// @required: true - /// @notes: | + /// @notes: /// - **Do NOT include the `http://` scheme in this configuration value.** /// @toml_example: | /// endpoint = "localhost:3700" @@ -4329,7 +4329,7 @@ pub struct EventObserverConfigFile { /// --- /// @default: No default. /// @required: true - /// @notes: | + /// @notes: /// - For a more detailed documentation check the event-dispatcher docs in the `/docs` folder. /// @toml_example: | /// events_keys = [ @@ -4362,7 +4362,7 @@ pub struct EventObserverConfigFile { /// will be made for that specific event. /// --- /// @default: `false` (retries are enabled) - /// @notes: | + /// @notes: /// - **Warning:** Setting this to `true` can lead to missed events if the observer endpoint is temporarily unavailable or experiences issues. pub disable_retries: Option, } From d8e931d008e862deec2ec351d6860750888d6c3d Mon Sep 17 00:00:00 2001 From: Francesco Leacche Date: Tue, 10 Jun 2025 12:49:59 +0100 Subject: [PATCH 7/8] improve multiline defaults --- stackslib/src/config/mod.rs | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/stackslib/src/config/mod.rs b/stackslib/src/config/mod.rs index cd818d38fe..1597ae1eee 100644 --- a/stackslib/src/config/mod.rs +++ b/stackslib/src/config/mod.rs @@ -1260,8 +1260,8 @@ pub struct BurnchainConfig { /// The network-specific identifier used in P2P communication and database initialization. /// --- /// @default: | - /// - [`CHAIN_ID_MAINNET`] if [`BurnchainConfig::mode`] is `"mainnet"` - /// - [`CHAIN_ID_TESTNET`] otherwise + /// - if [`BurnchainConfig::mode`] is `"mainnet"`: [`CHAIN_ID_MAINNET`] + /// - else: [`CHAIN_ID_TESTNET`] /// @notes: /// - **Warning:** Do not modify this unless you really know what you're doing. /// - This is intended strictly for testing purposes. @@ -1270,8 +1270,8 @@ pub struct BurnchainConfig { /// This parameter cannot be set via the configuration file. /// --- /// @default: | - /// - [`PEER_VERSION_MAINNET`] if [`BurnchainConfig::mode`] is `"mainnet"` - /// - [`PEER_VERSION_TESTNET`] otherwise + /// - if [`BurnchainConfig::mode`] is `"mainnet"`: [`PEER_VERSION_MAINNET`] + /// - else: [`PEER_VERSION_TESTNET`] /// @notes: /// - **Warning:** Do not modify this unless you really know what you're doing. pub peer_version: u32, @@ -1348,8 +1348,8 @@ pub struct BurnchainConfig { /// Configured as a 2-character ASCII string (e.g., "X2" for mainnet). /// --- /// @default: | - /// - `"T2"` if [`BurnchainConfig::mode`] is `"xenon"` - /// - `"X2"` otherwise + /// - if [`BurnchainConfig::mode`] is `"xenon"`: `"T2"` + /// - else: `"X2"` pub magic_bytes: MagicBytes, /// The public key associated with the local mining address for the underlying Bitcoin regtest node. /// Provided as a hex string representing an uncompressed public key. @@ -2204,9 +2204,7 @@ pub struct NodeConfig { /// - 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` if [`NodeConfig::miner`] is `false` - /// - `false` if [`NodeConfig::miner`] is `true` + /// @default: Derived from the inverse of [`NodeConfig::miner`] value. 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 @@ -2250,10 +2248,10 @@ pub struct NodeConfig { /// e.g., "SP000000000000000000002Q6VF78.pox-3") that this node should actively replicate. /// --- /// @default: | - /// - If [`NodeConfig::miner`] is `true` or [`NodeConfig::stacker`] is `true`, relevant system contracts + /// - if [`NodeConfig::miner`] is `true` or [`NodeConfig::stacker`] is `true`: relevant system contracts /// (like `.miners`, `.signers-*`) are automatically added in addition to any contracts /// specified in the configuration file. - /// - Otherwise, defaults to an empty list `[]` if not specified in the TOML. + /// - else: defaults to an empty list `[]`. /// @notes: /// - Values are strings representing qualified contract identifiers. /// @toml_example: | @@ -2803,8 +2801,8 @@ pub struct MinerConfig { /// This key must be present at runtime for mining operations to succeed. /// --- /// @default: | - /// - [`NodeConfig::seed`] if the `[miner]` section *is present* in the config file - /// - `None` if the `[miner]` section *is not present* + /// - if the `[miner]` section *is present* in the config file: [`NodeConfig::seed`] + /// - else: `None` pub mining_key: Option, /// Amount of time while mining in nakamoto to wait in between mining interim blocks. /// --- @@ -3449,8 +3447,8 @@ pub struct ConnectionOptionsFile { /// how much historical inventory information is requested in each sync attempt. /// --- /// @default: | - /// - `3` if [`BurnchainConfig::mode`] is `"mainnet"` - /// - [`INV_REWARD_CYCLES_TESTNET`] otherwise + /// - if [`BurnchainConfig::mode`] is `"mainnet"`: `3` + /// - else: [`INV_REWARD_CYCLES_TESTNET`] /// @units: PoX reward cycles pub inv_reward_cycles: Option, /// The Public IPv4 address and port (e.g. "203.0.113.42:20444") to advertise to other nodes. @@ -3492,6 +3490,9 @@ pub struct ConnectionOptionsFile { /// --- /// @default: `None` (feature disabled) /// @notes: + /// - If set to a positive value, the node will periodically disconnect all of its P2P peers at + /// roughly this interval. + /// - This simulates network churn or partitioning for testing node resilience. /// - The code enforcing this behavior is conditionally compiled using `cfg!(test)` and is /// only active during test runs. /// - This setting has no effect in standard production builds. From c8757132fb57be953cef71d38769d4306863660d Mon Sep 17 00:00:00 2001 From: Francesco Leacche Date: Tue, 10 Jun 2025 15:30:20 +0200 Subject: [PATCH 8/8] improve max-line-lenght formatting of comments --- stackslib/src/config/mod.rs | 1080 +++++++++++++++++++---------------- 1 file changed, 601 insertions(+), 479 deletions(-) diff --git a/stackslib/src/config/mod.rs b/stackslib/src/config/mod.rs index 1597ae1eee..25ec594c70 100644 --- a/stackslib/src/config/mod.rs +++ b/stackslib/src/config/mod.rs @@ -1277,19 +1277,21 @@ pub struct BurnchainConfig { pub peer_version: u32, /// Specifies a mandatory wait period (in milliseconds) after receiving a burnchain tip /// before the node attempts to build the anchored block for the new tenure. - /// This duration effectively schedules the start of the block-building - /// process relative to the tip's arrival time. + /// This duration effectively schedules the start of the block-building process + /// relative to the tip's arrival time. /// --- /// @default: `5_000` /// @units: milliseconds /// @notes: /// - This is intended strictly for testing purposes. pub commit_anchor_block_within: u64, - /// The maximum amount (in sats) of "burn commitment" to broadcast for the next block's leader election. - /// Acts as a safety cap to limit the maximum amount spent on mining. - /// It serves as both the target fee and a fallback if dynamic fee calculations fail or cannot be performed. + /// The maximum amount (in sats) of "burn commitment" to broadcast for the next + /// block's leader election. Acts as a safety cap to limit the maximum amount + /// spent on mining. It serves as both the target fee and a fallback if dynamic + /// fee calculations fail or cannot be performed. /// - /// This setting can be hot-reloaded from the config file, allowing adjustment without restarting. + /// This setting can be hot-reloaded from the config file, allowing adjustment + /// without restarting. /// --- /// @default: `20_000` /// @units: satoshis @@ -1298,8 +1300,9 @@ pub struct BurnchainConfig { pub burn_fee_cap: u64, /// The hostname or IP address of the bitcoin node peer. /// - /// This field is required for all node configurations as it specifies where to find the underlying - /// bitcoin node to interact with for PoX operations, block validation, and mining. + /// This field is required for all node configurations as it specifies where to + /// find the underlying bitcoin node to interact with for PoX operations, + /// block validation, and mining. /// --- /// @default: `"0.0.0.0"` pub peer_host: String, @@ -1311,7 +1314,8 @@ pub struct BurnchainConfig { /// --- /// @default: `8332` pub rpc_port: u16, - /// Flag indicating whether to use SSL/TLS when connecting to the bitcoin node's RPC interface. + /// Flag indicating whether to use SSL/TLS when connecting to the bitcoin node's + /// RPC interface. /// --- /// @default: `false` pub rpc_ssl: bool, @@ -1335,12 +1339,12 @@ pub struct BurnchainConfig { /// @default: `60` /// @units: seconds pub timeout: u32, - /// The network "magic bytes" used to identify packets for the specific bitcoin network - /// instance (e.g., mainnet, testnet, regtest). Must match the magic bytes of the connected - /// bitcoin node. + /// The network "magic bytes" used to identify packets for the specific bitcoin + /// network instance (e.g., mainnet, testnet, regtest). Must match the magic + /// bytes of the connected bitcoin node. /// - /// These two-byte identifiers help ensure that nodes only connect to peers on the same - /// network type. Common values include: + /// These two-byte identifiers help ensure that nodes only connect to peers on the + /// same network type. Common values include: /// - "X2" for mainnet /// - "T2" for testnet (xenon) /// - Other values for specific test networks @@ -1351,33 +1355,37 @@ pub struct BurnchainConfig { /// - if [`BurnchainConfig::mode`] is `"xenon"`: `"T2"` /// - else: `"X2"` pub magic_bytes: MagicBytes, - /// The public key associated with the local mining address for the underlying Bitcoin regtest node. - /// Provided as a hex string representing an uncompressed public key. + /// The public key associated with the local mining address for the underlying + /// Bitcoin regtest node. Provided as a hex string representing an uncompressed + /// public key. /// - /// It is primarily used in modes that rely on a controlled Bitcoin regtest backend - /// (e.g., "helium", "mocknet", "neon") where the Stacks node itself needs to - /// instruct the Bitcoin node to generate blocks. + /// It is primarily used in modes that rely on a controlled Bitcoin regtest + /// backend (e.g., "helium", "mocknet", "neon") where the Stacks node itself + /// needs to instruct the Bitcoin node to generate blocks. /// - /// The key is used to derive the Bitcoin address that receives the coinbase rewards - /// when generating blocks on the regtest network. + /// The key is used to derive the Bitcoin address that receives the coinbase + /// rewards when generating blocks on the regtest network. /// --- /// @default: `None` /// @notes: /// - Mandatory if [`BurnchainConfig::mode`] is "helium". /// - This is intended strictly for testing purposes. pub local_mining_public_key: Option, - /// Optional bitcoin block height at which the Stacks node process should gracefully exit. - /// When bitcoin reaches this height, the node logs a message and initiates a graceful shutdown. + /// Optional bitcoin block height at which the Stacks node process should + /// gracefully exit. When bitcoin reaches this height, the node logs a message + /// and initiates a graceful shutdown. /// --- /// @default: `None` /// @notes: /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". /// - This is intended strictly for testing purposes. pub process_exit_at_block_height: Option, - /// The interval, in seconds, at which the node polls the bitcoin node for new blocks and state updates. + /// The interval, in seconds, at which the node polls the bitcoin node for new + /// blocks and state updates. /// /// The default value of 10 seconds is mainly intended for testing purposes. - /// It's suggested to set this to a higher value for mainnet, e.g., 300 seconds (5 minutes). + /// It's suggested to set this to a higher value for mainnet, e.g., 300 seconds + /// (5 minutes). /// --- /// @default: `10` /// @units: seconds @@ -1390,19 +1398,20 @@ pub struct BurnchainConfig { /// @notes: /// - Only relevant if [`NodeConfig::miner`] is `true`. pub satoshis_per_byte: u64, - /// Maximum fee rate multiplier allowed when using Replace-By-Fee (RBF) for bitcoin transactions. - /// Expressed as a percentage of the original [`BurnchainConfig::satoshis_per_byte`] rate (e.g., - /// 150 means the fee rate can be increased up to 1.5x). Used in mining logic for RBF decisions - /// to cap the replacement fee rate. + /// Maximum fee rate multiplier allowed when using Replace-By-Fee (RBF) for + /// bitcoin transactions. Expressed as a percentage of the original + /// [`BurnchainConfig::satoshis_per_byte`] rate (e.g., 150 means the fee rate + /// can be increased up to 1.5x). Used in mining logic for RBF decisions to + /// cap the replacement fee rate. /// --- /// @default: [`DEFAULT_MAX_RBF_RATE`] /// @units: percent /// @notes: /// - Only relevant if [`NodeConfig::miner`] is `true`. pub max_rbf: u64, - /// Estimated size (in virtual bytes) of a leader key registration transaction on bitcoin. - /// Used for fee calculation in mining logic by multiplying with the fee rate - /// [`BurnchainConfig::satoshis_per_byte`]. + /// Estimated size (in virtual bytes) of a leader key registration transaction + /// on bitcoin. Used for fee calculation in mining logic by multiplying with the + /// fee rate [`BurnchainConfig::satoshis_per_byte`]. /// --- /// @default: [`OP_TX_LEADER_KEY_ESTIM_SIZE`] /// @units: virtual bytes @@ -1454,14 +1463,15 @@ pub struct BurnchainConfig { /// - Should be used together with [`BurnchainConfig::first_burn_block_height`] and /// [`BurnchainConfig::first_burn_block_timestamp`] for proper operation. pub first_burn_block_hash: Option, - /// Custom override for the definitions of Stacks epochs (start/end burnchain heights, consensus rules). - /// This setting allows testing specific epoch transitions or custom consensus rules by defining exactly - /// when each epoch starts on bitcoin. + /// Custom override for the definitions of Stacks epochs (start/end burnchain + /// heights, consensus rules). This setting allows testing specific epoch + /// transitions or custom consensus rules by defining exactly when each epoch + /// starts on bitcoin. /// - /// Epochs define distinct protocol rule sets (consensus rules, execution costs, capabilities). - /// When configured, the list must include all epochs sequentially from "1.0" up to the - /// highest desired epoch, without skipping any intermediate ones. - /// Valid `epoch_name` values currently include: + /// Epochs define distinct protocol rule sets (consensus rules, execution costs, + /// capabilities). When configured, the list must include all epochs + /// sequentially from "1.0" up to the highest desired epoch, without skipping + /// any intermediate ones. Valid `epoch_name` values currently include: /// `"1.0"`, `"2.0"`, `"2.05"`, `"2.1"`, `"2.2"`, `"2.3"`, `"2.4"`, `"2.5"`, `"3.0"`, `"3.1"`. /// /// **Validation Rules:** @@ -1492,8 +1502,9 @@ pub struct BurnchainConfig { /// 2. The block height from which PoX reward set calculations switch to PoX v2 rules. /// /// **Behavior:** - /// - This value directly sets the auto unlock height for PoX v1 lockups before transition to PoX v2. - /// This also defines the burn height at which PoX reward sets are calculated using PoX v2 rather than v1. + /// - This value directly sets the auto unlock height for PoX v1 lockups before + /// transition to PoX v2. This also defines the burn height at which PoX reward + /// sets are calculated using PoX v2 rather than v1. /// - If custom [`BurnchainConfig::epochs`] are provided: /// - This value is used to validate that Epoch 2.1's start height is ≤ this value. /// - However, the height specified in `epochs` for Epoch 2.1 takes precedence. @@ -1519,55 +1530,58 @@ pub struct BurnchainConfig { /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". /// - This is intended strictly for testing purposes. pub pox_prepare_length: Option, - /// Overrides the bitcoin height at which the PoX sunset period begins in epochs before 2.1. - /// The sunset period represents a planned phase-out of the PoX mechanism. During this period, - /// stacking rewards gradually decrease, eventually ceasing entirely. This parameter allows - /// testing the PoX sunset transition by explicitly setting its start height. + /// Overrides the bitcoin height at which the PoX sunset period begins in epochs + /// before 2.1. The sunset period represents a planned phase-out of the PoX + /// mechanism. During this period, stacking rewards gradually decrease, + /// eventually ceasing entirely. This parameter allows testing the PoX sunset + /// transition by explicitly setting its start height. /// --- /// @default: `None` (uses the standard sunset start height for the mode) - /// @deprecated: The sunset phase was removed in Epoch 2.1. This parameter can still be used for - /// testing purposes for epochs before 2.1. + /// @deprecated: The sunset phase was removed in Epoch 2.1. /// @notes: /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". - /// - This is intended strictly for testing purposes. + /// - This is intended strictly for testing purposes for epochs before 2.1. pub sunset_start: Option, - /// Overrides the bitcoin height, non-inclusive, at which the PoX sunset period ends in epochs before 2.1. - /// After this height, Stacking rewards are disabled completely. This parameter works together - /// with `sunset_start` to define the full sunset transition period for PoX. + /// Overrides the bitcoin height, non-inclusive, at which the PoX sunset period + /// ends in epochs before 2.1. After this height, Stacking rewards are disabled + /// completely. This parameter works together with `sunset_start` to define the + /// full sunset transition period for PoX. /// --- /// @default: `None` (uses the standard sunset end height for the mode) - /// @deprecated: The sunset phase was removed in Epoch 2.1. This parameter can still be used for - /// testing purposes for epochs before 2.1. + /// @deprecated: The sunset phase was removed in Epoch 2.1. /// @notes: /// - Applied only if [`BurnchainConfig::mode`] is not "mainnet". - /// - This is intended strictly for testing purposes. + /// - This is intended strictly for testing purposes for epochs before 2.1. pub sunset_end: Option, - /// Specifies the name of the Bitcoin wallet to use within the connected bitcoin node. - /// Used to interact with a specific named wallet if the bitcoin node manages multiple wallets. + /// Specifies the name of the Bitcoin wallet to use within the connected bitcoin + /// node. Used to interact with a specific named wallet if the bitcoin node + /// manages multiple wallets. /// - /// If the specified wallet doesn't exist, the node will attempt to create it via the - /// `createwallet` RPC call. This is particularly useful for miners who need to manage - /// separate wallets. + /// If the specified wallet doesn't exist, the node will attempt to create it via + /// the `createwallet` RPC call. This is particularly useful for miners who need + /// to manage separate wallets. /// --- /// @default: `""` (empty string, implying the default wallet or no specific wallet needed) /// @notes: /// - Primarily relevant for miners interacting with multi-wallet Bitcoin nodes. pub wallet_name: String, - /// Override for the burnchain height activating stricter AST size checks pre-epoch 3.0 for testing purposes. + /// Override for the burnchain height activating stricter AST size checks + /// pre-epoch 3.0 for testing purposes. /// - /// Used pre-epoch 3.0 to control activation before it became standard (at burn height `752000`). - /// Ignored in standard production builds as the underlying mechanism is disabled unless the `testing` - /// feature is active. + /// Used pre-epoch 3.0 to control activation before it became standard (at burn + /// height `752000`). Ignored in standard production builds as the underlying + /// mechanism is disabled unless the `testing` feature is active. /// --- /// @default: `None` /// @deprecated: This setting is ignored in Epoch 3.0+. pub ast_precheck_size_height: Option, /// Overrides for the burnchain block affirmation map for specific reward cycles. - /// Allows manually setting the miner affirmation ('p'resent/'n'ot-present/'a'bsent) map for a - /// given cycle, bypassing the map normally derived from sortition results. + /// Allows manually setting the miner affirmation ('p'resent/'n'ot-present/'a'bsent) + /// map for a given cycle, bypassing the map normally derived from sortition results. /// - /// Special defaults are added when [`BurnchainConfig::mode`] is "xenon", but config entries take precedence. - /// At startup, these overrides are written to the `BurnchainDB` (`overrides` table). + /// Special defaults are added when [`BurnchainConfig::mode`] is "xenon", but + /// config entries take precedence. At startup, these overrides are written to + /// the `BurnchainDB` (`overrides` table). /// --- /// @default: Empty map /// @deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. @@ -1580,24 +1594,28 @@ pub struct BurnchainConfig { /// reward_cycle = 413 /// affirmation = "pna..." # Must be 412 chars long pub affirmation_overrides: HashMap, - /// Fault injection setting for testing. Introduces an artificial delay (in milliseconds) - /// before processing each burnchain block download. Simulates a slow burnchain connection. + /// Fault injection setting for testing. Introduces an artificial delay (in + /// milliseconds) before processing each burnchain block download. Simulates a + /// slow burnchain connection. /// --- /// @default: `0` (no delay) /// @units: milliseconds /// @notes: /// - This is intended strictly for testing purposes. pub fault_injection_burnchain_block_delay: u64, - /// The maximum number of unspent transaction outputs (UTXOs) to request from the bitcoin node. + /// The maximum number of unspent transaction outputs (UTXOs) to request from + /// the bitcoin node. /// - /// This value is passed as the `maximumCount` parameter to the bitcoin node. It helps manage - /// response size and processing load, particularly relevant for miners querying for available - /// UTXOs to fund operations like block commits or leader key registrations. + /// This value is passed as the `maximumCount` parameter to the bitcoin node. + /// It helps manage response size and processing load, particularly relevant + /// for miners querying for available UTXOs to fund operations like block + /// commits or leader key registrations. /// - /// Setting this limit too high might lead to performance issues or timeouts when querying - /// nodes with a very large number of UTXOs. Conversely, setting it too low might prevent - /// the miner from finding enough UTXOs in a single query to meet the required funding amount - /// for a transaction, even if sufficient funds exist across more UTXOs not returned by the limited query. + /// Setting this limit too high might lead to performance issues or timeouts when + /// querying nodes with a very large number of UTXOs. Conversely, setting it too + /// low might prevent the miner from finding enough UTXOs in a single query to + /// meet the required funding amount for a transaction, even if sufficient funds + /// exist across more UTXOs not returned by the limited query. /// --- /// @default: `1024` /// @notes: @@ -2005,48 +2023,51 @@ 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). + /// 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 [`MinerConfig::mining_key`] is not set, this seed may also be used for mining-related signing. + /// If [`MinerConfig::mining_key`] is not set, this seed may also be used for + /// mining-related signing. /// --- /// @default: Randomly generated 32 bytes /// @notes: /// - Required if [`NodeConfig::miner`] is `true` and [`MinerConfig::mining_key`] is absent. pub seed: Vec, /// 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. + /// 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. /// --- /// @default: `/tmp/stacks-node-{current_timestamp}` /// @notes: - /// - For persistent mainnet or testnet nodes, this path must be explicitly configured to - /// a non-temporary location. + /// - For persistent mainnet or testnet nodes, this path must be explicitly + /// configured to a non-temporary location. 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. + /// 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. + /// 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. + /// 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: Derived by adding "http://" prefix to [`NodeConfig::rpc_bind`] value. /// @notes: /// - Example: For rpc_bind="0.0.0.0:20443", data_url becomes "http://0.0.0.0:20443". pub data_url: String, - /// The publicly accessible IPv4 address and port that this node advertises to peers for P2P connections. - /// This might differ from [`NodeConfig::p2p_bind`] if the node is behind NAT or a proxy. + /// The publicly accessible IPv4 address and port that this node advertises to peers + /// for P2P connections. This might differ from [`NodeConfig::p2p_bind`] if the + /// node is behind NAT or a proxy. /// --- /// @default: Derived directly from [`NodeConfig::rpc_bind`] value. /// @notes: @@ -2054,38 +2075,41 @@ pub struct NodeConfig { /// - The default value derivation might be unexpected, potentially using the /// [`NodeConfig::rpc_bind`] address; explicit configuration is recommended if needed. 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`]. + /// 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, - /// 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. + /// 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) /// @toml_example: | /// bootstrap_node = "pubkey1@example.com:30444,pubkey2@192.168.1.100:20444" pub bootstrap_node: Vec, /// 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. + /// 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) /// @toml_example: | /// deny_nodes = "192.168.1.100:20444,badhost.example.com:20444" pub deny_nodes: Vec, - /// 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 + /// 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. + /// 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, @@ -2097,8 +2121,8 @@ pub struct NodeConfig { /// @notes: /// - Only relevant if [`NodeConfig::miner`] is `true`. pub mock_mining: bool, - /// If [`NodeConfig::mock_mining`] is enabled, this specifies an optional directory path where the - /// generated mock Stacks blocks will be saved. (pre-Nakamoto) + /// 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` @@ -2140,17 +2164,18 @@ pub struct NodeConfig { /// @default: `30_000` (30 seconds) /// @units: milliseconds pub wait_time_for_blocks: u64, - /// 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. + /// 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). A default value of 10 seconds is reasonable on mainnet + /// (where bitcoin blocks are ~10 minutes). A lower value might be useful in + /// other environments with faster burn blocks. /// --- /// @default: `10_000` (10 seconds) /// @units: milliseconds 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. + /// 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, @@ -2167,90 +2192,105 @@ pub struct NodeConfig { /// @default: `None` (effectively `"noop"`) pub marf_cache_strategy: Option, /// 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). + /// - 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. + /// 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` /// @units: 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. + /// 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. /// --- /// @default: `None` (uses standard network genesis) /// @notes: /// - This is intended strictly for testing purposes and is disallowed on mainnet. pub use_test_genesis_chainstate: Option, - /// 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. + /// 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. + /// 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: Derived from the inverse of [`NodeConfig::miner`] value. 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. - /// - 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. + /// 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. + /// - 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. /// --- /// @default: `true` /// @notes: - /// - This parameter cannot be set via the configuration file; - /// it must be modified programmatically. + /// - This parameter cannot be set via the configuration file; it must be modified + /// programmatically. /// - This is intended strictly for testing purposes. /// - The halt check runs *before* affirmation checks. - /// - In Nakamoto (Epoch 3.0+), all prepare phase have anchor blocks. + /// - In Nakamoto (Epoch 3.0+), all prepare phases have anchor blocks. pub assume_present_anchor_blocks: bool, - /// 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. + /// 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) /// @notes: /// - Values: 0-100 (percentage). pub fault_injection_block_push_fail_probability: Option, - /// 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. + /// 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. /// --- /// @default: `false` /// @notes: - /// - This parameter cannot be set via the configuration file; it must be modified programmatically. + /// - This parameter cannot be set via the configuration file; it must be modified + /// programmatically. pub fault_injection_hide_blocks: bool, - /// 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. + /// 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` (5 minutes) /// @units: seconds pub chain_liveness_poll_time_secs: u64, - /// A list of specific StackerDB contracts (identified by their qualified contract identifiers, - /// e.g., "SP000000000000000000002Q6VF78.pox-3") that this node should actively 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: | - /// - if [`NodeConfig::miner`] is `true` or [`NodeConfig::stacker`] is `true`: relevant system contracts - /// (like `.miners`, `.signers-*`) are automatically added in addition to any contracts - /// specified in the configuration file. + /// - if [`NodeConfig::miner`] is `true` or [`NodeConfig::stacker`] is `true`: + /// relevant system contracts (e.g., `.miners`, `.signers-*`) are + /// automatically added in addition to any contracts specified in the + /// configuration file. /// - else: defaults to an empty list `[]`. /// @notes: /// - Values are strings representing qualified contract identifiers. @@ -2260,9 +2300,10 @@ pub struct NodeConfig { /// "SP2C2YFP12AJZB4M4KUPSTMZQR0SNHNPH204SCQJM.stx-oracle-v1" /// ] pub stacker_dbs: Vec, - /// 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. + /// 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, @@ -2712,9 +2753,10 @@ pub struct MinerConfig { /// @units: milliseconds /// @deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. pub microblock_attempt_time_ms: u64, - /// Maximum time (in milliseconds) the miner spends selecting transactions from the mempool - /// when assembling a Nakamoto block. Once this duration is exceeded, the miner stops - /// adding transactions and finalizes the block with those already selected. + /// Maximum time (in milliseconds) the miner spends selecting transactions from + /// the mempool when assembling a Nakamoto block. Once this duration is exceeded, + /// the miner stops adding transactions and finalizes the block with those + /// already selected. /// --- /// @default: `5_000` (5 seconds) /// @units: milliseconds @@ -2732,13 +2774,13 @@ pub struct MinerConfig { /// --- /// @default: `"GlobalFeeRate"` pub mempool_walk_strategy: MemPoolWalkStrategy, - /// Probability (percentage, 0-100) of prioritizing a transaction without a known fee rate - /// during candidate selection. + /// Probability (percentage, 0-100) of prioritizing a transaction without a + /// known fee rate during candidate selection. /// /// Only effective when `mempool_walk_strategy` is `GlobalFeeRate`. Helps ensure - /// transactions lacking fee estimates are periodically considered alongside high-fee ones, - /// preventing potential starvation. A value of 0 means never prioritize them first, - /// 100 means always prioritize them first (if available). + /// transactions lacking fee estimates are periodically considered alongside + /// high-fee ones, preventing potential starvation. A value of 0 means never + /// prioritize them first, 100 means always prioritize them first (if available). /// --- /// @default: `25` (25% chance) /// @units: percent @@ -2747,9 +2789,10 @@ pub struct MinerConfig { pub probability_pick_no_estimate_tx: u8, /// Optional recipient for the coinbase block reward, overriding the default miner address. /// - /// By default (`None`), the reward is sent to the miner's primary address ([`NodeConfig::seed`]). - /// If set to some principal address *and* the current Stacks epoch is > 2.1, - /// the reward will be directed to the specified address instead. + /// By default (`None`), the reward is sent to the miner's primary address + /// ([`NodeConfig::seed`]). If set to some principal address *and* the current + /// Stacks epoch is > 2.1, the reward will be directed to the specified + /// address instead. /// --- /// @default: `None` pub block_reward_recipient: Option, @@ -2764,10 +2807,10 @@ pub struct MinerConfig { pub wait_for_block_download: bool, /// Max size (in bytes) of the in-memory cache for storing expected account nonces. /// - /// This cache accelerates mempool processing (e.g., during block building) by storing - /// the anticipated next nonce for accounts, reducing expensive lookups into the node's - /// state (MARF trie). A larger cache can improve performance for workloads involving - /// many unique accounts but increases memory consumption. + /// This cache accelerates mempool processing (e.g., during block building) by + /// storing the anticipated next nonce for accounts, reducing expensive lookups + /// into the node's state (MARF trie). A larger cache can improve performance + /// for workloads involving many unique accounts but increases memory consumption. /// --- /// @default: `1048576` (1 MiB) /// @units: bytes @@ -2777,13 +2820,14 @@ pub struct MinerConfig { /// Max size (in *number* of items) of transaction candidates to hold in the in-memory /// retry cache. /// - /// This cache stores transactions encountered during a `GlobalFeeRate` mempool walk - /// whose nonces are currently too high for immediate processing. These candidates - /// are prioritized for reconsideration later within the *same* walk, potentially - /// becoming valid if other processed transactions update the expected nonces. + /// This cache stores transactions encountered during a `GlobalFeeRate` mempool + /// walk whose nonces are currently too high for immediate processing. These + /// candidates are prioritized for reconsideration later within the *same* walk, + /// potentially becoming valid if other processed transactions update the + /// expected nonces. /// - /// A larger cache retains more potentially valid future candidates but uses more memory. - /// This setting is primarily relevant for the `GlobalFeeRate` strategy. + /// A larger cache retains more potentially valid future candidates but uses more + /// memory. This setting is primarily relevant for the `GlobalFeeRate` strategy. /// --- /// @default: `1048576` /// @units: items @@ -2809,20 +2853,21 @@ pub struct MinerConfig { /// @default: `None` /// @deprecated: Use `min_time_between_blocks_ms` instead. pub wait_on_interim_blocks: Option, - /// Minimum number of transactions that must be in a block if we're going to replace a pending - /// block-commit with a new block-commit. + /// Minimum number of transactions that must be in a block if we're going to + /// replace a pending block-commit with a new block-commit. /// --- /// @default: `0` /// @deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. pub min_tx_count: u64, - /// If true, requires subsequent mining attempts for the same block height - /// to have a transaction count >= the previous best attempt. + /// If true, requires subsequent mining attempts for the same block height to have + /// a transaction count >= the previous best attempt. /// --- /// @default: `false` /// @deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. pub only_increase_tx_count: bool, - /// Optional path to an external helper script for fetching unconfirmed block-commits. - /// Used to inform the miner's dynamic burn fee bidding strategy with off-chain data. + /// Optional path to an external helper script for fetching unconfirmed + /// block-commits. Used to inform the miner's dynamic burn fee bidding strategy + /// with off-chain data. /// /// If a path is provided, the target script must: /// - Be executable by the user running the Stacks node process. @@ -2831,18 +2876,20 @@ pub struct MinerConfig { /// (see [`stacks::config::chain_data::UnconfirmedBlockCommit`] struct) to stdout. /// - Exit with code 0 on success. /// - /// Look at `test_get_unconfirmed_commits` in `stackslib/src/config/chain_data.rs` for an example script. + /// Look at `test_get_unconfirmed_commits` in `stackslib/src/config/chain_data.rs` + /// for an example script. /// --- /// @default: `None` (feature disabled). - /// @deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode and by the - /// `get-spend-amount` cli subcommand. + /// @deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode + /// and by the `get-spend-amount` cli subcommand. pub unconfirmed_commits_helper: Option, /// The minimum win probability this miner aims to achieve in block sortitions. /// - /// This target is used to detect prolonged periods of underperformance. If the miner's - /// calculated win probability consistently falls below this value for a duration specified - /// by [`MinerConfig::underperform_stop_threshold`] (after an initial startup phase), the miner may - /// cease spending in subsequent sortitions (returning a burn fee cap of 0) to conserve resources. + /// This target is used to detect prolonged periods of underperformance. If the + /// miner's calculated win probability consistently falls below this value for a + /// duration specified by [`MinerConfig::underperform_stop_threshold`] (after + /// an initial startup phase), the miner may cease spending in subsequent + /// sortitions (returning a burn fee cap of 0) to conserve resources. /// /// Setting this value close to 0.0 effectively disables the underperformance check. /// --- @@ -2851,46 +2898,51 @@ pub struct MinerConfig { pub target_win_probability: f64, /// Path to a file for storing and loading the currently active, registered VRF leader key. /// - /// Loading: On startup or when needing to register a key, if this path is set, the relayer first - /// attempts to load a serialized [`RegisteredKey`] from this file. If successful, it uses the - /// loaded key and skips the on-chain VRF key registration transaction, saving time and fees. - /// Saving: After a new VRF key registration transaction is confirmed and activated on the burnchain, - /// if this path is set, the node saves the details of the newly activated [`RegisteredKey`] to this file. - /// This allows the miner to persist its active VRF key across restarts. - /// If the file doesn't exist during load, or the path is `None`, the node proceeds with a new registration. + /// Loading: On startup or when needing to register a key, if this path is set, + /// the relayer first attempts to load a serialized [`RegisteredKey`] from this + /// file. If successful, it uses the loaded key and skips the on-chain VRF key + /// registration transaction, saving time and fees. + /// Saving: After a new VRF key registration transaction is confirmed and + /// activated on the burnchain, if this path is set, the node saves the details + /// of the newly activated [`RegisteredKey`] to this file. This allows the + /// miner to persist its active VRF key across restarts. + /// If the file doesn't exist during load, or the path is `None`, the node + /// proceeds with a new registration. /// --- /// @default: `None` pub activated_vrf_key_path: Option, /// Controls how the miner estimates its win probability when checking for underperformance. /// /// This estimation is used in conjunction with [`MinerConfig::target_win_probability`] and - /// [`MinerConfig::underperform_stop_threshold`] to decide whether to pause mining due to - /// low predicted success rate. + /// [`MinerConfig::underperform_stop_threshold`] to decide whether to pause + /// mining due to low predicted success rate. /// - /// - If `true`: The win probability estimation looks at projected spend distributions - /// ~6 blocks into the future. This might help the miner adjust its spending more quickly - /// based on anticipated competition changes. - /// - If `false`: The win probability estimation uses the currently observed spend distribution - /// for the next block. + /// - If `true`: The win probability estimation looks at projected spend + /// distributions ~6 blocks into the future. This might help the miner adjust + /// its spending more quickly based on anticipated competition changes. + /// - If `false`: The win probability estimation uses the currently observed + /// spend distribution for the next block. /// --- /// @default: `false` /// @deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode and by the /// `get-spend-amount` cli subcommand. pub fast_rampup: bool, - /// The maximum number of consecutive Bitcoin blocks the miner will tolerate underperforming - /// (i.e., having a calculated win probability below [`MinerConfig::target_win_probability`]) - /// before temporarily pausing mining efforts. + /// The maximum number of consecutive Bitcoin blocks the miner will tolerate + /// underperforming (i.e., having a calculated win probability below + /// [`MinerConfig::target_win_probability`]) before temporarily pausing mining efforts. /// - /// This check is only active after an initial startup phase (6 blocks past the mining start height). - /// If the miner underperforms for this number of consecutive blocks, the - /// [`BlockMinerThread::get_mining_spend_amount`] function will return 0, effectively preventing the - /// miner from submitting a block commit for the current sortition to conserve funds. + /// This check is only active after an initial startup phase (6 blocks past the + /// mining start height). If the miner underperforms for this number of + /// consecutive blocks, the [`BlockMinerThread::get_mining_spend_amount`] function + /// will return 0, effectively preventing the miner from submitting a block commit + /// for the current sortition to conserve funds. /// --- /// @default: `None` (underperformance check is disabled). /// @deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode. pub underperform_stop_threshold: Option, - /// Specifies which types of transactions the miner should consider including in a block - /// during the mempool walk process. Transactions of types not included in this set will be skipped. + /// Specifies which types of transactions the miner should consider including in a + /// block during the mempool walk process. Transactions of types not included in + /// this set will be skipped. /// /// This allows miners to exclude specific transaction categories. /// Configured as a comma-separated string of transaction type names in the configuration file. @@ -2904,26 +2956,29 @@ pub struct MinerConfig { /// @toml_example: | /// txs_to_consider = "TokenTransfer,ContractCall" pub txs_to_consider: HashSet, - /// A comma separated list of Stacks addresses to whitelist so that only transactions from - /// these addresses should be considered during the mempool walk for block building. If this - /// list is non-empty, any transaction whose origin address is *not* in this set will be skipped. + /// A comma separated list of Stacks addresses to whitelist so that only + /// transactions from these addresses should be considered during the mempool walk + /// for block building. If this list is non-empty, any transaction whose origin + /// address is *not* in this set will be skipped. /// /// This allows miners to prioritize transactions originating from specific accounts that are /// important to them. - /// Configured as a comma-separated string of standard Stacks addresses (e.g., "ST123...,ST456...") - /// in the configuration file. + /// Configured as a comma-separated string of standard Stacks addresses + /// (e.g., "ST123...,ST456...") in the configuration file. /// --- /// @default: Empty set (all origins are considered). /// @toml_example: | /// filter_origins = "ST2QKZ4FKHAH1NQKYKYAYZPY440FEPK7GZ1R5HBP2,ST319CF5WV77KYR1H3GT0GZ7B8Q4AQPY42ETP1VPF" pub filter_origins: HashSet, - /// Defines the maximum depth (in Stacks blocks) the miner considers when evaluating - /// potential chain tips when selecting the best tip to mine the next block on. + /// Defines the maximum depth (in Stacks blocks) the miner considers when + /// evaluating potential chain tips when selecting the best tip to mine the next + /// block on. /// - /// The miner analyzes candidate tips within this depth from the highest known tip. - /// It selects the "nicest" tip, often defined as the one that minimizes chain reorganizations - /// or orphans within this lookback window. A lower value restricts the analysis to shallower forks, - /// while a higher value considers deeper potential reorganizations. + /// The miner analyzes candidate tips within this depth from the highest known + /// tip. It selects the "nicest" tip, often defined as the one that minimizes + /// chain reorganizations or orphans within this lookback window. A lower value + /// restricts the analysis to shallower forks, while a higher value considers + /// deeper potential reorganizations. /// /// This setting influences which fork the miner chooses to build upon if multiple valid tips exist. /// --- @@ -2931,72 +2986,82 @@ pub struct MinerConfig { /// @deprecated: This setting is ignored in Epoch 3.0+. Only used in the neon chain mode and the /// `pick-best-tip` cli subcommand. pub max_reorg_depth: u64, - /// Enables a mock signing process for testing purposes, specifically designed for use during Epoch 2.5 - /// before the activation of Nakamoto consensus. + /// Enables a mock signing process for testing purposes, specifically designed + /// for use during Epoch 2.5 before the activation of Nakamoto consensus. /// - /// When set to `true` and [`MinerConfig::mining_key`] is provided, the miner will interact - /// with the `.miners` and `.signers` contracts via the stackerdb to send and receive mock - /// proposals and signatures, simulating aspects of the Nakamoto leader election and block signing flow. + /// When set to `true` and [`MinerConfig::mining_key`] is provided, the miner + /// will interact with the `.miners` and `.signers` contracts via the stackerdb + /// to send and receive mock proposals and signatures, simulating aspects of the + /// Nakamoto leader election and block signing flow. /// --- /// @default: `false` (Should only default true if [`MinerConfig::mining_key`] is set). /// @deprecated: This setting is ignored in Epoch 3.0+. /// @notes: /// - This is intended strictly for testing Epoch 2.5 conditions. pub pre_nakamoto_mock_signing: bool, - /// The minimum time to wait between mining blocks in milliseconds. The value must be greater - /// than or equal to 1000 ms because if a block is mined within the same second as its parent, - /// it will be rejected by the signers. + /// The minimum time to wait between mining blocks in milliseconds. The value + /// must be greater than or equal to 1000 ms because if a block is mined + /// within the same second as its parent, it will be rejected by the signers. /// - /// This check ensures compliance with signer rules that prevent blocks with identical timestamps - /// (at second resolution) to their parents. If a lower value is configured, 1000 ms is used instead. + /// This check ensures compliance with signer rules that prevent blocks with + /// identical timestamps (at second resolution) to their parents. If a lower + /// value is configured, 1000 ms is used instead. /// --- /// @default: [`DEFAULT_MIN_TIME_BETWEEN_BLOCKS_MS`] /// @units: milliseconds pub min_time_between_blocks_ms: u64, - /// The amount of time in milliseconds that the miner should sleep in between attempts to - /// mine a block when the mempool is empty. + /// The amount of time in milliseconds that the miner should sleep in between + /// attempts to mine a block when the mempool is empty. /// - /// This prevents the miner from busy-looping when there are no pending transactions, - /// conserving CPU resources. During this sleep, the miner still checks burnchain tip changes. + /// This prevents the miner from busy-looping when there are no pending + /// transactions, conserving CPU resources. During this sleep, the miner still + /// checks burnchain tip changes. /// --- /// @default: [`DEFAULT_EMPTY_MEMPOOL_SLEEP_MS`] /// @units: milliseconds pub empty_mempool_sleep_time: Duration, - /// Time in milliseconds to pause after receiving the first threshold rejection, before proposing a new block. + /// Time in milliseconds to pause after receiving the first threshold rejection, + /// before proposing a new block. /// - /// When a miner's block proposal fails to gather enough signatures from the signers for the first time - /// at a given height, the miner will pause for this duration before attempting to mine and propose again. + /// When a miner's block proposal fails to gather enough signatures from the + /// signers for the first time at a given height, the miner will pause for this + /// duration before attempting to mine and propose again. /// --- /// @default: [`DEFAULT_FIRST_REJECTION_PAUSE_MS`] /// @units: milliseconds pub first_rejection_pause_ms: u64, - /// Time in milliseconds to pause after receiving subsequent threshold rejections, before proposing a new block. + /// Time in milliseconds to pause after receiving subsequent threshold rejections, + /// before proposing a new block. /// - /// If a miner's block proposal is rejected multiple times at the same height (after the first rejection), - /// this potentially longer pause duration is used before retrying. This gives more significant time - /// for network state changes or signer coordination. + /// If a miner's block proposal is rejected multiple times at the same height + /// (after the first rejection), this potentially longer pause duration is used + /// before retrying. This gives more significant time for network state changes + /// or signer coordination. /// --- /// @default: [`DEFAULT_SUBSEQUENT_REJECTION_PAUSE_MS`] /// @units: milliseconds pub subsequent_rejection_pause_ms: u64, - /// Time in milliseconds to wait for a Nakamoto block after seeing a burnchain block before submitting a block commit. + /// Time in milliseconds to wait for a Nakamoto block after seeing a burnchain + /// block before submitting a block commit. /// - /// After observing a new burnchain block, the miner's relayer waits for this duration - /// before submitting its next block commit transaction to Bitcoin. This delay provides an opportunity - /// for a new Nakamoto block (produced by the winner of the latest sortition) to arrive. - /// Waiting helps avoid situations where the relayer immediately submits a commit that needs - /// to be replaced via RBF if a new Stacks block appears shortly after. - /// This delay is skipped if the new burnchain blocks leading to the tip contain no sortitions. + /// After observing a new burnchain block, the miner's relayer waits for this + /// duration before submitting its next block commit transaction to Bitcoin. + /// This delay provides an opportunity for a new Nakamoto block (produced by the + /// winner of the latest sortition) to arrive. Waiting helps avoid situations + /// where the relayer immediately submits a commit that needs to be replaced + /// via RBF if a new Stacks block appears shortly after. This delay is skipped + /// if the new burnchain blocks leading to the tip contain no sortitions. /// --- /// @default: [`DEFAULT_BLOCK_COMMIT_DELAY_MS`] /// @units: milliseconds pub block_commit_delay: Duration, /// The percentage of the remaining tenure cost limit to consume each block. /// - /// This setting limits the execution cost (Clarity cost) a single Nakamoto block can incur, - /// expressed as a percentage of the *remaining* cost budget for the current mining tenure. - /// For example, if set to 25, a block can use at most 25% of the tenure's currently available cost limit. - /// This allows miners to spread the tenure's total execution budget across multiple blocks rather than + /// This setting limits the execution cost (Clarity cost) a single Nakamoto block + /// can incur, expressed as a percentage of the *remaining* cost budget for the + /// current mining tenure. For example, if set to 25, a block can use at most + /// 25% of the tenure's currently available cost limit. This allows miners to + /// spread the tenure's total execution budget across multiple blocks rather than /// potentially consuming it all in the first block. /// --- /// @default: [`DEFAULT_TENURE_COST_LIMIT_PER_BLOCK_PERCENTAGE`] @@ -3009,30 +3074,34 @@ pub struct MinerConfig { /// Duration to wait in-between polling the sortition DB to see if we need to /// extend the ongoing tenure (e.g. because the current sortition is empty or invalid). /// - /// After the relayer determines that a tenure extension might be needed but cannot proceed immediately - /// (e.g., because a miner thread is already active for the current burn view), it will wait for this - /// duration before re-checking the conditions for tenure extension. + /// After the relayer determines that a tenure extension might be needed but + /// cannot proceed immediately (e.g., because a miner thread is already active + /// for the current burn view), it will wait for this duration before + /// re-checking the conditions for tenure extension. /// --- /// @default: [`DEFAULT_TENURE_EXTEND_POLL_SECS`] /// @units: seconds pub tenure_extend_poll_timeout: Duration, - /// Duration to wait before trying to continue a tenure because the next miner did not produce blocks. + /// Duration to wait before trying to continue a tenure because the next miner + /// did not produce blocks. /// - /// If the node was the winner of the previous sortition but not the most recent one, - /// the relayer waits for this duration before attempting to extend its own tenure. - /// This gives the new winner of the most recent sortition a grace period to produce their first block. - /// Also used in scenarios with empty sortitions to give the winner of the *last valid* sortition time - /// to produce a block before the current miner attempts an extension. + /// If the node was the winner of the previous sortition but not the most recent + /// one, the relayer waits for this duration before attempting to extend its own + /// tenure. This gives the new winner of the most recent sortition a grace period + /// to produce their first block. Also used in scenarios with empty sortitions + /// to give the winner of the *last valid* sortition time to produce a block + /// before the current miner attempts an extension. /// --- /// @default: [`DEFAULT_TENURE_EXTEND_WAIT_MS`] /// @units: milliseconds pub tenure_extend_wait_timeout: Duration, /// Duration to wait before attempting to issue a time-based tenure extend. /// - /// A miner can proactively attempt to extend its tenure if a significant amount of time has passed - /// since the last tenure change, even without an explicit trigger like an empty sortition. - /// If the time elapsed since the last tenure change exceeds this value, and the signer coordinator - /// indicates an extension is timely, and the cost usage threshold ([`MinerConfig::tenure_extend_cost_threshold`]) + /// A miner can proactively attempt to extend its tenure if a significant amount + /// of time has passed since the last tenure change, even without an explicit + /// trigger like an empty sortition. If the time elapsed since the last tenure + /// change exceeds this value, and the signer coordinator indicates an extension + /// is timely, and the cost usage threshold ([`MinerConfig::tenure_extend_cost_threshold`]) /// is met, the miner will include a tenure extension transaction in its next block. /// --- /// @default: [`DEFAULT_TENURE_TIMEOUT_SECS`] @@ -3040,34 +3109,38 @@ pub struct MinerConfig { pub tenure_timeout: Duration, /// Percentage of block budget that must be used before attempting a time-based tenure extend. /// - /// This sets a minimum threshold for the accumulated execution cost within a tenure before a - /// time-based tenure extension ([`MinerConfig::tenure_timeout`]) can be initiated. - /// The miner checks if the proportion of the total tenure budget consumed so far exceeds this percentage. - /// If the cost usage is below this threshold, a time-based extension will not be attempted, even if - /// the [`MinerConfig::tenure_timeout`] duration has elapsed. - /// This prevents miners from extending tenures very early if they have produced only low-cost blocks. + /// This sets a minimum threshold for the accumulated execution cost within a + /// tenure before a time-based tenure extension ([`MinerConfig::tenure_timeout`]) + /// can be initiated. The miner checks if the proportion of the total tenure + /// budget consumed so far exceeds this percentage. If the cost usage is below + /// this threshold, a time-based extension will not be attempted, even if the + /// [`MinerConfig::tenure_timeout`] duration has elapsed. This prevents miners + /// from extending tenures very early if they have produced only low-cost blocks. /// --- /// @default: [`DEFAULT_TENURE_EXTEND_COST_THRESHOLD`] /// @units: percent /// @notes: /// - Values: 0-100. pub tenure_extend_cost_threshold: u64, - /// Defines adaptive timeouts for waiting for signer responses, based on the accumulated weight of rejections. + /// Defines adaptive timeouts for waiting for signer responses, based on the + /// accumulated weight of rejections. /// - /// Configured as a map where keys represent rejection count thresholds in percentage, - /// and values are the timeout durations (in seconds) to apply when the rejection count - /// reaches or exceeds that key but is less than the next key. + /// Configured as a map where keys represent rejection count thresholds in + /// percentage, and values are the timeout durations (in seconds) to apply when + /// the rejection count reaches or exceeds that key but is less than the next key. /// - /// When a miner proposes a block, it waits for signer responses (approvals or rejections). - /// The SignerCoordinator tracks the total weight of received rejections. It uses this map to determine - /// the current timeout duration. It selects the timeout value associated with the largest key - /// in the map that is less than or equal to the current accumulated rejection weight. - /// If this timeout duration expires before a decision is reached, the coordinator signals a timeout. - /// This prompts the miner to potentially retry proposing the block. - /// As more rejections come in, the applicable timeout step might change (likely decrease), - /// allowing the miner to abandon unviable proposals faster. + /// When a miner proposes a block, it waits for signer responses (approvals or + /// rejections). The SignerCoordinator tracks the total weight of received + /// rejections. It uses this map to determine the current timeout duration. It + /// selects the timeout value associated with the largest key in the map that is + /// less than or equal to the current accumulated rejection weight. If this + /// timeout duration expires before a decision is reached, the coordinator + /// signals a timeout. This prompts the miner to potentially retry proposing the + /// block. As more rejections come in, the applicable timeout step might change + /// (likely decrease), allowing the miner to abandon unviable proposals faster. /// - /// A key for 0 (zero rejections) must be defined, representing the initial timeout when no rejections have been received. + /// A key for 0 (zero rejections) must be defined, representing the initial + /// timeout when no rejections have been received. /// --- /// @default: `{ 0: 180, 10: 90, 20: 45, 30: 0 }` (times in seconds) /// @notes: @@ -3083,10 +3156,11 @@ pub struct MinerConfig { pub block_rejection_timeout_steps: HashMap, /// Defines the maximum execution time (in seconds) allowed for a single contract call transaction. /// - /// When processing a transaction (contract call or smart contract deployment), if this option is set, - /// and the execution time exceeds this limit, the transaction processing fails with an `ExecutionTimeout` error, - /// and the transaction is skipped. This prevents potentially long-running or infinite-loop transactions - /// from blocking block production. + /// When processing a transaction (contract call or smart contract deployment), + /// if this option is set, and the execution time exceeds this limit, the + /// transaction processing fails with an `ExecutionTimeout` error, and the + /// transaction is skipped. This prevents potentially long-running or + /// infinite-loop transactions from blocking block production. /// --- /// @default: `None` (no execution time limit) /// @units: seconds @@ -3164,19 +3238,23 @@ pub struct ConnectionOptionsFile { /// --- /// @default: `100` pub outbox_maxlen: Option, - /// Maximum duration (in seconds) a connection attempt is allowed to remain in the connecting state. + /// Maximum duration (in seconds) a connection attempt is allowed to remain in + /// the connecting state. /// - /// This applies to both incoming P2P and HTTP connections. If a remote peer initiates a connection - /// but does not complete the connection process (e.g., handshake for P2P) within this time, the node - /// will consider it unresponsive and drop the connection attempt. + /// This applies to both incoming P2P and HTTP connections. If a remote peer + /// initiates a connection but does not complete the connection process + /// (e.g., handshake for P2P) within this time, the node will consider it + /// unresponsive and drop the connection attempt. /// --- /// @default: `10` /// @units: seconds pub connect_timeout: Option, - /// Maximum duration (in seconds) a P2P peer is allowed after connecting before completing the handshake. + /// Maximum duration (in seconds) a P2P peer is allowed after connecting before + /// completing the handshake. /// - /// If a P2P peer connects successfully but fails to send the necessary handshake messages - /// within this time, the node will consider it unresponsive and drop the connection. + /// If a P2P peer connects successfully but fails to send the necessary handshake + /// messages within this time, the node will consider it unresponsive and drop the + /// connection. /// --- /// @default: `5` /// @units: seconds @@ -3184,9 +3262,11 @@ pub struct ConnectionOptionsFile { /// General communication timeout (in seconds). /// /// - For HTTP connections: Governs two timeout aspects: - /// - Server-side: Defines the maximum allowed time since the last request was received from a client. - /// An idle connection is dropped if both this timeout and [`ConnectionOptionsFile::idle_timeout`] are exceeded. - /// - Client-side: Sets the timeout duration (TTL) for outgoing HTTP requests initiated by the node itself. + /// - Server-side: Defines the maximum allowed time since the last request was + /// received from a client. An idle connection is dropped if both this + /// timeout and [`ConnectionOptionsFile::idle_timeout`] are exceeded. + /// - Client-side: Sets the timeout duration (TTL) for outgoing HTTP requests + /// initiated by the node itself. /// - For P2P connections: Used as the specific timeout for NAT punch-through requests. /// --- /// @default: `15` @@ -3194,43 +3274,46 @@ pub struct ConnectionOptionsFile { pub timeout: Option, /// Maximum idle time (in seconds) for HTTP connections. /// - /// This applies only to HTTP connections. It defines the maximum allowed time since the - /// last response was sent by the node to the client. An HTTP connection is dropped if - /// both this `idle_timeout` and the general [`ConnectionOptionsFile::timeout`] (time since last - /// request received) are exceeded. + /// This applies only to HTTP connections. It defines the maximum allowed time + /// since the last response was sent by the node to the client. An HTTP + /// connection is dropped if both this `idle_timeout` and the general + /// [`ConnectionOptionsFile::timeout`] (time since last request received) are exceeded. /// --- /// @default: `15` /// @units: seconds pub idle_timeout: Option, - /// Interval (in seconds) at which this node expects to send or receive P2P keep-alive messages. + /// Interval (in seconds) at which this node expects to send or receive P2P + /// keep-alive messages. /// - /// During the P2P handshake, this node advertises this configured `heartbeat` value to its peers. - /// Each peer uses the other's advertised heartbeat interval (plus a timeout margin) to monitor - /// responsiveness and detect potential disconnections. This node also uses its own configured - /// value to proactively send Ping messages if the connection would otherwise be idle, helping to - /// keep it active. + /// During the P2P handshake, this node advertises this configured `heartbeat` + /// value to its peers. Each peer uses the other's advertised heartbeat + /// interval (plus a timeout margin) to monitor responsiveness and detect + /// potential disconnections. This node also uses its own configured value to + /// proactively send Ping messages if the connection would otherwise be idle, + /// helping to keep it active. /// --- /// @default: `3_600` (1 hour) /// @units: seconds pub heartbeat: Option, - /// Validity duration (in number of bitcoin blocks) for the node's P2P session private key. - /// - /// The node uses a temporary private key for signing P2P messages. This key has an associated - /// expiry bitcoin block height stored in the peer database. When the current bitcoin height - /// reaches or exceeds the key's expiry height, the node automatically generates a new random + /// Validity duration (in number of bitcoin blocks) for the node's P2P session /// private key. - /// The expiry block height for this new key is calculated by adding the configured - /// [`ConnectionOptionsFile::private_key_lifetime`] (in blocks) to the previous key's expiry block height. - /// The node then re-handshakes with peers to transition to the new key. - /// This provides periodic key rotation for P2P communication. + /// + /// The node uses a temporary private key for signing P2P messages. This key has + /// an associated expiry bitcoin block height stored in the peer database. When + /// the current bitcoin height reaches or exceeds the key's expiry height, the + /// node automatically generates a new random private key. + /// The expiry block height for this new key is calculated by adding the + /// configured [`ConnectionOptionsFile::private_key_lifetime`] (in blocks) to the + /// previous key's expiry block height. The node then re-handshakes with peers + /// to transition to the new key. This provides periodic key rotation for P2P communication. /// --- /// @default: `9223372036854775807` (i64::MAX, effectively infinite, disabling automatic re-keying). /// @units: bitcoin blocks pub private_key_lifetime: Option, /// Target number of peers for StackerDB replication. /// - /// Sets the maximum number of potential replication target peers requested from the - /// StackerDB control contract (`get-replication-targets`) when configuring a replica. + /// Sets the maximum number of potential replication target peers requested from + /// the StackerDB control contract (`get-replication-targets`) when configuring a replica. /// /// Note: Formerly (pre-Epoch 3.0), this also controlled the target peer count for /// inventory synchronization. @@ -3239,34 +3322,34 @@ pub struct ConnectionOptionsFile { pub num_neighbors: Option, /// Maximum number of allowed concurrent inbound P2P connections. /// - /// This acts as a hard limit. If the node already has this many active inbound P2P - /// connections, any new incoming P2P connection attempts will be rejected. + /// This acts as a hard limit. If the node already has this many active inbound + /// P2P connections, any new incoming P2P connection attempts will be rejected. /// Outbound P2P connections initiated by this node are not counted against this limit. /// --- /// @default: `750` pub num_clients: Option, /// Maximum total number of allowed concurrent HTTP connections. /// - /// This limits the total number of simultaneous connections the node's RPC/HTTP server - /// will accept. If this limit is reached, new incoming HTTP connection attempts - /// will be rejected. + /// This limits the total number of simultaneous connections the node's RPC/HTTP + /// server will accept. If this limit is reached, new incoming HTTP connection + /// attempts will be rejected. /// --- /// @default: `1000` pub max_http_clients: Option, /// Target number of outbound P2P connections the node aims to maintain. /// /// The connection pruning logic only activates if the current number of established - /// outbound P2P connections exceeds this value. Pruning aims to reduce the connection - /// count back down to this target, ensuring the node maintains a baseline number - /// of outbound peers for network connectivity. + /// outbound P2P connections exceeds this value. Pruning aims to reduce the + /// connection count back down to this target, ensuring the node maintains a + /// baseline number of outbound peers for network connectivity. /// --- /// @default: `16` pub soft_num_neighbors: Option, /// Soft limit threshold for triggering inbound P2P connection pruning. /// - /// If the total number of currently active inbound P2P connections exceeds this value, - /// the node will activate pruning logic to reduce the count, typically by applying - /// per-host limits (see [`ConnectionOptionsFile::soft_max_clients_per_host`]). + /// If the total number of currently active inbound P2P connections exceeds this + /// value, the node will activate pruning logic to reduce the count, typically by + /// applying per-host limits (see [`ConnectionOptionsFile::soft_max_clients_per_host`]). /// This helps manage the overall load from inbound peers. /// --- /// @default: `750` @@ -3288,41 +3371,44 @@ pub struct ConnectionOptionsFile { pub soft_max_neighbors_per_host: Option, /// Soft limit on the number of outbound P2P connections per network organization (ASN). /// - /// During connection pruning (when total outbound connections > [`ConnectionOptionsFile::soft_num_neighbors`]), - /// the node checks if any single network organization (identified by ASN) has more - /// outbound connections than this limit. If so, it preferentially prunes the least - /// healthy/newest connections from that overrepresented organization until its count - /// is reduced to this limit or the total outbound count reaches - /// [`ConnectionOptionsFile::soft_num_neighbors`]. This encourages connection diversity across - /// different network providers. + /// During connection pruning (when total outbound connections > + /// [`ConnectionOptionsFile::soft_num_neighbors`]), the node checks if any single + /// network organization (identified by ASN) has more outbound connections than + /// this limit. If so, it preferentially prunes the least healthy/newest + /// connections from that overrepresented organization until its count is + /// reduced to this limit or the total outbound count reaches + /// [`ConnectionOptionsFile::soft_num_neighbors`]. This encourages connection diversity + /// across different network providers. /// --- /// @default: `32` pub soft_max_neighbors_per_org: Option, /// Soft limit on the number of inbound P2P connections allowed per host IP address. /// - /// During inbound connection pruning (when total inbound connections > [`ConnectionOptionsFile::soft_num_clients`]), - /// the node checks if any single IP address has more connections than this limit. - /// If so, it preferentially prunes the newest connections originating from that - /// specific IP address until its count is reduced to this limit. - /// This prevents a single host from dominating the node's inbound connection capacity. + /// During inbound connection pruning (when total inbound connections > + /// [`ConnectionOptionsFile::soft_num_clients`]), the node checks if any single + /// IP address has more connections than this limit. If so, it preferentially + /// prunes the newest connections originating from that specific IP address + /// until its count is reduced to this limit. This prevents a single host from + /// dominating the node's inbound connection capacity. /// --- /// @default: `4` pub soft_max_clients_per_host: Option, /// Maximum total number of concurrent network sockets the node is allowed to manage. /// - /// This limit applies globally to all types of sockets handled by the node's networking layer, - /// including listening sockets (P2P and RPC/HTTP), established P2P connections (inbound/outbound), - /// and established HTTP connections. - /// It serves as a hard limit to prevent the node from exhausting operating system - /// resources related to socket descriptors. + /// This limit applies globally to all types of sockets handled by the node's + /// networking layer, including listening sockets (P2P and RPC/HTTP), + /// established P2P connections (inbound/outbound), and established HTTP connections. + /// It serves as a hard limit to prevent the node from exhausting operating + /// system resources related to socket descriptors. /// --- /// @default: `800` pub max_sockets: Option, /// Minimum interval (in seconds) between the start of consecutive neighbor discovery walks. /// - /// The node periodically performs "neighbor walks" to discover new peers and maintain - /// an up-to-date view of the P2P network topology. This setting controls how frequently - /// these walks can be initiated, preventing excessive network traffic and processing. + /// The node periodically performs "neighbor walks" to discover new peers and + /// maintain an up-to-date view of the P2P network topology. This setting + /// controls how frequently these walks can be initiated, preventing excessive + /// network traffic and processing. /// --- /// @default: `60` /// @units: seconds @@ -3331,26 +3417,29 @@ pub struct ConnectionOptionsFile { /// /// This probability applies only when the node is not in Initial Block Download (IBD) /// and is already connected to at least one seed/bootstrap peer. - /// Normally, in this situation, the walk would start from a random inbound or outbound peer. - /// However, with this probability, the walk is forced to start from a seed peer instead. - /// This helps ensure the node periodically re-establishes its network view from trusted entry points. + /// Normally, in this situation, the walk would start from a random inbound or + /// outbound peer. However, with this probability, the walk is forced to start + /// from a seed peer instead. This helps ensure the node periodically + /// re-establishes its network view from trusted entry points. /// --- /// @default: `0.1` (10%) pub walk_seed_probability: Option, - /// Frequency (in milliseconds) for logging the current P2P neighbor list at the DEBUG level. + /// Frequency (in milliseconds) for logging the current P2P neighbor list at the + /// DEBUG level. /// - /// If set to a non-zero value, the node will periodically log details about its currently - /// established P2P connections (neighbors). Setting this to 0 disables this periodic logging. + /// If set to a non-zero value, the node will periodically log details about its + /// currently established P2P connections (neighbors). Setting this to 0 disables + /// this periodic logging. /// --- /// @default: `60_000` (1 minute) /// @units: milliseconds pub log_neighbors_freq: Option, /// Maximum time (in milliseconds) to wait for a DNS query to resolve. /// - /// When the node needs to resolve a hostname (e.g., from a peer's advertised `data_url` - /// or an Atlas attachment URL) into an IP address, it initiates a DNS lookup. - /// This setting defines the maximum duration the node will wait for the DNS server - /// to respond before considering the lookup timed out. + /// When the node needs to resolve a hostname (e.g., from a peer's advertised + /// [`NodeConfig::data_url`] or an Atlas attachment URL) into an IP address, it + /// initiates a DNS lookup. This setting defines the maximum duration the node will + /// wait for the DNS server to respond before considering the lookup timed out. /// --- /// @default: `15_000` (15 seconds) /// @units: milliseconds @@ -3379,8 +3468,8 @@ pub struct ConnectionOptionsFile { /// - Configuring a non-zero value has no effect on read-only call execution. /// @units: bytes pub read_only_call_limit_write_length: Option, - /// Maximum total size (in bytes) of data allowed to be read from Clarity data space (variables, maps) - /// during a read-only call. + /// Maximum total size (in bytes) of data allowed to be read from Clarity data + /// space (variables, maps) during a read-only call. /// --- /// @default: `100_000` (100 KB). /// @units: bytes @@ -3392,7 +3481,8 @@ pub struct ConnectionOptionsFile { /// - This limit is effectively forced to 0 by the API handler, ensuring read-only behavior. /// - Configuring a non-zero value has no effect on read-only call execution. pub read_only_call_limit_write_count: Option, - /// Maximum number of distinct read operations from Clarity data space allowed during a read-only call. + /// Maximum number of distinct read operations from Clarity data space allowed + /// during a read-only call. /// --- /// @default: `30` pub read_only_call_limit_read_count: Option, @@ -3407,8 +3497,8 @@ pub struct ConnectionOptionsFile { /// /// This limit is enforced on the `Content-Length` of incoming requests to the /// `/v2/contracts/call-read-only/...` RPC endpoint. It prevents excessively large - /// request bodies, which might contain numerous or very large hex-encoded function arguments, - /// from overwhelming the node. + /// request bodies, which might contain numerous or very large hex-encoded + /// function arguments, from overwhelming the node. /// --- /// @default: `83_886_080` (80 MiB) /// @units: bytes @@ -3417,20 +3507,22 @@ pub struct ConnectionOptionsFile { pub maximum_call_argument_size: Option, /// Minimum interval (in seconds) between consecutive block download scans in epoch 2.x. /// - /// In the pre-Nakamoto block download logic, if a full scan for blocks completed without - /// finding any new blocks to download, and if the known peer inventories had not changed, - /// the node would wait at least this duration before initiating the next download scan. - /// This throttled the downloader when the node was likely already synchronized. + /// In the pre-Nakamoto block download logic, if a full scan for blocks completed + /// without finding any new blocks to download, and if the known peer inventories + /// had not changed, the node would wait at least this duration before + /// initiating the next download scan. This throttled the downloader when the + /// node was likely already synchronized. /// --- /// @default: `10` /// @units: seconds /// @deprecated: This setting is ignored in Epoch 3.0+. pub download_interval: Option, - /// Minimum interval (in seconds) between initiating inventory synchronization attempts with the same peer. + /// Minimum interval (in seconds) between initiating inventory synchronization + /// attempts with the same peer. /// - /// Acts as a per-peer cooldown to throttle sync requests. A new sync cycle with a peer generally - /// starts only after this interval has passed since the previous attempt began *and* the previous - /// cycle is considered complete. + /// Acts as a per-peer cooldown to throttle sync requests. A new sync cycle with + /// a peer generally starts only after this interval has passed since the previous + /// attempt began *and* the previous cycle is considered complete. /// --- /// @default: `45` /// @units: seconds @@ -3442,9 +3534,10 @@ pub struct ConnectionOptionsFile { pub full_inv_sync_interval: Option, /// Lookback depth (in PoX reward cycles) for Nakamoto inventory synchronization requests. /// - /// When initiating an inventory sync cycle with a peer, the node requests data starting - /// from `inv_reward_cycles` cycles before the current target reward cycle. This determines - /// how much historical inventory information is requested in each sync attempt. + /// When initiating an inventory sync cycle with a peer, the node requests data + /// starting from `inv_reward_cycles` cycles before the current target reward + /// cycle. This determines how much historical inventory information is requested + /// in each sync attempt. /// --- /// @default: | /// - if [`BurnchainConfig::mode`] is `"mainnet"`: `3` @@ -3453,22 +3546,24 @@ pub struct ConnectionOptionsFile { pub inv_reward_cycles: Option, /// The Public IPv4 address and port (e.g. "203.0.113.42:20444") to advertise to other nodes. /// - /// If this option is not set (`None`), the node will attempt to automatically discover its - /// public IP address. + /// If this option is not set (`None`), the node will attempt to automatically + /// discover its public IP address. /// --- /// @default: `None` (triggers automatic discovery attempt) pub public_ip_address: Option, - /// If true, disables the neighbor discovery mechanism from starting walks from inbound peers. - /// Walks will only initiate from seed/bootstrap peers, outbound connections, or pingbacks. + /// If true, disables the neighbor discovery mechanism from starting walks from + /// inbound peers. Walks will only initiate from seed/bootstrap peers, outbound + /// connections, or pingbacks. /// --- /// @default: `false` /// @notes: /// - Primarily intended for testing or specific network debugging scenarios. pub disable_inbound_walks: Option, - /// If true, prevents the node from processing initial handshake messages from new inbound P2P connections. + /// If true, prevents the node from processing initial handshake messages from new + /// inbound P2P connections. /// - /// This effectively stops the node from establishing new authenticated inbound P2P sessions. - /// Outbound connections initiated by this node are unaffected. + /// This effectively stops the node from establishing new authenticated inbound + /// P2P sessions. Outbound connections initiated by this node are unaffected. /// --- /// @default: `false` /// @notes: @@ -3476,35 +3571,39 @@ pub struct ConnectionOptionsFile { pub disable_inbound_handshakes: Option, /// If true, completely disables the block download state machine. /// - /// The node will not attempt to download Stacks blocks (neither Nakamoto tenures nor - /// legacy blocks) from peers. + /// The node will not attempt to download Stacks blocks (neither Nakamoto + /// tenures nor legacy blocks) from peers. /// --- /// @default: `false` /// @notes: /// - Intended for testing or specialized node configurations. pub disable_block_download: Option, - /// Fault injection setting for testing purposes. Interval (in seconds) for forced disconnection of all peers. + /// Fault injection setting for testing purposes. Interval (in seconds) for + /// forced disconnection of all peers. /// - /// If set to a positive value, the node will periodically disconnect all of its P2P peers at - /// roughly this interval. This simulates network churn or partitioning for testing node resilience. + /// If set to a positive value, the node will periodically disconnect all of its + /// P2P peers at roughly this interval. This simulates network churn or + /// partitioning for testing node resilience. /// --- /// @default: `None` (feature disabled) /// @notes: - /// - If set to a positive value, the node will periodically disconnect all of its P2P peers at - /// roughly this interval. + /// - If set to a positive value, the node will periodically disconnect all of + /// its P2P peers at roughly this interval. /// - This simulates network churn or partitioning for testing node resilience. - /// - The code enforcing this behavior is conditionally compiled using `cfg!(test)` and is - /// only active during test runs. + /// - The code enforcing this behavior is conditionally compiled using `cfg!(test)` + /// and is only active during test runs. /// - This setting has no effect in standard production builds. /// @units: seconds pub force_disconnect_interval: Option, - /// Controls whether a node with public inbound connections should still push blocks, even if not NAT'ed. + /// Controls whether a node with public inbound connections should still push + /// blocks, even if not NAT'ed. /// - /// In the Stacks 2.x anti-entropy logic, if a node detected it had inbound connections - /// from public IPs (suggesting it wasn't behind NAT) and this flag was set to `false`, - /// it would refrain from proactively pushing blocks and microblocks to peers. - /// The assumption was that publicly reachable nodes should primarily serve downloads. - /// If set to `true` (default), the node would push data regardless of its perceived reachability. + /// In the Stacks 2.x anti-entropy logic, if a node detected it had inbound + /// connections from public IPs (suggesting it wasn't behind NAT) and this flag + /// was set to `false`, it would refrain from proactively pushing blocks and + /// microblocks to peers. The assumption was that publicly reachable nodes should + /// primarily serve downloads. If set to `true` (default), the node would push + /// data regardless of its perceived reachability. /// --- /// @default: `true` /// @deprecated: This setting is ignored in Epoch 3.0+. @@ -3518,16 +3617,16 @@ pub struct ConnectionOptionsFile { /// - Skip querying peers with private IPs for mempool or StackerDB data. /// - Filter out peers with private IPs from API responses listing potential peers. /// - /// Setting this to `true` disables these restrictions, which can be useful for local testing - /// environments or fully private network deployments. + /// Setting this to `true` disables these restrictions, which can be useful for + /// local testing environments or fully private network deployments. /// --- /// @default: `false` pub private_neighbors: Option, /// HTTP auth password to use when communicating with stacks-signer binary. /// /// This token is used in the `Authorization` header for certain requests. - /// Primarily, it secures the communication channel between this node and a connected - /// `stacks-signer` instance. + /// Primarily, it secures the communication channel between this node and a + /// connected `stacks-signer` instance. /// /// It is also used to authenticate requests to `/v2/blocks?broadcast=1`. /// --- @@ -3538,11 +3637,13 @@ pub struct ConnectionOptionsFile { /// via the `/v3/block_proposal` endpoint. /// - The value must match the token configured on the signer. pub auth_token: Option, - /// Minimum interval (in seconds) between attempts to run the Epoch 2.x anti-entropy data push mechanism. + /// Minimum interval (in seconds) between attempts to run the Epoch 2.x anti-entropy + /// data push mechanism. /// - /// The Stacks 2.x anti-entropy protocol involves the node proactively pushing its known - /// Stacks blocks and microblocks to peers. This value specifies the cooldown period for this operation. - /// This prevents the node from excessively attempting to push data to its peers. + /// The Stacks 2.x anti-entropy protocol involves the node proactively pushing its + /// known Stacks blocks and microblocks to peers. This value specifies the + /// cooldown period for this operation. This prevents the node from excessively + /// attempting to push data to its peers. /// --- /// @default: `3_600` (1 hour) /// @deprecated: This setting is ignored in Epoch 3.0+. @@ -3550,20 +3651,22 @@ pub struct ConnectionOptionsFile { pub antientropy_retry: Option, /// Controls whether the node accepts Nakamoto blocks pushed proactively by peers. /// - /// - If `true`: Pushed blocks are ignored (logged at DEBUG and discarded). The node will - /// still process blocks that it actively downloads. + /// - If `true`: Pushed blocks are ignored (logged at DEBUG and discarded). The + /// node will still process blocks that it actively downloads. /// - If `false`: Both pushed blocks and actively downloaded blocks are processed. /// --- /// @default: `false` pub reject_blocks_pushed: Option, - /// Static list of preferred replica peers for specific StackerDB contracts, provided as a JSON string. + /// Static list of preferred replica peers for specific StackerDB contracts, + /// provided as a JSON string. /// - /// This allows manually specifying known peers to use for replicating particular StackerDBs, - /// potentially overriding or supplementing the peers discovered via the StackerDB's control contract. + /// This allows manually specifying known peers to use for replicating particular + /// StackerDBs, potentially overriding or supplementing the peers discovered via + /// the StackerDB's control contract. /// /// Format: The configuration value must be a TOML string containing valid JSON. - /// The JSON structure must be an array of tuples, where each tuple pairs a contract identifier - /// with a list of preferred neighbor addresses: + /// The JSON structure must be an array of tuples, where each tuple pairs a + /// contract identifier with a list of preferred neighbor addresses: /// `[[ContractIdentifier, [NeighborAddress, ...]], ...]` /// /// 1. `ContractIdentifier`: A JSON object representing the [`QualifiedContractIdentifier`]. @@ -3595,12 +3698,13 @@ pub struct ConnectionOptionsFile { /// ] /// ''' pub stackerdb_hint_replicas: Option, - /// Maximum age (in seconds) allowed for a block proposal received via the `/v3/block_proposal` RPC endpoint. + /// Maximum age (in seconds) allowed for a block proposal received via the + /// `/v3/block_proposal` RPC endpoint. /// - /// If a block proposal is received whose timestamp is older than - /// the current time minus this configured value, the node will reject the proposal - /// with an HTTP 422 (Unprocessable Entity) error, considering it too stale. - /// This prevents the node from spending resources validating outdated proposals. + /// If a block proposal is received whose timestamp is older than the current + /// time minus this configured value, the node will reject the proposal with an + /// HTTP 422 (Unprocessable Entity) error, considering it too stale. This + /// prevents the node from spending resources validating outdated proposals. /// --- /// @default: [`DEFAULT_BLOCK_PROPOSAL_MAX_AGE_SECS`] /// @units: seconds @@ -3952,33 +4056,39 @@ pub struct FeeEstimationConfigFile { /// use the default unit cost metric. pub cost_metric: Option, /// If `true`, all fee and cost estimation features are disabled. - /// The node will use unit estimators and metrics, which effectively - /// provide no actual estimation capabilities. + /// The node will use unit estimators and metrics, which effectively provide no + /// actual estimation capabilities. /// /// When disabled, the node will: - /// 1. Not track historical transaction costs or fee rates - /// 2. Return simple unit values for costs for any transaction, regardless of its actual complexity - /// 3. Be unable to provide meaningful fee estimates for API requests (always returns an error) - /// 4. Consider only raw transaction fees (not fees per cost unit) when assembling blocks + /// 1. Not track historical transaction costs or fee rates. + /// 2. Return simple unit values for costs for any transaction, regardless of + /// its actual complexity. + /// 3. Be unable to provide meaningful fee estimates for API requests (always + /// returns an error). + /// 4. Consider only raw transaction fees (not fees per cost unit) when + /// assembling blocks. /// /// This setting takes precedence over individual estimator/metric configurations. /// --- /// @default: `false` /// @notes: /// - When `true`, the values for [`FeeEstimationConfigFile::cost_estimator`], - /// [`FeeEstimationConfigFile::fee_estimator`], and [`FeeEstimationConfigFile::cost_metric`] are ignored. + /// [`FeeEstimationConfigFile::fee_estimator`], and + /// [`FeeEstimationConfigFile::cost_metric`] are ignored. pub disabled: Option, /// If `true`, errors encountered during cost or fee estimation will be logged. /// This can help diagnose issues with the fee estimation subsystem. /// --- /// @default: `false` pub log_error: Option, - /// Specifies the fraction of random noise to add if using the `FuzzedWeightedMedianFeeRate` fee estimator. - /// This value should be in the range [0, 1], representing a percentage of the base fee rate. + /// Specifies the fraction of random noise to add if using the + /// `FuzzedWeightedMedianFeeRate` fee estimator. This value should be in the + /// range [0, 1], representing a percentage of the base fee rate. /// - /// For example, with a value of 0.1 (10%), fee rate estimates will have random noise added - /// within the range of ±10% of the original estimate. This randomization makes it difficult - /// for users to precisely optimize their fees while still providing reasonable estimates. + /// For example, with a value of 0.1 (10%), fee rate estimates will have random + /// noise added within the range of ±10% of the original estimate. This + /// randomization makes it difficult for users to precisely optimize their fees + /// while still providing reasonable estimates. /// --- /// @default: `0.1` (10%) /// @notes: @@ -3989,16 +4099,16 @@ pub struct FeeEstimationConfigFile { /// This determines how many historical fee rate data points are considered /// when calculating the median fee rate. /// - /// The window size controls how quickly the fee estimator responds to changing - /// network conditions. A smaller window size (e.g., 5) makes the estimator more - /// responsive to recent fee rate changes but potentially more volatile. A larger - /// window size (e.g., 10) produces more stable estimates but may be slower to - /// adapt to rapid network changes. + // The window size controls how quickly the fee estimator responds to changing + // network conditions. A smaller window size (e.g., 5) makes the estimator more + // responsive to recent fee rate changes but potentially more volatile. A larger + // window size (e.g., 10) produces more stable estimates but may be slower to + // adapt to rapid network changes. /// --- /// @default: `5` /// @notes: - /// - This setting is primarily relevant when [`FeeEstimationConfigFile::fee_estimator`] is set to - /// `"FuzzedWeightedMedianFeeRate"`, as it's used by the underlying [`WeightedMedianFeeRateEstimator`]. + /// - This setting is primarily relevant when [`FeeEstimationConfigFile::fee_estimator`] is set + /// to `"FuzzedWeightedMedianFeeRate"`. pub fee_rate_window_size: Option, } @@ -4256,11 +4366,12 @@ impl AtlasConfigFile { #[derive(Clone, Deserialize, Default, Debug, Hash, PartialEq, Eq, PartialOrd)] #[serde(deny_unknown_fields)] pub struct EventObserverConfigFile { - /// URL endpoint (hostname and port) where event notifications will be sent via HTTP POST requests. + /// URL endpoint (hostname and port) where event notifications will be sent via + /// HTTP POST requests. /// /// The node will automatically prepend `http://` to this endpoint and append the - /// specific event path (e.g., `/new_block`, `/new_mempool_tx`). - /// Therefore, this value should be specified as `hostname:port` (e.g., "localhost:3700"). + /// specific event path (e.g., `/new_block`, `/new_mempool_tx`). Therefore, this + /// value should be specified as `hostname:port` (e.g., "localhost:3700"). /// /// This should point to a service capable of receiving and processing Stacks event data. /// --- @@ -4273,18 +4384,20 @@ pub struct EventObserverConfigFile { pub endpoint: String, /// List of event types that this observer is configured to receive. /// - /// Each string in the list specifies an event category or a specific event to subscribe to. - /// For an observer to receive any notifications, this list must contain at least one valid key. - /// Providing an invalid string that doesn't match any of the valid formats below will cause - /// the node to panic on startup when parsing the configuration. + /// Each string in the list specifies an event category or a specific event to + /// subscribe to. For an observer to receive any notifications, this list must + /// contain at least one valid key. Providing an invalid string that doesn't match + /// any of the valid formats below will cause the node to panic on startup when + /// parsing the configuration. /// - /// All observers, regardless of their `events_keys` configuration, implicitly receive - /// payloads on the `/attachments/new` endpoint. + /// All observers, regardless of their `events_keys` configuration, implicitly + /// receive payloads on the `/attachments/new` endpoint. /// /// Valid Event Keys: /// - `"*"`: Subscribes to a broad set of common events. /// - Events delivered to: - /// - `/new_block`: For blocks containing transactions that generate STX, FT, NFT, or smart contract events. + /// - `/new_block`: For blocks containing transactions that generate STX, FT, + /// NFT, or smart contract events. /// - `/new_microblocks`: For all new microblock streams. Note: Only until epoch 2.5. /// - `/new_mempool_tx`: For new mempool transactions. /// - `/drop_mempool_tx`: For dropped mempool transactions. @@ -4293,7 +4406,8 @@ pub struct EventObserverConfigFile { /// /// - `"stx"`: Subscribes to STX token operation events (transfer, mint, burn, lock). /// - Events delivered to: `/new_block`, `/new_microblocks`. - /// - Payload details: The "events" array in the delivered payloads will be filtered to include only STX-related events. + /// - Payload details: The "events" array in the delivered payloads will be + /// filtered to include only STX-related events. /// /// - `"memtx"`: Subscribes to new and dropped mempool transaction events. /// - Events delivered to: `/new_mempool_tx`, `/drop_mempool_tx`. @@ -4305,9 +4419,10 @@ pub struct EventObserverConfigFile { /// - Events delivered to: `/new_microblocks`. /// - Payload details: /// - The "transactions" field will contain all transactions from the microblocks. - /// - The "events" field will contain STX, FT, NFT, or specific smart contract events - /// *only if* this observer is also subscribed to those more specific event types - /// (e.g., via `"stx"`, `"*"`, a specific contract event key, or a specific asset identifier key). + /// - The "events" field will contain STX, FT, NFT, or specific smart contract + /// events *only if* this observer is also subscribed to those more specific + /// event types (e.g., via `"stx"`, `"*"`, a specific contract event key, + /// or a specific asset identifier key). /// - Note: Only until epoch 2.5. /// /// - `"stackerdb"`: Subscribes to StackerDB chunk update events. @@ -4320,13 +4435,16 @@ pub struct EventObserverConfigFile { /// - Format: `"{contract_address}.{contract_name}::{event_name}"` /// (e.g., `ST0000000000000000000000000000000000000000.my-contract::my-custom-event`) /// - Events delivered to: `/new_block`, `/new_microblocks`. - /// - Payload details: The "events" array in the delivered payloads will be filtered for this specific event. + /// - Payload details: The "events" array in the delivered payloads will be + /// filtered for this specific event. /// - /// - Asset Identifier for FT/NFT Events: Subscribes to events (mint, burn, transfer) for a specific Fungible Token (FT) or Non-Fungible Token (NFT). + /// - Asset Identifier for FT/NFT Events: Subscribes to events (mint, burn, + /// transfer) for a specific Fungible Token (FT) or Non-Fungible Token (NFT). /// - Format: `"{contract_address}.{contract_name}.{asset_name}"` - /// (e.g., for an FT: `ST0000000000000000000000000000000000000000.my-ft-contract.my-fungible-token`) + /// (e.g., for an FT: `ST0000000000000000000000000000000000000000.contract.token`) /// - Events delivered to: `/new_block`, `/new_microblocks`. - /// - Payload details: The "events" array in the delivered payloads will be filtered for events related to the specified asset. + /// - Payload details: The "events" array in the delivered payloads will be + /// filtered for events related to the specified asset. /// --- /// @default: No default. /// @required: true @@ -4342,29 +4460,33 @@ pub struct EventObserverConfigFile { pub events_keys: Vec, /// Maximum duration (in milliseconds) to wait for the observer endpoint to respond. /// - /// When the node sends an event notification to this observer, it will wait at most this long - /// for a successful HTTP response (status code 200) before considering the request timed out. - /// If a timeout occurs and retries are enabled (see [`EventObserverConfig::disable_retries`]), - /// the request will be attempted again according to the retry strategy. + /// When the node sends an event notification to this observer, it will wait at + /// most this long for a successful HTTP response (status code 200) before + /// considering the request timed out. If a timeout occurs and retries are enabled + /// (see [`EventObserverConfigFile::disable_retries`]), the request will be attempted + /// again according to the retry strategy. /// --- /// @default: `1_000` /// @units: milliseconds pub timeout_ms: Option, - /// Controls whether the node should retry sending event notifications if delivery fails or times out. + /// Controls whether the node should retry sending event notifications if delivery + /// fails or times out. /// - /// - If `false` (default): The node will attempt to deliver event notifications persistently. - /// If an attempt fails (due to network error, timeout, or a non-200 HTTP response), the event - /// payload is saved and retried indefinitely. This ensures that all events will eventually be - /// delivered. However, this can cause the node's block processing to stall if an observer is - /// down, or indefinitely fails to process the event. + /// If `false` (default): The node will attempt to deliver event notifications + /// persistently. If an attempt fails (due to network error, timeout, or a + /// non-200 HTTP response), the event payload is saved and retried indefinitely. + /// This ensures that all events will eventually be delivered. However, this can + /// cause the node's block processing to stall if an observer is down, or + /// indefinitely fails to process the event. /// - /// - If `true`: The node will make only a single attempt to deliver each event notification. - /// If this single attempt fails for any reason, the event is discarded, and no further retries - /// will be made for that specific event. + /// - If `true`: The node will make only a single attempt to deliver each event + /// notification. If this single attempt fails for any reason, the event is + /// discarded, and no further retries will be made for that specific event. /// --- /// @default: `false` (retries are enabled) /// @notes: - /// - **Warning:** Setting this to `true` can lead to missed events if the observer endpoint is temporarily unavailable or experiences issues. + /// - **Warning:** Setting this to `true` can lead to missed events if the + /// observer endpoint is temporarily unavailable or experiences issues. pub disable_retries: Option, }