Setting Up Your GenLayer Validator

Running a GenLayer Validator node ensures the security and reliability of the GenLayer network. Below are the requirements for running a GenLayer validator.

Dependencies

LLM Access

Each validator needs access to a Large Language Model (LLM) for executing and evaluating Intelligent Contracts.

It is up to each validator to select the model they want to use.

Possible options:

• Run an open-source model locally on the same machine with a GPU
• Run an open-source model on a different machine
• Connect to a hosted inference provider (OpenAI, Anthropic, Heurist, Atoma network etc.)

ZKSync Full Node for the GenLayer Chain

Each validator needs access to a ZKSync Full Node (opens in a new tab) connected to the GenLayer chain. Validators use this node to read the chain state and submit transactions.

One full node can be shared between multiple validators. The optimal validator-to-node ratio is currently under evaluation.

System Requirements

Below are the initial recommended system requirements. These guidelines may change as the network grows and evolves.

RAM

• Recommended: 16 GB
• Why:
  • GenLayer's genvm can spawn multiple Sub-VMs for contract calls and non-deterministic blocks.
  • Each Sub-VM can consume up to ~4 GB of RAM for storage.

CPU

• Recommended: Modern multi-core processor with at least 8 cores/16 threads

Architecture

• Recommended: AMD64
• ARM64 is not supported at this time

Storage

• Recommended Disk Space: 128 GB+
• Preferred Type: SSD or NVMe (M.2)

Network

• 100 Mbps connection
• Recommended:: 1 Gbps+

GPU (Optional)

• GPU is Not Required
• If you want to run LLMs locally, you will need to select appropriate hardware (typically a CUDA-compatible GPU with sufficient VRAM for the model you intend to use)

Software

• Operating System - 64-bit Linux (Ubuntu, Debian, CentOS, etc.)
• docker - for running the WebDriver container

Setup

Download the node software

1. Select the version of the node you want to run by checking the available builds

   You can use this command to list available versions:

   curl -s "https://storage.googleapis.com/storage/v1/b/gh-af/o?prefix=genlayer-node/bin/amd64" | grep -o '"name": *"[^"]*"' | sed -n 's/.*\/\(v[0-9.]*-[^/]*\)\/.*/\1/p' | sort -ru

   You should see a list like this

      v0.2.0-testnet007
      v0.2.0-testnet006
      v0.2.0-testnet005
      v0.2.0-testnet004
      v0.2.0-testnet003
      v0.2.0-testnet002
      v0.2.0-testnet001
      v0.1.0-testnet008
      v0.1.0-testnet007
      v0.1.0-testnet006
      v0.1.0-testnet005
      v0.1.0-testnet004
      v0.1.0-testnet003
      v0.1.0-testnet002
      v0.0.0-test019
      v0.0.0-test018

   Typically you will want to run the latest version

2. Download the packaged application

   export version=v0.2.0-testnet007 # set your desired version here
   wget https://storage.googleapis.com/gh-af/genlayer-node/bin/amd64/${version}/genlayer-node-linux-amd64-${version}.tar.gz

3. Extract the node software

   tar -xzvf genlayer-node-linux-amd64-${version}.tar.gz

4. Change the directory

   cd genlayer-node-linux-amd64

Configuration

Before you can start up the node, you need to configure it.

config.yaml

This is the main configuration file of your node. Without it, your node won't start

The file needs to be located at configs/node/config.yaml

You can use the following example configuration. Note: For most users, you will only need to modify the zksyncurl and zksyncwebsocketurl values below.

rollup:
  zksyncurl: "TODO: Set your GenLayer Chain ZKSync HTTP RPC URL here" # ZKSync RPC URL
  zksyncwebsocketurl: "TODO: Set your GenLayer Chain ZKSync WebSocket RPC URL here" # ZKSync WebSocket URL
consensus:
  contractmanageraddress: "0x12290919253844d3400432Aebb5d0706D0f5865f" # ConsensusManager Smart Contract Address
  contractmainaddress: "0x174782d5819dD26F3d6967c995EE43db7DB824F8" # ConsensusMain Smart Contract Address
  contractdataaddress: "0x88B0F18613Db92Bf970FfE264E02496e20a74D16" # ConsensusData Smart Contract Address
  contractidlenessaddress: "0x2C0F0B98F52EB358410A825f68302653EAb5cc5B" # ConsensusIdleness Smart Contract Address
datadir: "./data/node" # Cache directory
logging:
  level: "INFO"
  # json: `true` for json output to console, false for human readable log formatting
  json: false
  # Configuration for https://github.com/natefinch/lumberjack
  file:
    # enabled: set to `true` to save logs to a folder
    enabled: true
    level: "DEBUG"
    # folder: path to the folder where to store logs. Relative paths go under `datadir`.
    folder: logs
    # maxsize: maximum size in megabytes of the log file before it gets rotated. It defaults to 100 megabytes.
    maxsize: 500
    # maxage: maximum number of days to retain old log files based on the timestamp encoded in their filename.
    maxage: 7
    # maxbackups: maximum number of old log files to retain. Set to 0 for no limit
    maxbackups: 10
    # localtime: determines if the time used for formatting the timestamps in backup files is the computer's local time. Set to `false` to use UTC time.
    localtime: false
    # compress: determines if the rotated log files should be compressed using gzip
    compress: true
node:
  mode: "validator" # "validator" or "archive"
  rpc:
    port: 9151 # JSON RPC port
    endpoints:
      groups:
        ethereum: true # Enable Ethereum RPC endpoints
        debug: false # Enable debug endpoints
      methods: # Enabled `eth_` methods
        eth_blockNumber: true
        eth_getBlockByNumber: true
        eth_getBlockByHash: true
        eth_sendRawTransaction: false
  ops:
    port: 9153 # Metrics port
    endpoints:
      metrics: true # Enable metrics endpoint
      health: true # Enable health endpoint
  dev: # Configuration for development purposes
    disableSubscription: false # Disable subscription
 
genvm:
  bin_dir: ./third_party/genvm/bin
  manage_modules: true
 
# Advanced configuration
merkleforest:
  maxdepth: 16
  dbpath: "./data/node/merkle/forest/data.db"
  indexdbpath: "./data/node/merkle/index.db"
merkletree:
  maxdepth: 16
  dbpath: "./data/node/merkle/tree/"

GenVM Configuration

You need to set up an LLM for your node to use to provide answers to natural language prompts. You can use any LLM you wish, however the quality of its answers will affect the performance of your node.

The GenVM configuration files are located at third_party/genvm/config/

genvm-module-llm.yaml

This is the configuration file of the LLM module. In this file you can set up and configure various LLM providers, as well as the system prompts of your validator.

You can turn on and off various LLMs by setting the enabled field to false.

At this stage, select one LLM and set all other to disabled.

Note environment variable name for LLM API keys (e.g., HEURISTKEY). You will need to ensure this key is correctly set before running the node.

genvm-module-web.yaml

This is the configuration of webdriver module that enables the GenVM to access the internet. You should not need to modify this.

genvm.yaml

This is the configuration of the GenVM itself, such as how many threads it can use and what are the addresses of various modules. You should not need to edit this file either.

2. Run precompilation of pre-delivered wasm modules (this step is optional but is highly recommended for improved performance)

   ./third_party/genvm/bin/genvm precompile
   Precompilation should be re-run after switching to a different node release

Greyboxing LLMs

Greyboxing is a way to further customise your LLM setup to improve its performance as well as security.

genvm-modules llm provides user with ability to customize greyboxing via lua scripting. Right now users can customize prompt templates, specify temperature and system prompt.

Related scripts are located at:

1. ./scripts/genvm-greyboxing.lua – user defined script
2. ./share/lib/genvm/greyboxing/lib-greyboxing.lua – more low-level library

Set Up The Validator Key

In this step we'll generate your validator key and address.

./bin/genlayernode account new -c $(pwd)/configs/node/config.yaml --setup --password "your secret password" # Remember it! You will need it to unlock your account when running the node

You should see the following output:

Account created:
  New address: 0xA0b12Fd2f3F7e86fEC458D114A5E7a6f571160a8
  Account setup as a validator

Backing Up Your Validator Key

After generating your validator key, it is critical to back it up securely.

You can export your key using the following command:

./bin/genlayernode account export \
--password "your node password" \
--address "your validator address" \
--passphrase "your backup encryption passphrase" \
--path "/path/to/your/secure/backup.key" \
-c $(pwd)/configs/node/config.yaml 

To print (display) the private key from your exported backup file, you can use the --print flag with the account export command. This will output the private key in plain text to your terminal. Keep this private key secure and never share it. You can use this private key to set up any other EVM-compatible wallet such as MetaMask.

Importing (Restoring) Your Validator Key

If you need to restore your validator key from a backup (for example, after migrating to a new server or recovering from data loss), you can import it using the following command:

./bin/genlayernode account import \
  --password "your node password" \
  --passphrase "your backup encryption passphrase" \
  --path "/path/to/your/secure/backup.key" \
  -c $(pwd)/configs/node/config.yaml \
  --setup

You should see the following output:

  Account imported:
    Address: 0xA0b12Fd2f3F7e86fEC458D114A5E7a6f571160a8
    Account setup as a validator

• The validator key will be imported and available for use by your node.

• You can now start your node as usual.

Running the node

Once you have configured everything, you are ready to start the node.

1. Set the LLM Provider API Key

   export HEURISTKEY='your_llm_provider_api_key'

2. Run the WebDriver container

   docker compose up -d # Starts the WebDriver needed by the GenVM web module

3. (Optional) Run two services (modules) in background (this is a crucial step for running Intelligent contracts). This can be done automatically or manually.

   • To start them automatically in node configuration set genvm.manage_modules to true
   • To start them manually run

      ./third_party/genvm/bin/genvm-modules web & ./third_party/genvm/bin/genvm-modules llm &

4. Run the node

   ./bin/genlayernode run -c $(pwd)/configs/node/config.yaml --password "your secret password" # The same password you used when creating the account

Common Issues

Node exits with exit code 1 without any error messages

Try running the node with

NODE_STARTUP_LOG_LEVEL=DEBUG ./bin/genlayernode run ...