Feat/ts v4.12.0

ts/README.md

@@ -148,6 +148,7 @@ Token and contract operations, resource staking, voting rewards, message signing
 | [`message`](docs/commands/message/index.md) · [`typed-data`](docs/commands/typed-data/index.md) | Sign arbitrary messages, or EIP-712/TIP-712 structured data |
 | [`permission`](docs/commands/permission/index.md) | View / update account permissions for multi-sig |
 | [`gasfree`](docs/commands/gasfree/index.md) | Gas-free token transfers via the GasFree service |
+| [`typed-data`](docs/commands/typed-data/index.md) | Sign EIP-712 / TIP-712 structured data ([sign](docs/commands/typed-data/sign.md)) |
 
 ### Local tools and configuration
 

ts/docs/commands/account/activate.md

@@ -26,8 +26,8 @@ Requires the payer account and the master password via `--password-stdin`; watch
 | `--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` |
-| `--expiration <ms>` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only` |
-| `--permission-id <n>` | Permission group to sign with (default `0`) |
+| `--expiration <ms>` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) |
+| `--permission-id <n>` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` |
 | `--wait` / `--wait-timeout <ms>` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) |
 | `--password-stdin` | Master password from stdin |
 

ts/docs/commands/account/set.md

@@ -27,8 +27,8 @@ Requires the account and the master password via `--password-stdin`; watch-only
 | `--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` |
-| `--expiration <ms>` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only` |
-| `--permission-id <n>` | Permission group to sign with (default `0`) |
+| `--expiration <ms>` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) |
+| `--permission-id <n>` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` |
 | `--wait` / `--wait-timeout <ms>` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) |
 | `--password-stdin` | Master password from stdin |
 

ts/docs/commands/asset/index.md

@@ -0,0 +1,37 @@
+# wallet-cli asset
+
+Issue and operate TRC10 tokens.
+
+TRC10 is TRON's **chain-native** token type: the protocol itself tracks issuance, an ICO window and frozen supply, with no smart contract involved. That is why it is a group of its own — [`token`](../token/index.md) handles TRC20 contract tokens, and the two share almost no mechanics.
+
+Two things shape everything in this group:
+
+- **An account may issue exactly one TRC10, ever.** `asset issue` burns a fee that is not refunded, and once it lands the account can never issue again. Only the description, URL and the two free-bandwidth limits stay changeable; supply, price, ICO dates, precision and the frozen tranches are fixed permanently.
+- **Transfer is not here.** Sending TRC10 is [`tx send`](../tx/send.md) with an asset id — the same command you use for everything else.
+
+**Ledger cannot sign any of the write commands in this group.** The Ledger TRON app does not implement the TRC10 issuance contract types, so `issue`, `update`, `participate` and `unfreeze` require a software account and fail fast with `ledger_unsupported`. (TRC10 *transfer* via `tx send` does work on Ledger.)
+
+## Synopsis
+
+```
+wallet-cli asset COMMAND
+```
+
+## Subcommands
+
+| Command | Page | Description |
+|---|---|---|
+| `asset issue` | [issue.md](issue.md) | Issue a TRC10 and lock in its ICO terms |
+| `asset update` | [update.md](update.md) | Update the four mutable fields of your TRC10 |
+| `asset participate` | [participate.md](participate.md) | Buy into a TRC10's ICO at its fixed rate |
+| `asset unfreeze` | [unfreeze.md](unfreeze.md) | Release matured frozen supply |
+| `asset info` | [info.md](info.md) | Show one TRC10 in full |
+| `asset list` | [list.md](list.md) | List TRC10 tokens, one page at a time |
+
+## Units
+
+Command input and text output use **whole tokens**. JSON and the chain use **minimal units** — whole tokens scaled by the asset's `precision`. A token with `precision: 6` and a supply of 1,000,000,000 has an on-chain `total_supply` of `1000000000000000`.
+
+## See also
+
+[`token`](../token/index.md) (TRC20) · [`tx send`](../tx/send.md) (TRC10 transfer) · [`exchange`](../exchange/index.md) (trading TRC10 against TRX)

ts/docs/commands/asset/info.md

