Release v4.16.0

.gitignore

@@ -27,4 +27,7 @@ ts/.npmrc
 .codex/
 
 # MCP
-.mcp.json
+.mcp.json
+
+# Team working files (status, briefs, handoffs); local only
+.team/

.graphifyignore

@@ -0,0 +1,33 @@
+# Generated code and build/dependency output obscure the handwritten code graph.
+java/src/main/gen/
+java/src/gen/
+node_modules/
+build/
+dist/
+bin/
+.gradle/
+coverage/
+graphify-out/
+
+# Generated fixtures, dependency locks, and architecture drawing data.
+**/__snapshots__/
+**/package-lock.json
+**/yarn.lock
+**/pnpm-lock.yaml
+ts/.dependency-cruiser-known-violations.json
+ts/eslint-suppressions.json
+ts/docs/
+java/docs/
+
+# Local agent state and wallet data are outside the source graph.
+.claude/
+.codex/
+.agents/
+.superpowers/
+.team/
+.private/
+.mcp.json
+Wallet/
+Mnemonic/
+wallet_data/
+.wallet-cli/

AGENTS.md

@@ -0,0 +1,6 @@
+# AGENTS.md
+
+Read `CLAUDE.md` for the repository layout, build, and test commands.
+
+Before changing anything under `ts/`, read every file in `ts/docs/dev/rules/`. Those rules are the single
+source of truth for the TypeScript architecture and comment style.

CLAUDE.md

@@ -6,20 +6,37 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 The repository holds two independent implementations:
 
