genlayer 0.31.0 → 0.32.1

package/docs/delegator-guide.md

@@ -0,0 +1,203 @@
+# Delegator Guide
+
+This guide walks you through delegating GEN tokens to a validator on the GenLayer testnet.
+
+## What is Delegation?
+
+Delegation allows you to stake your GEN tokens with an existing validator without running validator infrastructure yourself. You earn staking rewards proportional to your stake.
+
+## Prerequisites
+
+- Node.js installed
+- GenLayer CLI installed (`npm install -g genlayer`)
+- GEN tokens for staking
+
+## 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: Set Network to Testnet
+
+```bash
+genlayer network testnet-asimov
+```
+
+## Step 3: Fund Your Account
+
+Transfer GEN tokens to your address. Check your balance:
+
+```bash
+genlayer account
+```
+
+## Step 4: Check Minimum Delegation
+
+```bash
+genlayer staking epoch-info
+```
+
+Note the `delegatorMinStake` - you need at least this amount.
+
+## Step 5: Find a Validator
+
+List all active validators:
+
+```bash
+genlayer staking active-validators
+```
+
+Output:
+```json
+{
+  count: 6,
+  validators: [
+    '0xa8f1BF1e5e709593b4468d7ac5DC315Ea3CAe130',
+    '0xe9246A020cbb4fC6C46e60677981879c9219e8B9',
+    ...
+  ]
+}
+```
+
+Get details about a specific validator:
+
+```bash
+genlayer staking validator-info --validator 0xa8f1BF1e5e709593b4468d7ac5DC315Ea3CAe130
+```
+
+Look for:
+- `live: true` - Validator is active
+- `banned: 'Not banned'` - Validator is in good standing
+- `identity` - Validator's metadata (moniker, website, etc.)
+
+## Step 6: Unlock Your Account (Optional)
+
+For convenience:
+
+```bash
+genlayer account unlock
+```
+
+## Step 7: Delegate to a Validator
+
+```bash
+genlayer staking delegator-join --validator 0xa8f1...130 --amount 100gen
+```
+
+Options:
+- `--validator <address>` - Validator address to delegate to (required)
+- `--amount <amount>` - Amount to stake (e.g., `100gen`)
+
+## Step 8: Verify Your Delegation
+
+```bash
+genlayer staking delegation-info --validator 0xa8f1...130
+```
+
+Output:
+```json
+{
+  delegator: '0x86D0d159483CBf01E920ECfF8bB7F0Cd7E964E7E',
+  validator: '0xa8f1BF1e5e709593b4468d7ac5DC315Ea3CAe130',
+  shares: '100000000000000000000',
+  stake: '100 GEN',
+  projectedReward: '0.2 GEN per epoch',
+  pendingDeposits: 'None',
+  pendingWithdrawals: 'None'
+}
+```
+
+The `projectedReward` shows your estimated earnings per epoch based on current inflation and your stake weight.
+
+## Managing Your Delegation
+
+### Check Your Stake
+
+```bash
+genlayer staking delegation-info --validator 0xa8f1...130
+```
+
+### Withdraw (Exit) Delegation
+
+To withdraw your stake:
+
+```bash
+genlayer staking delegator-exit --validator 0xa8f1...130 --shares 50
+```
+
+Options:
+- `--validator <address>` - Validator you delegated to
+- `--shares <shares>` - Number of shares to withdraw
+
+This initiates a withdrawal. Your tokens enter an **unbonding period of 7 epochs** before they can be claimed.
+
+Check your pending withdrawals with `delegation-info`:
+```json
+pendingWithdrawals: [
+  {
+    epoch: '5',
+    shares: '50',
+    stake: '50 GEN',
+    claimableAtEpoch: '12',
+    status: 'Unbonding (4 epochs remaining)'
+  }
+]
+```
+
+### Claim Withdrawals
+
+After the 7-epoch unbonding period, claim your tokens:
+
+```bash
+genlayer staking delegator-claim --validator 0xa8f1...130
+```
+
+## Choosing a Validator
+
+Consider these factors when choosing a validator:
+
+1. **Uptime** - Validators with high uptime earn more rewards
+2. **Reputation** - Check their identity metadata and community presence
+3. **Stake** - Higher stake may indicate trust from the community
+4. **Not banned/quarantined** - Avoid validators with issues
+
+Check quarantined validators:
+```bash
+genlayer staking quarantined-validators
+```
+
+Check banned validators:
+```bash
+genlayer staking banned-validators
+```
+
+## 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 amount.
+
+### "Validator not found"
+Verify the validator address is correct and they are still active.
+
+### Transaction Stuck
+Check the transaction status:
+```bash
+genlayer receipt <tx-hash>
+```
+
+## Lock Your Account
+
+When done, lock your account:
+
+```bash
+genlayer account lock
+```

