tronprotocol · gummy789j · Sep 18, 2026 · Sep 18, 2026 · Sep 18, 2026 · Sep 18, 2026
diff --git a/README.md b/README.md
@@ -26,10 +26,10 @@ 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` + `cd wallet-cli/java && ./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 <command>` from your shell. Prompts appear only on a short allowlist (`create`, `import *`, `backup`, `change-password`, `delete`); every other command errors instead of asking.                                                                                                                                               |
+| **How you drive it**   | An **interactive prompt only** — start it, then type commands at `>`.                                                          | **One-shot subcommands** — `wallet-cli <command>` 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` 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.                                                                                                                                           |
+| **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, Base, and their testnets.                                                                                                                                           |
 | **Signing**            | Software keystore · Ledger.                                                                                                    | Encrypted local keystore · Ledger. Secrets enter via stdin/TTY, never argv or dedicated secret environment variables.                                                                                                                                       |
 | **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.                                                                                                                                                                                                                     |

diff --git a/java/README.md b/java/README.md
@@ -46,7 +46,7 @@ You can also switch networks at runtime with the [`SwitchNetwork`](docs/commands
     $ java -jar wallet-cli.jar
     ```
 
-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.
+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 copy bundled into the jar at build time (`java/src/main/resources/config.conf`). Use `SwitchNetwork` to switch among mainnet, testnets (Nile and Shasta), and custom networks.
 
 ## Quickstart
 

diff --git a/java/docs/commands/account.md b/java/docs/commands/account.md
@@ -4,11 +4,11 @@ Query and update on-chain accounts, manage account metadata, and view local reco
 
 ## 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**.
+You can create accounts by transferring funds to non-existing accounts, or by initiating a transaction to create an account using the **CreateAccount** command. Either way the payer covers an on-chain account-creation fee, which is the sum of two chain parameters — `getCreateAccountFee` and `getCreateNewAccountFeeInSystemContract`. On mainnet today that is 100,000 SUN + 1,000,000 SUN = **1.1 TRX**, but both are proposal-adjustable, so read them with `getchainparameters` instead of assuming a fixed value.
 
 ## CreateAccount
 
-Create a new account with an inactive address, burning a 1-TRX handling fee for it.
+Create a new account with an inactive address. The payer covers the account-creation fee described above (about 1.1 TRX on mainnet today, `getCreateAccountFee` + `getCreateNewAccountFeeInSystemContract`).
 
 ```console
 > CreateAccount [OwnerAddress] Address

diff --git a/java/docs/commands/exchange.md b/java/docs/commands/exchange.md
@@ -50,15 +50,15 @@ Capital injection. When conducting a capital injection, depending on its quantit
 - `OwnerAddress` (optional) — the address of the account which initiated the transaction. Default: the address of the login account.
 - `exchange_id` — ID of the trading pair.
 - `token_id`, `quant` — the ID and quantity of tokens being exchanged, equivalent to selling.
-- `expected` — expected quantity of another token. `expected` must be less than `quant`, or an error will be reported.
+- `expected` — the **minimum quantity of the other token** you are willing to receive, in that token's base unit. It is a slippage floor, not a price: the chain computes the real output along the pair's bonding curve and rejects the transaction if it would come out below `expected`. It is denominated in a different token than `quant`, so the two are not comparable — `expected` is not required to be smaller than `quant`. It must be greater than 0.
 
 Example:
 
 ```console
 > ExchangeTransaction 1 1000001 100 80
 ```
 
-It is expected to acquire 80 TRX by exchanging 1000001 from the trading pair with ID 1, and the amount is 100. (Equivalent to selling an amount of 100 tokenID - 1000001, at a price of 80 TRX, in trading pair ID - 1.)
+Sells 100 base units of token 1000001 into trading pair 1, and requires at least 80 base units of the pair's other token in return. If the curve would return less than 80 at that moment, the transaction fails and nothing is sold. The `80` is a floor on the amount received, not a price.
 
 ## ExchangeWithdraw
 

diff --git a/java/docs/commands/stake-v2.md b/java/docs/commands/stake-v2.md
@@ -107,14 +107,15 @@ wallet> GetTransactionById dcfea1d92fc928d24c88f7f71a03ae8105d0b5b112d6d48be93d3
 ### DelegateResource
 
 ```console
-> delegateResource [OwnerAddress] balance ResourceCode(0 BANDWIDTH,1 ENERGY), ReceiverAddress [lock]
+> delegateResource [OwnerAddress] balance ResourceCode(0 BANDWIDTH,1 ENERGY), ReceiverAddress [lock] [lockPeriod]
 ```
 
 - `OwnerAddress` — the address of the account that initiated the transaction, optional, default is the address of the login account.
 - `balance` — the amount of delegate, the unit is the smallest unit (Sun), the minimum is 1000000 sun.
 - `ResourceCode` — 0 BANDWIDTH; 1 ENERGY.
 - `ReceiverAddress` — the address of the account.
-- `lock` — default is false, set true if you need to lock the delegate for 3 days.
+- `lock` — default is false, set true to lock the delegation so it cannot be reclaimed before the lock period ends.
+- `lockPeriod` — optional, only meaningful with `lock true`. The lock length **in blocks** (one block ≈ 3 seconds), so 28800 is one day. Omit it to use the chain's default lock period of 3 days.
 
 Example:
 

diff --git a/java/docs/commands/transfer-trc10.md b/java/docs/commands/transfer-trc10.md
@@ -154,14 +154,14 @@ Participate in the issuance of a TRC10 token.
 - `OwnerAddress` (optional) — the address of the account which initiated the transaction. Default: the address of the login account.
 - `ToAddress` — account address of TRC10 issuers.
 - `AssetID` — TRC10 token ID. Example: 1000001.
-- `Amount` — the number of TRC10 token to transfer.
+- `Amount` — the amount of **TRX you spend**, in SUN. It is *not* the number of tokens you receive: the tokens credited to you are `Amount / TrxNum * AssetNum` at the rate fixed when the token was issued, rounded down to a whole base unit. The TRX is transferred in full, so a truncated remainder is not refunded.
 
 The participation process must happen during the release of TRC10, otherwise an error may occur.
 
 Example:
 
 ```console
-> ParticipateAssetIssue TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ 1000001 1000
+> ParticipateAssetIssue TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ 1000001 1000  # spend 1000 SUN
 > getaccount TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW  # View remaining balance
 {
   "address": "TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW",
@@ -175,6 +175,8 @@ Example:
 }
 ```
 
+The 1000 SUN spent above buys 1000 base units only because this token was issued at a rate of `TrxNum` 1 : `AssetNum` 1. At a rate of `TrxNum` 2 : `AssetNum` 1, the same 1000 SUN would credit 500. Query the rate with [`getAssetIssueById`](#how-to-obtain-trc10-token-information) before participating.
+
 ### ListAssetIssuePaginated
 
 Query the list of all the tokens by pagination. Returns a list of tokens that succeed the token located at offset.

diff --git a/java/docs/commands/vote-reward.md b/java/docs/commands/vote-reward.md
@@ -86,7 +86,7 @@ After each block is produced, the block award is sent to the account's allowance
 
 ## How to create witness
 
-Applying to become a witness account needs to consume **100_000 TRX**. This part of the funds will be burned directly.
+Applying to become a witness account burns a registration fee — currently about **9,999 TRX**. The exact amount is the chain parameter `getAccountUpgradeCost`, which the network can change by proposal, so read it with `getchainparameters` rather than assuming a fixed value. The fee is burned outright and is not refundable; there is no way to unregister.
 
 ### CreateWitness
 

diff --git a/java/docs/commands/wallet.md b/java/docs/commands/wallet.md
@@ -38,7 +38,7 @@ wallet> ExportWalletMnemonic
 Please input your password.
 password:
 exportWalletMnemonic  successful !!
-alert twist correct matter pass gather pit position stop empty coconut abandon
+a*ert tw*st co*rect mat*er pa*s g*ther p*t p*sition s*op em*ty coc*nut aband*n
 ```
 
 ## ExportWalletKeystore

diff --git a/java/docs/concepts/index.md b/java/docs/concepts/index.md
@@ -4,7 +4,7 @@ Background on the TRON mechanics behind the commands. These are worth understand
 
 | Concept | What it covers |
 |---|---|
-| [Resources: bandwidth, energy & shares](resources.md) | How freezing produces resources, and how bandwidth is calculated |
+| [Resources: bandwidth, energy & TRON Power](resources.md) | What staking yields, and how bandwidth and energy are consumed and priced |
 | [Staking models: Stake 1.0 vs 2.0](staking-models.md) | The two freeze generations and which commands belong to each |
 | [Multi-signature concepts](multisig.md) | Permission types, keys, weights, and thresholds |
 

diff --git a/java/docs/concepts/resources.md b/java/docs/concepts/resources.md
@@ -1,29 +1,49 @@
-# Resources: bandwidth, energy & shares
+# Resources: bandwidth, energy & TRON Power
 
-TRON accounts obtain resources by freezing (staking) TRX. This page collects the mechanics that the operation pages refer to.
+TRON accounts obtain resources by **staking** TRX with `freezeBalanceV2` (Stake 2.0). This page collects the mechanics that the operation pages refer to. For the commands themselves, see [commands/stake-v2](../commands/stake-v2.md).
 
-## Shares and bandwidth from freezing
+## What staking gives you
 
-After funds are frozen, the corresponding number of shares and bandwidth is obtained. Shares can be used for voting and bandwidth can be used for trading.
+| Resource | Consumed by | Obtained by |
+|---|---|---|
+| **Bandwidth** | every transaction you broadcast, in proportion to its size | staking for `BANDWIDTH` (ResourceCode 0), plus a free daily allowance |
+| **Energy** | smart-contract execution only, including TRC20 transfers | staking for `ENERGY` (ResourceCode 1) |
+| **TRON Power** | [voting](../commands/vote-reward.md#how-to-vote) for super representatives | staking for `TRON_POWER` (ResourceCode 2) — 1 TRX staked = 1 vote |
 
-- **Share** — 1 unit of share can be obtained for every 1 TRX frozen. Shares are used for [voting](../commands/vote-reward.md#how-to-vote). After unfreezing, a previous vote will expire.
-- **Bandwidth** — consumed by contracts (transfers, asset transfers, voting, freezing, etc.). Querying does not consume bandwidth.
+Staked TRX remains yours; it is locked, not spent. Unstaking (`unfreezeBalanceV2`) drops the resources immediately and puts the TRX into a waiting period before it can be withdrawn, and votes cast with unstaked TRON Power expire.
 
-## How to calculate bandwidth
+Queries (`getaccount`, `getblock`, and the rest) are node reads, not transactions, and consume nothing.
 
-The bandwidth calculation rule is:
+## How bandwidth is consumed
+
+A transaction consumes bandwidth equal to the **size of the signed transaction in bytes** — a plain TRX transfer runs a few hundred. There is no fixed per-transaction figure; a transaction with more signatures or a memo is bigger and costs more.
+
+The node draws on three sources in order:
+
+1. The **free daily allowance** — the chain parameter `getFreeNetLimit`, 600 bytes/day on mainnet today. TRC10 transfers may draw on the issuer's `free_asset_net_limit` first.
+2. **Staked bandwidth**, which regenerates over 24 hours.
+3. Whatever is still uncovered is paid by **burning TRX**, at `getTransactionFee` — 1,000 SUN per byte on mainnet today.
+
+Energy works the same way at the third step, burning at `getEnergyFee` (100 SUN per energy on mainnet today), but has no free allowance: an account with no staked energy pays for every contract call in TRX.
+
+## How much bandwidth or energy a stake yields
+
+Staking does not buy a fixed amount. Each resource is a **fixed network-wide pool split in proportion to what everyone has staked**:
 
 ```
-constant * FrozenFunds * days
+your bandwidth = getTotalNetLimit           * yourBandwidthStake / totalBandwidthStaked
+your energy    = getTotalEnergyCurrentLimit * yourEnergyStake    / totalEnergyStaked
 ```
 
-Assuming freeze of 1 TRX (1_000_000 Sun) for 3 days, bandwidth obtained = 1 * 1_000_000 * 3 = 3_000_000.
+On mainnet today those pools are 43,200,000,000 bandwidth and 180,000,000,000 energy. Because the denominator is everyone else's stake, the same stake yields less as the network stakes more — check what you actually hold with `getaccountresource` rather than computing an expected figure.
+
+Every value named above is a chain parameter that super representatives can change by proposal. Read the current ones with [`GetChainParameters`](../commands/chain-data.md#getchainparameters); do not hardcode them.
 
-All contracts consume bandwidth, including transferring, transferring of assets, voting, freezing, etc. Querying does not consume bandwidth. Each contract needs to consume **100_000 bandwidth**.
+## Stake 1.0: how this used to work
 
-If a contract exceeds a certain time (**10s**), this operation does not consume bandwidth.
+Before Stake 2.0, `freezeBalance` took a `frozen_duration` (3 days) and each freeze was a separate position tied to that duration, unfrozen individually once it expired. Descriptions of bandwidth as `constant * frozen amount * days` come from that model.
 
-When the unfreezing operation occurs, the bandwidth is not cleared. The next time the freeze is performed, the newly added bandwidth is accumulated.
+`freezeBalanceV2` no longer accepts a duration — it takes only an amount and a resource type — and the proportional-share rules above are what applies now. The Stake 1.0 commands remain available for unwinding old positions; see [commands/stake-v1-legacy](../commands/stake-v1-legacy.md).
 
 ## Resource prices
 

diff --git a/java/docs/concepts/staking-models.md b/java/docs/concepts/staking-models.md
@@ -6,7 +6,7 @@ wallet-cli supports two generations of the TRON staking mechanism. New usage sho
 
 The original model, driven by `freezeBalance` / `unfreezeBalance`:
 
-- Freezing specifies a `frozen_duration`, currently only allowed to be **3 days**.
+- Freezing specifies a `frozen_duration`, currently only allowed to be **3 days**. Stake 2.0 dropped the parameter entirely — `freezeBalanceV2` takes only an amount and a resource type.
 - After the freezing time expires, funds can be unfrozen; when the unfreezing operation occurs, bandwidth is not cleared.
 - Resource delegation is expressed through the optional `receiverAddress` parameter of the same freeze/unfreeze commands.
 
@@ -17,7 +17,7 @@ See [commands/stake-v1-legacy](../commands/stake-v1-legacy.md).
 The current model, driven by `freezeBalanceV2` / `unfreezeBalanceV2`, with resource delegation and an explicit unbonding/withdrawal flow:
 
 - `freezeBalanceV2` stakes TRX for BANDWIDTH, ENERGY, or TRON_POWER.
-- `delegateResource` / `unDelegateResource` delegate resources to another account (optionally locked for 3 days).
+- `delegateResource` / `unDelegateResource` delegate resources to another account, optionally locked — `lockPeriod` sets the lock length in blocks, defaulting to the chain's 3 days.
 - `unfreezeBalanceV2` begins unbonding; `withdrawExpireUnfreeze` withdraws the amount once it has expired; `cancelAllUnfreezeV2` cancels pending unfreezes.
 - Dedicated v2 query commands report delegation state and available/withdrawable amounts.