## What Migrate the `--keystore-factory` interactive REPL from FullNode.jar to Toolkit.jar as picocli subcommands, extract the keystore core library from `framework` to `crypto` module, and add new capabilities (list, update, SM2 support, JSON output, password-file support). ## Why **The current `--keystore-factory` has several limitations:** 1. **Coupled to FullNode.jar** — operators must have the full node binary and configuration to manage keystore files, even though keystore operations have zero dependency on the node runtime 2. **Interactive REPL only** — cannot be scripted, piped, or used in CI/CD pipelines; no support for `--password-file` or structured output 3. **Security gaps** — `Scanner`-based password input echoes to terminal; no `--key-file` option forces private keys to be typed interactively or passed as command-line arguments (visible in `ps`, shell history) 4. **Module coupling** — the keystore library (`Wallet.java`, `WalletUtils.java`) lives in `framework` and calls `Args.getInstance()`, preventing reuse by `plugins` (Toolkit.jar) without pulling in the entire framework dependency chain ## Changes ### Commit 1: `refactor(crypto): extract keystore library from framework module` Extract the keystore package from `framework` to `crypto` module to break the framework dependency: | File | Change | |------|--------| | `Wallet.java` | Moved to `crypto/`, removed `Args` import, added `boolean ecKey` parameter to `decrypt()`, changed MAC comparison to constant-time `MessageDigest.isEqual()` | | `WalletUtils.java` | Moved to `crypto/`, removed `Args` import, added `boolean ecKey` parameter to `generateNewWalletFile()`, `generateFullNewWalletFile()`, `generateLightNewWalletFile()`, `loadCredentials()` | | `Credentials.java`, `WalletFile.java` | Moved to `crypto/` unchanged | | `WitnessInitializer.java` | Updated to pass `Args.getInstance().isECKeyCryptoEngine()` to `loadCredentials()` | | `KeystoreFactory.java` | Updated to pass `CommonParameter.getInstance().isECKeyCryptoEngine()` to keystore calls | | `plugins/build.gradle` | Added `implementation project(":crypto")` with exclusions (libp2p, prometheus, aspectj, httpcomponents) | | `CredentialsTest.java` | Merged two test files (fixed `keystroe` typo directory) into `crypto` module | | `WalletFileTest.java` | Moved to `crypto` module | ### Commit 2: `feat(plugins): add keystore new and import commands to Toolkit` Add picocli subcommands for the two core keystore operations: ```bash java -jar Toolkit.jar keystore new [--password-file ] [--keystore-dir ] [--json] [--sm2] java -jar Toolkit.jar keystore import --key-file [--password-file ] [--keystore-dir ] [--json] [--sm2] ``` **Security design:** - Interactive password input uses `Console.readPassword()` (no echo), with null check for EOF (Ctrl+D) - Password `char[]` compared directly via `Arrays.equals()` (avoids creating unnecessary String), zeroed in `finally` blocks - Password/key file `byte[]` zeroed after reading via `Arrays.fill(bytes, (byte) 0)` - Private key import reads from `--key-file` or interactive prompt, never from command-line arguments - Accepts `0x`-prefixed keys (common Ethereum format) - Keystore files set to 600 permissions via `Files.setPosixFilePermissions` - JSON output via `ObjectMapper.writeValueAsString()`, not string concatenation - `--sm2` flag for SM2 algorithm support **Shared utilities:** - `KeystoreCliUtils` — `readPassword()`, `ensureDirectory()` (uses `Files.createDirectories`), `setOwnerOnly()`, `printJson()` - `ensureDirectory()` uses `Files.createDirectories()` to avoid TOCTOU race conditions - `Toolkit.java` updated to register `Keystore.class` in subcommands **Test infrastructure:** - Ethereum standard test vectors (inline JSON from Web3 Secret Storage spec, pbkdf2 + scrypt) with known password/private key — verifies exact private key recovery - Dynamic format compatibility tests — generate keystore, serialize to file, deserialize, decrypt, verify Web3 Secret Storage structure + TRON address format - Property tests: 100 random encrypt/decrypt roundtrips + 2 standard scrypt roundtrips (with timeout) + 50 wrong-password rejection tests - CLI tests: password-file, invalid password, empty password, special-char password, custom directory, no-TTY error, JSON output, key-file, invalid key (short, non-hex), SM2, whitespace-padded key (with roundtrip verification), duplicate address import, dir-is-file ### Commit 3: `feat(plugins): add keystore list and update commands, deprecate --keystore-factory` ```bash java -jar Toolkit.jar keystore list [--keystore-dir ] [--json] java -jar Toolkit.jar keystore update

