LUKSO CLI

The LUKSO CLI is a command line tool to install, manage and set up validators of different clients for the LUKSO Blockchain. For more information and tutorial, please check the LUKSO Tech Docs.

Features

🧰 Installation of Execution, Consensus, and Validator Clients
📀 Running a node as a validator
📑 Accessing various client logs

Supported EVM Clients

The LUKSO CLI is able to install multiple clients for running the node.

Execution Clients: Geth, Erigon, Nethermind, Besu
Consensus Clients: Prysm, Lighthouse, Teku
Validator Staking Clients: Prysm, Lighthouse, Teku

Client versions

Client	Version	Release
Geth	v1.14.7	https://github.com/ethereum/go-ethereum/releases/tag/v1.14.7
Erigon	v2.60.4	https://github.com/ledgerwatch/erigon/releases/tag/v2.60.4
Nethermind	v1.27.0	https://github.com/NethermindEth/nethermind/releases/tag/1.27.0
Besu	v24.7.0	https://github.com/hyperledger/besu/releases/tag/24.7.0
Prysm	v5.0.4	https://github.com/prysmaticlabs/prysm/releases/tag/v5.0.4
Lighthouse	v5.2.1	https://github.com/sigp/lighthouse/releases/tag/v5.2.1
Teku	v24.6.1	https://github.com/Consensys/teku/releases/tag/24.6.1

More clients will be added in the future.

Supported Platforms

The LUKSO CLI is officially supported on Mac, Ubuntu, and Debian with the following architectures:

x86/x86_64: Intel and AMD Processors
ARM/aarch64: Single-Board Computers as M1 or Raspberry

The experience might differ with other setups or versions of these operating systems.

Setting up the Node

Process of setting up the node using the LUKSO CLI.

Installing the LUKSO CLI

Download and execute the LUKSO CLI installation script
Running this script will install the full LUKSO CLI on Mac and Linux
Installation directory: /usr/local/bin/lukso

# Might need admin access by typing `sudo` in front of the sh command
$ curl https://install.lukso.network | sh

Initialise the Working Directory

Create and move into a working directory for your node's data

# Exchange [folder_name] with the folder name you want
$ mkdir [folder_name] && cd ./[folder_name]

Initialize the working directory

# Downloads all network configs from https://github.com/lukso-network/network-configs
$ lukso init

Installing the Clients

Install choosen LUKSO clients into the working directory

# Installing Execution, Consensus, and Validator Client
# Might need admin access by typing `sudo` in front of the command
$ lukso install

Starting the Clients

Please refer to the start command below for more information.

Working Directories' Structure

As the LUKSO CLI is able to manage multiple clients for multiple blockchain networks in one folder, the structure of the node is set up in a generic way.

When initializing the node (with lukso init), a global configuration folder is created, which holds shared and unique client information for each type of network.
When executing commands, directories for the associated network type will be created accordingly.

Network Types: mainnet, testnet

Even if multiple networks are set up, only one can be active simultaneously, as the LUKSO CLI runs natively within your system environments.

lukso-node
│
├───configs                                 // Configuration
│   └───[network_type]                      // Network's Config Data
│       ├───shared
|       |   ├───genesis.json                // Genesis JSON Data
|       |   ├───genesis.ssz                 // Genesis Validator File
|       |   └───config.yaml                 // Global Client Config
│       ├───geth                            // Config for Geth Client
│       ├───prysm                           // Config for Prysm Client
│       ├───erigon                          // Config for Erigon Client
│       ├───nethermind                      // Config for Nethermind Client
│       ├───besu                            // Config for Besu Client
│       ├───teku                            // Config for Teku Client
│       └───lighthouse                      // Config for Lighthouse Client
│
├───[network_type]-keystore                 // Network's Validator Wallet
│   ├───keys                                // Encrypted Private Keys
│   ├───...                                 // Files for Signature Creation
|   ├───pubkeys.json                        // Validator Public Keys
|   ├───deposit_data.json                   // Deposit JSON for Validators
|   └───node_config.yaml                    // Node Configuration File
|
├───[network_type]-data                     // Network's Blockchain Data
│   ├───consensus                           // Storage of used Consensus Client
│   ├───execution                           // Storage of used Execution Client
│   └───validator                           // Storage of Validator Client
│
├───[network_type]-logs                     // Network's Logged Data
|
└───cli-config.yaml                         // Global CLI Configuration

