Reviewing files that changed from the base of the PR and between 26ea482 and 51340fd.

• CLAUDE.md (1 hunks)
• README.md (3 hunks)
• docs/delegator-guide.md (1 hunks)
• docs/validator-guide.md (1 hunks)
• src/commands/account/create.ts (1 hunks)
• src/commands/account/import.ts (1 hunks)
• src/commands/account/index.ts (1 hunks)
• src/commands/account/lock.ts (2 hunks)
• src/commands/account/send.ts (1 hunks)
• src/commands/account/show.ts (1 hunks)
• src/commands/account/unlock.ts (2 hunks)
• src/commands/keygen/create.ts (0 hunks)
• src/commands/keygen/index.ts (0 hunks)
• src/commands/network/setNetwork.ts (2 hunks)
• src/commands/staking/StakingAction.ts (1 hunks)
• src/commands/staking/delegatorClaim.ts (1 hunks)
• src/commands/staking/delegatorExit.ts (1 hunks)
• src/commands/staking/delegatorJoin.ts (1 hunks)
• src/commands/staking/index.ts (1 hunks)
• src/commands/staking/setIdentity.ts (1 hunks)
• src/commands/staking/setOperator.ts (1 hunks)
• src/commands/staking/stakingInfo.ts (1 hunks)
• src/commands/staking/validatorClaim.ts (1 hunks)
• src/commands/staking/validatorDeposit.ts (1 hunks)
• src/commands/staking/validatorExit.ts (1 hunks)
• src/commands/staking/validatorJoin.ts (1 hunks)
• src/commands/staking/validatorPrime.ts (1 hunks)
• src/index.ts (1 hunks)
• src/lib/actions/BaseAction.ts (4 hunks)
• tests/actions/create.test.ts (2 hunks)
• tests/actions/lock.test.ts (4 hunks)
• tests/actions/setNetwork.test.ts (8 hunks)
• tests/actions/staking.test.ts (1 hunks)
• tests/actions/unlock.test.ts (9 hunks)
• tests/commands/account.test.ts (1 hunks)
• tests/commands/keygen.test.ts (0 hunks)
• tests/commands/staking.test.ts (1 hunks)
• tests/index.test.ts (2 hunks)
• tests/libs/baseAction.test.ts (1 hunks)

• src/commands/keygen/index.ts
• src/commands/keygen/create.ts
• tests/commands/keygen.test.ts

src/commands/account/lock.ts (1)

1-30: LGTM! Clean terminology update.

The rename from LockAction to LockAccountAction and the updated user-facing messages ("account" instead of "wallet") align well with the broader refactor to account-centric terminology across the CLI.

src/commands/account/unlock.ts (1)

1-41: LGTM! Consistent terminology update.

The rename from UnlockAction to UnlockAccountAction and the updated messaging align well with the account-centric refactor. The core unlock flow remains functionally unchanged.

src/index.ts (1)

6-27: LGTM! CLI initialization updated correctly.

The replacement of initializeKeygenCommands with initializeAccountCommands and the addition of initializeStakingCommands properly reflect the new command structure. The initialization order is logical and consistent.

CLAUDE.md (1)

1-55: LGTM! Helpful documentation for AI assistants.

This documentation provides clear guidance on the project structure, build/test commands, and architectural patterns. The content accurately reflects the current codebase structure including the new account and staking command domains.

tests/libs/baseAction.test.ts (1)

110-124: LGTM! Tests correctly cover new failSpinner behavior.

The updates properly test both the non-exit path (with shouldExit=false) and the default exit behavior. This aligns with the broader refactor to support non-fatal error handling in BaseAction.

Based on learnings, the codebase uses failSpinner patterns for error handling rather than throwing exceptions.

docs/delegator-guide.md (1)

1-203: Excellent comprehensive guide for delegators!

The guide provides clear step-by-step instructions with concrete examples and expected outputs. The content covers all essential aspects of delegation including validator selection criteria, stake management, and troubleshooting.

tests/index.test.ts (1)

16-50: LGTM! Test mocks updated correctly.

The mocks properly reflect the CLI refactor from keygen to account commands and the addition of staking commands.

src/commands/account/index.ts (1)

9-67: LGTM! Clean command wiring with good UX.

The command structure is well-organized with:

