From 3bca45e787c50d8e5c1331b841b2626fb74fc88c Mon Sep 17 00:00:00 2001 From: Pana Date: Fri, 21 Mar 2025 16:26:36 +0800 Subject: [PATCH 1/2] add node configuration doc --- docs/running-node/node-configuration.md | 116 ++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 docs/running-node/node-configuration.md diff --git a/docs/running-node/node-configuration.md b/docs/running-node/node-configuration.md new file mode 100644 index 0000000000..4c831c65e6 --- /dev/null +++ b/docs/running-node/node-configuration.md @@ -0,0 +1,116 @@ +# 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 +``` + +## Hardfork Configurations + +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. 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. + +There are two ways to specify activation heights: 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). + +The following are the CIP activation configuration options introduced in each version of Conflux-Rust: + +### v1.1 + +| Configuration Key | Required | CIP(s) | +|---------------------------------|------------------------------------|-----------------------| +| tanzanite_transition_height | ✅ | CIP40 | + +### v2.0 + +| Configuration Key | Required | CIP(s) | +|---------------------------------|------------------------------------|-----------------------| +| hydra_transition_number | ✅ | CIP43a, CIP64, CIP71, CIP78a, CIP92 | +| hydra_transition_height | ✅ | CIP76, CIP86 | +| cip43_init_end_number | ✅ | CIP43b | +| pos_reference_enable_height | ✅ | | +| cip78_patch_transition_number | | CIP78b | +| cip90_transition_height | | CIP90a | +| cip90_transition_number | | CIP90b | + +There are two configuration options for setting the proportion of eSpace transactions in the overall block space.: + +```toml +# The following parameter controls how many blocks are allowed to +# contain EVM Space transactions. Setting it to N means that one block +# must has a height of the multiple of N to contain EVM transactions. +evm_transaction_block_ratio=5 +# The following parameter controls the ratio of gas limit allowed for +# EVM space transactions. Setting it to N means that only 1/N of th +# block gas limit can be used for EVM transaction enabled blocks. +evm_transaction_gas_ratio=2 +``` + +### v2.1 + +| Configuration Key | Required | CIP(s) | +|---------------------------------|------------------------------------|-----------------------| +| dao_vote_transition_number | ✅ | CIP97, CIP98, CIP94n, CIP105 | +| dao_vote_transition_height | ✅ | CIP94h | +| cip105_transition_number | | CIP105 | + +### v2.2 + +| Configuration Key | Required | CIP(s) | +|---------------------------------|------------------------------------|-----------------------| +| sigma_fix_transition_number | ✅ | | + +### v2.3 + +| Configuration Key | Required | CIP(s) | +|---------------------------------|------------------------------------|-----------------------| +| cip107_transition_number | ✅ | CIP107 | +| cip112_transition_height | ✅ | CIP112 | +| cip118_transition_number | ✅ | CIP118 | +| cip119_transition_number | ✅ | CIP119 | + +### v2.4 + +| Configuration Key | Required | CIP(s) | +|---------------------------------|------------------------------------|-----------------------| +| next_hardfork_transition_number | ✅ | CIP131, CIP132, CIP133b, CIP137, CIP144, CIP145, Cancun Opcodes | +| next_hardfork_transition_height | ✅ | CIP130, CIP133, CIP1559 | +| cip1559_transition_height | | CIP1559 | +| cancun_opcodes_transition_number| | Cancun Opcodes | + +There are two configuration options for setting the minimum base price of Core Space and eSpace.: + +```toml +min_native_base_price=1000000000 # 1 GDrip +min_eth_base_price=1000000000 # 1 GDrip +``` + +### v2.5 + +| Configuration Key | Required | CIP(s) | +|---------------------------------|------------------------------------|-----------------------| +| c2_fix_transition_height | ✅ | | + +### v2.6 + +| Configuration Key | Required | CIP(s) | +|---------------------------------|------------------------------------|-----------------------| +| eoa_code_transition_height | ✅ | CIP7702 | +| align_evm_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. From a20ecaa8f569634417bfe7cb984f6b5c90cc043e Mon Sep 17 00:00:00 2001 From: Pana Date: Tue, 13 May 2025 15:00:37 +0800 Subject: [PATCH 2/2] update cip docs --- docs/running-node/cips-configuration.md | 157 ++++++++++++++++++++++++ docs/running-node/node-configuration.md | 99 ++------------- 2 files changed, 165 insertions(+), 91 deletions(-) create mode 100644 docs/running-node/cips-configuration.md 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 index 4c831c65e6..c82c838c56 100644 --- a/docs/running-node/node-configuration.md +++ b/docs/running-node/node-configuration.md @@ -12,105 +12,22 @@ The configuration file path can be specified using the command-line parameter `- ./conflux --config /path/to/your/config.toml ``` -## Hardfork Configurations +## 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. 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. +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. -There are two ways to specify activation heights: 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). - -The following are the CIP activation configuration options introduced in each version of Conflux-Rust: - -### v1.1 - -| Configuration Key | Required | CIP(s) | -|---------------------------------|------------------------------------|-----------------------| -| tanzanite_transition_height | ✅ | CIP40 | - -### v2.0 - -| Configuration Key | Required | CIP(s) | -|---------------------------------|------------------------------------|-----------------------| -| hydra_transition_number | ✅ | CIP43a, CIP64, CIP71, CIP78a, CIP92 | -| hydra_transition_height | ✅ | CIP76, CIP86 | -| cip43_init_end_number | ✅ | CIP43b | -| pos_reference_enable_height | ✅ | | -| cip78_patch_transition_number | | CIP78b | -| cip90_transition_height | | CIP90a | -| cip90_transition_number | | CIP90b | - -There are two configuration options for setting the proportion of eSpace transactions in the overall block space.: +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 -# The following parameter controls how many blocks are allowed to -# contain EVM Space transactions. Setting it to N means that one block -# must has a height of the multiple of N to contain EVM transactions. -evm_transaction_block_ratio=5 -# The following parameter controls the ratio of gas limit allowed for -# EVM space transactions. Setting it to N means that only 1/N of th -# block gas limit can be used for EVM transaction enabled blocks. -evm_transaction_gas_ratio=2 +default_transition_time = 1 +# cip1559 needs to be activated after the pos_reference_enable_height +pos_reference_enable_height = 1 ``` -### v2.1 - -| Configuration Key | Required | CIP(s) | -|---------------------------------|------------------------------------|-----------------------| -| dao_vote_transition_number | ✅ | CIP97, CIP98, CIP94n, CIP105 | -| dao_vote_transition_height | ✅ | CIP94h | -| cip105_transition_number | | CIP105 | - -### v2.2 - -| Configuration Key | Required | CIP(s) | -|---------------------------------|------------------------------------|-----------------------| -| sigma_fix_transition_number | ✅ | | - -### v2.3 - -| Configuration Key | Required | CIP(s) | -|---------------------------------|------------------------------------|-----------------------| -| cip107_transition_number | ✅ | CIP107 | -| cip112_transition_height | ✅ | CIP112 | -| cip118_transition_number | ✅ | CIP118 | -| cip119_transition_number | ✅ | CIP119 | - -### v2.4 - -| Configuration Key | Required | CIP(s) | -|---------------------------------|------------------------------------|-----------------------| -| next_hardfork_transition_number | ✅ | CIP131, CIP132, CIP133b, CIP137, CIP144, CIP145, Cancun Opcodes | -| next_hardfork_transition_height | ✅ | CIP130, CIP133, CIP1559 | -| cip1559_transition_height | | CIP1559 | -| cancun_opcodes_transition_number| | Cancun Opcodes | - -There are two configuration options for setting the minimum base price of Core Space and eSpace.: - -```toml -min_native_base_price=1000000000 # 1 GDrip -min_eth_base_price=1000000000 # 1 GDrip -``` - -### v2.5 - -| Configuration Key | Required | CIP(s) | -|---------------------------------|------------------------------------|-----------------------| -| c2_fix_transition_height | ✅ | | - -### v2.6 - -| Configuration Key | Required | CIP(s) | -|---------------------------------|------------------------------------|-----------------------| -| eoa_code_transition_height | ✅ | CIP7702 | -| align_evm_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. +This configuration will activate all implemented features at the first block after the genesis block. -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. +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).