diff --git a/docs/running-node/cips-configuration.md b/docs/running-node/cips-configuration.md new file mode 100644 index 0000000000..3a385177c3 --- /dev/null +++ b/docs/running-node/cips-configuration.md @@ -0,0 +1,157 @@ +# CIP Activation Configuration + +Each hardfork may involve two activation points: by **block height** or by **block number**. These terms have different meanings in Conflux: + +- **Block height** refers to the height of the pivot chain. +- **Block number** represents the total number of blocks in the full ledger. + +Typically, the block height is smaller than the block number. For a deeper understanding, refer to the [Conflux Ledger Structure Overview](https://doc.confluxnetwork.org/docs/general/conflux-basics/consensus-mechanisms/proof-of-work/tree-graph). + +## Configuration Hierarchy for CIP Activation Time + +The activation time for a CIP is configured through a hierarchical approach: + +### Highest Priority: CIP-Specific Configuration + +If the CIP has its own configuration parameter, the activation point specified by this parameter takes the highest priority. + +### Second Priority: Hardfork Configuration + +If the CIP does not have its own configuration parameter or the user has not specified one, the activation point is determined by the configuration parameters of the hardfork to which the CIP belongs. + +### Third Priority: Default Transition Time + +If the hardfork configuration parameters are not specified, the system uses the default_transition_time parameter. This parameter sets both the transition_number and transition_height of the hardfork to the value of default_transition_time. + +### Final Priority: Node Mode + +If default_transition_time is not specified, the activation time is determined based on the node's mode: + +For nodes in test or dev mode, the activation time is set to 1, meaning all CIPs are activated immediately after the blockchain starts. +For nodes in other modes, the activation time is set to infinity, meaning all CIPs are deactivated by default. +Recommendation +Configuring default_transition_time=1 is sufficient for launching a node with all the latest features, meeting most use cases. Fine-grained CIP activation configurations are primarily intended for developer debugging and are not recommended for mature products. + +### Caution + +While it is possible to modify the activation time and order of different CIPs using configuration parameters, deviating from the mainnet activation sequence (e.g., activating a CIP from V2.4 before a CIP from V2.1) may lead to unexpected outcomes. + +## Hardfork & CIPs Configuration + +The following are the hardfork and CIP activation configuration options introduced in each version of Conflux-Rust: + +### v1.1 + +#### Hardfork Configuration + +| Configuration Key | CIP(s) | +|---------------------------------|-----------------------| +| tanzanite_transition_height | CIP39, CIP40 | + +### v2.0 + +#### Hardfork Configuration + +| Configuration Key | CIP(s) | +|---------------------------------|-----------------------| +| hydra_transition_number | CIP43, CIP64, CIP71, CIP78, CIP92 | +| hydra_transition_height | CIP76, CIP86 | + +#### CIP Configuration + +| Configuration Key | CIP(s) | +|---------------------------------|-----------------------| +| cip78_patch_transition_number | CIP78 | +| cip90_transition_height | CIP90 point a | +| cip90_transition_number | CIP90 point b | + +#### PoS chain Configuration + +| Configuration Key | CIP(s) | +|---------------------------------|-----------------------| +| cip43_init_end_number | CIP43 | +| pos_reference_enable_height | | + +### v2.1 + +#### hardfork Configuration + +| Configuration Key | CIP(s) | +|---------------------------------|-----------------------| +| dao_vote_transition_number | CIP97, CIP98, CIP94, CIP105 | +| dao_vote_transition_height | CIP94 | + +#### CIP Configuration + +| Configuration Key | CIP(s) | +|---------------------------------|-----------------------| +| cip105_transition_number | CIP105 | + +### v2.2 + +#### Hardfork Configuration + +| Configuration Key | CIP(s) | +|---------------------------------|-----------------------| +| sigma_fix_transition_number | | + +### v2.3 + +#### CIP Configuration + +| Configuration Key | CIP(s) | +|---------------------------------|-----------------------| +| cip107_transition_number | CIP107 | +| cip112_transition_height | CIP112 | +| cip118_transition_number | CIP118 | +| cip119_transition_number | CIP119 | + +#### PoS chain Configuration + +| Configuration Key | CIP(s) | +|---------------------------------|-----------------------| +| cip113_transition_height | CIP113 | + +### v2.4 + +#### Hardfork Configuration + +| Configuration Key | Required | CIP(s) | +|---------------------------------|------------------------------------|-----------------------| +| base_fee_burn_transition_number | | CIP131, CIP132, CIP133, CIP137, CIP144, CIP145, CIP-141,142,143 | +| base_fee_burn_transition_height | | CIP130, CIP133, CIP1559 | + +#### CIP Configuration + +| Configuration Key | CIP(s) | +|---------------------------------|-----------------------| +| cip1559_transition_height | CIP1559 | +| cancun_opcodes_transition_number| CIP-141,142,143 | + +### v2.5 + +#### Hardfork Configuration + +| Configuration Key | Required | CIP(s) | +|---------------------------------|------------------------------------|-----------------------| +| c2_fix_transition_height | | | + +### v2.6 + +#### Hardfork Configuration + +| Configuration Key | Required | CIP(s) | +|---------------------------------|------------------------------------|-----------------------| +| eoa_code_transition_height | | CIP150 CIP151 CIP152 CIP154 CIP645 CIP7702 | +| align_evm_transition_height | | | + +#### CIP Configuration + +| Configuration Key | Required | CIP(s) | +|---------------------------------|------------------------------------|-----------------------| +| cip151_transition_height | | | +| cip645_transition_height | | | + +Note: `align_evm_transition_height` is a **devnet** only configuration. When this configuration is set, the node will align the canonical EVM opcodes gas cost. Which means the eSpace EVM is identical to the canonical EVM. + +There is a [template file](https://github.com/Conflux-Chain/conflux-docker/blob/master/fullnode-configs/dev-node/devnode.toml) that contains the activation configurations for various CIPs, which can be used as a reference. \ No newline at end of file diff --git a/docs/running-node/node-configuration.md b/docs/running-node/node-configuration.md new file mode 100644 index 0000000000..c82c838c56 --- /dev/null +++ b/docs/running-node/node-configuration.md @@ -0,0 +1,33 @@ +# Node Configuration + +The Conflux node configuration file is a TOML file. You can modify this file to configure the node's behavior. + +The official documentation provides an [introduction to the main configuration options](https://doc.confluxnetwork.org/docs/general/run-a-node/advanced-topics/node-configuration), where you can find the most commonly used configuration options along with their descriptions. + +In the `run` directory of this repository, there is a default configuration file, usually named `hydra.toml` (for mainnet) or `testnet.toml` (for testnet). This file contains almost all available configuration options with comments. You can modify this file to configure your node. + +The configuration file path can be specified using the command-line parameter `--config`, for example: + +```shell +./conflux --config /path/to/your/config.toml +``` + +## Enable all CIPs in private network + +As the Conflux network evolves, we introduce new features, fix bugs, and improve network performance through hard forks. Any changes involving consensus rule modifications are introduced via [CIPs (Conflux Improvement Proposals)](https://github.com/conflux-chain/cips), and each hard fork may include one or more CIPs. + +For a complete list of historically activated CIPs, refer to [this page](https://github.com/conflux-chain/cips?tab=readme-ov-file#activated). The list of all past hard forks can be found [here](https://github.com/conflux-chain/cips?tab=readme-ov-file#list-of-hardforks). + +Typically, node operators do not need to manually configure hard fork settings, as the upgrade heights for both the mainnet and testnet are fixed and hardcoded in the released Conflux node binaries. However, if you are setting up a [private network](https://doc.confluxnetwork.org/docs/general/run-a-node/advanced-topics/running-independent-chain), you may need to specify the activation height for each CIP according to your requirements. + +Most requirements for running a private network are to run an environment that includes all the latest features. Due to the peculiarities of the genesis block, features added by CIP cannot be activated in the genesis block. Therefore, the most common and simplest approach is to activate all features in the block immediately following the genesis block. + +```toml +default_transition_time = 1 +# cip1559 needs to be activated after the pos_reference_enable_height +pos_reference_enable_height = 1 +``` + +This configuration will activate all implemented features at the first block after the genesis block. + +More precise control over the activation timing of each feature is mainly used for code integration testing. If you are absolutely certain that you need to use this feature, please read [CIP configuration](./cips-configuration.md).