• A sensible default action (showing account info)
• Consistent pattern across all subcommands
• Clear option descriptions and defaults
• Ergonomic command signatures (e.g., send <to> <amount>)

src/commands/staking/delegatorJoin.ts (1)

1-42: LGTM!

The implementation follows established patterns from other staking actions (ValidatorJoinAction, DelegatorClaimAction) with appropriate error handling, spinner feedback, and structured output.

src/commands/staking/index.ts (1)

1-224: LGTM!

The staking command wiring is comprehensive and consistent. All subcommands properly define their options, match their corresponding action interfaces, and follow the established CLI patterns.

tests/actions/lock.test.ts (1)

2-64: LGTM!

Test updates correctly align with the renamed LockAccountAction and updated messaging. All test expectations match the implementation.

src/commands/network/setNetwork.ts (1)

30-59: LGTM!

The alias-based network storage implementation is correct and consistent throughout the method. The non-null assertion on line 56 is safe since the network is validated before use.

src/commands/staking/setOperator.ts (1)

1-40: LGTM!

The implementation follows the established staking action patterns with proper error handling and structured output. Consistent with other staking actions like ValidatorJoinAction and SetIdentityAction.

src/commands/account/show.ts (1)

17-59: LGTM!

The implementation correctly handles account info retrieval with proper validation, error handling, and formatted output. Network resolution is properly integrated.

src/commands/staking/delegatorExit.ts (1)

1-50: LGTM!

The implementation correctly mirrors ValidatorExitAction patterns with proper shares validation (positive BigInt check), error handling, and informative output including the unbonding period note.

docs/validator-guide.md (1)

113-113: No action needed — the --output option is properly implemented.

The genlayer account create command includes the --output option, defined in src/commands/account/index.ts at line 22 with the default value "./keypair.json". The documentation example is accurate.

src/commands/account/create.ts (1)

1-23: CreateAccountAction wiring and flow look consistent and correct

Account creation delegates cleanly to BaseAction.createKeypair, and spinner/success/failure handling matches the existing action patterns. I don’t see any functional issues here.

tests/actions/unlock.test.ts (1)

2-121: UnlockAccountAction tests accurately track the new account-unlock behavior

The tests now line up with UnlockAccountAction (constructor, path, spinner text, error messages) and exercise the key success and failure paths, so the coverage here looks solid.

tests/actions/setNetwork.test.ts (1)

29-145: NetworkActions tests correctly reflect alias-based network storage

The expectations against writeConfig("network", "<alias>") and the updated interactive prompt choices/return values all match the new alias-centric network handling, while keeping the existing failure cases intact. Looks good.

tests/commands/account.test.ts (1)

1-121: Account command wiring tests align with initializeAccountCommands behavior

These tests correctly assert the options passed into CreateAccountAction.execute for all flag combinations, and verify that unlock/lock actions are instantiated and invoked. The coverage of the CLI wiring looks good.

src/commands/staking/delegatorClaim.ts (1)

1-41: DelegatorClaimAction execute flow is consistent and matches tests

The action correctly resolves the delegator address (explicit or signer), calls client.delegatorClaim with typed addresses, and surfaces clear spinner messages on success/failure. It lines up with the expectations in tests/actions/staking.test.ts.

src/commands/staking/validatorDeposit.ts (1)

1-35: ValidatorDepositAction logic is straightforward and correct (pending StakingAction helper fix)

The deposit action correctly parses the amount via parseAmount, calls validatorDeposit, and reports a detailed success payload; error handling follows the shared pattern. Once the parseAmount/formatAmount helpers in StakingAction are fixed, this should work as intended.

src/commands/staking/validatorJoin.ts (1)

1-47: LGTM! Clean implementation following established patterns.

The action correctly extends StakingAction, handles the optional operator parameter, and follows the spinner-based UX pattern used by other staking actions. Error handling and output formatting are consistent with the codebase conventions.

tests/actions/create.test.ts (1)

1-45: LGTM! Tests properly updated to align with the renamed action class.

The test expectations correctly match the implementation in src/commands/account/create.ts. Both success and error paths are covered.

src/commands/staking/validatorClaim.ts (1)

1-38: LGTM! Clean implementation with sensible defaults.