package/docs/validator-guide.md

@@ -0,0 +1,291 @@
+# Validator Guide
+
+This guide 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)
+
+## Quick Start: Validator Wizard
+
+The easiest way to become a validator is using the interactive wizard:
+
+```bash
+genlayer staking wizard
+```
+
+The wizard guides you through all steps:
+1. Account setup (create or select)
+2. Network selection
+3. Balance verification
+4. Operator setup (optional, recommended for security)
+5. Stake amount selection
+6. Validator creation
+7. Identity setup (moniker, website, etc.)
+
+If you prefer manual setup, follow the steps below.
+
+---
+
+## Manual Setup
+
+## Step 1: Create an Owner Account
+
+```bash
+genlayer account create --name owner
+```
+
+You'll be prompted to set a password. This creates an encrypted keystore file in standard web3 format.
+
+The owner account holds your staked funds and controls the validator. Keep it secure.
+
+## Step 2: View Your Account
+
+```bash
+genlayer account show
+```
+
+Output:
+```
+{
+  name: 'owner',
+  address: '0x86D0d159483CBf01E920ECfF8bB7F0Cd7E964E7E',
+  balance: '0 GEN',
+  network: 'localnet',
+  status: 'locked',
+  active: true
+}
+```
+
+## Step 3: Set Network to Testnet
+
+```bash
+genlayer network testnet-asimov
+```
+
+Verify with:
+```bash
+genlayer account show
+```
+
+You should see `network: 'Asimov Testnet'`.
+
+## Step 4: Fund Your Account
+
+Transfer GEN tokens to your address:
+- Use the faucet (if available)
+- Transfer from another funded account using `genlayer account send`
+
+## 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 <amount>` - Stake amount (e.g., `42000gen` or `42000`)
+- `--operator <address>` - 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.
+
+If you already have an operator wallet (e.g., from geth, foundry, or another tool), you can use its address directly. Otherwise, create one:
+
+```bash
+# Create operator account (skip if you already have one)
+genlayer account create --name operator
+
+# View operator address
+genlayer account show --account operator
+# Address: 0xOperator123...
+
+# Export keystore for validator node software (standard web3 format)
+genlayer account export --account operator --output ./operator-keystore.json
+
+# Join as validator with separate operator
+genlayer staking validator-join --amount 42000gen --operator 0xOperator123...
+```
+
+Transfer `operator-keystore.json` to your validator server and import it into your validator node software. The keystore is in standard web3 format, compatible with geth, foundry, and other Ethereum tools.
+
+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 <address>` - Your validator address
+- `--moniker <name>` - Display name for your validator
+
+**Optional:**
+- `--logo-uri <uri>` - Logo image URL
+- `--website <url>` - Website URL
+- `--description <text>` - Description of your validator
+- `--email <email>` - Contact email
+- `--twitter <handle>` - Twitter handle
+- `--telegram <handle>` - Telegram handle
+- `--github <handle>` - GitHub handle
+- `--extra-cid <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 show`.
+
+### "Below minimum stake"
+Check minimum with `genlayer staking epoch-info` and increase your stake amount.
+
+### Transaction Stuck
+Check the transaction status:
+```bash
+genlayer receipt <tx-hash>
+```
+
+## Lock Your Account
+
+When done, lock your account to remove the cached private key:
+
+```bash
+genlayer account lock
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genlayer",
-  "version": "0.31.0",
+  "version": "0.32.1",
   "description": "GenLayer Command Line Tool",
   "main": "src/index.ts",
   "type": "module",
@@ -65,7 +65,7 @@
     "dotenv": "^17.0.0",
     "ethers": "^6.13.4",
     "fs-extra": "^11.3.0",
-    "genlayer-js": "^0.16.0",
+    "genlayer-js": "^0.18.7",
     "inquirer": "^12.0.0",
     "keytar": "^7.9.0",
     "node-fetch": "^3.0.0",

package/src/commands/account/create.ts

