genlayer 0.38.9 → 0.38.11

package/docs/api-references/staking/staking/validators.mdx

@@ -0,0 +1,19 @@
+---
+title: staking validators
+---
+
+Show validator set with stake, status, and voting power
+
+### Usage
+
+`$ genlayer staking validators [options]`
+
+### Options
+
+| Short | Long | Description | Required | Default |
+| --- | --- | --- | :---: | --- |
+|  | --all | Include banned validators | No |  |
+|  | --network <network> | Network to use (localnet, testnet-asimov) | No |  |
+|  | --rpc <rpcUrl> | RPC URL for the network | No |  |
+|  | --staking-address <address> | Staking contract address (overrides chain config) | No |  |
+| -h | --help | display help for command | No |  |

package/docs/api-references/staking/staking/wizard.mdx

@@ -0,0 +1,20 @@
+---
+title: staking wizard
+---
+
+Interactive wizard to become a validator
+
+### Usage
+
+`$ genlayer staking wizard [options]`
+
+### Options
+
+| Short | Long | Description | Required | Default |
+| --- | --- | --- | :---: | --- |
+|  | --account <name> | Account to use (skip selection) | No |  |
+|  | --network <network> | Network to use (skip selection) | No |  |
+|  | --skip-identity | Skip identity setup step | No |  |
+|  | --rpc <rpcUrl> | RPC URL for the network | No |  |
+|  | --staking-address <address> | Staking contract address (overrides chain config) | No |  |
+| -h | --help | display help for command | No |  |

package/docs/api-references/staking/staking.mdx

@@ -0,0 +1,42 @@
+---
+title: staking
+---
+
+Staking operations for validators and delegators
+
+### Usage
+
+`$ genlayer staking [options] [command]`
+
+### Arguments
+
+- `[command]`
+
+### Options
+
+| Short | Long | Description | Required | Default |
+| --- | --- | --- | :---: | --- |
+| -h | --help | display help for command | No |  |
+
+### Subcommands
+
+- `genlayer wizard` — Interactive wizard to become a validator
+- `genlayer validator-join` — Join as a validator by staking tokens
+- `genlayer validator-deposit` — Make an additional deposit to a validator wallet
+- `genlayer validator-exit` — Exit as a validator by withdrawing shares
+- `genlayer validator-claim` — Claim validator withdrawals after unbonding period
+- `genlayer validator-prime` — Prime a validator to prepare their stake record for the next epoch
+- `genlayer prime-all` — Prime all validators that need priming
+- `genlayer set-operator` — Change the operator address for a validator wallet
+- `genlayer set-identity` — Set validator identity metadata (moniker, website, socials, etc.)
+- `genlayer delegator-join` — Join as a delegator by staking with a validator
+- `genlayer delegator-exit` — Exit as a delegator by withdrawing shares from a validator
+- `genlayer delegator-claim` — Claim delegator withdrawals after unbonding period
+- `genlayer validator-info` — Get information about a validator
+- `genlayer delegation-info` — Get delegation info for a delegator with a validator
+- `genlayer epoch-info` — Get current epoch and staking parameters
+- `genlayer active-validators` — List all active validators
+- `genlayer quarantined-validators` — List all quarantined validators
+- `genlayer banned-validators` — List all banned validators
+- `genlayer validators` — Show validator set with stake, status, and voting power
+- `genlayer validator-history` — Show slash and reward history for a validator (default: last 10 epochs)

package/docs/api-references/transactions/_meta.json

@@ -0,0 +1,6 @@
+{
+  "receipt": "receipt",
+  "trace": "trace",
+  "appeal": "appeal",
+  "appeal-bond": "appeal-bond"
+}

package/docs/api-references/transactions/appeal-bond.mdx

@@ -0,0 +1,20 @@
+---
+title: appeal-bond
+---
+
+Show minimum appeal bond required for a transaction
+
+### Usage
+
+`$ genlayer appeal-bond [options] <txId>`
+
+### Arguments
+
+- `<txId>`
+
+### Options
+
+| Short | Long | Description | Required | Default |
+| --- | --- | --- | :---: | --- |
+|  | --rpc &lt;rpcUrl&gt; | RPC URL for the network | No |  |
+| -h | --help | display help for command | No |  |

package/docs/api-references/transactions/appeal.mdx