Available Commands

Command	Description
`install`	Installs choosen clients (Execution, Consensus, Validator) and their binary dependencies
`update`	Update all currently selected clients to their newest versions
`update configs`	Update chain configuration files. This commands overwrites your oldchain configs, but keeps your client configs
`init`	Initializes the working directory, it's structure, and network configuration
`start`	Starts all or specific clients and connects to the specified network
`stop`	Stops all or specific clients that are currently running
`logs`	Listens to and logs all events from a specific client in the current terminal window
`status`	Shows the client processes that are currently running
`status peers`	Shows the peer count of your node
`reset`	Resets all or specific client data directories and logs excluding the validator keys
`validator import`	Import the validator keys in the wallet
`validator list`	Display the imported validator keys
`validator exit`	Issue an exit for your validator
`version`	Display the version of the LUKSO CLI that is currently installed
`help`, `h`	Shows the full list of commands, global options, and their usage

Global Help Flag

Flag	Description
--help, -h	Can be added before or after a command to show it's help page

Examples and Explanations

For almost each command in the list, options can be added after it to modify or specify certain behavior. Below, you can find examples and options tables for all available commands.

Options containting [string] expects a string input in quotes.

Options containting [int] expects an int input without quotes.

`install`

How to install the clients

# User is able to select its Consensus and Execution clients.
# Detects pre-installed clients and will ask for overrides
$ lukso install

# Installs clients and agrees with Terms & Conditions automatically
$ lukso install --agree-terms

Rollback clients to specific version

install command allows you to install a specific version of a client. This means that you can easily roll back any client to a version of your choice.

# To roll back a client to specific version, you need to specify which version do you want to install.
# Format of a flag is --<client>-tag, e.g. for Prysm:
$ lukso install --prysm-tag v5.0.4
# or Erigon:
$ lukso install --erigon-tag 2.55.0

# When rolling back Geth, please make sure to also provide first 8 characters of release commit hash.
# You can find those on Geth's download page: https://geth.ethereum.org/downloads
$ lukso install --geth-tag 1.14.7 --geth-commit-hash aa55f5ea

Options for `install`

Option	Description	Default
--agree-terms	Automatically accept Terms and Conditions	false
--geth-tag value	Tag for Geth	"1.14.7"
--geth-commit-hash value	A hash of commit that is bound to given release tag	"aa55f5ea"
--validator-tag value	Tag for validator binary	"v5.0.4"
--prysm-tag value	Tag for Prysm	"v5.0.4"
--erigon-tag value	Tag for Erigon	"2.60.4"
--lighthouse-tag value	Tag for Lighthouse	"v5.2.1"
--teku-tag value	Tag for Teku	"24.6.1"
--besu-tag value	Tag for Besu	"24.7.0"
--nethermind-tag value	Tag for Teku	"1.27.0"
--nethermind-commit-hash value	A hash of commit that is bound to given release tag	"220b5b85"
--help, -h	show help	false

`update`

update will install the newest verions of the clients that you selected duing installation process.

How to update clients

# starts an update of your selected clients - note that your node must be STOPPED before proceeding with update
$ lukso update

`update configs`

update configs Update chain configuration files. This commands overwrites your oldchain configs, but keeps your client configs.
In order to update your configs, you need to: 1) Have your node stopped 2) Be in the LUKSO CLI initialized directory

How to update chain config files

# starts an update of chain config files. 
$ lukso update configs

`start`

start will automatically start clients selected during the installation process and connect them to the network.
Please note that Teku needs a JDK installed in order to operate - this can be installed during the client installation process.

How to start the clients

# Starts your node and connects to LUKSO mainnet
# Uses the default config files from configs/mainnet folder
$ lukso start

# Starts your node and connects to mainnet as a validator
$ lukso start --validator --transaction-fee-recipient "0x1234..."

