Skip to content

add node configuration doc #3114

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
157 changes: 157 additions & 0 deletions docs/running-node/cips-configuration.md
Original file line number Diff line number Diff line change
@@ -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.
33 changes: 33 additions & 0 deletions docs/running-node/node-configuration.md
Original file line number Diff line number Diff line change
@@ -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).