@@ -0,0 +1,21 @@
+---
+title: appeal
+---
+
+Appeal a transaction by its hash
+
+### Usage
+
+`$ genlayer appeal [options] <txId>`
+
+### Arguments
+
+- `<txId>`
+
+### Options
+
+| Short | Long | Description | Required | Default |
+| --- | --- | --- | :---: | --- |
+|  | --bond &lt;amount&gt; | Appeal bond amount (e.g. 500gen, 0.5gen). Auto-calculated if omitted | No |  |
+|  | --rpc &lt;rpcUrl&gt; | RPC URL for the network | No |  |
+| -h | --help | display help for command | No |  |

package/docs/api-references/transactions/receipt.mdx

@@ -0,0 +1,25 @@
+---
+title: receipt
+---
+
+Get transaction receipt by hash
+
+### Usage
+
+`$ genlayer receipt [options] <txId>`
+
+### Arguments
+
+- `<txId>`
+
+### Options
+
+| Short | Long | Description | Required | Default |
+| --- | --- | --- | :---: | --- |
+|  | --status &lt;status&gt; | Transaction status to wait for (UNINITIALIZED, PENDING, PROPOSING, COMMITTING, REVEALING, ACCEPTED, UNDETERMINED, FINALIZED, CANCELED, APPEAL_REVEALING, APPEAL_COMMITTING, READY_TO_FINALIZE, VALIDATORS_TIMEOUT, LEADER_TIMEOUT) (default: "FINALIZED") | No |  |
+|  | --retries &lt;retries&gt; | Number of retries | No | `100` |
+|  | --interval &lt;interval&gt; | Interval between retries in milliseconds (default: 5000) | No |  |
+|  | --rpc &lt;rpcUrl&gt; | RPC URL for the network | No |  |
+|  | --stdout | Print only stdout from the receipt | No |  |
+|  | --stderr | Print only stderr from the receipt | No |  |
+| -h | --help | display help for command | No |  |

package/docs/api-references/transactions/trace.mdx

@@ -0,0 +1,21 @@
+---
+title: trace
+---
+
+Get execution trace for a transaction (return data, stdout, stderr, GenVM logs)
+
+### Usage
+
+`$ genlayer trace [options] <txId>`
+
+### Arguments
+
+- `<txId>`
+
+### Options
+
+| Short | Long | Description | Required | Default |
+| --- | --- | --- | :---: | --- |
+|  | --round &lt;round&gt; | Consensus round number | No | `0) (default: 0` |
+|  | --rpc &lt;rpcUrl&gt; | RPC URL for the network | No |  |
+| -h | --help | display help for command | No |  |

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-bradbury
+```
+
+## 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,329 @@
+# Validator Guide
+
+This guide walks you through becoming a validator on the GenLayer testnet using the CLI.
+
+For a deeper understanding of how staking works in GenLayer, see the [Staking documentation](/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking).
+
+## 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-bradbury
+```
+
+Verify with:
+```bash
+genlayer account show
+```
+
+You should see `network: 'Bradbury 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:
+```
+✔ Epoch info
+
+  Current Epoch: 5 (started 9h 30m ago)
+  Next Epoch:    in 14h 30m
+  Validators:    33
+  Weight:        6061746783417938774454
+  Slashed:       0 GEN
+
+  Previous Epoch: 4 (finalized)
+  Inflation:      1732904.66 GEN
+  Claimed:        0 GEN
+  Unclaimed:      1732904.66 GEN
+  Slashed:        0 GEN
+
+  Min Epoch Duration:   24h 0m
+  Validator Min Stake:  42000 GEN
+  Delegator Min Stake:  42 GEN
+```
+
+You can also query a specific epoch:
+```bash
+genlayer staking epoch-info --epoch 4
+```
+
+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
+
+### Priming Your Validator
+
+Validators must be "primed" each epoch to participate in consensus. Priming updates the validator's stake record for the upcoming epoch.
+
+```bash
+# Prime your validator
+genlayer staking validator-prime 0xYourValidator...
+
+# Or prime all validators at once (anyone can do this)
+genlayer staking prime-all
+```
+
+The `validators` command shows priming status:
+- **Green** `e11` - Primed for current epoch
+- **Yellow** `e10` - Needs priming before next epoch
+- **Red** `e9!` - Urgently needs priming (behind)
+
+### Add More Stake
+
+```bash
+genlayer staking validator-deposit --validator 0xYourValidatorWallet... --amount 1000gen
+```
+
+### Check Active Validators
+
+```bash
+genlayer staking active-validators
+```
+
+### View Validator Set
+
+```bash
+# Show all validators with stake, primed status, and weight
+genlayer staking validators
+
+# Include banned validators
+genlayer staking validators --all
+```
+
+### Exit as Validator
+
+```bash
+genlayer staking validator-exit --validator 0xYourValidatorWallet... --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 --validator 0xYourValidatorWallet...
+```
+
+## 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
+```