fix(staking): preserve validator UX on the train

.github/e2e-track

@@ -1 +1 @@
-v0.5
+v0.6

.github/workflows/smoke.yml

@@ -9,6 +9,10 @@ on:
 jobs:
   smoke:
     name: Testnet Smoke Tests
+    # The v0.40 line intentionally targets the resolution-kernel train and
+    # does not support the currently deployed pre-train testnets. Its live
+    # coverage comes from the cross-repository E2E stack until they upgrade.
+    if: github.event_name != 'pull_request' || github.base_ref != 'v0.40-dev'
     runs-on: ubuntu-latest
     timeout-minutes: 10
     continue-on-error: true

README.md

@@ -485,7 +485,8 @@ COMMANDS:
    delegation-info [validator]   Get delegation info for a delegator with a validator
    epoch-info [options]          Get current/previous epoch info (--epoch <n> for specific)
    validators [options]          Show validator set with stake, primed status, and weight
-   active-validators [options]   List all active validators
+   active-validators [options]   List validators currently eligible for consensus duties
+   joined-validators [options]   List every validator in the joined registry
    quarantined-validators        List all quarantined validators
    banned-validators             List all banned validators
 
@@ -551,7 +552,7 @@ EXAMPLES:
    #
    #   Current Epoch: 5 (started 9h 30m ago)
    #   Next Epoch:    in 14h 30m
-   #   Validators:    33
+   #   Active Validators: 33
    #   ...
    #
    #   Previous Epoch: 4 (finalized)
@@ -563,7 +564,7 @@ EXAMPLES:
    # Query specific epoch data
    genlayer staking epoch-info --epoch 4
 
-   # List active validators
+   # List validators currently eligible for consensus duties
    genlayer staking active-validators
    # Output:
    # {
@@ -575,6 +576,9 @@ EXAMPLES:
    #   ]
    # }
 
+   # List every joined validator, including identities that are not currently active
+   genlayer staking joined-validators
+
    # Show validator set table with stake, status, weight
    genlayer staking validators
    genlayer staking validators --all  # Include banned validators

docs/api-references/_meta.json

@@ -11,6 +11,7 @@
   "estimate-fees": "estimate-fees",
   "finalize": "finalize",
   "finalize-batch": "finalize-batch",
+  "lifecycle": "lifecycle",
   "vesting": "vesting",
   "wallet": "wallet"
 }

docs/api-references/configuration/network/add.mdx

@@ -29,4 +29,5 @@ alias                        Custom network alias
 |  | --rounds-storage <addr> | RoundsStorage contract address override | No |  |
 |  | --appeals <addr> | Appeals contract address override | No |  |
 |  | --chain-id <n> | Chain ID override | No |  |
