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
-
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
-
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
-
Extract the node software
tar -xzvf genlayer-node-linux-amd64-${version}.tar.gz
-
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.
- Run precompilation of pre-delivered wasm modules (this step is optional but is highly recommended for improved performance)
Precompilation should be re-run after switching to a different node release
./third_party/genvm/bin/genvm precompile
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:
./scripts/genvm-greyboxing.lua
– user defined script./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.
-
Set the LLM Provider API Key
export HEURISTKEY='your_llm_provider_api_key'
-
Run the WebDriver container
docker compose up -d # Starts the WebDriver needed by the GenVM web module
-
(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
totrue
- To start them manually run
./third_party/genvm/bin/genvm-module-web & ./third_party/genvm/bin/genvm-module-llm run &
- To start them automatically in node configuration set
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.
-
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).