# Starts your node and connects to the LUKSO testnet
$ lukso start --testnet

# Starts your node and connects to testnet as a validator
$ lukso start --testnet --validator --transaction-fee-recipient "0x1234..."

How to start a node using config files

# Geth Configutation
# Change [config] to the name of your configuration file
$ lukso start --geth-config "./[config].toml"

# Prysm Configutation
# Change [config] to the name of your configuration file
# Change [custom_bootnode] to the bootnode's name
$ lukso start --prysm-config "./[config].yaml" --geth-bootnodes "[custom_bootnode]"

# Lighthouse Configutation
# Change [config] to the name of your configuration file
# Change [custom_bootnode] to the bootnode's name
$ lukso start --lighthouse-config "./[config].yaml" --lighthouse-bootnodes "[custom_bootnode]"

How to set up and customize a logs folder

# Setting up a custom logs directory
# Change [folder path] to a static or dynamic directory path
$ lukso start --logs-folder "[folder_path]"

Using Checkpoint Syncing

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.

Checkpoints with LUKSO CLI version 0.8

# Mainnet Checkpoint Sync for Consensus Client
$ lukso start --checkpoint-sync

# Testnet Checkpoint Sync for Consensus Client
$ lukso start --testnet --checkpoint-sync

LUKSO CLI takes advantage of a weak subjectivity checkpoint flag (varies across different clients) that allows you to specify a weak subjectivity checkpoint. With this flag specified, your beacon node will ensure that it reconstructs a historical chain that matches the checkpoint root at the given epoch. This can offer the same level of weak subjectivity protection that checkpoint sync offers. The CLI will automatically retrieve the latest finalized values to use with this feature.

Checkpoints with LUKSO CLI version 0.7 or below

Visit the Mainnet Checkpoint Explorer and get the latest block root and epoch. Then input both values into the flags below.

# Mainnet Checkpoint for Prysm Consensus Client
$ lukso start --prysm-checkpoint-sync-url=https://checkpoints.mainnet.lukso.network \
--prysm-genesis-beacon-api-url=https://checkpoints.mainnet.lukso.network/ \
--prysm-weak-subjectivity-checkpoint=$<BLOCK_ROOT>:$<EPOCH>

# Mainnet Checkpoint for Lighthouse Consensus Client
$ lukso start --lighthouse-checkpoint-sync-url=https://checkpoints.mainnet.lukso.network \
--lighthouse-genesis-beacon-api-url=https://checkpoints.mainnet.lukso.network/ \
--lighthouse-weak-subjectivity-checkpoint=$<BLOCK_ROOT>:$<EPOCH>

# Testnet Checkpoint for Prysm Consensus Client
$ lukso start --testnet --prysm-checkpoint-sync-url=https://checkpoints.testnet.lukso.network

# Testnet Checkpoint for Lighthouse Consensus Client
$ lukso start --testnet --lighthouse-checkpoint-sync-url=https://checkpoints.testnet.lukso.network

Possible issues

When starting prysm <=v4.0.8 after the v0.16.0 CLI update, you may encounter some configuration issues:

time="2024-02-27 11:32:55" level=error msg="There were some issues parsing the config from a yaml file" error="yaml: unmarshal errors:
line 113: field DENEB_FORK_VERSION not found in type params.BeaconChainConfig
line 119: field DENEB_FORK_EPOCH not found in type params.BeaconChainConfig"

Please note that this won't affect your node in any way.

Options for `start`

