genlayer 0.31.0 → 0.32.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.32.1 (2025-12-04)
+
+## 0.32.0 (2025-12-03)
+
+### Features
+
+* Implements staking functionality ([#266](https://github.com/yeagerai/genlayer-cli/issues/266)) ([36e4180](https://github.com/yeagerai/genlayer-cli/commit/36e4180c6093f380d1f552e9051345812e6bd024))
+
 ## 0.31.0 (2025-09-03)
 
 ### Features

package/CLAUDE.md

@@ -0,0 +1,55 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build & Development
+
+```bash
+npm install          # Install dependencies
+npm run dev          # Watch mode development build (uses esbuild)
+npm run build        # Production build
+node dist/index.js   # Run CLI from source
+```
+
+## Testing
+
+```bash
+npm test             # Run all tests (vitest)
+npm run test:watch   # Watch mode
+npm run test:coverage # Coverage report
+npx vitest tests/commands/deploy.test.ts  # Single test file
+npx vitest -t "test name pattern"         # Run specific test by name
+```
+
+## Architecture
+
+### Entry Point & Command Structure
+- `src/index.ts` - Main entry, initializes Commander program and registers all command groups
+- Commands organized in `src/commands/<domain>/index.ts` - each exports `initialize*Commands(program)` function
+- Command domains: general (init/up/stop), account, contracts, config, localnet, update, scaffold, network, transactions, staking
+
+### Core Classes
+- `BaseAction` (`src/lib/actions/BaseAction.ts`) - Base class for all CLI actions. Provides:
+  - GenLayer client initialization via `genlayer-js` SDK
+  - Keystore management (encrypted wallet with password)
+  - Spinner/logging utilities (ora, chalk)
+  - User prompts (inquirer)
+- `ConfigFileManager` (`src/lib/config/ConfigFileManager.ts`) - Manages `~/.genlayer/genlayer-config.json`
+- `KeychainManager` (`src/lib/config/KeychainManager.ts`) - System keychain integration via keytar
+
+### Pattern for Adding Commands
+1. Create action class extending `BaseAction` in `src/commands/<domain>/<action>.ts`
+2. Export action options interface
+3. Register in domain's `index.ts` via Commander
+4. Add tests in `tests/commands/<domain>.test.ts` and `tests/actions/<action>.test.ts`
+
+### External Dependencies
+- `commander` - CLI framework
+- `genlayer-js` - GenLayer SDK for blockchain interactions
+- `ethers` - Wallet/keystore encryption
+- `dockerode` - Docker management for localnet
+- `viem` - Ethereum utilities
+
+### Path Aliases
+- `@/*` → `./src/*`
+- `@@/tests/*` → `./tests/*`

package/README.md

@@ -203,21 +203,30 @@ EXAMPLES:
 ##### Schema
 - `schema` - Retrieves the contract schema
 
-#### Keypair Management
+#### Account Management
 
-Generate and manage keypairs.
+View and manage your account.
 
 ```bash
 USAGE:
-   genlayer keygen create [options]
+   genlayer account                   Show account info (address, balance, network, status)
+   genlayer account create [options]  Create a new account
+   genlayer account send <to> <amount> Send GEN to an address
+   genlayer account unlock            Unlock account (cache key in OS keychain)
+   genlayer account lock              Lock account (remove key from OS keychain)
 
-OPTIONS:
-   --output <path>    Path to save the keypair (default: "./keypair.json")
-   --overwrite        Overwrite the existing file if it already exists (default: false)
+OPTIONS (create):
+   --output <path>    Path to save the keystore (default: "./keypair.json")
+   --overwrite        Overwrite existing file (default: false)
 
 EXAMPLES:
-   genlayer keygen create
-   genlayer keygen create --output ./my_key.json --overwrite
+   genlayer account
+   genlayer account create
+   genlayer account create --output ./my_key.json --overwrite
+   genlayer account send 0x123...abc 10gen
+   genlayer account send 0x123...abc 0.5gen
+   genlayer account unlock
+   genlayer account lock
 ```
 
 #### Update Resources
@@ -284,6 +293,105 @@ EXAMPLES:
    genlayer localnet validators create-random --count 3 --providers openai --models gpt-4 gpt-4o
 ```
 
+#### Staking Operations
+
+Manage staking for validators and delegators on testnet-asimov. Staking is not available on localnet/studio.
+
+```bash
+USAGE:
+   genlayer staking <command> [options]
+
+COMMANDS:
+   validator-join [options]      Join as a validator by staking tokens
+   validator-deposit [options]   Make an additional deposit as a validator
+   validator-exit [options]      Exit as a validator by withdrawing shares
+   validator-claim [options]     Claim validator withdrawals after unbonding period
+   delegator-join [options]      Join as a delegator by staking with a validator
+   delegator-exit [options]      Exit as a delegator by withdrawing shares
+   delegator-claim [options]     Claim delegator withdrawals after unbonding period
+   validator-info [options]      Get information about a validator
+   delegation-info [options]     Get delegation info for a delegator with a validator
+   epoch-info [options]          Get epoch info with timing estimates
+   active-validators [options]   List all active validators
+
+COMMON OPTIONS (all commands):
+   --network <network>           Network to use (localnet, testnet-asimov)
+   --rpc <rpcUrl>                RPC URL override
+   --staking-address <address>   Staking contract address override
+
+OPTIONS (validator-join):
+   --amount <amount>             Amount to stake (in wei or with 'gen' suffix)
+   --operator <address>          Operator address (defaults to signer)
+
+OPTIONS (delegator-join):
+   --validator <address>         Validator address to delegate to
+   --amount <amount>             Amount to stake (in wei or with 'gen' suffix)
+
+OPTIONS (exit commands):
+   --shares <shares>             Number of shares to withdraw
+   --validator <address>         Validator address (for delegator commands)
+
+EXAMPLES:
+   # Get epoch info (uses --network to specify testnet-asimov)
+   genlayer staking epoch-info --network testnet-asimov
+
+   # Or set network globally first
+   genlayer network testnet-asimov
+
+   # Join as validator with 42000 GEN
+   genlayer staking validator-join --amount 42000gen
+
+   # Join as delegator with 42 GEN
+   genlayer staking delegator-join --validator 0x... --amount 42gen
+
+   # Check validator info
+   genlayer staking validator-info --validator 0x...
+   # Output:
+   # {
+   #   validator: '0xa8f1BF1e5e709593b4468d7ac5DC315Ea3CAe130',
+   #   vStake: '0.01 GEN',
+   #   vShares: '10000000000000000',
+   #   dStake: '0 GEN',
+   #   dShares: '0',
+   #   vDeposit: '0 GEN',
+   #   vWithdrawal: '0 GEN',
+   #   epoch: '0',
+   #   live: true,
+   #   banned: 'Not banned'
+   # }
+
+   # Get current epoch info (includes timing estimates)
+   genlayer staking epoch-info
+   # Output:
+   # {
+   #   currentEpoch: '2',
+   #   epochStarted: '2025-11-28T09:57:49.000Z',
+   #   epochEnded: 'Not ended',
+   #   nextEpochEstimate: '2025-11-29T09:57:49.000Z',
+   #   timeUntilNextEpoch: '19h 56m',
+   #   minEpochDuration: '24h 0m',
+   #   validatorMinStake: '0.01 GEN',
+   #   delegatorMinStake: '42 GEN',
+   #   activeValidatorsCount: '6'
+   # }
+
+   # List active validators
+   genlayer staking active-validators
+   # Output:
+   # {
+   #   count: 6,
+   #   validators: [
+   #     '0xa8f1BF1e5e709593b4468d7ac5DC315Ea3CAe130',
+   #     '0xe9246A020cbb4fC6C46e60677981879c9219e8B9',
+   #     ...
+   #   ]
+   # }
+
+   # Exit and claim
+   genlayer staking validator-exit --shares 100
+   genlayer staking validator-claim
+```
+
 ### Running the CLI from the repository
 
 First, install the dependencies and start the build process
@@ -301,6 +409,11 @@ Then in another window execute the CLI commands like so:
 node dist/index.js init
 ```
 
+## Guides
+
+- [Validator Guide](docs/validator-guide.md) - How to become a validator on GenLayer testnet
+- [Delegator Guide](docs/delegator-guide.md) - How to delegate GEN to a validator
+
 ## Documentation
 
 For detailed information on how to use GenLayer CLI, please refer to our [documentation](https://docs.genlayer.com/).