The action correctly falls back to the signer's address when no validator is specified, which is the expected behavior for self-claiming. The implementation follows the established staking action pattern.

src/commands/staking/validatorPrime.ts (1)

1-35: LGTM! Follows the established staking action pattern.

The implementation is clean and consistent with other staking actions. The required validator parameter is appropriate for this operation.

src/commands/staking/setIdentity.ts (1)

1-61: Overall structure looks good.

The action correctly extends StakingAction and follows the established spinner-based UX pattern.

src/commands/staking/validatorExit.ts (2)

15-23: Good input validation for shares.

The nested try-catch correctly handles both invalid numeric input (e.g., non-numeric strings) and non-positive values. The early return after failSpinner prevents further execution.

---

1-44: LGTM! Clean implementation with proper validation.

The action correctly validates the shares input before attempting the exit operation and includes a helpful note about the unbonding period in the output.

src/commands/account/send.ts (3)

110-118: Consider making the polling timeout configurable or using exponential backoff.

The fixed 2-second polling interval for up to 60 iterations (120 seconds total) works but could be improved:

• Network congestion may require longer waits
• Initial polls could use shorter intervals

This is acceptable for now but could be enhanced later.

---

47-149: Overall implementation is solid.

The execute method correctly handles:

• Account validation and keystore decryption
• Network resolution with fallback
• Transaction preparation, signing, and submission
• Receipt polling with graceful handling of pending transactions
• Error handling throughout the flow

---

79-80: The Hash type cast is correct and does not require changes.

The Hash type from genlayer-js/types is equivalent to 0x${string} (a hex string prefixed with "0x"), which is exactly what createAccount expects. However, note that src/commands/staking/StakingAction.ts line 47 uses the more explicit 0x${string} pattern for the same function call. Consider aligning this with that pattern for consistency across the codebase.

README.md (2)

296-393: Well-documented staking operations section.

The staking documentation is comprehensive with clear command descriptions, options, and practical examples including sample output. This will help users understand the staking workflows effectively.

---

412-416: Both guide documents exist in the repository (docs/validator-guide.md and docs/delegator-guide.md), so the links in the Guides section are valid.

src/commands/account/import.ts (3)

1-10: Clean imports and interface definition.

The interface correctly defines the import options with optional privateKey for interactive input.

---

19-65: LGTM - Solid import workflow implementation.

The execute method properly:

• Handles both CLI argument and interactive input for private keys
• Validates before file I/O operations
• Uses secure password prompts with confirmation
• Clears the keychain after import to ensure clean state

---

67-80: Good security practice using masked input for private key.

Using promptPassword for private key input ensures the sensitive data is masked in the terminal.

src/lib/actions/BaseAction.ts (4)

97-108: Clean integration of network resolution.

The getClient method now uses the centralized resolveNetwork function, simplifying network handling across the codebase.

---

123-129: Good use of non-exiting failure for recoverable scenarios.

Using failSpinner(..., undefined, false) allows the user to be informed of the invalid format while still offering the option to create a new keypair.

---

253-260: Backwards-compatible enhancement to failSpinner.

The optional shouldExit parameter (defaulting to true) maintains existing behavior while enabling non-fatal failure scenarios. Based on learnings, this aligns with the codebase's error handling patterns.

---

11-44: Network resolution implementation is sound with proper backwards compatibility.

The resolveNetwork function cleanly handles both the new alias format (direct key lookup) and old JSON format (with name matching) for backwards compatibility. The assumption that built-in network names (localnet, studionet, testnetAsimov) are unique across chains is reasonable given they're imported from the external genlayer-js library and used consistently throughout the codebase. The implementation correctly prioritizes direct alias lookup first for performance before falling back to JSON parsing, and provides appropriate error handling for truly invalid input.

src/commands/staking/stakingInfo.ts (3)

1-11: Clean interface and class setup.

The StakingInfoOptions interface appropriately extends StakingConfig for the query methods that need a validator address.

---

184-226: Well-implemented epoch info retrieval.

The formatDuration helper and time calculations are clean. The method provides comprehensive epoch information with human-readable formatting.

---

228-291: Consistent implementation across validator list methods.

All three list methods (listActiveValidators, listQuarantinedValidators, listBannedValidators) follow a clean, consistent pattern with proper error handling.