genlayer 0.31.0 → 0.32.0

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:
+```
+{
+  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 stake-info --validator 0xa8f1...130
+```
+
+Output:
+```
+{
+  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 stake-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 `stake-info`:
+```
+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,260 @@
+# 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)
+
+## 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 <your-address> 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 <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.
+
+```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 <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`.
+
+### "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.0",
   "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.5",
     "inquirer": "^12.0.0",
     "keytar": "^7.9.0",
     "node-fetch": "^3.0.0",

package/src/commands/account/create.ts

@@ -0,0 +1,23 @@
+import {BaseAction} from "../../lib/actions/BaseAction";
+
+export interface CreateAccountOptions {
+  output: string;
+  overwrite: boolean;
+}
+
+export class CreateAccountAction extends BaseAction {
+  constructor() {
+    super();
+  }
+
+  async execute(options: CreateAccountOptions): Promise<void> {
+    try {
+      this.startSpinner("Creating encrypted keystore...");
+      await this.createKeypair(options.output, options.overwrite);
+
+      this.succeedSpinner(`Account created and saved to: ${options.output}`);
+    } catch (error) {
+      this.failSpinner("Failed to create account", error);
+    }
+  }
+}

package/src/commands/account/import.ts

@@ -0,0 +1,81 @@
+import {BaseAction} from "../../lib/actions/BaseAction";
+import {ethers} from "ethers";
+import {writeFileSync, existsSync} from "fs";
+import {KeystoreData} from "../../lib/interfaces/KeystoreData";
+
+export interface ImportAccountOptions {
+  privateKey?: string;
+  output: string;
+  overwrite: boolean;
+}
+
+export class ImportAccountAction extends BaseAction {
+  private static readonly MIN_PASSWORD_LENGTH = 8;
+
+  constructor() {
+    super();
+  }
+
+  async execute(options: ImportAccountOptions): Promise<void> {
+    try {
+      const privateKey = options.privateKey || await this.promptPrivateKey();
+
+      const normalizedKey = this.normalizePrivateKey(privateKey);
+      this.validatePrivateKey(normalizedKey);
+
+      const finalOutputPath = this.getFilePath(options.output);
+
+      if (existsSync(finalOutputPath) && !options.overwrite) {
+        this.failSpinner(`File at ${finalOutputPath} already exists. Use '--overwrite' to replace.`);
+      }
+
+      const wallet = new ethers.Wallet(normalizedKey);
+
+      const password = await this.promptPassword("Enter a password to encrypt your keystore (minimum 8 characters):");
+      const confirmPassword = await this.promptPassword("Confirm password:");
+
+      if (password !== confirmPassword) {
+        this.failSpinner("Passwords do not match");
+      }
+
+      if (password.length < ImportAccountAction.MIN_PASSWORD_LENGTH) {
+        this.failSpinner(`Password must be at least ${ImportAccountAction.MIN_PASSWORD_LENGTH} characters long`);
+      }
+
+      this.startSpinner("Encrypting and saving keystore...");
+
+      const encryptedJson = await wallet.encrypt(password);
+
+      const keystoreData: KeystoreData = {
+        version: 1,
+        encrypted: encryptedJson,
+        address: wallet.address,
+      };
+
+      writeFileSync(finalOutputPath, JSON.stringify(keystoreData, null, 2));
+      this.writeConfig("keyPairPath", finalOutputPath);
+
+      await this.keychainManager.removePrivateKey();
+
+      this.succeedSpinner(`Account imported and saved to: ${finalOutputPath}`);
+      this.logInfo(`Address: ${wallet.address}`);
+    } catch (error) {
+      this.failSpinner("Failed to import account", error);
+    }
+  }
+
+  private async promptPrivateKey(): Promise<string> {
+    return this.promptPassword("Enter private key to import:");
+  }
+
+  private normalizePrivateKey(key: string): string {
+    const trimmed = key.trim();
+    return trimmed.startsWith("0x") ? trimmed : `0x${trimmed}`;
+  }
+
+  private validatePrivateKey(key: string): void {
+    if (!/^0x[0-9a-fA-F]{64}$/.test(key)) {
+      this.failSpinner("Invalid private key format. Expected 64 hex characters (with or without 0x prefix).");
+    }
+  }
+}

