Lisk node

Lisk provides a cost-efficient, fast, and scalable Layer 2 (L2) network based on Optimism (OP) that is secured by Ethereum.

This repository contains information on how to run your own node on the Lisk network.

System requirements

The following system requirements are recommended to run a Lisk L2 node.

Memory

• Modern multi-core CPU with good single-core performance
• Machines with a minimum of 16 GB RAM (32 GB recommended)

Storage

• Machines with a high performance SSD drive with at least 750GB (full node) or 4.5TB (archive node) free

Docker

• Docker Engine version 27.0.1 or higher

Supported networks

Network	Status
Lisk Sepolia	✅
Lisk Mainnet	✅

Usage

Note:

• It is currently not possible to run the nodes with the --op-network flag until the open PRs for adding configs for Lisk Sepolia and Lisk Mainnet are merged into the superchain-registry.

Clone the Repository

git clone https://github.com/LiskHQ/lisk-node.git
cd lisk-node

Docker

1. Ensure you have an Ethereum L1 full node RPC available (not Lisk), and set the OP_NODE_L1_ETH_RPC and the OP_NODE_L1_BEACON variables (within the .env.* files, if using docker-compose). If running your own L1 node, it needs to be synced before the Lisk node will be able to fully sync.

2. Please ensure that the environment file relevant to your network (.env.sepolia, or .env.mainnet) is set for the env_file properties within docker-compose.yml. By default, it is set to .env.mainnet.

3. We currently support running either the op-geth or the op-reth nodes alongside the op-node. By default, we run the op-geth node. If you would like to run the op-reth client, please set the CLIENT environment variable to reth before starting the node.

   Note:

   • The op-reth client can be built in either the maxperf (default) or release profile. To learn more about them, please check reth's documentation on Optimizations. Please set the RETH_BUILD_PROFILE environment variable accordingly.
   • Unless you are building the op-reth client in release profile, please ensure that you have a machine with 32 GB RAM.
   • Additionally, if you have the Docker Desktop installed on your system, please make sure to set Memory limit to a minimum of 16 GB.
     It can be set under Settings -> Resources -> Resource Allocation -> Memory limit.

4. Run:
   with op-geth:

   docker compose up --build --detach

   or, with op-reth:

   CLIENT=reth RETH_BUILD_PROFILE=release docker compose up --build --detach

5. You should now be able to curl your Lisk node:

   curl -s -d '{"id":0,"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["latest",false]}' \
     -H "Content-Type: application/json" http://localhost:8545

Source

Build

• Before proceeding, please make sure to install the following dependency (this information is missing in the OP documentations linked below):

  • jq

• To build op-node and op-geth from source, follow the OP documentation.

  • Before building the op-node, please patch the code with lisk-hotfix.patch for an unhandled SystemConfig event emitted on Lisk Sepolia, resulting in errors on the Lisk nodes.

    git apply <path-to-lisk-hotfix.patch>

• To build op-reth from source, follow the reth official documentation.

Set environment variables

Set the following environment variable:

export DATADIR_PATH=... # Path to the folder where geth data will be stored

Create a JWT Secret

op-geth and op-node communicate over the engine API authrpc. This communication can be secured with a shared secret which can be provided to both when starting the applications. In this case, the secret takes the form of a random 32-byte hex string and can be generated with:

openssl rand -hex 32 > jwt.txt

For more information refer to the OP documentation.

Initialize op-geth

Important: If you already had your node running prior to the Fjord upgrade (Sepolia: May 29, 2024 & Mainnet: July 10, 2024), please make sure to re-initialize your data directory with the updated genesis block. This is automatically taken care of for the Docker users.

Navigate to your op-geth directory and initialize the service by running the command:

./build/bin/geth init --datadir=$DATADIR_PATH PATH_TO_NETWORK_GENESIS_FILE

Note:

• Alternatively, this initialization step can be skipped by specifying --op-network=OP_NODE_NETWORK flag in the start commands below.
• This flag automatically fetches the necessary information from the superchain-registry.

Run op-geth

Navigate to your op-geth directory and start service by running the command:

./build/bin/geth \
    --datadir=$DATADIR_PATH \
    --verbosity=3 \
    --http \
    --http.corsdomain="*" \
    --http.vhosts="*" \
    --http.addr=0.0.0.0 \
    --http.port=8545 \
    --http.api=web3,debug,eth,net,engine \
    --authrpc.addr=0.0.0.0 \
    --authrpc.port=8551 \
    --authrpc.vhosts="*" \
    --authrpc.jwtsecret=PATH_TO_JWT_TEXT_FILE \
    --ws \
    --ws.addr=0.0.0.0 \
    --ws.port=8546 \
    --ws.origins="*" \
    --ws.api=debug,eth,net,engine \
    --metrics \
    --metrics.addr=0.0.0.0 \
    --metrics.port=6060 \
    --syncmode=full \
    --gcmode=full \
    --maxpeers=100 \
    --nat=extip:0.0.0.0 \
    --rollup.sequencerhttp=SEQUENCER_HTTP \
    --rollup.halt=major \
    --port=30303 \
    --rollup.disabletxpoolgossip=true

Refer to the op-geth configuration documentation for detailed information about available options.

Run op-reth

Navigate to your reth directory and start service by running the command:

./target/release/op-reth node \
  -vvv \
  --chain=PATH_TO_NETWORK_GENESIS_FILE \
  --datadir="$DATADIR_PATH" \
  --log.stdout.format log-fmt \
  --authrpc.addr=0.0.0.0 \
  --authrpc.port=8551 \
  --authrpc.jwtsecret=PATH_TO_JWT_TEXT_FILE \
  --ws \
  --ws.origins="*" \
  --ws.addr=0.0.0.0 \
  --ws.port=8546 \
  --ws.api=debug,eth,net,txpool \
  --http \
  --http.corsdomain="*" \
  --http.addr=0.0.0.0 \
  --http.port=8545 \
  --http.api=web3,debug,eth,net,txpool \
  --metrics=0.0.0.0:6060 \
  --disable-discovery \
  --port=30303 \
  --rollup.sequencer-http=SEQUENCER_HTTP \
  --rollup.disable-tx-pool-gossip

Refer to the reth configuration documentation for detailed information about available options.

Note:
Official Lisk Sequencer HTTP RPC:

• Lisk Sepolia: https://rpc.sepolia-api.lisk.com
• Lisk Mainnet: https://rpc.api.lisk.com

Run op-node

Navigate to your op-node directory and start service by running the command:

./bin/op-node \
  --l1=$OP_NODE_L1_ETH_RPC \
  --l1.rpckind=$OP_NODE_L1_RPC_KIND \
  --l1.beacon=$OP_NODE_L1_BEACON \
  --l2=ws://localhost:8551 \
  --l2.jwt-secret=PATH_TO_JWT_TEXT_FILE \
  --rollup.config=PATH_TO_NETWORK_ROLLUP_FILE

The above command starts op-node in full sync mode. Depending on the chain length, the initial sync process could take significant time; varying from days to weeks.

INFO [06-26|13:31:20.389] Advancing bq origin                      origin=17171d..1bc69b:8300332 originBehind=false

For more information refer to the OP documentation.

Note:

• In case you had skipped the op-geth initialization step above, you can start the node with the --network=OP_NODE_NETWORK flag.
• When specifying the --network flag, kindly make sure to remove the --rollup.config flag.

Refer to the op-node configuration documentation for detailed information about available options.

Note:
Some L1 nodes (e.g. Erigon) do not support fetching storage proofs. You can work around this by specifying --l1.trustrpc when starting op-node (add it in op-node-entrypoint and rebuild the docker image with docker compose build.) Do not do this unless you fully trust the L1 node provider.

Snapshots

Note: Currently, snapshots are only available for the op-geth client and are NOT regularly updated. We are currently working on improving this.

Docker

To enable auto-snapshot download and application, please set the APPLY_SNAPSHOT environment variable to true when starting the node.

APPLY_SNAPSHOT=true docker compose up --build --detach

Source

Please follow the steps below:

• Download the snapshot and the corresponding checksum from. The latest snapshot is always named geth-snapshot:

  • Sepolia: https://snapshots.lisk.com/sepolia
  • Mainnet: https://snapshots.lisk.com/mainnet

• Verify the integrity of the downloaded snapshot with:

  sha256sum -c <checksum-file-name>

• Import the snapshot

  ./build/bin/geth import --datadir=$GETH_DATA_DIR <path-to-snapshot>

Syncing

Sync speed depends on your L1 node, as the majority of the chain is derived from data submitted to the L1. You can check your syncing status using the optimism_syncStatus RPC on the op-node container. Example:

command -v jq  &> /dev/null || { echo "jq is not installed" 1>&2 ; }
echo Latest synced block behind by: \
$((($( date +%s )-\
$( curl -s -d '{"id":0,"jsonrpc":"2.0","method":"optimism_syncStatus"}' -H "Content-Type: application/json" http://localhost:9545 |
   jq -r .result.unsafe_l2.timestamp))/60)) minutes