Skip to content

docs(wallet-cli): 从 wallet-cli 仓库命令文档 - #380

Merged
Benson0224 merged 10 commits into
tronprotocol:masterfrom
jizhen181-dot:wallet-cli
Sep 8, 2026
Merged

Benson0224 merged 10 commits into
tronprotocol:masterfrom
jizhen181-dot:wallet-cli

Conversation

@jizhen181-dot

Copy link
Copy Markdown
Contributor

将 tronprotocol/wallet-cli 仓库自带的用户文档(origin/develop @ 0190dab7) 完整迁移为中文,与英文源一一对应,共 153 篇:

index.md ← README.md
java/index.md ← java/README.md
java/{guide,concepts,commands,reference}/ 25 篇
typescript/index.md ← ts/README.md
typescript/{guide,concepts}/ 11 篇
typescript/commands/ 112 篇(20 个子目录)
typescript/{machine-interface,troubleshooting}.md

替换原有 12 篇手工合并的页面(java-cli.md、typescript-cli.md、
wallet-management.md 等),mkdocs.yml 导航整段重写。

其中 16 处技术表述与实际实现不符,已按源码修正(confirmed 表示已入块
而非已固化、not_found 超时属状态未知、--sign-only 仍需联网、--dry-run 仍调用 RPC、密码要求的例外、轮询脚本的退出码处理、tx broadcast 的
Synopsis、argv/环境变量措辞),依据均可在 ts/src 中核对。

jizhen181-dot and others added 4 commits August 28, 2026 14:20
将 tronprotocol/wallet-cli 仓库自带的用户文档(origin/develop @ 0190dab7)
完整迁移为中文,与英文源一一对应,共 153 篇:

  index.md                        ← README.md
  java/index.md                   ← java/README.md
  java/{guide,concepts,commands,reference}/   25 篇
  typescript/index.md             ← ts/README.md
  typescript/{guide,concepts}/    11 篇
  typescript/commands/            112 篇(20 个子目录)
  typescript/{machine-interface,troubleshooting}.md

替换原有 12 篇手工合并的页面(java-cli.md、typescript-cli.md、
wallet-management.md 等),mkdocs.yml 导航整段重写。

其中 16 处技术表述与实际实现不符,已按源码修正(confirmed 表示已入块
而非已固化、not_found 超时属状态未知、--sign-only 仍需联网、--dry-run
仍调用 RPC、密码要求的例外、轮询脚本的退出码处理、tx broadcast 的
Synopsis、argv/环境变量措辞),依据均可在 ts/src 中核对。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
wallet-cli 文档迁移进站后,两处介绍性文字仍指向 GitHub,且只描述了
Java 一种实现:

- getting_started/getting_started_with_javatron.md —— 补充两种实现的
  区别(Java 版交互式、通过 gRPC 连接节点;TypeScript 版通过 npm 安装、
  面向脚本、通过 FullNode HTTP 接口访问节点),并注明本指南使用 Java 版;
  文档链接改为站内的 Java CLI 环境准备。
- using_javatron/private_network.md —— 地址创建工具列表中的 wallet-cli
  改为站内链接,并说明两种实现。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
依据 tronprotocol/wallet-cli feat/v4.13.0(cc19d485)重新同步。该版本
在 TRON 之外新增 EVM 多链支持(以太坊、BNB Smart Chain),网络改用
CAIP-2 规范 id,原有名称保留为别名。

译文按 diff 增量更新,保留既有措辞与此前的人工校正。同时修正了若干
此前遗留的问题:

- RegisterWallet 示例不再把密码作为命令行参数(该写法会进入 shell 历史)
- vote-reward 的冻结金额与注释自相矛盾,且仍在使用占位地址
- stake-v1-legacy 的 ResourceCode 漏掉 2 TRON_POWER
- transfer-trc10 的 JSON 示例被截断
- 补全缺失的 EVM 示例,以及 gasfree 的 TIP-712(此前误作 EIP-712)
- 为被引用的中文标题补上显式锚点:中文标题的自动 slug 为空,
  相关跨页链接此前均会失效

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
统一书面语风格,并把行文中的 id 统一为 ID。仅调整措辞,未改动
任何技术含义、示例、字段名与错误码。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Comment thread docs/clients/wallet-cli/index.md Outdated
Comment thread docs/clients/wallet-cli/index.md Outdated
Comment thread docs/clients/wallet-cli/index.md Outdated
@vivian1912

Copy link
Copy Markdown
Contributor