+|  | --explorer <url> | Block explorer URL for this custom network (custom networks do NOT inherit the base's explorer, to avoid misleading links) | No |  |
 | -h | --help | display help for command | No |  |

docs/api-references/finalize-batch.mdx

@@ -2,7 +2,7 @@
 title: finalize-batch
 ---
 
-Finalize a batch of idle transactions in a single call (public call)
+Advanced recovery: manually finalize eligible idle transactions
 
 ### Usage
 

docs/api-references/finalize.mdx

@@ -2,7 +2,7 @@
 title: finalize
 ---
 
-Finalize a transaction that is ready to be finalized (public call)
+Advanced recovery: manually finalize an eligible transaction
 
 ### Usage
 

docs/api-references/index.mdx

@@ -6,7 +6,7 @@ GenLayer CLI is a development environment for the GenLayer ecosystem. It allows
 developers to interact with the protocol by creating accounts, sending
 transactions, and working with Intelligent Contracts by testing, debugging, and
 deploying them.
-Version: `0.40.0-clarke.2`
+Version: `0.40.0-clarke.4`
 
 ### Command List
 
@@ -29,12 +29,13 @@ Version: `0.40.0-clarke.2`
 - `genlayer appeal` — Appeal a transaction by its hash
 - `genlayer appeal-bond` — Show minimum appeal bond required for a transaction
 - `genlayer trace` — Get execution trace for a transaction (return data, stdout, stderr, GenVM logs)
-- `genlayer finalize` — Finalize a transaction that is ready to be finalized (public call)
-- `genlayer finalize-batch` — Finalize a batch of idle transactions in a single call (public call)
 - `genlayer staking` — Staking operations for validators and delegators
 - `genlayer vesting` — Vesting operations for beneficiaries
 - `genlayer wallet` — Manage the persistent browser-wallet (MetaMask) signing session
 - `genlayer balances` — Show wallet + vesting balances and committed stake (read-only)
+- `genlayer lifecycle` — Advanced: inspect raw stored/projected lifecycle and resolution action
+- `genlayer finalize` — Advanced recovery: manually finalize an eligible transaction
+- `genlayer finalize-batch` — Advanced recovery: manually finalize eligible idle transactions
 
 ---
 

docs/api-references/lifecycle.mdx

@@ -0,0 +1,21 @@
+---
+title: lifecycle
+---
+
+Advanced: inspect raw stored/projected lifecycle and resolution action
+
+### Usage
+
+`$ genlayer lifecycle [options] <txId>`
+
+### Arguments
+
+- `<txId>`
+
+### Options
+
+| Short | Long | Description | Required | Default |
+| --- | --- | --- | :---: | --- |
+|  | --timestamp &lt;timestamp&gt; | Evaluate lifecycle at a Unix timestamp | No |  |
+|  | --rpc &lt;rpcUrl&gt; | RPC URL for the network | No |  |
+| -h | --help | display help for command | No |  |

docs/api-references/staking/staking.mdx

@@ -20,22 +20,25 @@ Staking operations for validators and delegators
 
 ### Subcommands
 
-- `genlayer wizard` — Interactive wizard to become a validator: funds the stake from your wallet or a vesting contract, and signs with a keystore key or a browser wallet (--wallet browser)
+- `genlayer wizard` — Interactive wizard to become a validator: funds the stake from your wallet or a vesting contract, and signs with a keystore key or a browser wallet (--wallet browser). Every prompt can be supplied by a flag; pass --non-interactive to run scripted with zero prompts
 - `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-operator` — Rotate a validator operator using a possession proof
+- `genlayer initiate-operator-transfer` — Start a two-step operator rotation for a validator wallet
+- `genlayer complete-operator-transfer` — Finalise a pending operator rotation once its delay has elapsed
 - `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 active-validators` — List validators currently eligible for consensus duties
+- `genlayer joined-validators` — List every validator in the joined registry
 - `genlayer quarantined-validators` — List all quarantined validators
 - `genlayer banned-validators` — List all banned validators
 - `genlayer validators` — List validators with stake, status, and optional explorer performance

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

@@ -2,7 +2,7 @@
 title: staking active-validators
 ---
 
-List all active validators
+List validators currently eligible for consensus duties
 
 ### Usage
 

docs/api-references/staking/staking/complete-operator-transfer.mdx

@@ -0,0 +1,25 @@
+---
+title: staking complete-operator-transfer
+---
+
+Finalise a pending operator rotation once its delay has elapsed
+
+### Usage
+
+`$ genlayer staking complete-operator-transfer [options] [validator]`
+
+### Arguments
+
+- `[validator]`
+
+### Options
+
+| Short | Long | Description | Required | Default |
+| --- | --- | --- | :---: | --- |
+|  | --validator <address> | Validator wallet address | No |  |
+|  | --account <name> | Account to use (validator owner or pending operator) | No |  |
+|  | --password <password> | Password to unlock account (skips interactive prompt) | No |  |
+|  | --network <network> | built-in or custom network alias (see: genlayer network list) | No |  |
+|  | --rpc <rpcUrl> | RPC URL for the network | No |  |
+|  | --wallet <mode> | Signing mode: 'keystore' or 'browser' (sign in MetaMask via a local bridge; forward the port for remote/SSH: ssh -L <port>:127.0.0.1:<port>). Defaults to the 'walletMode' config value, else 'keystore'. | No |  |
+| -h | --help | display help for command | No |  |

docs/api-references/staking/staking/initiate-operator-transfer.mdx

@@ -0,0 +1,29 @@
+---
+title: staking initiate-operator-transfer
+---
+
+Start a two-step operator rotation for a validator wallet
+
+### Usage
+
+`$ genlayer staking initiate-operator-transfer [options] [validator] [operator]`
+
+### Arguments
+
+- `[validator]`
+- `[operator]`
+
+### Options
+
+| Short | Long | Description | Required | Default |
+| --- | --- | --- | :---: | --- |
+|  | --validator <address> | Validator wallet address | No |  |
+|  | --operator <address> | Incoming operator address (key must be in the local keystore) | No |  |
+|  | --operator-account <name> | Keystore account holding the incoming operator key | No |  |
+|  | --operator-password <password> | Password to unlock the incoming operator account | No |  |
+|  | --account <name> | Account to use (must be validator owner) | No |  |
+|  | --password <password> | Password to unlock account (skips interactive prompt) | No |  |
+|  | --network <network> | built-in or custom network alias (see: genlayer network list) | No |  |
+|  | --rpc <rpcUrl> | RPC URL for the network | No |  |
+|  | --wallet <mode> | Signing mode: 'keystore' or 'browser' (sign in MetaMask via a local bridge; forward the port for remote/SSH: ssh -L <port>:127.0.0.1:<port>). Defaults to the 'walletMode' config value, else 'keystore'. | No |  |
+| -h | --help | display help for command | No |  |

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

@@ -0,0 +1,18 @@
+---
+title: staking joined-validators
+---
+
+List every validator in the joined registry
+
+### Usage
+
+`$ genlayer staking joined-validators [options]`
+
+### Options
+
+| Short | Long | Description | Required | Default |
+| --- | --- | --- | :---: | --- |
+|  | --network <network> | built-in or custom network alias (see: genlayer network list) | 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 |  |

docs/api-references/staking/staking/set-operator.mdx

@@ -2,7 +2,7 @@
 title: staking set-operator
 ---
 
-Change the operator address for a validator wallet
+Rotate a validator operator using a possession proof
 
 ### Usage
 
@@ -19,6 +19,8 @@ Change the operator address for a validator wallet
 | --- | --- | --- | :---: | --- |
 |  | --validator <address> | Validator wallet address (deprecated, use positional arg) | No |  |
 |  | --operator <address> | New operator address (deprecated, use positional arg) | No |  |
+|  | --operator-account <name> | Keystore account holding the incoming operator key | No |  |
+|  | --operator-password <password> | Password to unlock the incoming operator account | No |  |
 |  | --account <name> | Account to use (must be validator owner) | No |  |
 |  | --password <password> | Password to unlock account (skips interactive prompt) | No |  |
 |  | --network <network> | built-in or custom network alias (see: genlayer network list) | No |  |

docs/api-references/staking/staking/validator-deposit.mdx

@@ -22,5 +22,6 @@ Make an additional deposit to a validator wallet
 |  | --password <password> | Password to unlock account (skips interactive prompt) | No |  |
 |  | --network <network> | built-in or custom network alias (see: genlayer network list) | No |  |
 |  | --rpc <rpcUrl> | RPC URL for the network | No |  |
+|  | --force | Proceed even if self-stake is below the minimum required to become active | No |  |
 |  | --wallet <mode> | Signing mode: 'keystore' or 'browser' (sign in MetaMask via a local bridge; forward the port for remote/SSH: ssh -L <port>:127.0.0.1:<port>). Defaults to the 'walletMode' config value, else 'keystore'. | No |  |
 | -h | --help | display help for command | No |  |

docs/api-references/staking/staking/validator-info.mdx

@@ -21,5 +21,6 @@ Get information about a validator
 |  | --network <network> | built-in or custom network alias (see: genlayer network list) | No |  |
 |  | --rpc <rpcUrl> | RPC URL for the network | No |  |
 |  | --staking-address <address> | Staking contract address (overrides chain config) | No |  |
+|  | --json | Output raw validator info as machine-readable JSON | No |  |
 |  | --debug | Show raw unfiltered pending deposits/withdrawals | No |  |
 | -h | --help | display help for command | No |  |

docs/api-references/staking/staking/validator-join.mdx

@@ -13,11 +13,13 @@ Join as a validator by staking tokens
 | Short | Long | Description | Required | Default |
 | --- | --- | --- | :---: | --- |
 |  | --amount <amount> | Amount to stake (in wei or with 'eth'/'gen' suffix, e.g., '42000gen') | No |  |
-|  | --operator <address> | Operator address (defaults to signer) | No |  |
+|  | --operator <address> | Operator address for an imported local CLI account (defaults to signer) | No |  |
+|  | --operator-password <password> | Password for the selected operator keystore (for non-interactive proof signing) | No |  |
 |  | --account <name> | Account to use | No |  |
 |  | --password <password> | Password to unlock account (skips interactive prompt) | No |  |
 |  | --network <network> | built-in or custom network alias (see: genlayer network list) | No |  |
 |  | --rpc <rpcUrl> | RPC URL for the network | No |  |
+|  | --force | Proceed even if self-stake is below the minimum required to become active | No |  |
 |  | --staking-address <address> | Staking contract address (overrides chain config) | No |  |
 |  | --wallet <mode> | Signing mode: 'keystore' or 'browser' (sign in MetaMask via a local bridge; forward the port for remote/SSH: ssh -L <port>:127.0.0.1:<port>). Defaults to the 'walletMode' config value, else 'keystore'. | No |  |
 | -h | --help | display help for command | No |  |

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

@@ -4,7 +4,8 @@ title: staking wizard
 
 Interactive wizard to become a validator: funds the stake from your wallet or a
 vesting contract, and signs with a keystore key or a browser wallet (--wallet
-browser)
+browser). Every prompt can be supplied by a flag; pass --non-interactive to run
+scripted with zero prompts
 
 ### Usage
 
