Merge pull request #927 from tronprotocol/release_v4.9.5

Release v4.9.5

Author: gummy789j

.github/workflows/build-artifact.yml

@@ -0,0 +1,60 @@
+name: Build Artifact
+
+on:
+  push:
+    branches:
+      - "release_*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build wallet-cli artifact
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "8"
+          cache: gradle
+
+      - name: Build
+        run: ./gradlew clean build shadowJar shadowDistZip
+
+      - name: Package artifacts
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          version="${GITHUB_REF_NAME#release_}"
+          if [ "$version" = "$GITHUB_REF_NAME" ]; then
+            version="dev"
+          fi
+
+          artifact_dir="artifacts"
+          artifact_base="wallet-cli-${version}-rc.${GITHUB_RUN_NUMBER}"
+          artifact_name="wallet-cli-artifact-${GITHUB_REF_NAME}"
+
+          mkdir -p "$artifact_dir"
+          cp build/libs/wallet-cli.jar "$artifact_dir/${artifact_base}.jar"
+          cp build/distributions/*shadow*.zip "$artifact_dir/${artifact_base}.zip"
+          git rev-parse HEAD > "$artifact_dir/git-sha.txt"
+          echo "ARTIFACT_NAME=${artifact_name}" >> "$GITHUB_ENV"
+
+          (
+            cd "$artifact_dir"
+            shasum -a 256 "${artifact_base}.jar" "${artifact_base}.zip" git-sha.txt > checksums.txt
+          )
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ env.ARTIFACT_NAME }}
+          path: artifacts/*

.gitignore

@@ -1,3 +1,4 @@
+.claude/settings.local.json 
 .DS_Store
 build
 out
@@ -11,4 +12,27 @@ src/gen
 tools
 src/main/resources/static/js/tronjs/tron-protoc.js
 logs
+docs
+!docs/
+!docs/standard-cli-contract-spec.md
 FileTest
+bin
+
+# Wallet keystore files created at runtime
+Wallet/
+Mnemonic/
+wallet_data/
+
+# QA runtime output
+qa/results/
+qa/runtime/
+qa/report.txt
+qa/.verify.lock/
+
+# claude
+.claude/
+
+.private/
+
+# graphify 
+graphify-out/

CLAUDE.md

@@ -0,0 +1,124 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build & Run
+
+```bash
+# Build the project (generates protobuf sources into src/main/gen/)
+./gradlew build
+
+# Build fat JAR (output: build/libs/wallet-cli.jar)
+./gradlew shadowJar
+
+# Run in REPL 交互模式 (human-friendly, interactive prompts)
+./gradlew run
+# Or after building: java -jar build/libs/wallet-cli.jar
+
+# Run in standard CLI mode (non-interactive, scriptable)
+java -jar build/libs/wallet-cli.jar --network nile get-account --address TXyz...
+java -jar build/libs/wallet-cli.jar --output json --network nile get-account --address TXyz...
+
+# Run tests
+./gradlew test
+
+# Run a single test class
+./gradlew test --tests "org.tron.keystore.StringUtilsTest"
+
+# Clean (also removes src/main/gen/)
+./gradlew clean
+```
+
+Java 8 source/target compatibility. Protobuf sources are in `src/main/protos/` and generate into `src/main/gen/` — this directory is git-tracked but rebuilt on `clean`.
+
+## QA Verification
+
+The `qa/` directory contains shell-based parity tests that compare interactive REPL output vs standard CLI (text and JSON modes). Requires a funded Nile testnet account.
+
+```bash
+# Run QA verification (needs TRON_TEST_PRIVATE_KEY env var for private key)
+TRON_TEST_PRIVATE_KEY=<nile-private-key> bash qa/run.sh verify
+
+# QA config is in qa/config.sh; test commands are in qa/commands/*.sh
+# MASTER_PASSWORD env var is used for keystore auto-login (default: testpassword123A)
+```
+
+## Architecture
+
+This is a **TRON blockchain CLI wallet** built on the [Trident SDK](https://github.com/tronprotocol/trident). It communicates with TRON nodes via gRPC.
+
+### Two CLI Modes
+
+1. **REPL 交互模式** (human-friendly) — `Client` class with JCommander `@Parameters` inner classes. Entry point: `org.tron.walletcli.Client`. Features tab completion, interactive prompts, and conversational output. This is the largest file (~4700 lines). Best for manual exploration and day-to-day wallet management by humans.
+2. **Standard CLI 模式** (AI-agent-friendly) — `StandardCliRunner` with `CommandRegistry`/`CommandDefinition` pattern in `org.tron.walletcli.cli.*`. Supports `--output json`, `--network`, `--quiet` flags. Commands are registered in `cli/commands/` classes (e.g., `WalletCommands`, `TransactionCommands`, `QueryCommands`). Designed for automation: deterministic exit codes, structured JSON output, no interactive prompts, and env-var-based authentication — ideal for AI agents, scripts, and CI/CD pipelines.
+
+The standard CLI suppresses all stray stdout/stderr in JSON mode to ensure machine-parseable output. Authentication is automatic via `MASTER_PASSWORD` env var + keystore files in `Wallet/`.
+
+### Standard CLI Contract
+
+Before changing parser behavior, auth flow, JSON output, command success/failure semantics, or `qa/` expectations for
+the standard CLI, read:
+
+- `docs/standard-cli-contract-spec.md`
+
+Treat that file as the source of truth for the standard CLI contract unless the repository owner explicitly decides to
+revise it.
+
+### Request Flow
+
+```
+# Standard CLI mode:
+User Input → GlobalOptions → StandardCliRunner → CommandRegistry → CommandHandler → WalletApiWrapper → WalletApi → Trident SDK → gRPC → TRON Node
+
+# Interactive REPL mode:
+User Input → Client (JCommander) → WalletApiWrapper → WalletApi → Trident SDK → gRPC → TRON Node
+```
+
+### Key Classes
+
+- **`org.tron.walletcli.Client`** — Legacy REPL entry point and CLI command dispatcher. Each command is a JCommander `@Parameters` inner class.
+- **`org.tron.walletcli.cli.StandardCliRunner`** — New standard CLI executor. Handles network init, auto-authentication, JSON stream suppression, and command dispatch.
+- **`org.tron.walletcli.cli.CommandRegistry`** — Maps command names/aliases to `CommandDefinition` instances. Supports fuzzy suggestion on typos.
+- **`org.tron.walletcli.cli.CommandDefinition`** — Immutable command metadata (name, aliases, options, handler). Built via fluent `Builder` API.
+- **`org.tron.walletcli.cli.OutputFormatter`** — Formats output as text or JSON. In JSON mode, wraps results in `{"success":true,"data":...}` envelope.
+- **`org.tron.walletcli.WalletApiWrapper`** — Orchestration layer between CLI and core wallet logic. Handles transaction construction, signing, and broadcasting.
+- **`org.tron.walletserver.WalletApi`** — Core wallet operations: account management, transaction creation, proposals, asset operations. Delegates gRPC calls to Trident.
+- **`org.tron.walletcli.ApiClientFactory`** — Creates gRPC client instances for different networks (mainnet, Nile testnet, Shasta testnet, custom).
+
+### Adding a New Standard CLI Command
+
+1. Create or extend a class in `cli/commands/` (e.g., `TransactionCommands.java`)
+2. Build a `CommandDefinition` via `CommandDefinition.builder()` with name, aliases, options, and handler
+3. Register it in the appropriate `register(CommandRegistry)` method
+4. The handler receives `(ParsedOptions, WalletApiWrapper, OutputFormatter)` — use `formatter.success()/error()` for output
+
+### Package Organization
+
+| Package | Purpose |
+|---------|---------|
+| `walletcli` | CLI entry points, API wrapper |
+| `walletcli.cli` | Standard CLI framework: registry, definitions, options, formatter |
+| `walletcli.cli.commands` | Standard CLI command implementations by domain |
+| `walletserver` | Core wallet API and gRPC communication |
+| `common` | Crypto utilities, encoding, enums, shared helpers |
+| `core` | Configuration, data converters, DAOs, exceptions, managers |
+| `keystore` | Wallet file encryption/decryption, key management |
+| `ledger` | Ledger hardware wallet integration via HID |
+| `mnemonic` | BIP39 mnemonic seed phrase support |
+| `multi` | Multi-signature transaction handling |
+| `gasfree` | GasFree transaction API (transfer tokens without gas) |
+
+### Configuration
+
+- **Network config:** `src/main/resources/config.conf` (HOCON format via Typesafe Config)
+- **Logging:** `src/main/resources/logback.xml` (Logback, INFO level console + rolling file)
+- **Lombok:** `lombok.config` — uses `logger` as the log field name (not the default `log`)
+
+### Key Frameworks & Libraries
+
+- **Trident SDK 0.10.0** — All gRPC API calls to TRON nodes
+- **JCommander 1.82** — CLI argument parsing (REPL 交互模式)
+- **JLine 3.25.0** — Interactive terminal/readline
+- **BouncyCastle** — Cryptographic operations
+- **Protobuf 3.25.5 / gRPC 1.60.0** — Protocol definitions and transport
+- **Lombok** — `@Getter`, `@Setter`, `@Slf4j` etc. (annotation processing)

build.gradle

@@ -130,6 +130,10 @@ protobuf {
     }
 }
 
+tasks.named("processResources") {
+    dependsOn tasks.named("generateProto")
+}
+
 clean.doFirst {
     delete "src/main/gen"
 }
@@ -146,3 +150,19 @@ shadowJar {
     version = null
     mergeServiceFiles() //  https://github.com/grpc/grpc-java/issues/10853
 }
+
+task qaJar(type: Jar, dependsOn: [shadowJar, testClasses]) {
+    from zipTree(shadowJar.archiveFile)
+    from sourceSets.test.output
+    archiveBaseName.set('wallet-cli-qa')
+    archiveClassifier.set('')
+    archiveVersion.set('')
+    duplicatesStrategy = DuplicatesStrategy.EXCLUDE
+}
+
+task qaRun(type: JavaExec) {
+    classpath = sourceSets.test.runtimeClasspath
+    mainClass = 'org.tron.qa.QARunner'
+    args = project.hasProperty('qaArgs') ? project.property('qaArgs').split(' ') : ['list']
+    standardInput = System.in
+}