Run a Validator
Setup Guide

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)
⚠️

These requirements are a starting point. As GenLayer evolves and usage patterns change (e.g., more complex AI-driven Intelligent Contracts), the recommended hardware may change.

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 "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 -u

    You should see a list like this

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

    Typically you will want to run the latest version

  2. Download the packaged application

    export version=v0.2.0-testnet002 # 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" # Log level
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.

💡

GenLayer has partnered with Heurist (opens in a new tab) is a Layer 2 network for AI model hosting and inference, built on the ZK Stack. It offers serverless access to open-source AI models through a decentralized network.

GenLayer Validators can obtain free Heurist API credits (opens in a new tab) by using the referral code: "genlayer".

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.

  1. 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.

💡

Greyboxing is an advanced feature. Familiarity with Lua scripting and LLM prompt engineering is recommended for customization.

genvm-module-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
🏗️

More features and built-in filters will be added soon

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
🚨

Important: Back up your validator key! Losing access to this key means losing control of your validator. Store the backup 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" --export "/path/to/your/secure/backup.key" -c $(pwd)/configs/node/config.yaml

Remember both the node password (used during setup) and the backup encryption passphrase.

Currently the GenLayer Testnet is permissioned. You can apply to be selected by filling out the following form (opens in a new tab)

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-module-web & ./third_party/genvm/bin/genvm-module-llm run &

Note: If you are using the default configuration, genvm.manage_modules is set to true by default, meaning the node will manage these modules automatically.

  1. 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

If you are running the node via SSH, the process might terminate if your connection drops. To prevent this, consider using a terminal multiplexer like screen or tmux to keep the node running in the background even if your SSH session ends. You can find a guide on using screen here (opens in a new tab).