@@ -19,5 +20,23 @@ browser)
 |  | --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 |  |
+|  | --non-interactive | Run end-to-end with no prompts; every choice must come from a flag | No |  |
+|  | --yes | Alias for --non-interactive (assume yes to confirmations) | No |  |
+|  | --funding-source <source> | Where the self-stake is funded from: 'wallet' (default) or 'vesting' | No |  |
+|  | --vesting-contract <address> | Vesting contract to fund from (with --funding-source vesting) | No |  |
+|  | --operator <address> | Operator address for an imported local CLI account (0x...) | No |  |
+|  | --create-operator <name> | Create a new operator account and export its keystore | No |  |
+|  | --operator-same | Use the owner address as the operator | No |  |
+|  | --operator-password <password> | Password for the exported operator keystore (with --create-operator) | No |  |
+|  | --operator-keystore-out <path> | Output filename for the exported operator keystore | No |  |
+|  | --amount <amount> | Self-stake amount (GEN, e.g. '42' or '42gen') | No |  |
+|  | --moniker <name> | Validator display name (enables the identity step) | No |  |
+|  | --logo-uri <uri> | Logo URI | No |  |
+|  | --website <url> | Website URL | No |  |
+|  | --description <text> | Description | No |  |
+|  | --email <email> | Contact email | No |  |
+|  | --twitter <handle> | Twitter handle | No |  |
+|  | --telegram <handle> | Telegram handle | No |  |
+|  | --github <handle> | GitHub handle | No |  |
 |  | --wallet <mode> | Signing mode: 'keystore' or 'browser' (sign in MetaMask via a local bridge; forward the port for remote/SSH: ssh -L <port>:127.0.0.1:<port>). Defaults to the 'walletMode' config value, else 'keystore'. | No |  |
 | -h | --help | display help for command | No |  |

docs/api-references/transactions/receipt.mdx

@@ -16,10 +16,11 @@ Get transaction receipt by hash
 
 | Short | Long | Description | Required | Default |
 | --- | --- | --- | :---: | --- |
-|  | --status <status> | 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, LEADER_REVEALING) | No | `FINALIZED` |
+|  | --wait-until <stage> | Wait for a materialized decision or finalization (decided, finalized) | No | `finalized` |
 |  | --retries <retries> | Number of retries | No | `100` |
 |  | --interval <interval> | Interval between retries in milliseconds (default: 5000) | No |  |
 |  | --rpc <rpcUrl> | RPC URL for the network | No |  |
 |  | --stdout | Print only stdout from the receipt | No |  |
 |  | --stderr | Print only stderr from the receipt | No |  |
+|  | --raw | Show full raw receipt data | No |  |
 | -h | --help | display help for command | No |  |

docs/api-references/vesting/validator/create.mdx

@@ -16,8 +16,9 @@ Create a vesting-backed validator
 
 | Short | Long | Description | Required | Default |
 | --- | --- | --- | :---: | --- |
-|  | --operator <address> | Operator address (deprecated, use positional arg) | No |  |
+|  | --operator <address> | Operator address for an imported local CLI account (deprecated, use positional arg) | No |  |
 |  | --amount <amount> | Amount to self-stake (in wei or with 'eth'/'gen' suffix) | No |  |
