From d68f75529c933bc0a478824526164accf33ce6c7 Mon Sep 17 00:00:00 2001 From: Darien Hernandez Date: Wed, 3 Dec 2025 15:28:38 +0100 Subject: [PATCH 01/21] docs: Update setup guide for v0.4.0 --- pages/validators/setup-guide.mdx | 461 ++++++++++++++++++++++++++++--- 1 file changed, 430 insertions(+), 31 deletions(-) diff --git a/pages/validators/setup-guide.mdx b/pages/validators/setup-guide.mdx index cfebfe4f..0525db99 100644 --- a/pages/validators/setup-guide.mdx +++ b/pages/validators/setup-guide.mdx @@ -85,6 +85,7 @@ Below are the **initial** recommended system requirements. These guidelines may You should see a list like this ```sh + v0.4.0 v0.3.11 v0.3.10 v0.3.9 @@ -105,23 +106,29 @@ Below are the **initial** recommended system requirements. These guidelines may v0.2.0-testnet001 ``` - Typically you will want to run the latest version + Typically, you will want to run the latest version -1. Download the packaged application +2. Download the packaged application ```sh - export version=v0.3.11 # set your desired version here + export version=v0.4.0 # set your desired version here wget https://storage.googleapis.com/gh-af/genlayer-node/bin/amd64/${version}/genlayer-node-linux-amd64-${version}.tar.gz ``` -1. Extract the node software +3. Extract the node software ```sh tar -xzvf genlayer-node-linux-amd64-${version}.tar.gz ``` -1. Change the directory +4. Change the directory ```sh cd genlayer-node-linux-amd64 ``` +5. Run Genvm setup + + ```sh + ./third_party/genvm/bin/genvm setup + ``` + ## Configuration Before you can start up the node, you need to configure it. @@ -137,20 +144,13 @@ You can use the following example configuration. **Note:** For most users, you w ```yaml # rollup configuration 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 + genlayerchainrpcurl: "https://asimov-chain-1.genlayerlabs.com/rpc" # GenLayer Chain RPC URL + genlayerchainwebsocketurl: "wss://asimov-chain-1.genlayerlabs.com/ws" # GenLayer Chain WebSocket URL # consensus contracts configuration consensus: - # Required addresses - these must be configured - contractmainaddress: "0xe30293d600fF9B2C865d91307826F28006A458f4" # ConsensusMain Smart Contract Address (REQUIRED) - contractdataaddress: "0x2a50afD9d3E0ACC824aC4850d7B4c5561aB5D27a" # ConsensusData Smart Contract Address (REQUIRED) - - # DEPRECATED: The following addresses are auto-discovered from ConsensusMain.GetContracts() - # These fields will be removed in v0.4.0. If present, values are IGNORED and a deprecation warning is logged. - # contractmanageraddress: "0x0761ff3847294eb3234f37Bf63fd7F1CA1E840bB" # DEPRECATED - Auto-discovered from ConsensusMain - # contractidlenessaddress: "0xD1D09c2743DD26d718367Ba249Ee1629BE88CF33" # DEPRECATED - Auto-discovered from ConsensusMain - # contractstakingaddress: "0x31Cb4018ccB7d4F30419d367b6C5c7677AAE30E7" # DEPRECATED - Auto-discovered from ConsensusMain - + # Asimov - Phase 4 + contractmainaddress: "0xe30293d600fF9B2C865d91307826F28006A458f4" # ConsensusMain Smart Contract Address + contractdataaddress: "0x2a50afD9d3E0ACC824aC4850d7B4c5561aB5D27a" # ConsensusData Smart Contract Address genesis: 817855 # (Optional) Genesis block number for this consensus deployment. If not provided, it will be auto-detected by searching for the first log from the ConsensusMain contract. # data directory @@ -181,12 +181,16 @@ logging: # node configuration node: - # Uncomment if the ID of the node is different from the consensus validator address. + # Uncomment if the ID of the node is different from the validator wallet address. # It is used to identify the node in the network. # id: "node" - # Mode can be "validator" or "archive". + # Mode can be "validator" or "full". # Default value is "validator". mode: "validator" + # Address of the ValidatorWallet contract (required for validator mode) + validatorWalletAddress: "" + # Address of the operator that owns the ValidatorWallet + operatorAddress: "" admin: port: 9155 rpc: @@ -209,22 +213,21 @@ node: eth_blockNumber: true eth_getBlockByNumber: true eth_getBlockByHash: true - eth_getBalance: true - eth_getTransactionCount: true - eth_getTransactionReceipt: true - eth_getLogs: true - eth_getCode: true - eth_sendRawTransaction: false - debug_icStateDump: false + eth_sendRawTransaction: true + zks_getTransaction: true ops: port: 9153 # Metrics port endpoints: metrics: true # Enable metrics endpoint health: true # Enable health endpoint balance: true # Enable balance endpoint + +# genvm configuration genvm: - bin_dir: ./third_party/genvm/bin - manage_modules: true # if true node will start genvm modules itself + root_dir: ./third_party/genvm + start_manager: true # if true node will start genvm manager itself + manager_url: http://127.0.0.1:3999 + permits: # Leave empty for autodiscovery, put a number for updating genvm permits on startup # Advanced configuration merkleforest: @@ -254,8 +257,6 @@ metrics: ``` - - ### 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. @@ -395,10 +396,296 @@ You should see the following output: validator address. +### Validator Joining the Network + +This section walks you through becoming a validator on the GenLayer testnet using the CLI. + +#### Prerequisites + +- Node.js installed +- GenLayer CLI installed (`npm install -g genlayer`) +- GEN tokens for staking (minimum stake required) + +#### Step 1: Create an Account + +```bash +genlayer account create +``` + +You'll be prompted to set a password. This creates an encrypted keystore file. + +#### Step 2: View Your Account + +```bash +genlayer account +``` + +Output: + +``` +{ + address: '0x86D0d159483CBf01E920ECfF8bB7F0Cd7E964E7E', + balance: '0 GEN', + network: 'localnet', + status: 'locked' +} +``` + +#### Step 3: Set Network to Testnet + +```bash +genlayer network testnet-asimov +``` + +Verify with: + +```bash +genlayer account +``` + +You should see `network: 'Asimov Testnet'`. + +#### Step 4: Fund Your Account + +Transfer GEN tokens to your address. You can: + +- Use the faucet (if available) +- Transfer from another account: + +```bash +genlayer account send 50000gen +``` + +#### Step 5: Check Staking Requirements + +```bash +genlayer staking epoch-info +``` + +Output: + +``` +{ + currentEpoch: '2', + epochStarted: '2025-01-15T00:00:00.000Z', + nextEpochEstimate: '2025-01-16T00:00:00.000Z', + timeUntilNextEpoch: '12h 30m', + minEpochDuration: '24h 0m', + validatorMinStake: '42000 GEN', + delegatorMinStake: '42 GEN', + activeValidatorsCount: '6', + epochInflation: '1000 GEN', + totalWeight: '500000000000000000000000', + totalClaimed: '500 GEN' +} +``` + +Note the `validatorMinStake` - you need at least this amount. + +#### Step 6: Unlock Your Account (Optional) + +For convenience, unlock your account to avoid entering password repeatedly: + +```bash +genlayer account unlock +``` + +This caches your private key in the OS keychain. + +#### Step 7: Join as Validator + +```bash +genlayer staking validator-join --amount 42000gen --operator 0xOperator... +``` + +Options: + +- `--amount ` - Stake amount (e.g., `42000gen` or `42000`) +- `--operator
` - Operator address (recommended, see below) + +##### Why Use an Operator Address? + + +**Recommended:** Use a separate operator address for security. + + +- **Validator wallet** - Holds your staked funds (keep offline/cold) +- **Operator wallet** - Signs blocks and performs validator duties (hot wallet on server) + +This way, if your operator server is compromised, your staked funds remain safe. + +```bash +# Create operator account on your validator server +genlayer account create --output ./operator.json + +# Get operator address +cat ./operator.json | jq -r .address +# 0xOperator123... + +# Join with separate operator (run from your main wallet) +genlayer staking validator-join --amount 42000gen --operator 0xOperator123... +``` + +You can change the operator later: + +```bash +genlayer staking set-operator --validator 0xYourValidator... --operator 0xNewOperator... +``` + +#### Step 8: Verify Your Validator Status + +```bash +genlayer staking validator-info +``` + +Output: + +``` +{ + validator: '0x86D0d159483CBf01E920ECfF8bB7F0Cd7E964E7E', + vStake: '42000 GEN', + vShares: '42000000000000000000000', + live: true, + banned: 'Not banned', + ... +} +``` + +#### Step 9: Set Validator Identity (Metadata) + +Set your validator's public identity so delegators can find you: + +```bash +genlayer staking set-identity \ + --validator 0x86D0...7E \ + --moniker "My Validator" \ + --website "https://myvalidator.com" \ + --description "Reliable validator with 99.9% uptime" \ + --twitter "myvalidator" \ + --github "myvalidator" +``` + +**Required:** + +- `--validator
` - Your validator address +- `--moniker ` - Display name for your validator + +**Optional:** + +- `--logo-uri ` - Logo image URL +- `--website ` - Website URL +- `--description ` - Description of your validator +- `--email ` - Contact email +- `--twitter ` - Twitter handle +- `--telegram ` - Telegram handle +- `--github ` - GitHub handle +- `--extra-cid ` - Additional data as IPFS CID + +Your identity will show in `validator-info`: + +```bash +genlayer staking validator-info +``` + +Output will include: + +``` +{ + ... + identity: { + moniker: 'My Validator', + website: 'https://myvalidator.com', + twitter: 'myvalidator', + github: 'myvalidator' + } +} +``` + +#### Managing Your Validator + +##### Add More Stake + +```bash +genlayer staking validator-deposit --amount 1000gen +``` + +##### Check Active Validators + +```bash +genlayer staking active-validators +``` + +##### Exit as Validator + +```bash +genlayer staking validator-exit --shares 100 +``` + +This initiates a withdrawal. Your tokens enter an **unbonding period of 7 epochs** before they can be claimed. + +Check your pending withdrawals with `validator-info`: + +``` +selfStakePendingWithdrawals: [ + { + epoch: '5', + shares: '100', + stake: '100 GEN', + claimableAtEpoch: '12', + status: 'Unbonding (4 epochs remaining)' + } +] +``` + +##### Claim Withdrawals + +After the 7-epoch unbonding period: + +```bash +genlayer staking validator-claim +``` + +#### Troubleshooting + +##### "No account found" + +Run `genlayer account create` first. + +##### "Insufficient balance" + +Ensure you have enough GEN. Check with `genlayer account`. + +##### "Below minimum stake" + +Check minimum with `genlayer staking epoch-info` and increase your stake amount. + +##### Transaction Stuck + +Check the transaction status: + +```bash +genlayer receipt +``` + +#### Lock Your Account + +When done, lock your account to remove the cached private key: + +```bash +genlayer account lock +``` ## Running the node - Once you have configured everything, you are ready to start the node. +Once you have configured everything, you are ready to start the node. + + + **Important: Before starting the node, ensure you have the operator address and validator wallet address + set up. If you do not have setup the validator wallet address, your node will not be able to validate, + therefore it will act as a full node instead. + + +### Running the Node using the binary 1. Set the LLM Provider API Key @@ -464,6 +751,114 @@ You should see the following output: [here](https://www.networkworld.com/article/967925/how-the-linux-screen-tool-can-save-your-tasks-and-your-sanity-if-ssh-is-interrupted.html). +### Running the Node using docker-compose + +You can also run the GenLayer node using Docker and Docker Compose. + +1. Create a `docker-compose.yaml` file with the following content: + +```yaml +services: + webdriver-container: + container_name: genlayer-node-webdriver + image: yeagerai/genlayer-genvm-webdriver:0.0.9 + shm_size: 2gb + security_opt: + - no-new-privileges:true + environment: + PORT: 4444 + ports: + - "${WEBDRIVER_PORT:-4444}:4444" + restart: unless-stopped + + genlayer-node: + image: yeagerai/genlayer-node:${NODE_VERSION:-latest} + entrypoint: [ + "sh", "-c", "/app/bin/genlayernode run --password ${NODE_PASSWORD:-12345678}", + ] + container_name: genlayer-node + restart: unless-stopped + env_file: + - path: ./.env + required: false + ports: + - "${NODE_RPC_PORT:-9151}:9151" + - "${NODE_OPS_PORT:-9153}:9153" + volumes: + - ${NODE_CONFIG_PATH:-./configs/node/config.yaml}:/app/configs/node/config.yaml:ro + - ${NODE_DATA_PATH:-./data}:/app/data + - ./genvm-module-web-docker.yaml:/app/third_party/genvm/config/genvm-module-web.yaml + security_opt: + - no-new-privileges:true + logging: + driver: "json-file" + options: + max-size: "100m" + max-file: "3" + compress: "true" + depends_on: + - webdriver-container + profiles: + - node + +``` + +2. Set the required environment variables in a `.env` file: + +```env +# GenLayer Node Release Configuration + +# ============================================================================= +# WebDriver Configuration (required for GenVM) +# ============================================================================= +WEBDRIVER_PORT=4444 + +# ============================================================================= +# Node Service Configuration (optional - use node profile) +# ============================================================================= +# Docker image version +NODE_VERSION=latest + +# Keystore password (used to unlock the pre-imported wallet) +NODE_PASSWORD=12345678 + +# Path to node configuration file +NODE_CONFIG_PATH=./configs/node/config.yaml + +# Path to node data directory (for persistence) +NODE_DATA_PATH=./data + +# Port mappings +NODE_RPC_PORT=9151 +NODE_OPS_PORT=9153 + +# LLM API Key (required for GenVM LLM module) +HEURISTKEY= +ANTHROPICKEY= +XAIKEY= +GEMINIKEY= +ATOMAKEY= +``` + +or simply use the provided `docker-compose.yaml` and the `.env.example` from the downloaded application packaged. + +3. Checking Your Configuration + +To ensure your node is correctly configured, you can run the following command: + +```sh +source .env && docker run --rm --env-file ./.env \ + -v ${NODE_CONFIG_PATH:-./configs/node/config.yaml}:/app/configs/node/config.yaml \ + yeagerai/genlayer-node:${NODE_VERSION:-latest} \ + ./bin/genlayernode doctor +``` + +4. Start the services using Docker Compose: + +```sh +source .env && docker compose --profile node up -d +``` + ## Monitoring with Metrics GenLayer validators expose comprehensive metrics that are ready for consumption by Prometheus and other monitoring tools. This allows you to monitor your validator's performance, health, and resource usage. @@ -538,3 +933,7 @@ curl -s http://localhost:9153/metrics | grep genlayer_node_ For production validators, we recommend setting up a complete monitoring stack with Prometheus and Grafana. This enables real-time visibility into your validator's performance and helps identify issues before they impact your validator's operation. + +### Logs and metrics forwarding + +You can forward your logs and metrics to external systems for centralized monitoring and alerting by using the service `alloy` provided in the `docker-compose.yaml` from the downloaded application packaged. From 54ebc23e15819668854d295ed100c1eb42b0fde5 Mon Sep 17 00:00:00 2001 From: Darien Hernandez Date: Wed, 3 Dec 2025 17:11:26 +0100 Subject: [PATCH 02/21] docs: Update changelog for v0.4.0 release with new features, bug fixes, and miscellaneous changes --- content/validators/changelog/v0.4.0.mdx | 72 ++++++++++++++++++++++++ pages/validators/changelog.mdx | 73 +++++++++++++++++++++++++ pages/validators/upgrade.mdx | 14 +++++ 3 files changed, 159 insertions(+) create mode 100644 content/validators/changelog/v0.4.0.mdx diff --git a/content/validators/changelog/v0.4.0.mdx b/content/validators/changelog/v0.4.0.mdx new file mode 100644 index 00000000..4e9de176 --- /dev/null +++ b/content/validators/changelog/v0.4.0.mdx @@ -0,0 +1,72 @@ +## v0.4.0 + +### New features + +- Migrate to new consensus staking +- Handle validator priming +- Finalize epochs +- Advance epochs when epochs finalize +- Handle automatic gas increase +- Implement ProcessIdleness and enhance event subscription +- Handle validator commit idleness for leader +- Implement leader idleness detection and rotation +- Add detailed ban information with epoch and permanent flag +- Handle unfinished transactions with batch finalization +- Add nonceSafe for granular transaction locking +- Add sanity check for operator address in validator wallet configuration +- Add missing fields from consensus transaction data to API response +- Add validator telemetry push monitoring +- Add actionable fix suggestions to WebDriver error messages in doctor command +- Add zkSync connectivity checks +- Add Staking Contract address comparison to doctor checks +- Add libertai as a new LLM provider +- Add transaction count metrics for consensus roles +- Implement consensus sync status metrics +- Add TimeoutsSet event router for dynamic timeout configuration +- Add enhanced transaction failure debugging with trace support +- Sync data with finalized and appeal started events +- Add timeout delay mechanism for RPC resilience +- Add status and blockNumber parameters to gen_call +- Enhance health endpoint with version info and validator with ban and permanent ban detection +- Update genvm version to v0.2.7 +- Store and expose genvm execution information +- Add sign admin endpoint for genvm + +### Bug fixes + +- GenVM architecture on arm64 +- Fix sync issue when there are no consensus events +- Use latest block instead of timestamp for transaction queries +- Update WebDriver check for Puppeteer implementation +- Resolve multi-transaction nonce issue +- Remove duplicated check logic and fix status check on specific block +- Leader rotation timeout and receipt cleanup +- Change transaction finalization to allow all nodes to finalize +- GenVM non determinism +- Add retry logic to prevent validator banning on transient errors +- GenVM sanity checks +- Cancel context and wait for group when genvm tester fails +- Decoding calldata into complex types +- Don't try activating already activated transactions +- Starting node +- Still process sync failed TX for DB consistency +- Add correct encoding for getState +- Only sync transactions with ResultCodeReturn and add sanity check +- Use block number for transaction data retrieval +- Validator votes idleness +- Leader idleness +- Accidental deadlock in genvm +- Lazy validators commit order + +### Misc + +- Simplify environment variable configuration using .env file +- Add environment variable override support for config values +- Update webdriver image to v0.0.9 +- Update RPC and WebSocket endpoints in config.yaml.example +- Correct status for validatorTimeout after appeal time window +- Validate presence of abigen in dependency check +- Rename environment validation functions for clarity +- Use cockroachdb errors package for error handling +- Remove wallet.yaml file handling +- Rename archive to full diff --git a/pages/validators/changelog.mdx b/pages/validators/changelog.mdx index ce32b9f3..3ccde325 100644 --- a/pages/validators/changelog.mdx +++ b/pages/validators/changelog.mdx @@ -1,5 +1,78 @@ # Changelog +## v0.4.0 + +### New features + +- Migrate to new consensus staking +- Handle validator priming +- Finalize epochs +- Advance epochs when epochs finalize +- Handle automatic gas increase +- Implement ProcessIdleness and enhance event subscription +- Handle validator commit idleness for leader +- Implement leader idleness detection and rotation +- Add detailed ban information with epoch and permanent flag +- Handle unfinished transactions with batch finalization +- Add nonceSafe for granular transaction locking +- Add sanity check for operator address in validator wallet configuration +- Add missing fields from consensus transaction data to API response +- Add validator telemetry push monitoring +- Add actionable fix suggestions to WebDriver error messages in doctor command +- Add zkSync connectivity checks +- Add Staking Contract address comparison to doctor checks +- Add libertai as a new LLM provider +- Add transaction count metrics for consensus roles +- Implement consensus sync status metrics +- Add TimeoutsSet event router for dynamic timeout configuration +- Add enhanced transaction failure debugging with trace support +- Sync data with finalized and appeal started events +- Add timeout delay mechanism for RPC resilience +- Add status and blockNumber parameters to gen_call +- Enhance health endpoint with version info and validator with ban and permanent ban detection +- Update genvm version to v0.2.7 +- Store and expose genvm execution information +- Add sign admin endpoint for genvm + +### Bug fixes + +- GenVM architecture on arm64 +- Fix sync issue when there are no consensus events +- Use latest block instead of timestamp for transaction queries +- Update WebDriver check for Puppeteer implementation +- Resolve multi-transaction nonce issue +- Remove duplicated check logic and fix status check on specific block +- Leader rotation timeout and receipt cleanup +- Change transaction finalization to allow all nodes to finalize +- GenVM non determinism +- Add retry logic to prevent validator banning on transient errors +- GenVM sanity checks +- Cancel context and wait for group when genvm tester fails +- Decoding calldata into complex types +- Don't try activating already activated transactions +- Starting node +- Still process sync failed TX for DB consistency +- Add correct encoding for getState +- Only sync transactions with ResultCodeReturn and add sanity check +- Use block number for transaction data retrieval +- Validator votes idleness +- Leader idleness +- Accidental deadlock in genvm +- Lazy validators commit order + +### Misc + +- Simplify environment variable configuration using .env file +- Add environment variable override support for config values +- Update webdriver image to v0.0.9 +- Update RPC and WebSocket endpoints in config.yaml.example +- Correct status for validatorTimeout after appeal time window +- Validate presence of abigen in dependency check +- Rename environment validation functions for clarity +- Use cockroachdb errors package for error handling +- Remove wallet.yaml file handling +- Rename archive to full + ## v0.3.11 ### New features diff --git a/pages/validators/upgrade.mdx b/pages/validators/upgrade.mdx index d535941e..c306c7ec 100644 --- a/pages/validators/upgrade.mdx +++ b/pages/validators/upgrade.mdx @@ -11,6 +11,20 @@ import { Callout } from "nextra-theme-docs"; A fully Zero-downtime upgrade procedure is coming in a future update. +## v0.3.x → v0.4 (Breaking Change) + +`v0.4` switches to a new consensus deployment with staking. For this reason, the validator must be set up from scratch without reusing the old database stored at `data/node/genlayer.db`. +You do not need to keep your existing validator node running while you download and configure the new version. + +- Stop the node if it is running. +- Back up the `configs/node/config.yaml` file so that you can refer to any values you have set in the previous version. +- Back up the `data/node/keystore` folder so that you use your previous operator. +- Download the packaged binary. +- Install the new version. +- Remove the storage folder `data/node/genlayer.db`. +- Check that configuration is correct by running `genlayernode doctor` command. +- Start the node. + ## Configuration Change `v0.3.8` introduces updated consensus contract deployment with new contract addresses. **Critical**: Some consensus contract addresses have changed, and validators must update their consensus configuration to continue participating in the network. From 3588514cca3fcb072eec98c7f15bf6c084d42530 Mon Sep 17 00:00:00 2001 From: Darien Hernandez Date: Wed, 3 Dec 2025 17:11:45 +0100 Subject: [PATCH 03/21] docs: Update configuration for GenLayer Chain and improve comments --- content/validators/config.yaml | 44 ++++++++++++++++------------------ 1 file changed, 20 insertions(+), 24 deletions(-) diff --git a/content/validators/config.yaml b/content/validators/config.yaml index 52196575..90e46100 100644 --- a/content/validators/config.yaml +++ b/content/validators/config.yaml @@ -1,19 +1,12 @@ # rollup configuration 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 + genlayerchainrpcurl: "https://asimov-chain-1.genlayerlabs.com/rpc" # GenLayer Chain RPC URL + genlayerchainwebsocketurl: "wss://asimov-chain-1.genlayerlabs.com/ws" # GenLayer Chain WebSocket URL # consensus contracts configuration consensus: - # Required addresses - these must be configured - contractmainaddress: "0xe30293d600fF9B2C865d91307826F28006A458f4" # ConsensusMain Smart Contract Address (REQUIRED) - contractdataaddress: "0x2a50afD9d3E0ACC824aC4850d7B4c5561aB5D27a" # ConsensusData Smart Contract Address (REQUIRED) - - # DEPRECATED: The following addresses are auto-discovered from ConsensusMain.GetContracts() - # These fields will be removed in v0.4.0. If present, values are IGNORED and a deprecation warning is logged. - # contractmanageraddress: "0x0761ff3847294eb3234f37Bf63fd7F1CA1E840bB" # DEPRECATED - Auto-discovered from ConsensusMain - # contractidlenessaddress: "0xD1D09c2743DD26d718367Ba249Ee1629BE88CF33" # DEPRECATED - Auto-discovered from ConsensusMain - # contractstakingaddress: "0x31Cb4018ccB7d4F30419d367b6C5c7677AAE30E7" # DEPRECATED - Auto-discovered from ConsensusMain - + # Asimov - Phase 4 + contractmainaddress: "0xe30293d600fF9B2C865d91307826F28006A458f4" # ConsensusMain Smart Contract Address + contractdataaddress: "0x2a50afD9d3E0ACC824aC4850d7B4c5561aB5D27a" # ConsensusData Smart Contract Address genesis: 817855 # (Optional) Genesis block number for this consensus deployment. If not provided, it will be auto-detected by searching for the first log from the ConsensusMain contract. # data directory @@ -44,12 +37,16 @@ logging: # node configuration node: - # Uncomment if the ID of the node is different from the consensus validator address. + # Uncomment if the ID of the node is different from the validator wallet address. # It is used to identify the node in the network. # id: "node" - # Mode can be "validator" or "archive". + # Mode can be "validator" or "full". # Default value is "validator". mode: "validator" + # Address of the ValidatorWallet contract (required for validator mode) + validatorWalletAddress: "" + # Address of the operator that owns the ValidatorWallet + operatorAddress: "" admin: port: 9155 rpc: @@ -72,22 +69,21 @@ node: eth_blockNumber: true eth_getBlockByNumber: true eth_getBlockByHash: true - eth_getBalance: true - eth_getTransactionCount: true - eth_getTransactionReceipt: true - eth_getLogs: true - eth_getCode: true - eth_sendRawTransaction: false - debug_icStateDump: false + eth_sendRawTransaction: true + zks_getTransaction: true ops: port: 9153 # Metrics port endpoints: metrics: true # Enable metrics endpoint health: true # Enable health endpoint balance: true # Enable balance endpoint + +# genvm configuration genvm: - bin_dir: ./third_party/genvm/bin - manage_modules: true # if true node will start genvm modules itself + root_dir: ./third_party/genvm + start_manager: true # if true node will start genvm manager itself + manager_url: http://127.0.0.1:3999 + permits: # Leave empty for autodiscovery, put a number for updating genvm permits on startup # Advanced configuration merkleforest: @@ -100,7 +96,7 @@ merkletree: # metrics configuration metrics: - interval: "15s" # Default interval for all collectors (can be overridden per collector) + interval: "15s" # Default interval for all collectors (can be overridden per collector) # collectors: # node: # enabled: true From 2f5e82feb19eebe1eda5771dee6a60374a1bc14b Mon Sep 17 00:00:00 2001 From: Darien Hernandez Date: Wed, 3 Dec 2025 18:57:42 +0100 Subject: [PATCH 04/21] docs: Update setup guide to include Docker networking configuration for genvm-module-web --- pages/validators/setup-guide.mdx | 31 ++++++++++++++++++++++++++----- 1 file changed, 26 insertions(+), 5 deletions(-) diff --git a/pages/validators/setup-guide.mdx b/pages/validators/setup-guide.mdx index 0525db99..53e5f11b 100644 --- a/pages/validators/setup-guide.mdx +++ b/pages/validators/setup-guide.mdx @@ -803,7 +803,28 @@ services: ``` -2. Set the required environment variables in a `.env` file: +2. Create `genvm-module-web-docker.yaml` for Docker networking: + +The extracted tarball includes `third_party/genvm/config/genvm-module-web.yaml` configured for `localhost`, which works when running +the binary directly. For docker-compose, you need a version that points to the webdriver service name. + +Create `genvm-module-web-docker.yaml` in the same directory as your `docker-compose.yaml`: + +- Copy the contents of `third_party/genvm/config/genvm-module-web.yaml` into `genvm-module-web-docker.yaml`. +- Modify the `webdriver_host` configuration to use the service name `webdriver-container` instead of `localhost`: + +```yaml +webdriver_host: http://webdriver-container:4444 +``` + +This allows the node container to reach the webdriver container using Docker's internal networking. + +The key difference: +- **Binary execution**: uses `localhost:4444` (webdriver runs on same machine) +- **Docker-compose**: uses `webdriver-container:4444` (container service name) + + +3. Set the required environment variables in a `.env` file: ```env # GenLayer Node Release Configuration @@ -840,9 +861,9 @@ GEMINIKEY= ATOMAKEY= ``` -or simply use the provided `docker-compose.yaml` and the `.env.example` from the downloaded application packaged. +or simply use the provided `docker-compose.yaml`, `.env.example` and the `genvm-module-web-docker.yaml` from the extracted tarball. -3. Checking Your Configuration +4. Checking Your Configuration To ensure your node is correctly configured, you can run the following command: @@ -853,7 +874,7 @@ source .env && docker run --rm --env-file ./.env \ ./bin/genlayernode doctor ``` -4. Start the services using Docker Compose: +5. Start the services using Docker Compose: ```sh source .env && docker compose --profile node up -d @@ -936,4 +957,4 @@ curl -s http://localhost:9153/metrics | grep genlayer_node_ ### Logs and metrics forwarding -You can forward your logs and metrics to external systems for centralized monitoring and alerting by using the service `alloy` provided in the `docker-compose.yaml` from the downloaded application packaged. +You can forward your logs and metrics to external systems for centralized monitoring and alerting by using the service `alloy` provided in the `docker-compose.yaml` from the extracted tarball. From 304484d8044c7f393fa2366f52711e215040219f Mon Sep 17 00:00:00 2001 From: Darien Hernandez Date: Wed, 3 Dec 2025 19:00:52 +0100 Subject: [PATCH 05/21] docs: Update Node version in setup guide to v0.4.0 --- pages/validators/setup-guide.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/validators/setup-guide.mdx b/pages/validators/setup-guide.mdx index 53e5f11b..33ad22ff 100644 --- a/pages/validators/setup-guide.mdx +++ b/pages/validators/setup-guide.mdx @@ -838,7 +838,7 @@ WEBDRIVER_PORT=4444 # Node Service Configuration (optional - use node profile) # ============================================================================= # Docker image version -NODE_VERSION=latest +NODE_VERSION=v0.4.0 # Keystore password (used to unlock the pre-imported wallet) NODE_PASSWORD=12345678 From bd89b629ca5b0d2dd35d2344389a8acc7c85ac87 Mon Sep 17 00:00:00 2001 From: Darien Hernandez Date: Wed, 3 Dec 2025 19:08:08 +0100 Subject: [PATCH 06/21] docs: Update Docker image version to v0.4.0 in setup guide --- pages/validators/setup-guide.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/validators/setup-guide.mdx b/pages/validators/setup-guide.mdx index 33ad22ff..c97557c6 100644 --- a/pages/validators/setup-guide.mdx +++ b/pages/validators/setup-guide.mdx @@ -772,7 +772,7 @@ services: restart: unless-stopped genlayer-node: - image: yeagerai/genlayer-node:${NODE_VERSION:-latest} + image: yeagerai/genlayer-node:${NODE_VERSION:-v0.4.0} entrypoint: [ "sh", "-c", "/app/bin/genlayernode run --password ${NODE_PASSWORD:-12345678}", ] @@ -870,7 +870,7 @@ To ensure your node is correctly configured, you can run the following command: ```sh source .env && docker run --rm --env-file ./.env \ -v ${NODE_CONFIG_PATH:-./configs/node/config.yaml}:/app/configs/node/config.yaml \ - yeagerai/genlayer-node:${NODE_VERSION:-latest} \ + yeagerai/genlayer-node:${NODE_VERSION:-v0.4.0} \ ./bin/genlayernode doctor ``` From ca183b5321d87c35c40c865a57de56729876ba4e Mon Sep 17 00:00:00 2001 From: Darien Hernandez Date: Wed, 3 Dec 2025 19:20:33 +0100 Subject: [PATCH 07/21] docs: Update GenLayer Chain RPC and WebSocket URLs to placeholders in configuration --- content/validators/config.yaml | 4 ++-- pages/validators/setup-guide.mdx | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/content/validators/config.yaml b/content/validators/config.yaml index 90e46100..b2beeafc 100644 --- a/content/validators/config.yaml +++ b/content/validators/config.yaml @@ -1,7 +1,7 @@ # rollup configuration rollup: - genlayerchainrpcurl: "https://asimov-chain-1.genlayerlabs.com/rpc" # GenLayer Chain RPC URL - genlayerchainwebsocketurl: "wss://asimov-chain-1.genlayerlabs.com/ws" # GenLayer Chain WebSocket URL + genlayerchainrpcurl: "TODO: Set your GenLayer Chain ZKSync HTTP RPC URL here" # GenLayer Chain RPC URL + genlayerchainwebsocketurl: "TODO: Set your GenLayer Chain ZKSync HTTP RPC URL here" # GenLayer Chain WebSocket URL # consensus contracts configuration consensus: # Asimov - Phase 4 diff --git a/pages/validators/setup-guide.mdx b/pages/validators/setup-guide.mdx index c97557c6..e697917f 100644 --- a/pages/validators/setup-guide.mdx +++ b/pages/validators/setup-guide.mdx @@ -144,8 +144,8 @@ You can use the following example configuration. **Note:** For most users, you w ```yaml # rollup configuration rollup: - genlayerchainrpcurl: "https://asimov-chain-1.genlayerlabs.com/rpc" # GenLayer Chain RPC URL - genlayerchainwebsocketurl: "wss://asimov-chain-1.genlayerlabs.com/ws" # GenLayer Chain WebSocket URL + genlayerchainrpcurl: "TODO: Set your GenLayer Chain ZKSync HTTP RPC URL here" # GenLayer Chain RPC URL + genlayerchainwebsocketurl: "TODO: Set your GenLayer Chain ZKSync HTTP RPC URL here" # GenLayer Chain WebSocket URL # consensus contracts configuration consensus: # Asimov - Phase 4 From d22a41de6c7504d4e2f75eddbf8951edbd8a1de4 Mon Sep 17 00:00:00 2001 From: Darien Hernandez Date: Wed, 3 Dec 2025 19:24:49 +0100 Subject: [PATCH 08/21] docs: Update changelog and version documentation to reflect integration of GenLayer Consensus v0.4 with Staking --- content/validators/changelog/v0.4.0.mdx | 2 +- pages/validators/changelog.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/validators/changelog/v0.4.0.mdx b/content/validators/changelog/v0.4.0.mdx index 4e9de176..3e90e03d 100644 --- a/content/validators/changelog/v0.4.0.mdx +++ b/content/validators/changelog/v0.4.0.mdx @@ -2,7 +2,7 @@ ### New features -- Migrate to new consensus staking +- Integrate the latest GenLayer Consensus version v0.4 with Staking - Handle validator priming - Finalize epochs - Advance epochs when epochs finalize diff --git a/pages/validators/changelog.mdx b/pages/validators/changelog.mdx index 3ccde325..5ff96658 100644 --- a/pages/validators/changelog.mdx +++ b/pages/validators/changelog.mdx @@ -4,7 +4,7 @@ ### New features -- Migrate to new consensus staking +- Integrate the latest GenLayer Consensus version v0.4 with Staking - Handle validator priming - Finalize epochs - Advance epochs when epochs finalize From 963b7fe5f6dca131de5f617bff77eda39b964210 Mon Sep 17 00:00:00 2001 From: Darien Hernandez Date: Wed, 3 Dec 2025 19:26:37 +0100 Subject: [PATCH 09/21] docs: Clarify backup instructions for operator key in upgrade guide --- pages/validators/upgrade.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/validators/upgrade.mdx b/pages/validators/upgrade.mdx index c306c7ec..8faf683b 100644 --- a/pages/validators/upgrade.mdx +++ b/pages/validators/upgrade.mdx @@ -18,7 +18,7 @@ You do not need to keep your existing validator node running while you download - Stop the node if it is running. - Back up the `configs/node/config.yaml` file so that you can refer to any values you have set in the previous version. -- Back up the `data/node/keystore` folder so that you use your previous operator. +- Back up the `data/node/keystore` folder so that you can maintain your previous operator key. - Download the packaged binary. - Install the new version. - Remove the storage folder `data/node/genlayer.db`. From 9b6bd2e75e56445c30aed28a8d6622c24a9074be Mon Sep 17 00:00:00 2001 From: Darien Hernandez Date: Wed, 3 Dec 2025 19:55:17 +0100 Subject: [PATCH 10/21] docs: Update consensus contract addresses and genesis block number in configuration --- content/validators/config.yaml | 6 +++--- pages/validators/setup-guide.mdx | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/content/validators/config.yaml b/content/validators/config.yaml index b2beeafc..86292853 100644 --- a/content/validators/config.yaml +++ b/content/validators/config.yaml @@ -5,9 +5,9 @@ rollup: # consensus contracts configuration consensus: # Asimov - Phase 4 - contractmainaddress: "0xe30293d600fF9B2C865d91307826F28006A458f4" # ConsensusMain Smart Contract Address - contractdataaddress: "0x2a50afD9d3E0ACC824aC4850d7B4c5561aB5D27a" # ConsensusData Smart Contract Address - genesis: 817855 # (Optional) Genesis block number for this consensus deployment. If not provided, it will be auto-detected by searching for the first log from the ConsensusMain contract. + contractmainaddress: "0x67fd4aC71530FB220E0B7F90668BAF977B88fF07" # ConsensusMain Smart Contract Address + contractdataaddress: "0xB6E1316E57d47d82FDcEa5002028a554754EF243" # ConsensusData Smart Contract Address + genesis: 4632386 # (Optional) Genesis block number for this consensus deployment. If not provided, it will be auto-detected by searching for the first log from the ConsensusMain contract. # data directory datadir: "./data/node" diff --git a/pages/validators/setup-guide.mdx b/pages/validators/setup-guide.mdx index e697917f..ee5226be 100644 --- a/pages/validators/setup-guide.mdx +++ b/pages/validators/setup-guide.mdx @@ -149,9 +149,9 @@ rollup: # consensus contracts configuration consensus: # Asimov - Phase 4 - contractmainaddress: "0xe30293d600fF9B2C865d91307826F28006A458f4" # ConsensusMain Smart Contract Address - contractdataaddress: "0x2a50afD9d3E0ACC824aC4850d7B4c5561aB5D27a" # ConsensusData Smart Contract Address - genesis: 817855 # (Optional) Genesis block number for this consensus deployment. If not provided, it will be auto-detected by searching for the first log from the ConsensusMain contract. + contractmainaddress: "0x67fd4aC71530FB220E0B7F90668BAF977B88fF07" # ConsensusMain Smart Contract Address + contractdataaddress: "0xB6E1316E57d47d82FDcEa5002028a554754EF243" # ConsensusData Smart Contract Address + genesis: 4632386 # (Optional) Genesis block number for this consensus deployment. If not provided, it will be auto-detected by searching for the first log from the ConsensusMain contract. # data directory datadir: "./data/node" From 2adf003899712c48c8f11e3f93d8738c73b8e351 Mon Sep 17 00:00:00 2001 From: Darien Hernandez Date: Thu, 4 Dec 2025 09:28:23 +0100 Subject: [PATCH 11/21] docs: Update changelog and v0.4.0 documentation to include validator wallet feature --- content/validators/changelog/v0.4.0.mdx | 8 ++++---- pages/validators/changelog.mdx | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/content/validators/changelog/v0.4.0.mdx b/content/validators/changelog/v0.4.0.mdx index 3e90e03d..98af64b6 100644 --- a/content/validators/changelog/v0.4.0.mdx +++ b/content/validators/changelog/v0.4.0.mdx @@ -3,9 +3,10 @@ ### New features - Integrate the latest GenLayer Consensus version v0.4 with Staking -- Handle validator priming -- Finalize epochs -- Advance epochs when epochs finalize + - Introduce validator wallet + - Handle validator priming + - Finalize epochs + - Advance epochs when epochs finalize - Handle automatic gas increase - Implement ProcessIdleness and enhance event subscription - Handle validator commit idleness for leader @@ -48,7 +49,6 @@ - Cancel context and wait for group when genvm tester fails - Decoding calldata into complex types - Don't try activating already activated transactions -- Starting node - Still process sync failed TX for DB consistency - Add correct encoding for getState - Only sync transactions with ResultCodeReturn and add sanity check diff --git a/pages/validators/changelog.mdx b/pages/validators/changelog.mdx index 5ff96658..565751b0 100644 --- a/pages/validators/changelog.mdx +++ b/pages/validators/changelog.mdx @@ -5,9 +5,10 @@ ### New features - Integrate the latest GenLayer Consensus version v0.4 with Staking -- Handle validator priming -- Finalize epochs -- Advance epochs when epochs finalize + - Introduce validator wallet + - Handle validator priming + - Finalize epochs + - Advance epochs when epochs finalize - Handle automatic gas increase - Implement ProcessIdleness and enhance event subscription - Handle validator commit idleness for leader @@ -50,7 +51,6 @@ - Cancel context and wait for group when genvm tester fails - Decoding calldata into complex types - Don't try activating already activated transactions -- Starting node - Still process sync failed TX for DB consistency - Add correct encoding for getState - Only sync transactions with ResultCodeReturn and add sanity check From 8e4d1abe42268a9e36afc07c40804ec503eda05a Mon Sep 17 00:00:00 2001 From: Darien Hernandez Date: Thu, 4 Dec 2025 10:43:59 +0100 Subject: [PATCH 12/21] docs: Update RPC URL placeholders in configuration and setup guide for clarity --- content/validators/config.yaml | 4 ++-- pages/validators/setup-guide.mdx | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/content/validators/config.yaml b/content/validators/config.yaml index 86292853..5724ac89 100644 --- a/content/validators/config.yaml +++ b/content/validators/config.yaml @@ -1,7 +1,7 @@ # rollup configuration rollup: - genlayerchainrpcurl: "TODO: Set your GenLayer Chain ZKSync HTTP RPC URL here" # GenLayer Chain RPC URL - genlayerchainwebsocketurl: "TODO: Set your GenLayer Chain ZKSync HTTP RPC URL here" # GenLayer Chain WebSocket URL + genlayerchainrpcurl: "TODO: Set your GenLayer Chain ZKSync HTTP RPC URL here" # ZKSync RPC URL + genlayerchainwebsocketurl: "TODO: Set your GenLayer Chain ZKSync WebSocket RPC URL here" # ZKSync WebSocket URL # consensus contracts configuration consensus: # Asimov - Phase 4 diff --git a/pages/validators/setup-guide.mdx b/pages/validators/setup-guide.mdx index ee5226be..05f80324 100644 --- a/pages/validators/setup-guide.mdx +++ b/pages/validators/setup-guide.mdx @@ -144,8 +144,8 @@ You can use the following example configuration. **Note:** For most users, you w ```yaml # rollup configuration rollup: - genlayerchainrpcurl: "TODO: Set your GenLayer Chain ZKSync HTTP RPC URL here" # GenLayer Chain RPC URL - genlayerchainwebsocketurl: "TODO: Set your GenLayer Chain ZKSync HTTP RPC URL here" # GenLayer Chain WebSocket URL + genlayerchainrpcurl: "TODO: Set your GenLayer Chain ZKSync HTTP RPC URL here" # ZKSync RPC URL + genlayerchainwebsocketurl: "TODO: Set your GenLayer Chain ZKSync WebSocket RPC URL here" # ZKSync WebSocket URL # consensus contracts configuration consensus: # Asimov - Phase 4 From 237fea7c6a211d5efee7dee84348aec9123067be Mon Sep 17 00:00:00 2001 From: Darien Hernandez Date: Thu, 4 Dec 2025 13:17:43 +0100 Subject: [PATCH 13/21] docs: Add section on overriding configuration with environment variables in setup guide --- pages/validators/setup-guide.mdx | 68 +++++++++++++++++++++++--------- 1 file changed, 50 insertions(+), 18 deletions(-) diff --git a/pages/validators/setup-guide.mdx b/pages/validators/setup-guide.mdx index 05f80324..b50d1501 100644 --- a/pages/validators/setup-guide.mdx +++ b/pages/validators/setup-guide.mdx @@ -257,6 +257,46 @@ metrics: ``` +### Overriding Configuration with Environment Variables + +Any configuration value in `config.yaml` can be overridden using environment variables with the prefix `GENLAYERNODE_`. + +**Pattern:** + +- Replace dots (`.`) with underscores (`_`) +- Convert to uppercase +- Add the `GENLAYERNODE_` prefix + +**Examples:** + +| Config Key | Environment Variable | +|------------|---------------------| +| `rollup.genlayerchainrpcurl` | `GENLAYERNODE_ROLLUP_GENLAYERCHAINRPCURL` | +| `rollup.genlayerchainwebsocketurl` | `GENLAYERNODE_ROLLUP_GENLAYERCHAINWEBSOCKETURL` | +| `consensus.contractmainaddress` | `GENLAYERNODE_CONSENSUS_CONTRACTMAINADDRESS` | +| `consensus.contractdataaddress` | `GENLAYERNODE_CONSENSUS_CONTRACTDATAADDRESS` | +| `consensus.genesis` | `GENLAYERNODE_CONSENSUS_GENESIS` | +| `node.mode` | `GENLAYERNODE_NODE_MODE` | +| `node.validatorWalletAddress` | `GENLAYERNODE_NODE_VALIDATORWALLETADDRESS` | +| `node.operatorAddress` | `GENLAYERNODE_NODE_OPERATORADDRESS` | +| `node.rpc.port` | `GENLAYERNODE_NODE_RPC_PORT` | +| `logging.level` | `GENLAYERNODE_LOGGING_LEVEL` | + +**Usage example:** + +```sh +# Override the RPC port +export GENLAYERNODE_CONSENSUS_CONTRACTMAINADDRESS="0x..." + +# Set validator wallet address +export GENLAYERNODE_NODE_VALIDATORWALLETADDRESS="0x..." + +# Set logging level +export GENLAYERNODE_LOGGING_LEVEL="DEBUG" +``` + +Environment variables take precedence over values in `config.yaml`, making them ideal for Docker deployments or sensitive values you don't want in configuration files. + ### 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. @@ -503,30 +543,18 @@ Options: - `--amount ` - Stake amount (e.g., `42000gen` or `42000`) - `--operator
` - Operator address (recommended, see below) -##### Why Use an Operator Address? +##### Why Use a dedicated Operator Address? -**Recommended:** Use a separate operator address for security. + **Recommended:** Use a separate operator address for security. -- **Validator wallet** - Holds your staked funds (keep offline/cold) -- **Operator wallet** - Signs blocks and performs validator duties (hot wallet on server) - -This way, if your operator server is compromised, your staked funds remain safe. - -```bash -# Create operator account on your validator server -genlayer account create --output ./operator.json - -# Get operator address -cat ./operator.json | jq -r .address -# 0xOperator123... +- **Owner address** - Holds your staked funds (keep offline/cold) +- **Operator address** - Signs blocks and performs validator duties (hot wallet on server) -# Join with separate operator (run from your main wallet) -genlayer staking validator-join --amount 42000gen --operator 0xOperator123... -``` +This way, if your operator server is compromised, your staked funds remain safe. This also enables delegating the validator operation to an external staking provider. -You can change the operator later: +You can change the operator at any time: ```bash genlayer staking set-operator --validator 0xYourValidator... --operator 0xNewOperator... @@ -826,6 +854,10 @@ The key difference: 3. Set the required environment variables in a `.env` file: + + This `.env` file serves two purposes: it configures Docker Compose variables (like `NODE_VERSION`, `NODE_PASSWORD`, ports) and can also include `GENLAYERNODE_*` variables to override node configuration values as described in [Overriding Configuration with Environment Variables](#overriding-configuration-with-environment-variables). + + ```env # GenLayer Node Release Configuration From 15544ebae992700a2d6b1d69883da97ca3f34667 Mon Sep 17 00:00:00 2001 From: Edgars Date: Thu, 4 Dec 2025 15:32:11 +0000 Subject: [PATCH 14/21] feat: use the new wizard --- pages/api-references/genlayer-cli.mdx | 188 ++++++++++++- pages/validators/setup-guide.mdx | 363 +++++++------------------- 2 files changed, 272 insertions(+), 279 deletions(-) diff --git a/pages/api-references/genlayer-cli.mdx b/pages/api-references/genlayer-cli.mdx index d1ffbd5d..b6bf17da 100644 --- a/pages/api-references/genlayer-cli.mdx +++ b/pages/api-references/genlayer-cli.mdx @@ -184,21 +184,191 @@ EXAMPLES: ### Network Management -Configure network settings. +Configure and view network settings. ```bash USAGE: - genlayer network [network] + genlayer network set [network] + genlayer network info + genlayer network list -ARGUMENTS: - [network] Optional network name or alias to set. If omitted, displays an interactive selection menu. - Valid options: localnet, studionet, testnet-asimov +COMMANDS: + set [network] Set the network (interactive menu if network not specified) + info Show current network configuration and contract addresses + list List all available networks + +EXAMPLES: + genlayer network set # Interactive selection menu + genlayer network set localnet # Set network to localnet + genlayer network set testnet-asimov # Set network to testnet-asimov + genlayer network info # Show current network details + genlayer network list # List available networks +``` + +### Account Management + +Create and manage accounts with encrypted keystores. + +```bash +USAGE: + genlayer account create [options] + genlayer account show [options] + genlayer account list + genlayer account use + genlayer account remove + genlayer account lock [options] + genlayer account unlock [options] + genlayer account export [options] + genlayer account import [options] + genlayer account send [options] + +COMMANDS: + create Create a new account with encrypted keystore + show Show account details and balance + list List all accounts + use Set an account as active + remove Remove an account + lock Lock an account (remove cached private key) + unlock Unlock an account (cache private key in OS keychain) + export Export account to standard web3 keystore format + import Import account from keystore file or private key + send Send GEN tokens to another address + +OPTIONS (create): + --name Account name (default: "default") + --overwrite Overwrite existing account + +OPTIONS (show): + --account Account to show (default: active account) + --rpc RPC URL for balance lookup + +OPTIONS (lock/unlock): + --account Account to lock/unlock + +OPTIONS (export): + --account Account to export + --output Output file path + --password Password for exported keystore + +OPTIONS (import): + --name Name for imported account + --keystore Path to keystore file + --private-key Private key to import (alternative to keystore) + +OPTIONS (send): + --to
Recipient address + --amount Amount to send (e.g., "1.5" or "1.5gen") + --account Account to send from EXAMPLES: - genlayer network # Interactive selection menu - genlayer network localnet # Set network to localnet - genlayer network studionet # Set network to studionet - genlayer network testnet-asimov # Set network to testnet-asimov + genlayer account create --name owner + genlayer account show + genlayer account show --account operator + genlayer account list + genlayer account use owner + genlayer account unlock --account owner + genlayer account export --account operator --output ./operator-keystore.json + genlayer account import --name backup --keystore ./backup.json + genlayer account send --to 0x123... --amount 100gen +``` + +### Staking Operations + +Staking operations for validators and delegators on testnet. + +```bash +USAGE: + genlayer staking wizard [options] + genlayer staking validator-join [options] + genlayer staking validator-deposit [options] + genlayer staking validator-exit [options] + genlayer staking validator-claim [options] + genlayer staking validator-info [options] + genlayer staking set-operator [options] + genlayer staking set-identity [options] + genlayer staking delegator-join [options] + genlayer staking delegator-exit [options] + genlayer staking delegator-claim [options] + genlayer staking epoch-info [options] + genlayer staking active-validators [options] + +COMMANDS: + wizard Interactive wizard to become a validator + validator-join Join as a validator by staking tokens + validator-deposit Make an additional deposit as a validator + validator-exit Exit as a validator by withdrawing shares + validator-claim Claim validator withdrawals after unbonding period + validator-info Get information about a validator + set-operator Change the operator address for a validator + set-identity Set validator identity metadata (moniker, website, socials) + delegator-join Join as a delegator by staking with a validator + delegator-exit Exit as a delegator by withdrawing shares + delegator-claim Claim delegator withdrawals after unbonding period + epoch-info Get current epoch and staking parameters + active-validators List all active validators + +OPTIONS (wizard): + --account Account to use (skip selection) + --network Network to use (skip selection) + --skip-identity Skip identity setup step + +OPTIONS (validator-join): + --amount Amount to stake (e.g., "42000gen") + --operator
Operator address (defaults to signer) + --account Account to use + +OPTIONS (validator-deposit): + --amount Amount to deposit + +OPTIONS (validator-exit): + --shares Number of shares to withdraw + +OPTIONS (set-operator): + --validator
Validator wallet address + --operator
New operator address + +OPTIONS (set-identity): + --validator
Validator wallet address + --moniker Validator display name (required) + --website Website URL + --description Description + --twitter Twitter handle + --github GitHub handle + +OPTIONS (delegator-join): + --validator
Validator to delegate to + --amount Amount to stake + +OPTIONS (delegator-exit): + --validator
Validator to exit from + --shares Number of shares to withdraw + +COMMON OPTIONS: + --network Network to use (localnet, testnet-asimov) + --rpc RPC URL for the network + --staking-address Override staking contract address + +EXAMPLES: + # Become a validator using the interactive wizard + genlayer staking wizard + + # Join as validator manually + genlayer staking validator-join --amount 42000gen --operator 0x123... + + # Check validator status + genlayer staking validator-info + + # Set validator identity + genlayer staking set-identity --validator 0x123... --moniker "My Validator" --website "https://example.com" + + # Delegate to a validator + genlayer staking delegator-join --validator 0x123... --amount 1000gen + + # Check epoch info + genlayer staking epoch-info + + # List active validators + genlayer staking active-validators ``` ### Keypair Management diff --git a/pages/validators/setup-guide.mdx b/pages/validators/setup-guide.mdx index b50d1501..a786c24e 100644 --- a/pages/validators/setup-guide.mdx +++ b/pages/validators/setup-guide.mdx @@ -187,9 +187,10 @@ node: # Mode can be "validator" or "full". # Default value is "validator". mode: "validator" - # Address of the ValidatorWallet contract (required for validator mode) + # Address of your ValidatorWallet contract (from wizard output or validator-info) + # Run: genlayer staking validator-info to find this validatorWalletAddress: "" - # Address of the operator that owns the ValidatorWallet + # Address of your operator key (the key imported into this node) operatorAddress: "" admin: port: 9155 @@ -357,21 +358,56 @@ Related scripts are located at: More features and built-in filters will be added soon -### Set Up The Validator Key +### Set Up The Operator Key -In this step we'll generate your validator key and address. +The operator key is used by your node to sign blocks and perform validator duties. This is separate from your owner account which holds your staked funds. - ```sh - ./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 - ``` + + **Owner vs Operator:** The owner account holds your stake and should be kept secure (cold wallet). The operator account runs on your validator server and signs blocks (hot wallet). If your server is compromised, your staked funds remain safe. + - You should see the following output: +#### Option 1: Import from CLI Wizard (Recommended) - ```sh - Account created: - New address: 0xA0b12Fd2f3F7e86fEC458D114A5E7a6f571160a8 - Account setup as a validator - ``` +If you used the `genlayer staking wizard` to become a validator, it exported an operator keystore file (e.g., `operator-keystore.json`). Transfer this file to your validator server and import it: + +```sh +./bin/genlayernode account import \ + --password "your node password" \ + --passphrase "password you set when exporting from wizard" \ + --path "/path/to/operator-keystore.json" \ + -c $(pwd)/configs/node/config.yaml \ + --setup +``` + +You should see: + +```sh +Account imported: + Address: 0xA0b12Fd2f3F7e86fEC458D114A5E7a6f571160a8 + Account setup as a validator +``` + +#### Option 2: Generate New Operator Key + +If you haven't set up your validator yet, you can generate a new operator key directly on the server: + +```sh +./bin/genlayernode account new -c $(pwd)/configs/node/config.yaml --setup --password "your secret password" +``` + +You should see: + +```sh +Account created: + New address: 0xA0b12Fd2f3F7e86fEC458D114A5E7a6f571160a8 + Account setup as a validator +``` + +Use this address as the `--operator` when joining as a validator via the CLI: + +```bash +genlayer staking validator-join --amount 42000gen --operator 0xA0b12Fd2f3F7e86fEC458D114A5E7a6f571160a8 +``` Currently the GenLayer Testnet is permissioned. You can apply to be selected @@ -379,36 +415,28 @@ In this step we'll generate your validator key and address. form](https://docs.google.com/forms/d/e/1FAIpQLSc7YujY6S6knB9XC8kL-2wsgNHrweqULstgc-OOMERlRsfg0A/viewform) -### Backing Up Your Validator Key - -After generating your validator key, it is critical to back it up securely. +### Backing Up Your Operator Key -You can export your key using the following command: +After setting up your operator key, back it up securely: ```sh ./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 + --password "your node password" \ + --address "your operator address" \ + --passphrase "your backup encryption passphrase" \ + --path "/path/to/your/secure/backup.key" \ + -c $(pwd)/configs/node/config.yaml ``` - **Important: Back up your validator key!** Losing access to this key means - losing control of your validator and any associated rewards. Store the backup - securely. Remember both the node password (used during setup) and the backup - encryption passphrase. + **Important: Back up your operator key!** Losing access means you'll need to set up a new operator and update your validator configuration. Store the backup securely. -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. +To print the private key from your backup file, use the `--print` flag. **Keep this private key secure and never share it.** -### Importing (Restoring) Your Validator Key +### Restoring Your Operator 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: +To restore from a backup (e.g., after migrating to a new server): ```sh ./bin/genlayernode account import \ @@ -419,21 +447,8 @@ If you need to restore your validator key from a backup (for example, after migr --setup ``` -You should see the following output: - -```sh - 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. - - Important: Always verify that your imported key works by checking your - validator address. + Always verify that your imported key works by checking the operator address matches what's configured for your validator. ### Validator Joining the Network @@ -446,271 +461,79 @@ This section walks you through becoming a validator on the GenLayer testnet usin - GenLayer CLI installed (`npm install -g genlayer`) - GEN tokens for staking (minimum stake required) -#### Step 1: Create an Account - -```bash -genlayer account create -``` - -You'll be prompted to set a password. This creates an encrypted keystore file. - -#### Step 2: View Your Account - -```bash -genlayer account -``` - -Output: - -``` -{ - address: '0x86D0d159483CBf01E920ECfF8bB7F0Cd7E964E7E', - balance: '0 GEN', - network: 'localnet', - status: 'locked' -} -``` - -#### Step 3: Set Network to Testnet +#### Using the Validator Wizard -```bash -genlayer network testnet-asimov -``` - -Verify with: +The easiest way to become a validator is using the interactive wizard: ```bash -genlayer account +genlayer staking wizard ``` -You should see `network: 'Asimov Testnet'`. - -#### Step 4: Fund Your Account +The wizard guides you through all required steps: -Transfer GEN tokens to your address. You can: - -- Use the faucet (if available) -- Transfer from another account: - -```bash -genlayer account send 50000gen -``` - -#### Step 5: Check Staking Requirements - -```bash -genlayer staking epoch-info -``` - -Output: - -``` -{ - currentEpoch: '2', - epochStarted: '2025-01-15T00:00:00.000Z', - nextEpochEstimate: '2025-01-16T00:00:00.000Z', - timeUntilNextEpoch: '12h 30m', - minEpochDuration: '24h 0m', - validatorMinStake: '42000 GEN', - delegatorMinStake: '42 GEN', - activeValidatorsCount: '6', - epochInflation: '1000 GEN', - totalWeight: '500000000000000000000000', - totalClaimed: '500 GEN' -} -``` +1. **Account setup** - Create a new account or select existing +2. **Network selection** - Choose testnet-asimov +3. **Balance verification** - Confirms you have enough GEN +4. **Operator setup** - Configure a separate operator address (recommended for security) +5. **Stake amount** - Enter how much GEN to stake +6. **Validator creation** - Submits the staking transaction +7. **Identity setup** - Set your validator's public profile (moniker, website, etc.) -Note the `validatorMinStake` - you need at least this amount. - -#### Step 6: Unlock Your Account (Optional) - -For convenience, unlock your account to avoid entering password repeatedly: - -```bash -genlayer account unlock -``` - -This caches your private key in the OS keychain. - -#### Step 7: Join as Validator - -```bash -genlayer staking validator-join --amount 42000gen --operator 0xOperator... -``` - -Options: - -- `--amount ` - Stake amount (e.g., `42000gen` or `42000`) -- `--operator
` - Operator address (recommended, see below) - -##### Why Use a dedicated Operator Address? +##### Why Use a Separate Operator Address? **Recommended:** Use a separate operator address for security. -- **Owner address** - Holds your staked funds (keep offline/cold) -- **Operator address** - Signs blocks and performs validator duties (hot wallet on server) - -This way, if your operator server is compromised, your staked funds remain safe. This also enables delegating the validator operation to an external staking provider. - -You can change the operator at any time: - -```bash -genlayer staking set-operator --validator 0xYourValidator... --operator 0xNewOperator... -``` - -#### Step 8: Verify Your Validator Status - -```bash -genlayer staking validator-info -``` - -Output: - -``` -{ - validator: '0x86D0d159483CBf01E920ECfF8bB7F0Cd7E964E7E', - vStake: '42000 GEN', - vShares: '42000000000000000000000', - live: true, - banned: 'Not banned', - ... -} -``` - -#### Step 9: Set Validator Identity (Metadata) - -Set your validator's public identity so delegators can find you: - -```bash -genlayer staking set-identity \ - --validator 0x86D0...7E \ - --moniker "My Validator" \ - --website "https://myvalidator.com" \ - --description "Reliable validator with 99.9% uptime" \ - --twitter "myvalidator" \ - --github "myvalidator" -``` - -**Required:** - -- `--validator
` - Your validator address -- `--moniker ` - Display name for your validator +- **Owner account** - Holds your staked funds (keep offline/cold) +- **Operator account** - Signs blocks and performs validator duties (hot wallet on server) -**Optional:** +This way, if your operator server is compromised, your staked funds remain safe. The wizard can create and export an operator keystore file for you to transfer to your validator server. -- `--logo-uri ` - Logo image URL -- `--website ` - Website URL -- `--description ` - Description of your validator -- `--email ` - Contact email -- `--twitter ` - Twitter handle -- `--telegram ` - Telegram handle -- `--github ` - GitHub handle -- `--extra-cid ` - Additional data as IPFS CID +#### Verify Your Validator -Your identity will show in `validator-info`: +After completing the wizard, verify your status: ```bash genlayer staking validator-info ``` -Output will include: - -``` -{ - ... - identity: { - moniker: 'My Validator', - website: 'https://myvalidator.com', - twitter: 'myvalidator', - github: 'myvalidator' - } -} -``` - #### Managing Your Validator -##### Add More Stake - ```bash +# Add more stake genlayer staking validator-deposit --amount 1000gen -``` - -##### Check Active Validators -```bash +# Check active validators genlayer staking active-validators -``` -##### Exit as Validator - -```bash +# Exit (initiates 7-epoch unbonding) genlayer staking validator-exit --shares 100 -``` - -This initiates a withdrawal. Your tokens enter an **unbonding period of 7 epochs** before they can be claimed. - -Check your pending withdrawals with `validator-info`: - -``` -selfStakePendingWithdrawals: [ - { - epoch: '5', - shares: '100', - stake: '100 GEN', - claimableAtEpoch: '12', - status: 'Unbonding (4 epochs remaining)' - } -] -``` -##### Claim Withdrawals - -After the 7-epoch unbonding period: - -```bash +# Claim after unbonding period genlayer staking validator-claim -``` - -#### Troubleshooting - -##### "No account found" - -Run `genlayer account create` first. - -##### "Insufficient balance" - -Ensure you have enough GEN. Check with `genlayer account`. -##### "Below minimum stake" +# Change operator address +genlayer staking set-operator --validator 0x... --operator 0xNew... -Check minimum with `genlayer staking epoch-info` and increase your stake amount. - -##### Transaction Stuck - -Check the transaction status: - -```bash -genlayer receipt +# Update identity +genlayer staking set-identity --validator 0x... --moniker "New Name" ``` -#### Lock Your Account +#### Manual Setup -When done, lock your account to remove the cached private key: - -```bash -genlayer account lock -``` +For step-by-step manual setup instructions, see the [full validator guide](https://github.com/yeagerai/genlayer-cli/blob/main/docs/validator-guide.md) in the CLI repository ## Running the node Once you have configured everything, you are ready to start the node. - **Important: Before starting the node, ensure you have the operator address and validator wallet address - set up. If you do not have setup the validator wallet address, your node will not be able to validate, - therefore it will act as a full node instead. + **Important:** Before starting the node, ensure you have: + 1. **Operator key** imported into the node (see "Set Up The Operator Key" above) + 2. **Validator wallet address** - obtained after joining as validator via `genlayer staking wizard` or `validator-join` + + Without both configured, your node will run as a full node instead of a validator. ### Running the Node using the binary From 0e7b5ca618fa3c58c78d124648bd6c75c22c9b32 Mon Sep 17 00:00:00 2001 From: Edgars Date: Thu, 4 Dec 2025 16:09:28 +0000 Subject: [PATCH 15/21] fix: improve order and clarity --- pages/validators/setup-guide.mdx | 203 +++++++++++++++---------------- 1 file changed, 97 insertions(+), 106 deletions(-) diff --git a/pages/validators/setup-guide.mdx b/pages/validators/setup-guide.mdx index a786c24e..8073b6e9 100644 --- a/pages/validators/setup-guide.mdx +++ b/pages/validators/setup-guide.mdx @@ -4,6 +4,88 @@ import { Callout } from "nextra-theme-docs"; Running a GenLayer Validator node ensures the security and reliability of the GenLayer network. Below are the requirements for running a GenLayer validator. +## Create the Validator Wallet + +Before setting up your validator node, you need to create your validator wallet and stake GEN tokens. + +### Understanding Validator Addresses + + +GenLayer validators use three distinct addresses: + +| Address | Description | Where Used | +|---------|-------------|------------| +| **Owner** | Your main account that holds staked funds. Keep this secure (cold wallet). | CLI wizard - signs staking transaction | +| **Operator** | Hot wallet on your server that signs blocks. Can be same as owner, but separate is recommended. | Node config: `operatorAddress` | +| **Validator Wallet** | Smart contract created when you join. This is your validator's on-chain identity. | Node config: `validatorWalletAddress` | + +The wizard outputs all three addresses at the end. Save them - you'll need the Validator Wallet and Operator addresses for your node configuration. + + +### Prerequisites + +- **Node.js** (v18 or higher) +- **GenLayer CLI** - Install the latest version: + ```bash + npm install -g genlayer + ``` +- **GEN tokens** - You need at least **42,000 GEN** for the minimum self-stake requirement + +### Using the Validator Wizard + +The easiest way to create your validator wallet is using the interactive wizard: + +```bash +genlayer staking wizard +``` + +The wizard guides you through: + +1. **Account setup** - Create or select your owner account +2. **Network selection** - Choose testnet-asimov +3. **Balance verification** - Confirms you have at least 42,000 GEN +4. **Operator setup** - Create and export an operator keystore for your validator server +5. **Stake amount** - Enter how much GEN to stake (minimum 42,000) +6. **Validator creation** - Submits the staking transaction +7. **Identity setup** - Set your validator's public profile (moniker, website, etc.) + + + **Save Your Validator Wallet Address!** After the wizard completes, note down your **Validator Wallet** address. You'll need this for your node configuration. + + +#### Operator Keystore Export + +The wizard creates and exports an operator keystore file for you to transfer to your validator server. If your server is compromised, your staked funds (controlled by owner) remain safe. + +### Verify Your Validator + +After completing the wizard, verify your status: + +```bash +genlayer staking validator-info --validator 0xYourValidatorWallet... +``` + +### Managing Your Validator + +```bash +# Add more stake +genlayer staking validator-deposit --amount 1000gen + +# Check active validators +genlayer staking active-validators + +# Exit (initiates 7-epoch unbonding) +genlayer staking validator-exit --shares 100 + +# Claim after unbonding period +genlayer staking validator-claim + +# Update identity +genlayer staking set-identity --validator 0x... --moniker "New Name" +``` + +--- + ## Dependencies ### LLM Access @@ -332,11 +414,15 @@ This is the configuration of webdriver module that enables the GenVM to access t 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) - ```bash - ./third_party/genvm/bin/genvm precompile - ``` - Precompilation should be re-run after switching to a different node release +#### Precompilation (Recommended) + +Run precompilation of pre-delivered wasm modules (this step is optional but **highly** recommended for improved performance): + +```bash +./third_party/genvm/bin/genvm precompile +``` + +Precompilation should be re-run after switching to a different node release. #### Greyboxing LLMs @@ -358,17 +444,13 @@ Related scripts are located at: More features and built-in filters will be added soon -### Set Up The Operator Key +### Import the Operator Key -The operator key is used by your node to sign blocks and perform validator duties. This is separate from your owner account which holds your staked funds. - - - **Owner vs Operator:** The owner account holds your stake and should be kept secure (cold wallet). The operator account runs on your validator server and signs blocks (hot wallet). If your server is compromised, your staked funds remain safe. - +The operator key is used by your node to sign blocks and perform validator duties. #### Option 1: Import from CLI Wizard (Recommended) -If you used the `genlayer staking wizard` to become a validator, it exported an operator keystore file (e.g., `operator-keystore.json`). Transfer this file to your validator server and import it: +If you used `genlayer staking wizard`, it exported an operator keystore file. Transfer this file to your validator server and import it: ```sh ./bin/genlayernode account import \ @@ -389,31 +471,13 @@ Account imported: #### Option 2: Generate New Operator Key -If you haven't set up your validator yet, you can generate a new operator key directly on the server: +You can also generate a new operator key directly on the server: ```sh ./bin/genlayernode account new -c $(pwd)/configs/node/config.yaml --setup --password "your secret password" ``` -You should see: - -```sh -Account created: - New address: 0xA0b12Fd2f3F7e86fEC458D114A5E7a6f571160a8 - Account setup as a validator -``` - -Use this address as the `--operator` when joining as a validator via the CLI: - -```bash -genlayer staking validator-join --amount 42000gen --operator 0xA0b12Fd2f3F7e86fEC458D114A5E7a6f571160a8 -``` - - - Currently the GenLayer Testnet is permissioned. You can apply to be selected - [by filling out the following - form](https://docs.google.com/forms/d/e/1FAIpQLSc7YujY6S6knB9XC8kL-2wsgNHrweqULstgc-OOMERlRsfg0A/viewform) - +Then use this address when running the wizard on your local machine. ### Backing Up Your Operator Key @@ -451,86 +515,13 @@ To restore from a backup (e.g., after migrating to a new server): Always verify that your imported key works by checking the operator address matches what's configured for your validator. -### Validator Joining the Network - -This section walks you through becoming a validator on the GenLayer testnet using the CLI. - -#### Prerequisites - -- Node.js installed -- GenLayer CLI installed (`npm install -g genlayer`) -- GEN tokens for staking (minimum stake required) - -#### Using the Validator Wizard - -The easiest way to become a validator is using the interactive wizard: - -```bash -genlayer staking wizard -``` - -The wizard guides you through all required steps: - -1. **Account setup** - Create a new account or select existing -2. **Network selection** - Choose testnet-asimov -3. **Balance verification** - Confirms you have enough GEN -4. **Operator setup** - Configure a separate operator address (recommended for security) -5. **Stake amount** - Enter how much GEN to stake -6. **Validator creation** - Submits the staking transaction -7. **Identity setup** - Set your validator's public profile (moniker, website, etc.) - -##### Why Use a Separate Operator Address? - - - **Recommended:** Use a separate operator address for security. - - -- **Owner account** - Holds your staked funds (keep offline/cold) -- **Operator account** - Signs blocks and performs validator duties (hot wallet on server) - -This way, if your operator server is compromised, your staked funds remain safe. The wizard can create and export an operator keystore file for you to transfer to your validator server. - -#### Verify Your Validator - -After completing the wizard, verify your status: - -```bash -genlayer staking validator-info -``` - -#### Managing Your Validator - -```bash -# Add more stake -genlayer staking validator-deposit --amount 1000gen - -# Check active validators -genlayer staking active-validators - -# Exit (initiates 7-epoch unbonding) -genlayer staking validator-exit --shares 100 - -# Claim after unbonding period -genlayer staking validator-claim - -# Change operator address -genlayer staking set-operator --validator 0x... --operator 0xNew... - -# Update identity -genlayer staking set-identity --validator 0x... --moniker "New Name" -``` - -#### Manual Setup - -For step-by-step manual setup instructions, see the [full validator guide](https://github.com/yeagerai/genlayer-cli/blob/main/docs/validator-guide.md) in the CLI repository - ## Running the node Once you have configured everything, you are ready to start the node. **Important:** Before starting the node, ensure you have: - 1. **Operator key** imported into the node (see "Set Up The Operator Key" above) + 1. **Operator key** imported into the node (see "Import the Operator Key" above) 2. **Validator wallet address** - obtained after joining as validator via `genlayer staking wizard` or `validator-join` Without both configured, your node will run as a full node instead of a validator. From 2f511fba3ae0e5fc0b23353577f444a7dd6932c0 Mon Sep 17 00:00:00 2001 From: Edgars Date: Thu, 4 Dec 2025 16:11:43 +0000 Subject: [PATCH 16/21] docs: Clarifies validator owner address role Updates the description of the Owner address in the validator setup guide. Emphasizes that the Owner address is the only address that can withdraw staked funds, highlighting its critical role in security and control of staked assets. --- pages/validators/setup-guide.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/validators/setup-guide.mdx b/pages/validators/setup-guide.mdx index 8073b6e9..6bd3d0dd 100644 --- a/pages/validators/setup-guide.mdx +++ b/pages/validators/setup-guide.mdx @@ -15,7 +15,7 @@ GenLayer validators use three distinct addresses: | Address | Description | Where Used | |---------|-------------|------------| -| **Owner** | Your main account that holds staked funds. Keep this secure (cold wallet). | CLI wizard - signs staking transaction | +| **Owner** | The only address that can withdraw staked funds. Keep this secure (cold wallet). | CLI wizard - signs staking transaction | | **Operator** | Hot wallet on your server that signs blocks. Can be same as owner, but separate is recommended. | Node config: `operatorAddress` | | **Validator Wallet** | Smart contract created when you join. This is your validator's on-chain identity. | Node config: `validatorWalletAddress` | From 83e837f9880ed82b86f583d2490d482750f3ab02 Mon Sep 17 00:00:00 2001 From: Edgars Date: Thu, 4 Dec 2025 16:19:18 +0000 Subject: [PATCH 17/21] docs: Updates genlayer-cli docs for staking Adds new staking commands and options to the genlayer-cli documentation. This includes: - validator-prime - delegation-info - quarantined-validators - banned-validators Also adds options for the new commands and examples. --- pages/api-references/genlayer-cli.mdx | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/pages/api-references/genlayer-cli.mdx b/pages/api-references/genlayer-cli.mdx index b6bf17da..a516b3a2 100644 --- a/pages/api-references/genlayer-cli.mdx +++ b/pages/api-references/genlayer-cli.mdx @@ -283,14 +283,18 @@ USAGE: genlayer staking validator-deposit [options] genlayer staking validator-exit [options] genlayer staking validator-claim [options] + genlayer staking validator-prime [options] genlayer staking validator-info [options] genlayer staking set-operator [options] genlayer staking set-identity [options] genlayer staking delegator-join [options] genlayer staking delegator-exit [options] genlayer staking delegator-claim [options] + genlayer staking delegation-info [options] genlayer staking epoch-info [options] genlayer staking active-validators [options] + genlayer staking quarantined-validators [options] + genlayer staking banned-validators [options] COMMANDS: wizard Interactive wizard to become a validator @@ -298,14 +302,18 @@ COMMANDS: validator-deposit Make an additional deposit as a validator validator-exit Exit as a validator by withdrawing shares validator-claim Claim validator withdrawals after unbonding period + validator-prime Prime a validator to prepare stake for next epoch validator-info Get information about a validator set-operator Change the operator address for a validator set-identity Set validator identity metadata (moniker, website, socials) delegator-join Join as a delegator by staking with a validator delegator-exit Exit as a delegator by withdrawing shares delegator-claim Claim delegator withdrawals after unbonding period + delegation-info Get delegation info for a delegator with a validator epoch-info Get current epoch and staking parameters active-validators List all active validators + quarantined-validators List all quarantined validators + banned-validators List all banned validators OPTIONS (wizard): --account Account to use (skip selection) @@ -323,6 +331,9 @@ OPTIONS (validator-deposit): OPTIONS (validator-exit): --shares Number of shares to withdraw +OPTIONS (validator-prime): + --validator
Validator address to prime + OPTIONS (set-operator): --validator
Validator wallet address --operator
New operator address @@ -343,6 +354,10 @@ OPTIONS (delegator-exit): --validator
Validator to exit from --shares Number of shares to withdraw +OPTIONS (delegation-info): + --validator
Validator address + --delegator
Delegator address (defaults to signer) + COMMON OPTIONS: --network Network to use (localnet, testnet-asimov) --rpc RPC URL for the network @@ -364,6 +379,9 @@ EXAMPLES: # Delegate to a validator genlayer staking delegator-join --validator 0x123... --amount 1000gen + # Check your delegation info + genlayer staking delegation-info --validator 0x123... + # Check epoch info genlayer staking epoch-info From 065a3a738c034178e89df49d5b17270639af2364 Mon Sep 17 00:00:00 2001 From: Edgars Date: Thu, 4 Dec 2025 16:24:02 +0000 Subject: [PATCH 18/21] docs: fix sections --- pages/validators/setup-guide.mdx | 62 +++++++++++++++++--------------- 1 file changed, 33 insertions(+), 29 deletions(-) diff --git a/pages/validators/setup-guide.mdx b/pages/validators/setup-guide.mdx index 6bd3d0dd..817fb39c 100644 --- a/pages/validators/setup-guide.mdx +++ b/pages/validators/setup-guide.mdx @@ -86,9 +86,13 @@ genlayer staking set-identity --validator 0x... --moniker "New Name" --- -## Dependencies +## Set Up the Validator Node -### LLM Access +Once your validator wallet is created and staked, set up your node software. + +### Dependencies + +#### LLM Access Each validator needs access to a Large Language Model (LLM) for executing and evaluating Intelligent Contracts. @@ -100,24 +104,24 @@ Possible options: - 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 +#### ZKSync Full Node for the GenLayer Chain Each validator needs access to a [ZKSync Full Node](https://docs.zksync.io/zksync-era/tooling/external-node) 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 +### System Requirements Below are the **initial** recommended system requirements. These guidelines may change as the network grows and evolves. -### RAM +#### 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 +#### CPU - **Recommended:** Modern multi-core processor with at least 8 cores/16 threads @@ -126,17 +130,17 @@ Below are the **initial** recommended system requirements. These guidelines may - **Recommended:** `AMD64` - `ARM64` is not supported at this time -### Storage +#### Storage - **Recommended Disk Space:** 128 GB+ - **Preferred Type:** SSD or NVMe (M.2) -### Network +#### Network - 100 Mbps connection - **Recommended:**: 1 Gbps+ -### GPU (Optional) +#### 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) @@ -147,14 +151,14 @@ Below are the **initial** recommended system requirements. These guidelines may recommended hardware may change. -### Software +#### Software - Operating System - 64-bit Linux (Ubuntu, Debian, CentOS, etc.) - `docker` - for running the WebDriver container -## Setup +### Setup -### Download the node software +#### Download the node software 1. Select the version of the node you want to run by checking the available builds @@ -211,11 +215,11 @@ Below are the **initial** recommended system requirements. These guidelines may ./third_party/genvm/bin/genvm setup ``` -## Configuration +### Configuration Before you can start up the node, you need to configure it. -### `config.yaml` +#### `config.yaml` This is the main configuration file of your node. Without it, your node won't start @@ -340,7 +344,7 @@ metrics: ``` -### Overriding Configuration with Environment Variables +#### Overriding Configuration with Environment Variables Any configuration value in `config.yaml` can be overridden using environment variables with the prefix `GENLAYERNODE_`. @@ -380,7 +384,7 @@ export GENLAYERNODE_LOGGING_LEVEL="DEBUG" Environment variables take precedence over values in `config.yaml`, making them ideal for Docker deployments or sensitive values you don't want in configuration files. -### GenVM Configuration +#### 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. @@ -444,7 +448,7 @@ Related scripts are located at: More features and built-in filters will be added soon -### Import the Operator Key +#### Import the Operator Key The operator key is used by your node to sign blocks and perform validator duties. @@ -479,7 +483,7 @@ You can also generate a new operator key directly on the server: Then use this address when running the wizard on your local machine. -### Backing Up Your Operator Key +#### Backing Up Your Operator Key After setting up your operator key, back it up securely: @@ -498,7 +502,7 @@ After setting up your operator key, back it up securely: To print the private key from your backup file, use the `--print` flag. **Keep this private key secure and never share it.** -### Restoring Your Operator Key +#### Restoring Your Operator Key To restore from a backup (e.g., after migrating to a new server): @@ -515,7 +519,7 @@ To restore from a backup (e.g., after migrating to a new server): Always verify that your imported key works by checking the operator address matches what's configured for your validator. -## Running the node +### Running the node Once you have configured everything, you are ready to start the node. @@ -527,7 +531,7 @@ Once you have configured everything, you are ready to start the node. Without both configured, your node will run as a full node instead of a validator. -### Running the Node using the binary +#### Running the Node using the binary 1. Set the LLM Provider API Key @@ -593,7 +597,7 @@ Once you have configured everything, you are ready to start the node. [here](https://www.networkworld.com/article/967925/how-the-linux-screen-tool-can-save-your-tasks-and-your-sanity-if-ssh-is-interrupted.html). -### Running the Node using docker-compose +#### Running the Node using docker-compose You can also run the GenLayer node using Docker and Docker Compose. @@ -726,11 +730,11 @@ source .env && docker run --rm --env-file ./.env \ source .env && docker compose --profile node up -d ``` -## Monitoring with Metrics +### Monitoring with Metrics GenLayer validators expose comprehensive metrics that are ready for consumption by Prometheus and other monitoring tools. This allows you to monitor your validator's performance, health, and resource usage. -### Accessing Metrics +#### Accessing Metrics The metrics endpoint is exposed on the operations port (default: 9153) configured in your `config.yaml`: @@ -747,7 +751,7 @@ Once your node is running, you can access the metrics at: http://localhost:9153/metrics ``` -### Available Metrics +#### Available Metrics The validator exposes various metric collectors that can be individually configured: @@ -755,7 +759,7 @@ The validator exposes various metric collectors that can be individually configu - **GenVM Metrics**: Virtual machine performance metrics, including execution times and resource usage - **WebDriver Metrics**: Metrics related to web access and external data fetching -### Configuring Metrics Collection +#### Configuring Metrics Collection You can customize metrics collection in your `config.yaml`: @@ -774,7 +778,7 @@ metrics: interval: "60s" ``` -### Example Metrics Query +#### Example Metrics Query To check if metrics are working correctly: @@ -790,7 +794,7 @@ curl -s http://localhost:9153/metrics | grep genlayer_node_ The metrics endpoint also provides `/health` and `/balance` endpoints on the same port for additional monitoring capabilities. -### Monitoring Best Practices +#### Monitoring Best Practices 1. **Set up alerts** for critical metrics like node synchronization status and missed blocks 2. **Monitor resource usage** to ensure your validator has sufficient CPU, memory, and disk space @@ -801,6 +805,6 @@ curl -s http://localhost:9153/metrics | grep genlayer_node_ For production validators, we recommend setting up a complete monitoring stack with Prometheus and Grafana. This enables real-time visibility into your validator's performance and helps identify issues before they impact your validator's operation. -### Logs and metrics forwarding +#### Logs and metrics forwarding You can forward your logs and metrics to external systems for centralized monitoring and alerting by using the service `alloy` provided in the `docker-compose.yaml` from the extracted tarball. From c5a0bc37d8d6492308116fb2db51e2c0eb98bcf4 Mon Sep 17 00:00:00 2001 From: Edgars Date: Thu, 4 Dec 2025 17:15:13 +0000 Subject: [PATCH 19/21] docs: improve restore clarity --- pages/validators/setup-guide.mdx | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/pages/validators/setup-guide.mdx b/pages/validators/setup-guide.mdx index 817fb39c..de7a83be 100644 --- a/pages/validators/setup-guide.mdx +++ b/pages/validators/setup-guide.mdx @@ -483,42 +483,44 @@ You can also generate a new operator key directly on the server: Then use this address when running the wizard on your local machine. -#### Backing Up Your Operator Key +#### Restoring Your Operator Key -After setting up your operator key, back it up securely: +To restore from a backup (e.g., after migrating to a new server): ```sh -./bin/genlayernode account export \ +./bin/genlayernode account import \ --password "your node password" \ - --address "your operator address" \ --passphrase "your backup encryption passphrase" \ --path "/path/to/your/secure/backup.key" \ - -c $(pwd)/configs/node/config.yaml + -c $(pwd)/configs/node/config.yaml \ + --setup ``` - **Important: Back up your operator key!** Losing access means you'll need to set up a new operator and update your validator configuration. Store the backup securely. + Always verify that your imported key works by checking the operator address matches what's configured for your validator. -To print the private key from your backup file, use the `--print` flag. **Keep this private key secure and never share it.** - -#### Restoring Your Operator Key +#### Backing Up Your Operator Key -To restore from a backup (e.g., after migrating to a new server): +After setting up your operator key, back it up securely: ```sh -./bin/genlayernode account import \ +./bin/genlayernode account export \ --password "your node password" \ + --address "your operator address" \ --passphrase "your backup encryption passphrase" \ --path "/path/to/your/secure/backup.key" \ - -c $(pwd)/configs/node/config.yaml \ - --setup + -c $(pwd)/configs/node/config.yaml ``` - Always verify that your imported key works by checking the operator address matches what's configured for your validator. + **Important: Back up your operator key!** Losing access means you'll need to set up a new operator and update your validator configuration. Store the backup securely. +To print the private key from your backup file, use the `--print` flag. **Keep this private key secure and never share it.** + + + ### Running the node Once you have configured everything, you are ready to start the node. From ba526c3c9a8f67c533842f6fe1816e8cf9836d2f Mon Sep 17 00:00:00 2001 From: Edgars Date: Thu, 4 Dec 2025 17:41:57 +0000 Subject: [PATCH 20/21] docs: Adds staking documentation link Adds a link to the staking documentation for a deeper understanding of how staking works in GenLayer. --- pages/validators/setup-guide.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/pages/validators/setup-guide.mdx b/pages/validators/setup-guide.mdx index de7a83be..4a06d2f9 100644 --- a/pages/validators/setup-guide.mdx +++ b/pages/validators/setup-guide.mdx @@ -4,6 +4,8 @@ import { Callout } from "nextra-theme-docs"; Running a GenLayer Validator node ensures the security and reliability of the GenLayer network. Below are the requirements for running a GenLayer validator. +For a deeper understanding of how staking works in GenLayer, see the [Staking documentation](/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking). + ## Create the Validator Wallet Before setting up your validator node, you need to create your validator wallet and stake GEN tokens. From ab124288dbfef94e65bea6054c77e44f8111ab76 Mon Sep 17 00:00:00 2001 From: Edgars Date: Thu, 4 Dec 2025 18:07:11 +0000 Subject: [PATCH 21/21] docs: operator key upgrade guide --- pages/validators/upgrade.mdx | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/pages/validators/upgrade.mdx b/pages/validators/upgrade.mdx index 8faf683b..4d62597e 100644 --- a/pages/validators/upgrade.mdx +++ b/pages/validators/upgrade.mdx @@ -16,7 +16,16 @@ import { Callout } from "nextra-theme-docs"; `v0.4` switches to a new consensus deployment with staking. For this reason, the validator must be set up from scratch without reusing the old database stored at `data/node/genlayer.db`. You do not need to keep your existing validator node running while you download and configure the new version. +This release involves a change from a single validator address to owner/operator separation. You will need to follow the [setup guide](/validators/setup-guide) to create your new Validator Wallet. + + + **Recommended: Keep your current validator key as the operator key** + + To maintain continuity, retain your current keystore and use your existing validator address as the operator address when following the setup guide. You can find your current validator address in `configs/node/wallet.yaml`. + + - Stop the node if it is running. +- Note your current validator address from `configs/node/wallet.yaml` - you'll use this as your operator address. - Back up the `configs/node/config.yaml` file so that you can refer to any values you have set in the previous version. - Back up the `data/node/keystore` folder so that you can maintain your previous operator key. - Download the packaged binary.