This PR ultimately synchronizes wallet-cli documentation from feat/v4.13.0 @ cc19d485, not from develop; the earlier develop @ 0190dab7 import was superseded by the later sync commit. However, cc19d485 is an intermediate snapshot: the current release_v4.13.0 head is 82486420, 67 commits ahead, including user-visible CLI contract and documentation fixes such as EVM tx sign --out support and error-contract updates.
In addition, the latest package currently published on npm is still v4.12.0, while these pages describe unreleased v4.13-only functionality such as EVM support. Please synchronize from the final v4.13 release source and either coordinate publication of these pages with the v4.13 package release or clearly version/label them as unreleased. Otherwise, the main documentation site will describe commands that the install instructions do not provide, while also retaining behavior that is already stale relative to the release branch.

依据 tronprotocol/wallet-cli develop 分支(release_v4.13.0 已合入)重新
同步,较此前的 cc19d485 基线前进 67 个提交。源文档共 10 个文件发生变化:

- `import keystore` 不再拒绝重复地址:同一把密钥重复导入是幂等的
  (`status: "existing"`);若地址已由其他类型账户持有,则新增一个独立的
  `privateKey` 账户。`account_exists` 已从其退出码 1 清单中移除
- `tx sign --out` 现在在 EVM 上生效,写出已签名的 RLP,且结果体中仍保留 hex
- `--account <address>` 受所属链约束,跨链需用 accountId 或 label
- machine-interface 补充 errorCodes 的 exit / retry 元数据,以及新错误码
  `ambiguous_account`;其中说明了 retry 描述的是错误而非命令——提交路径上的
  超时可能发生在节点已受理之后,盲目重发会构成第二笔转账
- Java 网络推断改为只比对实际填写的端点
- 余额显示加千分位分隔符

另删除两个手写 index 页中的 [Agent skill] 链接:上游已删除
ts/skills/wallet-cli/SKILL.md,该链接已失效。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
jizhen181-dot added a commit to jizhen181-dot/documentation-en that referenced this pull request Sep 8, 2026
Review feedback on tronprotocol/documentation-zh#380, verified against
the wallet-cli sources and applied to both landing pages:

- the two implementations do NOT derive the same account set. Only the
  first account matches; Java increments the address index
  (m/44'/195'/0'/0/i) while TypeScript increments the account level
  (m/44'/195'/i'/0/0), so a wallet restored in the other CLI shows
  different addresses. Say so, and point at the recorded BIP44 path
- the Gradle project lives in java/, so ./gradlew has to run from
  wallet-cli/java, not the repo root
- RegisterWallet takes no password argument: Client.registerWallet()
  always prompts twice and then asks for the mnemonic length, so the
  old example both failed and printed a password in the clear
- config.conf is java/src/main/resources/config.conf

The review flagged these on index.md only; java/index.md carried the
same two quickstart defects and is fixed here too.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
jizhen181-dot and others added 4 commits September 8, 2026 14:27
依据 tronprotocol#380 的评审意见,已逐条到 wallet-cli
源码核实,并同时修正两个首页:

- 两种实现**并不会**派生出相同的账户集合。只有第一个账户相同:Java 递增的是
  地址索引(m/44'/195'/0'/0/i),TypeScript 递增的是 account 层级
  (m/44'/195'/i'/0/0),因此在另一个 CLI 中恢复钱包会看到不同的地址,
  但这并不是资金丢失。已改为明确提示,并要求迁移前核对 BIP44 路径
- Gradle 工程位于 java/ 子目录,./gradlew 必须在 wallet-cli/java 下执行,
  而不是仓库根目录
- RegisterWallet 不接受密码参数:Client.registerWallet() 始终两次提示输入
  密码,再询问助记词长度;原示例既跑不通,又把密码明文写在命令里
- config.conf 的完整路径是 java/src/main/resources/config.conf

评审只在 index.md 上标注,但 java/index.md 存在同样的两处快速上手缺陷,
一并修正。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
这三个手写页其实对应上游的 README.md、ts/README.md 和 java/README.md,
但它们不在 ts/docs、java/docs 下,同步比对从未覆盖,内容已经漂移。逐条
对照源码核实后校准:

- 交互式提示是一份白名单(create、各 import 子命令、backup、
  change-password、delete),而不是"仅敏感信息输入"——共三处
- Java 的 net.type 并不决定连接哪个网络,它只控制是否应用
  grpc.mainnet.apiKey;网络是从节点端点推断的
- config.conf 先在当前工作目录查找,找不到才回退到 JAR 内置资源
- Ledger 需要安装与所选家族对应的 app,而不是一律 TRON app
- create 的回执包含 Type 和 EVM 地址,并提示尽快执行 backup——原先全缺
- 示例网络在 TRON 上是 Nile,在 EVM 上是 Sepolia
- 查看用法是 help <command>,直接输入命令名并不会显示
- 首页导语与安装行补上 EVM 与 wallet-cli/java

已对照代码核实:Java 仅交互式(标准 CLI 在 4.13 中移除)、Trident 0.11.0、
node >=20、NetType 为 MAIN/NILE/SHASTA/CUSTOM、七个内置网络及其别名。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
"支持的链"一节的引言此前偏离了 ts/README.md,写成"TRON 使用 tron,
EVM 使用 eip155"——恰好断言了上游特意否认的那个等价关系。namespace
不等于链家族:eip155 是 CAIP-2 的 namespace,而 CLI 用于分支判断的
家族名是 evm,family_mismatch 和 chain.family 报的都是后者。现已按
上游原文改回。

表格仍保留别名版,而不是换成 README 的"家族 / 原生币"版:别名才是
读者实际要敲的东西,"原生币价值"一列则是资金安全提示。同时在每个
EVM 行的说明中补上币种符号,使 README 那张表独有的信息——ETH 还是
BNB——不至于丢失。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
这五处在上游 java/docs 原文中即为错误,经与上游维护者沟通后在此修正。
每一处都对照源码或本站自有的 TRON 机制文档核实过。

- ParticipateAssetIssue 的 Amount 是你支付的 TRX,而不是你收到的 token
  数量(TS 的 asset.ts 有明确说明)。只改 ParticipateAssetIssue 下的那处;
  TransferAsset 下同样的句子是正确的,保持不动。
- ExchangeTransaction 的 expected 是另一种 token 的最低到手量,而不是
  "必须小于 quant";代码中没有该校验,且两者币种不同、不可比较。
- 见证人注册费取自链参数 getAccountUpgradeCost,而非固定的 100_000 TRX。
- 创建账户燃烧的是 getCreateNewAccountFeeInSystemContract 激活费,同时
  消耗带宽;只有在质押或代理带宽不足时才按 getCreateAccountFee 燃烧,
  且每日免费带宽不能用于创建账户(见 mechanism-algorithm/account.md)。
- 带宽额度是全网带宽池中按质押占比分得的一份,是重新计算而非逐次累加;
  冻结天数只是锁定条件,不参与计算(见 mechanism-algorithm/resource.md)。
  同时删除"每个合约消耗 100_000 带宽"和"超过 10s 不消耗带宽"两处说法,
  它们与站内记载的每日约 600 免费带宽额度自相矛盾。

另外,资源页不再把普通转账、投票、冻结统称为"合约":这是 TRON 协议层
的术语用法,中文里会被读成"智能合约",且与质押指南中"智能合约调用消耗
能量而非带宽"的表述冲突。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@jizhen181-dot

Copy link
Copy Markdown
Contributor Author

Thanks for the review — all four points were valid. Each was verified against the wallet-cli sources rather than taken on faith, and all are now fixed.

  1. Cross-implementation derivation. Confirmed. ts/src/domain/family/index.ts sets indexAt: "account" (m/44'/195'/'/0/0), while SubAccount.java builds PATH_PREFIX + first + "'/0/" + second and defaults to incrementing the last segment (m/44'/195'/0'/0/i). Only account 0 matches. The claim that both derive the same accounts is removed; the page now states that the account stores are not interchangeable, gives both path templates, notes that a wallet restored in the other CLI shows different addresses rather than missing funds, and tells the reader to check the recorded BIP44 path before migrating.

  2. ./gradlew directory. Confirmed — the Gradle project is java/; there is no wrapper at the repo root. Fixed to cd wallet-cli/java && ./gradlew build && cd build/libs, both in the code block and in the install row of the comparison table.

  3. RegisterWallet. Confirmed — Client.registerWallet() takes no argument; it calls inputPassword2Twice(false) and then asks for the mnemonic length, so extra parameters are ignored. Fixed to bare RegisterWallet, annotated that it prompts twice for the password and then for the mnemonic length.

Points 2 and 3 were flagged on index.md; the same two defects were present in java/index.md, so both files are fixed, in the English and Chinese trees.

  1. Sync source and release timing. Both concerns are resolved. The branch is re-synced from develop @ 3960316e (release_v4.13.0 merged), which contains 82486420 and the follow-ups you named — EVM tx sign --out, the error-contract changes (errorCodes exit/retry metadata, ambiguous_account), idempotent import keystore, and the broadened invalid_node_response. On publication timing: @tron-walletcli/wallet-cli@4.13.0 was published to npm on 2026-09-04T12:07Z, about eight hours after your comment, and is now dist-tags.latest. The install instructions and the documented feature set therefore agree, so no "unreleased" labelling is needed.

Comment thread docs/clients/wallet-cli/java/guide/getting-started.md Outdated
Comment thread docs/clients/wallet-cli/typescript/machine-interface.md Outdated
Comment thread docs/clients/wallet-cli/java/commands/exchange.md Outdated
- java/guide/getting-started.md 重复了创建账户那段,且仍写死 1 TRX。
  现改为不再重述数字,指向已修正的 commands/account.md——那里已说明
  激活费与带宽费都是可经治理提案修改的链参数。
- typescript/machine-interface.md 的退出码 2 表格里 migration_required
  出现两次,删掉其中信息量较少的那条。
- java/commands/exchange.md 链接的 mechanism-algorithm/dex.md 已被上游
  在 5fcebec 中删除。这里选择移除链接而非改指他处:system-contracts.md
  只列出 Exchange 的 protobuf 字段,并不解释该句所指的 Bancor 定价模型。

dex 链接在我们自己的分支上是可解析的(分支基线仍带该文件),只有合并
目标分支后才会失效,因此历次本地链接检查全部通过。现已补充对
`upstream/master` 的跨目录链接校验;另外两个链接在上游 master 中仍然存在。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@jizhen181-dot

Copy link
Copy Markdown
Contributor Author

All three confirmed and fixed.

  1. Duplicate account-creation paragraph in java/guide/getting-started.md. You're right — I corrected commands/account.md last round and did not sweep for the same claim elsewhere. The paragraph now defers to that page instead of restating a number: it says an activation fee is burned and bandwidth is consumed, that both are governance-controlled chain parameters rather than fixed amounts, and links to commands/account.md#how-to-create-account.

  2. Duplicated migration_required. Removed. The exit-2 table listed it twice; the shorter of the two entries is dropped, and the one that explains the master-password condition is kept. Both trees now list it once.

  3. Dead mechanism-algorithm/dex.md link. Confirmed — the file was removed upstream in 5fcebec Remove obsolete documentation files, and mechanism-algorithm/ on master no longer contains it. I checked whether the link could be repointed instead: system-contracts.md has sections for the Exchange contracts, but they are protobuf field listings and do not explain the Bancor pricing the sentence refers to. So the link is removed and the Bancor statement kept, as you suggested.

This one is worth calling out as a process gap on my side rather than a one-off. The link resolved fine against this branch, whose base still carries dex.md, so every link check I ran passed; it only breaks once the target branch is merged. I've added validation of cross-tree links against upstream/master — the only other two, mechanism-algorithm/resource.md and using_javatron/installing_javatron.md, both survive there, so this was the only occurrence.

I also swept for siblings of 1 and 2 rather than fixing just the reported instances: no other table in either tree repeats a row key, and the remaining 1 TRX / 0.1 TRX occurrences are unit definitions (1 TRX = 1,000,000 SUN) or console output samples, not rules stated as fixed amounts.

@Benson0224
Benson0224 merged commit 0cc2e65 into tronprotocol:master Sep 8, 2026
abn2357 added a commit to abn2357/documentation-zh that referenced this pull request Sep 8, 2026
Rebuild the gh-pages site to publish Chinese documentation updates merged into master after the previous rebuild (tronprotocol#375), ordered by merge time.

Included PRs:
- tronprotocol#373 remove obsolete documentation files
- tronprotocol#377 align module structure with java-tron v4.8.2
- tronprotocol#378 clarify dependency verification guidance
- tronprotocol#372 add node logging documentation
- tronprotocol#374 add separate CI workflow documentation based on v4.8.2
- tronprotocol#381 align docs with java-tron v4.8.2.1
- tronprotocol#380 migrate the full wallet-cli command documentation from the wallet-cli repository

Adds new generated Chinese documentation sections:
- using_javatron/logging/ for the Node Logging guide
- developers/workflows/ for the java-tron CI workflow reference
- clients/wallet-cli/java/ and clients/wallet-cli/typescript/ for the full wallet-cli documentation

Removes obsolete and replaced pages, and refreshes sitemap.xml, sitemap.xml.gz, search/search_index.json, docs-manifest.json, and revision dates.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants