Skip to main content
Node operators mailing list

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.

A map fo the LUKSO mainnet network with genesis validators.

Map of the LUKSO genesis validators from the execution stats website - 19.09.23.

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.

SettingsValue
Operating SystemLinux or macOS
Number of CPU cores4
RAM16 GB
SSD (NVMe)100 GB

Supported clients versions

The LUKSO network currently supports the following clients versions:

Execution Clients

ClientVersionGithubDocsChatStatusSupportLanguageDonate
Gethv1.14.7StableLinux, Win, macOS, ARMGolang
Erigonv2.60.4Alpha & BetaLinux, Win, macOS, ARMGolang
Besuv24.7.0StableLinux, Win, macOSJava
Nethermindv1.27.0StableLinux, Win, macOS, ARMC#

Consensus Clients

ClientVersionGithubDocsChatStatusSupportLanguageDonate
Prysmv5.0.4StableLinux, Win, macOS, ARMGolang
Lighthousev5.2.1StableLinux, Win, macOS, ARMRust
Tekuv24.6.1StableLinux, Win, macOSJava
info

In preparation for the upcoming Dencun fork on LUKSO, we highly recommend node operators to update their clients and network configurations.

caution

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 🌶️

dappnode screenshot

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

tip

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
Sudo mode

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.

tip

The shortcut is ideal for making installation, validator migration, or recovery much faster.

info

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

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 🟢
info

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.

LUKSO Docker Factory

📄 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>

caution

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.

Configurations of all LUKSO networks

Need Help?

Check the Network FAQ section.

Ask your question in the validators channel on the official LUKSO Discord server.

Further Reads

You can check out the following links for extended help or advice for setting up your node: