From c21eacf2ab9d728104f129b83e6c2ad2ce4f23a9 Mon Sep 17 00:00:00 2001 From: "Leon.Zhang" Date: Fri, 28 Aug 2026 18:55:15 +0800 Subject: [PATCH 1/5] docs: align transaction mode guidance with CLI behavior --- ts/docs/commands/account/activate.md | 4 ++-- ts/docs/commands/account/set.md | 4 ++-- ts/docs/commands/asset/issue.md | 2 +- ts/docs/commands/asset/participate.md | 2 +- ts/docs/commands/asset/unfreeze.md | 2 +- ts/docs/commands/asset/update.md | 2 +- ts/docs/commands/contract/clear-abi.md | 2 +- ts/docs/commands/contract/deploy.md | 2 +- ts/docs/commands/contract/send.md | 2 +- ts/docs/commands/contract/set-origin-energy-limit.md | 2 +- ts/docs/commands/contract/set-user-resource-percent.md | 2 +- ts/docs/commands/exchange/create.md | 2 +- ts/docs/commands/exchange/inject.md | 2 +- ts/docs/commands/exchange/trade.md | 2 +- ts/docs/commands/exchange/withdraw.md | 2 +- ts/docs/commands/gasfree/transfer.md | 2 +- ts/docs/commands/permission/update.md | 4 ++-- ts/docs/commands/proposal/approve.md | 2 +- ts/docs/commands/proposal/create.md | 2 +- ts/docs/commands/proposal/delete.md | 2 +- ts/docs/commands/reward/withdraw.md | 2 +- ts/docs/commands/stake/cancel-unfreeze.md | 2 +- ts/docs/commands/stake/delegate.md | 2 +- ts/docs/commands/stake/freeze.md | 2 +- ts/docs/commands/stake/undelegate.md | 2 +- ts/docs/commands/stake/unfreeze.md | 2 +- ts/docs/commands/stake/withdraw.md | 2 +- ts/docs/commands/tx/index.md | 4 ++-- ts/docs/commands/vote/cast.md | 2 +- ts/docs/commands/witness/create.md | 2 +- ts/docs/commands/witness/set-brokerage.md | 2 +- ts/docs/commands/witness/update.md | 2 +- ts/docs/concepts/security.md | 2 +- ts/docs/guide/ledger.md | 2 +- ts/docs/guide/send-tokens.md | 4 ++-- ts/docs/guide/stake-and-resources.md | 4 ++-- ts/src/adapters/inbound/cli/commands/contract.ts | 2 +- ts/src/adapters/inbound/cli/commands/proposal.ts | 2 +- ts/src/adapters/inbound/cli/commands/shared.ts | 4 ++-- ts/src/adapters/inbound/cli/commands/witness.ts | 2 +- 40 files changed, 47 insertions(+), 47 deletions(-) diff --git a/ts/docs/commands/account/activate.md b/ts/docs/commands/account/activate.md index cf0bb92da..f9d74e980 100644 --- a/ts/docs/commands/account/activate.md +++ b/ts/docs/commands/account/activate.md @@ -16,7 +16,7 @@ A TRON address doesn't exist on-chain until it receives its first asset or is ex Use it only when an address needs to *exist* on its own — to be queryable, or able to initiate its own transactions. If you're sending it funds anyway, [`tx send`](../tx/send.md) activates the recipient automatically in one step; and adding an address to a multi-sig permission does **not** require activation. -Requires the payer account and the master password via `--password-stdin`; watch-only accounts fail with `watch_only_no_signer`. +Requires the payer account. The master password via `--password-stdin` is needed only when the selected mode signs — `--dry-run` and `--build-only` do not unlock the wallet and run without it. Watch-only accounts fail with `watch_only_no_signer` in a signing mode. ## Options @@ -25,7 +25,7 @@ Requires the payer account and the master password via `--password-stdin`; watch | `--address ` | **Required.** The address to activate (a valid, not-yet-activated TRON address) | | `--dry-run` | Build and estimate only; no signature/broadcast, no password. Excludes `--sign-only` / `--build-only` | | `--sign-only` | Build and sign, output the signed hex (feed [`tx broadcast`](../tx/broadcast.md)). Excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex (feed [`tx multisig --create`](../tx/multisig.md)). Excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex (feed [`tx multisig --create`](../tx/multisig.md)). Excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/commands/account/set.md b/ts/docs/commands/account/set.md index 22ef0f84f..524606f90 100644 --- a/ts/docs/commands/account/set.md +++ b/ts/docs/commands/account/set.md @@ -16,7 +16,7 @@ Sets the account's on-chain **name** (a display alias, up to 32 bytes) or its ** ⚠️ **On mainnet each can be set only once and can never be changed** — the value is permanent, and there is no confirmation prompt. This is different from [`rename`](../rename.md), which changes the local label and can be redone anytime. -Requires the account and the master password via `--password-stdin`; watch-only accounts fail with `watch_only_no_signer`. The account id's uniqueness is enforced on-chain — a taken id fails with `id_taken`. +Requires the account. The master password via `--password-stdin` is needed only when the selected mode signs — `--dry-run` and `--build-only` do not unlock the wallet and run without it. Watch-only accounts fail with `watch_only_no_signer` in a signing mode. The account id's uniqueness is enforced on-chain — a taken id fails with `id_taken`. ## Options @@ -26,7 +26,7 @@ Requires the account and the master password via `--password-stdin`; watch-only | `--id ` | **Required** (one of). Account id, 8–32 bytes, globally unique; can be set once | | `--dry-run` | Build and estimate only; no signature/broadcast, no password. Excludes `--sign-only` / `--build-only` | | `--sign-only` | Build and sign, output the signed hex (feed [`tx broadcast`](../tx/broadcast.md)). Excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex (feed [`tx multisig --create`](../tx/multisig.md)). Excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex (feed [`tx multisig --create`](../tx/multisig.md)). Excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/commands/asset/issue.md b/ts/docs/commands/asset/issue.md index 27e1e960e..6c1228b1f 100644 --- a/ts/docs/commands/asset/issue.md +++ b/ts/docs/commands/asset/issue.md @@ -48,7 +48,7 @@ Constraints are checked locally before broadcast: `--name` and `--abbr` are 1– | `--freeze :` | **Repeatable.** Frozen tranche; amount in whole tokens, e.g. `100000000:30` | | `--dry-run` | Build and estimate only, no signature/broadcast; excludes `--sign-only` / `--build-only` | | `--sign-only` | Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/commands/asset/participate.md b/ts/docs/commands/asset/participate.md index 3041d4e60..0967c1c5c 100644 --- a/ts/docs/commands/asset/participate.md +++ b/ts/docs/commands/asset/participate.md @@ -28,7 +28,7 @@ The acting account cannot be the token's own issuer. | `--pay ` | **Required.** TRX to spend (not a token count), > 0 | | `--dry-run` | Build and estimate only, no signature/broadcast; excludes `--sign-only` / `--build-only` | | `--sign-only` | Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/commands/asset/unfreeze.md b/ts/docs/commands/asset/unfreeze.md index b318945e6..a2ee1cff8 100644 --- a/ts/docs/commands/asset/unfreeze.md +++ b/ts/docs/commands/asset/unfreeze.md @@ -30,7 +30,7 @@ This command has no options of its own. |---|---| | `--dry-run` | Build and estimate only, no signature/broadcast; excludes `--sign-only` / `--build-only` | | `--sign-only` | Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/commands/asset/update.md b/ts/docs/commands/asset/update.md index 243bc60c6..379451e04 100644 --- a/ts/docs/commands/asset/update.md +++ b/ts/docs/commands/asset/update.md @@ -31,7 +31,7 @@ Pass only the fields you are changing. The others are read from chain and writte | `--public-free-net ` | Shared free-bandwidth pool for holders (unchanged if omitted) | | `--dry-run` | Build and estimate only, no signature/broadcast; excludes `--sign-only` / `--build-only` | | `--sign-only` | Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/commands/contract/clear-abi.md b/ts/docs/commands/contract/clear-abi.md index a6ffc6092..1a081f116 100644 --- a/ts/docs/commands/contract/clear-abi.md +++ b/ts/docs/commands/contract/clear-abi.md @@ -29,7 +29,7 @@ Only the contract's deployer can do this — the address the chain records as th | `
` | **Required.** Contract whose ABI to clear | | `--dry-run` | Build and estimate only, no signature/broadcast; excludes `--sign-only` / `--build-only` | | `--sign-only` | Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/commands/contract/deploy.md b/ts/docs/commands/contract/deploy.md index cf5f59595..65bd48418 100644 --- a/ts/docs/commands/contract/deploy.md +++ b/ts/docs/commands/contract/deploy.md @@ -50,7 +50,7 @@ Requires an account. The master password (via `--password-stdin`) is needed only | `--constructor-signature ` | The constructor's types when there is no ABI, e.g. `constructor(uint256,string)`; excludes `--artifact`, and not accepted on TRON | | `--dry-run` | Estimate only; excludes `--sign-only` / `--build-only` | | `--sign-only` | Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only` | -| `--build-only` | Build only, output the **unsigned** hex; excludes `--dry-run` / `--sign-only` | +| `--build-only` | Build and estimate, output the **unsigned** hex; excludes `--dry-run` / `--sign-only` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | | `--password-stdin` | Master password from stdin | diff --git a/ts/docs/commands/contract/send.md b/ts/docs/commands/contract/send.md index 5df66830b..e65f033fe 100644 --- a/ts/docs/commands/contract/send.md +++ b/ts/docs/commands/contract/send.md @@ -36,7 +36,7 @@ Requires an account. The master password (via `--password-stdin`) is needed only | `--value ` | Native coin sent with the call, in whole coins | | `--dry-run` | Estimate only, no signature/broadcast; excludes `--sign-only` / `--build-only` | | `--sign-only` | Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only` | -| `--build-only` | Build only, output the **unsigned** hex; excludes `--dry-run` / `--sign-only` | +| `--build-only` | Build and estimate, output the **unsigned** hex; excludes `--dry-run` / `--sign-only` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | | `--password-stdin` | Master password from stdin | diff --git a/ts/docs/commands/contract/set-origin-energy-limit.md b/ts/docs/commands/contract/set-origin-energy-limit.md index 54b711fd7..1a04f6eb2 100644 --- a/ts/docs/commands/contract/set-origin-energy-limit.md +++ b/ts/docs/commands/contract/set-origin-energy-limit.md @@ -32,7 +32,7 @@ Only the contract's deployer can do this; the current value is in [`contract inf | `` | **Required.** Per-call energy the deployer will cover, integer > 0 | | `--dry-run` | Build and estimate only, no signature/broadcast; excludes `--sign-only` / `--build-only` | | `--sign-only` | Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/commands/contract/set-user-resource-percent.md b/ts/docs/commands/contract/set-user-resource-percent.md index ab3104684..99a40eb2b 100644 --- a/ts/docs/commands/contract/set-user-resource-percent.md +++ b/ts/docs/commands/contract/set-user-resource-percent.md @@ -32,7 +32,7 @@ Only the contract's deployer can do this; the current value is in [`contract inf | `` | **Required.** Share of energy paid by the caller, integer 0–100 | | `--dry-run` | Build and estimate only, no signature/broadcast; excludes `--sign-only` / `--build-only` | | `--sign-only` | Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/commands/exchange/create.md b/ts/docs/commands/exchange/create.md index 3615a8a90..147ee641c 100644 --- a/ts/docs/commands/exchange/create.md +++ b/ts/docs/commands/exchange/create.md @@ -36,7 +36,7 @@ The creation fee is **burned** — the chain parameter `getExchangeCreateFee`, c | `--raw-amounts :` | The same two amounts in minimal units. One of `--amounts` / `--raw-amounts` | | `--dry-run` | Build and estimate only, no signature/broadcast; excludes `--sign-only` / `--build-only` | | `--sign-only` | Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/commands/exchange/inject.md b/ts/docs/commands/exchange/inject.md index 580878ba2..fec12ce95 100644 --- a/ts/docs/commands/exchange/inject.md +++ b/ts/docs/commands/exchange/inject.md @@ -33,7 +33,7 @@ If the amount is so small that the computed other side rounds to zero, the chain | `--raw-amount ` | The same amount in minimal units. One of `--amount` / `--raw-amount` | | `--dry-run` | Build and estimate only, no signature/broadcast; excludes `--sign-only` / `--build-only` | | `--sign-only` | Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/commands/exchange/trade.md b/ts/docs/commands/exchange/trade.md index d3ba4121a..09793771c 100644 --- a/ts/docs/commands/exchange/trade.md +++ b/ts/docs/commands/exchange/trade.md @@ -45,7 +45,7 @@ Slippage grows with trade size relative to the reserves — that is the curve, n | `--slippage ` | Derive the floor from current reserves, minus this percentage; > 0 and < 100 | | `--dry-run` | Build and estimate only, no signature/broadcast; excludes `--sign-only` / `--build-only` | | `--sign-only` | Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/commands/exchange/withdraw.md b/ts/docs/commands/exchange/withdraw.md index edb359982..7089140d4 100644 --- a/ts/docs/commands/exchange/withdraw.md +++ b/ts/docs/commands/exchange/withdraw.md @@ -31,7 +31,7 @@ The mirror of [`exchange inject`](inject.md): you name one side and its amount, | `--raw-amount ` | The same amount in minimal units. One of `--amount` / `--raw-amount` | | `--dry-run` | Build and estimate only, no signature/broadcast; excludes `--sign-only` / `--build-only` | | `--sign-only` | Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/commands/gasfree/transfer.md b/ts/docs/commands/gasfree/transfer.md index 11cc9e9b6..fb1ade637 100644 --- a/ts/docs/commands/gasfree/transfer.md +++ b/ts/docs/commands/gasfree/transfer.md @@ -15,7 +15,7 @@ Signs a transfer with EIP-712 structured-data signing and submits it to the GasF Submission returns a **`traceId`** (the provider's acceptance id); at that point the transfer is accepted but **not yet on-chain**. Add `--wait` to poll the provider to a terminal state (`SUCCEED` / `FAILED`), or follow it later with [`gasfree trace`](trace.md). On the first transfer, when the GasFree address isn't activated yet, this transfer carries the activation automatically and the total deducted is amount + service fee + activation fee (itemised in the receipt and in `--dry-run`). -There is no `--sign-only` / `--build-only`: the signed payload is bound to the provider's submission protocol, so offline distribution has no meaning. Requires an account, the master password via `--password-stdin`, and the provider credentials (`gasfreeApiKey` / `gasfreeApiSecret`, set with [`config`](../config.md)); watch-only accounts fail with `watch_only_no_signer`. +There is no `--sign-only` / `--build-only`: the signed payload is bound to the provider's submission protocol, so offline distribution has no meaning. Requires an account and the provider credentials (`gasfreeApiKey` / `gasfreeApiSecret`, set with [`config`](../config.md)). The master password via `--password-stdin` is needed only when submitting the transfer; `--dry-run` does not unlock or sign. Watch-only accounts fail with `watch_only_no_signer` when submitting. ## Options diff --git a/ts/docs/commands/permission/update.md b/ts/docs/commands/permission/update.md index 39285de00..64d6260bd 100644 --- a/ts/docs/commands/permission/update.md +++ b/ts/docs/commands/permission/update.md @@ -14,7 +14,7 @@ wallet-cli permission update (--file | --json ) Replaces the account's **entire** permission structure with the new one given by `--file` (a JSON file) or `--json` (an inline JSON string) — TRON's `UpdateAccountPermission` has replace semantics, so the JSON you supply becomes the whole structure. The chain burns **100 TRX** for the change. -The command runs without a confirmation prompt. It requires an account and the master password via `--password-stdin`; watch-only accounts fail with `watch_only_no_signer`. +The command runs without a confirmation prompt. It requires an account. The master password via `--password-stdin` is needed only when the selected mode signs — `--dry-run` and `--build-only` do not unlock the wallet and run without it. Watch-only accounts fail with `watch_only_no_signer` in a signing mode. **Input format.** The permission JSON is the same shape as [`permission show -o json`](show.md)'s `data` (`owner` / `witness` / `actives`; a key's `local` field may be omitted). You write the **contract-type names** for each active group's `operations`, not the raw bitmap — the CLI encodes it. A convenient way to produce a valid input is to export the current structure, edit it, and submit the file. @@ -42,7 +42,7 @@ Changing only `keys`, `threshold` or `name` needs no such deletion. | `--json ` | **Required** (one of). Inline JSON string with the new structure (same shape) | | `--dry-run` | Mock receipt — fee, resulting-structure card, and warnings — matching a real submission; no signature, no broadcast, no password. Excludes `--sign-only` / `--build-only` | | `--sign-only` | Build and sign, output the signed hex without broadcasting (feed [`tx broadcast`](../tx/broadcast.md) for on-chain co-signing). Excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex (feed [`tx multisig --create`](../tx/multisig.md) for service-relayed multi-sig). Excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex (feed [`tx multisig --create`](../tx/multisig.md) for service-relayed multi-sig). Excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active) — changing permissions is owner-level, so normally `0` (default `0`) | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/commands/proposal/approve.md b/ts/docs/commands/proposal/approve.md index 4acbb58ab..3bf38c916 100644 --- a/ts/docs/commands/proposal/approve.md +++ b/ts/docs/commands/proposal/approve.md @@ -26,7 +26,7 @@ Only a registered witness can approve; other accounts fail with `not_a_witness`. | `--cancel` | Withdraw an approval you cast earlier instead of adding one | | `--dry-run` | Build and estimate only, no signature/broadcast; excludes `--sign-only` / `--build-only` | | `--sign-only` | Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/commands/proposal/create.md b/ts/docs/commands/proposal/create.md index c1cf2b7dd..21c07ddb8 100644 --- a/ts/docs/commands/proposal/create.md +++ b/ts/docs/commands/proposal/create.md @@ -27,7 +27,7 @@ Pass `--set` once per parameter. The receipt and `data.changes[]` order changes | `--set =` | **Required, repeatable.** One parameter change, e.g. `--set getTransactionFee=15`; `name` is a `chain params` key, a raw parameter id is also accepted | | `--dry-run` | Build and estimate only, no signature/broadcast; excludes `--sign-only` / `--build-only` | | `--sign-only` | Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/commands/proposal/delete.md b/ts/docs/commands/proposal/delete.md index 2cbb069a2..4802c9302 100644 --- a/ts/docs/commands/proposal/delete.md +++ b/ts/docs/commands/proposal/delete.md @@ -27,7 +27,7 @@ The chain records the result under its own name — after a successful delete, [ | `` | **Required.** Proposal id | | `--dry-run` | Build and estimate only, no signature/broadcast; excludes `--sign-only` / `--build-only` | | `--sign-only` | Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/commands/reward/withdraw.md b/ts/docs/commands/reward/withdraw.md index cbc940746..19b59ec57 100644 --- a/ts/docs/commands/reward/withdraw.md +++ b/ts/docs/commands/reward/withdraw.md @@ -23,7 +23,7 @@ Moves your accumulated voting rewards (plus block rewards if you are an SR) into |---|---| | `--dry-run` | Build and estimate only, no signature/broadcast; excludes `--sign-only` / `--build-only` | | `--sign-only` | Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/commands/stake/cancel-unfreeze.md b/ts/docs/commands/stake/cancel-unfreeze.md index 475ef2b72..246547e08 100644 --- a/ts/docs/commands/stake/cancel-unfreeze.md +++ b/ts/docs/commands/stake/cancel-unfreeze.md @@ -21,7 +21,7 @@ Cancels **every** unstake still in its waiting period and rolls those amounts ba |---|---| | `--dry-run` | Estimate only, no signature/broadcast; excludes `--sign-only` / `--build-only` | | `--sign-only` | Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/commands/stake/delegate.md b/ts/docs/commands/stake/delegate.md index 33d3b59c5..f0fecbcc6 100644 --- a/ts/docs/commands/stake/delegate.md +++ b/ts/docs/commands/stake/delegate.md @@ -31,7 +31,7 @@ Check how much you can still delegate with [`stake delegated`](delegated.md) (`M | `--lock-period ` | Lock duration in blocks (~3 s/block); requires `--lock` | | `--dry-run` | Estimate only, no signature/broadcast; excludes `--sign-only` / `--build-only` | | `--sign-only` | Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/commands/stake/freeze.md b/ts/docs/commands/stake/freeze.md index 1118ba65e..85eb46702 100644 --- a/ts/docs/commands/stake/freeze.md +++ b/ts/docs/commands/stake/freeze.md @@ -25,7 +25,7 @@ Amount is in SUN (1 TRX = 1,000,000 SUN). Staked TRX stays yours; to get it back | `--resource ` | Resource type to obtain (default `bandwidth`) | | `--dry-run` | Estimate only, no signature/broadcast; excludes `--sign-only` / `--build-only` | | `--sign-only` | Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/commands/stake/undelegate.md b/ts/docs/commands/stake/undelegate.md index 5e313addb..b6ac8a171 100644 --- a/ts/docs/commands/stake/undelegate.md +++ b/ts/docs/commands/stake/undelegate.md @@ -27,7 +27,7 @@ Reclaiming is immediate (no waiting period — the TRX was staked all along, onl | `--resource ` | Resource type to reclaim (default `bandwidth`) | | `--dry-run` | Estimate only, no signature/broadcast; excludes `--sign-only` / `--build-only` | | `--sign-only` | Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/commands/stake/unfreeze.md b/ts/docs/commands/stake/unfreeze.md index 43ad8cfc5..9b42c73f3 100644 --- a/ts/docs/commands/stake/unfreeze.md +++ b/ts/docs/commands/stake/unfreeze.md @@ -25,7 +25,7 @@ Stake 2.0 allows at most **32 pending unstakes** per account at a time; check re | `--resource ` | Resource type to release (default `bandwidth`) | | `--dry-run` | Estimate only, no signature/broadcast; excludes `--sign-only` / `--build-only` | | `--sign-only` | Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/commands/stake/withdraw.md b/ts/docs/commands/stake/withdraw.md index 3cff26c4a..d4b2e985b 100644 --- a/ts/docs/commands/stake/withdraw.md +++ b/ts/docs/commands/stake/withdraw.md @@ -23,7 +23,7 @@ Withdrawing also frees up unstake slots (max 32 pending unstakes per account). |---|---| | `--dry-run` | Estimate only, no signature/broadcast; excludes `--sign-only` / `--build-only` | | `--sign-only` | Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/commands/tx/index.md b/ts/docs/commands/tx/index.md index e8e4ad85e..aeac4a4a6 100644 --- a/ts/docs/commands/tx/index.md +++ b/ts/docs/commands/tx/index.md @@ -25,13 +25,13 @@ The transaction **hex** these commands exchange is `protocol.Transaction` protob ## The transaction lifecycle ``` -build ──sign──> submit ──solidify──> confirmed +build ──sign──> submit ──receipt──> confirmed │ │ │ └ --dry-run └ default return └ tx status: confirmed/failed stops here point ("submitted") (pending/not_found while in flight) ``` -`tx send` covers build+sign+submit in one step (with `--dry-run` / `--sign-only` stopping earlier); `tx broadcast` submits what was signed elsewhere; `tx status` / `tx info` observe the outcome. **Submission is not confirmation** — scripts must follow [machine-interface → Script safety](../../machine-interface.md#script-safety-never-mistake-submitted-for-confirmed). +`tx send` covers build+sign+submit in one step (with `--dry-run` / `--sign-only` stopping earlier); `tx broadcast` submits what was signed elsewhere; `tx status` / `tx info` observe the outcome. `confirmed` means included and receipted, not finalized. **Submission is not confirmation** — scripts must follow [machine-interface → Script safety](../../machine-interface.md#script-safety-never-mistake-submitted-for-confirmed). ## Multi-sig co-signing diff --git a/ts/docs/commands/vote/cast.md b/ts/docs/commands/vote/cast.md index 5c33138f9..b0ba849d9 100644 --- a/ts/docs/commands/vote/cast.md +++ b/ts/docs/commands/vote/cast.md @@ -29,7 +29,7 @@ Votes take effect at the next maintenance cycle (~6 h). Each vote uses 1 TP (it | `--for ` | **Required, repeatable.** SR address = vote count (positive integer); the whole set becomes your full allocation (1–30 entries) | | `--dry-run` | Build and estimate only, no signature/broadcast; excludes `--sign-only` / `--build-only` | | `--sign-only` | Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/commands/witness/create.md b/ts/docs/commands/witness/create.md index b9ddb39fa..658308aff 100644 --- a/ts/docs/commands/witness/create.md +++ b/ts/docs/commands/witness/create.md @@ -27,7 +27,7 @@ The account must already be activated and hold at least the registration fee. `- | `--url ` | **Required.** Candidate info page | | `--dry-run` | Build and estimate only, no signature/broadcast; reports the registration fee; excludes `--sign-only` / `--build-only` | | `--sign-only` | Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/commands/witness/set-brokerage.md b/ts/docs/commands/witness/set-brokerage.md index 2b0c05dbe..74e9d5af5 100644 --- a/ts/docs/commands/witness/set-brokerage.md +++ b/ts/docs/commands/witness/set-brokerage.md @@ -27,7 +27,7 @@ Any registered witness can set it, elected or not. The acting account must be a | `` | **Required.** Share the SR keeps, integer 0–100 | | `--dry-run` | Build and estimate only, no signature/broadcast; excludes `--sign-only` / `--build-only` | | `--sign-only` | Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/commands/witness/update.md b/ts/docs/commands/witness/update.md index 688856ec6..647fad391 100644 --- a/ts/docs/commands/witness/update.md +++ b/ts/docs/commands/witness/update.md @@ -25,7 +25,7 @@ The acting account must already be a candidate; otherwise the command fails with | `--url ` | **Required.** New candidate info page | | `--dry-run` | Build and estimate only, no signature/broadcast; excludes `--sign-only` / `--build-only` | | `--sign-only` | Sign without broadcasting, output the signed hex; excludes `--dry-run` / `--build-only`; pairs with `--expiration` | -| `--build-only` | Build only, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | +| `--build-only` | Build and estimate, output the **unsigned** hex; excludes `--dry-run` / `--sign-only`; pairs with `--expiration` | | `--expiration ` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) | | `--permission-id ` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` | | `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | diff --git a/ts/docs/concepts/security.md b/ts/docs/concepts/security.md index 8dad1ebd7..79254f4b3 100644 --- a/ts/docs/concepts/security.md +++ b/ts/docs/concepts/security.md @@ -4,7 +4,7 @@ What wallet-cli protects, how, and what remains your job. ## Local storage -All secrets (seeds, private keys) are stored **encrypted under your master password**; nothing usable is on disk in the clear. Metadata (labels, addresses) is readable without unlock — that's why `list` needs no password but `tx send` does. +All secrets (seeds, private keys) are stored **encrypted under your master password**; nothing usable is on disk in the clear. Metadata (labels, addresses) is readable without unlock — that's why `list` needs no password but a software-signed `tx send` does. The master password is local protection only: it is never sent anywhere and **cannot be recovered**. It must be at least 8 characters with an uppercase letter, a lowercase letter, a digit, and a special character. diff --git a/ts/docs/guide/ledger.md b/ts/docs/guide/ledger.md index a11ca9fd4..2591dad7b 100644 --- a/ts/docs/guide/ledger.md +++ b/ts/docs/guide/ledger.md @@ -50,7 +50,7 @@ More remedies: [Troubleshooting](../troubleshooting.md#timeout-exit-1). ## Offline pattern -Ledger already isolates keys, but you can combine it with the split flow — `--sign-only` on the machine with the device, [`tx broadcast`](../commands/tx/broadcast.md) on a connected one. See [Scripting → Sign here, broadcast there](scripting.md#sign-here-broadcast-there). +Ledger already isolates keys, but you can still split build/sign/broadcast. For a device machine with no chain access, build unsigned hex with `--build-only` on a connected machine, sign it with `tx sign --offline` where the Ledger is attached, then broadcast the signed hex from a connected machine. See [Scripting → Sign here, broadcast there](scripting.md#sign-here-broadcast-there). ## See also diff --git a/ts/docs/guide/send-tokens.md b/ts/docs/guide/send-tokens.md index 5d70cc4a5..8ff272754 100644 --- a/ts/docs/guide/send-tokens.md +++ b/ts/docs/guide/send-tokens.md @@ -2,7 +2,7 @@ One command sends every asset kind — the network's native coin, TRC20/ERC20 contract tokens, and TRC10 assets — the selector flags decide which. Command examples run on Nile; the same commands work on an EVM network by swapping `--network`. -> **Password**: every `tx send` needs your master password on stdin, and signing shows no prompt. The examples below omit it to keep the token flags in focus — prepend `printf '%s' "$PW" |` and append `--password-stdin`, or pipe from a password manager (see [Getting started](getting-started.md#3-send-your-first-transaction)). +> **Password**: software-signed sends need your master password on stdin, and signing shows no prompt. The examples below omit it to keep the token flags in focus — prepend `printf '%s' "$PW" |` and append `--password-stdin`, or pipe from a password manager. `--dry-run`, `--build-only`, and Ledger signing do not use the master password. ## The native coin @@ -76,7 +76,7 @@ wallet-cli tx send --to T... --asset-id 1002000 --raw-amount 1000000 --network t ## Rehearse, then send -`--dry-run` builds the transaction and estimates fees without signing or broadcasting — nothing can leave your wallet: +`--dry-run` builds the transaction and estimates fees through the selected network, then returns without signing or broadcasting: ```bash wallet-cli tx send --to T... --token USDT --amount 5 --network tron:nile --dry-run -o json diff --git a/ts/docs/guide/stake-and-resources.md b/ts/docs/guide/stake-and-resources.md index af09581e7..88b6c1f74 100644 --- a/ts/docs/guide/stake-and-resources.md +++ b/ts/docs/guide/stake-and-resources.md @@ -2,7 +2,7 @@ Stake TRX to earn **resources** — energy and bandwidth — instead of burning TRX on every transaction. This walkthrough uses the `stake` commands on Nile. **TRON only**: EVM networks price transactions in gas and have nothing to stake, so every command here fails there with `family_mismatch`. Background: [Energy & bandwidth](../concepts/energy-bandwidth.md). -> **Password**: every `stake` command signs a transaction, so it needs your master password on stdin (`--password-stdin`), and signing shows no prompt. The examples below omit it to keep the resource flags in focus — prepend `printf '%s' "$PW" |` and append `--password-stdin`, or pipe from a password manager (see [Getting started](getting-started.md#3-send-your-first-transaction)). Step 1 is a read-only query and needs no password. +> **Password**: stake write commands need your master password only when the selected mode signs. The examples below omit it to keep the resource flags in focus — prepend `printf '%s' "$PW" |` and append `--password-stdin` for software signing, or pipe from a password manager. `--dry-run`, `--build-only`, `stake info`, and `stake delegated` need no password. ## 1. See what you have @@ -33,7 +33,7 @@ Plain TRX transfers consume **bandwidth**; smart-contract calls (TRC20 transfers wallet-cli stake freeze --amount-sun 100000000 --resource energy --network tron:nile ``` -`--resource` chooses which resource the stake produces. It defaults to `bandwidth`; stake for `energy` when you plan to send TRC20 tokens or call contracts, since those spend energy (as in step 1). The TRX stays yours — it is locked, not spent — and staking also grants TRON Power (governance votes). Like every state-changing command, `stake freeze` supports `--dry-run`, `--sign-only`, `--wait`, and returns at submission by default. +`--resource` chooses which resource the stake produces. It defaults to `bandwidth`; stake for `energy` when you plan to send TRC20 tokens or call contracts, since those spend energy (as in step 1). The TRX stays yours — it is locked, not spent — and staking also grants TRON Power (governance votes). Like every state-changing command, `stake freeze` supports `--dry-run`, `--sign-only`, `--build-only`, `--wait`, and returns at submission by default. Verify the effect by running `account info` again — the `Energy` limit now reflects the TRX you staked: diff --git a/ts/src/adapters/inbound/cli/commands/contract.ts b/ts/src/adapters/inbound/cli/commands/contract.ts index 8529633fd..b3f6622f2 100644 --- a/ts/src/adapters/inbound/cli/commands/contract.ts +++ b/ts/src/adapters/inbound/cli/commands/contract.ts @@ -690,7 +690,7 @@ export const contractInfoTronBinding = (svc: TronContractService): FamilyBinding const contractGovernanceBase = { network: "optional" as const, wallet: "optional" as const, - auth: "required" as const, + auth: "conditional" as const, broadcasts: true, capability: "contract.governance", baseRefine: governanceTxRefine, diff --git a/ts/src/adapters/inbound/cli/commands/proposal.ts b/ts/src/adapters/inbound/cli/commands/proposal.ts index 07b49e097..1dbe14800 100644 --- a/ts/src/adapters/inbound/cli/commands/proposal.ts +++ b/ts/src/adapters/inbound/cli/commands/proposal.ts @@ -65,7 +65,7 @@ export const proposalShowTronBinding = (service: TronProposalService): FamilyBin const proposalWriteBase = { network: "optional" as const, wallet: "optional" as const, - auth: "required" as const, + auth: "conditional" as const, broadcasts: true, capability: "proposal.write", baseRefine: governanceTxRefine, diff --git a/ts/src/adapters/inbound/cli/commands/shared.ts b/ts/src/adapters/inbound/cli/commands/shared.ts index 98087ea96..e44adebbe 100644 --- a/ts/src/adapters/inbound/cli/commands/shared.ts +++ b/ts/src/adapters/inbound/cli/commands/shared.ts @@ -50,7 +50,7 @@ export const txModeFields = { .boolean() .default(false) .describe( - "build and output unsigned complete transaction hex without unlocking; the entry point for multi-party signing (relay it with `tx sign`, or open a queue with `tx multisig --create`)", + "build and estimate, then output unsigned complete transaction hex without unlocking; the entry point for multi-party signing (relay it with `tx sign`, or open a queue with `tx multisig --create`)", ), }; @@ -62,7 +62,7 @@ export const governanceTxModeFields = { .boolean() .default(false) .describe( - "build an unsigned transaction without signing or broadcasting; mutually exclusive with --dry-run/--sign-only", + "build and estimate an unsigned transaction without unlocking, signing, or broadcasting; mutually exclusive with --dry-run/--sign-only", ), }; diff --git a/ts/src/adapters/inbound/cli/commands/witness.ts b/ts/src/adapters/inbound/cli/commands/witness.ts index 27410c41a..4208cc664 100644 --- a/ts/src/adapters/inbound/cli/commands/witness.ts +++ b/ts/src/adapters/inbound/cli/commands/witness.ts @@ -14,7 +14,7 @@ const witnessUrl = z const witnessWriteBase = { network: "optional" as const, wallet: "optional" as const, - auth: "required" as const, + auth: "conditional" as const, broadcasts: true, capability: "witness.manage", baseRefine: governanceTxRefine, From 44fae254a9e0907c1a0fcc75b502631d019c309c Mon Sep 17 00:00:00 2001 From: "Leon.Zhang" Date: Fri, 28 Aug 2026 19:38:17 +0800 Subject: [PATCH 2/5] docs: align CLI behavior references --- ts/docs/commands/account/index.md | 2 +- ts/docs/commands/contract/index.md | 2 +- ts/docs/commands/index.md | 8 ++++---- ts/docs/commands/tx/multisig.md | 8 ++++---- ts/docs/commands/tx/sign.md | 8 ++++---- ts/docs/guide/stake-and-resources.md | 2 +- ts/docs/machine-interface.md | 10 +++++----- 7 files changed, 20 insertions(+), 20 deletions(-) diff --git a/ts/docs/commands/account/index.md b/ts/docs/commands/account/index.md index 9ba23041a..7580fc474 100644 --- a/ts/docs/commands/account/index.md +++ b/ts/docs/commands/account/index.md @@ -8,7 +8,7 @@ Query on-chain account state, and activate & name accounts. wallet-cli account COMMAND ``` -Subcommands act on the **active account** by default; override with `--account ` or change the default with `wallet-cli use `. Which address is queried follows the selected network's family — the same account has a TRON base58 address and an EVM `0x` address. The first four are read-only queries; `activate` and `set` change on-chain state and need the master password. +Subcommands act on the **active account** by default; override with `--account ` or change the default with `wallet-cli use `. Which address is queried follows the selected network's family — the same account has a TRON base58 address and an EVM `0x` address. The first four are read-only queries; `activate` and `set` change on-chain state. Software signing needs the master password, Ledger signing confirms on device, and `--dry-run` / `--build-only` do not unlock the wallet. ## Subcommands diff --git a/ts/docs/commands/contract/index.md b/ts/docs/commands/contract/index.md index 97dcb9d22..018bcf68a 100644 --- a/ts/docs/commands/contract/index.md +++ b/ts/docs/commands/contract/index.md @@ -23,7 +23,7 @@ wallet-cli contract COMMAND | `contract set-user-resource-percent` | [set-user-resource-percent.md](set-user-resource-percent.md) | Share of a call's energy paid by the caller | TRON only | | `contract create2` | [create2.md](create2.md) | Precompute a CREATE2 address | TRON only | -The three portable commands share one flag vocabulary and differ only in fees: `--fee-limit` / `--permission-id` / `--expiration` on TRON, `--gas-limit` / `--max-fee` / `--priority-fee` / `--nonce` on EVM, each refused on the other family with `invalid_option`. The **TRON only** commands are the ones with no EVM counterpart — an on-chain ABI registry and the deployer-pays energy model are TRON protocol features, and TRON's CREATE2 derivation is not Ethereum's. Running one against an EVM network fails with `family_mismatch`. +The portable commands share the same chain families, not the same flags. `contract call` is read-only and takes call inputs; `contract send` and `contract deploy` are write transactions and carry the fee/signing vocabulary: `--fee-limit` / `--permission-id` / `--expiration` on TRON, `--gas-limit` / `--max-fee` / `--priority-fee` / `--nonce` on EVM, each refused on the other family with `invalid_option`. The **TRON only** commands are the ones with no EVM counterpart — an on-chain ABI registry and the deployer-pays energy model are TRON protocol features, and TRON's CREATE2 derivation is not Ethereum's. Running one against an EVM network fails with `family_mismatch`. ## See also diff --git a/ts/docs/commands/index.md b/ts/docs/commands/index.md index b92dc0a33..4aafee713 100644 --- a/ts/docs/commands/index.md +++ b/ts/docs/commands/index.md @@ -185,16 +185,16 @@ Individual flags are family-scoped the same way. `--help` tags them `(tron only) -h, --help / -V, --version ``` -Broadcast (✍️) commands additionally take `--wait` / `--wait-timeout ` (cap default: config `waitTimeoutMs`, built-in 60000) and the early-exit modes `--dry-run` / `--sign-only` / `--build-only`. +Broadcast (✍️) commands additionally take `--wait` / `--wait-timeout ` (cap default: config `waitTimeoutMs`, built-in 60000). Early-exit modes are command-specific: transaction-building commands expose `--dry-run` / `--sign-only` / `--build-only`, while submit-only commands such as `tx broadcast` do not rebuild or sign and therefore omit `--sign-only` / `--build-only`. Fee and multi-sig flags are **family-scoped**, so they are not global: | Flags | Family | Where | |---|---|---| -| Permission group and expiry — see below | TRON | every TRON broadcast command | +| Permission group and expiry — see below | TRON | TRON transaction-building commands that sign or can emit unsigned hex; not `tx broadcast` or GasFree | | `--fee-limit ` | TRON | the commands that spend energy: `tx send`, `contract send` / `deploy` | | `--gas-limit ` / `--max-fee ` / `--priority-fee ` / `--nonce ` | EVM | `tx send`, `contract send` / `deploy` | -Every TRON broadcast command takes the multi-signature pair: the permission group to sign under (0=owner, 1=witness, 2-9=active) and the transaction's expiry, which extends the window for collecting co-signatures. On a multi-family command they are tagged `(tron only)` and refused on EVM with `invalid_option`; an EVM transaction carries exactly one signature, so neither has a counterpart there. +Those TRON transaction-building commands take the multi-signature pair: the permission group to sign under (0=owner, 1=witness, 2-9=active) and the transaction's expiry, which extends the window for collecting co-signatures when building or signing offline. On a multi-family command they are tagged `(tron only)` and refused on EVM with `invalid_option`; an EVM transaction carries exactly one signature, so neither has a counterpart there. -The three early-exit modes are mutually exclusive, and `--expiration` is accepted only alongside `--sign-only` or `--build-only`. Breaking either rule is a usage error at exit `2`. The code depends on where the check runs: on the governance writes it is `invalid_value`, and the message names the field as `--input` rather than the flags you passed — for example `invalid --input: choose at most one of --dry-run, --sign-only, --build-only`. Elsewhere the same conflict reports `invalid_option`. Branch on the exit code, not on the code string; see [machine interface](../machine-interface.md#error-codes). +Where all three early-exit modes are present, they are mutually exclusive, and `--expiration` is accepted only alongside `--sign-only` or `--build-only`. Breaking either rule is a usage error at exit `2`. The code depends on where the check runs: on the governance writes it is `invalid_value`, and the message names the field as `--input` rather than the flags you passed — for example `invalid --input: choose at most one of --dry-run, --sign-only, --build-only`. Elsewhere the same conflict reports `invalid_option`. Branch on the exit code, not on the code string; see [machine interface](../machine-interface.md#error-codes). diff --git a/ts/docs/commands/tx/multisig.md b/ts/docs/commands/tx/multisig.md index 615590037..2e399ddf2 100644 --- a/ts/docs/commands/tx/multisig.md +++ b/ts/docs/commands/tx/multisig.md @@ -16,8 +16,8 @@ wallet-cli tx multisig [--create (--hex | --file ) | --sign Where the on-chain path passes a hex from person to person, the service path has the TronLink service **hold** a transaction, **accumulate** signatures one by one, and **push** notifications to co-signers over a WebSocket. The command has four mutually exclusive modes: - **default (no mode flag)** — list the service's multi-sig transactions involving this account, with their progress. This is the everyday way to find what's awaiting you. -- **`--create`** — sign an **unsigned** transaction locally and submit it, which opens the collection. The input is unsigned hex, produced by any broadcast command in `--build-only` mode (e.g. `tx send … --build-only`). Requires the master password. -- **`--sign `** — co-sign one: fetch it with the signatures gathered so far, sign locally, and submit the whole transaction back for the service to accumulate. Requires the master password. +- **`--create`** — sign an **unsigned** transaction locally and submit it, which opens the collection. The input is unsigned hex, produced by a transaction-building command that supports `--build-only` (e.g. `tx send … --build-only`). Software accounts require the master password; Ledger accounts confirm on device. +- **`--sign `** — co-sign one: fetch it with the signatures gathered so far, sign locally, and submit the whole transaction back for the service to accumulate. Software accounts require the master password; Ledger accounts confirm on device. - **`--watch`** — keep a WebSocket open and nudge you with the **count** of transactions awaiting your signature (no details); list them with the default mode to act. ### Opening a collection is your first signature @@ -43,11 +43,11 @@ The credentials are per-environment (mainnet / testnet); set them with [`config` | `--sign ` | Co-sign a pending transaction by 32-byte hex txId: fetch → sign locally → submit back; excludes `--create` / `--watch` | | `--watch` | Keep a WebSocket open; nudge with the count awaiting your signature (no details); excludes `--create` / `--sign` | -Plus the [global options](../index.md#global-options-every-command) and `--password-stdin` (with `--create` and `--sign`). +Plus the [global options](../index.md#global-options-every-command) and `--password-stdin` for software accounts (with `--create` and `--sign`). ## Examples -In the examples, `$PW` is your master password, fed on stdin via `--password-stdin`. +In the examples, `$PW` is a software account's master password, fed on stdin via `--password-stdin`. The initiator builds an **unsigned** transaction (`--build-only`, expiry extended to allow collection), then signs and submits it to open a collection: diff --git a/ts/docs/commands/tx/sign.md b/ts/docs/commands/tx/sign.md index 7bb3b427d..133047ac1 100644 --- a/ts/docs/commands/tx/sign.md +++ b/ts/docs/commands/tx/sign.md @@ -16,9 +16,9 @@ Two input modes: with `--hex` / `--file` it signs the transaction hex (protobuf **On EVM there is no co-signing.** An EVM transaction carries exactly one signature, so a hex that already has one is refused with `invalid_transaction`, and there is no threshold, weight or permission group to report. The chain id inside the transaction is checked against `--network` **before** signing (`chain_id_mismatch`) — a mainnet transaction handed to `--network sepolia` would otherwise come back validly signed for mainnet, and nothing downstream could catch it. -On TRON it is the on-chain co-signing path: an initiator produces a partially signed hex with `tx send --sign-only` (or any broadcast command in `--sign-only` mode), each co-signer runs `tx sign` in turn — passing the hex from person to person — and once the weight reaches the threshold, anyone broadcasts the final hex with [`tx broadcast --hex`](broadcast.md). All signatures must be collected before the transaction expires (default ~60s, up to 24h via `--expiration`). +On TRON it is the on-chain co-signing path: an initiator produces a partially signed hex with `tx send --sign-only` (or another transaction-building command that supports `--sign-only`), each co-signer runs `tx sign` in turn — passing the hex from person to person — and once the weight reaches the threshold, anyone broadcasts the final hex with [`tx broadcast --hex`](broadcast.md). All signatures must be collected before the transaction expires (default ~60s, up to 24h via `--expiration`). -Signing endorses the transaction with your key: the command shows no preview or confirmation, reads the master password from `--password-stdin`, and signs directly — to inspect a transaction without signing it, use [`tx approvals`](approvals.md). It does **not** broadcast, and has **no `--permission-id`** (the group is fixed in the transaction body; it's shown on the `Permission` line). Watch-only accounts fail with `watch_only_no_signer`. +Signing endorses the transaction with your key: software accounts read the master password from `--password-stdin` and sign without a CLI preview, while Ledger accounts do not read a master password and confirm on device. To inspect a transaction without signing it, use [`tx approvals`](approvals.md). It does **not** broadcast, and has **no `--permission-id`** (the group is fixed in the transaction body; it's shown on the `Permission` line). Watch-only accounts fail with `watch_only_no_signer`. ### What is verified before signing @@ -44,7 +44,7 @@ Four contract types cannot be re-encoded by the bundled decoder — `UnfreezeAss | `--offline` | Sign locally without contacting a node; skips the signer-permission and approval-weight checks. Only meaningful on TRON — EVM signing contacts no node either way | | `--out ` | Write the resulting hex to a file (mode 0644, written atomically) instead of stdout | -Plus the [global options](../index.md#global-options-every-command) and `--password-stdin`. +Plus the [global options](../index.md#global-options-every-command) and `--password-stdin` for software accounts. The transaction is passed on argv, not stdin: it is not a secret, and this leaves fd 0 free for `--password-stdin`. @@ -58,7 +58,7 @@ An initiator first produces a partially signed `tx.hex` with `tx send --sign-onl echo "$PW" | wallet-cli tx send --to TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub --amount 1000 --sign-only --permission-id 2 --expiration 86400000 --network tron:nile --password-stdin > tx.hex ``` -A second signer appends their signature — no preview, no confirmation; the receipt carries the transaction content and progress blocks: +A second software signer appends their signature; the receipt carries the transaction content and progress blocks: ```bash echo "$PW" | wallet-cli tx sign --file tx.hex --account cosigner --out tx.signed.hex --network tron:nile --password-stdin diff --git a/ts/docs/guide/stake-and-resources.md b/ts/docs/guide/stake-and-resources.md index 88b6c1f74..178226a43 100644 --- a/ts/docs/guide/stake-and-resources.md +++ b/ts/docs/guide/stake-and-resources.md @@ -33,7 +33,7 @@ Plain TRX transfers consume **bandwidth**; smart-contract calls (TRC20 transfers wallet-cli stake freeze --amount-sun 100000000 --resource energy --network tron:nile ``` -`--resource` chooses which resource the stake produces. It defaults to `bandwidth`; stake for `energy` when you plan to send TRC20 tokens or call contracts, since those spend energy (as in step 1). The TRX stays yours — it is locked, not spent — and staking also grants TRON Power (governance votes). Like every state-changing command, `stake freeze` supports `--dry-run`, `--sign-only`, `--build-only`, `--wait`, and returns at submission by default. +`--resource` chooses which resource the stake produces. It defaults to `bandwidth`; stake for `energy` when you plan to send TRC20 tokens or call contracts, since those spend energy (as in step 1). The TRX stays yours — it is locked, not spent — and staking also grants TRON Power (governance votes). Like the other stake write commands, `stake freeze` supports `--dry-run`, `--sign-only`, `--build-only`, `--wait`, and returns at submission by default. Verify the effect by running `account info` again — the `Energy` limit now reflects the TRX you staked: diff --git a/ts/docs/machine-interface.md b/ts/docs/machine-interface.md index 3875aa443..8c8f13a63 100644 --- a/ts/docs/machine-interface.md +++ b/ts/docs/machine-interface.md @@ -158,13 +158,13 @@ Text mode titles the same window (`Assets (limit 50, offset 0)`, `Proposals (sho The **exit code is the hard contract**: `2` means the call was malformed (it will still be wrong on retry), `1` means execution failed (network / device / chain / wallet). `error.code` is a machine-readable string that refines the exit code — branch on the exit code first, then optionally on `error.code`. -**The complete code index is published**, one line per code, under `errorCodes` in the discovery catalog: +**The maintained code index is published**, one line per code, under `errorCodes` in the discovery catalog: ```bash wallet-cli --json-schema | jq '.errorCodes' ``` -That index is the authority and is enforced by the build: a code cannot be raised without an entry, and an entry cannot outlive its code. The tables below are the frequently-hit subset, kept for reading. New codes may still be added within v1, and a few strings (e.g. `invalid_value`, `aborted`) can appear under either exit code depending on where they are raised — so always tolerate an unknown code by falling back to its exit-code class. +That index is the machine-readable catalog exposed by this build. Treat it as a discovery aid, not a closed enum: a few code paths choose among error-code strings dynamically, so a runtime envelope can still carry a code not present in `errorCodes`. The tables below are the frequently-hit subset, kept for reading. New codes may still be added within v1, and a few strings (e.g. `invalid_value`, `aborted`) can appear under either exit code depending on where they are raised — so always tolerate an unknown code by falling back to its exit-code class. Common codes at exit **2** (usage — fix the call): @@ -176,7 +176,7 @@ Common codes at exit **2** (usage — fix the call): | `invalid_option` | A flag was used in an invalid combination, or is scoped to the other chain family | | `invalid_value` | A flag value failed validation (e.g. `config defaultOutput xml`) | | `invalid_amount` | An amount is malformed or out of range | -| `invalid_secret` | A supplied mnemonic / private key is malformed | +| `invalid_mnemonic` / `invalid_private_key` | A supplied mnemonic or private key is malformed | | `weak_password` | Master password below policy (≥8 chars; upper + lower + digit + special) | | `tty_required` | An interactive prompt is needed but no TTY is attached — pass the matching `*-stdin` flag | | `missing_network` / `unsupported_network` | `--network` absent, or not a known canonical id or alias | @@ -220,7 +220,7 @@ Common codes at exit **1** (execution — runtime failure): | `ledger_unsupported` | The Ledger TRON app cannot sign this contract type — refused before the device is touched (`asset` writes, `witness` writes) | | `not_a_witness` / `already_witness` / `not_proposal_owner` | Governance identity does not meet the operation's rule | | `already_approved` / `not_approved` / `proposal_expired` / `already_canceled` | Proposal voting conditions | -| `account_not_active` / `chain_parameter_unavailable` | `witness create`: the account is not activated on chain, or the node did not return `getAccountUpgradeCost` | +| `account_not_active` / `account_already_active` / `name_already_set` / `id_already_set` / `chain_parameter_unavailable` | Account activation/name/id conditions, or `witness create` could not read `getAccountUpgradeCost` | | `not_contract_deployer` | The account did not deploy that contract | | `already_issued_asset` / `not_an_issuer` | The account has already issued a TRC10, or has never issued one | | `not_in_ico_window` / `self_participation` | TRC10 ICO participation conditions | @@ -232,7 +232,7 @@ Common codes at exit **1** (execution — runtime failure): | `account_exists` / `wrong_keystore_password` | `import keystore`: the address is already in the wallet, or the file's own password is wrong (distinct from `auth_failed`, which is the master password). A file whose `mac` is missing or not hex is `invalid_keystore`, not a wrong password — hex case is not significant | | `internal_error` | Unexpected internal failure; message is intentionally generic | -Unexpected exceptions are **redacted** to `internal_error` with a generic message, so a library error that happens to echo secret material can never reach the envelope. The two tables above are a reading aid; `--json-schema`'s `errorCodes` is the complete index. +Unexpected exceptions are **redacted** to `internal_error` with a generic message, so a library error that happens to echo secret material can never reach the envelope. The two tables above are a reading aid; `--json-schema`'s `errorCodes` is the maintained discovery index, not a parser exhaustiveness guarantee. ### `error.details.matches` From 6b30d87803133572428ca45b9578d2e4fd14c3c9 Mon Sep 17 00:00:00 2001 From: "Leon.Zhang" Date: Sun, 30 Aug 2026 22:30:44 +0800 Subject: [PATCH 3/5] docs: align behavior docs with implementation --- ts/docs/commands/contract/deploy.md | 2 +- ts/docs/commands/tx/broadcast.md | 10 ++++++---- ts/docs/guide/scripting.md | 2 +- ts/docs/machine-interface.md | 2 +- ts/docs/troubleshooting.md | 6 +++--- ts/src/domain/errors/codes.ts | 2 +- 6 files changed, 13 insertions(+), 11 deletions(-) diff --git a/ts/docs/commands/contract/deploy.md b/ts/docs/commands/contract/deploy.md index 65bd48418..b07f8e6e6 100644 --- a/ts/docs/commands/contract/deploy.md +++ b/ts/docs/commands/contract/deploy.md @@ -32,7 +32,7 @@ An artifact is read for `.bytecode.object`, `.bytecode`, or `.evm.bytecode.objec **TRON needs an ABI.** Pass `--artifact` or `--abi`; passing both is an error. `--abi` is TRON-only, and the ABI's `constructor` entry needs a string `stateMutability` (`"nonpayable"` / `"payable"`) — `solc` emits it, but a hand-trimmed ABI or one from `solc` older than 0.5 may not. EVM deploys need no ABI when the types come from `--constructor-signature` or the arguments are self-describing. -Same execution model as other broadcast commands: `--dry-run` previews, `--sign-only` outputs a signed transaction for [`tx broadcast`](../tx/broadcast.md), `--build-only` an unsigned one, default returns at submission, `--wait` blocks until confirmed/failed. +Execution modes match the transaction-building write commands: `--dry-run` previews, `--sign-only` outputs a signed transaction for [`tx broadcast`](../tx/broadcast.md), `--build-only` an unsigned one, default returns at submission, `--wait` blocks until confirmed/failed. Fee flags follow the family — `--fee-limit` (TRON, default `100000000` SUN) or `--gas-limit` / `--max-fee` / `--priority-fee` / `--nonce` (EVM). Help tags each set, and using one on the other family is refused with `invalid_option`. diff --git a/ts/docs/commands/tx/broadcast.md b/ts/docs/commands/tx/broadcast.md index f386d1caa..67abcb01b 100644 --- a/ts/docs/commands/tx/broadcast.md +++ b/ts/docs/commands/tx/broadcast.md @@ -13,7 +13,7 @@ wallet-cli tx broadcast (--hex | --file | --transaction | -- Submits a transaction that was signed elsewhere, on TRON or EVM networks alike. No wallet unlock is needed; the transaction is already signed. The signed input can be **hex** — `--hex` inline or `--file` from a file (the format emitted by `--sign-only` and `tx sign`; protobuf on TRON, RLP `0x02…` on EVM) — or **JSON** — `--transaction` inline or `--tx-stdin` from stdin, both **TRON only**. Exactly one of the four; prefer `--file` for long hex. -A presigned transaction carries no network of its own, so pass `--network` to say which network to broadcast to (falls back to the config default network when omitted). +TRON signed transactions do not carry a network id. EVM signed transactions do carry an EIP-155 chain id, but `--network` still selects the endpoint and the CLI rejects the transaction if that chain id does not match. When omitted, `--network` falls back to the config default. ### Validation before submission @@ -78,7 +78,7 @@ wallet-cli tx broadcast --hex 0a02...9f31 --network tron:nile -o json ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"tx.broadcast","data":{"kind":"broadcast","stage":"submitted","txId":"72a315303323125708f426c77b94c5215afd8964ed27d67e49c29b56e29078f5"},"meta":{"durationMs":926,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"tx.broadcast","data":{"kind":"broadcast","stage":"submitted","txId":"72a315303323125708f426c77b94c5215afd8964ed27d67e49c29b56e29078f5","transaction":{"txId":"72a315303323125708f426c77b94c5215afd8964ed27d67e49c29b56e29078f5","contractType":"TransferContract","operation":"Transfer TRX","from":"TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ","to":"TVjsyZ7fYF3qLF6BQgPmTEZy1xrNNyVAAA","rawAmount":"1000000","permission":{"id":0,"name":"owner","threshold":1},"currentWeight":1,"missingWeight":0,"thresholdReached":true,"approved":[{"address":"TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ","weight":1}],"expiration":1784388720000,"expired":false,"signatures":1},"multiSignFeeSun":0},"meta":{"durationMs":926,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` ## Output @@ -87,8 +87,10 @@ wallet-cli tx broadcast --hex 0a02...9f31 --network tron:nile -o json | Stage | Fields | |---|---| -| default (submit) | `kind`, `stage: "submitted"`, `txId` | -| `--wait` (confirmed/failed) | above, plus `confirmed`, `blockNumber`, `failed`, and result fields — `netUsed` / `feeSun` on TRON, `gasUsed` / `feeWei` / `effectiveGasPriceWei` on EVM | +| default (submit, TRON) | `kind`, `stage: "submitted"`, `txId`, `transaction` (approval view), `multiSignFeeSun` | +| default (submit, EVM) | `kind`, `stage: "submitted"`, `txId`, and `alreadyKnown: true` when the node had already seen the transaction | +| `--wait` (confirmed/failed) | submit fields, plus `confirmed`, `blockNumber`, `failed`, and result fields — `netUsed` / `feeSun` on TRON, `gasUsed` / `feeWei` / `effectiveGasPriceWei` on EVM | +| `--dry-run` (TRON) | `kind`, `mode: "dry-run"`, `transaction` (approval view), `multiSignFeeSun` | | `--dry-run` (EVM) | `kind`, `mode: "dry-run"`, `txId`, `hash`, `address` (recovered signer), `to`, `rawAmount`, `fee` (`feeModel`, `maxCostWei`, `gasLimit`, `maxPerGasWei`), `tx`, and `checks[]` (`name`, `status` — `ok` / `warning` / `skipped` — and `detail`) | On EVM a node that already knows the transaction sets `alreadyKnown: true` on the submitted receipt rather than failing. diff --git a/ts/docs/guide/scripting.md b/ts/docs/guide/scripting.md index 7c2cc80fd..c2e5035f5 100644 --- a/ts/docs/guide/scripting.md +++ b/ts/docs/guide/scripting.md @@ -4,7 +4,7 @@ How to call wallet-cli from shell scripts and CI. This is the gentle version; th ## Discovering the surface -Before hard-coding anything, ask the CLI what it supports. One call returns every command, its flags as JSON Schema, which chain families it serves, and the complete error-code index: +Before hard-coding anything, ask the CLI what it supports. One call returns every command, its flags as JSON Schema, which chain families it serves, and the maintained error-code discovery index: ```bash wallet-cli --json-schema | jq '.commands[] | select(.id == "tx.send") | {families, examples}' diff --git a/ts/docs/machine-interface.md b/ts/docs/machine-interface.md index 8c8f13a63..d554026c5 100644 --- a/ts/docs/machine-interface.md +++ b/ts/docs/machine-interface.md @@ -200,7 +200,7 @@ Common codes at exit **1** (execution — runtime failure): | `rpc_error` | The node rejected or failed the request — a TRON API call, or a JSON-RPC method such as `eth_estimateGas` | | `invalid_node_response` | The node's answer contradicts the request or the protocol: a TRC10/exchange record whose id is not the one asked for, a `precision` outside 0..6, or a rate pair that is not a positive int32. These decide signed amounts, so the command stops rather than acting on them. List reads drop the offending record and keep the page | | `timeout` | Aborted waiting for network or device (`--timeout` exceeded) | -| `auth_required` | Master password required but not supplied | +| `auth_required` | Required credential was unavailable — a software master password, or Ledger app/device readiness | | `auth_failed` | Wrong master password (decryption failed) | | `signing_rejected` / `transaction_rejected` | Signing or broadcast rejected (device or chain) | | `watch_only_no_signer` | The account is watch-only and cannot sign | diff --git a/ts/docs/troubleshooting.md b/ts/docs/troubleshooting.md index f4b6f2210..913c4a7cc 100644 --- a/ts/docs/troubleshooting.md +++ b/ts/docs/troubleshooting.md @@ -1,6 +1,6 @@ # Troubleshooting -Remedies for humans, keyed by the [error codes](machine-interface.md#error-codes) defined in the machine interface (the single authority on what each code *is* — this page only covers what to *do*). For a code not covered here, the complete one-line index is `wallet-cli --json-schema | jq '.errorCodes'`. +Remedies for humans, keyed by the [error codes](machine-interface.md#error-codes) defined in the machine interface (the single authority on what each code *is* — this page only covers what to *do*). For a code not covered here, the maintained discovery index is `wallet-cli --json-schema | jq '.errorCodes'`; still fall back to the exit-code class if a runtime envelope carries a code outside that catalog. ## `usage_error` / `invalid_value` (exit 2) @@ -40,10 +40,10 @@ A nonce that is *ahead* of the account's next one is not an error: it is a `meta ## `tty_required` / `auth_required` (exit 2 / exit 1) -A secret was needed but none could be read. +A credential, secret, or signing-device approval was needed but none was available. - `tty_required` — no terminal is attached (CI, pipes). For commands with a stdin path, provide the matching `*-stdin` flag (`--password-stdin`, `--tx-stdin`). `import mnemonic`, `import private-key`, and `change-password` are interactive-only — they must run in a real TTY; there is no non-interactive alternative. -- `auth_required` — the command needs the master password; pass `--password-stdin` or run it interactively. +- `auth_required` — software signing needs the master password, or Ledger signing needs the right app/device state. For software accounts, pass `--password-stdin` or run interactively; for Ledger, unlock the device and open the TRON or Ethereum app that matches the account family. - `auth_failed` — the password was wrong (decryption failed); re-enter it. ## `timeout` (exit 1) diff --git a/ts/src/domain/errors/codes.ts b/ts/src/domain/errors/codes.ts index 57d5338f3..99695c385 100644 --- a/ts/src/domain/errors/codes.ts +++ b/ts/src/domain/errors/codes.ts @@ -37,7 +37,7 @@ export const ERROR_CODES = { watch_only_no_signer: "the selected account can be watched but cannot sign", // ── secrets, keystore, local files ──────────────────────────────────────── - auth_required: "the master password is needed and was not available", + auth_required: "a required credential or Ledger app/device approval was not available", auth_failed: "the master password was wrong", weak_password: "the proposed master password does not meet the strength rule", wrong_keystore_password: "the keystore file's own password was wrong", From 19716cd097df20fa024d88d9919067c500f5b758 Mon Sep 17 00:00:00 2001 From: "Leon.Zhang" Date: Mon, 31 Aug 2026 17:37:50 +0800 Subject: [PATCH 4/5] docs: correct remaining implementation mismatches --- README.md | 15 +++++++------ java/README.md | 13 ++++++++--- java/docs/guide/command-flow.md | 2 +- java/docs/guide/getting-started.md | 15 +++++++++++-- java/docs/guide/index.md | 4 ++-- ts/README.md | 22 +++++++++++-------- ts/docs/commands/account/activate.md | 4 +++- ts/docs/commands/account/set.md | 4 +++- ts/docs/commands/address/generate.md | 2 +- ts/docs/commands/asset/issue.md | 4 +++- ts/docs/commands/asset/participate.md | 4 +++- ts/docs/commands/asset/unfreeze.md | 4 +++- ts/docs/commands/asset/update.md | 4 +++- ts/docs/commands/backup.md | 4 +--- ts/docs/commands/chain/params.md | 2 +- ts/docs/commands/change-password.md | 6 ++--- ts/docs/commands/config.md | 2 +- ts/docs/commands/contact/add.md | 2 +- ts/docs/commands/contact/remove.md | 2 +- ts/docs/commands/contract/clear-abi.md | 4 +++- ts/docs/commands/contract/deploy.md | 4 +++- .../contract/set-origin-energy-limit.md | 4 +++- .../contract/set-user-resource-percent.md | 4 +++- ts/docs/commands/create.md | 2 +- ts/docs/commands/derive.md | 4 ++-- ts/docs/commands/exchange/index.md | 2 +- ts/docs/commands/gasfree/info.md | 2 +- ts/docs/commands/gasfree/trace.md | 2 +- ts/docs/commands/gasfree/transfer.md | 16 +++++++------- ts/docs/commands/import/keystore.md | 2 +- ts/docs/commands/import/mnemonic.md | 2 +- ts/docs/commands/import/private-key.md | 2 +- ts/docs/commands/permission/show.md | 2 +- ts/docs/commands/permission/update.md | 2 +- ts/docs/commands/rename.md | 2 +- ts/docs/commands/stake/cancel-unfreeze.md | 4 +++- ts/docs/commands/token/add.md | 2 +- ts/docs/commands/token/remove.md | 2 +- ts/docs/commands/tx/multisig.md | 2 +- ts/docs/commands/use.md | 2 +- ts/docs/commands/vote/cast.md | 2 +- ts/docs/commands/vote/list.md | 14 ++++++------ ts/docs/commands/vote/status.md | 12 +++++----- ts/docs/commands/witness/create.md | 4 +++- ts/docs/commands/witness/set-brokerage.md | 4 +++- ts/docs/commands/witness/update.md | 4 +++- ts/docs/concepts/accounts-and-hd.md | 2 +- ts/docs/concepts/networks.md | 4 +++- ts/docs/machine-interface.md | 21 +++++++++++------- 49 files changed, 153 insertions(+), 97 deletions(-) diff --git a/README.md b/README.md index b992cb920..363833d29 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@

wallet-cli

@@ -14,10 +14,10 @@ This repository holds **two independent implementations** that share the same purpose but target different users: -- **[Java](java/README.md)** — the original, full-featured reference CLI. An interactive prompt (REPL) you drive by hand. +- **[Java](java/README.md)** — the original, full-featured reference CLI. Run one-shot standard commands or start the interactive prompt (REPL). - **[TypeScript](ts/README.md)** — an agent-first rewrite for automation. Standard subcommands with a stable JSON envelope, built for scripts, CI, and AI agents. -Both manage the same kind of wallet on the same networks — your address is identical regardless of which you use. They cover the same TRON feature surface and differ in how you install and drive them. Pick one and read its own README for depth; this page gives you the basics of each so you can choose. +Both manage TRON wallets, but they are independent implementations rather than interchangeable account stores. Do not assume every derived account has the same address across implementations: check the recorded BIP44 path when migrating. The TypeScript implementation additionally supports selected EVM networks. ## At a glance @@ -26,10 +26,10 @@ Both manage the same kind of wallet on the same networks — your address is ide | **What it is** | The mature, full-feature reference CLI. | A newer rewrite focused on programmatic integration. | | **Runtime** | JVM — built with Gradle, run as a `.jar`. Uses the [Trident](https://github.com/tronprotocol/trident) SDK. | [Node.js](https://nodejs.org) **20+**. | | **Install** | `git clone` + `./gradlew build` (see [Setup](java/README.md#setup)) | `npm install -g @tron-walletcli/wallet-cli` | -| **How you drive it** | An **interactive prompt only** — start it, then type commands at `>`. | **One-shot subcommands** — `wallet-cli ` from your shell. Interactive prompts only for secret input. | +| **How you drive it** | One-shot standard commands, or an interactive prompt when run without a command / with `--interactive`. | **One-shot subcommands** — `wallet-cli ` from your shell. Interactive prompts only for secret input. | | **Command style** | PascalCase verbs: `RegisterWallet`, `SendCoin`, `GetBalance`. Amounts in **SUN** (1 TRX = 1,000,000 SUN). | Noun-verb subcommands: `create`, `tx send`, `account balance`, with `--flags`. | -| **Output for scripts** | Human-readable text. | Stable JSON via `-o json` ([`wallet-cli.result.v1`](ts/docs/machine-interface.md)) + fixed exit codes (`0`/`1`/`2`). | -| **Config / networks** | `config.conf` (net type + full node), or `SwitchNetwork` at runtime. Mainnet · Nile · Shasta · custom. | `--network` flag / `config` command. `tron:mainnet` · `tron:nile` · `tron:shasta`. | +| **Output for scripts** | Text by default; standard mode supports `--output json` and structured success/error envelopes. | Stable JSON via `-o json` ([`wallet-cli.result.v1`](ts/docs/machine-interface.md)) + fixed exit codes (`0`/`1`/`2`). | +| **Config / networks** | `config.conf` (net type + full node), or `SwitchNetwork` at runtime. Mainnet · Nile · Shasta · custom. | `--network` flag / `config` command. Three TRON networks plus Ethereum, Sepolia, BNB Smart Chain, and its testnet. | | **Signing** | Software keystore · Ledger. | Encrypted local keystore · Ledger. Secrets enter via stdin/TTY, never argv or dedicated secret env vars. | | **Feature scope** | **The full surface** — wallets and transfers, staking, voting and rewards, governance, contracts, TRC10, and the on-chain exchange. | **The full surface** — HD wallets, TRX/TRC20/TRC10 transfers, staking & delegation, voting & rewards, governance proposals & super-representative operation, contract call/deploy/governance, TRC10 issuance, the on-chain Bancor exchange, multi-sig, GasFree transfers, message signing, and on-chain queries. | | **Best for** | People at a terminal who want every TRON capability. | Scripting, CI pipelines, and AI agents. | @@ -37,11 +37,12 @@ Both manage the same kind of wallet on the same networks — your address is ide ## Java — get a taste -Interactive only. Build it, start the prompt, then type commands: +Build it, then either run a standard command or start the prompt: ```console $ git clone https://github.com/tronprotocol/wallet-cli.git $ cd wallet-cli && ./gradlew build && cd build/libs +$ java -jar wallet-cli.jar --output json --network nile get-balance --address T... $ java -jar wallet-cli.jar # opens the interactive prompt > RegisterWallet 123456 # create a keystore (password 123456) > Login # unlock it diff --git a/java/README.md b/java/README.md index 46462fe76..72ec9f94f 100644 --- a/java/README.md +++ b/java/README.md @@ -1,6 +1,6 @@ # wallet-cli — Java implementation -The original, full-featured implementation of wallet-cli: an interactive prompt (REPL) covering the complete TRON feature surface — managing accounts and keystores, TRX / TRC10 / TRC20 transfers, staking resources, voting for super representatives, deploying and calling smart contracts, Ledger hardware signing, and [GasFree](https://gasfree.io) gas-less transfers. All gRPC calls run on the [Trident SDK](https://github.com/tronprotocol/trident). +The original, full-featured implementation of wallet-cli. It supports both one-shot standard commands for scripts and an interactive prompt (REPL), covering the complete TRON feature surface — managing accounts and keystores, TRX / TRC10 / TRC20 transfers, staking resources, voting for super representatives, deploying and calling smart contracts, Ledger hardware signing, and [GasFree](https://gasfree.io) gas-less transfers. All gRPC calls run on the [Trident SDK](https://github.com/tronprotocol/trident). > For what wallet-cli is and how this compares to the scriptable, JSON-first [TypeScript implementation](../ts/README.md), see the [repository overview](../README.md). @@ -43,14 +43,21 @@ You can also switch networks at runtime with the [`SwitchNetwork`](docs/commands $ cd wallet-cli $ ./gradlew build $ cd build/libs - $ java -jar wallet-cli.jar + $ java -jar wallet-cli.jar --help ``` +With no command, wallet-cli opens the legacy interactive prompt. With a command, it uses the standard CLI; `--interactive` selects the prompt explicitly. Standard mode accepts global options such as `--network `, `--wallet`, `--grpc-endpoint`, and `--output `: + +```console +$ java -jar wallet-cli.jar --output json --network nile get-balance --address T... +$ java -jar wallet-cli.jar --interactive +``` + wallet-cli connects to java-tron via the gRPC protocol, which can be deployed locally or remotely. Configure the java-tron node IP and port in `src/main/resources/config.conf`, or use `SwitchNetwork` to switch among mainnet, testnets (Nile and Shasta), and custom networks. ## Quickstart -Build, create an account, and send your first transfer — all from the interactive prompt: +This quickstart uses the interactive prompt. For automation, pass a standard command to the jar and add `--output json`; see the [standard CLI contract](docs/standard-cli-contract-spec.md). ```console # 1. Build diff --git a/java/docs/guide/command-flow.md b/java/docs/guide/command-flow.md index 8fa03a444..8fbbf2ae3 100644 --- a/java/docs/guide/command-flow.md +++ b/java/docs/guide/command-flow.md @@ -1,6 +1,6 @@ # Command-line operation flow -A worked end-to-end example of an interactive session: build and run, register, back up, inspect, issue an asset, and transfer it. +A worked end-to-end example of the legacy interactive session: build and run, register, back up, inspect, issue an asset, and transfer it. For one-shot commands and JSON output, see [Getting started](getting-started.md#standard-cli). ```console $ cd wallet-cli diff --git a/java/docs/guide/getting-started.md b/java/docs/guide/getting-started.md index c1866ed0e..4448b4f1d 100644 --- a/java/docs/guide/getting-started.md +++ b/java/docs/guide/getting-started.md @@ -1,10 +1,10 @@ # Getting started -The first-run flow: build, create an account, unlock it, inspect it, and send your first TRX — all from the interactive prompt. +wallet-cli has two entry modes: a standard one-shot CLI for scripts and a legacy interactive prompt. The first-run flow below uses the prompt because it keeps account creation, unlock, inspection, and transfer in one session. ## Quickstart -Build, create an account, and send your first transfer — all from the interactive prompt: +Build, create an account, and send your first transfer from the interactive prompt: ```console # 1. Build @@ -26,6 +26,17 @@ $ java -jar wallet-cli.jar > On mainnet these commands move **real funds**. While learning, switch to a testnet with `SwitchNetwork` (Nile or Shasta) and top up from that network's faucet. +## Standard CLI + +Passing a command selects the standard CLI instead of the prompt. It supports text or JSON output and global network, wallet, and endpoint overrides: + +```console +$ java -jar wallet-cli.jar --output json --network nile get-balance --address T... +$ java -jar wallet-cli.jar --network nile send-coin --to T... --amount 1000000 --password-stdin +``` + +Run `java -jar wallet-cli.jar --help` for the command catalog and ` --help` for command options. The parsing, authentication, JSON envelope, and exit behavior are defined in the [standard CLI contract](../standard-cli-contract-spec.md). + ## How to create account You can create accounts by transferring funds to non-existing accounts, or by initiating a transaction to create an account using the **CreateAccount** command. Transferring to a non-existent account has a minimum restriction amount of **1 TRX**. Creating an account through the `CreateAccount` command still burns **1 TRX**. diff --git a/java/docs/guide/index.md b/java/docs/guide/index.md index bc3bfd7f4..77c6ff100 100644 --- a/java/docs/guide/index.md +++ b/java/docs/guide/index.md @@ -4,7 +4,7 @@ Task-oriented walkthroughs for wallet-cli (Java). | Guide | What it covers | |---|---| -| [Getting started](getting-started.md) | Build, create an account, unlock, and send your first TRX | -| [Command-line operation flow](command-flow.md) | A worked end-to-end interactive session | +| [Getting started](getting-started.md) | Standard CLI and interactive entry modes; build, create an account, and send TRX | +| [Command-line operation flow](command-flow.md) | A worked end-to-end legacy interactive session | For per-command reference, see the [command index](../commands/index.md); for TRON mechanics, see [concepts](../concepts/index.md). diff --git a/ts/README.md b/ts/README.md index ebf8e1a18..2e3b16948 100644 --- a/ts/README.md +++ b/ts/README.md @@ -27,19 +27,23 @@ The agent-first implementation of wallet-cli, built for automation: every comman ## Supported chains -Three TRON networks are supported today. Networks are identified by a canonical `family:chain` id (all `tron` today): +Seven built-in networks are supported. Networks use a canonical `family:chain` id: -| Network id | What it is | TRX value | -|---|---|---| -| `tron:mainnet` | Production mainnet | **Real funds** | -| `tron:nile` | Primary testnet (faucet at nileex.io) | None — use freely | -| `tron:shasta` | Alternate testnet | None | +| Network id | Family | Native coin | Environment | +|---|---|---|---| +| `tron:mainnet` | TRON | TRX | Mainnet — **real funds** | +| `tron:nile` | TRON | TRX | Testnet | +| `tron:shasta` | TRON | TRX | Testnet | +| `evm:1` | EVM | ETH | Ethereum mainnet — **real funds** | +| `evm:11155111` | EVM | ETH | Sepolia testnet | +| `evm:56` | EVM | BNB | BNB Smart Chain mainnet — **real funds** | +| `evm:97` | EVM | BNB | BNB Smart Chain testnet | -Your address is the same on every network, but balances, tokens, and transactions are isolated per network. Fees use TRON's `tron-resource` model (bandwidth + energy) rather than EVM gas — see [networks](docs/concepts/networks.md) and [energy & bandwidth](docs/concepts/energy-bandwidth.md). +One seed produces a TRON address and a different EVM address. Each address is reused within its family, while balances, tokens, and transactions remain isolated per network. TRON uses the `tron-resource` fee model (bandwidth + energy); EVM networks use gas. See [networks](docs/concepts/networks.md) and [energy & bandwidth](docs/concepts/energy-bandwidth.md). ## Install -**Prerequisites**: [Node.js](https://nodejs.org) **20 or later** (`node --version` to check). Ledger signing additionally needs a supported Ledger device with the TRON app installed — see the [Ledger guide](docs/guide/ledger.md). +**Prerequisites**: [Node.js](https://nodejs.org) **20 or later** (`node --version` to check). Ledger signing additionally needs a supported Ledger device with the app for the selected family installed — TRON for TRON accounts, Ethereum for EVM accounts. See the [Ledger guide](docs/guide/ledger.md). ```bash npm install -g @tron-walletcli/wallet-cli @@ -180,7 +184,7 @@ Every command supports `-o json` and then prints **exactly one** terminal JSON f TRON differs a lot from EVM chains in fees, accounts, and key permissions — these are worth understanding up front to avoid surprises: -- [Networks](docs/concepts/networks.md) — the three networks and the `family:chain` id +- [Networks](docs/concepts/networks.md) — built-in TRON/EVM networks and the `family:chain` id - [Accounts & HD](docs/concepts/accounts-and-hd.md) — mnemonics, derivation paths, account activation - [Energy & bandwidth](docs/concepts/energy-bandwidth.md) — TRON's resource-based fee model (in place of EVM gas) - [Security](docs/concepts/security.md) — keystore encryption, secret handling, multi-sig permissions diff --git a/ts/docs/commands/account/activate.md b/ts/docs/commands/account/activate.md index f9d74e980..0810db993 100644 --- a/ts/docs/commands/account/activate.md +++ b/ts/docs/commands/account/activate.md @@ -18,6 +18,8 @@ Use it only when an address needs to *exist* on its own — to be queryable, or Requires the payer account. The master password via `--password-stdin` is needed only when the selected mode signs — `--dry-run` and `--build-only` do not unlock the wallet and run without it. Watch-only accounts fail with `watch_only_no_signer` in a signing mode. +The Ledger TRON app cannot sign `AccountCreateContract`: Ledger accounts may use `--dry-run` or `--build-only`, but `--sign-only`, default submission, and `--wait` fail with `ledger_unsupported` before device interaction. + ## Options | Option | Description | @@ -88,7 +90,7 @@ echo "$PW" | wallet-cli account activate --address TNewAddr9k2fP7cW4bXm1sV8dRj6e ## Exit status -`0` submitted (or built/signed/dry-run in early-exit modes) · `1` execution failure (`account_already_active`, `watch_only_no_signer`, `auth_failed`, `insufficient_balance`, `rpc_error`, `timeout`) · `2` usage error (`invalid_value` — malformed address). +`0` submitted (or built/signed/dry-run in early-exit modes) · `1` execution failure (`account_already_active`, `watch_only_no_signer`, `ledger_unsupported`, `auth_failed`, `insufficient_balance`, `rpc_error`, `timeout`) · `2` usage error (`invalid_value` — malformed address). After a **confirmed** transaction the command reads the account back to verify the change took effect. That follow-up never turns an already-paid transaction into a command failure: a mismatch or an unreadable read is reported as a `meta.warnings` entry (`account_activate_postcheck_mismatch` / `account_activate_postcheck_unavailable`) with `success` still `true` and exit `0`. diff --git a/ts/docs/commands/account/set.md b/ts/docs/commands/account/set.md index 524606f90..d10ee2b4c 100644 --- a/ts/docs/commands/account/set.md +++ b/ts/docs/commands/account/set.md @@ -18,6 +18,8 @@ Sets the account's on-chain **name** (a display alias, up to 32 bytes) or its ** Requires the account. The master password via `--password-stdin` is needed only when the selected mode signs — `--dry-run` and `--build-only` do not unlock the wallet and run without it. Watch-only accounts fail with `watch_only_no_signer` in a signing mode. The account id's uniqueness is enforced on-chain — a taken id fails with `id_taken`. +Ledger support differs by field: the TRON app can sign `--name`, but cannot sign `--id` (`SetAccountIdContract`). A Ledger account may still build or dry-run either field; a signing mode with `--id` fails with `ledger_unsupported` before device interaction. + ## Options | Option | Description | @@ -90,7 +92,7 @@ echo "$PW" | wallet-cli account set --id acme-treasury-01 --network tron:nile -- ## Exit status -`0` submitted (or built/signed/dry-run in early-exit modes) · `1` execution failure (`name_already_set`, `id_already_set`, `id_taken`, `watch_only_no_signer`, `auth_failed`, `rpc_error`, `timeout`) · `2` usage error (`invalid_value`, `invalid_option` — malformed or missing name/id). +`0` submitted (or built/signed/dry-run in early-exit modes) · `1` execution failure (`name_already_set`, `id_already_set`, `id_taken`, `watch_only_no_signer`, `ledger_unsupported` — Ledger signing with `--id`, `auth_failed`, `rpc_error`, `timeout`) · `2` usage error (`invalid_value`, `invalid_option` — malformed or missing name/id). After a **confirmed** transaction the command reads the account back to verify the change took effect. That follow-up never turns an already-paid transaction into a command failure: a mismatch or an unreadable read is reported as a `meta.warnings` entry (`account_set_postcheck_mismatch` / `account_set_postcheck_unavailable`) with `success` still `true` and exit `0`. diff --git a/ts/docs/commands/address/generate.md b/ts/docs/commands/address/generate.md index 1c447b25b..62c925a63 100644 --- a/ts/docs/commands/address/generate.md +++ b/ts/docs/commands/address/generate.md @@ -60,7 +60,7 @@ wallet-cli address generate -o json ## Exit status -`0` success · `1` execution failure (`io_error`, `output_exists` — the `--out` target already exists and is never overwritten, `entropy_failure` — the system CSPRNG was unavailable) · `2` usage error (`invalid_value`). +`0` success · `1` execution failure (`io_error`, `entropy_failure` — the system CSPRNG was unavailable) · `2` usage error (`output_exists` — the `--out` target already exists and is never overwritten; `invalid_value`). ## See also diff --git a/ts/docs/commands/asset/issue.md b/ts/docs/commands/asset/issue.md index 6c1228b1f..55be9419d 100644 --- a/ts/docs/commands/asset/issue.md +++ b/ts/docs/commands/asset/issue.md @@ -30,6 +30,8 @@ Constraints are checked locally before broadcast: `--name` and `--abbr` are 1– **By default the command returns at submission** (`stage: "submitted"`), not confirmation — add `--wait` to block until confirmed/failed. Requires an account. The master password (via `--password-stdin`) is needed only by the modes that sign — `--dry-run` and `--build-only` do not unlock the wallet and run without it. Watch-only accounts fail with `watch_only_no_signer` in a signing mode. +The Ledger TRON app cannot sign TRC10 issuance contract types. Ledger accounts may dry-run or build unsigned hex, but signing modes fail with `ledger_unsupported` before device interaction. + ## Options | Option | Description | @@ -110,7 +112,7 @@ Definition fields: `name`, `abbr`, `totalSupply` (raw), `precision`, `price` (th ## Exit status -`0` submitted (or built/signed in early-exit modes) · `1` execution failure (`already_issued_asset` — this account already issued one, `insufficient_balance` — below the issuance fee, `watch_only_no_signer`, `auth_failed`) · `2` usage error (`missing_option` — a required flag is absent; `invalid_asset_name` — name or abbreviation outside 1–32 visible ASCII; `invalid_value` — rate, precision, dates, bandwidth limits, or frozen tranches out of range, or the rate exceeding int32 after conversion). +`0` submitted (or built/signed in early-exit modes) · `1` execution failure (`already_issued_asset` — this account already issued one, `insufficient_balance` — below the issuance fee, `watch_only_no_signer`, `ledger_unsupported`, `auth_failed`) · `2` usage error (`missing_option` — a required flag is absent; `invalid_asset_name` — name or abbreviation outside 1–32 visible ASCII; `invalid_value` — rate, precision, dates, bandwidth limits, or frozen tranches out of range, or the rate exceeding int32 after conversion). ## See also diff --git a/ts/docs/commands/asset/participate.md b/ts/docs/commands/asset/participate.md index 0967c1c5c..7b82ab30e 100644 --- a/ts/docs/commands/asset/participate.md +++ b/ts/docs/commands/asset/participate.md @@ -20,6 +20,8 @@ The acting account cannot be the token's own issuer. **By default the command returns at submission** (`stage: "submitted"`), not confirmation — add `--wait` to block until confirmed/failed. Requires an account. The master password (via `--password-stdin`) is needed only by the modes that sign — `--dry-run` and `--build-only` do not unlock the wallet and run without it. Watch-only accounts fail with `watch_only_no_signer` in a signing mode. +The Ledger TRON app cannot sign TRC10 issuance contract types. Ledger accounts may dry-run or build unsigned hex, but signing modes fail with `ledger_unsupported` before device interaction. + ## Options | Option | Description | @@ -80,7 +82,7 @@ echo "$PW" | wallet-cli asset participate 1000124 --pay 100 --network tron:nile ## Exit status -`0` submitted (or built/signed in early-exit modes) · `1` execution failure (`asset_not_found` — no such token, `not_in_ico_window` — outside the funding window, `self_participation` — you issued this token, `insufficient_balance`, `watch_only_no_signer`, `auth_failed`) · `2` usage error (`missing_option` — no `--pay`; `invalid_amount` — `--pay` is not a decimal number, or has more than 6 decimal places; `invalid_value` — `--pay` ≤ 0, or too small to buy one unit). +`0` submitted (or built/signed in early-exit modes) · `1` execution failure (`asset_not_found` — no such token, `not_in_ico_window` — outside the funding window, `self_participation` — you issued this token, `insufficient_balance`, `watch_only_no_signer`, `ledger_unsupported`, `auth_failed`) · `2` usage error (`missing_option` — no `--pay`; `invalid_amount` — `--pay` is not a decimal number, or has more than 6 decimal places; `invalid_value` — `--pay` ≤ 0, or too small to buy one unit). ## See also diff --git a/ts/docs/commands/asset/unfreeze.md b/ts/docs/commands/asset/unfreeze.md index a2ee1cff8..25a2cc4eb 100644 --- a/ts/docs/commands/asset/unfreeze.md +++ b/ts/docs/commands/asset/unfreeze.md @@ -22,6 +22,8 @@ This is unrelated to [`stake unfreeze`](../stake/unfreeze.md), which releases st **By default the command returns at submission** (`stage: "submitted"`), not confirmation — add `--wait` to block until confirmed/failed. Requires an account. The master password (via `--password-stdin`) is needed only by the modes that sign — `--dry-run` and `--build-only` do not unlock the wallet and run without it. Watch-only accounts fail with `watch_only_no_signer` in a signing mode. +The Ledger TRON app cannot sign TRC10 issuance contract types. Ledger accounts may dry-run or build unsigned hex, but signing modes fail with `ledger_unsupported` before device interaction. + ## Options This command has no options of its own. @@ -79,7 +81,7 @@ echo "$PW" | wallet-cli asset unfreeze --network tron:nile --wait --password-std ## Exit status -`0` submitted (or built/signed in early-exit modes) · `1` execution failure (`not_an_issuer` — this account has not issued a TRC10, `no_frozen_supply`, `not_yet_unfreezable` — nothing has matured yet, `watch_only_no_signer`, `auth_failed`) · `2` usage error. +`0` submitted (or built/signed in early-exit modes) · `1` execution failure (`not_an_issuer` — this account has not issued a TRC10, `no_frozen_supply`, `not_yet_unfreezable` — nothing has matured yet, `watch_only_no_signer`, `ledger_unsupported`, `auth_failed`) · `2` usage error. ## See also diff --git a/ts/docs/commands/asset/update.md b/ts/docs/commands/asset/update.md index 379451e04..61f3dc9ba 100644 --- a/ts/docs/commands/asset/update.md +++ b/ts/docs/commands/asset/update.md @@ -21,6 +21,8 @@ Pass only the fields you are changing. The others are read from chain and writte **By default the command returns at submission** (`stage: "submitted"`), not confirmation — add `--wait` to block until confirmed/failed. Requires an account. The master password (via `--password-stdin`) is needed only by the modes that sign — `--dry-run` and `--build-only` do not unlock the wallet and run without it. Watch-only accounts fail with `watch_only_no_signer` in a signing mode. +The Ledger TRON app cannot sign TRC10 issuance contract types. Ledger accounts may dry-run or build unsigned hex, but signing modes fail with `ledger_unsupported` before device interaction. + ## Options | Option | Description | @@ -82,7 +84,7 @@ The four fields are `url`, `description`, `freeAssetNetLimit`, and `publicFreeAs ## Exit status -`0` submitted (or built/signed in early-exit modes) · `1` execution failure (`not_an_issuer` — this account has not issued a TRC10, `watch_only_no_signer`, `auth_failed`) · `2` usage error (`missing_option` — no field given; `invalid_value` — URL or description too long, bandwidth limits out of range). +`0` submitted (or built/signed in early-exit modes) · `1` execution failure (`not_an_issuer` — this account has not issued a TRC10, `watch_only_no_signer`, `ledger_unsupported`, `auth_failed`) · `2` usage error (`missing_option` — no field given; `invalid_value` — URL or description too long, bandwidth limits out of range). ## See also diff --git a/ts/docs/commands/backup.md b/ts/docs/commands/backup.md index 2310fa7fb..bbdc48b70 100644 --- a/ts/docs/commands/backup.md +++ b/ts/docs/commands/backup.md @@ -162,9 +162,7 @@ Both forms are local commands — no `chain` block — and they carry different ## Exit status -`0` success · `1` execution failure (`not_exportable` — watch-only or Ledger, `invalid_value` — no such account, `auth_failed`, `io_error` — path not writable) · `2` usage error (`output_exists` — the target file already exists and is never overwritten; `invalid_value` — a record filter without `--records`, `--keystore` / `--out` with `--records`, or a bad time / limit / offset). - -`invalid_value` appears under both exit codes here: an unresolvable account reference is exit `1`, a malformed call is exit `2`. Branch on the exit code first. +`0` success · `1` execution failure (`account_not_found` — no such account; `not_exportable` — watch-only or Ledger; `auth_failed`; `io_error` — path not writable) · `2` usage error (`output_exists` — the target file already exists and is never overwritten; `invalid_value` — a record filter without `--records`, `--keystore` / `--out` with `--records`, or a bad time / limit / offset). ## See also diff --git a/ts/docs/commands/chain/params.md b/ts/docs/commands/chain/params.md index 7cdf31b07..32db6f256 100644 --- a/ts/docs/commands/chain/params.md +++ b/ts/docs/commands/chain/params.md @@ -80,7 +80,7 @@ wallet-cli chain params --network tron:nile -o json ## Exit status -`0` success · `1` execution failure (`rpc_error`; `not_found` — `--key` doesn't exist) · `2` usage error (`invalid_value`). +`0` success · `1` execution failure (`rpc_error`) · `2` usage error (`not_found` — `--key` doesn't exist; `invalid_value`). ## See also diff --git a/ts/docs/commands/change-password.md b/ts/docs/commands/change-password.md index 320b10e97..dd63cc452 100644 --- a/ts/docs/commands/change-password.md +++ b/ts/docs/commands/change-password.md @@ -17,7 +17,7 @@ The master password decrypts **every software wallet's** keystore, so changing i The flow: 1. **Verify** — enter the current master password; it must decrypt an existing keystore (`auth_failed` otherwise, nothing touched). -2. **Set** — enter the new password twice (mismatch → retry; policy failure → `weak_password`). +2. **Set** — enter the new password twice. A mismatch or policy failure is rejected at the prompt and asks again. 3. **Confirm** — the command lists how many software wallets will be re-encrypted; `[y/N]` (skipped with `--yes`). Declining aborts with no changes. 4. **Re-encrypt atomically** — each keystore: decrypt with old → encrypt with new → write temp file → fsync; only after *all* succeed are files renamed into place. Any failure rolls everything back and reports `io_error` — the old keystores stay valid. @@ -48,11 +48,11 @@ wallet-cli change-password ## Output -This command is interactive: the receipt is printed to the terminal (listing the re-encrypted software wallets, never any secret), and even with `-o json` it produces no structured machine-readable output. Local command — no `chain` block. +This command is interactive. In text mode, the receipt lists the re-encrypted software wallets and never includes secret material. In JSON mode, `data.wallets` contains those wallet labels/ids and `data.count` contains their count. Local command — no `chain` block. ## Exit status -`0` changed · `1` execution failure (`tty_required` — no TTY for interactive input; `auth_failed`; `weak_password`; `no_software_wallet` — nothing to re-encrypt; `io_error` — write failed, rolled back) · `2` usage error. +`0` changed · `1` execution failure (`auth_failed`; `no_software_wallet` — nothing to re-encrypt; `invalid_value` — a referenced encrypted wallet blob is missing; `io_error` — write failed, rolled back) · `2` usage error (`tty_required` — no TTY for interactive input; `invalid_value` — the new password equals the current one; `aborted` — confirmation declined). ## See also diff --git a/ts/docs/commands/config.md b/ts/docs/commands/config.md index cae815413..6ac78bde2 100644 --- a/ts/docs/commands/config.md +++ b/ts/docs/commands/config.md @@ -149,7 +149,7 @@ An unset network field is **absent** from the view rather than present and empty ## Exit status -`0` success · `1` execution failure (`invalid_config` — `config.yaml` is unreadable or not valid YAML; `insecure_config` — it holds service credentials but is a symlink or group/world-readable, so `chmod 600` it) · `2` usage error (`invalid_value` — unknown key, a read-only key given a value, or an unsupported `networks..`). See [machine-interface](../machine-interface.md). +`0` success · `1` execution failure (`io_error` — an atomic config write failed) · `2` usage error (`invalid_config` — `config.yaml` is unreadable or not valid YAML; `insecure_config` — it holds service credentials but is a symlink or group/world-readable, so `chmod 600` it; `invalid_value` — unknown key, a read-only key given a value, or an unsupported `networks..`). See [machine-interface](../machine-interface.md). ## See also diff --git a/ts/docs/commands/contact/add.md b/ts/docs/commands/contact/add.md index 89bc21521..d6bded037 100644 --- a/ts/docs/commands/contact/add.md +++ b/ts/docs/commands/contact/add.md @@ -62,7 +62,7 @@ wallet-cli contact add alice TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub --note "Alice ma ## Exit status -`0` success · `1` execution failure (`already_exists` — the name is taken, `limit_exceeded` — the address book is full). The address book is a local file: `encoding_error` if it cannot be decoded, `insecure_permissions` if it is a symlink or group/world-readable (`chmod 600` it). · `2` usage error (`invalid_address` — the address is not valid for its family; `invalid_value` — an invalid name or note). +`0` success · `1` execution failure (`encoding_error` — the local address book cannot be decoded; `insecure_permissions` — it is a symlink or group/world-readable, so run `chmod 600`) · `2` usage error (`already_exists` — the name or address is taken; `limit_exceeded` — the address book is full; `invalid_address` — the address is not valid for a supported family; `invalid_value` — invalid name or note). ## See also diff --git a/ts/docs/commands/contact/remove.md b/ts/docs/commands/contact/remove.md index b970005f1..f5bc26f92 100644 --- a/ts/docs/commands/contact/remove.md +++ b/ts/docs/commands/contact/remove.md @@ -45,7 +45,7 @@ wallet-cli contact remove bob -o json ## Exit status -`0` success · `1` execution failure (`not_found` — no such contact, `encoding_error`, `insecure_permissions`) · `2` usage error. +`0` success · `1` execution failure (`encoding_error`, `insecure_permissions`) · `2` usage error (`contact_not_found` — no contact by that name; `invalid_value`). ## See also diff --git a/ts/docs/commands/contract/clear-abi.md b/ts/docs/commands/contract/clear-abi.md index 1a081f116..fc92f5781 100644 --- a/ts/docs/commands/contract/clear-abi.md +++ b/ts/docs/commands/contract/clear-abi.md @@ -22,6 +22,8 @@ Only the contract's deployer can do this — the address the chain records as th **By default the command returns at submission** (`stage: "submitted"`), not confirmation — add `--wait` to block until confirmed/failed. Requires an account. The master password (via `--password-stdin`) is needed only by the modes that sign — `--dry-run` and `--build-only` do not unlock the wallet and run without it. Watch-only accounts fail with `watch_only_no_signer` in a signing mode. +The Ledger TRON app cannot parse this governance contract type. Ledger accounts may dry-run or build, but signing modes fail with `ledger_unsupported` before device interaction. + ## Options | Option | Description | @@ -74,7 +76,7 @@ echo "$PW" | wallet-cli contract clear-abi TQ5nJ8mV...4wRe --network tron:nile - ## Exit status -`0` submitted (or built/signed in early-exit modes) · `1` execution failure (`contract_not_found` — no such contract, `not_contract_deployer`, `watch_only_no_signer`, `auth_failed`) · `2` usage error (`invalid_value` — malformed address). +`0` submitted (or built/signed in early-exit modes) · `1` execution failure (`contract_not_found` — no such contract, `not_contract_deployer`, `watch_only_no_signer`, `ledger_unsupported`, `auth_failed`) · `2` usage error (`invalid_value` — malformed address). ## See also diff --git a/ts/docs/commands/contract/deploy.md b/ts/docs/commands/contract/deploy.md index b07f8e6e6..bc26cfef9 100644 --- a/ts/docs/commands/contract/deploy.md +++ b/ts/docs/commands/contract/deploy.md @@ -38,6 +38,8 @@ Fee flags follow the family — `--fee-limit` (TRON, default `100000000` SUN) or Requires an account. The master password (via `--password-stdin`) is needed only by the modes that sign — `--dry-run` and `--build-only` do not unlock the wallet and run without it. Watch-only accounts fail with `watch_only_no_signer` in a signing mode. +On TRON, the Ledger app cannot sign `CreateSmartContract`; Ledger accounts may dry-run or build, but signing modes fail with `ledger_unsupported`. This restriction does not apply to EVM deployment through the Ethereum app. + ## Options | Option | Description | @@ -139,7 +141,7 @@ echo "$PW" | wallet-cli contract deploy --artifact ./build/contracts/Token.json ## Exit status -`0` submitted (or built/signed/dry-run in early-exit modes) · `1` execution failure (`watch_only_no_signer`, `auth_failed`, `rpc_error`, `timeout`) · `2` usage error — `file_not_found` (no artifact/bytecode file at that path), or `invalid_value` for: none or more than one of `--artifact` / `--code` / `--code-file`; an artifact that is not JSON, has no creation bytecode, or holds only `"0x"`; `--constructor-args` with no type source; `--constructor-params` or `--constructor-signature` alongside `--artifact`; a TRON deploy with neither `--abi` nor `--artifact`, or with both; `--constructor-signature` on TRON; an ABI constructor without a string `stateMutability`. +`0` submitted (or built/signed/dry-run in early-exit modes) · `1` execution failure (`watch_only_no_signer`, `ledger_unsupported` — TRON signing only, `auth_failed`, `rpc_error`, `timeout`) · `2` usage error — `file_not_found` (no artifact/bytecode file at that path), or `invalid_value` for: none or more than one of `--artifact` / `--code` / `--code-file`; an artifact that is not JSON, has no creation bytecode, or holds only `"0x"`; `--constructor-args` with no type source; `--constructor-params` or `--constructor-signature` alongside `--artifact`; a TRON deploy with neither `--abi` nor `--artifact`, or with both; `--constructor-signature` on TRON; an ABI constructor without a string `stateMutability`. ## See also diff --git a/ts/docs/commands/contract/set-origin-energy-limit.md b/ts/docs/commands/contract/set-origin-energy-limit.md index 1a04f6eb2..0c96fd486 100644 --- a/ts/docs/commands/contract/set-origin-energy-limit.md +++ b/ts/docs/commands/contract/set-origin-energy-limit.md @@ -24,6 +24,8 @@ Only the contract's deployer can do this; the current value is in [`contract inf **By default the command returns at submission** (`stage: "submitted"`), not confirmation — add `--wait` to block until confirmed/failed. Requires an account. The master password (via `--password-stdin`) is needed only by the modes that sign — `--dry-run` and `--build-only` do not unlock the wallet and run without it. Watch-only accounts fail with `watch_only_no_signer` in a signing mode. +The Ledger TRON app cannot parse this governance contract type. Ledger accounts may dry-run or build, but signing modes fail with `ledger_unsupported` before device interaction. + ## Options | Option | Description | @@ -80,7 +82,7 @@ echo "$PW" | wallet-cli contract set-origin-energy-limit TQ5nJ8mV...4wRe 5000000 ## Exit status -`0` submitted (or built/signed in early-exit modes) · `1` execution failure (`contract_not_found` — no such contract, `not_contract_deployer`, `watch_only_no_signer`, `auth_failed`) · `2` usage error (`invalid_value` — malformed address, or energy not an integer > 0). +`0` submitted (or built/signed in early-exit modes) · `1` execution failure (`contract_not_found` — no such contract, `not_contract_deployer`, `watch_only_no_signer`, `ledger_unsupported`, `auth_failed`) · `2` usage error (`invalid_value` — malformed address, or energy not an integer > 0). ## See also diff --git a/ts/docs/commands/contract/set-user-resource-percent.md b/ts/docs/commands/contract/set-user-resource-percent.md index 99a40eb2b..ea5e503d4 100644 --- a/ts/docs/commands/contract/set-user-resource-percent.md +++ b/ts/docs/commands/contract/set-user-resource-percent.md @@ -24,6 +24,8 @@ Only the contract's deployer can do this; the current value is in [`contract inf **By default the command returns at submission** (`stage: "submitted"`), not confirmation — add `--wait` to block until confirmed/failed. Requires an account. The master password (via `--password-stdin`) is needed only by the modes that sign — `--dry-run` and `--build-only` do not unlock the wallet and run without it. Watch-only accounts fail with `watch_only_no_signer` in a signing mode. +The Ledger TRON app cannot parse this governance contract type. Ledger accounts may dry-run or build, but signing modes fail with `ledger_unsupported` before device interaction. + ## Options | Option | Description | @@ -82,7 +84,7 @@ echo "$PW" | wallet-cli contract set-user-resource-percent TQ5nJ8mV...4wRe 100 - ## Exit status -`0` submitted (or built/signed in early-exit modes) · `1` execution failure (`contract_not_found` — no such contract, `not_contract_deployer`, `watch_only_no_signer`, `auth_failed`) · `2` usage error (`invalid_value` — malformed address, or percent outside 0–100). +`0` submitted (or built/signed in early-exit modes) · `1` execution failure (`contract_not_found` — no such contract, `not_contract_deployer`, `watch_only_no_signer`, `ledger_unsupported`, `auth_failed`) · `2` usage error (`invalid_value` — malformed address, or percent outside 0–100). ## See also diff --git a/ts/docs/commands/create.md b/ts/docs/commands/create.md index 61ca9e159..e76d7691c 100644 --- a/ts/docs/commands/create.md +++ b/ts/docs/commands/create.md @@ -70,7 +70,7 @@ printf '%s' "$PW" | wallet-cli create --label main --password-stdin -o json | `index` | number | HD derivation index (0 for the first account) | | `active` | boolean | Whether it became the active account | | `addresses` | object | One address per family the account can produce: `tron` (base58) and `evm` (`0x`, EIP-55 checksummed) | -| `derivationPath` | object | The BIP44 template each address came from: `{"tron":"m/44'/195'/0'/0/","evm":"m/44'/60'/0'/0/"}` | +| `derivationPath` | object | The BIP44 path each address came from: `{"tron":"m/44'/195'/'/0/0","evm":"m/44'/60'/0'/0/"}` | | `seedId` | string | Owning seed wallet id | ## Exit status diff --git a/ts/docs/commands/derive.md b/ts/docs/commands/derive.md index c4644c32a..5e6224452 100644 --- a/ts/docs/commands/derive.md +++ b/ts/docs/commands/derive.md @@ -46,7 +46,7 @@ printf '%s' "$PW" | wallet-cli derive --seed-id wlt_y8cz6xda --password-stdin -o ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"derive","data":{"status":"created","accountId":"wlt_y8cz6xda.1","label":"main-1","type":"seed","index":1,"active":true,"addresses":{"tron":"TWCa1W6BkcXZnRGxeZZw9jh8eNgULDVGzj","evm":"0x2395227A93465175c6D6EAF2B9d37c2cC0BaB60c"},"seedId":"wlt_y8cz6xda","derivationPath":{"tron":"m/44'/195'/0'/0/1","evm":"m/44'/60'/0'/0/1"}},"meta":{"durationMs":1013,"warnings":[]}} +{"schema":"wallet-cli.result.v1","success":true,"command":"derive","data":{"status":"created","accountId":"wlt_y8cz6xda.1","label":"main-1","type":"seed","index":1,"active":true,"addresses":{"tron":"TWCa1W6BkcXZnRGxeZZw9jh8eNgULDVGzj","evm":"0x2395227A93465175c6D6EAF2B9d37c2cC0BaB60c"},"seedId":"wlt_y8cz6xda","derivationPath":{"tron":"m/44'/195'/1'/0/0","evm":"m/44'/60'/0'/0/1"}},"meta":{"durationMs":1013,"warnings":[]}} ``` ## Output @@ -62,7 +62,7 @@ printf '%s' "$PW" | wallet-cli derive --seed-id wlt_y8cz6xda --password-stdin -o | `index` | number | HD derivation index | | `active` | boolean | Always `true` (the new account is made active) | | `addresses` | object | One address per family the account can produce: `tron` (base58) and `evm` (`0x`, EIP-55 checksummed) | -| `derivationPath` | object | The BIP44 template each address came from: `{"tron":"m/44'/195'/0'/0/","evm":"m/44'/60'/0'/0/"}` | +| `derivationPath` | object | The BIP44 path each address came from: `{"tron":"m/44'/195'/'/0/0","evm":"m/44'/60'/0'/0/"}` | | `seedId` | string | Owning seed wallet id | ## Exit status diff --git a/ts/docs/commands/exchange/index.md b/ts/docs/commands/exchange/index.md index 4087233fc..902eb2f5e 100644 --- a/ts/docs/commands/exchange/index.md +++ b/ts/docs/commands/exchange/index.md @@ -14,7 +14,7 @@ Pairs trade **TRX against TRC10** — never TRC20 — and settle instantly again `--raw-*` variants when the exact base-unit quantity matters — they are used verbatim. - **TRX's token id on chain is the underscore `_`.** Write `TRX` (any case) or an asset id; `_` is accepted too. json shows what actually went on chain, so TRX appears there as `"_"`. -**Pricing follows the curve, not the ratio.** The ratio of the two reserves is a marginal quote — true only for a trade of size zero. A real trade moves along the curve, and the larger it is relative to the reserves, the worse the price it gets. That gap is the slippage, which is why [`exchange trade`](trade.md) always requires a floor (`--min-received` or `--slippage`), and why no command here prints a "price". To price a specific amount, run `exchange trade --dry-run` against the current reserves. Reserves are also capped by the chain parameter `getExchangeBalanceLimit`. +**Pricing follows the curve, not the ratio.** The ratio of the two reserves is a marginal quote — true only for a trade of size zero. A real trade moves along the curve, and the larger it is relative to the reserves, the worse the price it gets. That gap is the slippage. [`exchange trade`](trade.md) accepts one optional floor (`--min-received`, `--raw-min-received`, or `--slippage`); omitting all three is allowed but emits a warning and submits the protocol minimum `expected = 1`, which provides no practical slippage protection. No command here prints a "price". To price a specific amount, run `exchange trade --dry-run` against the current reserves. Reserves are also capped by the chain parameter `getExchangeBalanceLimit`. **Tokens are named by id only in this group** — `TRX` or a numeric asset id, never a token name. Pairs are written with a colon (`--pair TRX:1000123`, `--amounts 10000:500000`), and TRC10 names may legally contain colons, so allowing names would make `--pair` ambiguous. Resolve a name to its id with [`asset info `](../asset/info.md). diff --git a/ts/docs/commands/gasfree/info.md b/ts/docs/commands/gasfree/info.md index 64de9c8cf..33aeed700 100644 --- a/ts/docs/commands/gasfree/info.md +++ b/ts/docs/commands/gasfree/info.md @@ -57,7 +57,7 @@ wallet-cli gasfree info --account main --network tron:nile -o json ## Exit status -`0` success · `1` execution failure (`gasfree_credentials_missing`, `gasfree_integrity` — the provider's fee metadata disagreed between the token list and the address response, `provider_error` — service error / rate limit, `unsupported_network`) · `2` usage error (`invalid_value`). +`0` success · `1` execution failure (`gasfree_integrity` — the provider's fee metadata disagreed between the token list and the address response, `provider_error` — service error / rate limit) · `2` usage error (`gasfree_credentials_missing`, `unsupported_network`, `invalid_value`). ## See also diff --git a/ts/docs/commands/gasfree/trace.md b/ts/docs/commands/gasfree/trace.md index 571028ad4..3aa688581 100644 --- a/ts/docs/commands/gasfree/trace.md +++ b/ts/docs/commands/gasfree/trace.md @@ -58,7 +58,7 @@ wallet-cli gasfree trace 7f3e9a02-58c1-4d2e-b6a4-91d0c3f8e527 --network tron:nil ## Exit status -`0` success · `1` execution failure (`gasfree_credentials_missing`, `not_found` — no such trace id, `gasfree_integrity`, `provider_error`, `unsupported_network`) · `2` usage error (`invalid_value`). +`0` success · `1` execution failure (`not_found` — no such trace id, `gasfree_integrity`, `provider_error`) · `2` usage error (`gasfree_credentials_missing`, `unsupported_network`, `invalid_value`). A `FAILED` transfer is a successful query: the envelope stays `success: true` at exit `0`, and `data.failureReason` carries the provider's explanation. diff --git a/ts/docs/commands/gasfree/transfer.md b/ts/docs/commands/gasfree/transfer.md index fb1ade637..cf5da6e07 100644 --- a/ts/docs/commands/gasfree/transfer.md +++ b/ts/docs/commands/gasfree/transfer.md @@ -43,7 +43,7 @@ echo "$PW" | wallet-cli gasfree transfer --to TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub ```console ⏳ Submitted to GasFree — send 25 USDT Trace ID 7f3e9a02-58c1-4d2e-b6a4-91d0c3f8e527 - From TVjsyZ7fYF3qCcNaMxN5PMWmSgYcCyqZfw (GasFree address) + From TNER12mMVWruqopsW9FQtKxCGfZcEtb3ER (GasFree address) To TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub Fee 0.5 USDT Total 25.5 USDT @@ -52,7 +52,7 @@ echo "$PW" | wallet-cli gasfree transfer --to TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"gasfree.transfer","data":{"kind":"gasfree-transfer","stage":"submitted","traceId":"7f3e9a02-58c1-4d2e-b6a4-91d0c3f8e527","token":"USDT","amount":"25000000","serviceFee":"500000","activateFee":"0","totalDeducted":"25500000","from":"TVjsyZ7fYF3qCcNaMxN5PMWmSgYcCyqZfw","to":"TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub","nonce":4},"meta":{"durationMs":650,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"gasfree.transfer","data":{"kind":"gasfree-transfer","stage":"submitted","traceId":"7f3e9a02-58c1-4d2e-b6a4-91d0c3f8e527","token":"USDT","tokenAddress":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf","decimals":6,"amount":"25000000","serviceFee":"500000","activateFee":"0","authorizedMaxFee":"500000","totalDeducted":"25500000","owner":"TMVQGm1qAQYVdetCeGRRkTWYYrLXuHK2HC","from":"TNER12mMVWruqopsW9FQtKxCGfZcEtb3ER","to":"TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub","serviceProvider":"TKtWbdzEq5ss9vTS9kwRhBp5mXmBfBns3E","nonce":"8","deadline":"1700000060"},"meta":{"durationMs":650,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` Add `--wait` to poll to a terminal state, with the on-chain txid and actual deduction: @@ -65,7 +65,7 @@ echo "$PW" | wallet-cli gasfree transfer --to TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub ✅ Sent 25 USDT via GasFree Trace ID a41b6c88-0d2f-4e73-9a05-3c7d81f2b964 TxID d2e... - From TVjsyZ7fYF3qCcNaMxN5PMWmSgYcCyqZfw (GasFree address) + From TNER12mMVWruqopsW9FQtKxCGfZcEtb3ER (GasFree address) To TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub Fee 0.5 USDT Total 25.5 USDT @@ -80,14 +80,14 @@ wallet-cli gasfree transfer --to TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub --amount 25 ```console ⏳ Dry run — GasFree transfer 25 USDT (not submitted) - From TVjsyZ7fYF3qCcNaMxN5PMWmSgYcCyqZfw (GasFree address, not activated) + From TNER12mMVWruqopsW9FQtKxCGfZcEtb3ER (GasFree address, not activated) To TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub Fee 1.5 USDT (0.5 service + 1.0 activation) Total 26.5 USDT ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"gasfree.transfer","data":{"kind":"gasfree-transfer","mode":"dry-run","token":"USDT","amount":"25000000","serviceFee":"500000","activateFee":"1000000","totalDeducted":"26500000","from":"TVjsyZ7fYF3qCcNaMxN5PMWmSgYcCyqZfw","to":"TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub","nonce":0},"meta":{"durationMs":210,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"gasfree.transfer","data":{"kind":"gasfree-transfer","stage":"dry-run","token":"USDT","tokenAddress":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf","decimals":6,"amount":"25000000","serviceFee":"500000","activateFee":"1000000","authorizedMaxFee":"1500000","totalDeducted":"26500000","owner":"TMVQGm1qAQYVdetCeGRRkTWYYrLXuHK2HC","from":"TNER12mMVWruqopsW9FQtKxCGfZcEtb3ER","to":"TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub","serviceProvider":"TKtWbdzEq5ss9vTS9kwRhBp5mXmBfBns3E","nonce":"8","deadline":"1700000060"},"meta":{"durationMs":210,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` ## Output @@ -96,16 +96,16 @@ wallet-cli gasfree transfer --to TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub --amount 25 | Mode | Fields | |---|---| -| default (submit) | `kind: "gasfree-transfer"`, `stage: "submitted"`, `traceId`, `token`, `tokenAddress`, `amount`, `serviceFee`, `activateFee`, `authorizedMaxFee`, `totalDeducted`, `from`, `to`, `nonce`, `deadline`, `serviceProvider`, plus `toContact` when `--to` was a contact name | +| default (submit) | `kind: "gasfree-transfer"`, `stage: "submitted"`, `traceId`, `token`, `tokenAddress`, `decimals`, `amount`, `serviceFee`, `activateFee`, `authorizedMaxFee`, `totalDeducted`, `owner`, `from`, `to`, `nonce`, `deadline`, `serviceProvider`, plus `toContact` when `--to` was a contact name | | `--wait` (confirmed) | the above, but `stage: "confirmed"`, plus `confirmed`, `state` (`SUCCEED` / `FAILED`), `failed`, and `txId` | | `--wait` (failed) | the same fields, but `stage: "failed"`, `failed: true`, `state: "FAILED"`, and `failureReason` carrying the provider's explanation | -| `--dry-run` | `kind`, `mode: "dry-run"`, `token`, `amount`, `serviceFee`, `activateFee`, `totalDeducted`, `from`, `to`; no `traceId` | +| `--dry-run` | the default fields except `traceId`, with `stage: "dry-run"`; no signature or submission | A provider-side failure still leaves the envelope at `success: true` and exit `0` — the command completed; the transfer did not. Branch on `data.stage` / `data.state`, not on the exit code. See [script safety](../../machine-interface.md#script-safety-never-mistake-submitted-for-confirmed). ## Exit status -`0` submitted (or dry-run) · `1` execution failure (`gasfree_credentials_missing`, `insufficient_token_balance` — token balance < amount + service fee [+ activation fee], `unsupported_token`, `gasfree_rejected` — the provider declined the authorization, `gasfree_integrity` — the provider's fee metadata disagreed with itself, `watch_only_no_signer`, `auth_failed`, `signing_rejected`, `provider_error`) · `2` usage error (`invalid_value`, `invalid_amount`). +`0` submitted (or dry-run) · `1` execution failure (`insufficient_token_balance` — token balance < amount + service fee [+ activation fee], `gasfree_rejected` — the provider declined the authorization, `gasfree_integrity` — the provider's fee metadata disagreed with itself, `watch_only_no_signer`, `auth_failed`, `signing_rejected`, `provider_error`) · `2` usage error (`gasfree_credentials_missing`, `unsupported_network`, `unsupported_token`, `invalid_value`, `invalid_amount`). ## See also diff --git a/ts/docs/commands/import/keystore.md b/ts/docs/commands/import/keystore.md index f7765a878..96a8e7f9c 100644 --- a/ts/docs/commands/import/keystore.md +++ b/ts/docs/commands/import/keystore.md @@ -75,7 +75,7 @@ wallet-cli import keystore ./tronlink-export.json --label imported -o json ## Exit status -`0` imported · `1` execution failure (`keystore_not_found` — no such file; `invalid_keystore` — not a valid keystore JSON; `wrong_keystore_password`; `account_exists` — this address is already in the wallet; `auth_failed`; `io_error`) · `2` usage error (`tty_required` — no TTY for interactive input, checked before anything else; duplicate label). +`0` imported · `1` execution failure (`wrong_keystore_password`; `account_exists` — this address is already in the wallet; `auth_failed`; `io_error`) · `2` usage error (`tty_required` — no TTY for interactive input, checked before anything else; `keystore_not_found` — no such file; `invalid_keystore` — not a valid keystore JSON; `invalid_value` — duplicate or invalid label). ## See also diff --git a/ts/docs/commands/import/mnemonic.md b/ts/docs/commands/import/mnemonic.md index 84edb2df6..60e4b57dc 100644 --- a/ts/docs/commands/import/mnemonic.md +++ b/ts/docs/commands/import/mnemonic.md @@ -78,7 +78,7 @@ wallet-cli import mnemonic --label restored -o json ## Exit status -`0` imported · `1` execution failure (`tty_required` — no TTY for interactive input; `auth_failed`; `password_mismatch`; `io_error`) · `2` usage error (invalid mnemonic, duplicate label). +`0` imported · `1` execution failure (`auth_failed` — the entered master password does not match an existing keystore; `invalid_mnemonic` — storage validation rejected the phrase; `io_error`) · `2` usage error (`tty_required` — no TTY for the hidden prompts; `invalid_value` — invalid or duplicate label). An invalid phrase or weak new password entered at a TTY prompt is rejected there and re-prompted rather than returned as a terminal error. ## See also diff --git a/ts/docs/commands/import/private-key.md b/ts/docs/commands/import/private-key.md index 8e9840a91..3337f5b97 100644 --- a/ts/docs/commands/import/private-key.md +++ b/ts/docs/commands/import/private-key.md @@ -70,7 +70,7 @@ wallet-cli import private-key --label hot -o json ## Exit status -`0` imported · `1` execution failure (`tty_required` — no TTY for interactive input; `auth_failed`; `password_mismatch`; `io_error`) · `2` usage error (invalid private key, duplicate label). +`0` imported · `1` execution failure (`auth_failed` — the entered master password does not match an existing keystore; `invalid_private_key` — storage validation rejected the key; `io_error`) · `2` usage error (`tty_required` — no TTY for the hidden prompts; `invalid_value` — invalid or duplicate label). An invalid key or weak new password entered at a TTY prompt is rejected there and re-prompted rather than returned as a terminal error. ## See also diff --git a/ts/docs/commands/permission/show.md b/ts/docs/commands/permission/show.md index 2fb185c75..cb155f06a 100644 --- a/ts/docs/commands/permission/show.md +++ b/ts/docs/commands/permission/show.md @@ -102,7 +102,7 @@ wallet-cli permission show --account main --network tron:nile -o json ## Exit status -`0` success · `1` execution failure (`rpc_error`) · `2` usage error (`invalid_value`, or `not_found` when the address is unactivated / absent on chain). +`0` success · `1` execution failure (`not_found` — the address is unactivated / absent on chain; `rpc_error`) · `2` usage error (`invalid_value`). ## See also diff --git a/ts/docs/commands/permission/update.md b/ts/docs/commands/permission/update.md index 64d6260bd..ecfc09498 100644 --- a/ts/docs/commands/permission/update.md +++ b/ts/docs/commands/permission/update.md @@ -124,7 +124,7 @@ Local warnings (`owner_lockout`, `owner_lockout_partial`, `active_can_update_per ## Exit status -`0` submitted (or built/signed/dry-run in early-exit modes) · `1` execution failure (`invalid_permission`, `not_authorized`, `watch_only_no_signer`, `auth_failed`, `insufficient_balance`, `rpc_error`, `timeout`) · `2` usage error (`invalid_value`). +`0` submitted (or built/signed/dry-run in early-exit modes) · `1` execution failure (`not_authorized`, `watch_only_no_signer`, `auth_failed`, `insufficient_balance`, `rpc_error`, `timeout`) · `2` usage error (`invalid_permission` — malformed JSON or an invalid permission structure; `invalid_value`). On a multi-sig account, a submission whose accumulated signature weight is below the permission threshold is refused **after signing and before broadcasting** with `not_authorized` (`signature threshold is not reached; missing N weight`) — nothing is sent and no fee is burned. Collect the remaining signatures through `--sign-only` + [`tx sign`](../tx/sign.md) and submit with [`tx broadcast`](../tx/broadcast.md) instead. `--sign-only` and `--build-only` still return a partial signature, which is how a co-signing flow starts. diff --git a/ts/docs/commands/rename.md b/ts/docs/commands/rename.md index a0f83e52e..76635226a 100644 --- a/ts/docs/commands/rename.md +++ b/ts/docs/commands/rename.md @@ -41,7 +41,7 @@ wallet-cli rename main-1 --label hot-hd -o json ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"rename","data":{"previousLabel":"main-1","accountId":"wlt_0y2z0gvr.1","label":"hot-hd","type":"seed","index":1,"active":true,"addresses":{"tron":"TRzaAZWRvPCcmqNETTWvmMLDi6cKwM3gbR","evm":"0x94f2e5cbb4BcA39A3F6c252217a0F30A0D23660b"},"seedId":"wlt_0y2z0gvr","derivationPath":{"tron":"m/44'/195'/0'/0/1","evm":"m/44'/60'/0'/0/1"}},"meta":{"durationMs":14,"warnings":[]}} +{"schema":"wallet-cli.result.v1","success":true,"command":"rename","data":{"previousLabel":"main-1","accountId":"wlt_0y2z0gvr.1","label":"hot-hd","type":"seed","index":1,"active":true,"addresses":{"tron":"TRzaAZWRvPCcmqNETTWvmMLDi6cKwM3gbR","evm":"0x94f2e5cbb4BcA39A3F6c252217a0F30A0D23660b"},"seedId":"wlt_0y2z0gvr","derivationPath":{"tron":"m/44'/195'/1'/0/0","evm":"m/44'/60'/0'/0/1"}},"meta":{"durationMs":14,"warnings":[]}} ``` ## Output diff --git a/ts/docs/commands/stake/cancel-unfreeze.md b/ts/docs/commands/stake/cancel-unfreeze.md index 246547e08..ab597c5ad 100644 --- a/ts/docs/commands/stake/cancel-unfreeze.md +++ b/ts/docs/commands/stake/cancel-unfreeze.md @@ -15,6 +15,8 @@ Cancels **every** unstake still in its waiting period and rolls those amounts ba **By default the command returns at submission**; `--wait` blocks until confirmed. Requires an account. The master password (via `--password-stdin`) is needed only by the modes that sign — `--dry-run` and `--build-only` do not unlock the wallet and run without it. Watch-only accounts fail with `watch_only_no_signer` in a signing mode. +The Ledger TRON app cannot sign `CancelAllUnfreezeV2`. Ledger accounts may dry-run or build, but signing modes fail with `ledger_unsupported` before device interaction. + ## Options | Option | Description | @@ -79,7 +81,7 @@ echo "$PW" | wallet-cli stake cancel-unfreeze --network tron:nile --wait --passw ## Exit status -`0` submitted (or built/signed in early-exit modes) · `1` execution failure (`watch_only_no_signer`, `auth_failed`, `rpc_error`, `timeout`) · `2` usage error. +`0` submitted (or built/signed in early-exit modes) · `1` execution failure (`watch_only_no_signer`, `ledger_unsupported`, `auth_failed`, `rpc_error`, `timeout`) · `2` usage error. ## See also diff --git a/ts/docs/commands/token/add.md b/ts/docs/commands/token/add.md index 458f3bb29..3268f8ec3 100644 --- a/ts/docs/commands/token/add.md +++ b/ts/docs/commands/token/add.md @@ -67,7 +67,7 @@ wallet-cli token add --contract 0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238 --net ## Exit status -`0` added · `1` execution failure (`token_metadata_unavailable` — metadata could not be fetched, nothing is stored; `token_already_listed` — already in the official layer) · `2` usage error (`invalid_value`; `invalid_option` — `--asset-id` on an EVM network). +`0` added · `1` execution failure (`token_metadata_unavailable` — metadata could not be fetched, nothing is stored) · `2` usage error (`token_already_listed` — already in the official layer; `invalid_value`; `invalid_option` — `--asset-id` on an EVM network). ## See also diff --git a/ts/docs/commands/token/remove.md b/ts/docs/commands/token/remove.md index 45e7cde76..648ce60d9 100644 --- a/ts/docs/commands/token/remove.md +++ b/ts/docs/commands/token/remove.md @@ -53,7 +53,7 @@ wallet-cli token remove --contract TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf --network ## Exit status -`0` removed · `1` execution failure (`token_is_official` — official-layer tokens can't be removed; `token_not_in_book` — not in the book) · `2` usage error (`invalid_value`; `invalid_option` — `--asset-id` on an EVM network). +`0` removed · `1` execution failure (`encoding_error`, `insecure_permissions`, `io_error`) · `2` usage error (`token_is_official` — official-layer tokens can't be removed; `token_not_in_book` — not in the user layer; `invalid_value`; `invalid_option` — `--asset-id` on an EVM network). ## See also diff --git a/ts/docs/commands/tx/multisig.md b/ts/docs/commands/tx/multisig.md index 2e399ddf2..aa404e5ef 100644 --- a/ts/docs/commands/tx/multisig.md +++ b/ts/docs/commands/tx/multisig.md @@ -174,7 +174,7 @@ A record the client cannot reconcile with the chain stays visible and is labelle ## Exit status -`0` success · `1` execution failure (`tronlink_credentials_missing`, `not_found` — txId not on the service, `not_authorized`, `already_signed`, `tx_expired`, `auth_failed`, `provider_error` — service error / rate limit) · `2` usage error (`invalid_value` — including an already-signed transaction passed to `--create`, conflicting modes). +`0` success · `1` execution failure (`not_found` — txId not on the service, `not_authorized`, `already_signed`, `tx_expired`, `auth_failed`, `provider_error` — service error / rate limit) · `2` usage error (`tronlink_credentials_missing`, `unsupported_network`, `invalid_value` — including an already-signed transaction passed to `--create`, conflicting modes). ## See also diff --git a/ts/docs/commands/use.md b/ts/docs/commands/use.md index bceb0aa6f..12a58b644 100644 --- a/ts/docs/commands/use.md +++ b/ts/docs/commands/use.md @@ -35,7 +35,7 @@ wallet-cli use main-1 -o json ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"use","data":{"previous":"wlt_758891fa.0","accountId":"wlt_758891fa.1","label":"main-1","type":"seed","index":1,"active":true,"addresses":{"tron":"TRs9HgTuY3dT3yDasdFdP9WQHqL37891Ax","evm":"0xf3ec542047Fe61E0b753a7EBca95B27a672F9cbe"},"seedId":"wlt_758891fa","derivationPath":{"tron":"m/44'/195'/0'/0/1","evm":"m/44'/60'/0'/0/1"}},"meta":{"durationMs":14,"warnings":[]}} +{"schema":"wallet-cli.result.v1","success":true,"command":"use","data":{"previous":"wlt_758891fa.0","accountId":"wlt_758891fa.1","label":"main-1","type":"seed","index":1,"active":true,"addresses":{"tron":"TRs9HgTuY3dT3yDasdFdP9WQHqL37891Ax","evm":"0xf3ec542047Fe61E0b753a7EBca95B27a672F9cbe"},"seedId":"wlt_758891fa","derivationPath":{"tron":"m/44'/195'/1'/0/0","evm":"m/44'/60'/0'/0/1"}},"meta":{"durationMs":14,"warnings":[]}} ``` ## Output diff --git a/ts/docs/commands/vote/cast.md b/ts/docs/commands/vote/cast.md index b0ba849d9..3f0cd0f25 100644 --- a/ts/docs/commands/vote/cast.md +++ b/ts/docs/commands/vote/cast.md @@ -89,7 +89,7 @@ echo "$PW" | wallet-cli vote cast --for TZ4...=600 --for TT5...=400 --network tr ## Exit status -`0` submitted (or built/signed in early-exit modes) · `1` execution failure (`watch_only_no_signer`, `auth_failed`, `insufficient_voting_power` — total exceeds available TP) · `2` usage error (`invalid_value` — bad SR address, non-positive count, > 30 entries). +`0` submitted (or built/signed in early-exit modes) · `1` execution failure (`watch_only_no_signer`, `auth_failed`) · `2` usage error (`insufficient_voting_power` — total exceeds available TP; `invalid_value` — bad SR address, non-positive count, > 30 entries). ## See also diff --git a/ts/docs/commands/vote/list.md b/ts/docs/commands/vote/list.md index 37254d550..933b0bc6a 100644 --- a/ts/docs/commands/vote/list.md +++ b/ts/docs/commands/vote/list.md @@ -10,11 +10,11 @@ wallet-cli vote list [--limit ] [--candidates] [options] ## Description -Lists SRs (the 27 elected, by default) with votes, estimated APR, and reward ratio — the numbers you need before a [`vote cast`](cast.md). Read-only, no account needed. +Lists SRs (the 27 elected, by default) with votes and reward ratio — the on-chain data available before a [`vote cast`](cast.md). Read-only, no account needed. Column semantics: -- **APR** — the voter's estimated annual return, already adjusted for the SR's reward ratio. **Best-effort**: not from chain RPC but from explorer/TronGrid data; when unavailable the column shows `—` (json `null`). +- **APR** — reserved for a future estimate source. The current implementation does not query one, so the column always shows `—` and json always returns `null`. - **Reward ratio** — the share of rewards the SR passes to voters (on-chain, reliable). 80% means voters split 80% of the rewards; **0% means your votes earn nothing**. json also carries the chain-native `brokeragePct` (= 100 − rewardRatioPct). - **Ranks and eligibility** — ranks 1–27 are elected SRs (block + vote rewards); 28–127 are partners (vote rewards only); beyond 127 candidates earn nothing, so `--limit` caps at 127. @@ -36,9 +36,9 @@ wallet-cli vote list --limit 3 --network tron:nile ```console | Rank | Name | Votes | APR | Reward ratio | Address | | ---- | --------------- | ------------- | ---- | ------------ | ---------------------------------- | -| 1 | TRONSCAN | 1,203,456,789 | 4.8% | 80% | TZ4UXDV5ZhNW7fb2AMSbgfAEZ7hWsnYS2g | -| 2 | Binance Staking | 998,765,432 | 0% | 0% | TT5W8MPbYJih9R586kTszb4LoybzUvCYm2 | -| 3 | JustLend | 876,543,210 | 4.9% | 80% | TWxkzUeAiKcFvzXvJEcaTQCQqCuMednAtN | +| 1 | TRONSCAN | 1,203,456,789 | — | 80% | TZ4UXDV5ZhNW7fb2AMSbgfAEZ7hWsnYS2g | +| 2 | Binance Staking | 998,765,432 | — | 0% | TT5W8MPbYJih9R586kTszb4LoybzUvCYm2 | +| 3 | JustLend | 876,543,210 | — | 80% | TWxkzUeAiKcFvzXvJEcaTQCQqCuMednAtN | ``` ```bash @@ -46,7 +46,7 @@ wallet-cli vote list --limit 3 --network tron:nile -o json ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"vote.list","data":{"witnesses":[{"rank":1,"name":"TRONSCAN","address":"TZ4UXDV5ZhNW7fb2AMSbgfAEZ7hWsnYS2g","voteCount":"1203456789","rewardRatioPct":80,"brokeragePct":20,"aprPct":4.8}]},"meta":{"durationMs":40,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"vote.list","data":{"witnesses":[{"rank":1,"name":"TRONSCAN","address":"TZ4UXDV5ZhNW7fb2AMSbgfAEZ7hWsnYS2g","voteCount":"1203456789","rewardRatioPct":80,"brokeragePct":20,"aprPct":null}]},"meta":{"durationMs":40,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` ## Output @@ -61,7 +61,7 @@ wallet-cli vote list --limit 3 --network tron:nile -o json | `voteCount` | string | Total votes, raw integer | | `rewardRatioPct` | number | % of rewards passed to voters (on-chain) | | `brokeragePct` | number | SR's cut (= 100 − `rewardRatioPct`) | -| `aprPct` | number \| null | Estimated voter APR; `null` when the estimate source is unavailable | +| `aprPct` | null | Reserved field; always `null` in the current implementation | ## Exit status diff --git a/ts/docs/commands/vote/status.md b/ts/docs/commands/vote/status.md index b1e0b1350..b06d8e41b 100644 --- a/ts/docs/commands/vote/status.md +++ b/ts/docs/commands/vote/status.md @@ -10,10 +10,10 @@ wallet-cli vote status [options] ## Description -One read-only screen for the stake → vote → reward loop: your current vote distribution (with each SR's APR and reward ratio), your voting power (total / used / available TP), and the currently claimable reward. +One read-only screen for the stake → vote → reward loop: your current vote distribution and each SR's reward ratio, your voting power (total / used / available TP), and the currently claimable reward. - **Voting power (TP)** — total = staked TRX; used = votes placed; available = total − used. -- **APR / Reward ratio** — same semantics and sources as [`vote list`](list.md). Worth re-checking: an SR can change its ratio at any time (on-chain UpdateBrokerage) — votes placed at 80% silently stop earning if it drops to 0%. +- **APR / Reward ratio** — reward ratio is read on-chain. `aprPct` is reserved and always `null` because the current implementation has no APR provider. An SR can change its ratio at any time (on-chain UpdateBrokerage) — votes placed at 80% silently stop earning if it drops to 0%. - **0% warning** — if any votes sit on an SR with a 0% reward ratio, text output appends a `!` line and json adds a plain-string entry to `meta.warnings`, one per affected SR. - **Claimable** — same source as [`reward balance`](../reward/balance.md); claim with [`reward withdraw`](../reward/withdraw.md). @@ -35,8 +35,8 @@ Claimable 12.345678 TRX Current votes (2) | Name | Votes | APR | Reward ratio | Address | | --------------- | ----- | ---- | ------------ | ---------------------------------- | -| TRONSCAN | 600 | 4.8% | 80% | TZ4UXDV5ZhNW7fb2AMSbgfAEZ7hWsnYS2g | -| Binance Staking | 400 | 0% | 0% | TT5W8MPbYJih9R586kTszb4LoybzUvCYm2 | +| TRONSCAN | 600 | — | 80% | TZ4UXDV5ZhNW7fb2AMSbgfAEZ7hWsnYS2g | +| Binance Staking | 400 | — | 0% | TT5W8MPbYJih9R586kTszb4LoybzUvCYm2 | ! 400 votes on Binance Staking earn nothing — 0% reward ratio ``` @@ -45,7 +45,7 @@ wallet-cli vote status --account main --network tron:nile -o json ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"vote.status","data":{"address":"TQk...","votingPower":{"total":1500,"used":1000,"available":500},"claimableRewardSun":"12345678","votes":[{"witness":"TZ4...","name":"TRONSCAN","count":600,"rewardRatioPct":80,"brokeragePct":20,"aprPct":4.8},{"witness":"TT5...","name":"Binance Staking","count":400,"rewardRatioPct":0,"brokeragePct":100,"aprPct":0}]},"meta":{"durationMs":16,"warnings":["400 votes on TT5... (Binance Staking) earn nothing: reward ratio is 0%"]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"vote.status","data":{"address":"TQk...","votingPower":{"total":1500,"used":1000,"available":500},"claimableRewardSun":"12345678","votes":[{"witness":"TZ4...","name":"TRONSCAN","count":600,"rewardRatioPct":80,"brokeragePct":20,"aprPct":null},{"witness":"TT5...","name":"Binance Staking","count":400,"rewardRatioPct":0,"brokeragePct":100,"aprPct":null}]},"meta":{"durationMs":16,"warnings":["400 votes on TT5... (Binance Staking) earn nothing: reward ratio is 0%"]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` ## Output @@ -55,7 +55,7 @@ wallet-cli vote status --account main --network tron:nile -o json | `address` | string | Queried account | | `votingPower.total` / `.used` / `.available` | number | TP total / spent / spendable | | `claimableRewardSun` | string | Currently claimable reward, in SUN | -| `votes[]` | array | Current distribution: `witness`, `name`, `count`, `rewardRatioPct`, `brokeragePct`, `aprPct` | +| `votes[]` | array | Current distribution: `witness`, `name`, `count`, `rewardRatioPct`, `brokeragePct`, and reserved `aprPct` (always `null`) | Zero-reward-ratio warnings appear in `meta.warnings` as plain strings — see [reading `meta.warnings`](../../machine-interface.md#reading-metawarnings). diff --git a/ts/docs/commands/witness/create.md b/ts/docs/commands/witness/create.md index 658308aff..2dc6865dc 100644 --- a/ts/docs/commands/witness/create.md +++ b/ts/docs/commands/witness/create.md @@ -20,6 +20,8 @@ The account must already be activated and hold at least the registration fee. `- **By default the command returns at submission** (`stage: "submitted"`), not confirmation — add `--wait` to block until confirmed/failed. Requires an account. The master password (via `--password-stdin`) is needed only by the modes that sign — `--dry-run` and `--build-only` do not unlock the wallet and run without it. Watch-only accounts fail with `watch_only_no_signer` in a signing mode. +The Ledger TRON app cannot sign witness contract types. Ledger accounts may dry-run or build, but signing modes fail with `ledger_unsupported` before device interaction. + ## Options | Option | Description | @@ -74,7 +76,7 @@ echo "$PW" | wallet-cli witness create --url https://sr.acme.io --network tron:n ## Exit status -`0` submitted (or built/signed in early-exit modes) · `1` execution failure (`already_witness`, `account_not_active`, `insufficient_balance` — below the registration fee, `watch_only_no_signer`, `auth_failed`) · `2` usage error (`missing_option` — no `--url`). +`0` submitted (or built/signed in early-exit modes) · `1` execution failure (`already_witness`, `account_not_active`, `insufficient_balance` — below the registration fee, `watch_only_no_signer`, `ledger_unsupported`, `auth_failed`) · `2` usage error (`missing_option` — no `--url`). ## See also diff --git a/ts/docs/commands/witness/set-brokerage.md b/ts/docs/commands/witness/set-brokerage.md index 74e9d5af5..40f247eab 100644 --- a/ts/docs/commands/witness/set-brokerage.md +++ b/ts/docs/commands/witness/set-brokerage.md @@ -20,6 +20,8 @@ Any registered witness can set it, elected or not. The acting account must be a **By default the command returns at submission** (`stage: "submitted"`), not confirmation — add `--wait` to block until confirmed/failed. Requires an account. The master password (via `--password-stdin`) is needed only by the modes that sign — `--dry-run` and `--build-only` do not unlock the wallet and run without it. Watch-only accounts fail with `watch_only_no_signer` in a signing mode. +The Ledger TRON app cannot sign witness contract types. Ledger accounts may dry-run or build, but signing modes fail with `ledger_unsupported` before device interaction. + ## Options | Option | Description | @@ -76,7 +78,7 @@ echo "$PW" | wallet-cli witness set-brokerage 20 --network tron:nile --wait --pa ## Exit status -`0` submitted (or built/signed in early-exit modes) · `1` execution failure (`not_a_witness`, `watch_only_no_signer`, `auth_failed`) · `2` usage error (`invalid_value` — percent missing, not an integer, or outside 0–100). +`0` submitted (or built/signed in early-exit modes) · `1` execution failure (`not_a_witness`, `watch_only_no_signer`, `ledger_unsupported`, `auth_failed`) · `2` usage error (`invalid_value` — percent missing, not an integer, or outside 0–100). ## See also diff --git a/ts/docs/commands/witness/update.md b/ts/docs/commands/witness/update.md index 647fad391..f50a01b0b 100644 --- a/ts/docs/commands/witness/update.md +++ b/ts/docs/commands/witness/update.md @@ -18,6 +18,8 @@ The acting account must already be a candidate; otherwise the command fails with **By default the command returns at submission** (`stage: "submitted"`), not confirmation — add `--wait` to block until confirmed/failed. Requires an account. The master password (via `--password-stdin`) is needed only by the modes that sign — `--dry-run` and `--build-only` do not unlock the wallet and run without it. Watch-only accounts fail with `watch_only_no_signer` in a signing mode. +The Ledger TRON app cannot sign witness contract types. Ledger accounts may dry-run or build, but signing modes fail with `ledger_unsupported` before device interaction. + ## Options | Option | Description | @@ -70,7 +72,7 @@ echo "$PW" | wallet-cli witness update --url https://sr.acme.io/v2 --network tro ## Exit status -`0` submitted (or built/signed in early-exit modes) · `1` execution failure (`not_a_witness`, `watch_only_no_signer`, `auth_failed`) · `2` usage error (`missing_option` — no `--url`). +`0` submitted (or built/signed in early-exit modes) · `1` execution failure (`not_a_witness`, `watch_only_no_signer`, `ledger_unsupported`, `auth_failed`) · `2` usage error (`missing_option` — no `--url`). ## See also diff --git a/ts/docs/concepts/accounts-and-hd.md b/ts/docs/concepts/accounts-and-hd.md index 381fe076c..35c33fe3f 100644 --- a/ts/docs/concepts/accounts-and-hd.md +++ b/ts/docs/concepts/accounts-and-hd.md @@ -19,7 +19,7 @@ wlt_4473p34m.1 A key is not tied to a chain, so **an account holds one address per [family](networks.md)** — a TRON base58 address and an EVM `0x` address — derived from the same seed at different BIP44 coin types: ``` -m/44'/195'/0'/0/ TRON +m/44'/195'/'/0/0 TRON m/44'/60'/0'/0/ EVM ``` diff --git a/ts/docs/concepts/networks.md b/ts/docs/concepts/networks.md index 589439173..432bae135 100644 --- a/ts/docs/concepts/networks.md +++ b/ts/docs/concepts/networks.md @@ -46,7 +46,9 @@ Listings (`networks`, `config`) print an endpoint's **host only**, because a com 1. Explicit `--network ` on the command; 2. otherwise `config.defaultNetwork` (`wallet-cli config defaultNetwork tron:nile`); -3. chain commands with neither will tell you a network is required. +3. if the config file does not override it, the built-in default is `tron:mainnet`. + +Omitting `--network` therefore does **not** stop a chain command. For any operation that can move funds, pass `--network` explicitly so the target is visible in shell history and review logs. Balances, tokens, and transactions are entirely separate per network. A txid from Nile does not exist on mainnet — querying it there returns `not_found`/`rpc_error`. diff --git a/ts/docs/machine-interface.md b/ts/docs/machine-interface.md index d554026c5..f0633bdd3 100644 --- a/ts/docs/machine-interface.md +++ b/ts/docs/machine-interface.md @@ -164,7 +164,7 @@ The **exit code is the hard contract**: `2` means the call was malformed (it wil wallet-cli --json-schema | jq '.errorCodes' ``` -That index is the machine-readable catalog exposed by this build. Treat it as a discovery aid, not a closed enum: a few code paths choose among error-code strings dynamically, so a runtime envelope can still carry a code not present in `errorCodes`. The tables below are the frequently-hit subset, kept for reading. New codes may still be added within v1, and a few strings (e.g. `invalid_value`, `aborted`) can appear under either exit code depending on where they are raised — so always tolerate an unknown code by falling back to its exit-code class. +That index is the machine-readable catalog exposed by this build. Treat it as a discovery aid, not a closed enum: a few code paths choose among error-code strings dynamically, so a runtime envelope can still carry a code not present in `errorCodes`. The tables below are the frequently-hit subset, kept for reading. New codes may still be added within v1, and a few strings (e.g. `invalid_value`, `aborted`, `not_found`) can appear under either exit code depending on where they are raised — so always tolerate an unknown code by falling back to its exit-code class. Common codes at exit **2** (usage — fix the call): @@ -174,12 +174,12 @@ Common codes at exit **2** (usage — fix the call): | `family_mismatch` | The command, the account, the recipient, or the raw transaction does not belong to the selected network's chain family | | `missing_option` | A required flag was not provided | | `invalid_option` | A flag was used in an invalid combination, or is scoped to the other chain family | +| `invalid_permission` | A permission document or selected permission group is invalid for the operation | | `invalid_value` | A flag value failed validation (e.g. `config defaultOutput xml`) | | `invalid_amount` | An amount is malformed or out of range | -| `invalid_mnemonic` / `invalid_private_key` | A supplied mnemonic or private key is malformed | | `weak_password` | Master password below policy (≥8 chars; upper + lower + digit + special) | -| `tty_required` | An interactive prompt is needed but no TTY is attached — pass the matching `*-stdin` flag | -| `missing_network` / `unsupported_network` | `--network` absent, or not a known canonical id or alias | +| `tty_required` | An interactive prompt is needed but no TTY is attached — run in a TTY, or use the matching stdin flag when that command exposes one | +| `missing_network` / `unsupported_network` | A caller explicitly asked the registry to resolve an empty network id, or the supplied canonical id / alias is unknown. Normal chain commands use `config.defaultNetwork`, whose built-in value is `tron:mainnet`, when `--network` is omitted | | `unsupported_network_capability` | The selected network does not offer what this command needs | | `limit_exceeded` | A bounded input (file size, list length, page size) was over its limit | | `unknown_command` | No such command | @@ -189,7 +189,11 @@ Common codes at exit **2** (usage — fix the call): | `invalid_keystore` | `import keystore`: not a valid Web3 V3 keystore — bad JSON, `version` ≠ 3, an unsupported cipher/KDF, or a payload that is not a 32-byte private key | | `invalid_config` | `config.yaml` cannot be read or is not valid YAML — fix or remove the file. The parser detail is withheld: it quotes the offending line, which may carry a credential | | `insecure_config` | `config.yaml` holds service credentials but is a symlink or is group/world-readable — run `chmod 600` on it (POSIX only; not enforced on Windows) | -| `token_not_in_book` / `token_is_official` / `token_metadata_unavailable` | Token address-book conditions | +| `contact_not_found` / `already_exists` | No contact by that name, or a contact name/address is already stored | +| `token_not_in_book` / `token_is_official` / `token_already_listed` | Token address-book conditions | +| `unsupported_token` | The selected provider or command does not support that token | +| `insufficient_voting_power` | The requested votes exceed the account's available voting power | +| `gasfree_credentials_missing` / `tronlink_credentials_missing` | Required service credentials are not configured (set them with `config`) | | `unknown_parameter` | No chain parameter by that name or id (`proposal create --set`) | | `invalid_asset_name` | A TRC10 name or abbreviation outside 1–32 visible ASCII characters | @@ -204,20 +208,21 @@ Common codes at exit **1** (execution — runtime failure): | `auth_failed` | Wrong master password (decryption failed) | | `signing_rejected` / `transaction_rejected` | Signing or broadcast rejected (device or chain) | | `watch_only_no_signer` | The account is watch-only and cannot sign | +| `invalid_mnemonic` / `invalid_private_key` | Storage validation rejected a malformed mnemonic or private key; interactive import normally catches it at the prompt and asks again | +| `token_metadata_unavailable` | Required token metadata could not be read from the selected network | | `wrong_device_seed` | Connected Ledger does not match the registered account | | `tx_integrity` / `invalid_transaction` | A presigned transaction failed integrity / validity checks | | `insufficient_balance` / `insufficient_token_balance` | Not enough TRX / token to cover the amount plus fees | | `provider_error` | An external service (GasFree, TronLink multi-sig) returned an error or rate-limited | -| `gasfree_credentials_missing` / `tronlink_credentials_missing` | Required service credentials are not configured (set them with `config`) | | `tx_expired` | The transaction's expiration passed before signatures were collected (TRON) | | `chain_id_mismatch` | An EVM transaction was built for a different chain than the selected network | | `nonce_too_low` | The EVM transaction's nonce is already used by a mined transaction | | `migration_required` | Persisted wallet data needs an upgrade that this invocation cannot perform — see [startup wallet-data upgrades](#startup-wallet-data-upgrades) | | `history_not_supported` | The endpoint lacks TronGrid history support (`account history`, TRON) | -| `not_found` | The addressed thing does not exist — an unactivated account, a contact, a chain parameter, a GasFree or TronLink resource. Lookups that have a group of their own use the specific code below | +| `not_found` | The addressed thing does not exist — for example an unactivated account, transaction, block, or GasFree / TronLink resource. Some command-level lookups raise the same string as a usage error instead; branch on exit code first | | `proposal_not_found` / `contract_not_found` / `asset_not_found` / `exchange_not_found` | Nothing on chain under that proposal id, contract address, TRC10 reference, or exchange pair id | | `ambiguous_asset_name` | A TRC10 name matches more than one token; `error.details` carries the candidates — see [`error.details.matches`](#errordetailsmatches) | -| `ledger_unsupported` | The Ledger TRON app cannot sign this contract type — refused before the device is touched (`asset` writes, `witness` writes) | +| `ledger_unsupported` | The selected Ledger app cannot sign this transaction type — refused before the device is touched (TRON account activation, account id, asset writes, contract deploy/governance, witness writes, and cancel-unfreeze) | | `not_a_witness` / `already_witness` / `not_proposal_owner` | Governance identity does not meet the operation's rule | | `already_approved` / `not_approved` / `proposal_expired` / `already_canceled` | Proposal voting conditions | | `account_not_active` / `account_already_active` / `name_already_set` / `id_already_set` / `chain_parameter_unavailable` | Account activation/name/id conditions, or `witness create` could not read `getAccountUpgradeCost` | From 6b5d69df6a759c97ecb56341d6e1fd1362663ef8 Mon Sep 17 00:00:00 2001 From: "Leon.Zhang" Date: Tue, 1 Sep 2026 14:51:30 +0800 Subject: [PATCH 5/5] docs: align remaining behavior references --- README.md | 10 +- java/README.md | 16 +-- java/docs/commands/contract.md | 8 +- java/docs/commands/index.md | 3 +- java/docs/commands/multisig.md | 2 + java/docs/commands/stake-v1-legacy.md | 7 +- java/docs/commands/stake-v2.md | 4 +- java/docs/commands/standard-cli.md | 97 +++++++++++++++++++ java/docs/commands/transfer-trc10.md | 2 +- java/docs/commands/vote-reward.md | 6 +- java/docs/commands/wallet.md | 2 +- java/docs/guide/command-flow.md | 8 +- java/docs/guide/getting-started.md | 8 +- java/docs/guide/index.md | 1 + java/docs/reference/config.md | 10 +- java/docs/standard-cli-contract-spec.md | 2 + ts/docs/commands/account/activate.md | 12 +-- ts/docs/commands/account/history.md | 13 ++- ts/docs/commands/account/info.md | 2 +- ts/docs/commands/account/set.md | 6 +- ts/docs/commands/asset/issue.md | 6 +- ts/docs/commands/asset/participate.md | 6 +- ts/docs/commands/asset/unfreeze.md | 6 +- ts/docs/commands/asset/update.md | 6 +- ts/docs/commands/backup.md | 6 +- ts/docs/commands/block.md | 2 +- ts/docs/commands/contact/add.md | 7 +- ts/docs/commands/contact/list.md | 4 +- ts/docs/commands/contract/clear-abi.md | 4 +- ts/docs/commands/contract/create2.md | 2 +- .../contract/set-origin-energy-limit.md | 4 +- .../contract/set-user-resource-percent.md | 4 +- ts/docs/commands/current.md | 3 +- ts/docs/commands/gasfree/info.md | 14 +-- ts/docs/commands/gasfree/trace.md | 12 ++- ts/docs/commands/gasfree/transfer.md | 39 +++++--- ts/docs/commands/import/keystore.md | 6 +- ts/docs/commands/import/ledger.md | 6 +- ts/docs/commands/import/mnemonic.md | 8 +- ts/docs/commands/import/private-key.md | 8 +- ts/docs/commands/import/watch.md | 6 +- ts/docs/commands/index.md | 2 +- ts/docs/commands/permission/show.md | 40 ++------ ts/docs/commands/permission/update.md | 30 +++--- ts/docs/commands/proposal/approve.md | 6 +- ts/docs/commands/proposal/create.md | 6 +- ts/docs/commands/proposal/delete.md | 6 +- ts/docs/commands/token/add.md | 2 +- ts/docs/commands/token/info.md | 33 ++++++- ts/docs/commands/token/remove.md | 2 +- ts/docs/commands/tx/info.md | 6 +- ts/docs/commands/tx/multisig.md | 25 +++-- ts/docs/commands/tx/sign.md | 18 ++-- ts/docs/commands/vote/cast.md | 10 +- ts/docs/commands/vote/list.md | 18 ++-- ts/docs/commands/vote/status.md | 10 +- ts/docs/commands/witness/create.md | 8 +- ts/docs/commands/witness/set-brokerage.md | 4 +- ts/docs/commands/witness/update.md | 4 +- ts/docs/concepts/security.md | 2 +- ts/docs/guide/ledger.md | 6 +- ts/docs/guide/scripting.md | 4 +- ts/docs/machine-interface.md | 14 +-- 63 files changed, 397 insertions(+), 237 deletions(-) create mode 100644 java/docs/commands/standard-cli.md diff --git a/README.md b/README.md index 363833d29..dd0bcd909 100644 --- a/README.md +++ b/README.md @@ -25,11 +25,11 @@ Both manage TRON wallets, but they are independent implementations rather than i | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **What it is** | The mature, full-feature reference CLI. | A newer rewrite focused on programmatic integration. | | **Runtime** | JVM — built with Gradle, run as a `.jar`. Uses the [Trident](https://github.com/tronprotocol/trident) SDK. | [Node.js](https://nodejs.org) **20+**. | -| **Install** | `git clone` + `./gradlew build` (see [Setup](java/README.md#setup)) | `npm install -g @tron-walletcli/wallet-cli` | +| **Install** | `git clone` + `cd wallet-cli/java && ./gradlew build` (see [Setup](java/README.md#setup)) | `npm install -g @tron-walletcli/wallet-cli` | | **How you drive it** | One-shot standard commands, or an interactive prompt when run without a command / with `--interactive`. | **One-shot subcommands** — `wallet-cli ` from your shell. Interactive prompts only for secret input. | -| **Command style** | PascalCase verbs: `RegisterWallet`, `SendCoin`, `GetBalance`. Amounts in **SUN** (1 TRX = 1,000,000 SUN). | Noun-verb subcommands: `create`, `tx send`, `account balance`, with `--flags`. | +| **Command style** | Kebab-case one-shot commands (`send-coin`) or PascalCase REPL verbs (`SendCoin`). Amounts in **SUN**. | Noun-verb subcommands: `create`, `tx send`, `account balance`, with `--flags`. | | **Output for scripts** | Text by default; standard mode supports `--output json` and structured success/error envelopes. | Stable JSON via `-o json` ([`wallet-cli.result.v1`](ts/docs/machine-interface.md)) + fixed exit codes (`0`/`1`/`2`). | -| **Config / networks** | `config.conf` (net type + full node), or `SwitchNetwork` at runtime. Mainnet · Nile · Shasta · custom. | `--network` flag / `config` command. Three TRON networks plus Ethereum, Sepolia, BNB Smart Chain, and its testnet. | +| **Config / networks** | `config.conf` endpoints, or `SwitchNetwork` at runtime. Mainnet · Nile · Shasta · custom. | `--network` flag / `config` command. Three TRON networks plus Ethereum, Sepolia, BNB Smart Chain, and its testnet. | | **Signing** | Software keystore · Ledger. | Encrypted local keystore · Ledger. Secrets enter via stdin/TTY, never argv or dedicated secret env vars. | | **Feature scope** | **The full surface** — wallets and transfers, staking, voting and rewards, governance, contracts, TRC10, and the on-chain exchange. | **The full surface** — HD wallets, TRX/TRC20/TRC10 transfers, staking & delegation, voting & rewards, governance proposals & super-representative operation, contract call/deploy/governance, TRC10 issuance, the on-chain Bancor exchange, multi-sig, GasFree transfers, message signing, and on-chain queries. | | **Best for** | People at a terminal who want every TRON capability. | Scripting, CI pipelines, and AI agents. | @@ -41,10 +41,10 @@ Build it, then either run a standard command or start the prompt: ```console $ git clone https://github.com/tronprotocol/wallet-cli.git -$ cd wallet-cli && ./gradlew build && cd build/libs +$ cd wallet-cli/java && ./gradlew build && cd build/libs $ java -jar wallet-cli.jar --output json --network nile get-balance --address T... $ java -jar wallet-cli.jar # opens the interactive prompt -> RegisterWallet 123456 # create a keystore (password 123456) +> RegisterWallet # prompts twice for the password, then for mnemonic length > Login # unlock it > GetAddress # your TRON address > GetBalance # TRX balance diff --git a/java/README.md b/java/README.md index 72ec9f94f..58f22f906 100644 --- a/java/README.md +++ b/java/README.md @@ -4,7 +4,7 @@ The original, full-featured implementation of wallet-cli. It supports both one-s > For what wallet-cli is and how this compares to the scriptable, JSON-first [TypeScript implementation](../ts/README.md), see the [repository overview](../README.md). -**Quick links:** [Setup](#setup) · [Quickstart](#quickstart) · [Commands](#commands) · [Understanding TRON mechanics](#understanding-tron-mechanics) · [Configuration](docs/reference/config.md) +**Quick links:** [Setup](#setup) · [Quickstart](#quickstart) · [Commands](#commands) · [Standard CLI](docs/commands/standard-cli.md) · [Understanding TRON mechanics](#understanding-tron-mechanics) · [Configuration](docs/reference/config.md) Need help? Join the [Telegram developer group](https://t.me/TronOfficialDevelopersGroupEn). @@ -18,7 +18,7 @@ git clone https://github.com/tronprotocol/wallet-cli.git ### Configuration -A minimal `config.conf` only needs a network type and a full node to talk to: +A minimal `config.conf` needs a full-node endpoint. `net.type` does not select the network; it only controls whether `grpc.mainnet.apiKey` is applied. The startup network is inferred from the configured node endpoints. ``` net { @@ -40,20 +40,20 @@ You can also switch networks at runtime with the [`SwitchNetwork`](docs/commands - **Compile and run**: ```console - $ cd wallet-cli + $ cd wallet-cli/java $ ./gradlew build $ cd build/libs $ java -jar wallet-cli.jar --help ``` -With no command, wallet-cli opens the legacy interactive prompt. With a command, it uses the standard CLI; `--interactive` selects the prompt explicitly. Standard mode accepts global options such as `--network `, `--wallet`, `--grpc-endpoint`, and `--output `: +With no arguments, wallet-cli opens the legacy interactive prompt. Any command selects the standard CLI; `--interactive` selects the prompt explicitly. Global options without a command, except supported modes such as `--help` and `--version`, are a usage error. Standard mode accepts options such as `--network `, `--wallet`, `--grpc-endpoint`, and `--output `: ```console $ java -jar wallet-cli.jar --output json --network nile get-balance --address T... $ java -jar wallet-cli.jar --interactive ``` -wallet-cli connects to java-tron via the gRPC protocol, which can be deployed locally or remotely. Configure the java-tron node IP and port in `src/main/resources/config.conf`, or use `SwitchNetwork` to switch among mainnet, testnets (Nile and Shasta), and custom networks. +wallet-cli connects to java-tron via gRPC. At startup it first looks for `config.conf` in the current working directory, then falls back to the bundled classpath resource. Use `SwitchNetwork` to switch among mainnet, testnets (Nile and Shasta), and custom networks. ## Quickstart @@ -62,13 +62,13 @@ This quickstart uses the interactive prompt. For automation, pass a standard com ```console # 1. Build $ git clone https://github.com/tronprotocol/wallet-cli.git -$ cd wallet-cli && ./gradlew build && cd build/libs +$ cd wallet-cli/java && ./gradlew build && cd build/libs # 2. Start the interactive wallet $ java -jar wallet-cli.jar # 3. In the wallet prompt: create an account (or ImportWallet), unlock, and inspect it -> RegisterWallet 123456 # create a keystore with password 123456 +> RegisterWallet # prompts twice for the password, then for mnemonic length > Login # unlock the account > GetAddress # show your address > GetBalance # TRX balance @@ -83,7 +83,7 @@ The full first-run walkthrough is in the [getting-started guide](docs/guide/gett ## Commands -Every command is documented on a family page under [docs/commands/](docs/commands/index.md). The **[command index](docs/commands/index.md)** has the full A–Z list linking each command to its section; in the wallet, typing any command shows its built-in usage tips. +Legacy interactive commands are documented on family pages under [docs/commands/](docs/commands/index.md). The **[interactive command index](docs/commands/index.md)** links each PascalCase command to its section. The separate **[standard CLI catalog](docs/commands/standard-cli.md)** lists the 107 one-shot commands and their global invocation contract. ### Wallets & accounts diff --git a/java/docs/commands/contract.md b/java/docs/commands/contract.md index 224143f31..6b47145fb 100644 --- a/java/docs/commands/contract.md +++ b/java/docs/commands/contract.md @@ -111,18 +111,20 @@ Example: ## TriggerConstantContract ```console -> TriggerConstantContract [ownerAddress] contractAddress method args isHex fee_limit value token_value token_id +> TriggerConstantContract ownerAddress contractAddress method args isHex [value token_value token_id] ``` -- `OwnerAddress` — the address of the account that initiated the transaction, optional, default is the address of the login account. +- `ownerAddress` — required. Pass a base58 address, or `#` to use the logged-in account. - `contractAddress` — smart contract address. - `method` — the name of the function and parameters; refer to the example. - `args` — parameter value; if you want to call `receive`, pass `#` instead. - `isHex` — the format of the parameters `method` and `args`; hex string or not. -- `fee_limit` — the most TRX allowed for consumption. +- `value` — optional call value in SUN; when supplied, `token_value` and `token_id` are required too. - `token_value` — number of TRC10. - `token_id` — TRC10 id; if not, use `#` instead. +The command accepts exactly five parameters without value/token fields, or eight parameters with all three optional fields. It does not take `fee_limit`. + Example: ```console diff --git a/java/docs/commands/index.md b/java/docs/commands/index.md index 66aef7619..0dcc215c3 100644 --- a/java/docs/commands/index.md +++ b/java/docs/commands/index.md @@ -2,12 +2,13 @@ Commands are grouped into family pages below; the A–Z index links each command to its owning page. Every family page is populated. Links point to the owning page (open it and jump to the command's section). -Type any command in the interactive wallet to see its built-in usage tips. +This page indexes legacy interactive commands. For one-shot kebab-case commands, global flags, and JSON output, use the [standard CLI reference](standard-cli.md). Type any command in the interactive wallet to see its built-in usage tips. ## By family | Family | Page | |---|---| +| Standard one-shot CLI | [standard-cli.md](standard-cli.md) | | Wallet management | [wallet.md](wallet.md) | | Account commands | [account.md](account.md) | | Network | [network.md](network.md) | diff --git a/java/docs/commands/multisig.md b/java/docs/commands/multisig.md index 2a514d2f1..7046d19da 100644 --- a/java/docs/commands/multisig.md +++ b/java/docs/commands/multisig.md @@ -2,6 +2,8 @@ Configure account permissions, co-sign transactions, inspect signature weight, and use TronLink multi-sign. For the underlying permission model, see [concepts/multisig](../concepts/multisig.md). +Many legacy REPL write commands accept `-m` only as their final token. That switch routes the operation through the interactive multi-sign flow instead of the normal single-signer broadcast. Support is command-specific; use the command's built-in usage text before appending it. The one-shot standard CLI uses command options documented by ` --help` and does not inherit this trailing-token convention. + ## How to use the multi-signature feature of wallet-cli Multi-signature allows other users to access the account in order to better manage it. There are three types of access: diff --git a/java/docs/commands/stake-v1-legacy.md b/java/docs/commands/stake-v1-legacy.md index aab565883..c2ab6e215 100644 --- a/java/docs/commands/stake-v1-legacy.md +++ b/java/docs/commands/stake-v1-legacy.md @@ -11,12 +11,13 @@ After the funds are frozen, the corresponding number of shares and bandwidth wil **Freeze operation is as follows:** ```console -> freezeBalance [OwnerAddress] frozen_balance frozen_duration [ResourceCode:0 BANDWIDTH, 1 ENERGY] [receiverAddress] +> freezeBalance [OwnerAddress] frozen_balance frozen_duration [ResourceCode:0 BANDWIDTH, 1 ENERGY, 2 TRON_POWER] [receiverAddress] ``` - `OwnerAddress` — the address of the account that initiated the transaction, optional, default is the address of the login account. - `frozen_balance` — the amount of frozen funds, the unit is Sun. The minimum value is **1000000 Sun (1 TRX)**. - `frozen_duration` — freeze time, this value is currently only allowed for **3 days**. +- `ResourceCode` — `0` BANDWIDTH; `1` ENERGY; `2` TRON_POWER only when `getAllowNewResourceModel` is enabled. TRON_POWER cannot be delegated, so omit `receiverAddress` when using `2`. For example: @@ -33,7 +34,7 @@ After the freezing time expires, funds can be unfrozen. **Unfreeze operation is as follows:** ```console -> unfreezeBalance [OwnerAddress] ResourceCode(0 BANDWIDTH, 1 CPU) [receiverAddress] +> unfreezeBalance [OwnerAddress] ResourceCode(0 BANDWIDTH, 1 ENERGY, 2 TRON_POWER) [receiverAddress] ``` ## How to delegate resource @@ -55,7 +56,7 @@ The latter two parameters are optional. If not set, the TRX is frozen to obtain ### UnfreezeBalance (undelegate) ```console -> unfreezeBalance [OwnerAddress] ResourceCode(0 BANDWIDTH, 1 CPU) [receiverAddress] +> unfreezeBalance [OwnerAddress] ResourceCode(0 BANDWIDTH, 1 ENERGY) [receiverAddress] ``` The latter two parameters are optional. If they are not set, the BANDWIDTH resource is unfrozen by default; when the `receiverAddress` is set, the delegated resources are unfrozen. diff --git a/java/docs/commands/stake-v2.md b/java/docs/commands/stake-v2.md index 42debeb2f..40e46b545 100644 --- a/java/docs/commands/stake-v2.md +++ b/java/docs/commands/stake-v2.md @@ -12,7 +12,7 @@ FreezeV2-based staking, resource delegation, and unfreeze withdrawal — the cur - `OwnerAddress` — the address of the account that initiated the transaction, optional, default is the address of the login account. - `frozen_balance` — the amount of frozen, the unit is the smallest unit (Sun), the minimum is 1000000 sun. -- `ResourceCode` — 0 BANDWIDTH; 1 ENERGY. +- `ResourceCode` — `0` BANDWIDTH; `1` ENERGY; `2` TRON_POWER only when `getAllowNewResourceModel` is enabled. Example: @@ -60,7 +60,7 @@ wallet> GetTransactionById 82244829971b4235d98a9f09ba67ddb09690ac2f879ad93e09ba - `OwnerAddress` — the address of the account that initiated the transaction, optional, default is the address of the login account. - `unfreezeBalance` — the amount of unfreeze, the unit is the smallest unit (Sun). -- `ResourceCode` — 0 BANDWIDTH; 1 ENERGY. +- `ResourceCode` — `0` BANDWIDTH; `1` ENERGY; `2` TRON_POWER only when `getAllowNewResourceModel` is enabled. Example: diff --git a/java/docs/commands/standard-cli.md b/java/docs/commands/standard-cli.md new file mode 100644 index 000000000..5c063c598 --- /dev/null +++ b/java/docs/commands/standard-cli.md @@ -0,0 +1,97 @@ +# Standard CLI command reference + +The Java jar has a one-shot CLI in addition to the legacy interactive prompt. Any invocation with a command token uses this mode: + +```console +$ java -jar wallet-cli.jar [global options] [command options] +$ java -jar wallet-cli.jar --network nile --output json get-balance --address T... +$ java -jar wallet-cli.jar get-balance --help +``` + +Running the jar with no arguments opens the prompt. Use `--interactive` as a standalone mode selector to open it explicitly. If a command token follows `--interactive`, the prompt still opens and that command is not executed; placing `--interactive` after a command instead passes it to that command and normally produces a usage error. A global option without a command, except `--help`, `--version`, or `--interactive`, returns a usage error with exit `2`. + +## Global options + +| Option | Meaning | +|---|---| +| `--output ` | Output format; default `text` | +| `--network ` | Select a built-in network or custom endpoint set | +| `--wallet ` | Select the wallet used by wallet-bound commands | +| `--grpc-endpoint ` | Override the gRPC endpoint | +| `--quiet` / `--verbose` | Suppress non-essential output or enable diagnostics; mutually exclusive | +| `--password-stdin` | Read the master password from stdin for commands that need one | +| `--help`, `-h`, `--version` | Global help or version when placed before the command | +| `--interactive` | Launch the legacy prompt; use without a command | + +Global execution options may appear before or after the command. Put command-specific options after the command and use ` --help` as the authority for required fields and authentication. + +JSON mode emits `{success, data}` on success or `{success, error, message}` on failure; alias resolution may add `meta.resolved`. Exit codes are `0` for success, `1` for execution failure, and `2` for usage errors. + +For password-bearing commands, keep the secret out of argv: + +```console +$ printf '%s\n' "$PW" | java -jar wallet-cli.jar --network nile --password-stdin send-coin --to T... --amount 1000000 +$ printf '%s\n' "$PW" | java -jar wallet-cli.jar --password-stdin register-wallet --name main --words 12 +``` + +## Wallet and alias commands + +These commands exist only in the standard CLI and do not have equivalent legacy REPL verbs: + +```console +$ java -jar wallet-cli.jar list-wallet +$ java -jar wallet-cli.jar set-active-wallet --name treasury +$ java -jar wallet-cli.jar get-active-wallet +$ java -jar wallet-cli.jar --network nile alias-add --name payroll --type ACCOUNT --address T... --note "operations" +$ java -jar wallet-cli.jar --network nile alias-list --type ACCOUNT +$ java -jar wallet-cli.jar --network nile alias-resolve --name payroll --type ACCOUNT +$ java -jar wallet-cli.jar --network nile alias-remove --name payroll +``` + +`set-active-wallet` requires exactly one of `--name` or `--address`. Alias data is network-scoped. `alias-add --type TOKEN` accepts `--decimals`; `--note` is valid only for `ACCOUNT` aliases. + +## Registered commands + +The registry currently contains 107 primary command names. Aliases are accepted by the parser but omitted here; global help prints the current primary catalog. + +### Wallets and aliases (12) + +`register-wallet`, `list-wallet`, `set-active-wallet`, `get-active-wallet`, `clear-wallet-keystore`, `reset-wallet`, `modify-wallet-name`, `generate-sub-account`, `alias-add`, `alias-remove`, `alias-list`, `alias-resolve` + +### Transactions (12) + +`send-coin`, `transfer-asset`, `transfer-usdt`, `participate-asset-issue`, `asset-issue`, `create-account`, `update-account`, `set-account-id`, `update-asset`, `broadcast-transaction`, `update-account-permission`, `gas-free-transfer` + +### Contracts (7) + +`deploy-contract`, `trigger-contract`, `trigger-constant-contract`, `estimate-energy`, `clear-contract-abi`, `update-setting`, `update-energy-limit` + +### Staking and rewards (10) + +`freeze-balance`, `freeze-balance-v2`, `unfreeze-balance`, `unfreeze-balance-v2`, `withdraw-expire-unfreeze`, `delegate-resource`, `undelegate-resource`, `cancel-all-unfreeze-v2`, `withdraw-balance`, `unfreeze-asset` + +### Witnesses and voting (4) + +`create-witness`, `update-witness`, `vote-witness`, `update-brokerage` + +### Governance proposals (3) + +`create-proposal`, `approve-proposal`, `delete-proposal` + +### Exchange and market (5) + +`exchange-create`, `exchange-inject`, `exchange-withdraw`, `market-sell-asset`, `market-cancel-order` + +### Queries (53) + +`get-address`, `get-balance`, `get-account`, `get-account-by-id`, `get-account-net`, `get-account-resource`, `get-usdt-balance`, `current-network`, `get-block`, `get-block-by-id`, `get-block-by-id-or-num`, `get-block-by-latest-num`, `get-block-by-limit-next`, `get-transaction-by-id`, `get-transaction-info-by-id`, `get-transaction-count-by-block-num`, `get-asset-issue-by-account`, `get-asset-issue-by-id`, `get-asset-issue-by-name`, `get-asset-issue-list-by-name`, `get-chain-parameters`, `get-bandwidth-prices`, `get-energy-prices`, `get-memo-fee`, `get-next-maintenance-time`, `get-contract`, `get-contract-info`, `get-delegated-resource`, `get-delegated-resource-v2`, `get-delegated-resource-account-index`, `get-delegated-resource-account-index-v2`, `get-can-delegated-max-size`, `get-available-unfreeze-count`, `get-can-withdraw-unfreeze-amount`, `get-brokerage`, `get-reward`, `list-nodes`, `list-witnesses`, `list-asset-issue`, `list-asset-issue-paginated`, `list-proposals`, `list-proposals-paginated`, `get-proposal`, `list-exchanges`, `list-exchanges-paginated`, `get-exchange`, `get-market-order-by-account`, `get-market-order-by-id`, `get-market-order-list-by-pair`, `get-market-pair-list`, `get-market-price-by-pair`, `gas-free-info`, `gas-free-trace` + +### Utility (1) + +`help` + +## See also + +- [Interactive command index](index.md) +- [Standard CLI contract](../standard-cli-contract-spec.md) +- [Configuration](../reference/config.md) diff --git a/java/docs/commands/transfer-trc10.md b/java/docs/commands/transfer-trc10.md index 3492cafbe..078476850 100644 --- a/java/docs/commands/transfer-trc10.md +++ b/java/docs/commands/transfer-trc10.md @@ -170,7 +170,7 @@ assetV2 Query the list of all the tokens by pagination. Returns a list of tokens that succeed the token located at offset. ```console -> ListAssetIssuePaginated address code salt +> ListAssetIssuePaginated offset limit ``` Example: diff --git a/java/docs/commands/vote-reward.md b/java/docs/commands/vote-reward.md index 38ff86fff..beec5ec9a 100644 --- a/java/docs/commands/vote-reward.md +++ b/java/docs/commands/vote-reward.md @@ -14,7 +14,7 @@ Voting requires share. Share can be obtained by freezing funds. For example: ```console -> freezeBalance 100000000 3 1 address # Freeze 10TRX and acquire 10 units of shares +> freezeBalance 10000000 3 1 address # Freeze 10 TRX and acquire 10 units of shares > votewitness 123455 witness1 4 witness2 6 # Cast 4 votes for witness1 and 6 votes for witness2 at the same time @@ -97,7 +97,7 @@ Apply to become a super representative candidate. ``` ```console -> CreateWitness TEDapYSVvAZ3aYH7w8N9tMEEFKaNKUD5Bp 007570646174654e616d6531353330363038383733343633 +> CreateWitness TEDapYSVvAZ3aYH7w8N9tMEEFKaNKUD5Bp https://sr.example.com ``` ### UpdateWitness @@ -105,7 +105,7 @@ Apply to become a super representative candidate. Edit the URL of the SR's official website. ```console -> UpdateWitness TEDapYSVvAZ3aYH7w8N9tMEEFKaNKUD5Bp 007570646174654e616d6531353330363038383733343633 +> UpdateWitness TEDapYSVvAZ3aYH7w8N9tMEEFKaNKUD5Bp https://sr.example.com/v2 ``` ## ListWitnesses diff --git a/java/docs/commands/wallet.md b/java/docs/commands/wallet.md index b7a8b4e1f..f24ab3bfc 100644 --- a/java/docs/commands/wallet.md +++ b/java/docs/commands/wallet.md @@ -73,7 +73,7 @@ Import a derived account from a Ledger device into wallet-cli. ```console wallet> ImportWalletByLedger -((Note:This will pair Ledger to user your hardward wallet) +(Note:This will pair Ledger to user your hardware wallet) Only one Ledger device is supported. If you have multiple devices, please ensure only one is connected. Ledger device found: Nano X Please input password. diff --git a/java/docs/guide/command-flow.md b/java/docs/guide/command-flow.md index 8fbbf2ae3..20eda6382 100644 --- a/java/docs/guide/command-flow.md +++ b/java/docs/guide/command-flow.md @@ -3,14 +3,14 @@ A worked end-to-end example of the legacy interactive session: build and run, register, back up, inspect, issue an asset, and transfer it. For one-shot commands and JSON output, see [Getting started](getting-started.md#standard-cli). ```console -$ cd wallet-cli +$ cd wallet-cli/java $ ./gradlew build $ ./gradlew run -> RegisterWallet 123456 (password = 123456) -> login 123456 +> RegisterWallet (prompts twice for the password, then for mnemonic length) +> login (prompts for the password) > getAddress address = TRfwwLDpr4excH4V4QzghLEsdYwkapTxnm' # backup it! -> BackupWallet 123456 +> BackupWallet (prompts for the password) priKey = 1234567890123456789012345678901234567890123456789012345678901234 # backup it!!! (BackupWallet2Base64 option) > getbalance Balance = 0 diff --git a/java/docs/guide/getting-started.md b/java/docs/guide/getting-started.md index 4448b4f1d..a14b0d1cd 100644 --- a/java/docs/guide/getting-started.md +++ b/java/docs/guide/getting-started.md @@ -9,13 +9,13 @@ Build, create an account, and send your first transfer from the interactive prom ```console # 1. Build $ git clone https://github.com/tronprotocol/wallet-cli.git -$ cd wallet-cli && ./gradlew build && cd build/libs +$ cd wallet-cli/java && ./gradlew build && cd build/libs # 2. Start the interactive wallet $ java -jar wallet-cli.jar # 3. In the wallet prompt: create an account (or ImportWallet), unlock, and inspect it -> RegisterWallet 123456 # create a keystore with password 123456 +> RegisterWallet # prompts twice for the password, then for mnemonic length > Login # unlock the account > GetAddress # show your address > GetBalance # TRX balance @@ -32,10 +32,10 @@ Passing a command selects the standard CLI instead of the prompt. It supports te ```console $ java -jar wallet-cli.jar --output json --network nile get-balance --address T... -$ java -jar wallet-cli.jar --network nile send-coin --to T... --amount 1000000 --password-stdin +$ printf '%s\n' "$PW" | java -jar wallet-cli.jar --network nile --password-stdin send-coin --to T... --amount 1000000 ``` -Run `java -jar wallet-cli.jar --help` for the command catalog and ` --help` for command options. The parsing, authentication, JSON envelope, and exit behavior are defined in the [standard CLI contract](../standard-cli-contract-spec.md). +Run `java -jar wallet-cli.jar --help` for the command catalog and ` --help` for command options. The [standard CLI command reference](../commands/standard-cli.md) lists all one-shot commands; parsing, authentication, JSON envelopes, and exit behavior are defined in the [standard CLI contract](../standard-cli-contract-spec.md). ## How to create account diff --git a/java/docs/guide/index.md b/java/docs/guide/index.md index 77c6ff100..22c2bf2d7 100644 --- a/java/docs/guide/index.md +++ b/java/docs/guide/index.md @@ -6,5 +6,6 @@ Task-oriented walkthroughs for wallet-cli (Java). |---|---| | [Getting started](getting-started.md) | Standard CLI and interactive entry modes; build, create an account, and send TRX | | [Command-line operation flow](command-flow.md) | A worked end-to-end legacy interactive session | +| [Standard CLI command reference](../commands/standard-cli.md) | One-shot commands, global flags, JSON mode, and the full registry | For per-command reference, see the [command index](../commands/index.md); for TRON mechanics, see [concepts](../concepts/index.md). diff --git a/java/docs/reference/config.md b/java/docs/reference/config.md index f2b4622bd..0b33975cb 100644 --- a/java/docs/reference/config.md +++ b/java/docs/reference/config.md @@ -1,10 +1,10 @@ # Configuration reference -Full reference for `config.conf`. wallet-cli reads the node config from `src/main/resources/config.conf`. You can also switch networks at runtime with the [`SwitchNetwork`](../commands/network.md) command, so editing `config.conf` is only needed for a custom node or the advanced features below. +Full reference for `config.conf`. At startup, wallet-cli first reads `./config.conf` from the process working directory. If that file does not exist, it loads the bundled classpath resource (`src/main/resources/config.conf` in a source checkout). You can also switch networks at runtime with [`SwitchNetwork`](../commands/network.md). ## Minimal config -A minimal `config.conf` only needs a network type and a full node to talk to: +A minimal `config.conf` needs a full-node endpoint. Keeping `net.type` is useful when configuring a mainnet API key, but it does not select the active network: ``` net { @@ -99,7 +99,7 @@ tronlink = { | Field | Purpose | |---|---| -| `net.type` | Network type (e.g. `mainnet`). | +| `net.type` | Controls whether `grpc.mainnet.apiKey` is loaded. It does not select the active network. | | `fullnode.ip.list` | Full node endpoint(s) `ip : port`. | | `soliditynode.ip.list` | Optional Solidity node endpoint(s). | | `ledger_debug` | Enable Ledger debug output. | @@ -111,7 +111,9 @@ tronlink = { ## Connecting to Java-tron -wallet-cli connects to Java-tron via the gRPC protocol, which can be deployed locally or remotely. Configure the Java-tron node IP and port in `src/main/resources/config.conf` so wallet-cli can talk to the node. You can also use `SwitchNetwork` to switch among mainnet, testnets (Nile and Shasta), and custom networks — see [commands/network](../commands/network.md). +wallet-cli connects to Java-tron via gRPC. The startup network is inferred by comparing `fullnode.ip.list` and `soliditynode.ip.list` with the built-in Mainnet, Nile, and Shasta endpoints; any other pair is `CUSTOM`. Consequently, `net.type = mainnet` with Nile endpoints still starts on Nile. Check the endpoints themselves before sending funds. + +To override the bundled file without rebuilding the jar, place `config.conf` in the directory from which you launch `java -jar`. You can also use `SwitchNetwork` to switch among mainnet, Nile, Shasta, and custom endpoints at runtime — see [commands/network](../commands/network.md). ## See also diff --git a/java/docs/standard-cli-contract-spec.md b/java/docs/standard-cli-contract-spec.md index 02a4f9e46..4a5ac7c54 100644 --- a/java/docs/standard-cli-contract-spec.md +++ b/java/docs/standard-cli-contract-spec.md @@ -113,6 +113,7 @@ Supported global options are: - `--version` - `--quiet` - `--verbose` + - `--password-stdin` - valued options: - `--output ` - `--network ` @@ -129,6 +130,7 @@ For Contract 1, this applies to valued global options only. ### Boundary Rules - Execution modifier global options are recognized before and after the command token. +- `--password-stdin` is an execution modifier and is recognized in either position. - Top-level mode selectors `--version` and `--interactive` are recognized only before the command token. - The first token before command resolution that does not begin with `-` is the command token. - The command token is normalized to lowercase for registry lookup. diff --git a/ts/docs/commands/account/activate.md b/ts/docs/commands/account/activate.md index 0810db993..9aeaaaff1 100644 --- a/ts/docs/commands/account/activate.md +++ b/ts/docs/commands/account/activate.md @@ -46,11 +46,11 @@ echo "$PW" | wallet-cli account activate --address TNewAddr9k2fP7cW4bXm1sV8dRj6e ``` ```console -⏳ Submitted — activate account - TxID a1b... +⏳ Account activated Address TNewAddr9k2fP7cW4bXm1sV8dRj6eL3aQz - Payer TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw (main) - Status pending + Payer TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw + TxID a1b... + Status pending — not yet on-chain ! Track it: wallet-cli tx info --network tron:nile --txid a1b... ``` @@ -66,9 +66,9 @@ echo "$PW" | wallet-cli account activate --address TNewAddr9k2fP7cW4bXm1sV8dRj6e ```console ✅ Account activated - TxID e7a... Address TNewAddr9k2fP7cW4bXm1sV8dRj6eL3aQz - Payer TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw (main) + Payer TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw + TxID e7a... Block #84,340,277 Fee 1.1 TRX Status success diff --git a/ts/docs/commands/account/history.md b/ts/docs/commands/account/history.md index 10eb675b8..cdb3cccac 100644 --- a/ts/docs/commands/account/history.md +++ b/ts/docs/commands/account/history.md @@ -10,14 +10,17 @@ wallet-cli account history [--limit ] [--only ] [options] ## Description -Lists recent transfers touching the account, newest first. TRON only — there is no EVM binding, so on an EVM network the command fails with `family_mismatch` rather than returning an empty list. History is served by **TronGrid**, not plain node RPC, so on TRON networks/endpoints without TronGrid it fails while `balance`/`info` still work. +Lists recent activity touching the account, newest first. TRON only — there is no EVM binding, so on an EVM network the command fails with `family_mismatch` rather than returning an empty list. History is served by **TronGrid**, not plain node RPC, so on TRON networks/endpoints without TronGrid it fails while `balance`/`info` still work. + +`--only token` selects TronGrid's TRC20 transfer endpoint. The current `--only native` path uses the general transactions endpoint and does not post-filter its records, so it may include non-native contract activity; omitting `--only` uses that same endpoint. Do not treat `only: "native"` in JSON as proof that every returned record is a TRX transfer. ## Options | Option | Description | |---|---| | `--limit ` | Max records, 1–200 (default 20) | -| `--only ` | Filter by transfer type; omit for all | +| `--only token` | Query TRC20 transfer history | +| `--only native` | Select the general transaction endpoint; currently not a strict native-transfer filter | Plus the [global options](../index.md#global-options-every-command). @@ -41,14 +44,14 @@ wallet-cli account history --limit 2 --network tron:nile -o json ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"account.history","data":{"address":"TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ","only":"all","count":2,"records":[{"txId":"fb7f8e6b44cd9100f6d1133acea341a2f3d53ab140a93c95b8f2bd74d3a2b366","time":1783780503000,"type":"Transfer","amount":"1","symbol":"TRX","from":"TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ","to":"TGkbaCYB4kRBc3Q6wjqkACefUvRwf2KzkH","counterparty":"TGkbaCYB4kRBc3Q6wjqkACefUvRwf2KzkH","status":"ok"},…]},"meta":{"durationMs":1556,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"account.history","data":{"address":"TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ","only":"all","count":2,"records":[{"txId":"fb7f8e6b44cd9100f6d1133acea341a2f3d53ab140a93c95b8f2bd74d3a2b366","time":1783780503000,"type":"Transfer","amount":"1","symbol":"TRX","from":"TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ","to":"TGkbaCYB4kRBc3Q6wjqkACefUvRwf2KzkH","counterparty":"TGkbaCYB4kRBc3Q6wjqkACefUvRwf2KzkH","status":"ok"},{"txId":"aa9c6d96b582201bda4ca1f7f35eff597371f5ca8e99db0df78d02d78f668a31","time":1783779301000,"type":"Transfer","amount":"2","symbol":"TRX","from":"TGkbaCYB4kRBc3Q6wjqkACefUvRwf2KzkH","to":"TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ","counterparty":"TGkbaCYB4kRBc3Q6wjqkACefUvRwf2KzkH","status":"ok"}]},"meta":{"durationMs":1556,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` ## Output | Field | Type | Meaning | |---|---|---| -| `address` / `only` / `count` | — | Query echo and record count | +| `address` / `only` / `count` | — | Query echo and returned record count; `only` echoes the selector and does not strengthen the filtering guarantee above | | `records[].txId` | string | Feed to [`tx info`](../tx/info.md) for detail | | `records[].time` | number | Epoch ms | | `records[].type` | string | Transaction type (e.g. `Transfer`, `CreateSmart`) | @@ -59,7 +62,7 @@ wallet-cli account history --limit 2 --network tron:nile -o json ## Exit status -`0` · `1` execution failure (incl. TronGrid unavailable) · `2` usage error (limit out of 1–200). +`0` · `1` execution failure (`history_not_supported`, including a missing or incompatible TronGrid endpoint) · `2` usage error (limit out of 1–200). ## See also diff --git a/ts/docs/commands/account/info.md b/ts/docs/commands/account/info.md index 22d302b26..fa875fdf5 100644 --- a/ts/docs/commands/account/info.md +++ b/ts/docs/commands/account/info.md @@ -40,7 +40,7 @@ wallet-cli account info --network tron:nile -o json ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"account.info","data":{"address":"TNmoJ3Be59WFEq5dsW6eCkZjveiL3G8HVB","account":{"account_name":"71612d74657374","balance":"9915803110","create_time":1753860222000,"owner_permission":{…},"active_permission":[…],"frozenV2":[{},{"type":"ENERGY"},{"type":"TRON_POWER"}],…},"resources":{"bandwidth":{"used":325,"limit":600},"energy":{"used":0,"limit":0}}},"meta":{"durationMs":746,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"account.info","data":{"address":"TNmoJ3Be59WFEq5dsW6eCkZjveiL3G8HVB","account":{"account_name":"71612d74657374","balance":"9915803110","create_time":1753860222000,"owner_permission":{},"active_permission":[{}],"frozenV2":[{},{"type":"ENERGY"},{"type":"TRON_POWER"}]},"resources":{"bandwidth":{"used":325,"limit":600},"energy":{"used":0,"limit":0}}},"meta":{"durationMs":746,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` On an EVM network the same command reports the EVM account state: diff --git a/ts/docs/commands/account/set.md b/ts/docs/commands/account/set.md index d10ee2b4c..5ef073392 100644 --- a/ts/docs/commands/account/set.md +++ b/ts/docs/commands/account/set.md @@ -48,7 +48,7 @@ echo "$PW" | wallet-cli account set --name "Acme Treasury" --network tron:nile - ```console ✅ On-chain name set - Account TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw (main) + Address TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw Name Acme Treasury TxID f2b... Block #84,341,590 @@ -72,8 +72,8 @@ echo "$PW" | wallet-cli account set --id acme-treasury-01 --network tron:nile -- ```console ✅ Account id set - Account TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw (main) - Id acme-treasury-01 + Address TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw + ID acme-treasury-01 TxID 3d9... Block #84,341,730 Fee 0.3 TRX diff --git a/ts/docs/commands/asset/issue.md b/ts/docs/commands/asset/issue.md index 55be9419d..d31bf4d9a 100644 --- a/ts/docs/commands/asset/issue.md +++ b/ts/docs/commands/asset/issue.md @@ -96,7 +96,7 @@ echo "$PW" | wallet-cli asset issue --name MyToken --abbr MTK --supply 100000000 ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"asset.issue","data":{"kind":"asset-issue","stage":"confirmed","txId":"7d1...","confirmed":true,"blockNumber":57883010,"failed":false,"assetId":"1000123","name":"MyToken","abbr":"MTK","totalSupply":1000000000000000,"precision":6,"price":"1:100","trxNum":1,"num":100,"startTime":1785542400000,"endTime":1788134400000,"url":"https://mytoken.io","description":"Demo TRC10","freeAssetNetLimit":0,"publicFreeAssetNetLimit":0,"frozenSupply":[{"amount":100000000000000,"days":30},{"amount":50000000000000,"days":90}],"feeSun":1024000000,"resource":{"netUsage":312,"netFeeSun":0,"energyUsage":0,"energyFeeSun":0}},"meta":{"durationMs":6720,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"asset.issue","data":{"kind":"asset-issue","stage":"confirmed","txId":"7d1...","confirmed":true,"blockNumber":57883010,"feeSun":1024000000,"netUsed":312,"netFeeSun":0,"failed":false,"assetId":"1000123","issuerAddress":"TQkXm4vN...","name":"MyToken","abbr":"MTK","totalSupply":"1000000000000000","precision":6,"price":"1:100","trxNum":1,"num":100,"startTime":1785542400000,"endTime":1788134400000,"url":"https://mytoken.io","description":"Demo TRC10","freeAssetNetLimit":0,"publicFreeAssetNetLimit":0,"frozenSupply":[{"amount":"100000000000000","days":30},{"amount":"50000000000000","days":90}]},"meta":{"durationMs":6720,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` ## Output @@ -106,9 +106,9 @@ echo "$PW" | wallet-cli asset issue --name MyToken --abbr MTK --supply 100000000 | Stage | Fields | |---|---| | default (submit) | `kind: "asset-issue"`, `stage: "submitted"`, `txId`, and the token definition below except `assetId` | -| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, `feeSun`, `resource`, `failed`, and `assetId` — assigned by the chain, so known only once confirmed | +| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, flat settlement fields when returned (`feeSun`, `energyUsed`, `netUsed`, `energyFeeSun`, `netFeeSun`), `failed`, and `assetId` — assigned by the chain, so known only once confirmed | -Definition fields: `name`, `abbr`, `totalSupply` (raw), `precision`, `price` (the `trx:tokens` string as given) with the stored `trxNum` / `num` pair, `startTime` / `endTime` (ms since epoch), `url`, `description`, `freeAssetNetLimit`, `publicFreeAssetNetLimit`, and `frozenSupply[]` (`amount` raw, `days`). +Definition fields: `issuerAddress`, `name`, `abbr`, `totalSupply` (raw decimal string), `precision`, `price` (the `trx:tokens` string as given) with the stored `trxNum` / `num` pair, `startTime` / `endTime` (ms since epoch), `url`, `description`, `freeAssetNetLimit`, `publicFreeAssetNetLimit`, and `frozenSupply[]` (`amount` raw decimal string, `days`). Confirmation resource fields are flat; there is no `resource` object and the bandwidth field is `netUsed`, not `netUsage`. ## Exit status diff --git a/ts/docs/commands/asset/participate.md b/ts/docs/commands/asset/participate.md index 7b82ab30e..43a86efb8 100644 --- a/ts/docs/commands/asset/participate.md +++ b/ts/docs/commands/asset/participate.md @@ -66,7 +66,7 @@ echo "$PW" | wallet-cli asset participate 1000124 --pay 100 --network tron:nile ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"asset.participate","data":{"kind":"asset-participate","stage":"confirmed","txId":"4c8...","confirmed":true,"blockNumber":57883402,"failed":false,"assetId":"1000124","name":"BetaToken","issuerAddress":"TBeta9mR...","participantAddress":"TQkXm4vN...","paidSun":100000000,"receivedAmount":10000000000,"feeSun":0,"resource":{"netUsage":301,"netFeeSun":0,"energyUsage":0,"energyFeeSun":0}},"meta":{"durationMs":6450,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"asset.participate","data":{"kind":"asset-participate","stage":"confirmed","txId":"4c8...","confirmed":true,"blockNumber":57883402,"feeSun":0,"netUsed":301,"netFeeSun":0,"failed":false,"assetId":"1000124","name":"BetaToken","issuerAddress":"TBeta9mR...","participantAddress":"TQkXm4vN...","paidSun":"100000000","receivedAmount":"10000000000","precision":6},"meta":{"durationMs":6450,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` ## Output @@ -76,9 +76,9 @@ echo "$PW" | wallet-cli asset participate 1000124 --pay 100 --network tron:nile | Stage | Fields | |---|---| | default (submit) | `kind: "asset-participate"`, `stage: "submitted"`, `txId`, `assetId`, `name`, `issuerAddress`, `participantAddress`, `paidSun`, `receivedAmount` | -| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, `feeSun`, `resource`, `failed` | +| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, flat settlement fields when returned (`feeSun`, `energyUsed`, `netUsed`, `energyFeeSun`, `netFeeSun`), and `failed` | -`paidSun` is the TRX spent in sun; `receivedAmount` is the token amount in its smallest unit (text shows both in human units). +`paidSun` is the TRX spent in sun; `receivedAmount` is the token amount in its smallest unit. Both are decimal strings; `precision` is included so text and machine consumers can scale the token amount. ## Exit status diff --git a/ts/docs/commands/asset/unfreeze.md b/ts/docs/commands/asset/unfreeze.md index 25a2cc4eb..0bd748d1e 100644 --- a/ts/docs/commands/asset/unfreeze.md +++ b/ts/docs/commands/asset/unfreeze.md @@ -65,7 +65,7 @@ echo "$PW" | wallet-cli asset unfreeze --network tron:nile --wait --password-std ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"asset.unfreeze","data":{"kind":"asset-unfreeze","stage":"confirmed","txId":"6a5...","confirmed":true,"blockNumber":57883560,"failed":false,"assetId":"1000123","name":"MyToken","issuerAddress":"TQkXm4vN...","releasedAmount":100000000000000,"stillFrozenAmount":50000000000000,"feeSun":0,"resource":{"netUsage":288,"netFeeSun":0,"energyUsage":0,"energyFeeSun":0}},"meta":{"durationMs":6410,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"asset.unfreeze","data":{"kind":"asset-unfreeze","stage":"confirmed","txId":"6a5...","confirmed":true,"blockNumber":57883560,"feeSun":0,"netUsed":288,"netFeeSun":0,"failed":false,"assetId":"1000123","name":"MyToken","issuerAddress":"TQkXm4vN...","releasedAmount":"100000000000000","stillFrozenAmount":"50000000000000","precision":6},"meta":{"durationMs":6410,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` ## Output @@ -75,9 +75,9 @@ echo "$PW" | wallet-cli asset unfreeze --network tron:nile --wait --password-std | Stage | Fields | |---|---| | default (submit) | `kind: "asset-unfreeze"`, `stage: "submitted"`, `txId`, `assetId`, `name`, `issuerAddress` | -| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, `feeSun`, `resource`, `failed`, `releasedAmount`, `stillFrozenAmount` | +| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, flat settlement fields when returned (`feeSun`, `energyUsed`, `netUsed`, `energyFeeSun`, `netFeeSun`), `failed`, `releasedAmount`, `stillFrozenAmount` | -`releasedAmount` and `stillFrozenAmount` are raw amounts (smallest unit) and reflect what the confirmed transaction actually did. +`releasedAmount` and `stillFrozenAmount` are raw decimal strings (smallest unit); `precision` is included for scaling. The confirmed `releasedAmount` reflects what the receipt reports. ## Exit status diff --git a/ts/docs/commands/asset/update.md b/ts/docs/commands/asset/update.md index 61f3dc9ba..152144a7d 100644 --- a/ts/docs/commands/asset/update.md +++ b/ts/docs/commands/asset/update.md @@ -68,7 +68,7 @@ echo "$PW" | wallet-cli asset update --url https://mytoken.io/v2 --network tron: ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"asset.update","data":{"kind":"asset-update","stage":"confirmed","txId":"9e3...","confirmed":true,"blockNumber":57883190,"failed":false,"assetId":"1000123","name":"MyToken","issuerAddress":"TQkXm4vN...","url":"https://mytoken.io/v2","description":"Demo TRC10","freeAssetNetLimit":0,"publicFreeAssetNetLimit":0,"feeSun":0,"resource":{"netUsage":295,"netFeeSun":0,"energyUsage":0,"energyFeeSun":0}},"meta":{"durationMs":6480,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"asset.update","data":{"kind":"asset-update","stage":"confirmed","txId":"9e3...","confirmed":true,"blockNumber":57883190,"feeSun":0,"netUsed":295,"netFeeSun":0,"failed":false,"assetId":"1000123","name":"MyToken","issuerAddress":"TQkXm4vN...","url":"https://mytoken.io/v2","description":"Demo TRC10","freeAssetNetLimit":0,"publicFreeAssetNetLimit":0},"meta":{"durationMs":6480,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` ## Output @@ -78,9 +78,9 @@ echo "$PW" | wallet-cli asset update --url https://mytoken.io/v2 --network tron: | Stage | Fields | |---|---| | default (submit) | `kind: "asset-update"`, `stage: "submitted"`, `txId`, `assetId`, `name`, `issuerAddress`, and the four fields as submitted | -| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, `feeSun`, `resource`, `failed` | +| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, flat settlement fields when returned (`feeSun`, `energyUsed`, `netUsed`, `energyFeeSun`, `netFeeSun`), and `failed` | -The four fields are `url`, `description`, `freeAssetNetLimit`, and `publicFreeAssetNetLimit` — always all four, including the ones read back unchanged. +The four fields are `url`, `description`, `freeAssetNetLimit`, and `publicFreeAssetNetLimit` — always all four, including the ones read back unchanged. Confirmation resource fields are flat; there is no nested `resource` object. ## Exit status diff --git a/ts/docs/commands/backup.md b/ts/docs/commands/backup.md index bbdc48b70..6609ecbd0 100644 --- a/ts/docs/commands/backup.md +++ b/ts/docs/commands/backup.md @@ -100,7 +100,7 @@ printf '%s' "$PW" | wallet-cli backup main --keystore --out ./main.keystore.json ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"backup","data":{"accountId":"wlt_d1qbj2fb.0","label":"main","type":"seed","index":0,"active":true,"addresses":{"tron":"TQkXm4vN...5Zt7Uw","evm":"0x7B28FE10...46C9C"},"seedId":"wlt_d1qbj2fb","derivationPath":{"tron":"m/44'/195'/0'/0/0","evm":"m/44'/60'/0'/0/0"},"family":"tron","secretType":"privateKey","format":"keystore","out":"./main.keystore.json","fileMode":"0600","bytes":491},"meta":{"durationMs":1420,"warnings":[]}} +{"schema":"wallet-cli.result.v1","success":true,"command":"backup","data":{"accountId":"wlt_d1qbj2fb.0","label":"main","type":"seed","index":0,"active":true,"addresses":{"tron":"TQkXm4vN...5Zt7Uw","evm":"0x7B28FE10...46C9C"},"seedId":"wlt_d1qbj2fb","derivationPath":{"tron":"m/44'/195'/0'/0/0","evm":"m/44'/60'/0'/0/0"},"family":"tron","secretType":"privateKey","format":"keystore","out":"./main.keystore.json","fileMode":"0600","bytes":491},"meta":{"durationMs":1420,"warnings":[]},"chain":{"family":"tron","network":"tron:mainnet","chainId":"mainnet"}} ``` The audit log: @@ -123,12 +123,12 @@ wallet-cli backup --records --limit 3 -o json ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"backup.records","data":{"records":[{"operation":"backup --keystore","accountId":"wlt_d1qbj2fb.0","account":"TQkXm4vN...5Zt7Uw","label":"main","out":"./wlt_d1qbj2fb.0-1785930000.keystore.json","timestamp":"2026-08-05T11:40:00Z"},{"operation":"backup","accountId":"wlt_d1qbj2fb.0","account":"TQkXm4vN...5Zt7Uw","label":"main","out":"./wlt_d1qbj2fb.0-1785834720.json","timestamp":"2026-08-04T09:12:00Z"},{"operation":"backup","accountId":"wlt_9x3k2m7p.0","account":"TBeta9mR...8pLx","label":null,"out":"./tbeta-seed.json","timestamp":"2026-07-30T22:03:00Z"}]},"meta":{"durationMs":8,"warnings":[],"pagination":{"offset":0,"limit":3,"total":12}}} +{"schema":"wallet-cli.result.v1","success":true,"command":"backup.records","data":{"records":[{"operation":"backup --keystore","accountId":"wlt_d1qbj2fb.0","account":"TQkXm4vN...5Zt7Uw","label":"main","out":"./wlt_d1qbj2fb.0-1785930000.keystore.json","timestamp":"2026-08-05T11:40:00Z"},{"operation":"backup","accountId":"wlt_d1qbj2fb.0","account":"TQkXm4vN...5Zt7Uw","label":"main","out":"./wlt_d1qbj2fb.0-1785834720.json","timestamp":"2026-08-04T09:12:00Z"},{"operation":"backup","accountId":"wlt_9x3k2m7p.0","account":"TBeta9mR...8pLx","label":null,"out":"./tbeta-seed.json","timestamp":"2026-07-30T22:03:00Z"}]},"meta":{"durationMs":8,"warnings":[],"pagination":{"offset":0,"limit":3,"total":12}},"chain":{"family":"tron","network":"tron:mainnet","chainId":"mainnet"}} ``` ## Output -Both forms are local commands — no `chain` block — and they carry different `command` ids: `backup` for an export, `backup.records` for the log. +Both forms are local and contact no node, but `backup` has an optional network display selector: the selected or default network chooses which family `--keystore` exports. The result therefore includes a `chain` block, including for `--records`. The forms carry different `command` ids: `backup` for an export, `backup.records` for the log. `data` for an export is the account plus the file's details: diff --git a/ts/docs/commands/block.md b/ts/docs/commands/block.md index 5925eabf5..bd7a64d9a 100644 --- a/ts/docs/commands/block.md +++ b/ts/docs/commands/block.md @@ -37,7 +37,7 @@ wallet-cli block 70433745 --network tron:nile -o json ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"block","data":{"block":{"blockID":"0000000041e6a3c3…","block_header":{"raw_data":{"number":69093315,"txTrieRoot":"…","witness_address":"41…","parentHash":"…","version":31,"timestamp":1783783761000},"witness_signature":"…"},"transactions":[{…}]}},"meta":{"durationMs":126,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"block","data":{"block":{"blockID":"0000000041e6a3c3…","block_header":{"raw_data":{"number":69093315,"txTrieRoot":"…","witness_address":"41…","parentHash":"…","version":31,"timestamp":1783783761000},"witness_signature":"…"},"transactions":[{}]}},"meta":{"durationMs":126,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` On an EVM network the text summary carries the gas and fee figures a block actually has: diff --git a/ts/docs/commands/contact/add.md b/ts/docs/commands/contact/add.md index d6bded037..4706b0f96 100644 --- a/ts/docs/commands/contact/add.md +++ b/ts/docs/commands/contact/add.md @@ -12,7 +12,7 @@ wallet-cli contact add

[--note ] Saves a recipient (name → address) to the local address book. The name can then be used wherever a recipient is expected — [`tx send --to`](../tx/send.md) and [`gasfree transfer --to`](../gasfree/transfer.md). The address is validated locally against the family it belongs to (`T…` = TRON, `0x…` = EVM), which is also the family recorded on the entry; no node access. -A contact belongs to **one family**. Filing a TRON address under EVM (or the reverse) is refused with `invalid_address`, because a name that resolved to an address that does not exist on the selected network would be worse than no name at all. +A contact belongs to **one family**, inferred directly from its address; this command has no family or network selector. A malformed address, or one that belongs to no supported family, is refused with `invalid_address`. Family compatibility is checked later when a contact is used by a chain command. The name must be 1–64 safe characters (no control or formatting characters) and must not **resemble** an address. The resemblance check is deliberately loose — it matches a near miss too, a checksum typo or a truncated paste — so that a mistyped address can never silently fall through to a name lookup and pay whoever registered that name. Names are compared case-insensitively after Unicode NFKC normalization. @@ -37,7 +37,7 @@ wallet-cli contact add alice TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub --note "Alice ma Note Alice mainnet ``` -An EVM address is filed the same way, under `family: "evm"`: +An EVM address is filed the same way. The family is used internally for routing but is not exposed in the public contact object: ```bash wallet-cli contact add alice-eth 0x742d35Cc6634C0532925a3b844Bc454e4438f44e --note "Alice mainnet" @@ -48,7 +48,7 @@ wallet-cli contact add alice TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub --note "Alice ma ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"contact.add","data":{"name":"alice","address":"TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub","note":"Alice mainnet","family":"tron"},"meta":{"durationMs":4,"warnings":[]}} +{"schema":"wallet-cli.result.v1","success":true,"command":"contact.add","data":{"name":"alice","address":"TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub","note":"Alice mainnet"},"meta":{"durationMs":4,"warnings":[]}} ``` ## Output @@ -58,7 +58,6 @@ wallet-cli contact add alice TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub --note "Alice ma | `name` | string | Contact name | | `address` | string | Recipient address | | `note` | string \| null | The note, or `null` | -| `family` | string | Chain family the address belongs to — `tron` or `evm`, detected from the address | ## Exit status diff --git a/ts/docs/commands/contact/list.md b/ts/docs/commands/contact/list.md index 800d98c9a..8b1f643e6 100644 --- a/ts/docs/commands/contact/list.md +++ b/ts/docs/commands/contact/list.md @@ -33,14 +33,14 @@ wallet-cli contact list -o json ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"contact.list","data":{"contacts":[{"name":"alice","address":"TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub","note":"Alice mainnet","family":"tron"},{"name":"bob","address":"TXe4Kd8nP2rF9gH5jL3mV6cW1bN7yS0aQz","note":null,"family":"tron"}]},"meta":{"durationMs":3,"warnings":[]}} +{"schema":"wallet-cli.result.v1","success":true,"command":"contact.list","data":{"contacts":[{"name":"alice","address":"TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub","note":"Alice mainnet"},{"name":"bob","address":"TXe4Kd8nP2rF9gH5jL3mV6cW1bN7yS0aQz","note":null}]},"meta":{"durationMs":3,"warnings":[]}} ``` ## Output | Field | Type | Meaning | |---|---|---| -| `contacts[]` | array | Recipients, each `{name, address, note, family}` — `note` is `null` when unset | +| `contacts[]` | array | Recipients, each `{name, address, note}` — `note` is `null` when unset. Family remains an internal routing detail and is not returned | ## Exit status diff --git a/ts/docs/commands/contract/clear-abi.md b/ts/docs/commands/contract/clear-abi.md index fc92f5781..5cf458d41 100644 --- a/ts/docs/commands/contract/clear-abi.md +++ b/ts/docs/commands/contract/clear-abi.md @@ -62,7 +62,7 @@ echo "$PW" | wallet-cli contract clear-abi TQ5nJ8mV...4wRe --network tron:nile - ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"contract.clear-abi","data":{"kind":"contract-clear-abi","stage":"confirmed","txId":"3f7...","confirmed":true,"blockNumber":57882140,"failed":false,"contractAddress":"TQ5nJ8mV...","deployerAddress":"TQkXm4vN...","feeSun":0,"resource":{"netUsage":287,"netFeeSun":0,"energyUsage":0,"energyFeeSun":0}},"meta":{"durationMs":6510,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"contract.clear-abi","data":{"kind":"contract-clear-abi","stage":"confirmed","txId":"3f7...","confirmed":true,"blockNumber":57882140,"failed":false,"contractAddress":"TQ5nJ8mV...","deployerAddress":"TQkXm4vN...","feeSun":0,"energyUsed":0,"netUsed":287,"energyFeeSun":0,"netFeeSun":0,"resource":{"netUsage":287,"netFeeSun":0,"energyUsage":0,"energyFeeSun":0}},"meta":{"durationMs":6510,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` ## Output @@ -72,7 +72,7 @@ echo "$PW" | wallet-cli contract clear-abi TQ5nJ8mV...4wRe --network tron:nile - | Stage | Fields | |---|---| | default (submit) | `kind: "contract-clear-abi"`, `stage: "submitted"`, `txId`, `contractAddress`, `deployerAddress` | -| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, `feeSun`, `resource`, `failed` | +| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, flat settlement fields when returned (`feeSun`, `energyUsed`, `netUsed`, `energyFeeSun`, `netFeeSun`), their governance compatibility view `resource` (`netUsage`, `netFeeSun`, `energyUsage`, `energyFeeSun`), and `failed` | ## Exit status diff --git a/ts/docs/commands/contract/create2.md b/ts/docs/commands/contract/create2.md index 22511572a..4e255421e 100644 --- a/ts/docs/commands/contract/create2.md +++ b/ts/docs/commands/contract/create2.md @@ -75,7 +75,7 @@ This is a local command, so the envelope carries no `chain` block. ## Exit status -`0` success · `1` execution failure (`io_error` — `--code-file` cannot be read) · `2` usage error (`missing_option` — no `--deployer` / `--salt`, or neither code source; `invalid_option` — both `--code` and `--code-file`; `invalid_value` — malformed deployer address, non-hex code, or a salt outside the 64-bit signed range). +`0` success · `1` execution failure · `2` usage error (`missing_option` — no `--deployer` or `--salt`; `file_not_found` — `--code-file` does not exist; `invalid_value` — neither or both code sources, an unreadable code file, malformed deployer address, non-hex code, or a salt outside the signed 64-bit range). ## See also diff --git a/ts/docs/commands/contract/set-origin-energy-limit.md b/ts/docs/commands/contract/set-origin-energy-limit.md index 0c96fd486..041b64829 100644 --- a/ts/docs/commands/contract/set-origin-energy-limit.md +++ b/ts/docs/commands/contract/set-origin-energy-limit.md @@ -66,7 +66,7 @@ echo "$PW" | wallet-cli contract set-origin-energy-limit TQ5nJ8mV...4wRe 5000000 ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"contract.set-origin-energy-limit","data":{"kind":"contract-set-origin-energy-limit","stage":"confirmed","txId":"3a9...","confirmed":true,"blockNumber":57882265,"failed":false,"contractAddress":"TQ5nJ8mV...","deployerAddress":"TQkXm4vN...","originEnergyLimit":50000000,"feeSun":0,"resource":{"netUsage":290,"netFeeSun":0,"energyUsage":0,"energyFeeSun":0}},"meta":{"durationMs":6530,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"contract.set-origin-energy-limit","data":{"kind":"contract-set-origin-energy-limit","stage":"confirmed","txId":"3a9...","confirmed":true,"blockNumber":57882265,"failed":false,"contractAddress":"TQ5nJ8mV...","deployerAddress":"TQkXm4vN...","originEnergyLimit":50000000,"feeSun":0,"energyUsed":0,"netUsed":290,"energyFeeSun":0,"netFeeSun":0,"resource":{"netUsage":290,"netFeeSun":0,"energyUsage":0,"energyFeeSun":0}},"meta":{"durationMs":6530,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` ## Output @@ -76,7 +76,7 @@ echo "$PW" | wallet-cli contract set-origin-energy-limit TQ5nJ8mV...4wRe 5000000 | Stage | Fields | |---|---| | default (submit) | `kind: "contract-set-origin-energy-limit"`, `stage: "submitted"`, `txId`, `contractAddress`, `deployerAddress`, `originEnergyLimit` | -| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, `feeSun`, `resource`, `failed` | +| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, flat settlement fields when returned (`feeSun`, `energyUsed`, `netUsed`, `energyFeeSun`, `netFeeSun`), their governance compatibility view `resource` (`netUsage`, `netFeeSun`, `energyUsage`, `energyFeeSun`), and `failed` | `originEnergyLimit` is the value now in effect. diff --git a/ts/docs/commands/contract/set-user-resource-percent.md b/ts/docs/commands/contract/set-user-resource-percent.md index ea5e503d4..130d67bec 100644 --- a/ts/docs/commands/contract/set-user-resource-percent.md +++ b/ts/docs/commands/contract/set-user-resource-percent.md @@ -68,7 +68,7 @@ echo "$PW" | wallet-cli contract set-user-resource-percent TQ5nJ8mV...4wRe 100 - ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"contract.set-user-resource-percent","data":{"kind":"contract-set-user-resource-percent","stage":"confirmed","txId":"8b2...","confirmed":true,"blockNumber":57882388,"failed":false,"contractAddress":"TQ5nJ8mV...","deployerAddress":"TQkXm4vN...","consumeUserResourcePercent":100,"feeSun":0,"resource":{"netUsage":289,"netFeeSun":0,"energyUsage":0,"energyFeeSun":0}},"meta":{"durationMs":6470,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"contract.set-user-resource-percent","data":{"kind":"contract-set-user-resource-percent","stage":"confirmed","txId":"8b2...","confirmed":true,"blockNumber":57882388,"failed":false,"contractAddress":"TQ5nJ8mV...","deployerAddress":"TQkXm4vN...","consumeUserResourcePercent":100,"feeSun":0,"energyUsed":0,"netUsed":289,"energyFeeSun":0,"netFeeSun":0,"resource":{"netUsage":289,"netFeeSun":0,"energyUsage":0,"energyFeeSun":0}},"meta":{"durationMs":6470,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` ## Output @@ -78,7 +78,7 @@ echo "$PW" | wallet-cli contract set-user-resource-percent TQ5nJ8mV...4wRe 100 - | Stage | Fields | |---|---| | default (submit) | `kind: "contract-set-user-resource-percent"`, `stage: "submitted"`, `txId`, `contractAddress`, `deployerAddress`, `consumeUserResourcePercent` | -| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, `feeSun`, `resource`, `failed` | +| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, flat settlement fields when returned (`feeSun`, `energyUsed`, `netUsed`, `energyFeeSun`, `netFeeSun`), their governance compatibility view `resource` (`netUsage`, `netFeeSun`, `energyUsage`, `energyFeeSun`), and `failed` | `consumeUserResourcePercent` is the value now in effect — the caller's share. diff --git a/ts/docs/commands/current.md b/ts/docs/commands/current.md index db6bd61ce..cdae2ff12 100644 --- a/ts/docs/commands/current.md +++ b/ts/docs/commands/current.md @@ -52,7 +52,7 @@ The QR encodes **one** address — the receive address for the selected network. wallet-cli current --qr --network evm:11155111 ``` -The QR is a terminal rendering only and scans from a real terminal (where the block characters line up); `-o json` is unchanged by `--qr` (machine consumers take the address and generate their own code). If the terminal is non-interactive or too narrow to fit it, it degrades to printing the addresses with a warning: +The QR is a terminal rendering only and scans from a real terminal (where the block characters line up). In JSON mode no QR pixels are rendered; `--qr` validates that the selected account has an address for the selected network and adds that value as `data.receiveAddress`. If the text terminal is non-interactive or too narrow to fit the QR, it degrades to printing the addresses with a warning: ```console warning: terminal is non-interactive or too narrow for a complete QR code; showing the full address only @@ -91,6 +91,7 @@ error [missing_wallet_address]: no active account; import one first | `derivationPath` | object \| null | Per-family BIP32 path for `seed` accounts; `null` otherwise | | `seedId` | string | Owning seed wallet id (`seed` accounts only) | | `family` | string | Chain family this account is bound to — single-family accounts (`watch`, `ledger`) only | +| `receiveAddress` | string | Present in JSON only when `--qr` was requested; address selected by `--network` | The `chain` block echoes the network selected for display; the command contacts no node. diff --git a/ts/docs/commands/gasfree/info.md b/ts/docs/commands/gasfree/info.md index 33aeed700..9d99a1e0d 100644 --- a/ts/docs/commands/gasfree/info.md +++ b/ts/docs/commands/gasfree/info.md @@ -27,14 +27,14 @@ wallet-cli gasfree info --account main --network tron:nile ``` ```console -Account main (TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw) +Owner TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw GasFree address TVjsyZ7fYF3qCcNaMxN5PMWmSgYcCyqZfw Status active Nonce 4 -Supported tokens (1) - Token Activation fee Transfer fee - USDT 1 USDT 0.5 USDT +| Token | Balance | Activation fee | Transfer fee | +| ----- | ------- | -------------- | ------------ | +| USDT | 125 USDT | 1 USDT | 0.5 USDT | ``` ```bash @@ -42,7 +42,7 @@ wallet-cli gasfree info --account main --network tron:nile -o json ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"gasfree.info","data":{"ownerAddress":"TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw","gasFreeAddress":"TVjsyZ7fYF3qCcNaMxN5PMWmSgYcCyqZfw","active":true,"nonce":4,"tokens":[{"symbol":"USDT","address":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t","decimals":6,"activateFee":"1000000","transferFee":"500000"}]},"meta":{"durationMs":380,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"gasfree.info","data":{"ownerAddress":"TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw","gasFreeAddress":"TVjsyZ7fYF3qCcNaMxN5PMWmSgYcCyqZfw","active":true,"nonce":"4","tokens":[{"symbol":"USDT","address":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t","decimals":6,"activateFee":"1000000","transferFee":"500000","balance":"125000000"}]},"meta":{"durationMs":380,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` ## Output @@ -52,8 +52,8 @@ wallet-cli gasfree info --account main --network tron:nile -o json | `ownerAddress` | string | The account's own TRON address | | `gasFreeAddress` | string | Derived GasFree address (receive/pay here) | | `active` | boolean | Whether the GasFree address is activated on-chain | -| `nonce` | number | Current per-address nonce | -| `tokens[]` | array | Supported tokens: `{symbol, address, decimals, activateFee, transferFee}` — fees in the token's base units | +| `nonce` | string | Current per-address nonce, as an unsigned decimal string | +| `tokens[]` | array | Supported tokens: `{symbol, address, decimals, activateFee, transferFee, balance}` — fees and balance are decimal strings in the token's base units | ## Exit status diff --git a/ts/docs/commands/gasfree/trace.md b/ts/docs/commands/gasfree/trace.md index 3aa688581..688d78593 100644 --- a/ts/docs/commands/gasfree/trace.md +++ b/ts/docs/commands/gasfree/trace.md @@ -32,7 +32,9 @@ Status succeed TxID d2e... Token USDT Amount 25 USDT -Fee 0.5 USDT +Service fee 0.5 USDT +Activation fee 0 USDT +Total 25.5 USDT To TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub ``` @@ -41,7 +43,7 @@ wallet-cli gasfree trace 7f3e9a02-58c1-4d2e-b6a4-91d0c3f8e527 --network tron:nil ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"gasfree.trace","data":{"traceId":"7f3e9a02-58c1-4d2e-b6a4-91d0c3f8e527","state":"SUCCEED","txId":"d2e...","token":"USDT","amount":"25000000","serviceFee":"500000","activateFee":"0","to":"TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub"},"meta":{"durationMs":290,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"gasfree.trace","data":{"traceId":"7f3e9a02-58c1-4d2e-b6a4-91d0c3f8e527","state":"SUCCEED","txId":"d2e...","token":"USDT","tokenAddress":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t","decimals":6,"amount":"25000000","serviceFee":"500000","activateFee":"0","totalDeducted":"25500000","from":"TNER12mMVWruqopsW9FQtKxCGfZcEtb3ER","owner":"TMVQGm1qAQYVdetCeGRRkTWYYrLXuHK2HC","to":"TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub","nonce":"8"},"meta":{"durationMs":290,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` ## Output @@ -52,9 +54,15 @@ wallet-cli gasfree trace 7f3e9a02-58c1-4d2e-b6a4-91d0c3f8e527 --network tron:nil | `state` | string | Raw state enum: `WAITING` / `INPROGRESS` / `CONFIRMING` / `SUCCEED` / `FAILED` | | `txId` | string | On-chain transaction id (once submitted) | | `token` | string | Token symbol | +| `tokenAddress` | string | TRC20 contract address | +| `decimals` | number | Token decimals used to render amounts | | `amount` | string | Amount, in token base units | | `serviceFee` / `activateFee` | string | Fees charged, in token base units | +| `totalDeducted` | string | Amount plus the settled service and activation fees, in token base units | +| `from` / `owner` | string | GasFree holding address / owning account address | | `to` | string | Recipient address | +| `nonce` | string | Authorization nonce | +| `failureReason` | string | Provider explanation, only when supplied for a failed transfer | ## Exit status diff --git a/ts/docs/commands/gasfree/transfer.md b/ts/docs/commands/gasfree/transfer.md index cf5da6e07..66efeec91 100644 --- a/ts/docs/commands/gasfree/transfer.md +++ b/ts/docs/commands/gasfree/transfer.md @@ -43,16 +43,18 @@ echo "$PW" | wallet-cli gasfree transfer --to TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub ```console ⏳ Submitted to GasFree — send 25 USDT Trace ID 7f3e9a02-58c1-4d2e-b6a4-91d0c3f8e527 - From TNER12mMVWruqopsW9FQtKxCGfZcEtb3ER (GasFree address) + From TNER12mMVWruqopsW9FQtKxCGfZcEtb3ER To TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub - Fee 0.5 USDT - Total 25.5 USDT - Status accepted + Service fee 0.5 USDT + Activation fee 0 USDT + Authorized max fee 1.5 USDT + Total 25.5 USDT + Status waiting ! Track it: wallet-cli gasfree trace 7f3e9a02-58c1-4d2e-b6a4-91d0c3f8e527 ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"gasfree.transfer","data":{"kind":"gasfree-transfer","stage":"submitted","traceId":"7f3e9a02-58c1-4d2e-b6a4-91d0c3f8e527","token":"USDT","tokenAddress":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf","decimals":6,"amount":"25000000","serviceFee":"500000","activateFee":"0","authorizedMaxFee":"500000","totalDeducted":"25500000","owner":"TMVQGm1qAQYVdetCeGRRkTWYYrLXuHK2HC","from":"TNER12mMVWruqopsW9FQtKxCGfZcEtb3ER","to":"TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub","serviceProvider":"TKtWbdzEq5ss9vTS9kwRhBp5mXmBfBns3E","nonce":"8","deadline":"1700000060"},"meta":{"durationMs":650,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"gasfree.transfer","data":{"kind":"gasfree-transfer","stage":"submitted","traceId":"7f3e9a02-58c1-4d2e-b6a4-91d0c3f8e527","state":"WAITING","token":"USDT","tokenAddress":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf","decimals":6,"amount":"25000000","serviceFee":"500000","activateFee":"0","authorizedMaxFee":"1500000","totalDeducted":"25500000","owner":"TMVQGm1qAQYVdetCeGRRkTWYYrLXuHK2HC","from":"TNER12mMVWruqopsW9FQtKxCGfZcEtb3ER","to":"TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub","serviceProvider":"TKtWbdzEq5ss9vTS9kwRhBp5mXmBfBns3E","nonce":"8","deadline":"1700000060"},"meta":{"durationMs":650,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` Add `--wait` to poll to a terminal state, with the on-chain txid and actual deduction: @@ -65,11 +67,13 @@ echo "$PW" | wallet-cli gasfree transfer --to TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub ✅ Sent 25 USDT via GasFree Trace ID a41b6c88-0d2f-4e73-9a05-3c7d81f2b964 TxID d2e... - From TNER12mMVWruqopsW9FQtKxCGfZcEtb3ER (GasFree address) + From TNER12mMVWruqopsW9FQtKxCGfZcEtb3ER To TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub - Fee 0.5 USDT - Total 25.5 USDT - Status succeed + Service fee 0.5 USDT + Activation fee 0 USDT + Authorized max fee 1.5 USDT + Total 25.5 USDT + Status succeed ``` On a first transfer the GasFree address isn't activated yet, so the fee itemises the service fee and the one-time activation fee, and `Total` includes activation: @@ -80,10 +84,13 @@ wallet-cli gasfree transfer --to TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub --amount 25 ```console ⏳ Dry run — GasFree transfer 25 USDT (not submitted) - From TNER12mMVWruqopsW9FQtKxCGfZcEtb3ER (GasFree address, not activated) + From TNER12mMVWruqopsW9FQtKxCGfZcEtb3ER To TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub - Fee 1.5 USDT (0.5 service + 1.0 activation) - Total 26.5 USDT + Service fee 0.5 USDT + Activation fee 1 USDT + Authorized max fee 1.5 USDT + Total 26.5 USDT + Status not submitted ``` ```json @@ -96,12 +103,12 @@ wallet-cli gasfree transfer --to TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub --amount 25 | Mode | Fields | |---|---| -| default (submit) | `kind: "gasfree-transfer"`, `stage: "submitted"`, `traceId`, `token`, `tokenAddress`, `decimals`, `amount`, `serviceFee`, `activateFee`, `authorizedMaxFee`, `totalDeducted`, `owner`, `from`, `to`, `nonce`, `deadline`, `serviceProvider`, plus `toContact` when `--to` was a contact name | -| `--wait` (confirmed) | the above, but `stage: "confirmed"`, plus `confirmed`, `state` (`SUCCEED` / `FAILED`), `failed`, and `txId` | -| `--wait` (failed) | the same fields, but `stage: "failed"`, `failed: true`, `state: "FAILED"`, and `failureReason` carrying the provider's explanation | +| default (submit) | `kind: "gasfree-transfer"`, `stage: "submitted"`, `traceId`, provider `state`, `token`, `tokenAddress`, `decimals`, `amount`, `serviceFee`, `activateFee`, `authorizedMaxFee`, `totalDeducted`, `owner`, `from`, `to`, `nonce`, `deadline`, `serviceProvider`, plus `toContact` when `--to` was a contact name | +| `--wait` (confirmed) | the above, but `stage: "confirmed"`, `state: "SUCCEED"`, and `txId` when supplied by the provider | +| `--wait` (failed) | the same fields, but `stage: "failed"`, `state: "FAILED"`, and optional `failureReason` / `txId` from the provider | | `--dry-run` | the default fields except `traceId`, with `stage: "dry-run"`; no signature or submission | -A provider-side failure still leaves the envelope at `success: true` and exit `0` — the command completed; the transfer did not. Branch on `data.stage` / `data.state`, not on the exit code. See [script safety](../../machine-interface.md#script-safety-never-mistake-submitted-for-confirmed). +A provider-side failure still leaves the envelope at `success: true` and exit `0` — the command completed; the transfer did not. There are no `confirmed` or `failed` booleans in this view; branch on `data.stage` / `data.state`, not on the exit code. See [script safety](../../machine-interface.md#script-safety-never-mistake-submitted-for-confirmed). ## Exit status diff --git a/ts/docs/commands/import/keystore.md b/ts/docs/commands/import/keystore.md index 96a8e7f9c..9ae10a2f3 100644 --- a/ts/docs/commands/import/keystore.md +++ b/ts/docs/commands/import/keystore.md @@ -44,6 +44,7 @@ wallet-cli import keystore ./tronlink-export.json --label imported Account ID wlt_7h2k9m1a Type private key TRON address TZx9kP2m...7bWq + EVM address 0xe4aAd11792F7E74f1B5cbce65f9a1E207c952961 Active yes ⚠️ The keystore password was read from hidden input and was not printed. @@ -56,7 +57,7 @@ wallet-cli import keystore ./tronlink-export.json --label imported -o json ```console ? Master password (hidden): ? Keystore file password (hidden): -{"schema":"wallet-cli.result.v1","success":true,"command":"import.keystore","data":{"status":"created","accountId":"wlt_7h2k9m1a","label":"imported","type":"privateKey","index":null,"active":true,"addresses":{"tron":"TZx9kP2m...7bWq"}},"meta":{"durationMs":44,"warnings":[]}} +{"schema":"wallet-cli.result.v1","success":true,"command":"import.keystore","data":{"status":"created","accountId":"wlt_7h2k9m1a","label":"imported","type":"privateKey","index":null,"active":true,"addresses":{"tron":"TZx9kP2m...7bWq","evm":"0xe4aAd11792F7E74f1B5cbce65f9a1E207c952961"},"derivationPath":null},"meta":{"durationMs":44,"warnings":[]}} ``` ## Output @@ -71,7 +72,8 @@ wallet-cli import keystore ./tronlink-export.json --label imported -o json | `type` | string | `"privateKey"` (standalone, no seed) | | `index` | number \| null | Non-HD account, always `null` | | `active` | boolean | Became the active account | -| `addresses.tron` | string | Base58 TRON address | +| `addresses` | object | Both encodings of the imported key: `tron` (base58) and `evm` (EIP-55) | +| `derivationPath` | null | A Web3 keystore contains one raw key and has no derivation path | ## Exit status diff --git a/ts/docs/commands/import/ledger.md b/ts/docs/commands/import/ledger.md index 5854bbf27..7c09a9198 100644 --- a/ts/docs/commands/import/ledger.md +++ b/ts/docs/commands/import/ledger.md @@ -14,7 +14,7 @@ wallet-cli import ledger --app (--index | --path | - | Option | Description | |---|---| | `--app ` | **Required.** Ledger app to open on the device; this is what selects the chain family and the derivation scheme | -| `--index ` | Account index under the app's default path; omit with no `--path`/`--address` to use index 0. Mutually exclusive with `--path` / `--address` | +| `--index ` | Account index under wallet-cli's family path template. Mutually exclusive with `--path` / `--address` | | `--path ` | Explicit derivation path, e.g. `m/44'/195'/0'/0/0` (TRON) or `m/44'/60'/0'/0/0` (Ethereum) | | `--address ` | Known address to locate by bounded scan | | `--scan-limit ` | Indexes to scan with `--address` (default 20) | @@ -26,6 +26,10 @@ Plus [global options](../index.md). Creates a watch-only entry; no secret is stored. Requires the device unlocked with the selected app open. +When all three locators are omitted, an attached TTY opens a paged account selector (five derived addresses at a time). In non-interactive use there is no selector and the command falls back to index 0; pass `--index`, `--path`, or `--address` explicitly in scripts. + +For Ethereum, `--index ` uses wallet-cli's MetaMask-style path `m/44'/60'/0'/0/`. Ledger Live commonly uses `m/44'/60'/'/0/0`; use an explicit `--path` when importing an account created under that scheme. + `--app` is what makes a Ledger account **single-family**: the TRON app registers a `tron` account and the Ethereum app an `evm` one, and the resulting account has only that one address. Import the same device twice, once per app, to hold both. See [Ledger guide](../../guide/ledger.md). ## Examples diff --git a/ts/docs/commands/import/mnemonic.md b/ts/docs/commands/import/mnemonic.md index 60e4b57dc..029c20479 100644 --- a/ts/docs/commands/import/mnemonic.md +++ b/ts/docs/commands/import/mnemonic.md @@ -45,6 +45,7 @@ wallet-cli import mnemonic --label restored Account ID wlt_d66fvems.0 Type HD TRON address TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH + EVM address 0x7B28FE10FBccE88c3967ff0Fd64f1ffB46b46C9C Active yes ⚠️ Recovery phrase was read from hidden input and was not printed. @@ -58,7 +59,7 @@ wallet-cli import mnemonic --label restored -o json ? Set master password (hidden): ? Confirm master password: ? Paste recovery phrase (hidden): -{"schema":"wallet-cli.result.v1","success":true,"command":"import.mnemonic","data":{"status":"created","accountId":"wlt_d66fvems.0","label":"restored","type":"seed","index":0,"active":true,"addresses":{"tron":"TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH"},"seedId":"wlt_d66fvems"},"meta":{"durationMs":38,"warnings":[]}} +{"schema":"wallet-cli.result.v1","success":true,"command":"import.mnemonic","data":{"status":"created","accountId":"wlt_d66fvems.0","label":"restored","type":"seed","index":0,"active":true,"addresses":{"tron":"TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH","evm":"0x7B28FE10FBccE88c3967ff0Fd64f1ffB46b46C9C"},"seedId":"wlt_d66fvems","derivationPath":{"tron":"m/44'/195'/0'/0/0","evm":"m/44'/60'/0'/0/0"}},"meta":{"durationMs":38,"warnings":[]}} ``` ## Output @@ -67,14 +68,15 @@ wallet-cli import mnemonic --label restored -o json | Field | Type | Meaning | |---|---|---| -| `status` | string | `"created"` | +| `status` | string | `"created"`, or `"existing"` when the mnemonic's account #0 was already present (the existing account is selected) | | `accountId` | string | Stable id `.` | | `label` | string | Account label | | `type` | string | `"seed"` (HD-derived) | | `index` | number | HD derivation index (0 for the first account) | | `active` | boolean | Became the active account | -| `addresses.tron` | string | Base58 TRON address | +| `addresses` | object | Both derived addresses: `tron` (base58) and `evm` (EIP-55) | | `seedId` | string | Owning seed wallet id | +| `derivationPath` | object | Per-family BIP44 path for account index 0 | ## Exit status diff --git a/ts/docs/commands/import/private-key.md b/ts/docs/commands/import/private-key.md index 3337f5b97..6d6450acc 100644 --- a/ts/docs/commands/import/private-key.md +++ b/ts/docs/commands/import/private-key.md @@ -38,6 +38,7 @@ wallet-cli import private-key --label hot Account ID wlt_2qnr6j1f Type private key TRON address TMVQGm1qAQYVdetCeGRRkTWYYrLXuHK2HC + EVM address 0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC Active yes ⚠️ Private key was read from hidden input and was not printed. @@ -51,7 +52,7 @@ wallet-cli import private-key --label hot -o json ? Set master password (hidden): ? Confirm master password: ? Paste private key (hidden): -{"schema":"wallet-cli.result.v1","success":true,"command":"import.private-key","data":{"status":"created","accountId":"wlt_2qnr6j1f","label":"hot","type":"privateKey","index":null,"active":true,"addresses":{"tron":"TMVQGm1qAQYVdetCeGRRkTWYYrLXuHK2HC"}},"meta":{"durationMs":38,"warnings":[]}} +{"schema":"wallet-cli.result.v1","success":true,"command":"import.private-key","data":{"status":"created","accountId":"wlt_2qnr6j1f","label":"hot","type":"privateKey","index":null,"active":true,"addresses":{"tron":"TMVQGm1qAQYVdetCeGRRkTWYYrLXuHK2HC","evm":"0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC"},"derivationPath":null},"meta":{"durationMs":38,"warnings":[]}} ``` ## Output @@ -60,13 +61,14 @@ wallet-cli import private-key --label hot -o json | Field | Type | Meaning | |---|---|---| -| `status` | string | `"created"` | +| `status` | string | `"created"`, or `"existing"` when the same key was already present (the existing account is selected) | | `accountId` | string | Stable account id | | `label` | string | Account label | | `type` | string | `"privateKey"` (standalone, no seed) | | `index` | number \| null | Non-HD account, always `null` | | `active` | boolean | Became the active account | -| `addresses.tron` | string | Base58 TRON address | +| `addresses` | object | Both encodings of the imported key: `tron` (base58) and `evm` (EIP-55) | +| `derivationPath` | null | A raw private key has no derivation path | ## Exit status diff --git a/ts/docs/commands/import/watch.md b/ts/docs/commands/import/watch.md index 4f86ef56c..72b08a996 100644 --- a/ts/docs/commands/import/watch.md +++ b/ts/docs/commands/import/watch.md @@ -46,7 +46,7 @@ wallet-cli import watch --address TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ --label col ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"import.watch","data":{"status":"created","accountId":"wlt_jsyq8fxe","label":"cold","type":"watch","index":null,"active":true,"addresses":{"tron":"TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ"},"family":"tron"},"meta":{"durationMs":36,"warnings":[]}} +{"schema":"wallet-cli.result.v1","success":true,"command":"import.watch","data":{"status":"created","accountId":"wlt_jsyq8fxe","label":"cold","type":"watch","index":null,"active":false,"addresses":{"tron":"TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ"},"family":"tron"},"meta":{"durationMs":36,"warnings":[]}} ``` ## Output @@ -55,12 +55,12 @@ wallet-cli import watch --address TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ --label col | Field | Type | Meaning | |---|---|---| -| `status` | string | `"created"` | +| `status` | string | `"created"`, or `"existing"` if the same watch address was already registered | | `accountId` | string | Stable account id | | `label` | string | Account label | | `type` | string | `"watch"` (read-only, cannot sign) | | `index` | number \| null | Non-HD account, always `null` | -| `active` | boolean | Became the active account | +| `active` | boolean | Whether this account is already the current active account. Registering a watch-only account does not select it; use [`use`](../use.md) explicitly | | `addresses` | object | The single address, keyed by its family — `{"tron":"T…"}` or `{"evm":"0x…"}` | | `family` | string | Chain family detected from the address — `tron` or `evm` | diff --git a/ts/docs/commands/index.md b/ts/docs/commands/index.md index 4aafee713..37d805a23 100644 --- a/ts/docs/commands/index.md +++ b/ts/docs/commands/index.md @@ -185,7 +185,7 @@ Individual flags are family-scoped the same way. `--help` tags them `(tron only) -h, --help / -V, --version ``` -Broadcast (✍️) commands additionally take `--wait` / `--wait-timeout ` (cap default: config `waitTimeoutMs`, built-in 60000). Early-exit modes are command-specific: transaction-building commands expose `--dry-run` / `--sign-only` / `--build-only`, while submit-only commands such as `tx broadcast` do not rebuild or sign and therefore omit `--sign-only` / `--build-only`. +Commands whose schema enables post-broadcast polling take `--wait` / `--wait-timeout ` (cap default: config `waitTimeoutMs`, built-in 60000). Early-exit modes are also command-specific: transaction-building commands may expose `--dry-run` / `--sign-only` / `--build-only`, while submit-only commands such as `tx broadcast` do not rebuild or sign and therefore omit `--sign-only` / `--build-only`. Fee and multi-sig flags are **family-scoped**, so they are not global: diff --git a/ts/docs/commands/permission/show.md b/ts/docs/commands/permission/show.md index cb155f06a..fed2087dc 100644 --- a/ts/docs/commands/permission/show.md +++ b/ts/docs/commands/permission/show.md @@ -27,33 +27,7 @@ No command-specific options; the [global options](../index.md#global-options-eve ## Examples -**A never-modified account** shows the chain-default structure — the active group covers every ordinary operation type: - -```bash -wallet-cli permission show --account solo --network tron:nile -``` - -```console -Account solo (TWfd2K9nP4rH7gL3jM6cV1bN8yS5aQ0eXt) - -Permission Name owner (id 0) -Threshold 1 -Authorized To Address Weight - TWfd2K9nP4rH7gL3jM6cV1bN8yS5aQ0eXt 1 (this wallet: solo) - -Permission Name active (id 2, active) -Operation(s) Activate Account · Transfer TRX · Transfer TRC10 - Vote · Issue TRC10 · Update Account Name - TRX Stake (1.0) · TRX Unstake (1.0) - Claim Voting Rewards · Create Smart Contract - Trigger Smart Contract · TRX Stake (2.0) - TRX Unstake (2.0) · Withdraw Unstaked TRX - Delegate Resources · Reclaim Resources - Cancel Unstake · … (40 total) -Threshold 1 -Authorized To Address Weight - TWfd2K9nP4rH7gL3jM6cV1bN8yS5aQ0eXt 1 (this wallet: solo) -``` +**A never-modified account** shows the chain-default owner and active groups. The active group's complete operation set is line-wrapped to fit the terminal; labels are never replaced with an ellipsis. Unknown bitmap bits are printed as `Unknown contract type `. **A multi-sig account** — here the owner group is a 2-of-3 and a scoped `finance` active group handles day-to-day transfers. This wallet holds only one of the keys (`main`); the other two are held by external co-signers, so they carry no annotation: @@ -72,7 +46,7 @@ Authorized To Address Weight TXe4Kd8nP2rF9gH5jL3mV6cW1bN7yS0aQz 1 Permission Name finance (id 2, active) -Operation(s) Transfer TRX · Transfer TRC10 · Trigger Smart Contract +Operation(s) Transfer TRX · Transfer TRC10 · Trigger Smart Contract (3 total) Threshold 2 Authorized To Address Weight TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw 1 (this wallet: main) @@ -85,7 +59,7 @@ wallet-cli permission show --account main --network tron:nile -o json ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"permission.show","data":{"address":"TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw","owner":{"id":0,"threshold":2,"keys":[{"address":"TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw","weight":1,"local":"main"},{"address":"TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub","weight":1,"local":null},{"address":"TXe4Kd8nP2rF9gH5jL3mV6cW1bN7yS0aQz","weight":1,"local":null}]},"witness":null,"actives":[{"id":2,"name":"finance","threshold":2,"operations":["TransferContract","TransferAssetContract","TriggerSmartContract"],"operationsHex":"0600008000000000000000000000000000000000000000000000000000000000","keys":[{"address":"TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw","weight":1,"local":"main"},{"address":"TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub","weight":1,"local":null},{"address":"TXe4Kd8nP2rF9gH5jL3mV6cW1bN7yS0aQz","weight":1,"local":null}]}]},"meta":{"durationMs":21,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"permission.show","data":{"address":"TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw","owner":{"id":0,"name":"owner","threshold":2,"keys":[{"address":"TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw","weight":1,"local":"main"},{"address":"TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub","weight":1,"local":null},{"address":"TXe4Kd8nP2rF9gH5jL3mV6cW1bN7yS0aQz","weight":1,"local":null}]},"witness":null,"actives":[{"id":2,"name":"finance","threshold":2,"operations":["TransferContract","TransferAssetContract","TriggerSmartContract"],"operationLabels":["Transfer TRX","Transfer TRC10","Trigger Smart Contract"],"operationsHex":"0600008000000000000000000000000000000000000000000000000000000000","unknownOperationIds":[],"keys":[{"address":"TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw","weight":1,"local":"main"},{"address":"TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub","weight":1,"local":null},{"address":"TXe4Kd8nP2rF9gH5jL3mV6cW1bN7yS0aQz","weight":1,"local":null}]}]},"meta":{"durationMs":21,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` ## Output @@ -93,11 +67,13 @@ wallet-cli permission show --account main --network tron:nile -o json | Field | Type | Meaning | |---|---|---| | `address` | string | Queried account | -| `owner` | object | Owner group `{id, threshold, keys[]}` | -| `witness` | object \| null | Witness group (SRs only), else `null` | -| `actives[]` | array | Active groups, each `{id, name, threshold, operations[], operationsHex, keys[]}` | +| `owner` | object | Owner group `{id, name, threshold, keys[]}` | +| `witness` | object \| null | Witness group with `{id, name, threshold, keys[]}` for SRs, else `null` | +| `actives[]` | array | Active groups, each `{id, name, threshold, operations[], operationLabels[], operationsHex, unknownOperationIds[], keys[]}` | | `…operations[]` | string[] | Contract-type names the active group may perform | +| `…operationLabels[]` | string[] | Human-readable labels corresponding to known operation ids | | `…operationsHex` | string | Raw 32-byte operations bitmap, hex | +| `…unknownOperationIds[]` | number[] | Set bits this build cannot map to a known contract type; empty when all operations are known | | `…keys[]` | array | Group keys: `{address, weight, local}` — `local` is the wallet label if held locally, else `null` | ## Exit status diff --git a/ts/docs/commands/permission/update.md b/ts/docs/commands/permission/update.md index ecfc09498..c534fdfa6 100644 --- a/ts/docs/commands/permission/update.md +++ b/ts/docs/commands/permission/update.md @@ -29,10 +29,11 @@ wallet-cli permission show -o json --network tron:nile | jq '.data' > perms.json Changing only `keys`, `threshold` or `name` needs no such deletion. -⚠️ **The chain applies no safety checks.** Even if the new structure contains no key you can sign with, the transaction still succeeds and the account is permanently locked, with no on-chain recovery. This CLI surfaces two **local** warnings but does **not** block the submission (in JSON they go to `meta.warnings`, and `success` stays `true`): +⚠️ **The chain applies no safety checks.** Even if the new structure contains no key you can sign with, the transaction still succeeds and the account is permanently locked, with no on-chain recovery. This CLI can surface four **local warning codes** but does **not** block the submission (in JSON they go to `meta.warnings`, and `success` stays `true`): - **Lockout risk** — when the combined weight of your locally-signable owner keys (software / Ledger) is below the new owner threshold, a `!` line spells out that you can no longer meet the owner threshold on your own (`owner_lockout` if you hold no weight, `owner_lockout_partial` if you now need co-signers). Multi-party custody legitimately means "I alone can't reach the threshold", so this is a notice, not a block. - **Dangerous operations** — when an active group includes `Update Account Permissions` (that group could then change the permissions themselves, effectively owner-level), a `!` line flags it (`active_can_update_permission`). +- **Unknown operations** — when an active bitmap grants contract-type ids this build cannot name, the ids are preserved and reported as `active_unknown_operations` rather than silently dropped. ## Options @@ -65,20 +66,22 @@ wallet-cli permission show --network tron:nile -o json | jq '.data' > perms.json $EDITOR perms.json ``` -Submit with `--wait`. The receipt is the transaction record plus the resulting on-chain structure (read back after confirmation, same cards as `permission show`), with any `!` warnings appended: +Submit with `--wait`. Safety warnings are written to stderr as `warning: ...` before the stdout receipt. After confirmation, the receipt includes the resulting on-chain structure when the follow-up read succeeds, using the same cards as `permission show`: ```bash echo "$PW" | wallet-cli permission update --file perms.json --network tron:nile --wait --password-stdin ``` ```console +warning: local keys hold 1 of 2 owner weight; co-signers are required for owner-level operations ✅ Permissions updated - Account main (TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw) TxID b3c... Block #84,335,102 Fee 100.268 TRX Status success +Account TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw + Permission Name owner (id 0) Threshold 2 Authorized To Address Weight @@ -87,25 +90,22 @@ Authorized To Address Weight TXe4Kd8nP2rF9gH5jL3mV6cW1bN7yS0aQz 1 Permission Name finance (id 2, active) -Operation(s) Transfer TRX · Transfer TRC10 · Trigger Smart Contract +Operation(s) Transfer TRX · Transfer TRC10 · Trigger Smart Contract (3 total) Threshold 2 Authorized To Address Weight TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw 1 (this wallet: main) TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub 1 TXe4Kd8nP2rF9gH5jL3mV6cW1bN7yS0aQz 1 - -! Your local keys now hold 1 of 2 owner weight — co-signers are required - for owner-level operations from now on. ``` -The JSON receipt's `data.permissions` is **structurally identical** to `permission show`'s `data`, so you can diff it against the pre-change export; the lockout warning is in `meta.warnings` with `success` still `true`: +When present, the JSON receipt's `data.permissions` is **structurally identical** to `permission show`'s `data`, so you can diff it against the pre-change export. If the confirmed post-check cannot be read, the field is omitted and `meta.warnings` contains `permission_postcheck_unavailable`; the confirmed transaction still has `success: true`. The lockout warning is also in `meta.warnings`: ```bash echo "$PW" | wallet-cli permission update --file perms.json --network tron:nile --wait --password-stdin -o json ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"permission.update","data":{"kind":"permission-update","stage":"confirmed","txId":"b3c...","confirmed":true,"blockNumber":84335102,"feeSun":100268000,"failed":false,"permissions":{"address":"TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw","owner":{"id":0,"threshold":2,"keys":[{"address":"TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw","weight":1,"local":"main"},{"address":"TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub","weight":1,"local":null},{"address":"TXe4Kd8nP2rF9gH5jL3mV6cW1bN7yS0aQz","weight":1,"local":null}]},"witness":null,"actives":[{"id":2,"name":"finance","threshold":2,"operations":["TransferContract","TransferAssetContract","TriggerSmartContract"],"operationsHex":"0600008000000000000000000000000000000000000000000000000000000000","keys":[{"address":"TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw","weight":1,"local":"main"},{"address":"TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub","weight":1,"local":null},{"address":"TXe4Kd8nP2rF9gH5jL3mV6cW1bN7yS0aQz","weight":1,"local":null}]}]}},"meta":{"durationMs":6810,"warnings":[{"code":"owner_lockout_partial","message":"local keys hold 1 of 2 owner weight; co-signers are required for owner-level operations"}]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"permission.update","data":{"kind":"permission-update","stage":"confirmed","txId":"b3c...","confirmed":true,"blockNumber":84335102,"feeSun":100268000,"failed":false,"permissions":{"address":"TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw","owner":{"id":0,"name":"owner","threshold":2,"keys":[{"address":"TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw","weight":1,"local":"main"},{"address":"TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub","weight":1,"local":null},{"address":"TXe4Kd8nP2rF9gH5jL3mV6cW1bN7yS0aQz","weight":1,"local":null}]},"witness":null,"actives":[{"id":2,"name":"finance","threshold":2,"operations":["TransferContract","TransferAssetContract","TriggerSmartContract"],"operationLabels":["Transfer TRX","Transfer TRC10","Trigger Smart Contract"],"operationsHex":"0600008000000000000000000000000000000000000000000000000000000000","unknownOperationIds":[],"keys":[{"address":"TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw","weight":1,"local":"main"},{"address":"TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub","weight":1,"local":null},{"address":"TXe4Kd8nP2rF9gH5jL3mV6cW1bN7yS0aQz","weight":1,"local":null}]}]}},"meta":{"durationMs":6810,"warnings":[{"code":"owner_lockout_partial","message":"local keys hold 1 of 2 owner weight; co-signers are required for owner-level operations"}]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` ## Output @@ -115,12 +115,14 @@ echo "$PW" | wallet-cli permission update --file perms.json --network tron:nile | Mode | Fields | |---|---| | default (submit) | `kind: "permission-update"`, `stage: "submitted"`, `txId` | -| `--wait` (confirmed) | the above, but `stage: "confirmed"`, plus `confirmed`, `blockNumber`, `feeSun`, `failed`, and `permissions` (same shape as `permission show` data, read back from chain) | -| `--dry-run` | `kind`, `mode: "dry-run"`, `fee` (the 100 TRX change fee), and `permissions` (the resulting structure); no `txId` | -| `--sign-only` | `kind`, `mode: "sign-only"`, `hex` (signed tx hex — feed `tx broadcast --hex`), `fee` | -| `--build-only` | `kind`, `mode: "build-only"`, `hex` (unsigned tx hex — feed `tx multisig --create`), `fee` | +| `--wait` (confirmed) | the above, but `stage: "confirmed"`, plus `confirmed`, `blockNumber`, `feeSun`, `failed`, and optional `permissions` (same shape as `permission show` data when the post-check read succeeds) | +| `--dry-run` | `kind`, `mode: "dry-run"`, `tx`, `fee` (the account-permission fee), and `permissions` (the resulting structure); no `txId` | +| `--sign-only` | `kind`, `mode: "sign-only"`, `signed`, `hex` (signed tx hex — feed `tx broadcast --hex`), `fee`, `address`, `txId`, and `permissions` | +| `--build-only` | `kind`, `mode: "build-only"`, `tx`, `hex` (unsigned tx hex — feed `tx multisig --create`), `fee`, and `permissions` | + +Local warnings (`owner_lockout`, `owner_lockout_partial`, `active_can_update_permission`, `active_unknown_operations`) are emitted before the transaction is built, appear in `meta.warnings` as `{code, message}` objects, and do not affect `success` — see [reading `meta.warnings`](../../machine-interface.md#reading-metawarnings). -Local warnings (`owner_lockout`, `owner_lockout_partial`, `active_can_update_permission`) are emitted before the transaction is built, appear in `meta.warnings` as `{code, message}` objects, and do not affect `success` — see [reading `meta.warnings`](../../machine-interface.md#reading-metawarnings). +Post-confirmation warnings use `permission_postcheck_unavailable` when the read-back fails and `permission_postcheck_mismatch` when the returned structure differs. In either case the transaction is already confirmed, so the command remains successful and callers must treat `permissions` as optional. ## Exit status diff --git a/ts/docs/commands/proposal/approve.md b/ts/docs/commands/proposal/approve.md index 3bf38c916..59e95973a 100644 --- a/ts/docs/commands/proposal/approve.md +++ b/ts/docs/commands/proposal/approve.md @@ -75,7 +75,7 @@ echo "$PW" | wallet-cli proposal approve 47 --network tron:nile --wait --passwor ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"proposal.approve","data":{"kind":"proposal-approve","stage":"confirmed","txId":"b1e...","confirmed":true,"blockNumber":57880240,"failed":false,"proposalId":47,"addApproval":true,"feeSun":0,"resource":{"netUsage":267,"netFeeSun":0,"energyUsage":0,"energyFeeSun":0}},"meta":{"durationMs":6410,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"proposal.approve","data":{"kind":"proposal-approve","stage":"confirmed","txId":"b1e...","confirmed":true,"blockNumber":57880240,"failed":false,"proposalId":47,"voterAddress":"TSRmq8kP...","addApproval":true,"approvals":13,"approvalThreshold":18,"feeSun":0,"energyUsed":0,"netUsed":267,"energyFeeSun":0,"netFeeSun":0,"resource":{"netUsage":267,"netFeeSun":0,"energyUsage":0,"energyFeeSun":0}},"meta":{"durationMs":6410,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` ## Output @@ -84,8 +84,8 @@ echo "$PW" | wallet-cli proposal approve 47 --network tron:nile --wait --passwor | Stage | Fields | |---|---| -| default (submit) | `kind: "proposal-approve"`, `stage: "submitted"`, `txId`, `proposalId`, `addApproval` (`false` with `--cancel`) | -| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, `feeSun`, `resource`, `failed` | +| default (submit) | `kind: "proposal-approve"`, `stage: "submitted"`, `txId`, `proposalId`, `voterAddress`, `addApproval` (`false` with `--cancel`), `approvals`, and `approvalThreshold` | +| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, flat settlement fields when returned (`feeSun`, `energyUsed`, `netUsed`, `energyFeeSun`, `netFeeSun`), their governance compatibility view `resource` (`netUsage`, `netFeeSun`, `energyUsage`, `energyFeeSun`), and `failed` | ## Exit status diff --git a/ts/docs/commands/proposal/create.md b/ts/docs/commands/proposal/create.md index 21c07ddb8..08f8a46b4 100644 --- a/ts/docs/commands/proposal/create.md +++ b/ts/docs/commands/proposal/create.md @@ -81,7 +81,7 @@ echo "$PW" | wallet-cli proposal create --set getTransactionFee=15 --network tro ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"proposal.create","data":{"kind":"proposal-create","stage":"confirmed","txId":"9c4...","confirmed":true,"blockNumber":57880102,"feeSun":0,"resource":{"netUsage":268,"netFeeSun":0,"energyUsage":0,"energyFeeSun":0},"failed":false,"proposalId":48,"changes":[{"id":3,"name":"getTransactionFee","currentValue":10,"proposedValue":15,"unit":"sun/byte"}]},"meta":{"durationMs":6480,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"proposal.create","data":{"kind":"proposal-create","stage":"confirmed","txId":"9c4...","confirmed":true,"blockNumber":57880102,"feeSun":0,"energyUsed":0,"netUsed":268,"energyFeeSun":0,"netFeeSun":0,"failed":false,"proposerAddress":"TSRmq8kP...","proposalId":48,"changes":[{"id":3,"name":"getTransactionFee","currentValue":10,"proposedValue":15,"unit":"sun/byte"}],"resource":{"netUsage":268,"netFeeSun":0,"energyUsage":0,"energyFeeSun":0}},"meta":{"durationMs":6480,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` ## Output @@ -90,8 +90,8 @@ echo "$PW" | wallet-cli proposal create --set getTransactionFee=15 --network tro | Stage | Fields | |---|---| -| default (submit) | `kind: "proposal-create"`, `stage: "submitted"`, `txId`, `changes[]` | -| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, `feeSun`, `resource`, `failed`, and `proposalId` — the new proposal's id, known only once it is on chain | +| default (submit) | `kind: "proposal-create"`, `stage: "submitted"`, `txId`, `proposerAddress`, `changes[]` | +| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, flat settlement fields when returned (`feeSun`, `energyUsed`, `netUsed`, `energyFeeSun`, `netFeeSun`), their governance compatibility view `resource` (`netUsage`, `netFeeSun`, `energyUsage`, `energyFeeSun`), `failed`, and optional `proposalId` — the new proposal's id, known only once it is on chain | `proposalId` is **omitted** when the id cannot be established beyond doubt. The chain does not report it, so it is recognised by comparing the proposal list against a snapshot taken before diff --git a/ts/docs/commands/proposal/delete.md b/ts/docs/commands/proposal/delete.md index 4802c9302..36f35285e 100644 --- a/ts/docs/commands/proposal/delete.md +++ b/ts/docs/commands/proposal/delete.md @@ -58,7 +58,7 @@ echo "$PW" | wallet-cli proposal delete 48 --network tron:nile --wait --password ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"proposal.delete","data":{"kind":"proposal-delete","stage":"confirmed","txId":"c7d...","confirmed":true,"blockNumber":57880355,"failed":false,"proposalId":48,"feeSun":0,"resource":{"netUsage":265,"netFeeSun":0,"energyUsage":0,"energyFeeSun":0}},"meta":{"durationMs":6390,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"proposal.delete","data":{"kind":"proposal-delete","stage":"confirmed","txId":"c7d...","confirmed":true,"blockNumber":57880355,"failed":false,"proposalId":48,"proposerAddress":"TSRmq8kP...","feeSun":0,"energyUsed":0,"netUsed":265,"energyFeeSun":0,"netFeeSun":0,"resource":{"netUsage":265,"netFeeSun":0,"energyUsage":0,"energyFeeSun":0}},"meta":{"durationMs":6390,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` ## Output @@ -67,8 +67,8 @@ echo "$PW" | wallet-cli proposal delete 48 --network tron:nile --wait --password | Stage | Fields | |---|---| -| default (submit) | `kind: "proposal-delete"`, `stage: "submitted"`, `txId`, `proposalId` | -| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, `feeSun`, `resource`, `failed` | +| default (submit) | `kind: "proposal-delete"`, `stage: "submitted"`, `txId`, `proposalId`, `proposerAddress` | +| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, flat settlement fields when returned (`feeSun`, `energyUsed`, `netUsed`, `energyFeeSun`, `netFeeSun`), their governance compatibility view `resource` (`netUsage`, `netFeeSun`, `energyUsage`, `energyFeeSun`), and `failed` | ## Exit status diff --git a/ts/docs/commands/token/add.md b/ts/docs/commands/token/add.md index 3268f8ec3..8634cc83c 100644 --- a/ts/docs/commands/token/add.md +++ b/ts/docs/commands/token/add.md @@ -67,7 +67,7 @@ wallet-cli token add --contract 0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238 --net ## Exit status -`0` added · `1` execution failure (`token_metadata_unavailable` — metadata could not be fetched, nothing is stored) · `2` usage error (`token_already_listed` — already in the official layer; `invalid_value`; `invalid_option` — `--asset-id` on an EVM network). +`0` added · `1` execution failure (`token_metadata_unavailable` — metadata could not be fetched, nothing is stored; `encoding_error` / `io_error` — the local token book could not be decoded or written) · `2` usage error (`token_already_listed` — already in the official layer; `invalid_value`; `invalid_option` — `--asset-id` on an EVM network). ## See also diff --git a/ts/docs/commands/token/info.md b/ts/docs/commands/token/info.md index f8fcba0af..4eaa9281b 100644 --- a/ts/docs/commands/token/info.md +++ b/ts/docs/commands/token/info.md @@ -12,7 +12,7 @@ wallet-cli token info (--contract
| --asset-id ) [options] Fetches a token's metadata straight from the chain — a pure RPC read that never touches your accounts. Pass exactly one selector: `--contract` for a contract-based token (TRC20 on TRON, ERC20 on EVM), `--asset-id` for a TRC10 asset. -TRON additionally reports `totalSupply`; the EVM read returns `name`, `symbol` and `decimals` only. +Contract-token reads (TRC20/ERC20) return normalized metadata. The TRC10 `--asset-id` branch keeps the node record's snake_case keys, but decodes its text fields (`name`, `abbr`, `url`, `description`) to UTF-8 and serializes int64 quantities such as `total_supply` as decimal strings. Do not apply the contract-token field set to a TRC10 response. ## Options @@ -53,15 +53,42 @@ wallet-cli token info --contract 0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238 --ne {"schema":"wallet-cli.result.v1","success":true,"command":"token.info","data":{"contract":"0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238","symbol":"USDC","decimals":6,"name":"USDC"},"meta":{"durationMs":409,"warnings":[]},"chain":{"family":"evm","network":"evm:11155111","chainId":"11155111"}} ``` +A TRC10 lookup keeps the node's key names while decoding text and preserving quantities exactly: + +```bash +wallet-cli token info --asset-id 1002000 --network tron:nile -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"token.info","data":{"id":"1002000","owner_address":"418225f3aa48a2d30643a64410abb1e914dfa0bd2f","name":"MyToken","abbr":"MTK","description":"Demo TRC10","url":"https://mytoken.example","total_supply":"1000000000","trx_num":1,"num":100,"precision":6,"start_time":1785542400000,"end_time":1788134400000,"free_asset_net_limit":0,"public_free_asset_net_limit":0,"frozen_supply":[]},"meta":{"durationMs":210,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + ## Output +For `--contract` (TRC20/ERC20): + | Field | Type | Meaning | |---|---|---| -| `contract` | string | Token contract address (or `assetId` for TRC10) | +| `contract` | string | Token contract address | | `name` | string | Token name | | `symbol` | string | Token symbol | | `decimals` | number | Token decimals | -| `totalSupply` | string | Total supply, raw integer in base units; **TRON only** | +| `totalSupply` | string | Total supply when the TRON contract adapter returns it; not returned by the EVM service | + +For `--asset-id` (TRC10): + +| Field | Type | Meaning | +|---|---|---| +| `id` / `owner_address` | string | Asset id and the node's hex owner address | +| `name` / `abbr` / `description` / `url` | string | UTF-8 text decoded from the node response | +| `total_supply` | string | Exact int64 supply in minimal units | +| `trx_num` / `num` | number | On-chain ICO rate pair | +| `precision` | number? | Asset precision; absent means `0` | +| `start_time` / `end_time` | number | ICO window, epoch milliseconds | +| `free_asset_net_limit` / `public_free_asset_net_limit` | number? | Free-bandwidth limits when present | +| `frozen_supply` | array? | Frozen tranches; each `frozen_amount` is a decimal string and `frozen_days` is a number | + +The TRC10 shape does not contain normalized `contract`, `symbol`, or `decimals` keys. ## Exit status diff --git a/ts/docs/commands/token/remove.md b/ts/docs/commands/token/remove.md index 648ce60d9..cac6ec928 100644 --- a/ts/docs/commands/token/remove.md +++ b/ts/docs/commands/token/remove.md @@ -53,7 +53,7 @@ wallet-cli token remove --contract TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf --network ## Exit status -`0` removed · `1` execution failure (`encoding_error`, `insecure_permissions`, `io_error`) · `2` usage error (`token_is_official` — official-layer tokens can't be removed; `token_not_in_book` — not in the user layer; `invalid_value`; `invalid_option` — `--asset-id` on an EVM network). +`0` removed · `1` execution failure (`encoding_error` / `io_error` — the local token book could not be decoded or written) · `2` usage error (`token_is_official` — official-layer tokens can't be removed; `token_not_in_book` — not in the user layer; `invalid_value`; `invalid_option` — `--asset-id` on an EVM network). ## See also diff --git a/ts/docs/commands/tx/info.md b/ts/docs/commands/tx/info.md index 9bc2731c5..60bd5f7b0 100644 --- a/ts/docs/commands/tx/info.md +++ b/ts/docs/commands/tx/info.md @@ -41,16 +41,16 @@ Confirmations 2 Fee 2.1 TRX ``` -`-o json` returns the full detail (`transaction` is the raw tx, `info` is the receipt; elided as `{…}` here): +`-o json` returns the full detail (`transaction` is the raw tx, `info` is the receipt; shown as empty objects here): ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"tx.info","data":{"txid":"34d9da372cd7fa9d4e7384744c0925af9d682eef4c9410fb831e0b87b355171b","from":"TR66PwBkGtktmiRhGjP9C6o8ts2ndDo4sP","to":"TVMV1gstFzkDyBfrpNc1Sa72Az2dMgDCLY","amount":"1","symbol":"TRX","status":"success","blockNumber":70433563,"confirmations":5,"feeSun":2100000,"transaction":{…},"info":{…}},"meta":{"durationMs":1396,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"tx.info","data":{"txid":"34d9da372cd7fa9d4e7384744c0925af9d682eef4c9410fb831e0b87b355171b","from":"TR66PwBkGtktmiRhGjP9C6o8ts2ndDo4sP","to":"TVMV1gstFzkDyBfrpNc1Sa72Az2dMgDCLY","amount":"1","symbol":"TRX","status":"success","blockNumber":70433563,"confirmations":5,"feeSun":2100000,"transaction":{},"info":{}},"meta":{"durationMs":1396,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` On an EVM network the summary adds `type` and `nonce`, prices the fee in wei, and nests `receipt` instead of `info`: ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"tx.info","data":{"txid":"0x55b0068ef31bce39bbf5b06d456eaef307fd77f96d85ea291f48c1ae4b900d80","type":"contract-call","from":"0x88878d9250e68C574912f5618ad3b43f675B8888","nonce":342,"to":"0x3bFA4769FB09eefC5a80d6E87c3B9C650f7Ae48E","rawAmount":"0","amount":"0","symbol":"ETH","blockTime":1787817996,"status":"success","blockNumber":11576586,"gasUsed":"127165","feeWei":"635825000000000","effectiveGasPriceWei":"5000000000","confirmations":0,"transaction":{…},"receipt":{…}},"meta":{"durationMs":706,"warnings":[]},"chain":{"family":"evm","network":"evm:11155111","chainId":"11155111"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"tx.info","data":{"txid":"0x55b0068ef31bce39bbf5b06d456eaef307fd77f96d85ea291f48c1ae4b900d80","type":"contract-call","from":"0x88878d9250e68C574912f5618ad3b43f675B8888","nonce":342,"to":"0x3bFA4769FB09eefC5a80d6E87c3B9C650f7Ae48E","rawAmount":"0","amount":"0","symbol":"ETH","blockTime":1787817996,"status":"success","blockNumber":11576586,"gasUsed":"127165","feeWei":"635825000000000","effectiveGasPriceWei":"5000000000","confirmations":0,"transaction":{},"receipt":{}},"meta":{"durationMs":706,"warnings":[]},"chain":{"family":"evm","network":"evm:11155111","chainId":"11155111"}} ``` An unknown txid errors out (exit 1) — unlike `tx status`'s `not_found` (exit 0): diff --git a/ts/docs/commands/tx/multisig.md b/ts/docs/commands/tx/multisig.md index aa404e5ef..3467a402a 100644 --- a/ts/docs/commands/tx/multisig.md +++ b/ts/docs/commands/tx/multisig.md @@ -88,10 +88,10 @@ wallet-cli tx multisig --account cosigner --network tron:nile ```console Multi-sig transactions — TronLink service (1 total) -| TxID | Type | Amount | State | Progress | Expires | -| ------ | ------------ | --------- | ------------ | -------- | ---------------- | -| 9c1... | Transfer TRX | 1,000 TRX | awaiting you | 1 / 2 | 2026-07-14 15:32 | -! Co-sign it: wallet-cli tx multisig --sign 9c1... +| TxID | Type | Amount | State | Validation | Progress | Expires | +| ------ | ---------------- | --------- | ------------ | ---------- | -------- | ---------------- | +| 9c1... | TransferContract | 1,000 TRX | awaiting you | verified | 1 / 2 | 2026-07-14 15:32 | +! Co-sign one with: wallet-cli tx multisig --sign ``` ```bash @@ -123,7 +123,7 @@ Progress 2 / 2 — threshold reached The list mode as JSON: ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"tx.multisig","data":{"address":"TXe4Kd8nP2rF9gH5jL3mV6cW1bN7yS0aQz","total":1,"unreadable":0,"transactions":[{"txId":"9c1...","state":"pending","verified":true,"contractType":"TransferContract","operation":"Transfer TRX","rawAmount":"1000000000","originator":"TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw","owner":"TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw","permission":{"id":2,"name":"finance","threshold":2},"currentWeight":1,"missingWeight":1,"thresholdReached":false,"awaitingMySignature":true,"signedByCurrentAccount":false,"expiration":1784388720000}]},"meta":{"durationMs":420,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"tx.multisig","data":{"address":"TXe4Kd8nP2rF9gH5jL3mV6cW1bN7yS0aQz","total":1,"unreadable":0,"transactions":[{"verified":true,"txId":"9c1...","state":"pending","contractType":"TransferContract","originator":"TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw","owner":"TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw","permission":{"id":2,"name":"finance","threshold":2},"currentWeight":1,"missingWeight":1,"thresholdReached":false,"awaitingMySignature":true,"signedByCurrentAccount":false,"createdAt":1784385120000,"expiration":1784388720000,"expired":false,"signatures":1,"signatureProgress":[{"address":"TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw","weight":1,"signed":true,"signedAt":1784385130000},{"address":"TXe4Kd8nP2rF9gH5jL3mV6cW1bN7yS0aQz","weight":1,"signed":false,"signedAt":null}],"from":"TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw","to":"TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub","rawAmount":"1000000000"}]},"meta":{"durationMs":420,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` Optionally, a WebSocket nudge (count only — list them to see details): @@ -135,6 +135,10 @@ wallet-cli tx multisig --watch --account cosigner --network tron:nile ```console Watching TronLink multi-sig service for tron:nile … (Ctrl-C to stop) 🔔 You have 1 transaction(s) to sign — view them with: wallet-cli tx multisig + +✅ Stopped watching TronLink multi-sig service + Address TXe4Kd8nP2rF9gH5jL3mV6cW1bN7yS0aQz + Notifications 1 ``` ## Output @@ -152,13 +156,18 @@ Watching TronLink multi-sig service for tron:nile … (Ctrl-C to stop) | `transactions[].state` | string | `pending` \| `signed` \| `success` \| `failed` | | `transactions[].verified` | boolean | Whether the record reconciled with the chain | | `transactions[].unverifiedReason` | string? | Present only when `verified` is `false` | -| `transactions[].contractType` / `operation` | string | Machine enum / human operation name | -| `transactions[].rawAmount` | string | Raw integer amount; units follow the contract type | +| `transactions[].contractType` | string | Contract type reported by the service | +| `transactions[].from` / `to` | string? | Decoded sender and recipient when the contract type exposes them | +| `transactions[].rawAmount` | string? | Decoded raw integer amount when available; units follow the contract type | | `transactions[].originator` / `owner` | string | Who created it / whose account it acts on | | `transactions[].permission` | object | `id`, `name`, `threshold` | | `transactions[].currentWeight` / `missingWeight` / `thresholdReached` | — | Approval progress | | `transactions[].awaitingMySignature` | boolean | Whether it is waiting on the selected account | | `transactions[].signedByCurrentAccount` | boolean | Whether this account already signed | +| `transactions[].createdAt` / `expiration` | number | Service creation time and transaction expiry, in Unix milliseconds | +| `transactions[].expired` | boolean | Whether the transaction is already expired | +| `transactions[].signatures` | number | Number of signatures currently attached | +| `transactions[].signatureProgress` | array | Per-key `address`, `weight`, `signed`, and nullable `signedAt` | A record the client cannot reconcile with the chain stays visible and is labelled rather than failing the whole page. @@ -170,7 +179,7 @@ A record the client cannot reconcile with the chain stays visible and is labelle | `hex` | string | The transaction hex including all signatures gathered so far | | `transaction` | object | Transaction summary + approval progress | -`--watch` streams count nudges and emits no terminal JSON frame. +`--watch` streams count nudges. When stopped, its terminal result is `{action: "watch", address, notifications}` in JSON mode; text mode prints the same address and notification count. ## Exit status diff --git a/ts/docs/commands/tx/sign.md b/ts/docs/commands/tx/sign.md index 133047ac1..0d64cce5e 100644 --- a/ts/docs/commands/tx/sign.md +++ b/ts/docs/commands/tx/sign.md @@ -32,7 +32,7 @@ Payload integrity is checked in every mode, offline included. A TRON transaction That three-way check is TRON's; an EVM transaction hashes its own bytes, so there is nothing to disagree. -Four contract types cannot be re-encoded by the bundled decoder — `UnfreezeAssetContract`, `ShieldedTransferContract`, `MarketSellAssetContract`, `MarketCancelOrderContract`. `--hex` / `--file` input carrying one is refused with `invalid_transaction`; sign those through `--transaction` JSON instead. +Three contract types cannot be field-by-field re-encoded by the bundled decoder — `ShieldedTransferContract`, `MarketSellAssetContract`, and `MarketCancelOrderContract`. They are not refused: the command still verifies `txID = sha256(raw_data_hex)` and binds the declared contract type to the protobuf envelope, but it cannot independently prove that the human-readable fields inside `raw_data` match the executed fields. Treat those fields as unverified and inspect the artifact with tooling that understands the contract type before signing. `UnfreezeAssetContract` is fully re-encoded by the bundled TRC10 codec. ## Options @@ -42,7 +42,7 @@ Four contract types cannot be re-encoded by the bundled decoder — `UnfreezeAss | `--file ` | **Required** (one of). File containing the transaction hex (prefer this for long hex) | | `--transaction ` | **Required** (one of). **TRON only.** Unsigned TRON transaction JSON; compatibility path, never checked online | | `--offline` | Sign locally without contacting a node; skips the signer-permission and approval-weight checks. Only meaningful on TRON — EVM signing contacts no node either way | -| `--out ` | Write the resulting hex to a file (mode 0644, written atomically) instead of stdout | +| `--out ` | **TRON artifact path only.** Atomically write the resulting co-signed protobuf hex to a mode-0644 file instead of stdout. Do not use on EVM: the current EVM binding accepts but ignores this option | Plus the [global options](../index.md#global-options-every-command) and `--password-stdin` for software accounts. @@ -117,6 +117,12 @@ echo "$PW" | wallet-cli tx sign --file tx.hex --account cosigner --out tx.signed {"schema":"wallet-cli.result.v1","success":true,"command":"tx.sign","data":{"kind":"tx-sign","signer":"TXe4Kd8nP2rF9gH5jL3mV6cW1bN7yS0aQz","hex":"0a02...9f31","checked":true,"transaction":{"txId":"9c1...","contractType":"TransferContract","operation":"Transfer TRX","from":"TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw","to":"TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub","rawAmount":"1000000000","permissionId":2,"expiration":1784388720000,"expired":false,"signatures":2},"signerWeight":1,"approval":{"txId":"9c1...","contractType":"TransferContract","operation":"Transfer TRX","from":"TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw","to":"TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub","rawAmount":"1000000000","permission":{"id":2,"name":"finance","threshold":2},"currentWeight":2,"missingWeight":0,"thresholdReached":true,"approved":[{"address":"TQkXm4vN8pR2sD6fWbYc3LhJa9Ee5Zt7Uw","weight":1},{"address":"TXe4Kd8nP2rF9gH5jL3mV6cW1bN7yS0aQz","weight":1}],"expiration":1784388720000,"expired":false,"signatures":2}},"meta":{"durationMs":310,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` +An EVM artifact-signing result has the single-signature shape: + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"tx.sign","data":{"kind":"sign","mode":"sign-only","signed":{"raw":"0x02f86b...","hash":"0x55b0068ef31bce39bbf5b06d456eaef307fd77f96d85ea291f48c1ae4b900d80"},"address":"0x88878d9250e68C574912f5618ad3b43f675B8888","txId":"0x55b0068ef31bce39bbf5b06d456eaef307fd77f96d85ea291f48c1ae4b900d80"},"meta":{"durationMs":84,"warnings":[]},"chain":{"family":"evm","network":"evm:11155111","chainId":"11155111"}} +``` + ## Output The two input modes return different shapes. @@ -133,11 +139,11 @@ The two input modes return different shapes. | `signerWeight` | number | The signer's weight in the group. TRON, and only when `checked` is `true` | | `approval` | object | Authoritative online approval state, same shape as [`tx approvals`](approvals.md) `data`. TRON, and only when `checked` is `true` | -On EVM the result is the single-signature shape instead — `kind: "sign"`, `mode: "sign-only"`, `signed` (`{raw, hash}`), `hex`, `address`, `txId` — the same shape `tx send --sign-only` emits, since one signature completes the transaction. +On EVM the result is the single-signature shape instead — `kind: "sign"`, `mode: "sign-only"`, `signed` (`{raw, hash}`), `address`, and `txId`. There is no top-level `hex`; the raw signed transaction is `signed.raw`. The accepted `--out` option is currently ignored by the EVM binding, so write `data.signed.raw` yourself or omit the flag. -`transaction` is always present and identical in both modes, so a consumer can read it unconditionally; test `checked` before reaching for `approval`. +For TRON `--hex` / `--file` results, `transaction` is always present in online and offline modes, so a consumer can read it unconditionally; test `checked` before reaching for `approval`. EVM results do not contain `transaction` or `checked`. -`--transaction` (direct JSON signing) returns the same shape `tx send --sign-only` emits, so consumers need no branch: +`--transaction` is the TRON-only direct JSON path and returns the same shape that TRON `tx send --sign-only` emits: | Field | Type | Meaning | |---|---|---| @@ -145,7 +151,7 @@ On EVM the result is the single-signature shape instead — `kind: "sign"`, `mod | `mode` | string | `"sign-only"` | | `address` | string | Address that produced the signature | | `txId` | string | Transaction id | -| `signed` | object | The signed transaction — exactly what [`tx broadcast`](broadcast.md) accepts. A TRON transaction object here; `{raw, hash}` on EVM | +| `signed` | object | Signed TRON transaction object — exactly what TRON [`tx broadcast`](broadcast.md) accepts through `--transaction` / `--tx-stdin` | No `fee` is reported for `--transaction`: nothing was estimated, because the transaction was not built here. diff --git a/ts/docs/commands/vote/cast.md b/ts/docs/commands/vote/cast.md index 3f0cd0f25..d311310f8 100644 --- a/ts/docs/commands/vote/cast.md +++ b/ts/docs/commands/vote/cast.md @@ -48,9 +48,9 @@ echo "$PW" | wallet-cli vote cast --for TZ4...=600 --for TT5...=400 --network tr ``` ```console -⏳ Submitted — vote 1,000 TP across 2 SRs - TxID e5f... +⏳ Voted 1,000 TP across 2 witnesses Votes TZ4...=600, TT5...=400 + TxID e5f... Status pending — tallied at next maintenance cycle (~6h) ! Track it: wallet-cli tx info --network tron:nile --txid e5f... ``` @@ -70,10 +70,10 @@ echo "$PW" | wallet-cli vote cast --for TZ4...=600 --for TT5...=400 --network tr ``` ```console -✅ Voted 1,000 TP across 2 SRs - TxID f8a... +✅ Voted 1,000 TP across 2 witnesses Votes TZ4...=600, TT5...=400 - Block 84,121,055 + TxID f8a... + Block #84,121,055 Fee 0 TRX Status success — tallied at next maintenance cycle (~6h) ``` diff --git a/ts/docs/commands/vote/list.md b/ts/docs/commands/vote/list.md index 933b0bc6a..e3c4b55d0 100644 --- a/ts/docs/commands/vote/list.md +++ b/ts/docs/commands/vote/list.md @@ -34,11 +34,11 @@ wallet-cli vote list --limit 3 --network tron:nile ``` ```console -| Rank | Name | Votes | APR | Reward ratio | Address | -| ---- | --------------- | ------------- | ---- | ------------ | ---------------------------------- | -| 1 | TRONSCAN | 1,203,456,789 | — | 80% | TZ4UXDV5ZhNW7fb2AMSbgfAEZ7hWsnYS2g | -| 2 | Binance Staking | 998,765,432 | — | 0% | TT5W8MPbYJih9R586kTszb4LoybzUvCYm2 | -| 3 | JustLend | 876,543,210 | — | 80% | TWxkzUeAiKcFvzXvJEcaTQCQqCuMednAtN | +| Rank | Name | Votes | APR | Reward ratio | Address | +| ---- | ---------------- | ------------- | ---- | ------------ | ---------------------------------- | +| 1 | tronscan.org | 1,203,456,789 | — | 80% | TZ4UXDV5ZhNW7fb2AMSbgfAEZ7hWsnYS2g | +| 2 | binance.com | 998,765,432 | — | 0% | TT5W8MPbYJih9R586kTszb4LoybzUvCYm2 | +| 3 | justlend.org | 876,543,210 | — | 80% | TWxkzUeAiKcFvzXvJEcaTQCQqCuMednAtN | ``` ```bash @@ -46,7 +46,7 @@ wallet-cli vote list --limit 3 --network tron:nile -o json ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"vote.list","data":{"witnesses":[{"rank":1,"name":"TRONSCAN","address":"TZ4UXDV5ZhNW7fb2AMSbgfAEZ7hWsnYS2g","voteCount":"1203456789","rewardRatioPct":80,"brokeragePct":20,"aprPct":null}]},"meta":{"durationMs":40,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"vote.list","data":{"witnesses":[{"rank":1,"name":"tronscan.org","address":"TZ4UXDV5ZhNW7fb2AMSbgfAEZ7hWsnYS2g","voteCount":"1203456789","rewardRatioPct":80,"brokeragePct":20,"aprPct":null}]},"meta":{"durationMs":40,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` ## Output @@ -56,11 +56,11 @@ wallet-cli vote list --limit 3 --network tron:nile -o json | Field | Type | Meaning | |---|---|---| | `rank` | number | Rank by vote count (1 = most votes) | -| `name` | string | SR name | +| `name` | string | Hostname derived from the witness URL; falls back to the URL text or address | | `address` | string | SR base58 address | | `voteCount` | string | Total votes, raw integer | -| `rewardRatioPct` | number | % of rewards passed to voters (on-chain) | -| `brokeragePct` | number | SR's cut (= 100 − `rewardRatioPct`) | +| `rewardRatioPct` | number \| null | % of rewards passed to voters; `null` when brokerage cannot be read | +| `brokeragePct` | number \| null | SR's cut (= 100 − `rewardRatioPct`); `null` when unavailable | | `aprPct` | null | Reserved field; always `null` in the current implementation | ## Exit status diff --git a/ts/docs/commands/vote/status.md b/ts/docs/commands/vote/status.md index b06d8e41b..933fe00cd 100644 --- a/ts/docs/commands/vote/status.md +++ b/ts/docs/commands/vote/status.md @@ -35,9 +35,9 @@ Claimable 12.345678 TRX Current votes (2) | Name | Votes | APR | Reward ratio | Address | | --------------- | ----- | ---- | ------------ | ---------------------------------- | -| TRONSCAN | 600 | — | 80% | TZ4UXDV5ZhNW7fb2AMSbgfAEZ7hWsnYS2g | -| Binance Staking | 400 | — | 0% | TT5W8MPbYJih9R586kTszb4LoybzUvCYm2 | -! 400 votes on Binance Staking earn nothing — 0% reward ratio +| tronscan.org | 600 | — | 80% | TZ4UXDV5ZhNW7fb2AMSbgfAEZ7hWsnYS2g | +| binance.com | 400 | — | 0% | TT5W8MPbYJih9R586kTszb4LoybzUvCYm2 | +! 400 votes on binance.com earn nothing — 0% reward ratio ``` ```bash @@ -45,7 +45,7 @@ wallet-cli vote status --account main --network tron:nile -o json ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"vote.status","data":{"address":"TQk...","votingPower":{"total":1500,"used":1000,"available":500},"claimableRewardSun":"12345678","votes":[{"witness":"TZ4...","name":"TRONSCAN","count":600,"rewardRatioPct":80,"brokeragePct":20,"aprPct":null},{"witness":"TT5...","name":"Binance Staking","count":400,"rewardRatioPct":0,"brokeragePct":100,"aprPct":null}]},"meta":{"durationMs":16,"warnings":["400 votes on TT5... (Binance Staking) earn nothing: reward ratio is 0%"]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"vote.status","data":{"address":"TQk...","votingPower":{"total":1500,"used":1000,"available":500},"claimableRewardSun":"12345678","votes":[{"witness":"TZ4...","name":"tronscan.org","count":600,"rewardRatioPct":80,"brokeragePct":20,"aprPct":null},{"witness":"TT5...","name":"binance.com","count":400,"rewardRatioPct":0,"brokeragePct":100,"aprPct":null}]},"meta":{"durationMs":16,"warnings":["400 votes on TT5... (binance.com) earn nothing: reward ratio is 0%"]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` ## Output @@ -55,7 +55,7 @@ wallet-cli vote status --account main --network tron:nile -o json | `address` | string | Queried account | | `votingPower.total` / `.used` / `.available` | number | TP total / spent / spendable | | `claimableRewardSun` | string | Currently claimable reward, in SUN | -| `votes[]` | array | Current distribution: `witness`, `name`, `count`, `rewardRatioPct`, `brokeragePct`, and reserved `aprPct` (always `null`) | +| `votes[]` | array | Current distribution: `witness`, URL-hostname `name`, `count`, nullable `rewardRatioPct` / `brokeragePct`, and reserved `aprPct` (always `null`) | Zero-reward-ratio warnings appear in `meta.warnings` as plain strings — see [reading `meta.warnings`](../../machine-interface.md#reading-metawarnings). diff --git a/ts/docs/commands/witness/create.md b/ts/docs/commands/witness/create.md index 2dc6865dc..f17de3dfe 100644 --- a/ts/docs/commands/witness/create.md +++ b/ts/docs/commands/witness/create.md @@ -60,7 +60,7 @@ echo "$PW" | wallet-cli witness create --url https://sr.acme.io --network tron:n ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"witness.create","data":{"kind":"witness-create","stage":"confirmed","txId":"d3a...","confirmed":true,"blockNumber":57881020,"failed":false,"witnessAddress":"TSRmq8kP...","url":"https://sr.acme.io","feeSun":9999000000,"resource":{"netUsage":285,"netFeeSun":0,"energyUsage":0,"energyFeeSun":0},"registrationFeeSun":9999000000},"meta":{"durationMs":6620,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"witness.create","data":{"kind":"witness-create","stage":"confirmed","txId":"d3a...","confirmed":true,"blockNumber":57881020,"failed":false,"witnessAddress":"TSRmq8kP...","url":"https://sr.acme.io","feeSun":"9999000000","energyUsed":0,"netUsed":285,"energyFeeSun":0,"netFeeSun":0,"registrationFeeSun":"9999000000","resource":{"netUsage":285,"netFeeSun":0,"energyUsage":0,"energyFeeSun":0}},"meta":{"durationMs":6620,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` ## Output @@ -69,10 +69,10 @@ echo "$PW" | wallet-cli witness create --url https://sr.acme.io --network tron:n | Stage | Fields | |---|---| -| default (submit) | `kind: "witness-create"`, `stage: "submitted"`, `txId`, `witnessAddress`, `url` | -| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, `feeSun`, `resource`, `failed`, `registrationFeeSun` | +| default (submit) | `kind: "witness-create"`, `stage: "submitted"`, `txId`, `witnessAddress`, `url`, `feeSun`, and `registrationFeeSun` | +| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, flat settlement fields when returned (`feeSun`, `energyUsed`, `netUsed`, `energyFeeSun`, `netFeeSun`), their governance compatibility view `resource` (`netUsage`, `netFeeSun`, `energyUsage`, `energyFeeSun`), `failed`, and `registrationFeeSun` | -`registrationFeeSun` is the burned registration fee on its own; `feeSun` is the transaction's total cost, which includes it. +`registrationFeeSun` and `feeSun` are decimal strings containing the same irreversible registration burn. The command deliberately overwrites the node receipt's bandwidth/energy fee with that economically relevant amount; do not add the two fields together. ## Exit status diff --git a/ts/docs/commands/witness/set-brokerage.md b/ts/docs/commands/witness/set-brokerage.md index 40f247eab..e71ba4acf 100644 --- a/ts/docs/commands/witness/set-brokerage.md +++ b/ts/docs/commands/witness/set-brokerage.md @@ -62,7 +62,7 @@ echo "$PW" | wallet-cli witness set-brokerage 20 --network tron:nile --wait --pa ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"witness.set-brokerage","data":{"kind":"witness-set-brokerage","stage":"confirmed","txId":"f8c...","confirmed":true,"blockNumber":57881402,"failed":false,"witnessAddress":"TSRmq8kP...","brokerage":20,"feeSun":0,"resource":{"netUsage":269,"netFeeSun":0,"energyUsage":0,"energyFeeSun":0}},"meta":{"durationMs":6470,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"witness.set-brokerage","data":{"kind":"witness-set-brokerage","stage":"confirmed","txId":"f8c...","confirmed":true,"blockNumber":57881402,"failed":false,"witnessAddress":"TSRmq8kP...","brokerage":20,"feeSun":0,"energyUsed":0,"netUsed":269,"energyFeeSun":0,"netFeeSun":0,"resource":{"netUsage":269,"netFeeSun":0,"energyUsage":0,"energyFeeSun":0}},"meta":{"durationMs":6470,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` ## Output @@ -72,7 +72,7 @@ echo "$PW" | wallet-cli witness set-brokerage 20 --network tron:nile --wait --pa | Stage | Fields | |---|---| | default (submit) | `kind: "witness-set-brokerage"`, `stage: "submitted"`, `txId`, `witnessAddress`, `brokerage` | -| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, `feeSun`, `resource`, `failed` | +| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, flat settlement fields when returned (`feeSun`, `energyUsed`, `netUsed`, `energyFeeSun`, `netFeeSun`), their governance compatibility view `resource` (`netUsage`, `netFeeSun`, `energyUsage`, `energyFeeSun`), and `failed` | `brokerage` is the value now in effect, as a number. diff --git a/ts/docs/commands/witness/update.md b/ts/docs/commands/witness/update.md index f50a01b0b..42f36539e 100644 --- a/ts/docs/commands/witness/update.md +++ b/ts/docs/commands/witness/update.md @@ -58,7 +58,7 @@ echo "$PW" | wallet-cli witness update --url https://sr.acme.io/v2 --network tro ``` ```json -{"schema":"wallet-cli.result.v1","success":true,"command":"witness.update","data":{"kind":"witness-update","stage":"confirmed","txId":"e5b...","confirmed":true,"blockNumber":57881190,"failed":false,"witnessAddress":"TSRmq8kP...","url":"https://sr.acme.io/v2","feeSun":0,"resource":{"netUsage":270,"netFeeSun":0,"energyUsage":0,"energyFeeSun":0}},"meta":{"durationMs":6440,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +{"schema":"wallet-cli.result.v1","success":true,"command":"witness.update","data":{"kind":"witness-update","stage":"confirmed","txId":"e5b...","confirmed":true,"blockNumber":57881190,"failed":false,"witnessAddress":"TSRmq8kP...","url":"https://sr.acme.io/v2","feeSun":0,"energyUsed":0,"netUsed":270,"energyFeeSun":0,"netFeeSun":0,"resource":{"netUsage":270,"netFeeSun":0,"energyUsage":0,"energyFeeSun":0}},"meta":{"durationMs":6440,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} ``` ## Output @@ -68,7 +68,7 @@ echo "$PW" | wallet-cli witness update --url https://sr.acme.io/v2 --network tro | Stage | Fields | |---|---| | default (submit) | `kind: "witness-update"`, `stage: "submitted"`, `txId`, `witnessAddress`, `url` | -| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, `feeSun`, `resource`, `failed` | +| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, flat settlement fields when returned (`feeSun`, `energyUsed`, `netUsed`, `energyFeeSun`, `netFeeSun`), their governance compatibility view `resource` (`netUsage`, `netFeeSun`, `energyUsage`, `energyFeeSun`), and `failed` | ## Exit status diff --git a/ts/docs/concepts/security.md b/ts/docs/concepts/security.md index 79254f4b3..bb02d9cb4 100644 --- a/ts/docs/concepts/security.md +++ b/ts/docs/concepts/security.md @@ -46,7 +46,7 @@ Unexpected internal exceptions are collapsed to a generic `internal_error` messa | Software key | `create` / `import` | Convenient; host compromise = key compromise | | Ledger | `import ledger` | Key never on host; every send confirmed on-device. `--app` fixes the account to one chain family — import once per app to cover both — see [Ledger guide](../guide/ledger.md) | | Watch-only | `import watch` | No signing at all; safe for monitoring balances of cold storage. Bound to the pasted address's family | -| Split sign/broadcast | `tx send --build-only` → `tx sign --offline` → `tx broadcast` | Signing machine can stay offline; `--sign-only` still builds and estimates online — see [Scripting](../guide/scripting.md#sign-here-broadcast-there) | +| Split sign/broadcast | TRON: `tx send --build-only --expiration ` → `tx sign --offline` → `tx broadcast`; EVM: the same flow without `--expiration` | Signing machine can stay offline; `--sign-only` still builds and estimates online. TRON defaults to about 60 seconds and permits at most 24 hours, so set the shortest window that covers artifact transfer — see [Scripting](../guide/scripting.md#sign-here-broadcast-there) | ## What wallet-cli cannot do for you diff --git a/ts/docs/guide/ledger.md b/ts/docs/guide/ledger.md index 2591dad7b..71e3bab2d 100644 --- a/ts/docs/guide/ledger.md +++ b/ts/docs/guide/ledger.md @@ -18,12 +18,14 @@ Locally this creates a **watch-only** entry — no secret is stored; signing hap | Flag | Use when | |---|---| -| `--index ` | You know the account index under the app's default path (omit everything for index 0) | +| `--index ` | You know the account index under wallet-cli's family path template | | `--path ` | You need an explicit derivation path, e.g. `m/44'/195'/0'/0/0` (TRON) or `m/44'/60'/0'/0/0` (Ethereum) | | `--address ` | You know the address; wallet-cli scans indexes to find it (`--scan-limit`, default 20) | **`--app` fixes the account to one chain family.** Unlike a software account — which holds a TRON *and* an EVM address from the same seed — a Ledger account has exactly the one address its app derives, and only works on networks of that family. Selecting it elsewhere fails with `family_mismatch`. Import the same device twice, once per app, to cover both. +With no locator, a TTY presents a paged account selector; a non-interactive invocation falls back to index 0. For Ethereum, wallet-cli's `--index ` template is `m/44'/60'/0'/0/` (MetaMask style), while Ledger Live commonly uses `m/44'/60'/'/0/0`. Use `--path` to register the exact Ledger Live account instead of assuming the indexes are interchangeable. + Confirm with `wallet-cli list` — the account appears alongside your software accounts and works with `use`, `--account`, and every query command. `list` shows one family at a time, so a TRON-app account is invisible under `--network sepolia` and vice versa; `-o json` shows every account regardless. ## 2. Sign and send @@ -50,7 +52,7 @@ More remedies: [Troubleshooting](../troubleshooting.md#timeout-exit-1). ## Offline pattern -Ledger already isolates keys, but you can still split build/sign/broadcast. For a device machine with no chain access, build unsigned hex with `--build-only` on a connected machine, sign it with `tx sign --offline` where the Ledger is attached, then broadcast the signed hex from a connected machine. See [Scripting → Sign here, broadcast there](scripting.md#sign-here-broadcast-there). +Ledger already isolates keys, but you can still split build/sign/broadcast. For a device machine with no chain access, build TRON unsigned hex with an explicit signing window, for example `--build-only --expiration 3600000`, on a connected machine; sign it with `tx sign --offline` where the Ledger is attached; then broadcast the signed hex from a connected machine. The default TRON expiry is about 60 seconds and is usually too short for a cross-machine workflow; the maximum is 24 hours. EVM artifacts have no expiration flag. See [Scripting → Sign here, broadcast there](scripting.md#sign-here-broadcast-there). ## See also diff --git a/ts/docs/guide/scripting.md b/ts/docs/guide/scripting.md index c2e5035f5..4288b80fa 100644 --- a/ts/docs/guide/scripting.md +++ b/ts/docs/guide/scripting.md @@ -62,7 +62,7 @@ Or decouple: capture `data.txId`, then poll [`tx status`](../commands/tx/status. ```bash # on the connected build machine wallet-cli tx send --to T... --amount 1 --network tron:nile \ - --build-only -o json | jq -r '.data.hex' > unsigned.hex + --build-only --expiration 3600000 -o json | jq -r '.data.hex' > unsigned.hex # on the offline signing machine printf '%s' "$PW" | wallet-cli tx sign --file unsigned.hex --network tron:nile \ @@ -72,7 +72,7 @@ printf '%s' "$PW" | wallet-cli tx sign --file unsigned.hex --network tron:nile \ wallet-cli tx broadcast --file signed.hex --network tron:nile -o json ``` -The **hex** form above works on both chain families — protobuf on TRON, RLP on EVM. If the signing machine does have RPC access and you only want to withhold broadcast, `tx send --sign-only` emits signed hex directly. +The **hex** form above works on both chain families — protobuf on TRON, RLP on EVM. `--expiration` is TRON-only; its value above gives the transfer one hour for file movement and signing (maximum 24 hours). The node default is about 60 seconds, and `tx sign --offline` refuses an expired artifact, so choose the shortest practical window and rebuild after it expires. Omit the flag for EVM, whose transaction format has no expiration field. If the signing machine does have RPC access and you only want to withhold broadcast, `tx send --sign-only` emits signed hex directly. TRON also accepts signed transaction JSON, but JSON must go through `--transaction` or `--tx-stdin`; `--file` and `--hex` are hex-only: diff --git a/ts/docs/machine-interface.md b/ts/docs/machine-interface.md index f0633bdd3..3fb394391 100644 --- a/ts/docs/machine-interface.md +++ b/ts/docs/machine-interface.md @@ -21,7 +21,7 @@ wallet-cli --json-schema tron # scoped to one chain family wallet-cli --json-schema # one command ``` -One call returns the whole surface: `tool`, `version`, `globalFlags`, `errorCodes`, and `commands[]` — each with `id`, `path`, `usage`, `families`, `requires` (network / auth / wallet), `capability`, `examples`, and a JSON Schema for its input. This is the intended way for an agent to learn the CLI; do not scrape `--help`. +One call returns the whole surface: `tool`, `version`, `globalFlags`, `errorCodes`, and `commands[]`. Command entries carry `id`, `path`, `usage`, `requires` (network / auth / wallet), `capability`, `examples`, and a JSON Schema for their input; chain commands also declare `families`. This is the intended way for an agent to learn the CLI; do not scrape `--help`. ### Chain families @@ -31,7 +31,7 @@ A network belongs to one **chain family**, `tron` or `evm`, and that is what dec - A flag may belong to one family too (`--asset-id` and `--permission-id` are TRON's, `--gas-limit` and `--nonce` are EVM's). Using one on the other family is **`invalid_option`** at exit `2`. `--help` tags them `(tron only)` / `(evm only)`. - An **account** is not family-bound when it holds a key — a seed or private-key account has both a TRON and an EVM address. Watch-only and Ledger accounts hold one address and therefore one family; selecting one on a mismatched network is also `family_mismatch`. -Both checks are static: they depend on the command, the flags and the selected network only, so an agent can decide them from the catalog without a call. +Command-family and flag-family checks are static and can be decided from the catalog. Account-family compatibility also depends on the selected wallet account: key-backed accounts serve both families, while watch-only and Ledger accounts are family-bound. ### Startup wallet-data upgrades @@ -106,10 +106,12 @@ Schema id: `wallet-cli.result.v1`. | `error.details` | object | optional | Structured extras when available | | `meta.durationMs` | number | always | Wall time | | `meta.warnings` | `(string \| {code, message})[]` | always | Non-fatal notices; **elements are not uniformly typed** — see below | -| `meta.pagination` | object | paginated commands only | `offset` / `limit` / `total`; present where `--limit` / `--offset` apply — see [pagination](#pagination) | -| `chain` | object | when a network was selected | `family` / `network` / `chainId`. Present on every chain command, and on the local commands that take `--network` as a display selector (`list`, `current`). Commands that never take one (`config`, `networks`, `contact`, `encoding`, `address`, `create`, `import`, …) omit it — its presence does **not** mean a node was contacted | +| `meta.pagination` | object | windowed commands only | `offset` / `limit` / `total`; present when the command returns a pagination window — see [pagination](#pagination) | +| `chain` | object | when a network was selected | `family` / `network` / `chainId`. Present on every chain command and on local commands whose policy resolves a network. Commands with `network: "none"` omit it; its presence does **not** mean a node was contacted | -Encoding rules: `bigint` values are serialized as decimal **strings** (e.g. `"balance": "1976489000"`), binary as hex. Treat every on-chain amount as a string. +The current local network-aware commands are `backup`, `current`, and `list`. They use the selected or default network as a family/display selector without contacting a node. + +Encoding rules: `bigint` values are serialized as decimal **strings** (e.g. `"balance": "1976489000"`), and binary values are hex. Amounts represented by `bigint` or protocol int64 values are strings; bounded counters and fees such as `feeSun`, `multiSignFeeSun`, `energyUsed`, and `netUsed` may be JSON numbers. Follow each command's field table instead of coercing every amount to one type. ### Reading `meta.warnings` @@ -127,7 +129,7 @@ Helpers that assume strings (`.meta.warnings | join("\n")`, `Array.prototype.joi ### Pagination -Every command that takes `--limit` / `--offset` reports the window it returned in `meta.pagination`, never inside `data`: +Commands that return an offset/limit window report it in `meta.pagination`, never inside `data`. The current set is `asset list`, `exchange list`, `proposal list`, and `backup --records`; a command may accept `--limit` merely as a result cap and then omit pagination metadata. | Key | Type | Meaning | |---|---|---|

- A command-line wallet for the TRON network — interactive in Java, agent-first in TypeScript + A command-line wallet for TRON and selected EVM networks — dual-mode in Java, agent-first in TypeScript