@@ -0,0 +1,73 @@
+# wallet-cli asset info
+
+Show one TRC10 in full.
+
+## Synopsis
+
+```
+wallet-cli asset info [<asset>] [--issuer <address>] [options]
+```
+
+## Description
+
+Shows a single TRC10's complete record: issuer, total supply, precision, ICO rate and window, project URL, description, both free-bandwidth limits, and every frozen tranche with its unlock time.
+
+Give **exactly one** of the `<asset>` argument or `--issuer`. A purely numeric `<asset>` is read as an id; anything else is read as a name. `--issuer` looks up the token issued by an address — unique by construction, since an account can only issue one.
+
+**Token names are not unique.** Duplicate names have been permitted since `AllowSameTokenName` was enabled, and there really are duplicates on both mainnet and Nile. A name matching more than one token is an **error** (`ambiguous_asset_name`) carrying the matching ids, not a differently-shaped success — the JSON `data` shape for this command never varies, so an agent can rely on it.
+
+Quantities are whole tokens in text and minimal units in JSON; the record carries its own `precision`, so no extra lookup is involved either way.
+
+**Related but different:** [`token info`](../token/info.md) is the cross-type metadata lookup (name / symbol / decimals / total supply, TRC20 and TRC10 alike). This command gives the TRC10-only issuance record.
+
+## Arguments
+
+| Argument | Description |
+|---|---|
+| `<asset>` | Token id or name; a numeric value is read as the id. Exactly one of this or `--issuer` |
+
+## Options
+
+| Option | Description |
+|---|---|
+| `--issuer <string>` | Look up the token issued by this address. Exactly one of this or `<asset>` |
+
+Plus the [global options](../index.md#global-options-every-command).
+
+## Examples
+
+By id:
+
+```bash
+wallet-cli asset info 1000123 --network tron:nile
+```
+
+By name — fails with the candidate ids if the name is not unique:
+
+```bash
+wallet-cli asset info MyToken --network tron:nile
+```
+
+By issuer:
+
+```bash
+wallet-cli asset info --issuer TQkXm4vN...5Zt7Uw --network tron:nile
+```
+
+Machine-readable:
+
+```bash
+wallet-cli asset info 1000123 --network tron:nile -o json
+```
+
+## Errors
+
+| Code | Meaning |
+|---|---|
+| `asset_not_found` | No TRC10 matches that id, name or issuer |
+| `ambiguous_asset_name` | The name matches several tokens; `details.assetIds` lists them |
+| `invalid_value` | Neither or both of `<asset>` and `--issuer` were given |
+
+## See also
+
+[`asset list`](list.md) · [`token info`](../token/info.md) · [`asset` group](index.md)

ts/docs/commands/asset/issue.md

@@ -0,0 +1,95 @@
+# wallet-cli asset issue
+
+Issue a TRC10 token and lock in its ICO terms.
+
+## Synopsis
+
+```
+wallet-cli asset issue --name <name> --supply <n> --price <trx>:<tokens>
+                       --start <datetime> --end <datetime> --url <url>
+                       [--abbr <s>] [--precision <0-6>] [--description <s>]
+                       [--free-net-per-account <n>] [--public-free-net <n>]
+                       [--freeze <amount>:<days> ...]
+                       [--dry-run | (--sign-only | --build-only) [--expiration <ms>] | --wait [--wait-timeout <ms>]] [--permission-id <n>] [options]
+```
+
+## Description
+
+Issues a TRC10 token and fixes its ICO terms in the same transaction.
+
+**This is irreversible in two ways.** The issuance fee is burned and never refunded, and an account can only ever issue **one** TRC10 — get it wrong and your only option is a different account. There is no confirmation prompt (it would break scripted use); preview with `--dry-run` instead.
+
+Only `--description`, `--url`, `--free-net-per-account` and `--public-free-net` can be changed afterwards, via [`asset update`](update.md). Supply, price, ICO dates, precision and the frozen tranches have no on-chain modification path at all.
+
+**`--price` is converted using `--precision`.** On chain the rate is a pair of int32s meaning "`trx_num` sun buys `num` minimal units", so the same `--price 1:100` stores as `trx_num=1, num=100` at `--precision 6` but `trx_num=10000, num=1` at `--precision 0`. The CLI reduces the fraction to lowest terms and refuses the issuance if either side no longer fits in an int32 — a silently truncated rate would misprice the token permanently.
+
+`--start` and `--end` are always read as **UTC**, so they mean the same thing on any machine. A bare date is midnight UTC, which means the earliest date-only `--start` is tomorrow; pass a time to open the sale today.
+
+Chain limits we cannot read are not pre-checked. The node exposes no RPC for the maximum tranche count, the tranche day bounds or the daily bandwidth limit, so those are left to the node to reject — which costs nothing, because a rejected transaction never enters a block and burns no fee.
+
+**By default the command returns at submission**; `--wait` blocks until confirmed. **The asset id is assigned by the chain**, so it only appears in the receipt once confirmed — without `--wait` the response carries the txid and no `assetId`.
+
+**Ledger accounts are refused** (`ledger_unsupported`): the Ledger TRON app cannot decode `AssetIssueContract`.
+
+## Options
+
+| Option | Description |
+|---|---|
+| `--name <string>` | **Required.** Token name, 1–32 visible ASCII characters — no spaces, no non-ASCII |
+| `--supply <string>` | **Required.** Total supply, in whole tokens |
+| `--price <trx>:<tokens>` | **Required.** ICO rate in whole TRX to whole tokens, e.g. `1:100` |
+| `--start <datetime>` | **Required.** ICO start, `YYYY-MM-DD` or `"YYYY-MM-DD HH:mm:ss"`, read as UTC; must be in the future |
+| `--end <datetime>` | **Required.** ICO end, same format, must be after `--start` |
+| `--url <string>` | **Required.** Project page; must not be empty, up to 256 bytes |
+| `--abbr <string>` | Token abbreviation; same character rules as `--name` |
+| `--precision <0-6>` | Decimal places (default `0`) |
+| `--description <string>` | Short description, up to 200 bytes |
+| `--free-net-per-account <n>` | Free bandwidth each holder may use |
+| `--public-free-net <n>` | Shared free bandwidth pool for holders |
+| `--freeze <amount>:<days>` | Frozen tranche, amount in whole tokens; repeatable for multiple tranches |
+| `--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` |
+| `--expiration <ms>` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) |
+| `--permission-id <n>` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` |
+| `--wait` / `--wait-timeout <ms>` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) |
+| `--password-stdin` | Master password from stdin |
+
+Plus the [global options](../index.md#global-options-every-command).
+
+## Examples
+
+In the examples, `$PW` is your master password, fed on stdin via `--password-stdin`.
+
+Preview before spending anything — always do this first:
+
+```bash
+echo "$PW" | wallet-cli asset issue --name MyToken --abbr MTK --supply 1000000000 \
+  --price 1:100 --precision 6 --start 2026-08-01 --end 2026-08-31 \
+  --url https://mytoken.io --dry-run --password-stdin --network tron:nile
+```
+
+Issue with two frozen tranches, waiting for the id:
+
+```bash
+echo "$PW" | wallet-cli asset issue --name MyToken --abbr MTK --supply 1000000000 \
+  --price 1:100 --precision 6 --start 2026-08-01 --end 2026-08-31 \
+  --url https://mytoken.io --description "Demo TRC10" \
+  --freeze 100000000:30 --freeze 50000000:90 \
+  --wait --password-stdin --network tron:nile
+```
+
+## Errors
+
+| Code | Meaning |
+|---|---|
+| `already_issued_asset` | This account has already issued a TRC10 |
+| `invalid_asset_name` | `--name` / `--abbr` is not 1–32 visible ASCII characters |
+| `invalid_value` | Price, precision, dates, byte lengths or tranche syntax out of range |
+| `ledger_unsupported` | The account is Ledger-backed; use a software account |
+| `watch_only_no_signer` | The account cannot sign |
+| `transaction_rejected` | The node refused it — the message carries its reason |
+
+## See also
+
+[`asset update`](update.md) · [`asset info`](info.md) · [`asset` group](index.md)

ts/docs/commands/asset/list.md

@@ -0,0 +1,58 @@
+# wallet-cli asset list
+
+List TRC10 tokens, one page at a time.
+
+## Synopsis
+
+```
+wallet-cli asset list [--limit <n>] [--offset <n>] [options]
+```
+
+## Description
+
+Lists TRC10 tokens with id, name, total supply, precision and issuer. Use [`asset info`](info.md) for one token in full.
+
+**Paged server-side, and small by default.** There are thousands of TRC10s on chain — around 5,200 on mainnet and 7,300 on Nile, roughly 2.7 MB if fetched in one go — so `--limit` defaults to **10**. Raise it deliberately; a tool call that returns five thousand records will exhaust an agent's context long before anyone notices.
+
+**No total is reported.** The paginated node endpoint does not return a count, and the only way to compute one is to transfer every record. [`meta.pagination`](../../machine-interface.md#reading-metapagination) therefore carries `total: null` — the count does not exist, rather than having been omitted — alongside `offset` and `limit`; the text header reads `Assets (limit 10, offset 0)`. Page until you get a short page.
+
+Total supply is shown in whole tokens; each record carries its own precision, so this costs no extra lookups.
+
+## Options
+
+| Option | Description |
+|---|---|
+| `--limit <number>` | Max tokens to return, 1–1000 (default `10`) |
+| `--offset <number>` | Pagination offset (default `0`) |
+
+Plus the [global options](../index.md#global-options-every-command).
+
+## Examples
+
+First page:
+
+```bash
+wallet-cli asset list --network tron:nile
+```
+
+Walk further in:
+
+```bash
+wallet-cli asset list --limit 50 --offset 50 --network tron:nile
+```
+
+Machine-readable:
+
+```bash
+wallet-cli asset list --limit 50 --network tron:nile -o json
+```
+
+## Errors
+
+| Code | Meaning |
+|---|---|
+| `invalid_value` | `--limit` outside 1–1000, or a negative `--offset` |
+
+## See also
+
+[`asset info`](info.md) · [`asset` group](index.md)

ts/docs/commands/asset/participate.md

@@ -0,0 +1,78 @@
+# wallet-cli asset participate
+
+Buy into a TRC10's ICO at its fixed rate.
+
+## Synopsis
+
+```
+wallet-cli asset participate <asset> --pay <trx>
+                             [--dry-run | (--sign-only | --build-only) [--expiration <ms>] | --wait [--wait-timeout <ms>]] [--permission-id <n>] [options]
+```
+
+## Description
+
+Buys tokens directly from an issuer during its ICO window, at the rate fixed when the token was issued. This is **participation in the issuance**, not a market trade — there is no counterparty, no order book and no price discovery. To trade a TRC10 against TRX at a market-ish price, see [`exchange trade`](../exchange/trade.md).
+
+**`--pay` is the TRX you spend, not the tokens you receive.** The chain computes `floor(pay × num ÷ trx_num)` — multiply first, then truncate — and transfers your TRX in full, so a truncated remainder is not refunded. Paying too little to buy even one minimal unit is rejected before broadcast rather than sent and wasted.
+
+The issuer's address is resolved from the token automatically; you never pass it.
+
+`<asset>` is a token id or a name. A purely numeric value is read as an id. Names are not unique on chain — a name matching more than one token is rejected with `ambiguous_asset_name` and the matching ids, so re-run with the id.
+
+**By default the command returns at submission**; `--wait` blocks until confirmed. The received amount is exact integer arithmetic from the token's fixed rate, so it is reported in both cases.
+
+**Ledger accounts are refused** (`ledger_unsupported`): the Ledger TRON app cannot decode `ParticipateAssetIssueContract`.
+
+## Arguments
+
+| Argument | Description |
+|---|---|
+| `<asset>` | **Required.** Token id or name; a numeric value is read as the id |
+
+## Options
+
+| Option | Description |
+|---|---|
+| `--pay <string>` | **Required.** TRX to spend — not the number of tokens |
+| `--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` |
+| `--expiration <ms>` | Transaction expiration in ms, up to `86400000` (24h); only with `--sign-only` or `--build-only`; omitted = node default (~60s) |
+| `--permission-id <n>` | Permission group to sign with (0=owner, 1=witness, 2-9=active); default `0` |
+| `--wait` / `--wait-timeout <ms>` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) |
+| `--password-stdin` | Master password from stdin |
+
+Plus the [global options](../index.md#global-options-every-command).
+
+## Examples
+
+Spend 100 TRX on token 1000124:
+
+```bash
+echo "$PW" | wallet-cli asset participate 1000124 --pay 100 \
+  --wait --password-stdin --network tron:nile
+```
+
+Check what you would get before committing:
+
+```bash
+echo "$PW" | wallet-cli asset participate 1000124 --pay 100 \
+  --dry-run --password-stdin --network tron:nile
+```
+
+## Errors
+
+| Code | Meaning |
+|---|---|
+| `asset_not_found` | No TRC10 matches that id or name |
+| `ambiguous_asset_name` | The name matches several tokens; `details.assetIds` lists them |
+| `not_in_ico_window` | The funding window has not opened, or has closed |
+| `self_participation` | An issuer cannot buy into its own ICO |
+| `invalid_value` | `--pay` is not positive, or too small to buy one unit |
+| `ledger_unsupported` | The account is Ledger-backed; use a software account |
+| `watch_only_no_signer` | The account cannot sign |
+| `transaction_rejected` | The node refused it — e.g. the issuer has run out of sellable supply |
+
+## See also
+
+[`asset info`](info.md) · [`exchange trade`](../exchange/trade.md) · [`asset` group](index.md)