This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
The repository holds two independent implementations:
ts/— the agent-first TypeScript rewrite (npm package@tron-walletcli/wallet-cli). See TypeScript andts/README.md.java/— the original REPL-first implementation. See Java.
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(requiresuvand 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/orjava/, usebash ../scripts/graphify.shwith the same arguments. The wrapper changes to the repository root and updates the shared graph for both implementations. - View
graphify-out/graph.htmlfor communities orgraphify-out/GRAPH_TREE.htmlfor symbols by file; query data is ingraphify-out/graph.jsonand the summary is ingraphify-out/GRAPH_REPORT.md. These generated files and the local Python environment are git-ignored. - The scan covers code and tests in both implementations;
.graphifyignoreexcludes 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.
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.
cd ts
npm ci # install
npm run build # bundle to dist/ via tsup (bin: wallet-cli -> dist/index.js)
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 layer rules
npm run lint # ESLint, with known violations suppressednpm 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.
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.
- Add the command module under
adapters/inbound/cli/commands/with its Zod schema. - Route it to an application use case under
application/use-cases/. - If it needs new I/O, define a port in
application/ports/, implement it inadapters/outbound/, and wire it inbootstrap/composition.ts. - Add co-located
*.test.tsand runnpm run depcruise && npm run typecheck && npm test.
All Java paths are relative to java/, and all Java commands are run from that directory (cd java first).
# Build the project (generates protobuf sources into src/main/gen/)
./gradlew build
# Build fat JAR (output: build/libs/wallet-cli.jar)
./gradlew shadowJar
# Run the interactive shell (the only way to run it)
./gradlew run
# Or after building: java -jar build/libs/wallet-cli.jar
# Run tests
./gradlew test
# Run a single test class
./gradlew test --tests "org.tron.keystore.StringUtilsTest"
# Clean (also removes src/main/gen/)
./gradlew cleanJava 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.
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
the not-logged-in guards. ./gradlew build passing does not mean the shell still
works, so run it whenever you touch shared helpers:
cd java
./gradlew shadowJar
./qa-repl/run.sh build/libs/wallet-cli.jar head # REPL regression
./qa-repl/cli-boundary.sh build/libs/wallet-cli.jar # entry point takes only --version/--helpThis is a TRON blockchain CLI wallet built on the Trident SDK. It communicates with TRON nodes via gRPC.
Interactive REPL — 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 (~4800 lines).
The shell is started one way only: a bare java -jar wallet-cli.jar. The entry point recognises
--version and --help and nothing else; any other argument prints a one-line pointer to the
TypeScript CLI on stderr and exits 2. Non-interactive, scriptable and CI use belongs to ts/
(npm @tron-walletcli/wallet-cli).
User Input → Client (JCommander) → WalletApiWrapper → WalletApi → Trident SDK → gRPC → TRON Node
org.tron.walletcli.Client— REPL entry point and command dispatcher. Each command is a JCommander@Parametersinner 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 | Purpose |
|---|---|
walletcli |
REPL entry point, API wrapper |
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) |
- 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— usesloggeras the log field name (not the defaultlog)
- Trident SDK 0.11.0 — All gRPC API calls to TRON nodes
- JCommander 1.82 — CLI argument parsing (interactive REPL)
- JLine 3.25.0 — Interactive terminal/readline
- BouncyCastle — Cryptographic operations
- Protobuf 3.25.8 / gRPC 1.75.0 — Protocol definitions and transport
- Lombok —
@Getter,@Setter,@Slf4jetc. (annotation processing)