Getting Started

System Requirements

Before setting up an ENI node, ensure your system meets the following minimum requirements:

Hardware Specifications

Component
Minimum Requirement
Recommended Configuration
Notes

CPU

8 cores

16 cores

Modern processor (Intel Xeon/Core i7/i9 or AMD Epyc/Ryzen)

Memory

32GB

64GB

DDR4 or higher

Storage

1TB NVMe SSD

2TB NVMe SSD

High IOPS required; SATA SSD not recommended

Network

1Gbps

2Gbps

Low-latency connection is critical

Basic System Setup

Start with a fresh installation of Debian 12, Ubuntu 20.04 LTS (or higher). Then, update the system and install the necessary packages:

sudo apt update && sudo apt upgrade -y
sudo apt install make gcc git jq chrony curl lz4 wget tar build-essential -y

Tip: Ensure your system clock is synchronized (via chrony or ntpd) and your timezone is set to UTC to avoid potential issues with block validation, IBC transfers, etc.

Rapid deployment

Eni has a default configuration of four nodes for single-machine deployment, which can be used for rapid deployment and startup of the eni chain. If implementing commercialized deployment, please skip rapid deployment and start with custom deployment or automated setup scripts below.

Download the source code

git clone

Clone the go-eni project code from the eni code repository using the git tool.

One-click deployment

After downloading the code, enter the project directory go-eni. Then execute the following command to deploy and start a four-node eni blockchain on one machine with one click.

The make start-4-node command will automatically perform the following operations:

  • Compile the go-eni project code, create the go-eni/build directory, and place the generated eni executable file in the go-eni/build directory.

  • Read node1~ node4 in the default configuration directory of go-eni/eni-nodes, and start the four nodes node1~ node4 according to the default configuration.

After the command execution is completed, if the following information is printed, it indicates that the chain compile deployment has started successfully.

After startup, the log files of the node will be printed in the go-eni/build directory in real time. You can enter go-eni/build to view the log files of node1~ node4 and observe the operation of the chain and node.

One-click close

Execute the following command to shut down the service with one click.

After the command is executed, if the following information is printed, it indicates that the service has been successfully shut down.

After the service is shut down, it can be restarted by using the one-click deployment command make Start4-node. After startup, the chain still runs based on the last data. For example, if it was shut down when the block height was 88 last time, after this startup, the block height will start from 88.If you want to restart a chain from scratch, you need to clear the data from the last run and redeploy it with one click.

Custom Deployment

If developers are not satisfied with rapid deployment based on default configuration and default Port Number, they can generate custom configurations and specify port deployment to start a chain.

Download the source code

git clone

Clone the go-eni project code from the eni code repository using the git tool.

Configuration generation

Enter the go-eni project directory and execute the following command to generate a custom configuration for the four nodes. The information such as the founder account and validator account in the configuration will be randomly generated. Because the default configuration already exists in the go-eni/eni-nodes directory, it is necessary to delete the default configuration directory before executing the custom configuration command.

After the command is executed, a new custom configuration will be generated in the go-eni/eni-nodes directory, as shown in the following figure.