@@ -0,0 +1,29 @@
+import {BaseAction} from "../../lib/actions/BaseAction";
+
+export interface CreateAccountOptions {
+  name: string;
+  overwrite: boolean;
+  setActive?: boolean;
+}
+
+export class CreateAccountAction extends BaseAction {
+  constructor() {
+    super();
+  }
+
+  async execute(options: CreateAccountOptions): Promise<void> {
+    try {
+      this.startSpinner(`Creating account '${options.name}'...`);
+      await this.createKeypairByName(options.name, options.overwrite);
+
+      if (options.setActive !== false) {
+        this.setActiveAccount(options.name);
+      }
+
+      const keystorePath = this.getKeystorePath(options.name);
+      this.succeedSpinner(`Account '${options.name}' created at: ${keystorePath}`);
+    } catch (error) {
+      this.failSpinner("Failed to create account", error);
+    }
+  }
+}

package/src/commands/account/export.ts

@@ -0,0 +1,106 @@
+import {BaseAction} from "../../lib/actions/BaseAction";
+import {ethers} from "ethers";
+import {writeFileSync, existsSync, readFileSync} from "fs";
+import path from "path";
+
+export interface ExportAccountOptions {
+  account?: string;
+  output: string;
+  password?: string;
+  sourcePassword?: string;
+  overwrite?: boolean;
+}
+
+export class ExportAccountAction extends BaseAction {
+  constructor() {
+    super();
+  }
+
+  async execute(options: ExportAccountOptions): Promise<void> {
+    try {
+      if (options.account) {
+        this.accountOverride = options.account;
+      }
+
+      const accountName = this.resolveAccountName();
+      const keystorePath = this.getKeystorePath(accountName);
+
+      if (!existsSync(keystorePath)) {
+        this.failSpinner(`Account '${accountName}' not found.`);
+      }
+
+      const outputPath = path.resolve(options.output);
+
+      if (existsSync(outputPath) && !options.overwrite) {
+        this.failSpinner(`Output file already exists: ${outputPath}`);
+      }
+
+      // Get the private key
+      const privateKey = await this.getPrivateKeyForExport(accountName, keystorePath, options.sourcePassword);
+
+      // Get password for the exported keystore
+      let password: string;
+      if (options.password) {
+        password = options.password;
+      } else {
+        password = await this.promptPassword("Enter password for exported keystore (minimum 8 characters):");
+        const confirmPassword = await this.promptPassword("Confirm password:");
+        if (password !== confirmPassword) {
+          this.failSpinner("Passwords do not match");
+        }
+      }
+
+      if (password.length < BaseAction.MIN_PASSWORD_LENGTH) {
+        this.failSpinner(`Password must be at least ${BaseAction.MIN_PASSWORD_LENGTH} characters long`);
+      }
+
+      this.startSpinner(`Exporting account '${accountName}'...`);
+
+      const wallet = new ethers.Wallet(privateKey);
+      const encryptedJson = await wallet.encrypt(password);
+
+      // Write standard web3 keystore format (compatible with geth, foundry, etc.)
+      writeFileSync(outputPath, encryptedJson);
+
+      this.succeedSpinner(`Account '${accountName}' exported to: ${outputPath}`);
+      this.logInfo(`Address: ${wallet.address}`);
+    } catch (error) {
+      this.failSpinner("Failed to export account", error);
+    }
+  }
+
+  private async getPrivateKeyForExport(
+    accountName: string,
+    keystorePath: string,
+    sourcePassword?: string
+  ): Promise<string> {
+    // First check if key is cached in keychain
+    const isAvailable = await this.keychainManager.isKeychainAvailable();
+    if (isAvailable) {
+      const cachedKey = await this.keychainManager.getPrivateKey(accountName);
+      if (cachedKey) {
+        return cachedKey;
+      }
+    }
+
+    // Need to decrypt the keystore
+    const fileContent = readFileSync(keystorePath, "utf-8");
+    const parsed = JSON.parse(fileContent);
+
+    const encryptedJson = parsed.encrypted || fileContent;
+
+    const password = sourcePassword || await this.promptPassword(`Enter password to unlock '${accountName}':`);
+
+    this.startSpinner("Decrypting keystore...");
+
+    try {
+      const wallet = await ethers.Wallet.fromEncryptedJson(encryptedJson, password);
+      this.stopSpinner();
+      return wallet.privateKey;
+    } catch {
+      this.failSpinner("Failed to decrypt keystore. Wrong password?");
+    }
+
+    throw new Error("Unreachable");
+  }
+}