-- `java/` — the original REPL-first implementation, described by the rest of this file.
-- `ts/` — the agent-first TypeScript rewrite (npm package `@tron-walletcli/wallet-cli`). See the
-  **TypeScript Implementation** section below and `ts/README.md`.
-
-Everything below (except the TypeScript Implementation section) refers to the Java implementation.
-**All Java paths are relative to `java/`, and all Java commands are run from that directory**
-(`cd java` first).
-
-## TypeScript Implementation
-
-The `ts/` package is a self-contained, agent-first CLI (Node.js 22.23.4+ / 24.22.1+ / 26.12.1+, ESM, TypeScript). Every command
-has a stable JSON envelope, deterministic exit codes, and discoverable schemas; interactive prompts
-are used only for secret input (create / import / backup / delete). **All `ts/` commands run from the
-`ts/` directory.**
+- `ts/` — the agent-first TypeScript rewrite (npm package `@tron-walletcli/wallet-cli`). See
+  [TypeScript](#typescript-ts) and `ts/README.md`.
+- `java/` — the original REPL-first implementation. See [Java](#java-java).
+
+## Graphify
+
+Use the local code graph when you need to explore: where a symbol is used, how a flow passes through modules,
+or what a change affects. Query it with
+`bash scripts/graphify.sh query "<symbol or question>" --budget 1200` from the repository root.
+Use this wrapper to select the project's pinned Graphify version and disable LLM backends. When you already
+know the file and lines, or need every occurrence of a string, use source search instead.
+
+- Initial setup: `bash scripts/graphify.sh setup` (requires `uv` and Python 3.13).
+- Refresh only before a query, when the graph may be stale (a new session, a branch change, or code edits since
+  the last refresh): `bash scripts/graphify.sh refresh`. Extraction reuses unchanged files. If refresh fails,
+  say the graph is stale and use source search.
+- From `ts/` or `java/`, use `bash ../scripts/graphify.sh` with the same arguments. The wrapper changes
+  to the repository root and updates the shared graph for both implementations.
+- View `graphify-out/graph.html` for communities or `graphify-out/GRAPH_TREE.html` for symbols by file;
+  query data is in `graphify-out/graph.json` and the summary is in
+  `graphify-out/GRAPH_REPORT.md`. These generated files and the local Python environment are git-ignored.
+- The scan covers code and tests in both implementations; `.graphifyignore` excludes generated code,
+  snapshots, build output, and local state. Document semantics are outside this code-only graph.
+- Confirm graph findings in source, especially port-to-adapter wiring in `ts/src/bootstrap/composition.ts`.
+  Architecture rules and automated checks remain authoritative. If Graphify is unavailable, use source search.
+
+## TypeScript (`ts/`)
+
+A self-contained, agent-first CLI (Node.js 22.23.4+ / 24.22.1+ / 26.12.1+, ESM, TypeScript). Every command has a
+stable JSON envelope, deterministic exit codes, and discoverable schemas; interactive prompts are used only for
+secret input (create / import / backup / delete). **All `ts/` commands run from the `ts/` directory.**
 
 ```bash
 cd ts
@@ -28,50 +45,56 @@ npm run build          # bundle to dist/ via tsup (bin: wallet-cli -> dist/index
 npm run dev -- <args>  # run from source via tsx (e.g. npm run dev -- create --label main)
 npm test               # vitest (tests are co-located as *.test.ts)
 npm run typecheck      # tsc --noEmit
-npm run depcruise      # dependency-cruiser — enforces the architecture rules below
+npm run depcruise      # dependency-cruiser — enforces the layer rules
+npm run lint           # ESLint, with known violations suppressed
 ```
 
-### Architecture (hexagonal / ports & adapters)
-
-Dependencies point inward, and the table below is the rule — read it before changing boundaries,
-ports, or command routing. `depcruise` enforces it in CI (`ts/.dependency-cruiser.cjs`).
-`ts/docs/machine-interface.md` is the source of truth for the JSON contract (envelope, exit codes,
-stdout/stderr discipline).
-
-| Area (`ts/src/…`) | Role | May depend on | Must NOT depend on |
-|---|---|---|---|
-| `domain` | Pure rules & values, zero I/O (address, amounts, derivation, wallet, family, errors) | Node / pure libs only | application, adapters, bootstrap |
-| `application` | Use cases, services, contracts, and **ports** (interfaces it owns) | `domain` | adapters, bootstrap |
-| `adapters/inbound` | CLI driving side — parse argv, route to use cases, render output | application, domain | adapters/outbound, bootstrap |
-| `adapters/outbound` | Implements application ports — keystore, TronWeb/Tron gateway, Ledger, price, config, persistence | application ports, domain | adapters/inbound, bootstrap |
-| `bootstrap` | Composition root + process lifecycle (`runner.ts`, `composition.ts`, `argv.ts`, `families/`) | all areas | — (assembly only) |
-
-Key points:
-- **Ports live in `application/ports/`** (e.g. `wallet-repository`, `tron-gateway`, `ledger-device`,
-  `price-provider`); outbound adapters implement them (dependency inversion). Shared transaction input types live in
-  `application/contracts/`; ports must not import use cases or services (`ports-are-innermost`).
-- **Chain-family differences** are isolated per family — `application/use-cases/<family>/`,
-  `adapters/outbound/chain/<family>/`, and the family plugin under `bootstrap/families/`. Both
-  `tron` and `evm` are registered unconditionally (`bootstrap/composition.ts`) and reachable: the
-  builtin networks and aliases cover ETH, Sepolia, BSC, BSC testnet, Base and Base Sepolia alongside the TRON three.
-  There is no family-level feature gate. EVM simply binds a narrower command set (30 bindings:
-  account, block, chain, tx, token, contract, message/typed-data signing, `bai recharge` and eight ERC-8004 identity commands) against TRON's 96, which adds
-  stake, permission, proposal, asset, GasFree, TronLink multisig, and the SunSwap and SunPump groups (17 commands).
-  The counts are the `families` tags in `wallet-cli --json-schema`.
-- **A single Zod schema per command** drives validation, yargs arity, help text, and JSON Schema.
-- **Secrets** (private keys, mnemonics, BIP39 passphrases) are encrypted at rest and never accepted
-  from argv or env — only a dedicated stdin channel or hidden TTY prompt.
-
-### Adding a TypeScript command
+`npm run depcruise` uses `ts/.dependency-cruiser-known-violations.json` and fails on new violations or
+stale/duplicate baseline entries. After fixing a known violation or enabling a rule with existing violations,
+run `npm run depcruise:baseline` from `ts/`, review the exact entries added or removed, and rerun
+`npm run depcruise`. Commit the baseline diff with the corresponding code or rule change. Regeneration records
+all current violations; fix unintended new violations before regenerating. To see unsuppressed diagnostics,
+run `npx --no-install depcruise src`.
+
+`npm run lint` uses `ts/eslint-suppressions.json`, ESLint's bulk suppressions file, which records a violation
+count per file and rule. It fails when a count rises, when it falls (the entry stays until regeneration), and
+on an entry for a file that is deleted, git-ignored, or ignored by ESLint (including `--ignore-pattern`).
+Keys must use ESLint's relative POSIX paths, such as `src/example.ts`; aliases such as `./src/example.ts` fail.
+Counts are compared, not locations, so fixing one violation and adding another of the same rule in the same
+file passes. After fixing a known
+violation or enabling a rule with existing violations, run `npm run lint:baseline` from `ts/`, review the exact
+entries added or removed, and rerun `npm run lint`; commit the diff as for depcruise. Pass the same
+`--ignore-pattern` options to both commands, for example for local git-ignored directories. To see the suppressed
+diagnostics, run `npx --no-install eslint . --format json` and read each file's `suppressedMessages`.
+Boolean ignore options use the last setting: `--ignore` or `--no-ignore`, optionally followed by `=true`
+or `=false`. The lint wrapper rejects other assignment values, including whitespace-padded booleans.
+
+Local ESLint rules live in `ts/eslint-rules/`; their tests in `ts/test/lint/rules/` run with
+`npm run test:unit`. The baseline can include test and tooling files. The npm-script integration suite
+`ts/test/lint/suppressions.test.ts` remains separate from these rule tests.
+
+### Development rules
+
+The rules for `ts/` are in `ts/docs/dev/rules/`. They are the single source of truth; do not restate them here.
+
+@ts/docs/dev/rules/architecture.md
+@ts/docs/dev/rules/comments.md
+
+Which commands each chain family supports: the `families` tags in `wallet-cli --json-schema`.
+
+### Adding a command
 
 1. Add the command module under `adapters/inbound/cli/commands/` with its Zod schema.
-2. Route it to an application use case (`application/use-cases/…`, e.g. `tron/transaction-service.ts`);
-   do not put I/O or chain logic in the inbound layer.
-3. If it needs new I/O, define a **port** in `application/ports/` and implement it in
-   `adapters/outbound/`. Wire it in `bootstrap/composition.ts`.
+2. Route it to an application use case under `application/use-cases/`.
+3. If it needs new I/O, define a port in `application/ports/`, implement it in `adapters/outbound/`, and wire
+   it in `bootstrap/composition.ts`.
 4. Add co-located `*.test.ts` and run `npm run depcruise && npm run typecheck && npm test`.
 
-## Build & Run
+## Java (`java/`)
+
+**All Java paths are relative to `java/`, and all Java commands are run from that directory** (`cd java` first).
+
+### Build & Run
 
 ```bash
 # Build the project (generates protobuf sources into src/main/gen/)
@@ -96,7 +119,7 @@ Key points:
 
 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`.
 
-## End-to-end coverage
+### End-to-end coverage
 
 `java/qa-repl/` drives the real interactive shell over a pty (`expect`) against a
 funded Nile account — wallet lifecycle, account queries, a signed 1 TRX transfer, and
@@ -110,11 +133,11 @@ cd java
 ./qa-repl/cli-boundary.sh build/libs/wallet-cli.jar    # entry point takes only --version/--help
 ```
 
-## Architecture
+### 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.
 
-### One CLI Mode
+#### One CLI Mode
 
 **Interactive REPL** — `Client` class with JCommander `@Parameters` inner classes. Entry point:
 `org.tron.walletcli.Client`. Features tab completion, interactive prompts, and conversational
@@ -125,20 +148,20 @@ The shell is started one way only: a bare `java -jar wallet-cli.jar`. The entry
 TypeScript CLI on stderr and exits 2. Non-interactive, scriptable and CI use belongs to `ts/`
 (npm `@tron-walletcli/wallet-cli`).
 
-### Request Flow
+#### Request Flow
 
 ```
 User Input → Client (JCommander) → WalletApiWrapper → WalletApi → Trident SDK → gRPC → TRON Node
 ```
 
-### Key Classes
+#### Key Classes
 
 - **`org.tron.walletcli.Client`** — REPL entry point and command dispatcher. Each command is a JCommander `@Parameters` inner class.
 - **`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).
 
-### Package Organization
+#### Package Organization
 
 | Package | Purpose |
 |---------|---------|
@@ -152,13 +175,13 @@ User Input → Client (JCommander) → WalletApiWrapper → WalletApi → Triden
 | `multi` | Multi-signature transaction handling |
 | `gasfree` | GasFree transaction API (transfer tokens without gas) |
 
-### Configuration
+#### 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
+#### Key Frameworks & Libraries
 
 - **Trident SDK 0.11.0** — All gRPC API calls to TRON nodes
 - **JCommander 1.82** — CLI argument parsing (interactive REPL)

java/AGENTS.md

@@ -0,0 +1,4 @@
+# Java agent instructions
+
+Read [the repository instructions](../AGENTS.md) and [the local instructions](CLAUDE.md), including
+the Graphify usage and refresh requirements, before working in this directory.

java/CLAUDE.md

@@ -0,0 +1,16 @@
+# Java agent instructions
+
+Read [the repository instructions](../CLAUDE.md) for build commands and the shared Graphify workflow.
+
+## Graphify
+
+Follow the [Graphify refresh requirements](../CLAUDE.md#graphify) when modifying code or tests here.
+From `java/`, use:
+
+```bash
+bash ../scripts/graphify.sh query "WalletApiWrapper" --budget 1200
+bash ../scripts/graphify.sh explain WalletApi
+bash ../scripts/graphify.sh refresh
+```
+
+The wrapper uses the shared repository graph at `../graphify-out/`.

scripts/graphify.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$repo_root"
+graphify_python="$repo_root/graphify-out/.venv/bin/python"
+graphify_cli="$repo_root/graphify-out/.venv/bin/graphify"
+export GRAPHIFY_BACKEND=none
+
+case "${1:-help}" in
+  setup)
+    if [[ ! -x "$graphify_python" ]]; then
+      uv venv --python 3.13 graphify-out/.venv
+    fi
+    uv pip install --python "$graphify_python" 'graphifyy==0.9.97'
+    ;;
+  refresh)
+    if [[ ! -x "$graphify_cli" ]]; then
+      echo 'Run bash scripts/graphify.sh setup first.' >&2
+      exit 1
+    fi
+    "$graphify_cli" extract . --code-only --max-workers 4
+    "$graphify_cli" cluster-only .
+    "$graphify_cli" tree --root . --label wallet-cli
+    ;;
+  help|--help|-h)
+    echo 'Usage: bash scripts/graphify.sh setup|refresh|<graphify command> [args...]'
+    echo 'Examples: query "MessageSigner" --budget 1200; explain "TronGridHistoryReader"'
+    ;;
+  *)
+    if [[ ! -x "$graphify_cli" ]]; then
+      echo 'Run bash scripts/graphify.sh setup first.' >&2
+      exit 1
+    fi
+    exec "$graphify_cli" "$@"
+    ;;
+esac

