chore: document BurnchainConfig parameters #6005
Conversation
Jiloc
changed the title
stackslib/src/config/mod.rs
Outdated
| /// This setting determines network parameters (like chain ID, peer version), | ||
| /// default configurations, genesis block definitions, and overall node behavior. | ||
| /// | ||
| /// Supported values: `"mainnet"`, `"mocknet"`, `"helium"`, `"neon"`, `"argon"`, `"krypton"`, `"xenon"`, `"nakamoto-neon"`. |
There was a problem hiding this comment.
i'd argue to format this in a table (at least for now) because one of the questions that comes up is "what is xenon?"
perhaps something like this:
Supported values:
mainnet => mainnet
xenon => testnet
mocknet => regtest
...
i recognize it may be a bit messy - just trying to think of a way to make it more clear for users later on
There was a problem hiding this comment.
I like the idea, i can make a table
stackslib/src/config/mod.rs
Outdated
| /// The network-specific identifier used in P2P communication and database initialization . | ||
| /// Derived from `mode` during config load, unless explicitly overridden (for test purposes). | ||
| /// | ||
| /// Default: Derived from [`BurnchainConfig::mode`] ([`CHAIN_ID_MAINNET`] for `mainnet`, [`CHAIN_ID_TESTNET`] otherwise). |
There was a problem hiding this comment.
I wonder if we should add a warning to several of these settings i.e. "Don't modify this unless you really know what you're doing"
chain_id is a great example of this.
stackslib/src/config/mod.rs
Outdated
| /// 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 a miner's config file, allowing adjustment without restarting. | ||
| /// Primarily relevant for miners. | ||
| /// | ||
| /// Default: `20000` satoshis |
There was a problem hiding this comment.
This should probably have a disclaimer that it's only used when mining
There was a problem hiding this comment.
Might make sense to start an issue that this could be moved to the miner config section.
| pub username: Option<String>, | ||
| /// The password for authenticating with the bitcoin node's RPC interface. | ||
| /// Required if the bitcoin node requires RPC authentication. |
There was a problem hiding this comment.
This seems inconsistent, otherwise we would want to add Required if... to several other settings in this PR.
i.e.
Required if bitcoin p2p is on a non-default port
I'm not convinced of either option, it just seems a bit inconsistent is all.
stackslib/src/config/mod.rs
Outdated
| /// 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 Xenon testnet |
There was a problem hiding this comment.
| /// - "T2" for Xenon testnet | |
| /// - "T2" for testnet (xenon) |
| /// - 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. |
There was a problem hiding this comment.
Inconsistent use of this line. for example, pox_reward_length and pox_2_activation should probably also have this line (as well as a few others in this PR).
I think it should be present on any setting that is used for testing only
Co-authored-by: wileyj <[email protected]>
Description
Add documentation for all
BurnchainConfigparametersApplicable issues
second step of #5898
Additional info (benefits, drawbacks, caveats)
Checklist
docs/rpc/openapi.yamlandrpc-endpoints.mdfor v2 endpoints,event-dispatcher.mdfor new events)clarity-benchmarkingrepobitcoin-tests.yml