Option	Description
NETWORK
--mainnet	Starts the LUKSO node with mainnet data [default] (./configs/mainnet)
--testnet	Starts the LUKSO node with testnet data (./configs/tesnet)
--devnet	Starts the LUKSO node with devnet data (./configs/devnet)
VALIDATOR
--validator	Starts the validator client
--validator-keys [string]	Directory of the validator keys (default: "./[network_type]-keystore")
--validator-wallet-password [string]	Location of password file that you used for generated validator keys
--validator-config [string]	Path to prysms validator.yaml config file
--transaction-fee-recipient [string]	The address that receives block reward from transactions (required for --validator flag)
--genesis-json [string]	The path to genesis JSON file
--genesis-ssz [string]	The path to genesis SSZ file
--no-slasher	Disables slasher
CLIENT OPTIONS
--logs-folder [string]	Sets up a custom logs directory (default: "./[network_type]-logs")
--geth-config [string]	Defines the path to geth TOML config file
--prysm-config [string]	Defines the path to prysm YAML config file
--erigon-config [string]	Defines the path to erigon TOML config file
--nethermind-config [string]	Defines the path to nethermind CFG config file
--besu-config [string]	Defines the path to besu TOML config file
--teku-config [string]	Defines the path to teku YAML config file
--validator-config [string]	Defines the path to teku validator YAML config file
--geth-[command]	The `command` will be passed to the Geth client. See the client docs for details
--prysm-[command]	The `command` will be passed to the Prysm client. See the client docs for details
--lighhouse-[command]	The `command` will be passed to the Lighthouse client. See the client docs for details
--erigon-[command]	The `command` will be passed to the Erigon client. See the client docs for details
--teku-[command]	The `command` will be passed to the Teku client. See the client docs for details
--besu-[command]	The `command` will be passed to the Besu client. See the client docs for details
--nethermind-[command]	The `command` will be passed to the Nethermind client. See the client docs for details
--checkpoint-sync	Run a node with checkpoint sync feature

`stop`

How to stop all or specific clients

# Stops all running node clients
$ lukso stop

# Only stops the validator client
$ lukso stop --validator

# Only stops the execution client
$ lukso stop --execution

# Only stops the consensus client
$ lukso stop --consensus

Options for `stop`

Option	Description
--validator	Stops the validator client
--execution	Stops the execution client
--consensus	Stops the consensus client

`logs`

How to view logs of the clients

# Displays and saves the logs of the mainnet's consensus client
$ lukso logs consensus

# Displays and saves the logs of the devnet's execution client
$ lukso logs execution --devnet

# Displays and saves the logs of the testnet's validator
$ lukso logs validator --testnet

Options for `logs`

Option	Description
--mainnet	Logs the mainnet client [default] (./mainnet-logs/[client_type]/)
--testnet	Logs the testnet client (./testnet-logs/[client_type]/)
--devnet	Logs the devnet client (./devnet-logs/[client_type]/)

`status`

How to check the status of the node

# Shows which client processes are currently running
$ lukso status

`status peers`

How to get your peer count

# Shows the peer count of your node
$ lukso status peers

Ensure that the appropriate API is enabled when starting the node, as not all clients enable peer querying by default. For specific information about each client's peers queries, visit their documentation:

All supported consensus clients follow the Beacon API standardization.

`reset`

How to reset the node's data directory

# Resets LUKSO's mainnet data directory
$ lukso reset

# Resets LUKSO's testnet data directory
$ lukso reset --testnet

# Resets LUKSO's devnet data directory
$ lukso reset --devnet

Options for `reset`

Option	Description
--mainnet	Resets LUKSO's mainnet data [default]
--testnet	Resets LUKSO's testnet data
--devnet	Resets LUKSO's devnet data

`version`

How to check the version of the LUKSO CLI

# Displays the currently installed version of the LUKSO CLI
$ lukso version

`help`

In addition to the help command, the global help flag can be used to generate help pages for commands

How to retrieve the help page in the CLI

# Displays the global help page
$ lukso help

# Displays the help page of the start command
$ lukso start --help

# Displays the help page of the start command
$ lukso start -h

Running a Validator

Validator keys can be generated using:

CLI: tools-key-gen-cli
GUI: wagyu-key-gen

Both of them will generate the validator keys directory.

After generating the validator keys, they can be imported into the LUKSO CLI. To fill the validator keys with funds to participate on the LUKSO Blockchain, you must use the LUKSO Launchpad to send LYXe from your wallet to the generated keys.

Genesis Amounts

All genesis validators will be prompted to vote for the initial token supply of LYX
The initial token supply will determine how much LYX the Foundation will receive
More details at: https://deposit.mainnet.lukso.network

Validator Stake

