Join the LUKSO node operators mailing list to stay up to date with important and critical updates.
Running a mainnet Node
Anyone is welcome to participate in the LUKSO network by running her/his own node. On this page, you will find the relevant information to configure and start your node. If you wish to stake LYX and run a validator node, you can check the Become a Validator page.
System Requirements
The system requirements will depend on the clients you are running. Please refer to the client specs for detailed information. Also, as the LUKSO blockchain is relatively new and small, you will be able to use a smaller SSD for storage as for other chains.
| Settings | Value |
|---|---|
| Operating System | Linux or macOS |
| Number of CPU cores | 4 |
| RAM | 16 GB |
| SSD (NVMe) | 100 GB |
Supported clients versions
The LUKSO network currently supports the following clients versions:
Execution Clients
| Client | Version | Github | Docs | Chat | Status | Support | Language | Donate |
|---|---|---|---|---|---|---|---|---|
| Geth | v1.14.13 | Stable | Linux, Win, macOS, ARM | Golang |  | |||
| Erigon | v2.61.0 | Stable | Linux, Win, macOS, ARM | Golang | | |||
| Besu | v24.12.2 | Stable | Linux, Win, macOS | Java | | |||
| Nethermind | v1.30.3 | Stable | Linux, Win, macOS, ARM | C# | |
Consensus Clients
| Client | Version | Github | Docs | Chat | Status | Support | Language | Donate |
|---|---|---|---|---|---|---|---|---|
| Prysm | v5.2.0 | Stable | Linux, Win, macOS, ARM | Golang | | |||
| Lighthouse | v6.0.1 | Stable | Linux, Win, macOS, ARM | Rust | | |||
| Teku | v24.12.1 | Stable | Linux, Win, macOS | Java | | |||
| Nimbus | v24.10.0 | Stable | Linux, Win, macOS | Nim | |
Running newer versions of the clients can potentially lead to validation issues, loss of funds, or even a validator slash.
Starting a Node
To start your clients and contribute to the LUKSO network, you have 4 options.
📦 With Dappnode
Difficulty: Easy 🌶️
LUKSO has partnered with Dappnode (announcement) to provide easy access for solo stakers/node runners.
👉 All the information are available in the Dappnode docs.
📟 With the LUKSO CLI
Difficulty: Medium 🌶️🌶️
The LUKSO CLI is a command line tool to install, manage and set up nodes and validators of different clients for the LUKSO blockchain. It provides simple and unified commands to interact with your node and runs natively on your operating system. The LUKSO CLI is officially supported for Ubuntu, Debian and macOS running on either x86 Intel and AMD Processors or Single Board ARM Computers.
For further information, you can check out the official LUKSO CLI Documentation. It does not stop you from running any supported clients, all configurations and flags can be passed down.
Install the LUKSO CLI
First, install the lukso command globally on your node machine.
curl https://install.lukso.network | sh
Create a working directory
The name of the directory myLUKSOnode in the commands below can be changed according to your preferences.
Next, create a working directory for your node's data and move into it. The directory is where everything regarding your blockchain node will be stored. Make sure to choose a proper name for your node folder. If you plan on running a validator later, this folder will also contain your validator key files by default.
mkdir myLUKSOnode && cd myLUKSOnode
Initialize the working folder, which will download the LUKSO network configuration and genesis files needed to sync with the LUKSO network.
lukso init
Depending on your configuration and permissions, you might need to run the commands as super user with the sudo command.
Install the clients
After the initialization is successful, you must download the blockchain clients, which will be managed from the CLI under the hood. They will be installed globally, need superuser permissions, and are set as default clients within your working directories configuration file. You will be asked which clients you want to download and install during the setup.
lukso install
Start the clients
The following command will spin up your execution and consensus client and connect to the mainnet.
Without specifying any flags, the node starts the regular synchronization process.
If you want more convenience and your validator to operate quickly, you can also use checkpoints. Checkpoint synchronization is a feature that significantly speeds up the initial sync time of the consensus client. If enabled, your node will begin syncing from a recently finalized consensus checkpoint instead of genesis. It will then download the rest of the blockchain data while your consensus is already running.
After the synchronization is finalized, you will end up with the equal blockchain data. You can use the flag on every startup. However, it shows the most significant effect when synchronizing from scratch or after an extended downtime. The shortcut is ideal for fresh installations, validator migration, or recovery.
- Checkpoint Synchronization
- Regular Synchronization
The shortcut is ideal for making installation, validator migration, or recovery much faster.
You will need the LUKSO CLI Version 0.8.0 or above in order to use the --checkpoint-sync command. If you are using an older version or run into issues, please pass down the checkpoint flag manually, as described in the LUKSO CLI Checkpoint Documentation.
lukso start --checkpoint-sync
The synchronization process will take multiple hours for the node to finalize.
Starting from the current version of the Lighthouse client software, it is mandatory to use checkpoint sync for initializing a fresh node. Without this, the node will fail to start and log the following error message: Syncing from genesis is insecure and incompatible with data availability checks. You should instead perform a checkpoint sync from a trusted node using the --checkpoint-sync-url option: lukso start --checkpoint-sync or use additional flag to force regular Lighthouse sync: lukso start --lighthouse-allow-insecure-genesis-sync
lukso start
Checking Processes
To check that everything is running correctly, you can see the status of all your clients using the status command. By default, the validator is not enabled. If you want to run your validator node, please have a look at the validator page.
lukso status
# INFO[0000] PID 39424 - Execution (geth): Running 🟢
# INFO[0000] PID 39430 - Consensus (prysm): Running 🟢
# INFO[0000] PID 39432 - Validator (validator): Stopped 🔘
The status command can also be used to check the connectivity to other node machines within the network, measuring active communication channels:
lukso status peers
# INFO[0000] Execution (Geth): Outbound: 28 | Inbound: 15 🟢
# INFO[0000] Consensus (Prysm): Outbound: 36 | Inbound: 21 🟢
Both lukso status commands are fetching information from your node in real-time and can change any time. In order to monitor the peers of the execution client, you may need to enable the API's admin namespace within your client configuration.
To check running clients in more detail, you can use the built-in logging command of the CLI. It will print out the current log messages of one client.
# Viewing the logs of the execution client
lukso logs execution
# Viewing the logs of the consensus client
lukso logs consensus
For more options, please check the LUKSO CLI Documentation.
To enable more advanced monitoring for your node, you can check the official network-docker-monitoring repository with a step-by-step guide.
🚢 With Docker
Difficulty: Hard 🌶️🌶️🌶️
We provide a basic repository with examples of docker-compose.yml files to run the LUKSO network.
We also created a "docker factory" web interface which allows you to generate your own docker-compose.yml files.
📄 With your own clients
Difficulty: Advanced 🌶️🌶️🌶️🌶️
You are in no way limited to the tools we provide. If you are a pro user, you can download and run the Erigon, Geth, Lighthouse, Prysm or any other clients in your preferred setup. Please refer to the LUKSO Mainnet network configuration repository to configure and start your node.
Additionally, some clients support LUKSO out of the box. This means you don't need to prepare your chain configurations beforehand and can use all the tools provided by that client. The list of these clients (with their respective guides) includes:
Execution layer clients:
- Besu Example command:
besu --network=lukso
You should consider adding more flags, e.g. --data-path=<PATH>
Consensus layer clients:
- Teku Example command:
teku --network=lukso
You should consider adding more flags, e.g. --data-base-path=<PATH>
It should be noted that a full PoS node consists of both execution and consensus layer processes. Both must be running in order to correctly add the third process, the validator.
Need Help?
Check the Network FAQ section.
Ask your question in the validators channel on the official LUKSO Discord server.
Further Reads
- LUKSO Mainnet Start Process Update #1
- LUKSO Mainnet Start Process Update #2
- LUKSO Mainnet Start Process Update #3
- Genesis Validators Deposit and Testnet Launch
- Genesis Validators, start your clients!
You can check out the following links for extended help or advice for setting up your node:
- Extended Wiki and LUKSO Node Guide by Felix Hildebrandt
- LUKSO Community Guides by Luksoverse
- ETHStaker Community Discord for running EVM Clients