[--password-file ] [--keystore-dir ] [--json] [--sm2] ``` - `list`: scans directory for keystore JSON files, displays address + filename, skips non-keystore files. JSON serialization failure returns exit code 1. - `update`: decrypts with old password, re-encrypts with new password. Atomic file write (temp file + `Files.move(ATOMIC_MOVE)`) prevents corruption on interrupt. Wrong old password fails without modifying the file. Supports Windows line endings in password file. - `@Deprecated` annotation on `KeystoreFactory` class + deprecation warning in `start()` + migration notice in `help()` method - Backward compatibility test: `WitnessInitializerKeystoreTest` verifies new tool's keystore can be loaded by `WitnessInitializer.initFromKeystore()` ## Scope - Does NOT change any consensus or transaction processing logic - Does NOT modify protobuf definitions or public APIs - Does NOT break existing `localwitnesskeystore` config — `WitnessInitializer` continues to load keystore files at node startup - The `--keystore-factory` flag remains functional with a deprecation warning ## Test - Full project test suite passes (2300+ tests, 0 failures) - 14 crypto module tests (roundtrip property tests, Ethereum standard vectors, format compatibility, credentials, wallet file) - 26 plugins module tests (all 4 subcommands: success paths, error paths, JSON output, no-TTY, SM2, special chars, whitespace, duplicate, CRLF) - 2 new framework tests (deprecation warning, WitnessInitializer backward compat). Existing `WitnessInitializerTest` and `SupplementTest` updated for new signatures. - Regression: `WitnessInitializerTest`, `ArgsTest`, `SupplementTest` all pass - Manual verification: built Toolkit.jar, tested all 4 commands end-to-end - Checkstyle passes (`checkstyleMain` + `checkstyleTest`) - Security scanning: Semgrep (OWASP + secrets, 0 findings), FindSecBugs (0 new findings in new code) ### Cross-implementation compatibility | Source | Format | Result | |--------|--------|--------| | Ethereum spec vector (inline) | pbkdf2 c=262144 | Decrypt OK, private key exact match | | Ethereum spec vector (inline) | scrypt n=262144 | Decrypt OK, private key exact match | | java-tron (dynamic) | scrypt n=262144 | Roundtrip OK, TRON address verified | | java-tron (dynamic) | scrypt n=4096 | Roundtrip OK | ## Migration from --keystore-factory | Feature | Old `--keystore-factory` | New `Toolkit.jar keystore` | |---------|------------------------|--------------------------| | Create keystore | `GenKeystore` | `keystore new` | | Import private key | `ImportPrivateKey` | `keystore import` | | List keystores | Not supported | `keystore list` | | Change password | Not supported | `keystore update` | | Non-interactive mode | Not supported | `--password-file`, `--key-file` | | JSON output | Not supported | `--json` | | SM2 algorithm | Not supported | `--sm2` | | Custom directory | Not supported | `--keystore-dir` | | Password no-echo | No (echoed to terminal) | Yes (`Console.readPassword`) | | Script/CI friendly | No (interactive REPL) | Yes (single command, exit codes) | The old `--keystore-factory` remains functional with a deprecation warning during the transition period. ## Usage ```bash java -jar Toolkit.jar keystore [options] ``` ### Commands | Command | Description | |---------|-------------| | `new` | Generate a new keystore file with a random keypair | | `import` | Import an existing private key into a keystore file | | `list` | List all keystore files and addresses in a directory | | `update` | Change the password of an existing keystore file | ### Common Options | Option | Description | |--------|-------------| | `--keystore-dir ` | Keystore directory (default: `./Wallet`) | | `--json` | Output in JSON format for scripting | | `--password-file ` | Read password from file (non-interactive) | | `--sm2` | Use SM2 algorithm instead of ECDSA | | `--key-file ` | Read private key from file (`import` only) | ### Examples ```bash # Create a new keystore java -jar Toolkit.jar keystore new --password-file pw.txt # Import a private key java -jar Toolkit.jar keystore import --key-file key.txt --password-file pw.txt # List all keystores java -jar Toolkit.jar keystore list --keystore-dir ./Wallet # List in JSON format java -jar Toolkit.jar keystore list --json # Change password (password file: old password on line 1, new on line 2) java -jar Toolkit.jar keystore update

--password-file passwords.txt # Use SM2 algorithm java -jar Toolkit.jar keystore new --sm2 --password-file pw.txt ```