+|  | --force | Proceed even if self-stake is below the minimum required to become active | No |  |
 |  | --vesting <address> | Vesting contract address (overrides beneficiary lookup) | No |  |
 |  | --account <name> | Account to use | No |  |
 |  | --password <password> | Password to unlock account (skips interactive prompt) | No |  |

docs/api-references/vesting/validator/deposit.mdx

@@ -17,6 +17,7 @@ Deposit more vesting-held tokens to a validator wallet
 | Short | Long | Description | Required | Default |
 | --- | --- | --- | :---: | --- |
 |  | --amount <amount> | Amount to deposit (in wei or with 'eth'/'gen' suffix) | No |  |
+|  | --force | Proceed even if self-stake is below the minimum required to become active | No |  |
 |  | --validator-wallet <address> | Validator wallet address (deprecated, use positional arg) | No |  |
 |  | --vesting <address> | Vesting contract address (overrides beneficiary lookup) | No |  |
 |  | --account <name> | Account to use | No |  |

docs/api-references/vesting/validator/join.mdx

@@ -16,8 +16,9 @@ Create a vesting-backed validator
 
 | Short | Long | Description | Required | Default |
 | --- | --- | --- | :---: | --- |
-|  | --operator <address> | Operator address (deprecated, use positional arg) | No |  |
+|  | --operator <address> | Operator address for an imported local CLI account (deprecated, use positional arg) | No |  |
 |  | --amount <amount> | Amount to self-stake (in wei or with 'eth'/'gen' suffix) | No |  |
+|  | --force | Proceed even if self-stake is below the minimum required to become active | No |  |
 |  | --vesting <address> | Vesting contract address (overrides beneficiary lookup) | No |  |
 |  | --account <name> | Account to use | No |  |
 |  | --password <password> | Password to unlock account (skips interactive prompt) | No |  |

docs/delegator-guide.md

@@ -44,7 +44,7 @@ Note the `delegatorMinStake` - you need at least this amount.
 
 ## Step 5: Find a Validator
 
-List all active validators:
+List validators currently eligible for consensus duties:
 
 ```bash
 genlayer staking active-validators