ts/.dependency-cruiser-known-violations.json

@@ -0,0 +1,35 @@
+[
+  {
+    "type": "dependency",
+    "from": "src/adapters/outbound/x402/gasfree-errors.test.ts",
+    "to": "@bankofai/x402-tron/gasfree/client",
+    "unresolvedTo": "@bankofai/x402-tron/gasfree/client",
+    "dependencyTypes": ["unknown"],
+    "rule": {
+      "severity": "error",
+      "name": "x402-payment-modules-only-in-payment-client"
+    }
+  },
+  {
+    "type": "dependency",
+    "from": "src/adapters/outbound/x402/gasfree-errors.test.ts",
+    "to": "node_modules/@bankofai/x402-fetch/dist/cjs/index.js",
+    "unresolvedTo": "@bankofai/x402-fetch",
+    "dependencyTypes": ["npm-dev", "import"],
+    "rule": {
+      "severity": "error",
+      "name": "x402-payment-modules-only-in-payment-client"
+    }
+  },
+  {
+    "type": "dependency",
+    "from": "src/adapters/outbound/x402/nile-settlement.test.ts",
+    "to": "@bankofai/x402-tron/exact/facilitator",
+    "unresolvedTo": "@bankofai/x402-tron/exact/facilitator",
+    "dependencyTypes": ["unknown"],
+    "rule": {
+      "severity": "error",
+      "name": "x402-payment-modules-only-in-payment-client"
+    }
+  }
+]