Here we need to focus on three documents:

  • node_key is the private key we use for network communication.

  • priv_validator_key is the private key used during the consensus period.

  • Keyring-test/validator1.info is the key file for collecting gas fee and block reward (there is no key by default, you can export the private key by the following command:

Configuration settings

After the custom configuration is generated, some configuration fields can be modified according to one's own needs.

app.toml configuration

The automatically generated app.toml file is missing EniDB Configuration and evm Configuration, so we need to manually append its content to the end of the app.toml file.

In the configuration of app.toml, the commonly used configuration item modifications are mainly the various fields under the state-store module and the evm module. Other fields generally use default values.

  • State-store module:

    • The ss-backend field specifies the database type. The optional database types can be found in the configuration comments. However, in daily life, the main choice is between leveldb and pebbledb. It is recommended that consensus nodes choose leveldb, which does not store historical data and can ensure higher consensus efficiency. It is recommended to choose pebbledb for synchronization nodes. For details, please refer to the appendix

  • EVM module:

    • http_enabled: whether the http service is enabled;

    • http_port: http Port Number, if it is a single deployment of multiple nodes, to avoid port conflicts, each node must be configured to different values.

    • ws_enabled: whether the websocket service is enabled;

    • ws_port: websocket Port Number, if it is a single machine deployment of multiple nodes, to avoid port conflicts, each node must be configured to different values.

Note: The configuration fields of the above common modification items can be configured to different values for each node according to its own situation, which will not affect the consensus consistency.

Contract administrator configuration

If the chain does not start the dpos mechanism, the consensus node set is the initial value configured by the genutil.gen_txs configuration item in the genesis.json configuration file (see the genesis.json configuration section for details). In the current version, we use the consensus mechanism that does not start the dpos, which has met the needs during the x play period.

However, for chain security, we still need to pay attention to the setting of the dpos administrator address to ensure that the key pair corresponding to the administrator address is managed by the official.Administrator privileges are crucial for the DPOS mechanism and consensus system. Therefore, if it is a custom-deployed chain, the default administrator address needs to be modified. The system contract of the DPOS series has a default administrator who is used to do some chain management work, including:

  • Set the initialization random value seed: In the DPOS mechanism, multiple block generation intervals can be set to one epoch period. Within each epoch period, the validator needs to send random values to the VRF contract of the DPOS for participation in consensus elections. The random values sent in each round are signed by the validator using their own private key for the previous random seed. The initial random value seed is passed in by the system admin, and subsequent random value seeds are generated by adding the random values of this round.

  • Verifier application review: If a user applies to become a verifier, the system admin needs to review the applicant's qualifications. If approved, it can be called a formal verifier participating in consensus election and block generation.

  • Verifier withdrawal: If a verifier requests to withdraw, the system admin also needs to pass the review to avoid a large number of verifiers suddenly withdrawing, exceeding the maximum consensus fault tolerance rate and causing the chain to fail to reach consensus.

  • System Contract Upgrade: The system contract uses a delegated call mechanism, where the proxy contract calls the logical contract to perform specific system functions. Administrators can deploy new logical contracts, pass in the address of the logical contract to replace the old one, and upgrade the system contract.

  • System admin change: system admin can transfer administrative permissions to other users, and will lose administrative permissions after transfer.

Modify the value of the update.contract_admin_addr field in the go-eni/app.toml configuration file to modify the default contract administrator address. Note that the default contract administrator address must be the same for all nodes on the chain.

Gas administrator configuration

The gas administrator has the authority to adjust the gas fee coefficients of the chain to adjust the transaction pressure and frequency of the chain, including:

  • base_fee_per_gas

  • maximum_fee_per_gas

  • max_dynamic_base_fee_upward_adjustment

  • max_dynamic_base_fee_downward_adjustment

  • target_gas_used_per_block

Modify the value of the update.gas_admin_addr field in the go-eni/app.toml configuration file to modify the default gas administrator address. Note that the default gas administrator address must be the same for all nodes on the chain, and the address must be of the eni address type.

Upgrade effective block high configuration

Each time the chain is upgraded, in order to ensure the consistency of the consensus across the network, a unified effective block height must be set for each node to be upgraded before the upgrade. When the block height reaches the effective block height, the upgraded logic will be executed concurrently.

When ENI fixed a bug caused by the consensus node slash mechanism, it had already undergone a mainnet upgrade. If other nodes want to join the ENI mainnet, they must also modify the effective block height to the same value as the mainnet before joining: 1982800. If the blockchain is deployed independently instead of joining the ENI mainnet, this value can be freely set.

Modify the value of the update.slashing_skip_height field in the go-eni/app.toml configuration file to modify the effective block height. Note that all nodes on the value chain must be the same.

config.toml configuration

note: the default configuration is already supported for commercial teams.

In the config.toml configuration file, commonly used configurations include the following fields:

  • Moniker: Node name, each node can be customized according to its own situation.

  • log_level: Log level, logs below the specified value will not be printed, for example, when it is info level, logs of debug and trace levels below info will not be printed.

  • genesis_file: Genesis file directory name.

  • p2p:

    • Laddr: The P2P port of this node, used for P2P communication between nodes. If deploying multiple nodes on a single machine, to avoid port conflicts, each node must be configured with different values.

    • persistent_peers: This node continues to link to the end node address and p2p port, similar to the seed node. If you create a configuration file to select multiple machines, you need to manually modify the IP here.

  • Mempool (default configuration already meets commercial requirements):

    • Size: The maximum number of transactions that can be stored in the transaction pool. It is recommended to configure the same value between nodes.

    • max_txs_bytes: the maximum total number of bytes of transactions that can be stored in the transaction pool;

    • cache_size: The maximum number of transactions that can be cached in the transaction pool. Cache is generally used for transaction plagiarism detection. The larger the cache, the larger the range of plagiarism detection, but it also consumes more memory.

    • Pending-size: Ethereum-type transactions with discontinuous nonce values will be placed in the pending transaction queue. Pending-size records the maximum value of the pending transaction queue.

    • max-pending-txs-bytes: records the total maximum number of bytes of pending transaction queue cache transactions.

  • Consensus (Consensus Configuration)

    • timeout_commit: Block interval, default is 5s, 1 s is recommended for commercial scenarios

genesis .json configuration

note: the default configuration is already supported for commercial teams

The configuration in genesis .json is a genesis configuration. Each node must be completely consistent, otherwise the chain will not be able to reach consensus at genesis. Generally, an error will be reported after startup, and the block cannot be grown.In the Genesis configuration, focus on whether the following fields need to be modified according to your own situation. It is recommended to use the default configuration values for configurations not mentioned.

  • app_state various configuration items under evm.params:

    • base_fee_per_gas: the base fee in the dynamic gas rate calculation;

    • minimum_fee_per_gas: the minimum value of gas price;

    • maximum_fee_per_gas: the maximum value of gas price;

    • max_dynamic_base_fee_upward_adjustment: the upper limit of the adjustment parameters in the dynamic rate;

    • max_dynamic_base_fee_downward_adjustment: the lower limit of the adjustment parameters in the dynamic rate;

    • init_eni_address: A list of account addresses generated by default at creation;

    • init_eni_amount: When creating, set the initial chain native token value for the default account address, that is, the ueni initial balance of the default account. Note that the assignment order must be the same as the init_eni_address, otherwise it will cause the problem of incorrect initial account balance.

  • Genesis transactions under Genutil.gen_txs body messages (these genesis transactions are transactions where staked tokens become consensus nodes):

    • pubkey.@type: Node public key type of the initial validator at chain startup;

    • Pubkey.key: The public key of the initial validator's node at chain startup. The public key is base64-encoded data used for message signing and verification during the consensus process.

Note: how many body configuration items are under genutil.gen_txs, how many initial validators will there be when the chain starts, and everything in the genesis .json configuration file must be exactly the same for each node in the chain.

Multi-machine deployment

After the configuration settings are completed, the eni needs to be deployed to different machines, and the machines must be able to communicate normally. Before deployment, package and send the compiled go-eni project to different designated machines.

Start eni on each node. Note that different nodes specify different configuration paths. For example, on node 1, specify./eni-nodes/node1, and on node 2, specify./eni-nodes/node2.

Full Node Deployment

Full nodes are asynchronous nodes that do not participate in the consensus of the chain and only synchronize blocks. If full nodes are not deployed, this chapter process can be skipped.

Copy configuration

Copy a configuration from any consensus node.

Modify config.toml

Modify the identity nickname moniker of the full node to avoid having the same name as other nodes.

Modify app.toml (optional modification, can be skipped)

Modify the database type in app.toml and enable historical data storage.

Delete nodes and validator key files

Non-consensus nodes must delete node_key and priv_validator_key files, otherwise they will interfere with consensus. After deletion, full nodes will regenerate their own node_key and priv_validator_key files.

Start the full node

After the configuration file is set up, compile the go-eni project and start the full node.

Automated setup scripts (development/testing)

In addition to one-click quick deployment and custom deployment, we also provide script automation deployment. This option is ideal when you want to quickly start a node without delving into manual configuration.

This script will guide you to choose:

  • Network: (mainnet, testnet or local)

  • Database backend: (recommended to use eni-db )

  • Basic configuration options

Advanced Synchronization Options

Choose one of the following synchronization methods based on your operational needs:

State Sync Configuration (Non-Archive Nodes)

State sync allows your node to catch up quickly by retrieving a recent snapshot from trusted peers instead of replaying all historical blocks.

Steps

Edit the [statesync] section: In ~/.eni/config/config.toml, update or add the following persistent peers:

Automate Trust Parameter Configuration:

Use the following script to dynamically set the trust height and hash based on the provided RPC endpoint:

Click to expand

Usage:

Ensure the [statesync] section already includes the persistent peers listed above.

Mempool Configuration Tuning

To optimize transaction processing and resource management, it’s recommended to update the mempool settings in the config.toml file as follows:

Suggestion: Adjust these parameters if you encounter performance or resource issues.

Set Up Service with systemd

Setting up a systemd service ensures your node starts automatically on boot and restarts if it crashes.

Note: Confirm that the User field suits your environment. Update it accordingly if running under a different user.

Validation and Troubleshooting

Validate Your Setup

Run the following commands to confirm the node’s status:

Your node is correctly set up when:

  • Sync status shows "catching_up": false

  • Logs indicate blocks are being processed

Common Troubleshooting Tips

Sync Issues

  • Verify sufficient disk space.

  • Ensure a stable network connection.

  • Confirm the system time is correctly synchronized.

  • Use state sync for rapid initial sync (note: not applicable for archive nodes).

Performance Issues

  • Monitor system resources (CPU, memory, I/O).

  • Evaluate disk performance and network bandwidth.

  • Adjust mempool and persistent peer settings if necessary.

Network Connectivity

  • Confirm firewall rules allow required ports (e.g., 26656, 26657, 9090).

  • Check that DNS resolution is functioning.

  • View system logs and node info via RPC [localhost:26657/net_info] to verify peer connections.

Next Steps

Once your node is up and running, consider the following:

  1. Monitoring and Alerts: Set up tools to monitor node health and performance.

  2. Security Best Practices: Harden your server (firewall, SSH keys, etc.).

  3. Backup Procedures: Regularly back up your configuration and data directories.

Additional documentation can be found at:

  • Advanced Configuration and Monitoring Guide

  • Node Operators Guide

  • Validators Guide

PreviousResourcesNextNode Operators Guide

Last updated