package/src/commands/account/index.ts

@@ -0,0 +1,67 @@
+import {Command} from "commander";
+import {ShowAccountAction} from "./show";
+import {CreateAccountAction, CreateAccountOptions} from "./create";
+import {ImportAccountAction, ImportAccountOptions} from "./import";
+import {UnlockAccountAction} from "./unlock";
+import {LockAccountAction} from "./lock";
+import {SendAction, SendOptions} from "./send";
+
+export function initializeAccountCommands(program: Command) {
+  const accountCommand = program
+    .command("account")
+    .description("Manage your account (address, balance, keys)")
+    .action(async () => {
+      // Default action: show account info
+      const showAction = new ShowAccountAction();
+      await showAction.execute();
+    });
+
+  accountCommand
+    .command("create")
+    .description("Create a new account with encrypted keystore")
+    .option("--output <path>", "Path to save the keystore", "./keypair.json")
+    .option("--overwrite", "Overwrite existing file", false)
+    .action(async (options: CreateAccountOptions) => {
+      const createAction = new CreateAccountAction();
+      await createAction.execute(options);
+    });
+
+  accountCommand
+    .command("import")
+    .description("Import an account from a private key")
+    .option("--private-key <key>", "Private key to import (will prompt if not provided)")
+    .option("--output <path>", "Path to save the keystore", "./keypair.json")
+    .option("--overwrite", "Overwrite existing file", false)
+    .action(async (options: ImportAccountOptions) => {
+      const importAction = new ImportAccountAction();
+      await importAction.execute(options);
+    });
+
+  accountCommand
+    .command("send <to> <amount>")
+    .description("Send GEN to an address")
+    .option("--rpc <rpcUrl>", "RPC URL for the network")
+    .option("--network <network>", "Network to use (localnet, testnet-asimov)")
+    .action(async (to: string, amount: string, options: {rpc?: string; network?: string}) => {
+      const sendAction = new SendAction();
+      await sendAction.execute({to, amount, rpc: options.rpc, network: options.network});
+    });
+
+  accountCommand
+    .command("unlock")
+    .description("Unlock account by caching private key in OS keychain")
+    .action(async () => {
+      const unlockAction = new UnlockAccountAction();
+      await unlockAction.execute();
+    });
+
+  accountCommand
+    .command("lock")
+    .description("Lock account by removing private key from OS keychain")
+    .action(async () => {
+      const lockAction = new LockAccountAction();
+      await lockAction.execute();
+    });
+
+  return program;
+}

package/src/commands/{keygen → account}/lock.ts

@@ -1,6 +1,6 @@
-import { BaseAction } from "../../lib/actions/BaseAction";
+import {BaseAction} from "../../lib/actions/BaseAction";
 
-export class LockAction extends BaseAction {
+export class LockAccountAction extends BaseAction {
   async execute(): Promise<void> {
     this.startSpinner("Checking keychain availability...");
 
@@ -14,7 +14,7 @@ export class LockAction extends BaseAction {
 
     const hasCachedKey = await this.keychainManager.getPrivateKey();
     if (!hasCachedKey) {
-      this.succeedSpinner("Wallet is already locked (no cached key found in OS keychain).");
+      this.succeedSpinner("Account is already locked.");
       return;
     }
 
@@ -22,10 +22,9 @@ export class LockAction extends BaseAction {
 
     try {
       await this.keychainManager.removePrivateKey();
-      
-      this.succeedSpinner("Wallet locked successfully! Your private key has been removed from the OS keychain.");
+      this.succeedSpinner("Account locked! Private key removed from OS keychain.");
     } catch (error) {
-      this.failSpinner("Failed to lock wallet.", error);
+      this.failSpinner("Failed to lock account.", error);
     }
   }
-} 
+}