Genesis Validators need to have at least 32 LYXe per validator
Validators also need some ETH on their wallet to pay for gas expenses

`validator import`

Import existing EIP-2335 keystore files (such as those generated by the Wagyu Keygen) into Prysm.

How to import validator keys

For validator import command the --validator-keys flag is required.

# Regular import process
# You will be asked for the passwords - of your validator keys and newly generated wallet

lukso validator import --validator-keys "./myKeysDir"

# You will be asked only for wallet password
lukso validator import --validator-keys "./myKeysDir" --validator-password "./myKeysPasswordFile.txt"

Options for `validator import`

Option	Description
--validator-keys [string]	Directory of the validator keys (default: "./[network_type]-keystore")
--validator-password [string]	Path to validator keys' password file
NETWORK
--mainnet	Will import the keys for mainnet [default] (Will use: "./mainnet-keystore")
--testnet	Will import the keys for testnet (Will use: "./testnet-keystore")
--devnet	Will import the keys for devnet (Will use: "./devnet-keystore")

`validator list`

List all imported keys from the validators keystore.

`validator exit`

Issue an exit for your validator keys that have set withdrawal credentials.

Running this command will take you to interactive version of exit command implemented by the respective consensus client developers (Running validator exit command while running Prysm consensus layer will take you to Prysm exit process etc.)

ETH1 withdrawal addresses are required for the exit to work. These are automatically generated by the Wagyu Key-Gen Tool. If you used BLS keys from the Key Gen CLI without specifying a withdrawal address, please update your withdrawal address credentials first.

IMPORTANT: The Validator exit is an irreversible action. Before exiting your validator you need make sure you are mindful of what the exit process carries with itself. #

Because different clients have different processes of exiting please make sure that you are familiar with the flags provided by the validator exit command.

How to exit validator keys

Make sure your validator node is running before starting the exit command.

# Exit validator keys with Prysm/Teku for Mainnet
sudo lukso validator exit

# Exit validator keys with Prysm/Teku for Testnet
sudo lukso validator exit --testnet

# Exit a validator key with Lighthouse for Mainnet - please note that you may issue an exit for only a single validator at a time
sudo lukso validator exit --keystore "./mainnet-keystore/keystore-xxx.json"

# Exit a validator key with Lighthouse for Testnet
sudo lukso validator exit --testnet --keystore "./testnet-keystore/keystore-xxx.json"

Note that each client that you use may have different exit process - you can read more about those on client's official documentation:

The Lighthouse client only allows to exit one validator key at a time. In case you have plenty of keys, please generate a separate keyfolder in a different working directory using Prysm. The new keystore folder can then be used for the exit command, even if your node is running the Lighthouse consensus client.

Option	Description
--keystore [string]	Path to keystore-xxx.json file containing public key that you want to exit - this flag is required when using Lighthouse validator
--validator-wallet-dir [string]	Path to wallet containing validators that you want to exit (default: "./mainnet-keystore" - is affected by the network flag)
--rpc-address [string]	Address of node that is used to make an exit (defaults to the default RPC address provided by your selected client)
--testnet-dir value	Path to network configuration folder (default: "./configs/mainnet/shared" - is affected by the network flag)
NETWORK
--mainnet	Will import the keys for mainnet [default] (Will use: "./mainnet-keystore")
--testnet	Will import the keys for testnet (Will use: "./testnet-keystore")
--devnet	Will import the keys for devnet (Will use: "./devnet-keystore")

How to import validator keys

# List imported keys for mainnet keystore
# You will be asked for the password
lukso validator list

# List imported keys for devnet keystore
# You will be asked for the password
lukso validator list --devnet

Options for `validator list`

Option	Description
NETWORK
--mainnet	Will list the keys for mainnet [default] (default: "./mainnet-keystore")
--testnet	Will list the keys for testnet (default: "./testnet-keystore")
--devnet	Will list the keys for devnet (default: "./devnet-keystore")

For specific validator options, please visit the Prysm Validator Specification. All flags and their parameters will be passed to the client. This can be useful to configure additional features like the validator's graffiti, extended logging, or connectivity options.

Starting the Validator

How to start your validator (keys & tx fee recipient)

When you use --validator, the --transaction-fee-recipient flag is required.

# Specify the transaction fee recipient, also known as coinbase
# It is the address where the transactions fees are sent to
$ lukso start --validator --transaction-fee-recipient "0x12345678..."

If you want to provide a specific keystore directory, you can use the --validator-keys flag. If no --validator-keys flag was specified, the CLI will look in the default directory: ./[network_type]-keystore.:

# Validator keys
# Command split across multiple lines for readability
# Change [file_name] with the your password text file's name
$ lukso start --validator \
--transaction-fee-recipient "0x12345678..." \
--validator-keys "./custom-keystore-dir-path"

How to start a genesis node

# Command split across multiple lines for readability
# Make sure that both SSZ and JSON files are placed correctly
$ lukso start \
--genesis-ssz "./config/mainnet/shared/genesis.ssz" \
--genesis-json "./config/mainnet/shared/genesis.json"

Uninstalling

The LUKSO CLI and downloaded clients are located within the binary folder of the user's system directory. It can be removed at any time. All node data is directly located within the working directory.

# Make sure to stop the node
$ lukso stop

# Uninstall the LUKSO CLI
$ rm -rf /usr/local/bin/lukso

# Uninstall Geth Execution Client
$ rm -rf /usr/local/bin/geth

# Uninstall Prysm Consensus Client
$ rm -rf /usr/local/bin/prysm

# Uninstall Lighthouse Consensus Client
$ rm -rf /usr/local/bin/lighthouse

# Uninstall Erigon Execution Client
$ rm -rf /usr/local/bin/erigon

# Remove the node data
# Make sure to backup your keys first
$ rm -rf ~/myNodeFolder

Known Issues

[Minor] With the v0.16.0 update, LUKSO CLI clients support the Cancun hardfork. To avoid uncontrolled forking, the LUKSO team have updated the chain config files, which can cause config unmarshalling errors for Prysm <=4.0.8. Client is still functioning as intended.
Example Prysm Error log:

time="2024-02-27 11:32:55" level=error msg="There were some issues parsing the config from a yaml file" error="yaml: unmarshal errors:
line 113: field DENEB_FORK_VERSION not found in type params.BeaconChainConfig
line 119: field DENEB_FORK_EPOCH not found in type params.BeaconChainConfig"

Contributing

If you want to contribute to this repository, please check CONTRIBUTING.md.

lukso-network / tools-lukso-cli

readme

LUKSO CLI

Features

Supported EVM Clients

Client versions

Supported Platforms

Setting up the Node

Installing the LUKSO CLI

Initialise the Working Directory

Installing the Clients

Starting the Clients

Working Directories' Structure

Available Commands

Global Help Flag

Examples and Explanations

install

How to install the clients

Rollback clients to specific version

Options for install

update

How to update clients

update configs

How to update chain config files

start

How to start the clients

How to start a node using config files

How to set up and customize a logs folder

Using Checkpoint Syncing

Checkpoints with LUKSO CLI version 0.8

Checkpoints with LUKSO CLI version 0.7 or below

Possible issues

Options for start

stop

How to stop all or specific clients

Options for stop

logs

How to view logs of the clients

Options for logs

status

How to check the status of the node

status peers

How to get your peer count

reset

How to reset the node's data directory

Options for reset

version

How to check the version of the LUKSO CLI

help

How to retrieve the help page in the CLI

Running a Validator

Genesis Amounts

Validator Stake

validator import

How to import validator keys

Options for validator import

validator list

validator exit

How to exit validator keys

How to import validator keys

Options for validator list

Starting the Validator

How to start your validator (keys & tx fee recipient)

How to start a genesis node

Uninstalling

Known Issues

Contributing

`install`

Options for `install`

`update`

`update configs`

`start`

Options for `start`

`stop`

Options for `stop`

`logs`

Options for `logs`

`status`

`status peers`

`reset`

Options for `reset`

`version`

`help`

`validator import`

Options for `validator import`

`validator list`

`validator exit`

Options for `validator list`