diff --git a/.github/workflows/build-artifact.yml b/.github/workflows/build-artifact.yml index 9b50bb6f..78a911d0 100644 --- a/.github/workflows/build-artifact.yml +++ b/.github/workflows/build-artifact.yml @@ -26,6 +26,7 @@ jobs: cache: gradle - name: Build + working-directory: java run: ./gradlew clean build shadowJar shadowDistZip - name: Package artifacts @@ -43,8 +44,8 @@ jobs: artifact_name="wallet-cli-artifact-${GITHUB_REF_NAME}" mkdir -p "$artifact_dir" - cp build/libs/wallet-cli.jar "$artifact_dir/${artifact_base}.jar" - cp build/distributions/*shadow*.zip "$artifact_dir/${artifact_base}.zip" + cp java/build/libs/wallet-cli.jar "$artifact_dir/${artifact_base}.jar" + cp java/build/distributions/*shadow*.zip "$artifact_dir/${artifact_base}.zip" git rev-parse HEAD > "$artifact_dir/git-sha.txt" echo "ARTIFACT_NAME=${artifact_name}" >> "$GITHUB_ENV" diff --git a/.gitignore b/.gitignore index 83de291e..171f9818 100644 --- a/.gitignore +++ b/.gitignore @@ -1,43 +1,20 @@ -.claude/settings.local.json +# Per-implementation ignores live in java/.gitignore and ts/.gitignore. +# Only repo-wide patterns belong here. + +# OS / editor / IDE .DS_Store -build -out .idea -.gradle +.vscode/ +# Eclipse JDT / VS Code Java language server output +/bin/ + +# Tooling node_modules -src/main/genjs/api -src/main/genjs/core -src/genjs -src/gen tools -src/main/resources/static/js/tronjs/tron-protoc.js -logs -docs -!docs/ -!docs/standard-cli-contract-spec.md -FileTest -bin - -# Wallet keystore files created at runtime -/Wallet/ -/Mnemonic/ -/wallet_data/ - -# QA runtime output -qa/results/ -qa/runtime/ -qa/report.txt -qa/.verify.lock/ +graphify-out/ -# claude +# Claude .claude/ +.claude/settings.local.json .private/ - -# graphify -graphify-out/ -.vscode/ -docs/superpowers - - -/ts-deprecated/ \ No newline at end of file diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index a32ec9a5..00000000 --- a/.travis.yml +++ /dev/null @@ -1,8 +0,0 @@ ---- -sudo: required -language: java -jdk: oraclejdk8 -dist: trusty - -script: - - ./gradlew build \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index 67bc9fcb..c579946e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,6 +2,68 @@ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +## Repository Layout + +The repository holds two independent implementations: + +- `java/` — the original REPL-first implementation, described by the rest of this file. +- `ts/` — the agent-first TypeScript rewrite (npm package `@tron-walletcli/wallet-cli`). See the + **TypeScript Implementation** section below and `ts/README.md`. + +Everything below (except the TypeScript Implementation section) refers to the Java implementation. +**All Java paths are relative to `java/`, and all Java commands are run from that directory** +(`cd java` first). + +## TypeScript Implementation + +The `ts/` package is a self-contained, agent-first CLI (Node.js 20+, ESM, TypeScript). Every command +has a stable JSON envelope, deterministic exit codes, and discoverable schemas; interactive prompts +are used only for secret input (create / import / backup / delete). **All `ts/` commands run from the +`ts/` directory.** + +```bash +cd ts +npm ci # install +npm run build # bundle to dist/ via tsup (bin: wallet-cli -> dist/index.js) +npm run dev -- # run from source via tsx (e.g. npm run dev -- create --label main) +npm test # vitest (tests are co-located as *.test.ts) +npm run typecheck # tsc --noEmit +npm run depcruise # dependency-cruiser — enforces the architecture rules below +``` + +### Architecture (hexagonal / ports & adapters) + +Dependencies point inward. The source of truth is +`ts/docs/typescript-wallet-cli-architecture-source-of-truth.md` — read it before changing +boundaries, ports, command routing, or the JSON contract. `depcruise` enforces these rules in CI. + +| Area (`ts/src/…`) | Role | May depend on | Must NOT depend on | +|---|---|---|---| +| `domain` | Pure rules & values, zero I/O (address, amounts, derivation, wallet, family, errors) | Node / pure libs only | application, adapters, bootstrap | +| `application` | Use cases, services, contracts, and **ports** (interfaces it owns) | `domain` | adapters, bootstrap | +| `adapters/inbound` | CLI driving side — parse argv, route to use cases, render output | application, domain | adapters/outbound, bootstrap | +| `adapters/outbound` | Implements application ports — keystore, TronWeb/Tron gateway, Ledger, price, config, persistence | application ports, domain | adapters/inbound, bootstrap | +| `bootstrap` | Composition root + process lifecycle (`runner.ts`, `composition.ts`, `argv.ts`, `families/`) | all areas | — (assembly only) | + +Key points: +- **Ports live in `application/ports/`** (e.g. `wallet-repository`, `tron-gateway`, `ledger-device`, + `price-provider`); outbound adapters implement them (dependency inversion). +- **Chain-family differences** are isolated in the `tron` family — `application/use-cases/tron/`, + `adapters/outbound/chain/tron/`, and the family plugin under `bootstrap/families/`. EVM is planned, + not yet public. +- **A single Zod schema per command** drives validation, yargs arity, help text, and JSON Schema. +- **Secrets** (private keys, mnemonics, BIP39 passphrases) are encrypted at rest and never accepted + from argv or env — only a dedicated stdin channel or hidden TTY prompt. + +### Adding a TypeScript command + +1. Add the command module under `adapters/inbound/cli/commands/` with its Zod schema. +2. Route it to an application use case (`application/use-cases/…`, e.g. `tron/transaction-service.ts`); + do not put I/O or chain logic in the inbound layer. +3. If it needs new I/O, define a **port** in `application/ports/` and implement it in + `adapters/outbound/`. Wire it in `bootstrap/composition.ts`. +4. Add co-located `*.test.ts` and run `npm run depcruise && npm run typecheck && npm test`. + ## Build & Run ```bash @@ -49,7 +111,7 @@ This is a **TRON blockchain CLI wallet** built on the [Trident SDK](https://gith ### Two CLI Modes -1. **REPL 交互模式** (human-friendly) — `Client` class with JCommander `@Parameters` inner classes. Entry point: `org.tron.walletcli.Client`. Features tab completion, interactive prompts, and conversational output. This is the largest file (~4700 lines). Best for manual exploration and day-to-day wallet management by humans. +1. **REPL 交互模式** (human-friendly) — `Client` class with JCommander `@Parameters` inner classes. Entry point: `org.tron.walletcli.Client`. Features tab completion, interactive prompts, and conversational output. This is the largest file (~4900 lines). Best for manual exploration and day-to-day wallet management by humans. 2. **Standard CLI 模式** (AI-agent-friendly) — `StandardCliRunner` with `CommandRegistry`/`CommandDefinition` pattern in `org.tron.walletcli.cli.*`. Supports `--output json`, `--network`, `--quiet` flags. Commands are registered in `cli/commands/` classes (e.g., `WalletCommands`, `TransactionCommands`, `QueryCommands`). Designed for automation: deterministic exit codes, structured JSON output, no interactive prompts, and env-var-based authentication — ideal for AI agents, scripts, and CI/CD pipelines. The standard CLI suppresses all stray stdout/stderr in JSON mode to ensure machine-parseable output. Authentication is automatic via `MASTER_PASSWORD` env var + keystore files in `Wallet/`. @@ -59,7 +121,7 @@ The standard CLI suppresses all stray stdout/stderr in JSON mode to ensure machi Before changing parser behavior, auth flow, JSON output, command success/failure semantics, or `qa/` expectations for the standard CLI, read: -- `docs/standard-cli-contract-spec.md` +- `java/docs/standard-cli-contract-spec.md` Treat that file as the source of truth for the standard CLI contract unless the repository owner explicitly decides to revise it. @@ -116,9 +178,9 @@ User Input → Client (JCommander) → WalletApiWrapper → WalletApi → Triden ### Key Frameworks & Libraries -- **Trident SDK 0.10.0** — All gRPC API calls to TRON nodes +- **Trident SDK 0.11.0** — All gRPC API calls to TRON nodes - **JCommander 1.82** — CLI argument parsing (REPL 交互模式) - **JLine 3.25.0** — Interactive terminal/readline - **BouncyCastle** — Cryptographic operations -- **Protobuf 3.25.5 / gRPC 1.60.0** — Protocol definitions and transport +- **Protobuf 3.25.8 / gRPC 1.75.0** — Protocol definitions and transport - **Lombok** — `@Getter`, `@Setter`, `@Slf4j` etc. (annotation processing) diff --git a/FETCH_HEAD b/FETCH_HEAD deleted file mode 100644 index e69de29b..00000000 diff --git a/README.md b/README.md index f4b5aa70..5330fafc 100644 --- a/README.md +++ b/README.md @@ -1,2725 +1,76 @@ -# Wallet-cli +

wallet-cli

-Welcome to use the Wallet-cli. +

+ A command-line wallet for the TRON network — interactive in Java, agent-first in TypeScript +

-Wallet-cli now supports [GasFree](https://gasfree.io) addresses, enable users to transfer tokens without paying gas fees. For more details, please check the [GasFree](#Gas-Free-Support) section below. +

+ + + + + +

-The underlying implementation of all Wallet-cli gRPC APIs has all migrated to the [Trident SDK](https://github.com/tronprotocol/trident). This strategic move consolidates the underlying implementation of the Wallet-cli's remote procedure calls, standardizing them under the robust and optimized Trident framework. +This repository holds **two independent implementations** that share the same purpose but target different users: -If you need any help, please join the [Telegram](https://t.me/TronOfficialDevelopersGroupEn). +- **[Java](java/README.md)** — the original, full-featured reference CLI. An interactive prompt (REPL) for people who want the complete TRON feature surface. +- **[TypeScript](ts/README.md)** — an agent-first rewrite for automation. Standard subcommands with a stable JSON envelope, built for scripts, CI, and AI agents. -## Get started +Both manage the same kind of wallet on the same networks — your address is identical regardless of which you use. They differ in how you install and drive them, and in how much of TRON they cover. Pick one and read its own README for depth; this page gives you the basics of each so you can choose. -### Download Wallet-cli +## At a glance - git clone https://github.com/tronprotocol/wallet-cli.git +| | [**Java**](java/README.md) — the original | [**TypeScript**](ts/README.md) — agent-first rewrite | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **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. | +| **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`. | +| **Signing** | Software keystore · Ledger. | Encrypted local keystore · Ledger. Secrets never via argv/env. | +| **Feature scope** | **The full surface** — plus GasFree gas-less transfers, TRC10 token issuance, on-chain DEX & governance/proposals, and TronLink multi-sig. | **Core wallet ops** — HD wallets, TRX/TRC20/TRC10 transfers, staking & delegation, voting & rewards, contract call/deploy, message signing, and on-chain queries. | +| **Best for** | People at a terminal who want every TRON capability. | Scripting, CI pipelines, and AI agents. | +| **Full docs** | [java/README.md](java/README.md) | [ts/README.md](ts/README.md) | -### Edit config.conf in src/main/resources +## Java — get a taste -``` -net { - type = mainnet -} - -fullnode = { - ip.list = [ - "fullnode ip : port" - ] -} - -#soliditynode = { -# //The IPs in this list can only be totally set to solidity. -# ip.list = [ -# "ip : solidity port" // default solidity -# ] -# // NOTE: solidity node is optional -#} - -# open ledger debug -# ledger_debug = true - -# To use the lock and unlock function of the login account, it is necessary to configure -# lockAccount = true in the config.conf. The current login account is locked, which means that -# signatures and transactions are not allowed. After the current login account is locked, it can be -# unlocked. By default, it will be unlocked again after 300 seconds. Unlocking can specify -# parameters in seconds. - -# lockAccount = true - -# To use the gasfree feature, please first apply for an APIkey and apiSecret. -# For details, please refer to -# https://docs.google.com/forms/d/e/1FAIpQLSc5EB1X8JN7LA4SAVAG99VziXEY6Kv6JxmlBry9rUBlwI-GaQ/viewform -gasfree = { - mainnet = { - apiKey = "" - apiSecret = "" - } - testnet = { - apiKey = "" - apiSecret = "" - } -} - -# If gRPC requests on the main network are limited in speed, you can apply for an apiKey of Trongrid to improve the user experience -grpc = { - mainnet = { - apiKey = "" - } -} - -# Set the maximum number of transactions and backup records that can be retained -maxRecords = 1000 - -# To use the tronlink multi-sign feature, please first apply for an secretId and secretKey. -# For details, please refer to -# https://docs.google.com/forms/d/e/1FAIpQLSc5EB1X8JN7LA4SAVAG99VziXEY6Kv6JxmlBry9rUBlwI-GaQ/viewform -# If you prefer not to apply, a speed-limited secretId and secretKey will be provided for use: -# secretId = "TEST", secretKey = "TESTTESTTEST", channel = "test". -tronlink = { - mainnet = { - secretId = "" - secretKey = "" - channel = "" - } - testnet = { - secretId = "" - secretKey = "" - channel = "" - } -} -``` - -### Run a web wallet - -- connect to fullNode - - Take a look at: [java-tron deployment](https://tronprotocol.github.io/documentation-en/developers/deployment/) - Run fullNode on either your local PC or a remote server. - -- compile and run web wallet - - ```console - $ cd wallet-cli - $ ./gradlew build - $ cd build/libs - $ java -jar wallet-cli.jar - ``` - -### Connect to Java-tron - -Wallet-cli connects to Java-tron via the gRPC protocol, which can be deployed locally or remotely. Check **Run a web Wallet** section. -We can configure Java-tron node IP and port in ``src/main/resources/config.conf``, so that wallet-cli server can successfully talk to java-tron nodes. -Besides that, you can simply use `SwitchNetwork` command to switch among the mainnet, testnets(Nile and Shasta) and custom networks. Please refer to the Switch Network section. - -## Wallet-cli supported command list - -Following is a list of Tron Wallet-cli commands: -For more information on a specific command, just type the command in the terminal when you start your Wallet. - -| [AddTransactionSign](#How-to-use-the-multi-signature-feature-of-wallet-cli) | [AddressBook](#address-book) | [ApproveProposal](#Approve--disapprove-a-proposal) | -|:--------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------:|:-----------------------------------------------------------------------------------:| -| [AssetIssue](#Issue-trc10-tokens) | [BackupWallet](#Wallet-related-commands) | [BackupWallet2Base64](#Wallet-related-commands) | -| [BroadcastTransaction](#Some-others) | [CancelAllUnfreezeV2](#How-to-freezev2) | [ChangePassword](#Wallet-related-commands) | -| [ClearContractABI](#clear-contract-abi) | [ClearWalletKeystore](#clear-wallet-keystore) | [Create2](#create2) | -| [CreateAccount](#create-account) | [CreateProposal](#Initiate-a-proposal) | [CreateWitness](#create-witness) | -| [CurrentNetwork](#current-network) | [DelegateResource](#How-to-freezev2) | [DeleteProposal](#Delete-an-existed-proposal) | -| [DeployContract](#How-to-use-smart-contract) | [EstimateEnergy](#estimate-energy) | [ExchangeCreate](#How-to-trade-on-the-exchange) | -| [ExchangeInject](#How-to-trade-on-the-exchange) | [ExchangeTransaction](#How-to-trade-on-the-exchange) | [ExchangeWithdraw](#How-to-trade-on-the-exchange) | -| [ExportWalletKeystore](#export-import-wallet-keystore) | [ExportWalletMnemonic](#import-and-export-mnemonic) | [FreezeBalance](#Delegate-resource) | -| [FreezeBalanceV2](#How-to-freezev2) | [GasFreeInfo](#gas-free-info) | [GasFreeTrace](#gas-free-trace) | -| [GasFreeTransfer](#gas-free-transfer) | [GenerateAddress](#Account-related-commands) | [GenerateSubAccount](#generate-sub-account) | -| [GetAccount](#Account-related-commands) | [GetAccountById](#get-account-by-id) | [GetAccountNet](#Account-related-commands) | -| [GetAccountResource](#Account-related-commands) | [GetAddress](#Account-related-commands) | [GetAssetIssueByAccount](#How-to-obtain-trc10-token-information) | -| [GetAssetIssueById](#How-to-obtain-trc10-token-information) | [GetAssetIssueByName](#How-to-obtain-trc10-token-information) | [GetAssetIssueListByName](#How-to-obtain-trc10-token-information) | -| [GetAvailableUnfreezeCount](#How-to-freezev2) | [GetBalance](#Account-related-commands) | [GetBandwidthPrices](#Get-resource-prices-and-memo-fee) | -| [GetBlock](#How-to-get-block-information) | [GetBlockById](#How-to-get-block-information) | [GetBlockByIdOrNum](#How-to-get-block-information) | -| [GetBlockByLatestNum](#How-to-get-block-information) | [GetBlockByLimitNext](#How-to-get-block-information) | [GetBrokerage](#Brokerage) | -| [GetCanDelegatedMaxSize](#How-to-freezev2) | [GetCanWithdrawUnfreezeAmount](#How-to-freezev2) | [GetChainParameters](#get-chain-parameters) | -| [GetContract](#Get-details-of-a-smart-contract) | [GetContractInfo](#get-info-of-a-smart-contract) | [GetDelegatedResource](#How-to-delegate-resource) | -| [GetDelegatedResourceAccountIndex](#How-to-delegate-resource) | [GetDelegatedResourceAccountIndexV2](#How-to-freezev2) | [GetDelegatedResourceV2](#How-to-freezev2) | -| [GetEnergyPrices](#Get-resource-prices-and-memo-fee) | [GetExchange](#get-exchange-by-id) | [GetMarketOrderByAccount](#How-to-use-tron-dex-to-sell-asset) | -| [GetMarketOrderById](#How-to-use-tron-dex-to-sell-asset) | [GetMarketOrderListByPair](#How-to-use-tron-dex-to-sell-asset) | [GetMarketPairList](#How-to-use-tron-dex-to-sell-asset) | -| [GetMarketPriceByPair](#How-to-use-tron-dex-to-sell-asset) | [GetMemoFee](#Get-resource-prices-and-memo-fee) | [GetNextMaintenanceTime](#Some-others) | -| [GetProposal](#Obtain-proposal-information) | [GetReward](#Brokerage) | [GetTransactionApprovedList](#How-to-use-the-multi-signature-feature-of-wallet-cli) | -| [GetTransactionById](#How-to-get-transaction-information) | [GetTransactionCountByBlockNum](#How-to-get-transaction-information) | [GetTransactionInfoByBlockNum](#How-to-get-transaction-information) | -| [GetTransactionInfoById](#How-to-get-transaction-information) | [GetTransactionSignWeight](#How-to-use-the-multi-signature-feature-of-wallet-cli) | [GetUSDTBalance](#get-usdt-balance) | -| [GetUsdtTransferById](#get-usdt-transfer-by-id) | [ImportWallet](#Wallet-related-commands) | [ImportWalletByBase64](#Wallet-related-commands) | -| [ImportWalletByKeystore](#export-import-wallet-keystore) | [ImportWalletByLedger](#import-wallet-by-ledger) | [ImportWalletByMnemonic](#import-and-export-mnemonic) | -| [ListAssetIssue](#How-to-obtain-trc10-token-information) | [ListAssetIssuePaginated](#list-asset-issue-paginated) | [ListExchanges](#How-to-trade-on-the-exchange) | -| [ListExchangesPaginated](#How-to-trade-on-the-exchange) | [ListNodes](#Some-others) | [ListProposals](#Obtain-proposal-information) | -| [ListProposalsPaginated](#Obtain-proposal-information) | [ListWitnesses](#Some-others) | [Lock](#lock) | -| [Login](#Command-line-operation-flow-example) | [LoginAll](#login-all) | [Logout](#logout) | -| [MarketCancelOrder](#How-to-use-tron-dex-to-sell-asset) | [MarketSellAsset](#How-to-use-tron-dex-to-sell-asset) | [ModifyWalletName](#Modify-wallet-name) | -| [ParticipateAssetIssue](#Participating-in-the-issue-of-trc10-token) | [RegisterWallet](#Wallet-related-commands) | [ResetWallet](#reset-wallet) | -| [SendCoin](#How-to-use-the-multi-signature-feature-of-wallet-cli) | [SetAccountId](#set-account-id) | [ShowReceivingQrCode](#show-receiving-qr-code) | -| [SwitchNetwork](#switch-network) | [SwitchWallet](#switch-wallet) | [TransferAsset](#Trc10-token-transfer) | -| [TransferUSDT](#transfer-usdt) | [TriggerConstantContract](#trigger-constant-contract) | [TriggerContract](#trigger-smart-contract) | -| [UnDelegateResource](#How-to-freezev2) | [UnfreezeAsset](#Unfreeze-trc10-token) | [UnfreezeBalance](#How-to-delegate-resource) | -| [UnfreezeBalanceV2](#How-to-freezev2) | [Unlock](#unlock) | [UpdateAccount](#update-account) | -| [UpdateAccountPermission](#How-to-use-the-multi-signature-feature-of-wallet-cli) | [UpdateAsset](#Update-parameters-of-trc10-token) | [UpdateBrokerage](#Brokerage) | -| [UpdateEnergyLimit](#Update-smart-contract-parameters) | [UpdateSetting](#Update-smart-contract-parameters) | [UpdateWitness](#update-witness) | -| [ViewBackupRecords](#View-backup-records) | [ViewTransactionHistory](#View-transaction-history) | [VoteWitness](#How-to-vote) | -| [WithdrawBalance](#withdraw-balance) | [WithdrawExpireUnfreeze](#withdraw-expire-unfreeze) | [TronlinkMultiSign](#tronlink-multi-sign) | -| [EncodingConverter](#encoding-converter) | [GetPrivateKeyByMnemonic](#How-to-get-privateKey-through-mnemonic) | [GetPaginatedNowWitnessList](#Get-paginated-now-witness-list) | - - -Type any one of the listed commands, to display how-to tips. - -## How to freeze/unfreeze balance - -After the funds are frozen, the corresponding number of shares and bandwidth will be obtained. -Shares can be used for voting and bandwidth can be used for trading. -The rules for the use and calculation of share and bandwidth are described later in this article. - -**Freeze operation is as follows:** - -```console -> freezeBalance [OwnerAddress] frozen_balance frozen_duration [ResourceCode:0 BANDWIDTH, 1 ENERGY] [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(1TRX)**. - -frozen_duration -> Freeze time, this value is currently only allowed for **3 days**. - -For example: - -```console -> freezeBalance 100000000 3 1 address -``` - -After the freeze operation, frozen funds will be transferred from Account Balance to Frozen, -You can view frozen funds from your account information. -After being unfrozen, it is transferred back to Balance by Frozen, and the frozen funds cannot be used for trading. - -When more share or bandwidth is needed temporarily, additional funds may be frozen to obtain additional share and bandwidth. -The unfrozen time is postponed until 3 days after the last freeze operation - -After the freezing time expires, funds can be unfroze. - -**Unfreeze operation is as follows:** - -```console -> unfreezeBalance [OwnerAddress] ResourceCode(0 BANDWIDTH, 1 ENERGY) [receiverAddress] -``` - -## How to vote - -Voting requires share. Share can be obtained by freezing funds. - -- The share calculation method is: **1** unit of share can be obtained for every **1TRX** frozen. -- After unfreezing, previous vote will expire. You can avoid the invalidation of the vote by re-freezing and voting. - -**NOTE** The Tron Network only records the status of your last vote, which means that each of your votes will overwrite all previous voting results. - -For example: - -```console -> freezeBalance 100000000 3 1 address # Freeze 10TRX 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 - -> votewitness 123455 witness1 10 # Voted 10 votes for witness1 -``` - -The final result of the above command was 10 votes for witness1 and 0 vote for witness2. - -## Brokerage - -After voting for the witness, you will receive the rewards. The witness has the right to decide the ratio of brokerage. The default ratio is 20%, and the witness can adjust it. - -By default, if a witness is rewarded, he will receive 20% of the whole rewards, and 80% of the rewards will be distributed to his voters. - -### GetBrokerage - -View the ratio of brokerage of the witness. - - > getbrokerage OwnerAddress - -OwnerAddress -> The address of the witness's account, it is a base58check type address. - -### GetReward - -Query unclaimed reward. - - > getreward OwnerAddress - -OwnerAddress -> The address of the voter's account, it is a base58check type address. - -### UpdateBrokerage - -Update the ratio of brokerage, this command is usually used by a witness account. - - > updateBrokerage OwnerAddress brokerage - -OwnerAddress -> The witness's account address is a base58check type address. - -brokerage -> The ratio of brokerage you want to update, from 0 to 100. If the input is 10, it means 10% of the total reward would be distributed to the SR and the rest would be rewarded to all the voters, which is 90% in this case - -For example: - -```console -> getbrokerage TZ7U1WVBRLZ2umjizxqz3XfearEHhXKX7h - -> getreward TNfu3u8jo1LDWerHGbzs2Pv88Biqd85wEY - -> updateBrokerage TZ7U1WVBRLZ2umjizxqz3XfearEHhXKX7h 30 -``` - -### withdraw balance - -> WithdrawBalance [owner_address] - -Withdraw voting or block rewards. - -Example: - -```console -> WithdrawBalance TEDapYSVvAZ3aYH7w8N9tMEEFKaNKUD5Bp -``` - -## How to calculate bandwidth - -The bandwidth calculation rule is: - - constant * FrozenFunds * days - -Assuming freeze 1TRX（1_000_000 Sun), 3 days, bandwidth obtained = 1 * 1_000_000 * 3 = 3_000_000. - -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**. - -If a contract exceeds a certain time (**10s**), this operation does not consume bandwidth. - -When the unfreezing operation occurs, the bandwidth is not cleared. -The next time the freeze is performed, the newly added bandwidth is accumulated. - -## How to withdraw balance - -After each block is produced, the block award is sent to the account's allowance, -and a withdraw operation is allowed every **24 hours** from allowance to balance. -The funds in allowance cannot be locked or traded. - -## How to create witness - -Applying to become a witness account needs to consume **100_000TRX**. -This part of the funds will be burned directly. - -### create witness -> CreateWitness [owner_address] url -Apply to become a super representative candidate. - -Example: -```console -> CreateWitness TEDapYSVvAZ3aYH7w8N9tMEEFKaNKUD5Bp 007570646174654e616d6531353330363038383733343633 -``` - -### update witness -> UpdateWitness -Edit the URL of the SR's official website. - -Example: -```console -> UpdateWitness TEDapYSVvAZ3aYH7w8N9tMEEFKaNKUD5Bp 007570646174654e616d6531353330363038383733343633 -``` - -## How to create account - -You can create accounts by transferring funds to non-existing accounts or initiating a transaction to create an account using the **CreateAccount** command. -Transferring to a non-existent account has minimum restriction amount of **1TRX**. -Creating an account through the CreateAccount command will still burn **1TRX**. - - -## Command line operation flow example - -```console -$ cd wallet-cli -$ ./gradlew build -$ ./gradlew run -> RegisterWallet 123456 (password = 123456) -> login 123456 -> getAddress -address = TRfwwLDpr4excH4V4QzghLEsdYwkapTxnm' # backup it! -> BackupWallet 123456 -priKey = 1234567890123456789012345678901234567890123456789012345678901234 # backup it!!! (BackupWallet2Base64 option) -> getbalance -Balance = 0 -> AssetIssue TestTRX TRX 75000000000000000 1 1 2 "2019-10-02 15:10:00" "2020-07-11" "just for test121212" www.test.com 100 100000 10000 10 10000 1 -> getaccount TRfwwLDpr4excH4V4QzghLEsdYwkapTxnm -(Print balance: 9999900000 -"assetV2": [ - { - "key": "1000001", - "value": 74999999999980000 - } -],) - # (cost trx 1000 trx for assetIssue) - # (You can query the trx balance and other asset balances for any account ) -> TransferAsset TWzrEZYtwzkAxXJ8PatVrGuoSNsexejRiM 1000001 10000 -``` - -## How to issue a TRC10 token - -Each account can only issue **ONE** TRC10 token. - -### Issue TRC10 tokens - -> AssetIssue [OwnerAddress] AssetName AbbrName TotalSupply TrxNum AssetNum Precision StartDate EndDate Description Url FreeNetLimitPerAccount PublicFreeNetLimit FrozenAmount0 FrozenDays0 [...] FrozenAmountN FrozenDaysN - -OwnerAddress (optional) -> The address of the account which initiated the transaction. -> Default: the address of the login account. - -AssetName -> The name of the issued TRC10 token - -AbbrName -> The abbreviation of TRC10 token - -TotalSupply -> TotalSupply = Account Balance of Issuer + All Frozen Token Amount -> TotalSupply: Total Issuing Amount -> Account Balance Of Issuer: At the time of issuance -> All Frozen Token Amount: Before asset transfer and the issuance - -TrxNum, AssetNum -> These two parameters determine the exchange rate when the token is issued. -> Exchange Rate = TrxNum / AssetNum -> AssetNum: Unit in base unit of the issued token -> TrxNum: Unit in SUN (0.000001 TRX) - -Precision -> Precision to how many decimal places - -FreeNetLimitPerAccount -> The maximum amount of bandwidth each account is allowed to use. Token issuers can freeze TRX to obtain bandwidth (TransferAssetContract only) - -PublicFreeNetLimit -> The maximum total amount of bandwidth which is allowed to use for all accounts. Token issuers can freeze TRX to obtain bandwidth (TransferAssetContract only) - -StartDate, EndDate -> The start and end date of token issuance. Within this period time, other users can participate in token issuance. - -FrozenAmount0 FrozenDays0 -> Amount and days of token freeze. -> FrozenAmount0: Must be bigger than 0 -> FrozenDays0: Must be between 1 and 3653. - -Example: - -```console -> AssetIssue TestTRX TRX 75000000000000000 1 1 2 "2019-10-02 15:10:00" "2020-07-11" "just for test121212" www.test.com 100 100000 10000 10 10000 1 -> GetAssetIssueByAccount TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ # View published information -{ - "assetIssue": [ - { - "owner_address": "TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ", - "name": "TestTRX", - "abbr": "TRX", - "total_supply": 75000000000000000, - "frozen_supply": [ - { - "frozen_amount": 10000, - "frozen_days": 1 - }, - { - "frozen_amount": 10000, - "frozen_days": 10 - } - ], - "trx_num": 1, - "precision": 2, - "num": 1, - "start_time": 1570000200000, - "end_time": 1594396800000, - "description": "just for test121212", - "url": "www.test.com", - "free_asset_net_limit": 100, - "public_free_asset_net_limit": 100000, - "id": "1000001" - } - ] -} -``` - -### Update parameters of TRC10 token - -> UpdateAsset [OwnerAddress] newLimit newPublicLimit description url - -Specific meaning of the parameters is the same as that of AssetIssue. - -Example: - -```console -> UpdateAsset 1000 1000000 "change description" www.changetest.com -> GetAssetIssueByAccount TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ # View the modified information -{ - "assetIssue": [ - { - "owner_address": "TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ", - "name": "TestTRX", - "abbr": "TRX", - "total_supply": 75000000000000000, - "frozen_supply": [ - { - "frozen_amount": 10000, - "frozen_days": 1 - }, - { - "frozen_amount": 10000, - "frozen_days": 10 - } - ], - "trx_num": 1, - "precision": 2, - "num": 1, - "start_time": 1570000200000, - "end_time": 1594396800000, - "description": "change description", - "url": "www.changetest.com", - "free_asset_net_limit": 1000, - "public_free_asset_net_limit": 1000000, - "id": "1000001" - } - ] -} -``` - -### TRC10 token transfer - -> TransferAsset [OwnerAddress] ToAddress AssertID Amount - -OwnerAddress (optional) -> The address of the account which initiated the transaction. -> Default: the address of the login account. - -ToAddress -> Address of the target account - -AssertName -> TRC10 token ID -> Example: 1000001 - -Amount -> The number of TRC10 token to transfer - -Example: - -```console -> TransferAsset TN3zfjYUmMFK3ZsHSsrdJoNRtGkQmZLBLz 1000001 1000 -> getaccount TN3zfjYUmMFK3ZsHSsrdJoNRtGkQmZLBLz # View target account information after the transfer -address: TN3zfjYUmMFK3ZsHSsrdJoNRtGkQmZLBLz - assetV2 - { - id: 1000001 - balance: 1000 - latest_asset_operation_timeV2: null - free_asset_net_usageV2: 0 - } -``` - -### Participating in the issue of TRC10 token - - > ParticipateAssetIssue [OwnerAddress] ToAddress AssetID Amount - -OwnerAddress (optional) -> The address of the account which initiated the transaction. -> Default: the address of the login account. - -ToAddress -> Account address of TRC10 issuers - -AssertName -> TRC10 token ID -> Example: 1000001 - -Amount -> The number of TRC10 token to transfers - -The participation process must happen during the release of TRC10, otherwise an error may occur. - -Example: - -```console -> ParticipateAssetIssue TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ 1000001 1000 -> getaccount TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW # View remaining balance -address: TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW -assetV2 - { - id: 1000001 - balance: 1000 - latest_asset_operation_timeV2: null - free_asset_net_usageV2: 0 - } -``` -### list asset issue paginated - -> ListAssetIssuePaginated address code salt - -Query the list of all the tokens by pagination.Returns a list of Tokens that succeed the Token located at offset. - -Example: - -```console -> ListAssetIssuePaginated 0 1 -``` - -### Unfreeze TRC10 token - -To unfreeze all TRC10 token which are supposed to be unfrozen after the freezing period. - - > unfreezeasset [OwnerAddress] - -## How to obtain TRC10 token information - -ListAssetIssue -> Obtain all of the published TRC10 token information - -GetAssetIssueByAccount -> Obtain TRC10 token information based on issuing address - -GetAssetIssueById -> Obtain TRC10 token Information based on ID - -GetAssetIssueByName -> Obtain TRC10 token Information based on names - -GetAssetIssueListByName -> Obtain a list of TRC10 token information based on names - -## How to operate with proposal - -Any proposal-related operations, except for viewing operations, must be performed by committee members. - -### Initiate a proposal - - > createProposal [OwnerAddress] id0 value0 ... idN valueN - -OwnerAddress (optional) -> The address of the account which initiated the transaction. -> Default: the address of the login account. - -id0 -> The serial number of the parameter. Every parameter of TRON network has a serial number. Please refer to "http://tronscan.org/#/sr/committee" - -Value0 -> The modified value - -In the example, modification No.4 (modifying token issuance fee) costs 1000TRX as follows: - -```console -> createProposal 4 1000 -> listproposals # View initiated proposal -{ - "proposals": [ - { - "proposal_id": 1, - "proposer_address": "TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ", - "parameters": [ - { - "key": 4, - "value": 1000 - } - ], - "expiration_time": 1567498800000, - "create_time": 1567498308000 - } - ] -} -``` - -The corresponding id is 1. - -### Approve / Disapprove a proposal - - > approveProposal [OwnerAddress] id is_or_not_add_approval - -OwnerAddress (optional) -> The address of the account which initiated the transaction. -> Default: the address of the login account. - -id -> ID of the initiated proposal -> Example: 1 - -is_or_not_add_approval -> true for approve; false for disapprove - -Example: - -```console -> ApproveProposal 1 true # in favor of the offer -> ApproveProposal 1 false # Cancel the approved proposal -``` - -### Delete an existed proposal - - > deleteProposal [OwnerAddress] proposalId - -proposalId -> ID of the initiated proposal -> Example: 1 - -The proposal must be canceled by the supernode that initiated the proposal. - -Example： - - > DeleteProposal 1 - -### Obtain proposal information - -ListProposals -> Obtain a list of initiated proposals - -ListProposalsPaginated -> Use the paging mode to obtain the initiated proposal - -GetProposal -> Obtain proposal information based on the proposal ID - -## How to trade on the exchange - -The trading and price fluctuations of trading pairs are in accordance with the Bancor Agreement, -which can be found in TRON's [related documents](https://tronprotocol.github.io/documentation-en/clients/wallet-cli-command/#dex). - -### Create a trading pair - -> exchangeCreate [OwnerAddress] first_token_id first_token_balance second_token_id second_token_balance - -OwnerAddress (optional) -> The address of the account which initiated the transaction. -> Default: the address of the login account. - -First_token_id, first_token_balance -> ID and amount of the first token - -second_token_id, second_token_balance -> ID and amount of the second token -> -> The ID is the ID of the issued TRC10 token. -> If it is TRX, the ID is "_". -> The amount must be greater than 0, and less than 1,000,000,000,000,000. - -Example: - -> exchangeCreate 1000001 10000 _ 10000 - # Create trading pairs with the IDs of 1000001 and TRX, with amount 10000 for both. - -### get exchange by id -> getExchange -Query exchange pair based on id (Confirmed state). - -Example: - -```console -> getExchange 1 -``` - -### Capital injection - -> exchangeInject [OwnerAddress] exchange_id token_id quant - -OwnerAddress (optional) -> The address of the account which initiated the transaction. -> Default: the address of the login account. - -exchange_id -> The ID of the trading pair to be funded - -token_id, quant -> TokenId and quantity (unit in base unit) of capital injection - -When conducting a capital injection, depending on its quantity (quant), a proportion -of each token in the trading pair will be withdrawn from the account, and injected into the trading -pair. Depending on the difference in the balance of the transaction, the same amount of money for -the same token would vary. - -### Transactions - -> exchangeTransaction [OwnerAddress] exchange_id token_id quant expected - -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. - -Example： - -> ExchangeTransaction 1 1000001 100 80 - -It is expected to acquire the 80 TRX by exchanging 1000001 from the trading pair ID of 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). - -### Capital Withdrawal - -> exchangeWithdraw [OwnerAddress] exchange_id token_id quant - -OwnerAddress (optional) -> The address of the account which initiated the transaction. -> Default: the address of the login account. - -Exchange_id - -> -The ID of the trading pair to be withdrawn - -Token_id, quant -> TokenId and quantity (unit in base unit) of capital withdrawal - -When conducting a capital withdrawal, depending on its quantity (quant), a proportion of each token -in the transaction pair is withdrawn from the trading pair, and injected into the account. Depending on the difference in the balance of the transaction, the same amount of money for the same token would vary. - -### Obtain information on trading pairs - -ListExchanges -> List trading pairs - -ListExchangesPaginated -> List trading pairs by page - -## 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 accesses: - -- owner: access to the owner of account -- active: access to other features of accounts, and access that authorizes a certain feature. Block production authorization is not included if it's for witness purposes. -- witness: only for witness, block production authorization will be granted to one of the other users. - -The rest of the users will be granted - -```console -> Updateaccountpermission TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ {"owner_permission":{"type":0,"permission_name":"owner","threshold":1,"keys":[{"address":"TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ","weight":1}]},"witness_permission":{"type":1,"permission_name":"witness","threshold":1,"keys":[{"address":"TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ","weight":1}]},"active_permissions":[{"type":2,"permission_name":"active12323","threshold":2,"operations":"7fff1fc0033e0000000000000000000000000000000000000000000000000000","keys":[{"address":"TNhXo1GbRNCuorvYu5JFWN3m2NYr9QQpVR","weight":1},{"address":"TKwhcDup8L2PH5r6hxp5CQvQzZqJLmKvZP","weight":1}]}]} -``` -or -```console -wallet> updateAccountPermission -=== UpdateAccountPermission Interactive Mode === - -Select permission to modify: -1. owner_permission -2. witness_permission -3. active_permissions -4. Add new active_permission -5. Delete active_permission -6. Show preview and Confirm -7. Exit -> -``` - -The account TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ gives the owner access to itself, active access to -TNhXo1GbRNCuorvYu5JFWN3m2NYr9QQpVR and TKwhcDup8L2PH5r6hxp5CQvQzZqJLmKvZP. Active access will -need signatures from both accounts in order to take effect. - -If the account is not a witness, it's not necessary to set witness_permission, otherwise an error will occur. - -### Signed transaction - -> SendCoin TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW 10000000000000000 - -Will show "Please confirm and input your permission id, if input y or Y means default 0, other -non-numeric characters will cancel transaction." - -This will require the transfer authorization of active access. Enter: 2 - -Then select accounts and put in local password, i.e. TNhXo1GbRNCuorvYu5JFWN3m2NYr9QQpVR needs a -private key TNhXo1GbRNCuorvYu5JFWN3m2NYr9QQpVR to sign a transaction. - -Select another account and enter the local password. i.e. TKwhcDup8L2PH5r6hxp5CQvQzZqJLmKvZP will -need a private key of TKwhcDup8L2PH5r6hxp5CQvQzZqJLmKvZP to sign a transaction. - -The weight of each account is 1, threshold of access is 2. When the requirements are met, users -will be notified with “Send 10000000000000000 Sun to TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW -successful !!”. - -This is how multiple accounts user multi-signature when using the same cli. -Use the instruction addTransactionSign according to the obtained transaction hex string if -signing at multiple cli. After signing, the users will need to broadcast final transactions -manually. - -## Obtain weight information according to transaction - - > getTransactionSignWeight - 0a8c010a020318220860e195d3609c86614096eadec79d2d5a6e080112680a2d747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e5472616e73666572436f6e747261637412370a1541a7d8a35b260395c14aa456297662092ba3b76fc01215415a523b449890854c8fc460ab602df9f31fe4293f18808084fea6dee11128027094bcb8bd9d2d1241c18ca91f1533ecdd83041eb0005683c4a39a2310ec60456b1f0075b4517443cf4f601a69788f001d4bc03872e892a5e25c618e38e7b81b8b1e69d07823625c2b0112413d61eb0f8868990cfa138b19878e607af957c37b51961d8be16168d7796675384e24043d121d01569895fcc7deb37648c59f538a8909115e64da167ff659c26101 - -The information displays as follows: - -```json -{ - "result":{ - "code":"PERMISSION_ERROR", - "message":"Signature count is 2 more than key counts of permission : 1" - }, - "permission":{ - "operations":"7fff1fc0033e0100000000000000000000000000000000000000000000000000", - "keys":[ - { - "address":"TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ", - "weight":1 - } - ], - "threshold":1, - "id":2, - "type":"Active", - "permission_name":"active" - }, - "transaction":{ - "result":{ - "result":true - }, - "txid":"7da63b6a1f008d03ef86fa871b24a56a501a8bbf15effd7aca635de6c738df4b", - "transaction":{ - "signature":[ - "c18ca91f1533ecdd83041eb0005683c4a39a2310ec60456b1f0075b4517443cf4f601a69788f001d4bc03872e892a5e25c618e38e7b81b8b1e69d07823625c2b01", - "3d61eb0f8868990cfa138b19878e607af957c37b51961d8be16168d7796675384e24043d121d01569895fcc7deb37648c59f538a8909115e64da167ff659c26101" - ], - "txID":"7da63b6a1f008d03ef86fa871b24a56a501a8bbf15effd7aca635de6c738df4b", - "raw_data":{ - "contract":[ - { - "parameter":{ - "value":{ - "amount":10000000000000000, - "owner_address":"TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ", - "to_address":"TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW" - }, - "type_url":"type.googleapis.com/protocol.TransferContract" - }, - "type":"TransferContract", - "Permission_id":2 - } - ], - "ref_block_bytes":"0318", - "ref_block_hash":"60e195d3609c8661", - "expiration":1554123306262, - "timestamp":1554101706260 - }, - "raw_data_hex":"0a020318220860e195d3609c86614096eadec79d2d5a6e080112680a2d747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e5472616e73666572436f6e747261637412370a1541a7d8a35b260395c14aa456297662092ba3b76fc01215415a523b449890854c8fc460ab602df9f31fe4293f18808084fea6dee11128027094bcb8bd9d2d" - } - } -} -``` - -### Get signature information according to transactions - - > getTransactionApprovedList - 0a8c010a020318220860e195d3609c86614096eadec79d2d5a6e080112680a2d747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e5472616e73666572436f6e747261637412370a1541a7d8a35b260395c14aa456297662092ba3b76fc01215415a523b449890854c8fc460ab602df9f31fe4293f18808084fea6dee11128027094bcb8bd9d2d1241c18ca91f1533ecdd83041eb0005683c4a39a2310ec60456b1f0075b4517443cf4f601a69788f001d4bc03872e892a5e25c618e38e7b81b8b1e69d07823625c2b0112413d61eb0f8868990cfa138b19878e607af957c37b51961d8be16168d7796675384e24043d121d01569895fcc7deb37648c59f538a8909115e64da167ff659c26101 - -```json -{ - "result":{ - - }, - "approved_list":[ - "TKwhcDup8L2PH5r6hxp5CQvQzZqJLmKvZP", - "TNhXo1GbRNCuorvYu5JFWN3m2NYr9QQpVR" - ], - "transaction":{ - "result":{ - "result":true - }, - "txid":"7da63b6a1f008d03ef86fa871b24a56a501a8bbf15effd7aca635de6c738df4b", - "transaction":{ - "signature":[ - "c18ca91f1533ecdd83041eb0005683c4a39a2310ec60456b1f0075b4517443cf4f601a69788f001d4bc03872e892a5e25c618e38e7b81b8b1e69d07823625c2b01", - "3d61eb0f8868990cfa138b19878e607af957c37b51961d8be16168d7796675384e24043d121d01569895fcc7deb37648c59f538a8909115e64da167ff659c26101" - ], - "txID":"7da63b6a1f008d03ef86fa871b24a56a501a8bbf15effd7aca635de6c738df4b", - "raw_data":{ - "contract":[ - { - "parameter":{ - "value":{ - "amount":10000000000000000, - "owner_address":"TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ", - "to_address":"TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW" - }, - "type_url":"type.googleapis.com/protocol.TransferContract" - }, - "type":"TransferContract", - "Permission_id":2 - } - ], - "ref_block_bytes":"0318", - "ref_block_hash":"60e195d3609c8661", - "expiration":1554123306262, - "timestamp":1554101706260 - }, - "raw_data_hex":"0a020318220860e195d3609c86614096eadec79d2d5a6e080112680a2d747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e5472616e73666572436f6e747261637412370a1541a7d8a35b260395c14aa456297662092ba3b76fc01215415a523b449890854c8fc460ab602df9f31fe4293f18808084fea6dee11128027094bcb8bd9d2d" - } - } -} -``` - -## How to use smart contract - -### deploy smart contracts - -> DeployContract [ownerAddress] contractName ABI byteCode constructor params isHex fee_limit consume_user_resource_percent origin_energy_limit value token_value token_id(e.g: TRXTOKEN, use # if don't provided) library:address,...> - -OwnerAddress -> The address of the account that initiated the transaction, optional, default is the address of the login account. - -contractName -> Name of smart contract - -ABI -> Compile generated ABI code - -byteCode -> Compile generated byte code - -constructor, params, isHex -> Define the format of the bytecode, which determines the way to parse byteCode from parameters - -fee_limit -> Transaction allows for the most consumed TRX - -consume_user_resource_percent -> Percentage of user resource consumed, in the range [0, 100] - -origin_energy_limit -> The most amount of developer Energy consumed by trigger contract once - -value -> The amount of trx transferred to the contract account - -token_value -> Number of TRX10 - -token_id -> TRX10 Id - -Example: - -``` -> deployContract normalcontract544 [{"constant":false,"inputs":[{"name":"i","type":"uint256"}],"name": "findArgsByIndexTest","outputs":[{"name":"z","type":"uint256"}],"payable":false,"stateMutability":"nonpayable","type":"function"}] -608060405234801561001057600080fd5b50610134806100206000396000f3006080604052600436106100405763ffffffff7c0100000000000000000000000000000000000000000000000000000000600035041663329000b58114610045575b600080fd5b34801561005157600080fd5b5061005d60043561006f565b60408051918252519081900360200190f35b604080516003808252608082019092526000916060919060208201838038833901905050905060018160008151811015156100a657fe5b602090810290910101528051600290829060019081106100c257fe5b602090810290910101528051600390829060029081106100de57fe5b6020908102909101015280518190849081106100f657fe5b906020019060200201519150509190505600a165627a7a72305820b24fc247fdaf3644b3c4c94fcee380aa610ed83415061ff9e65d7fa94a5a50a00029 # # false 1000000000 75 50000 0 0 # -``` - -Get the result of the contract execution with the getTransactionInfoById command: - -```console -> getTransactionInfoById 4978dc64ff746ca208e51780cce93237ee444f598b24d5e9ce0da885fb3a3eb9 -{ - "id": "8c1f57a5e53b15bb0a0a0a0d4740eda9c31fbdb6a63bc429ec2113a92e8ff361", - "fee": 6170500, - "blockNumber": 1867, - "blockTimeStamp": 1567499757000, - "contractResult": [ - "6080604052600436106100405763ffffffff7c0100000000000000000000000000000000000000000000000000000000600035041663329000b58114610045575b600080fd5b34801561005157600080fd5b5061005d60043561006f565b60408051918252519081900360200190f35b604080516003808252608082019092526000916060919060208201838038833901905050905060018160008151811015156100a657fe5b602090810290910101528051600290829060019081106100c257fe5b602090810290910101528051600390829060029081106100de57fe5b6020908102909101015280518190849081106100f657fe5b906020019060200201519150509190505600a165627a7a72305820b24fc247fdaf3644b3c4c94fcee380aa610ed83415061ff9e65d7fa94a5a50a00029" - ], - "contract_address": "TJMKWmC6mwF1QVax8Sy2AcgT6MqaXmHEds", - "receipt": { - "energy_fee": 6170500, - "energy_usage_total": 61705, - "net_usage": 704, - "result": "SUCCESS" - } -} -``` - -### trigger smart contract - -> TriggerContract [ownerAddress] contractAddress method args isHex fee_limit value token_value token_id - -OwnerAddress -> The address of the account that initiated the transaction, optional, default is the address of the login account. - -contractAddress -> Smart contract address - -method -> The name of function and parameters, please refer to the example - -args -> Parameter value, if you want to call `receive`, pass '#' instead - -isHex -> The format of the parameters method and args, is hex string or not - -fee_limit -> The most amount of trx allows for the consumption - -token_value -> Number of TRX10 - -token_id -> TRC10 id, If not, use ‘#’ instead - -Example: - -```console -> triggerContract TGdtALTPZ1FWQcc5MW7aK3o1ASaookkJxG findArgsByIndexTest(uint256) 0 false -1000000000 0 0 # -# Get the result of the contract execution with the getTransactionInfoById command -> getTransactionInfoById 7d9c4e765ea53cf6749d8a89ac07d577141b93f83adc4015f0b266d8f5c2dec4 -{ - "id": "de289f255aa2cdda95fbd430caf8fde3f9c989c544c4917cf1285a088115d0e8", - "fee": 8500, - "blockNumber": 2076, - "blockTimeStamp": 1567500396000, - "contractResult": [ - "" - ], - "contract_address": "TJMKWmC6mwF1QVax8Sy2AcgT6MqaXmHEds", - "receipt": { - "energy_fee": 8500, - "energy_usage_total": 85, - "net_usage": 314, - "result": "REVERT" - }, - "result": "FAILED", - "resMessage": "REVERT opcode executed" -} -``` - -### trigger constant contract - -> TriggerConstantContract [ownerAddress] contractAddress method args isHex fee_limit value token_value token_id - -OwnerAddress -> The address of the account that initiated the transaction, optional, default is the address of the login account. - -contractAddress -> Smart contract address - -method -> The name of function and parameters, please refer to the example - -args -> Parameter value, if you want to call `receive`, pass '#' instead - -isHex -> The format of the parameters method and args, is hex string or not - -fee_limit -> The most amount of trx allows for the consumption - -token_value -> Number of TRX10 - -token_id -> TRC10 id, If not, use ‘#’ instead - -Example: - -```console -> TriggerConstantContract TSNEe5Tf4rnc9zPMNXfaTF5fZfHDDH8oyW TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs "balanceOf(address)" 000000000000000000000000a614f803b6fd780986a42c78ec9c7f77e6ded13c true -``` - -### clear contract abi - -> ClearContractABI [ownerAddress] contractAddress - -OwnerAddress -> The address of the account that initiated the transaction, optional, default is the address of the login account. - -contractAddress -> Contract address - -Example: - -```console -> ClearContractABI TSNEe5Tf4rnc9zPMNXfaTF5fZfHDDH8oyW TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs -``` - -### get details of a smart contract - -> GetContract contractAddress - -contractAddress -> smart contract address - -Example: - -```console -> GetContract TGdtALTPZ1FWQcc5MW7aK3o1ASaookkJxG -{ - "origin_address": "TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ", - "contract_address": "TJMKWmC6mwF1QVax8Sy2AcgT6MqaXmHEds", - "abi": { - "entrys": [ - { - "name": "findArgsByIndexTest", - "inputs": [ - { - "name": "i", - "type": "uint256" - } - ], - "outputs": [ - { - "name": "z", - "type": "uint256" - } - ], - "type": "Function", - "stateMutability": "Nonpayable" - } - ] - }, - "bytecode": "608060405234801561001057600080fd5b50610134806100206000396000f3006080604052600436106100405763ffffffff7c0100000000000000000000000000000000000000000000000000000000600035041663329000b58114610045575b600080fd5b34801561005157600080fd5b5061005d60043561006f565b60408051918252519081900360200190f35b604080516003808252608082019092526000916060919060208201838038833901905050905060018160008151811015156100a657fe5b602090810290910101528051600290829060019081106100c257fe5b602090810290910101528051600390829060029081106100de57fe5b6020908102909101015280518190849081106100f657fe5b906020019060200201519150509190505600a165627a7a72305820b24fc247fdaf3644b3c4c94fcee380aa610ed83415061ff9e65d7fa94a5a50a00029", - "consume_user_resource_percent": 75, - "name": "normalcontract544", - "origin_energy_limit": 50000, - "code_hash": "23423cece3b4866263c15357b358e5ac261c218693b862bcdb90fa792d5714e6" -} -``` -### get info of a smart contract - -> GetContractInfo contractAddress - -contractAddress -> smart contract address - -Example: - -```console -> GetContractInfo TGdtALTPZ1FWQcc5MW7aK3o1ASaookkJxG -``` - -### update smart contract parameters - -> UpdateEnergyLimit [ownerAddress] contract_address energy_limit # Update parameter energy_limit -> UpdateSetting [ownerAddress] contract_address consume_user_resource_percent # Update parameter consume_user_resource_percent - -### create2 - -> Create2 address code salt - -Predict the contract address generated after deploying a contract. Among them, address is the contract address for executing the create 2 instruction, code is the bytecode of the contract to be deployed, and salt is a random salt value. - -Example: - -```console -> Create2 TEDapYSVvAZ3aYH7w8N9tMEEFKaNKUD5Bp 5f805460ff1916600190811790915560649055606319600255 2132 -``` - -### estimate-energy - -> EstimateEnergy owner_address(use # if you own) contract_address method args isHex [value token_value token_id(e.g: TRXTOKEN, use # if don't provided)] - -Estimate the energy required for the successful execution of smart contract transactions. (Confirmed state). - -Example: - -```console -> EstimateEnergy TSNEe5Tf4rnc9zPMNXfaTF5fZfHDDH8oyW TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs "balanceOf(address)" 000000000000000000000000a614f803b6fd780986a42c78ec9c7f77e6ded13c true -``` - -## How to delegate resource - -### delegate resource - - > freezeBalance [OwnerAddress] frozen_balance frozen_duration [ResourceCode:0 BANDWIDTH, 1 ENERGY] [receiverAddress] - -The latter two parameters are optional parameters. If not set, the TRX is frozen to obtain -resources for its own use; if it is not empty, the acquired resources are used by 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 TRX, the unit is the smallest unit (Sun), the minimum is 1000000sun. - -frozen_duration -> frezen duration, 3 days - -ResourceCode -> 0 BANDWIDTH;1 ENERGY (TRON_POWER is not delegatable) - -receiverAddress -> target account address - -### unfreeze delegated resource - - > unfreezeBalance [OwnerAddress] ResourceCode(0 BANDWIDTH, 1 ENERGY) [receiverAddress] - -The latter two parameters are optional. If they are not set, the BANDWIDTH resource is unfreeze -by default; when the receiverAddress is set, the delegate resources are unfreezed. - -### get resource delegation information - -getDelegatedResource fromAddress toAddress -> get the information from the fromAddress to the toAddress resource delegate - -getDelegatedResourceAccountIndex address -> get the information that address is delegated to other account resources - - -## How to freezev2 - -### freezev2/unfreezev2 resource - - > freezeBalanceV2 [OwnerAddress] frozen_balance [ResourceCode:0 BANDWIDTH,1 ENERGY,2 TRON_POWER] - -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 1000000sun. - -ResourceCode -> 0 BANDWIDTH;1 ENERGY;2 TRON_POWER (only when getAllowNewResourceModel is enabled) - -Example: -```console -wallet> FreezeBalanceV2 TJAVcszse667FmSNCwU2fm6DmfM5D4AyDh 1000000000000000 0 -txid is 82244829971b4235d98a9f09ba67ddb09690ac2f879ad93e09ba3ec1ab29177d -wallet> GetTransactionById 82244829971b4235d98a9f09ba67ddb09690ac2f879ad93e09ba3ec1ab29177d -{ - "ret":[ - { - "contractRet":"SUCCESS" - } - ], - "signature":[ - "4faa3772fa3d3e4792e8126cafed2dc2c5c069cd09c29532f0119bc982bf356004772e16fad86e401f5818c35b96d214d693efab06997ca2f07044d4494f12fd01" - ], - "txID":"82244829971b4235d98a9f09ba67ddb09690ac2f879ad93e09ba3ec1ab29177d", - "raw_data":{ - "contract":[ - { - "parameter":{ - "value":{ - "frozen_balance":1000000000000000, - "owner_address":"4159e3741a68ec3e1ebba80ad809d5ccd31674236e" - }, - "type_url":"type.googleapis.com/protocol.FreezeBalanceV2Contract" - }, - "type":"FreezeBalanceV2Contract" - } - ], - "ref_block_bytes":"0000", - "ref_block_hash":"19b59068c6058ff4", - "expiration":1671109891800, - "timestamp":1671088291796 - }, - "raw_data_hex":"0a020000220819b59068c6058ff440d8ada5afd1305a5c083612580a34747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e467265657a6542616c616e63655632436f6e747261637412200a154159e3741a68ec3e1ebba80ad809d5ccd31674236e1080809aa6eaafe30170d4fffea4d130" -} -``` - - > unfreezeBalanceV2 [OwnerAddress] unfreezeBalance ResourceCode(0 BANDWIDTH,1 ENERGY,2 TRON_POWER) - -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;2 TRON_POWER (only when getAllowNewResourceModel is enabled) - -Example: -```console -wallet> UnFreezeBalanceV2 TJAVcszse667FmSNCwU2fm6DmfM5D4AyDh 9000000 0 -txid is dcfea1d92fc928d24c88f7f71a03ae8105d0b5b112d6d48be93d3b9c73bea634 -wallet> GetTransactionById dcfea1d92fc928d24c88f7f71a03ae8105d0b5b112d6d48be93d3b9c73bea634 -{ - "ret":[ - { - "contractRet":"SUCCESS" - } - ], - "signature":[ - "f73a278f742c11e8e5ede693ca09b0447a804fcb28ea2bfdfd8545bb05da7be44bd08cfaa92bd4d159178f763fcf753f28d5296bd0c3d4557532cce3b256b9da00" - ], - "txID":"dcfea1d92fc928d24c88f7f71a03ae8105d0b5b112d6d48be93d3b9c73bea634", - "raw_data":{ - "contract":[ - { - "parameter":{ - "value":{ - "owner_address":"4159e3741a68ec3e1ebba80ad809d5ccd31674236e", - "unfreeze_balance":9000000 - }, - "type_url":"type.googleapis.com/protocol.UnfreezeBalanceV2Contract" - }, - "type":"UnfreezeBalanceV2Contract" - } - ], - "ref_block_bytes":"0000", - "ref_block_hash":"19b59068c6058ff4", - "expiration":1671119916913, - "timestamp":1671098316907 - }, - "raw_data_hex":"0a020000220819b59068c6058ff440f19e89b4d1305a5a083712560a36747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e556e667265657a6542616c616e63655632436f6e7472616374121c0a154159e3741a68ec3e1ebba80ad809d5ccd31674236e10c0a8a50470ebf0e2a9d130" -} -``` - -### delegate/undelegate resource - - > delegateResource [OwnerAddress] balance ResourceCode(0 BANDWIDTH,1 ENERGY), ReceiverAddress [lock] - -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 1000000sun. - -ResourceCode -> 0 BANDWIDTH;1 ENERGY - -ReceiverAddress -> The address of the account - -lock -> default is false, set true if need lock delegate for 3 days - -Example: -```console -wallet> DelegateResource TJAVcszse667FmSNCwU2fm6DmfM5D4AyDh 10000000 0 TQ4gjjpAjLNnE67UFbmK5wVt5fzLfyEVs3 true -txid is 363ac0b82b6ad3e0d3cad90f7d72b3eceafe36585432a3e013389db36152b6ed -wallet> GetTransactionById 363ac0b82b6ad3e0d3cad90f7d72b3eceafe36585432a3e013389db36152b6ed -{ - "ret":[ - { - "contractRet":"SUCCESS" - } - ], - "signature":[ - "1f57fd78456136faadc5091b47f5fd27a8e1181621e49129df6a4062499429fb48ee72e5f9a9ff5bfb7f2575f01f4076f7d4b89ca382d36af46a6fa4bc749f4301" - ], - "txID":"363ac0b82b6ad3e0d3cad90f7d72b3eceafe36585432a3e013389db36152b6ed", - "raw_data":{ - "contract":[ - { - "parameter":{ - "value":{ - "balance":10000000, - "receiver_address":"419a9afe56e155ef0ff3f680d00ecf19deff60bdca", - "lock":true, - "owner_address":"4159e3741a68ec3e1ebba80ad809d5ccd31674236e" - }, - "type_url":"type.googleapis.com/protocol.DelegateResourceContract" - }, - "type":"DelegateResourceContract" - } - ], - "ref_block_bytes":"0000", - "ref_block_hash":"19b59068c6058ff4", - "expiration":1671120059226, - "timestamp":1671098459216 - }, - "raw_data_hex":"0a020000220819b59068c6058ff440daf691b4d1305a720839126e0a35747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e44656c65676174655265736f75726365436f6e747261637412350a154159e3741a68ec3e1ebba80ad809d5ccd31674236e1880ade2042215419a9afe56e155ef0ff3f680d00ecf19deff60bdca280170d0c8eba9d130" -} - -``` - - > unDelegateResource [OwnerAddress] balance ResourceCode(0 BANDWIDTH,1 ENERGY), ReceiverAddress - -OwnerAddress -> The address of the account that initiated the transaction, optional, default is the address of the login account. - -balance -> The amount of unDelegate, the unit is the smallest unit (Sun) - -ResourceCode -> 0 BANDWIDTH;1 ENERGY - -ReceiverAddress -> The address of the account - -Example: -```console -wallet> UnDelegateResource TJAVcszse667FmSNCwU2fm6DmfM5D4AyDh 1000000 0 TQ4gjjpAjLNnE67UFbmK5wVt5fzLfyEVs3 -txid is feb334794cf361fd351728026ccf7319e6ae90eba622b9eb53c626cdcae4965c -wallet> GetTransactionById feb334794cf361fd351728026ccf7319e6ae90eba622b9eb53c626cdcae4965c -{ - "ret":[ - { - "contractRet":"SUCCESS" - } - ], - "signature":[ - "85a41a4e44780ffbe0841a44fd71cf621f129d98e84984cfca68e03364f781aa7f9d44177af0b40d82da052feec9f47a399ed6e51be66c5db07cb13477dcde8c01" - ], - "txID":"feb334794cf361fd351728026ccf7319e6ae90eba622b9eb53c626cdcae4965c", - "raw_data":{ - "contract":[ - { - "parameter":{ - "value":{ - "balance":1000000, - "receiver_address":"419a9afe56e155ef0ff3f680d00ecf19deff60bdca", - "owner_address":"4159e3741a68ec3e1ebba80ad809d5ccd31674236e" - }, - "type_url":"type.googleapis.com/protocol.UnDelegateResourceContract" - }, - "type":"UnDelegateResourceContract" - } - ], - "ref_block_bytes":"0000", - "ref_block_hash":"19b59068c6058ff4", - "expiration":1671120342283, - "timestamp":1671098742280 - }, - "raw_data_hex":"0a020000220819b59068c6058ff4408b9aa3b4d1305a71083a126d0a37747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e556e44656c65676174655265736f75726365436f6e747261637412320a154159e3741a68ec3e1ebba80ad809d5ccd31674236e18c0843d2215419a9afe56e155ef0ff3f680d00ecf19deff60bdca7088ecfca9d130" -} -``` -### withdraw expire unfreeze -> withdrawExpireUnfreeze [OwnerAddress] - -OwnerAddress -> The address of the account that initiated the transaction, optional, default is the address of the login account. - -Example: -```console -wallet> withdrawexpireunfreeze TJAVcszse667FmSNCwU2fm6DmfM5D4AyDh -txid is e5763ab8dfb1e7ed076770d55cf3c1ddaf36d75e23ec8330f99df7e98f54a147 -wallet> GetTransactionById e5763ab8dfb1e7ed076770d55cf3c1ddaf36d75e23ec8330f99df7e98f54a147 -{ - "ret":[ - { - "contractRet":"SUCCESS" - } - ], - "signature":[ - "f8f02b5aa634b8666862a6d2ed68fcfd90afc616d14062952b0b09f0404d9bca6c4d3dc6dab082784950ff1ded235a07dab0d738c8a202be9451d5ca92b8eece01" - ], - "txID":"e5763ab8dfb1e7ed076770d55cf3c1ddaf36d75e23ec8330f99df7e98f54a147", - "raw_data":{ - "contract":[ - { - "parameter":{ - "value":{ - "owner_address":"4159e3741a68ec3e1ebba80ad809d5ccd31674236e" - }, - "type_url":"type.googleapis.com/protocol.WithdrawExpireUnfreezeContract" - }, - "type":"WithdrawExpireUnfreezeContract" - } - ], - "ref_block_bytes":"0000", - "ref_block_hash":"19b59068c6058ff4", - "expiration":1671122055318, - "timestamp":1671100455315 - }, - "raw_data_hex":"0a020000220819b59068c6058ff44096e18bb5d1305a5a083812560a3b747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e5769746864726177457870697265556e667265657a65436f6e747261637412170a154159e3741a68ec3e1ebba80ad809d5ccd31674236e7093b3e5aad130" -} -``` -> cancelAllUnfreezeV2 [OwnerAddress] - -OwnerAddress -> The address of the account that initiated the transaction, optional, default is the address of the login account. - -Example: -```console -wallet> cancelAllUnfreezeV2 TJAVcszse667FmSNCwU2fm6DmfM5D4AyDh -txid is e5763ab8dfb1e7ed076770d55cf3c1ddaf36d75e23ec8330f99df7e98f54a147 -wallet> GetTransactionById e5763ab8dfb1e7ed076770d55cf3c1ddaf36d75e23ec8330f99df7e98f54a147 -{ - "ret":[ - { - "contractRet":"SUCCESS" - } - ], - "signature":[ - "f8f02b5aa634b8666862a6d2ed68fcfd90afc616d14062952b0b09f0404d9bca6c4d3dc6dab082784950ff1ded235a07dab0d738c8a202be9451d5ca92b8eece01" - ], - "txID":"e5763ab8dfb1e7ed076770d55cf3c1ddaf36d75e23ec8330f99df7e98f54a147", - "raw_data":{ - "contract":[ - { - "parameter":{ - "value":{ - "owner_address":"4159e3741a68ec3e1ebba80ad809d5ccd31674236e" - }, - "type_url":"type.googleapis.com/protocol.CancelAllUnfreezeV2" - }, - "type":"CancelAllUnfreezeV2Contract" - } - ], - "ref_block_bytes":"0000", - "ref_block_hash":"19b59068c6058ff4", - "expiration":1671122055318, - "timestamp":1671100455315 - }, - "raw_data_hex":"0a020000220819b59068c6058ff44096e18bb5d1305a5a083812560a3b747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e5769746864726177457870697265556e667265657a65436f6e747261637412170a154159e3741a68ec3e1ebba80ad809d5ccd31674236e7093b3e5aad130" -} -``` - -### get resource delegation information use v2 API - - > getDelegatedResourceV2 fromAddress toAddress -> get the information from the fromAddress to the toAddress resource delegate use v2 API - -fromAddress -> The address of the account that start the delegate - -toAddress -> The address of the account that receive the delegate - -Example: -```console -wallet> getDelegatedResourceV2 TJAVcszse667FmSNCwU2fm6DmfM5D4AyDh TQ4gjjpAjLNnE67UFbmK5wVt5fzLfyEVs3 -{ - "delegatedResource": [ - { - "from": "TJAVcszse667FmSNCwU2fm6DmfM5D4AyDh", - "to": "TQ4gjjpAjLNnE67UFbmK5wVt5fzLfyEVs3", - "frozen_balance_for_bandwidth": 10000000 - } - ] -} -``` - - > getDelegatedResourceAccountIndexV2 address -> get the information that address is delegated to other account resources use v2 API - -address -> The address of the account that start the delegate or receive the delegate - -Example: -```console -wallet> getDelegatedResourceAccountIndexV2 TJAVcszse667FmSNCwU2fm6DmfM5D4AyDh -{ - "account": "TJAVcszse667FmSNCwU2fm6DmfM5D4AyDh", - "toAccounts": [ - "TQ4gjjpAjLNnE67UFbmK5wVt5fzLfyEVs3" - ] -} -``` - - > getcandelegatedmaxsize ownerAddress type -> get the max size that the ownerAddress can delegate use delegateResource - -ownerAddress -> The address of the account that start the delegate, optional, default is the address of the login account. - -type -> 0 bandwidth, 1 energy - -Example: -```console -wallet> getCanDelegatedMaxSize TJAVcszse667FmSNCwU2fm6DmfM5D4AyDh 0 -{ - "max_size": 999999978708334 -} -``` - - > getavailableunfreezecount ownerAddress -> get the available unfreeze count that the ownerAddress can call unfreezeBalanceV2 - -ownerAddress -> The address of the account that initiated the transaction, optional, default is the address of the login account. - -Example: -```console -wallet> getAvailableUnfreezeCount TJAVcszse667FmSNCwU2fm6DmfM5D4AyDh -{ - "count": 31 -} -``` - - > getcanwithdrawunfreezeamount ownerAddress timestamp -> get the withdraw unfreeze amount that the ownerAddress can get by withdrawexpireunfreeze - -ownerAddress -> The address of the account that initiated the transaction, optional, default is the address of the login account. - -timestamp -> get can withdraw unfreeze amount until timestamp, - - -Example: -```console -wallet> getCanWithdrawUnfreezeAmount TJAVcszse667FmSNCwU2fm6DmfM5D4AyDh 1671100335000 -{ - "amount": 9000000 -} -``` -## Get resource prices and memo fee - > getbandwidthprices -> get historical unit price of bandwidth - -Example: -```console -wallet> getBandwidthPrices -{ - "prices": "0:10,1606537680000:40,1614238080000:140,1626581880000:1000,1626925680000:140,1627731480000:1000" -} -``` - > getenergyprices -> get historical unit price of energy - -Example: -```console -wallet> getEnergyPrices -{ - "prices": "0:100,1575871200000:10,1606537680000:40,1614238080000:140,1635739080000:280,1681895880000:420" -} -``` - > getmemofee -> get memo fee - -Example: -```console -wallet> getMemoFee -{ - "prices": "0:0,1675492680000:1000000" -} -``` - -### get chain parameters - -> GetChainParameters - -Show all parameters that the blockchain committee can set. -Example: - -```console -> GetChainParameters -``` - -## import and export mnemonic - >ImportWalletByMnemonic ->Import wallet, you need to set a password, mnemonic - -Example: -```console -wallet> ImportWalletByMnemonic -Please input password. -password: -Please input password again. -password: -Please enter 12 words (separated by spaces) [Attempt 1/3]: -``` - -> ExportWalletMnemonic ->export mnemonic of the address in the wallet - -Example: -```console -wallet> ExportWalletMnemonic -Please input your password. -password: -exportWalletMnemonic successful !! -a*ert tw*st co*rect mat*er pa*s g*ther p*t p*sition s*op em*ty coc*nut aband*n -``` - -## generate sub account - >GenerateSubAccount ->generate subaccount using the mnemonic in the wallet - -Example: -```console -wallet> GenerateSubAccount -Please input your password. -password: - -=== Sub Account Generator === ------------------------------ -Default Address: TYEhEg7b7tXm92UDbRDXPtJNU6T9xVGbbo -Default Path: m/44'/195'/0'/0/1 ------------------------------ - -1. Generate Default Path -2. Change Account -3. Custom Path - -Enter your choice (1-3): 1 -mnemonic file : ./Mnemonic/TYEhEg7b7tXm92UDbRDXPtJNU6T9xVGbbo.json -Generate a sub account successful, keystore file name is TYEhEg7b7tXm92UDbRDXPtJNU6T9xVGbbo.json -generateSubAccount successful. -``` -## clear wallet keystore - >ClearWalletKeystore ->clear wallet keystore of the login account - -Example: -```console -wallet> ClearWalletKeystore - -Warning: Dangerous operation! -This operation will permanently delete the Wallet&Mnemonic files of the Address: TABWx7yFhWrvZHbwKcCmFLyPLWjd2dZ2Rq -Warning: The private key and mnemonic words will be permanently lost and cannot be recovered! -Continue? (y/Y to proceed):y - -Final confirmation: -Please enter: 'DELETE' to confirm the delete operation: -Confirm: (DELETE): DELETE - -File deleted successfully: -- /wallet-cli/Wallet/TABWx8yFhWrvZHbwKcCmFLyPLWjd2dZ2Rq.json -- /wallet-cli/Mnemonic/TABWx8yFhWrvZHbwKcCmFLyPLWjd2dZ2Rq.json -ClearWalletKeystore successful !!! -``` -## export import wallet keystore - >ExportWalletKeystore ->export the wallet keystore to the format of tronlink wallet - -Example: -```console -wallet> ExportWalletKeystore tronlink /tmp -Please input your password. -password: -exported keystore file : /tmp/TYdhEg8b7tXm92UDbRDXPtJNU6T9xVGbbo.json -exportWalletKeystore successful !! -``` - >ImportWalletByKeystore ->import the keystore file of tronlink wallet to wallet-cli - -Example: -```console -wallet> ImportWalletByKeystore tronlink /tmp/tronlink.json -Please input password. -password: -Please input password again. -password: -fileName = TYQq6zp51unQDNELmT4xKMWh5WLcwpCDZJ.json -importWalletByKeystore successful !! -``` -## import wallet by ledger - >ImportWalletByLedger ->import the derived account of ledger to wallet-cli - -Example: -```console -wallet> ImportWalletByLedger -((Note:This will pair Ledger to user your hardward 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. -password: -Please input password again. -password: -------------------------------------------------- -Default Account Address: TAT1dA8F9HXGqmhvMCjxCKAD29YxDRw81y -Default Path: m/44'/195'/0'/0/0 -------------------------------------------------- -1. Import Default Account -2. Change Path -3. Custom Path -Select an option: 1 -Import a wallet by Ledger successful, keystore file : ./Wallet/Ledger-TAT1dA8F9HXGqmhvMCjxCKAD29YxDRw81y.json -You are now logged in, and you can perform operations using this account. -``` -## login all -> LoginAll ->Multiple Keystore accounts can be logged in with a unified password - -Example: -```console -wallet> loginall -Please input your password. -password: -Use user defined config file in current dir -[========================================] 100% -The 1th keystore file name is TJEEKTmaVTYSpJAxahtyuofnDSpe2seajB.json -The 2th keystore file name is TX1L9xonuUo1AHsjUZ3QzH8wCRmKm56Xew.json -The 3th keystore file name is TVuVqnJFuuDxN36bhEbgDQS7rNGA5dSJB7.json -The 4th keystore file name is Ledger-TRvVXgqddDGYRMx3FWf2tpVxXQQXDZxJQe.json -The 5th keystore file name is TYXFDtn86VPFKg4mkwMs45DKDcpAyqsada.json -Please choose between 1 and 5 -5 -LoginAll successful !!! -``` - -## logout -> Logout -> Log out of the current wallet account. - -Example: -```console -wallet> Logout -Logout successful !!! -``` - -## lock -> Lock ->To use the lock function of the login account, it is necessary to configure **lockAccount = true** in the **config.conf**. -The current login account is locked, which means that signatures and transactions are not allowed. - -Example: -```console -wallet> lock -lock successful !!! -``` - -## unlock -> Unlock ->To use the unlock function of the login account, it is necessary to configure **lockAccount = true** in the **config.conf**. -After the current login account is locked, it can be unlocked. By default, it will be unlocked again after 300 seconds. Unlocking can specify parameters in seconds. - -Example: -```console -wallet> unlock 60 -Please input your password. -password: -unlock successful !!! -``` - -## switch network - > SwitchNetwork ->This command allows for flexible network switching at any time. ->`switchnetwork local` will switch to the network configured in local config.conf. - -Example: -```console -wallet> switchnetwork -Please select network： -1. MAIN -2. NILE -3. SHASTA -Enter numbers to select a network (1-3):1 -Now, current network is : MAIN -SwitchNetwork successful !!! -``` -```console -wallet> switchnetwork main -Now, current network is : MAIN -SwitchNetwork successful !!! -``` - -```console -wallet> switchnetwork empty localhost:50052 -Now, current network is : CUSTOM -SwitchNetwork successful !!! -``` - -## current network - > CurrentNetwork ->View current network. - -Example: -```console -wallet> currentnetwork -currentNetwork: NILE -``` - -```console -wallet> currentnetwork -current network: CUSTOM -fullNode: EMPTY, solidityNode: localhost:50052 -``` -## Gas Free Support - -Wallet-cli now supports GasFree integration. This guide explains the new commands and provides instructions on how to use them. - -For more details, please refer to [GasFree Documentation](https://gasfree.io/specification) and [TronLink User Guide For GasFree](https://support.tronlink.org/hc/en-us/articles/38903684778393-GasFree-User-Guide). - -Prerequisites -API Credentials: Users must obtain the API Key and API Secret from GasFree for authentication. Please refer to the official [application form](https://docs.google.com/forms/d/e/1FAIpQLSc5EB1X8JN7LA4SAVAG99VziXEY6Kv6JxmlBry9rUBlwI-GaQ/viewform) for instructions on setting up API authentication. - -New Commands: - -### Gas Free info -> GasFreeInfo -Query GasFree Information -Function: Retrieve the basic info, including the GasFree address associated with your current wallet address. -Note: The GasFree address is automatically activated upon the first transfer, which may incur an activation fee. - -Example: -```console -wallet> gasfreeinfo -balanceOf(address):70a08231 -{ - "gasFreeAddress":"TCtSt8fCkZcVdrGpaVHUr6P8EmdjysswMF", - "active":true, - "tokenBalance":998696000, - "activateFee":0, - "transferFee":2000, - "maxTransferValue":998694000 -} -gasFreeInfo: successful !! -``` - -```console -wallet> gasfreeinfo TRvVXgqddDGYRMx3FWf2tpVxXQQXDZxJQe -balanceOf(address):70a08231 -{ - "gasFreeAddress":"TCtSt8fCkZcVdrGpaVHUr6P8EmdjysswMF", - "active":true, - "tokenBalance":998696000, - "activateFee":0, - "transferFee":2000, - "maxTransferValue":998694000 -} -gasFreeInfo: successful !! -``` -### Gas Free transfer -> GasFreeTransfer -Submit GasFree Transfer -Function: Submit a gas-free token transfer request. - -Example: -```console -wallet> gasfreetransfer TEkj3ndMVEmFLYaFrATMwMjBRZ1EAZkucT 100000 - -GasFreeTransfer result: { - "code":200, - "data":{ - "amount":100000, - "providerAddress":"TKtWbdzEq5ss9vTS9kwRhBp5mXmBfBns3E", - "apiKey":"", - "accountAddress":"TUUSMd58eC3fKx3fn7whxJyr1FR56tgaP8", - "signature":"", - "targetAddress":"TEkj3ndMVEmFLYaFrATMwMjBRZ1EAZkucT", - "maxFee":2000000, - "version":1, - "nonce":8, - "tokenAddress":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf", - "createdAt":1747909635678, - "expiredAt":1747909695000, - "estimatedTransferFee":2000, - "id":"6c3ff67e-0bf4-4c09-91ca-0c7c254b01a0", - "state":"WAITING", - "estimatedActivateFee":0, - "gasFreeAddress":"TNER12mMVWruqopsW9FQtKxCGfZcEtb3ER", - "updatedAt":1747909635678 - } -} -GasFreeTransfer successful !!! -``` - -### Gas Free trace -> GasFreeTrace -Track Transfer Status -Function: Check the progress of a GasFree transfer using the traceId obtained from GasFreeTransfer. - -Example: -```console -wallet> gasfreetrace 6c3ff67e-0bf4-4c09-91ca-0c7c254b01a0 -GasFreeTrace result: { - "code":200, - "data":{ - "amount":100000, - "providerAddress":"TKtWbdzEq5ss9vTS9kwRhBp5mXmBfBns3E", - "txnTotalCost":102000, - "accountAddress":"TUUSMd58eC3fKx3fn7whxJyr1FR56tgaP8", - "txnActivateFee":0, - "estimatedTotalCost":102000, - "targetAddress":"TEkj3ndMVEmFLYaFrATMwMjBRZ1EAZkucT", - "txnBlockTimestamp":1747909638000, - "txnTotalFee":2000, - "nonce":8, - "estimatedTotalFee":2000, - "tokenAddress":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf", - "txnHash":"858f9a00776163b1f8a34467b9c5727657f8971a9f4e9d492f0a247fac0384f9", - "txnBlockNum":57175988, - "createdAt":1747909635678, - "expiredAt":1747909695000, - "estimatedTransferFee":2000, - "txnState":"ON_CHAIN", - "id":"6c3ff67e-0bf4-4c09-91ca-0c7c254b01a0", - "state":"CONFIRMING", - "estimatedActivateFee":0, - "gasFreeAddress":"TNER12mMVWruqopsW9FQtKxCGfZcEtb3ER", - "txnTransferFee":2000, - "txnAmount":100000 - } -} -GasFreeTrace: successful!! -``` - -## switch wallet - > SwitchWallet ->After logging in with the LoginAll command, you can switch wallets - -Example: -```console -wallet> switchwallet -The 1th keystore file name is TJEEKTmaVTYSpJAxahtyuofnDSpe2seajB.json -The 2th keystore file name is TX1L9xonuUo1AHsjUZ3QzH8wCRmKm56Xew.json -The 3th keystore file name is TVuVqnJFuuDxN36bhEbgDQS7rNGA5dSJB7.json -The 4th keystore file name is Ledger-TRvVXgqddDGYRMx3FWf2tpVxXQQXDZxJQe.json -The 5th keystore file name is TYXFDtn86VPFKg4mkwMs45DKDcpAyqsada.json -Please choose between 1 and 5 -5 -SwitchWallet successful !!! -``` - -## reset wallet - > ResetWallet ->Use the resetWallet command to delete all local wallet's Keystore files and mnemonic files, and guide you to re register or import the wallet through prompts - -Example: -```console -wallet> resetwallet -User defined config file doesn't exists, use default config file in jar - -Warning: Dangerous operation! -This operation will permanently delete the Wallet&Mnemonic files -Warning: The private key and mnemonic words will be permanently lost and cannot be recovered! -Continue? (y/Y to proceed, c/C to cancel): -y - -Final confirmation: -Please enter: 'DELETE' to confirm the delete operation: -Confirm: (DELETE): DELETE -resetWallet successful !!! -Now, you can RegisterWallet or ImportWallet again. Or import the wallet through other means. -``` - -## create account -> CreateAccount ->This command can create a new account with an inactive address and burn a 1-trx handling fee for it - -Example: -```console -wallet> createaccount TDJ13zZzT3w91WMBm98gC3mwL7NbA6sQPA -{ - "raw_data":{ - "contract":[ - { - "parameter":{ - "value":{ - "owner_address":"TQLaB7L8o3ikjRVcN7tTjMZsRYPJ23XZbd", - "account_address":"TDJ13zZzT3w91WMBm98gC3mwL7NbA6sQPA" - }, - "type_url":"type.googleapis.com/protocol.AccountCreateContract" - }, - "type":"AccountCreateContract" - } - ], - "ref_block_bytes":"91a4", - "ref_block_hash":"2bfcd3bb597f3d40", - "expiration":1745333676000, - "timestamp":1745333618318 - }, - "raw_data_hex":"0a0291a422082bfcd3bb597f3d4040e0cff9efe5325a6612640a32747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e4163636f756e74437265617465436f6e7472616374122e0a15419d9c2bb5ee381a4396dd49ce42292e756b2e5e4b12154124764e4674179d4578cfc4c833c1ac1a09f6ce56708e8df6efe532" -} -Before sign transaction hex string is 0a84010a0291a422082bfcd3bb597f3d4040e0cff9efe5325a6612640a32747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e4163636f756e74437265617465436f6e7472616374122e0a15419d9c2bb5ee381a4396dd49ce42292e756b2e5e4b12154124764e4674179d4578cfc4c833c1ac1a09f6ce56708e8df6efe532 -Please confirm and input your permission id, if input y/Y means default 0, other non-numeric characters will cancel transaction. -y -Please choose your key for sign. -The 1th keystore file name is TJEEKTmaVTYSpJAxahtyuofnDSpe2seajB.json -The 2th keystore file name is TX1L9xonuUo1AHsjUZ3QzH8wCRmKm56Xew.json -The 3th keystore file name is TVuVqnJFuuDxN36bhEbgDQS7rNGA5dSJB7.json -The 4th keystore file name is Ledger-TRvVXgqddDGYRMx3FWf2tpVxXQQXDZxJQe.json -The 5th keystore file name is TYXFDtn86VPFKg4mkwMs45DKDcpAyqsada.json -Please choose between 1 and 5 -1 -After sign transaction hex string is 0a84010a0291a422082bfcd3bb597f3d404083bd9cfae5325a6612640a32747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e4163636f756e74437265617465436f6e7472616374122e0a15419d9c2bb5ee381a4396dd49ce42292e756b2e5e4b12154124764e4674179d4578cfc4c833c1ac1a09f6ce56708e8df6efe5321241ce53add4f75fe1838aa7e0a4e2411b3bbfce1d2164d68dac18507ed87e22ae503f65592a1161640834b3c0cef43c28f20b2d335120cc78b6f745a82ea95e451100 -TxId is 26d6fcdfdc0018097ec4166eb140e19ebd597bea2212579d2f6d921b0ad6e56f -CreateAccount successful !! -``` - -### set account id - -> SetAccountId [owner_address] account_id - -Sets a custom unique identifier (Account ID) for an account. - -Example: - -```console -> SetAccountId TEDapYSVvAZ3aYH7w8N9tMEEFKaNKUD5Bp 100 -``` - -### update account - -> UpdateAccount [owner_address] account_name - -Modify account name. - -Example: - -```console -> UpdateAccount test-name -``` - -### Modify wallet name -> ModifyWalletName new_wallet_name - -Modify wallet's name. - -Example: -```console -wallet> ModifyWalletName new-name -Modify Wallet Name successful !! -``` - -### View backup records -> ViewBackupRecords - -View backup records. You can configure the maximum number of records that `maxRecords` can retain in `config.conf`, excluding the number of buffer records. - -Example: -```console -wallet> ViewBackupRecords - -=== View Backup Records === -1. View all records -2. Filter by time range -Choose an option (1-2): 1 -``` -### View transaction history -> ViewTransactionHistory - -View transaction history. You can configure the maximum number of records that `maxRecords` can retain in `config.conf`, excluding the number of buffer records. +Interactive only. Build it, start the prompt, then type commands: -Example: ```console -wallet> ViewTransactionHistory -==================================== - TRANSACTION VIEWER -==================================== - -MAIN MENU: -1. View all transactions -2. Filter by time range -3. Help -4. Exit -Select option: 1 -``` - - -## Wallet related commands - -**RegisterWallet** -> Register your wallet, you need to set the wallet password and generate the address and private key. - -**BackupWallet** -> Back up your wallet, you need to enter your wallet password and export the private key.hex string format, such -as: 1234567890123456789012345678901234567890123456789012345678901234 - -**BackupWallet2Base64** -> Back up your wallet, you need to enter your wallet password and export the private key.base64 format, such as: ch1jsHTxjUHBR+BMlS7JNGd3ejC28WdFvEeo6uUHZUU= - -**ChangePassword** -> Modify the password of an account - -**ImportWallet** -> Import wallet, you need to set a password, hex String format - -**ImportWalletByBase64** -> Import wallet, you need to set a password, base64 format - -## Account related commands - -**GenerateAddress** -> Generate an address and print out the address and private key - -**GetAccount** -> Get account information based on address -**GetAccountById** -> Get account details information through account id - -**GetAccountNet** -> The usage of bandwidth - -**GetAccountResource** -> The usage of bandwidth and energy - -**GetAddress** -> Get the address of the current login account - -**GetBalance** -> Get the balance of the current login account - -## How to get transaction information - -**GetTransactionById** -> Get transaction information based on transaction id - -**GetTransactionCountByBlockNum** -> Get the number of transactions in the block based on the block height - -**GetTransactionInfoById** -> Get transaction-info based on transaction id, generally used to check the result of a smart contract trigger - -**GetTransactionInfoByBlockNum** -> Get the list of transaction information in the block based on the block height - -## How to get block information - -**GetBlock** -> Get the block according to the block number; if you do not pass the parameter, get the latest block - -**GetBlockById** -> Get block based on blockID - -**GetBlockByIdOrNum** -> Get blocks based on their ID or block height. If no parameters are passed, Get the header block. - -**GetBlockByLatestNum n** -> Get the latest n blocks, where 0 < n < 100 - -**GetBlockByLimitNext startBlockId endBlockId** -> Get the block in the range [startBlockId, endBlockId) - -## Some others - -**GetNextMaintenanceTime** -> Get the start time of the next maintain period - -**ListNodes** -> Get other peer information - -**ListWitnesses** -> Get all miner node information - -**BroadcastTransaction** -> Broadcast the transaction, where the transaction is in hex string format. - -## How to use tron-dex to sell asset - -### MarketSellAsset - -Create an order to sell asset - -> MarketSellAsset owner_address sell_token_id sell_token_quantity buy_token_id buy_token_quantity - -ownerAddress -> The address of the account that initiated the transaction - -sell_token_id, sell_token_quantity -> ID and amount of the token want to sell - -buy_token_id, buy_token_quantity -> ID and amount of the token want to buy - -Example: - -```console -MarketSellAsset TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW 1000001 200 _ 100 - -Get the result of the contract execution with the getTransactionInfoById command: -getTransactionInfoById 10040f993cd9452b25bf367f38edadf11176355802baf61f3c49b96b4480d374 - -{ - "id": "10040f993cd9452b25bf367f38edadf11176355802baf61f3c49b96b4480d374", - "blockNumber": 669, - "blockTimeStamp": 1578983493000, - "contractResult": [ - "" - ], - "receipt": { - "net_usage": 264 - } -} -``` - -### GetMarketOrderByAccount - -Get the order created by account(just include active status) - -> GetMarketOrderByAccount ownerAddress - -ownerAddress -> The address of the account that created market order - -Example: - -```console -GetMarketOrderByAccount TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW -{ - "orders": [ - { - "order_id": "fc9c64dfd48ae58952e85f05ecb8ec87f55e19402493bb2df501ae9d2da75db0", - "owner_address": "TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW", - "create_time": 1578983490000, - "sell_token_id": "_", - "sell_token_quantity": 100, - "buy_token_id": "1000001", - "buy_token_quantity": 200, - "sell_token_quantity_remain": 100 - } - ] -} -``` - -### GetMarketOrderById - -Get the specific order by order_id - -> GetMarketOrderById orderId - -Example: - -```console -GetMarketOrderById fc9c64dfd48ae58952e85f05ecb8ec87f55e19402493bb2df501ae9d2da75db0 -{ - "order_id": "fc9c64dfd48ae58952e85f05ecb8ec87f55e19402493bb2df501ae9d2da75db0", - "owner_address": "TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW", - "create_time": 1578983490000, - "sell_token_id": "_", - "sell_token_quantity": 100, - "buy_token_id": "1000001", - "buy_token_quantity": 200, -} -``` - -### GetMarketPairList - -Get market pair list - -Example: - -```console -GetMarketPairList -{ - "orderPair": [ - { - "sell_token_id": "_", - "buy_token_id": "1000001" - } - ] -} -``` - -### GetMarketOrderListByPair - -Get order list by pair - -> GetMarketOrderListByPair sell_token_id buy_token_id - -sell_token_id -> ID of the token want to sell - -buy_token_id -> ID of the token want to buy - -Example: - -```console -GetMarketOrderListByPair _ 1000001 -{ - "orders": [ - { - "order_id": "fc9c64dfd48ae58952e85f05ecb8ec87f55e19402493bb2df501ae9d2da75db0", - "owner_address": "TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW", - "create_time": 1578983490000, - "sell_token_id": "_", - "sell_token_quantity": 100, - "buy_token_id": "1000001", - "buy_token_quantity": 200, - "sell_token_quantity_remain": 100 - } - ] -} -``` - -### GetMarketPriceByPair - -Get market price by pair - -> GetMarketPriceByPair sell_token_id buy_token_id - -sell_token_id -> ID of the token want to sell - -buy_token_id -> ID of the token want to buy - -Example: - -```console -GetMarketPriceByPair _ 1000001 -{ - "sell_token_id": "_", - "buy_token_id": "1000001", - "prices": [ - { - "sell_token_quantity": 100, - "buy_token_quantity": 200 - } - ] -} -``` - -### MarketCancelOrder - -Cancel the order - -> MarketCancelOrder owner_address order_id - -owner_address -> the account address who have created the order - -order_id -> the order id which want to cancel - -Example: - -```console -MarketCancelOrder TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW fc9c64dfd48ae58952e85f05ecb8ec87f55e19402493bb2df501ae9d2da75db0 -``` - -Get the result of the contract execution with the getTransactionInfoById command: -```console -getTransactionInfoById b375787a098498623403c755b1399e82910385251b643811936d914c9f37bd27 -{ - "id": "b375787a098498623403c755b1399e82910385251b643811936d914c9f37bd27", - "blockNumber": 1582, - "blockTimeStamp": 1578986232000, - "contractResult": [ - "" - ], - "receipt": { - "net_usage": 283 - } -} +$ git clone https://github.com/tronprotocol/wallet-cli.git +$ cd wallet-cli && ./gradlew build && cd build/libs +$ java -jar wallet-cli.jar # opens the interactive prompt +> RegisterWallet 123456 # create a keystore (password 123456) +> Login # unlock it +> GetAddress # your TRON address +> GetBalance # TRX balance ``` -### Address book -> AddressBook -Addition, deletion, modification, and search of address book. +Full setup (config.conf, connecting to a node), the complete A–Z command list, and features like GasFree and multi-sig live in **[java/README.md](java/README.md)** — jump to [Setup](java/README.md#setup), [Quickstart](java/README.md#quickstart), [Commands](java/README.md#commands), or [GasFree](java/README.md#gasfree). -Example: -```console -wallet> AddressBook - -MAIN MENU: -1. addAddress -2. editAddress -3. delAddress -4. getAddressBook -Select option: 1 -``` -### show receiving qr code -> show-receiving-qr-code - -Display Receive Payment QR Code for the current address. -Executing this command requires installing 'qrencode' on the terminal in advance. -Debian/Ubuntu: -sudo apt install qrencode -CentOS: -sudo yum install qrencode -RHEL/Fedora: -sudo dnf install qrencode -macOS: -brew install qrencode - -Example: -```console -wallet> ShowReceivingQrCode -█████████████████████████████████████ -████ ▄▄▄▄▄ ██▄▀▀ ▄ ▀▄▀ ▀▀█ ▄▄▄▄▄ ████ -████ █ █ █▄ ▀▄ ▀▄▀▀███ █ █ ████ -████ █▄▄▄█ ██▀▄██▀▄▀▄▀ ▀██ █▄▄▄█ ████ -████▄▄▄▄▄▄▄█ ▀ █ ▀ ▀ ▀ ▀ █▄▄▄▄▄▄▄████ -████▄ █▄▄▄▄▄█ ██ ▀▀██▀ ██▀▄▀▀████ -████▄█▀▄█▀▄▀▄▄█▀█▄█▀▄ █▀██▄ █▄▄ ▄████ -████ █▄█▄ ▄▄▄██▀ ▀█▀▄██▄█▄▄ █ █ ▄████ -████ ▄▀▄▀▄▄▀ ▄█▄ ▀ ▀█ █ ██▀▀█▄▄▄████ -████▄█▀ ██▄██ ▄ ██ ██ █ ▄▄▄ ▄████ -████▄▀▀ ▀█▄█▀▄▀▀█▄█▄█▀ ▀▄▀█ ▄▄▄ ▄████ -████▄██▄█▄▄▄▀ ▄▀ ▀██ ▄▄ ▄▄▄ ▄▄▄████ -████ ▄▄▄▄▄ █ █▀▄ ▀ █▄▀▄ █▄█ ▄█▄ ████ -████ █ █ █▄▀▀ ██ ▄▄ █ ▄ ▄▄▄██████ -████ █▄▄▄█ █ ▀█▀█▄█▄▀▀█▄ ▄█ ██▀▄████ -████▄▄▄▄▄▄▄█▄▄██▄██ ▀▀▄▄▄▄█ ▀ ████ -█████████████████████████████████████ -TEDapYSVvAZ3aYH7w8N9tMEEFKaNKUD5Bp -``` -### get usdt balance -> GetUSDTBalance - -Get the current USDT balance of the account. - -Example: -```console -wallet> getusdtbalance -balanceOf(address):70a08231 -Execution result = { - "constant_result": [ - "0000000000000000000000000000000000000000000000000000000000000000" - ], - "result": { - "result": true - }, - "energy_used": 4062, - "energy_penalty": 3127 -} -USDT balance = 0 -``` -### get usdt transfer by id -> GetUsdtTransferById - -Get USDT transfer transaction summary based on transaction ID. - -Example: -```console -wallet> GetUsdtTransferById b0044dcb188568d11e77da926d96630f3e878583c5d5f4b3a72d2b984802143a -{ - "id":"b0044dcb188568d11e77da926d96630f3e878583c5d5f4b3a72d2b984802143a", - "type":"TriggerSmartContract(transferUSDT)", - "from":"TUUSMd58eC3fKx3fn7whxJyr1FR56tgaP8", - "to":"TGDjv2KKD4UqEmFTnZgLzup5WWjTex4Mvq", - "amount":100, - "tronscanQueryUrl":"https://nile.tronscan.org/#/transaction/b0044dcb188568d11e77da926d96630f3e878583c5d5f4b3a72d2b984802143a" -} -``` -### transfer usdt -> TransferUSDT - -Make a USDT transfer. +## TypeScript — get a taste -Example: -```console -wallet> transferusdt TR311sD6KasRnofj5RnFiFBA2rH8RH2kYk 1 -balanceOf(address):70a08231 -Execution result = { - "constant_result": [ - "000000000000000000000000000000000000000000000000000000006544ae57" - ], - "result": { - "result": true - }, - "energy_used": 935 -} -USDT balance = 1698999895 -transfer(address,uint256):a9059cbb -It is estimated that 345 bandwidth and 29650 energy will be consumed. -Execution result = { - "constant_result": [ - "0000000000000000000000000000000000000000000000000000000000000000" - ], - "result": { - "result": true - }, - "energy_used": 29650, - "logs": [ - { - "address": "NaMomAhUzuFzMNFzzQHVNsR8xbmP3A5LT", - "topics": [ - "ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef", - "000000000000000000000000caf9798d70a3c609b600f163e53cfe8f586e1b9f", - "000000000000000000000000a5418b8da12e73075abb46375e7a15c758ea21fc" - ], - "data": "0000000000000000000000000000000000000000000000000000000000000001" - } - ] -} -{ - "raw_data":{ - "contract":[ - { - "parameter":{ - "value":{ - "data":"a9059cbb000000000000000000000041a5418b8da12e73075abb46375e7a15c758ea21fc0000000000000000000000000000000000000000000000000000000000000001", - "owner_address":"TUUSMd58eC3fKx3fn7whxJyr1FR56tgaP8", - "contract_address":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf" - }, - "type_url":"type.googleapis.com/protocol.TriggerSmartContract" - }, - "type":"TriggerSmartContract" - } - ], - "ref_block_bytes":"08c7", - "ref_block_hash":"c02252c2ae3b92e1", - "expiration":1761639507000, - "fee_limit":1000000000, - "timestamp":1761639448851 - }, - "raw_data_hex":"0a0208c72208c02252c2ae3b92e140b8c896cfa2335aae01081f12a9010a31747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e54726967676572536d617274436f6e747261637412740a1541caf9798d70a3c609b600f163e53cfe8f586e1b9f121541eca9bc828a3005b9a3b909f2cc5c2a54794de05f2244a9059cbb000000000000000000000041a5418b8da12e73075abb46375e7a15c758ea21fc000000000000000000000000000000000000000000000000000000000000000170938293cfa23390018094ebdc03" -} -Before sign transaction hex string is 0ad4010a0208c72208c02252c2ae3b92e140b8c896cfa2335aae01081f12a9010a31747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e54726967676572536d617274436f6e747261637412740a1541caf9798d70a3c609b600f163e53cfe8f586e1b9f121541eca9bc828a3005b9a3b909f2cc5c2a54794de05f2244a9059cbb000000000000000000000041a5418b8da12e73075abb46375e7a15c758ea21fc000000000000000000000000000000000000000000000000000000000000000170938293cfa23390018094ebdc03 -Please confirm and input your permission id, if input y/Y means default 0, other non-numeric characters will cancel transaction. -y -Please choose your key for sign. - -No. Address Name -1 TUUSMd58eC3fKx3fn7whxJyr1FR56tgaP8 test -Please choose No. between 1 and 1, or enter search to search wallets -1 -Please input your password. -Lxc1992117 -After sign transaction hex string is 0ad4010a0208c72208c02252c2ae3b92e1409fb0b9d9a2335aae01081f12a9010a31747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e54726967676572536d617274436f6e747261637412740a1541caf9798d70a3c609b600f163e53cfe8f586e1b9f121541eca9bc828a3005b9a3b909f2cc5c2a54794de05f2244a9059cbb000000000000000000000041a5418b8da12e73075abb46375e7a15c758ea21fc000000000000000000000000000000000000000000000000000000000000000170938293cfa23390018094ebdc031241a776830e5cd054c6a94631b6d62704e249e7587ab3f036e5e4fac15cbf49e671262532e094e1a32ad858272da3e101958102df61b0f72f26756a94b608883a6f01 -TxId is 9c8d4b84e9a71ccaad86b0a96f790067d3fc7ea85c26b425e5d748b81d31a8b8 -Transfer 1 to TR311sD6KasRnofj5RnFiFBA2rH8RH2kYk broadcast successful. -Please check the given transaction id to get the result on blockchain using getTransactionInfoById command. -``` -### tronlink multi sign -> TronlinkMultiSign - -Create multi sign transactions and view the multi sign transaction list through the tronlink service. - -Example: -```console -wallet> tronlinkmultisign - -=== Multi-Sign Manager === -1. Multi-sign transaction list -2. Create multi-sign transaction -0. Exit -Please enter the number to operate: -``` +Install from npm, then run subcommands directly from your shell: -### encoding converter -> EncodingConverter - -A Useful Encoding Converter. - -Example: ```console -wallet> EncodingConverter - -============================== - Encoding Converter (CLI) -============================== -1) TRON - EVM Address -2) Base64 Encode / Decode -3) Base58Check Encode / Decode -4) Public Key -> Address -5) Private Key -> Public Key & Address -0) Exit -> +$ npm install -g @tron-walletcli/wallet-cli +$ wallet-cli create --label main # prompts for a master password +$ wallet-cli account balance --network tron:nile +$ wallet-cli account balance -o json # one wallet-cli.result.v1 JSON frame ``` -### How to get privateKey through mnemonic -> GetPrivateKeyByMnemonic - -Get the private key through mnemonics. +Every command has a reference page, and the JSON contract, exit codes, and agent integration are documented in depth. Start at **[ts/README.md](ts/README.md)**, then: -Example: -```console -wallet> GetPrivateKeyByMnemonic - -Please enter 12 or 24 words (separated by spaces) [Attempt 1/3]: -``` -### Get paginated now witness list -> GetPaginatedNowWitnessList +- [Getting started](ts/docs/guide/getting-started.md) — create a wallet and send your first transaction +- [Command reference](ts/docs/commands/index.md) — every command, A–Z +- [Machine interface](ts/docs/machine-interface.md) — JSON envelope, exit codes, script safety +- [Agent skill](ts/skills/wallet-cli/SKILL.md) — for AI agents -Get paginated now witness list. +## Which should I use? -Example: -```console -wallet> getPaginatedNowWitnessList 0 2 -{ - "witnesses": [ - { - "address": "TJmka325yjJKeFpQDwKSQAoNwEyNGhsaEV", - "voteCount": 5405926918, - "url": "http://sr-8.com", - "totalProduced": 1801675, - "totalMissed": 456, - "latestBlockNum": 64577529, - "latestSlotNum": 590063589, - "isJobs": true - }, - { - "address": "TFFLWM7tmKiwGtbh2mcz2rBssoFjHjSShG", - "voteCount": 2322244615, - "url": "http://sr-27.com", - "totalProduced": 1807756, - "totalMissed": 619, - "latestBlockNum": 64577530, - "latestSlotNum": 590063590, - "isJobs": true - } - ] -} -``` \ No newline at end of file +- **Scripting, CI, or building an AI agent?** → the [TypeScript version](ts/README.md) — the JSON envelope and deterministic exit codes exist for exactly this. +- **Working interactively and want the complete TRON toolkit** — GasFree, TRC10 issuance, on-chain DEX/governance, or multi-sig? → the [Java version](java/README.md). +- **Just sending TRX/tokens or staking from your own machine?** → either works; the TypeScript CLI is the lighter install (`npm install -g`, no build step). diff --git a/java/.gitignore b/java/.gitignore new file mode 100644 index 00000000..74ed3812 --- /dev/null +++ b/java/.gitignore @@ -0,0 +1,27 @@ +# Build output +build +out +bin +.gradle +logs +FileTest + +# Generated sources +src/gen +src/genjs +src/main/genjs/api +src/main/genjs/core +src/main/resources/static/js/tronjs/tron-protoc.js + +# Wallet keystore files created at runtime +Wallet/ +Mnemonic/ +wallet_data/ + +# QA runtime output +qa/results/ +qa/runtime/ +qa/report.txt +qa/.verify.lock/ + +docs/superpowers diff --git a/java/README.md b/java/README.md new file mode 100644 index 00000000..b64f438f --- /dev/null +++ b/java/README.md @@ -0,0 +1,2783 @@ +# 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). + +> 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) · [Contents](#contents) · [Commands](#commands) · [Configuration](#configuration) · [GasFree](#gasfree) + +Need help? Join the [Telegram developer group](https://t.me/TronOfficialDevelopersGroupEn). + +## Setup + +### Download Wallet-cli + + 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: + +``` +net { + type = mainnet +} + +fullnode = { + ip.list = [ + "fullnode ip : port" + ] +} +``` + +You can also switch networks at runtime with the `SwitchNetwork` command — see [Switch network](#switch-network) — so editing `config.conf` is only needed for a custom node or the advanced features below. + +
+Full annotated config — optional Solidity node, Ledger debug, account lock, GasFree, TronGrid API key, TronLink multi-sig, and record limits + +``` +net { + type = mainnet +} + +fullnode = { + ip.list = [ + "fullnode ip : port" + ] +} + +#soliditynode = { +# //The IPs in this list can only be totally set to solidity. +# ip.list = [ +# "ip : solidity port" // default solidity +# ] +# // NOTE: solidity node is optional +#} + +# open ledger debug +# ledger_debug = true + +# To use the lock and unlock function of the login account, it is necessary to configure +# lockAccount = true in the config.conf. The current login account is locked, which means that +# signatures and transactions are not allowed. After the current login account is locked, it can be +# unlocked. By default, it will be unlocked again after 300 seconds. Unlocking can specify +# parameters in seconds. + +# lockAccount = true + +# To use the gasfree feature, please first apply for an APIkey and apiSecret. +# For details, please refer to +# https://docs.google.com/forms/d/e/1FAIpQLSc5EB1X8JN7LA4SAVAG99VziXEY6Kv6JxmlBry9rUBlwI-GaQ/viewform +gasfree = { + mainnet = { + apiKey = "" + apiSecret = "" + } + testnet = { + apiKey = "" + apiSecret = "" + } +} + +# If gRPC requests on the main network are limited in speed, you can apply for an apiKey of Trongrid to improve the user experience +grpc = { + mainnet = { + apiKey = "" + } +} + +# Set the maximum number of transactions and backup records that can be retained +maxRecords = 1000 + +# To use the tronlink multi-sign feature, please first apply for an secretId and secretKey. +# For details, please refer to +# https://docs.google.com/forms/d/e/1FAIpQLSc5EB1X8JN7LA4SAVAG99VziXEY6Kv6JxmlBry9rUBlwI-GaQ/viewform +# If you prefer not to apply, a speed-limited secretId and secretKey will be provided for use: +# secretId = "TEST", secretKey = "TESTTESTTEST", channel = "test". +tronlink = { + mainnet = { + secretId = "" + secretKey = "" + channel = "" + } + testnet = { + secretId = "" + secretKey = "" + channel = "" + } +} +``` + +
+ +### Build and run + +- connect to fullNode + + Take a look at: [java-tron deployment](https://tronprotocol.github.io/documentation-en/developers/deployment/) + Run fullNode on either your local PC or a remote server. + +- compile and run web wallet + + ```console + $ cd wallet-cli + $ ./gradlew build + $ cd build/libs + $ java -jar wallet-cli.jar + ``` + +### Connect to Java-tron + +Wallet-cli connects to Java-tron via the gRPC protocol, which can be deployed locally or remotely. Check the **Build and run** section. +We can configure Java-tron node IP and port in ``src/main/resources/config.conf``, so that wallet-cli server can successfully talk to java-tron nodes. +Besides that, you can simply use `SwitchNetwork` command to switch among the mainnet, testnets(Nile and Shasta) and custom networks. Please refer to the Switch Network section. + +## Quickstart + +Build, create an account, and send your first transfer — all from the interactive prompt: + +```console +# 1. Build +$ git clone https://github.com/tronprotocol/wallet-cli.git +$ cd wallet-cli && ./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 +> Login # unlock the account +> GetAddress # show your address +> GetBalance # TRX balance + +# 4. Send 1 TRX (amounts are in SUN; 1 TRX = 1,000,000 SUN) +> SendCoin 1000000 +``` + +> 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. + +## Contents + +Grouped by task — see the [alphabetical command index](#commands) below for a full A–Z list. + +- **Setup** — [Setup](#setup) · [Quickstart](#quickstart) · [Build and run](#build-and-run) · [Switch network](#switch-network) · [Current network](#current-network) +- **Wallets & accounts** — [Create account](#how-to-create-account) · [Wallet commands](#wallet-related-commands) · [Account commands](#account-related-commands) · [Sub accounts](#generate-sub-account) · [Import/export mnemonic](#import-and-export-mnemonic) · [Import/export keystore](#export-import-wallet-keystore) · [Import by Ledger](#import-wallet-by-ledger) · [Login all](#login-all) / [Logout](#logout) · [Lock](#lock) / [Unlock](#unlock) +- **Transfers & tokens** — [Issue a TRC10 token](#how-to-issue-a-trc10-token) · [TRC10 token info](#how-to-obtain-trc10-token-information) · [Get USDT balance](#get-usdt-balance) · [Transfer USDT](#transfer-usdt) · [Address book](#address-book) +- **Staking & resources** — [FreezeV2 (Stake 2.0)](#how-to-freezev2) · [Delegate resource](#how-to-delegate-resource) · [Freeze/unfreeze (Stake 1.0, legacy)](#how-to-freezeunfreeze-balance) · [Bandwidth](#how-to-calculate-bandwidth) · [Resource prices & memo fee](#get-resource-prices-and-memo-fee) · [Withdraw balance](#how-to-withdraw-balance) +- **Voting & rewards** — [Vote](#how-to-vote) · [Brokerage & rewards](#brokerage) · [Create witness](#how-to-create-witness) +- **Smart contracts** — [Use smart contracts](#how-to-use-smart-contract) +- **Governance & exchange** — [Proposals](#how-to-operate-with-proposal) · [On-chain exchange](#how-to-trade-on-the-exchange) · [TRON-DEX (market)](#how-to-use-tron-dex-to-sell-asset) · [Multi-signature](#how-to-use-the-multi-signature-feature-of-wallet-cli) +- **GasFree** — [GasFree support](#gasfree) +- **Chain data** — [Transaction info](#how-to-get-transaction-information) · [Block info](#how-to-get-block-information) · [Chain parameters](#get-chain-parameters) + +## Commands + +The alphabetical index below links every command to its section. For usage of a specific command, just type it in the terminal after you start the wallet. + +| [AddTransactionSign](#How-to-use-the-multi-signature-feature-of-wallet-cli) | [AddressBook](#address-book) | [ApproveProposal](#Approve--disapprove-a-proposal) | +|:--------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------:|:-----------------------------------------------------------------------------------:| +| [AssetIssue](#Issue-trc10-tokens) | [BackupWallet](#Wallet-related-commands) | [BackupWallet2Base64](#Wallet-related-commands) | +| [BroadcastTransaction](#Some-others) | [CancelAllUnfreezeV2](#How-to-freezev2) | [ChangePassword](#Wallet-related-commands) | +| [ClearContractABI](#clear-contract-abi) | [ClearWalletKeystore](#clear-wallet-keystore) | [Create2](#create2) | +| [CreateAccount](#create-account) | [CreateProposal](#Initiate-a-proposal) | [CreateWitness](#create-witness) | +| [CurrentNetwork](#current-network) | [DelegateResource](#How-to-freezev2) | [DeleteProposal](#Delete-an-existed-proposal) | +| [DeployContract](#How-to-use-smart-contract) | [EstimateEnergy](#estimate-energy) | [ExchangeCreate](#How-to-trade-on-the-exchange) | +| [ExchangeInject](#How-to-trade-on-the-exchange) | [ExchangeTransaction](#How-to-trade-on-the-exchange) | [ExchangeWithdraw](#How-to-trade-on-the-exchange) | +| [ExportWalletKeystore](#export-import-wallet-keystore) | [ExportWalletMnemonic](#import-and-export-mnemonic) | [FreezeBalance](#Delegate-resource) | +| [FreezeBalanceV2](#How-to-freezev2) | [GasFreeInfo](#gas-free-info) | [GasFreeTrace](#gas-free-trace) | +| [GasFreeTransfer](#gas-free-transfer) | [GenerateAddress](#Account-related-commands) | [GenerateSubAccount](#generate-sub-account) | +| [GetAccount](#Account-related-commands) | [GetAccountById](#get-account-by-id) | [GetAccountNet](#Account-related-commands) | +| [GetAccountResource](#Account-related-commands) | [GetAddress](#Account-related-commands) | [GetAssetIssueByAccount](#How-to-obtain-trc10-token-information) | +| [GetAssetIssueById](#How-to-obtain-trc10-token-information) | [GetAssetIssueByName](#How-to-obtain-trc10-token-information) | [GetAssetIssueListByName](#How-to-obtain-trc10-token-information) | +| [GetAvailableUnfreezeCount](#How-to-freezev2) | [GetBalance](#Account-related-commands) | [GetBandwidthPrices](#Get-resource-prices-and-memo-fee) | +| [GetBlock](#How-to-get-block-information) | [GetBlockById](#How-to-get-block-information) | [GetBlockByIdOrNum](#How-to-get-block-information) | +| [GetBlockByLatestNum](#How-to-get-block-information) | [GetBlockByLimitNext](#How-to-get-block-information) | [GetBrokerage](#Brokerage) | +| [GetCanDelegatedMaxSize](#How-to-freezev2) | [GetCanWithdrawUnfreezeAmount](#How-to-freezev2) | [GetChainParameters](#get-chain-parameters) | +| [GetContract](#Get-details-of-a-smart-contract) | [GetContractInfo](#get-info-of-a-smart-contract) | [GetDelegatedResource](#How-to-delegate-resource) | +| [GetDelegatedResourceAccountIndex](#How-to-delegate-resource) | [GetDelegatedResourceAccountIndexV2](#How-to-freezev2) | [GetDelegatedResourceV2](#How-to-freezev2) | +| [GetEnergyPrices](#Get-resource-prices-and-memo-fee) | [GetExchange](#get-exchange-by-id) | [GetMarketOrderByAccount](#How-to-use-tron-dex-to-sell-asset) | +| [GetMarketOrderById](#How-to-use-tron-dex-to-sell-asset) | [GetMarketOrderListByPair](#How-to-use-tron-dex-to-sell-asset) | [GetMarketPairList](#How-to-use-tron-dex-to-sell-asset) | +| [GetMarketPriceByPair](#How-to-use-tron-dex-to-sell-asset) | [GetMemoFee](#Get-resource-prices-and-memo-fee) | [GetNextMaintenanceTime](#Some-others) | +| [GetProposal](#Obtain-proposal-information) | [GetReward](#Brokerage) | [GetTransactionApprovedList](#How-to-use-the-multi-signature-feature-of-wallet-cli) | +| [GetTransactionById](#How-to-get-transaction-information) | [GetTransactionCountByBlockNum](#How-to-get-transaction-information) | [GetTransactionInfoByBlockNum](#How-to-get-transaction-information) | +| [GetTransactionInfoById](#How-to-get-transaction-information) | [GetTransactionSignWeight](#How-to-use-the-multi-signature-feature-of-wallet-cli) | [GetUSDTBalance](#get-usdt-balance) | +| [GetUsdtTransferById](#get-usdt-transfer-by-id) | [ImportWallet](#Wallet-related-commands) | [ImportWalletByBase64](#Wallet-related-commands) | +| [ImportWalletByKeystore](#export-import-wallet-keystore) | [ImportWalletByLedger](#import-wallet-by-ledger) | [ImportWalletByMnemonic](#import-and-export-mnemonic) | +| [ListAssetIssue](#How-to-obtain-trc10-token-information) | [ListAssetIssuePaginated](#list-asset-issue-paginated) | [ListExchanges](#How-to-trade-on-the-exchange) | +| [ListExchangesPaginated](#How-to-trade-on-the-exchange) | [ListNodes](#Some-others) | [ListProposals](#Obtain-proposal-information) | +| [ListProposalsPaginated](#Obtain-proposal-information) | [ListWitnesses](#Some-others) | [Lock](#lock) | +| [Login](#Command-line-operation-flow-example) | [LoginAll](#login-all) | [Logout](#logout) | +| [MarketCancelOrder](#How-to-use-tron-dex-to-sell-asset) | [MarketSellAsset](#How-to-use-tron-dex-to-sell-asset) | [ModifyWalletName](#Modify-wallet-name) | +| [ParticipateAssetIssue](#Participating-in-the-issue-of-trc10-token) | [RegisterWallet](#Wallet-related-commands) | [ResetWallet](#reset-wallet) | +| [SendCoin](#How-to-use-the-multi-signature-feature-of-wallet-cli) | [SetAccountId](#set-account-id) | [ShowReceivingQrCode](#show-receiving-qr-code) | +| [SwitchNetwork](#switch-network) | [SwitchWallet](#switch-wallet) | [TransferAsset](#Trc10-token-transfer) | +| [TransferUSDT](#transfer-usdt) | [TriggerConstantContract](#trigger-constant-contract) | [TriggerContract](#trigger-smart-contract) | +| [UnDelegateResource](#How-to-freezev2) | [UnfreezeAsset](#Unfreeze-trc10-token) | [UnfreezeBalance](#How-to-delegate-resource) | +| [UnfreezeBalanceV2](#How-to-freezev2) | [Unlock](#unlock) | [UpdateAccount](#update-account) | +| [UpdateAccountPermission](#How-to-use-the-multi-signature-feature-of-wallet-cli) | [UpdateAsset](#Update-parameters-of-trc10-token) | [UpdateBrokerage](#Brokerage) | +| [UpdateEnergyLimit](#Update-smart-contract-parameters) | [UpdateSetting](#Update-smart-contract-parameters) | [UpdateWitness](#update-witness) | +| [ViewBackupRecords](#View-backup-records) | [ViewTransactionHistory](#View-transaction-history) | [VoteWitness](#How-to-vote) | +| [WithdrawBalance](#withdraw-balance) | [WithdrawExpireUnfreeze](#withdraw-expire-unfreeze) | [TronlinkMultiSign](#tronlink-multi-sign) | +| [EncodingConverter](#encoding-converter) | [GetPrivateKeyByMnemonic](#How-to-get-privateKey-through-mnemonic) | [GetPaginatedNowWitnessList](#Get-paginated-now-witness-list) | + + +Type any one of the listed commands, to display how-to tips. + +## How to freeze/unfreeze balance + +After the funds are frozen, the corresponding number of shares and bandwidth will be obtained. +Shares can be used for voting and bandwidth can be used for trading. +The rules for the use and calculation of share and bandwidth are described later in this article. + +**Freeze operation is as follows:** + +```console +> freezeBalance [OwnerAddress] frozen_balance frozen_duration [ResourceCode:0 BANDWIDTH, 1 ENERGY] [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(1TRX)**. + +frozen_duration +> Freeze time, this value is currently only allowed for **3 days**. + +For example: + +```console +> freezeBalance 100000000 3 1 address +``` + +After the freeze operation, frozen funds will be transferred from Account Balance to Frozen, +You can view frozen funds from your account information. +After being unfrozen, it is transferred back to Balance by Frozen, and the frozen funds cannot be used for trading. + +When more share or bandwidth is needed temporarily, additional funds may be frozen to obtain additional share and bandwidth. +The unfrozen time is postponed until 3 days after the last freeze operation + +After the freezing time expires, funds can be unfroze. + +**Unfreeze operation is as follows:** + +```console +> unfreezeBalance [OwnerAddress] ResourceCode(0 BANDWIDTH, 1 CPU) [receiverAddress] +``` + +## How to vote + +Voting requires share. Share can be obtained by freezing funds. + +- The share calculation method is: **1** unit of share can be obtained for every **1TRX** frozen. +- After unfreezing, previous vote will expire. You can avoid the invalidation of the vote by re-freezing and voting. + +**NOTE** The Tron Network only records the status of your last vote, which means that each of your votes will overwrite all previous voting results. + +For example: + +```console +> freezeBalance 100000000 3 1 address # Freeze 10TRX 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 + +> votewitness 123455 witness1 10 # Voted 10 votes for witness1 +``` + +The final result of the above command was 10 votes for witness1 and 0 vote for witness2. + +## Brokerage + +After voting for the witness, you will receive the rewards. The witness has the right to decide the ratio of brokerage. The default ratio is 20%, and the witness can adjust it. + +By default, if a witness is rewarded, he will receive 20% of the whole rewards, and 80% of the rewards will be distributed to his voters. + +### GetBrokerage + +View the ratio of brokerage of the witness. + + > getbrokerage OwnerAddress + +OwnerAddress +> The address of the witness's account, it is a base58check type address. + +### GetReward + +Query unclaimed reward. + + > getreward OwnerAddress + +OwnerAddress +> The address of the voter's account, it is a base58check type address. + +### UpdateBrokerage + +Update the ratio of brokerage, this command is usually used by a witness account. + + > updateBrokerage OwnerAddress brokerage + +OwnerAddress +> The witness's account address is a base58check type address. + +brokerage +> The ratio of brokerage you want to update, from 0 to 100. If the input is 10, it means 10% of the total reward would be distributed to the SR and the rest would be rewarded to all the voters, which is 90% in this case + +For example: + +```console +> getbrokerage TZ7U1WVBRLZ2umjizxqz3XfearEHhXKX7h + +> getreward TNfu3u8jo1LDWerHGbzs2Pv88Biqd85wEY + +> updateBrokerage TZ7U1WVBRLZ2umjizxqz3XfearEHhXKX7h 30 +``` + +### withdraw balance + +> WithdrawBalance [owner_address] + +Withdraw voting or block rewards. + +Example: + +```console +> WithdrawBalance TEDapYSVvAZ3aYH7w8N9tMEEFKaNKUD5Bp +``` + +## How to calculate bandwidth + +The bandwidth calculation rule is: + + constant * FrozenFunds * days + +Assuming freeze 1TRX（1_000_000 Sun), 3 days, bandwidth obtained = 1 * 1_000_000 * 3 = 3_000_000. + +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**. + +If a contract exceeds a certain time (**10s**), this operation does not consume bandwidth. + +When the unfreezing operation occurs, the bandwidth is not cleared. +The next time the freeze is performed, the newly added bandwidth is accumulated. + +## How to withdraw balance + +After each block is produced, the block award is sent to the account's allowance, +and a withdraw operation is allowed every **24 hours** from allowance to balance. +The funds in allowance cannot be locked or traded. + +## How to create witness + +Applying to become a witness account needs to consume **100_000TRX**. +This part of the funds will be burned directly. + +### create witness +> CreateWitness [owner_address] url +Apply to become a super representative candidate. + +Example: +```console +> CreateWitness TEDapYSVvAZ3aYH7w8N9tMEEFKaNKUD5Bp 007570646174654e616d6531353330363038383733343633 +``` + +### update witness +> UpdateWitness +Edit the URL of the SR's official website. + +Example: +```console +> UpdateWitness TEDapYSVvAZ3aYH7w8N9tMEEFKaNKUD5Bp 007570646174654e616d6531353330363038383733343633 +``` + +## How to create account + +You can create accounts by transferring funds to non-existing accounts or initiating a transaction to create an account using the **CreateAccount** command. +Transferring to a non-existent account has minimum restriction amount of **1TRX**. +Creating an account through the CreateAccount command will still burn **1TRX**. + + +## Command line operation flow example + +```console +$ cd wallet-cli +$ ./gradlew build +$ ./gradlew run +> RegisterWallet 123456 (password = 123456) +> login 123456 +> getAddress +address = TRfwwLDpr4excH4V4QzghLEsdYwkapTxnm' # backup it! +> BackupWallet 123456 +priKey = 1234567890123456789012345678901234567890123456789012345678901234 # backup it!!! (BackupWallet2Base64 option) +> getbalance +Balance = 0 +> AssetIssue TestTRX TRX 75000000000000000 1 1 2 "2019-10-02 15:10:00" "2020-07-11" "just for test121212" www.test.com 100 100000 10000 10 10000 1 +> getaccount TRfwwLDpr4excH4V4QzghLEsdYwkapTxnm +(Print balance: 9999900000 +"assetV2": [ + { + "key": "1000001", + "value": 74999999999980000 + } +],) + # (cost trx 1000 trx for assetIssue) + # (You can query the trx balance and other asset balances for any account ) +> TransferAsset TWzrEZYtwzkAxXJ8PatVrGuoSNsexejRiM 1000001 10000 +``` + +## How to issue a TRC10 token + +Each account can only issue **ONE** TRC10 token. + +### Issue TRC10 tokens + +> AssetIssue [OwnerAddress] AssetName AbbrName TotalSupply TrxNum AssetNum Precision StartDate EndDate Description Url FreeNetLimitPerAccount PublicFreeNetLimit FrozenAmount0 FrozenDays0 [...] FrozenAmountN FrozenDaysN + +OwnerAddress (optional) +> The address of the account which initiated the transaction. +> Default: the address of the login account. + +AssetName +> The name of the issued TRC10 token + +AbbrName +> The abbreviation of TRC10 token + +TotalSupply +> TotalSupply = Account Balance of Issuer + All Frozen Token Amount +> TotalSupply: Total Issuing Amount +> Account Balance Of Issuer: At the time of issuance +> All Frozen Token Amount: Before asset transfer and the issuance + +TrxNum, AssetNum +> These two parameters determine the exchange rate when the token is issued. +> Exchange Rate = TrxNum / AssetNum +> AssetNum: Unit in base unit of the issued token +> TrxNum: Unit in SUN (0.000001 TRX) + +Precision +> Precision to how many decimal places + +FreeNetLimitPerAccount +> The maximum amount of bandwidth each account is allowed to use. Token issuers can freeze TRX to obtain bandwidth (TransferAssetContract only) + +PublicFreeNetLimit +> The maximum total amount of bandwidth which is allowed to use for all accounts. Token issuers can freeze TRX to obtain bandwidth (TransferAssetContract only) + +StartDate, EndDate +> The start and end date of token issuance. Within this period time, other users can participate in token issuance. + +FrozenAmount0 FrozenDays0 +> Amount and days of token freeze. +> FrozenAmount0: Must be bigger than 0 +> FrozenDays0: Must be between 1 and 3653. + +Example: + +```console +> AssetIssue TestTRX TRX 75000000000000000 1 1 2 "2019-10-02 15:10:00" "2020-07-11" "just for test121212" www.test.com 100 100000 10000 10 10000 1 +> GetAssetIssueByAccount TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ # View published information +{ + "assetIssue": [ + { + "owner_address": "TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ", + "name": "TestTRX", + "abbr": "TRX", + "total_supply": 75000000000000000, + "frozen_supply": [ + { + "frozen_amount": 10000, + "frozen_days": 1 + }, + { + "frozen_amount": 10000, + "frozen_days": 10 + } + ], + "trx_num": 1, + "precision": 2, + "num": 1, + "start_time": 1570000200000, + "end_time": 1594396800000, + "description": "just for test121212", + "url": "www.test.com", + "free_asset_net_limit": 100, + "public_free_asset_net_limit": 100000, + "id": "1000001" + } + ] +} +``` + +### Update parameters of TRC10 token + +> UpdateAsset [OwnerAddress] newLimit newPublicLimit description url + +Specific meaning of the parameters is the same as that of AssetIssue. + +Example: + +```console +> UpdateAsset 1000 1000000 "change description" www.changetest.com +> GetAssetIssueByAccount TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ # View the modified information +{ + "assetIssue": [ + { + "owner_address": "TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ", + "name": "TestTRX", + "abbr": "TRX", + "total_supply": 75000000000000000, + "frozen_supply": [ + { + "frozen_amount": 10000, + "frozen_days": 1 + }, + { + "frozen_amount": 10000, + "frozen_days": 10 + } + ], + "trx_num": 1, + "precision": 2, + "num": 1, + "start_time": 1570000200000, + "end_time": 1594396800000, + "description": "change description", + "url": "www.changetest.com", + "free_asset_net_limit": 1000, + "public_free_asset_net_limit": 1000000, + "id": "1000001" + } + ] +} +``` + +### TRC10 token transfer + +> TransferAsset [OwnerAddress] ToAddress AssertID Amount + +OwnerAddress (optional) +> The address of the account which initiated the transaction. +> Default: the address of the login account. + +ToAddress +> Address of the target account + +AssertName +> TRC10 token ID +> Example: 1000001 + +Amount +> The number of TRC10 token to transfer + +Example: + +```console +> TransferAsset TN3zfjYUmMFK3ZsHSsrdJoNRtGkQmZLBLz 1000001 1000 +> getaccount TN3zfjYUmMFK3ZsHSsrdJoNRtGkQmZLBLz # View target account information after the transfer +address: TN3zfjYUmMFK3ZsHSsrdJoNRtGkQmZLBLz + assetV2 + { + id: 1000001 + balance: 1000 + latest_asset_operation_timeV2: null + free_asset_net_usageV2: 0 + } +``` + +### Participating in the issue of TRC10 token + + > ParticipateAssetIssue [OwnerAddress] ToAddress AssetID Amount + +OwnerAddress (optional) +> The address of the account which initiated the transaction. +> Default: the address of the login account. + +ToAddress +> Account address of TRC10 issuers + +AssertName +> TRC10 token ID +> Example: 1000001 + +Amount +> The number of TRC10 token to transfers + +The participation process must happen during the release of TRC10, otherwise an error may occur. + +Example: + +```console +> ParticipateAssetIssue TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ 1000001 1000 +> getaccount TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW # View remaining balance +address: TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW +assetV2 + { + id: 1000001 + balance: 1000 + latest_asset_operation_timeV2: null + free_asset_net_usageV2: 0 + } +``` +### list asset issue paginated + +> ListAssetIssuePaginated address code salt + +Query the list of all the tokens by pagination.Returns a list of Tokens that succeed the Token located at offset. + +Example: + +```console +> ListAssetIssuePaginated 0 1 +``` + +### Unfreeze TRC10 token + +To unfreeze all TRC10 token which are supposed to be unfrozen after the freezing period. + + > unfreezeasset [OwnerAddress] + +## How to obtain TRC10 token information + +ListAssetIssue +> Obtain all of the published TRC10 token information + +GetAssetIssueByAccount +> Obtain TRC10 token information based on issuing address + +GetAssetIssueById +> Obtain TRC10 token Information based on ID + +GetAssetIssueByName +> Obtain TRC10 token Information based on names + +GetAssetIssueListByName +> Obtain a list of TRC10 token information based on names + +## How to operate with proposal + +Any proposal-related operations, except for viewing operations, must be performed by committee members. + +### Initiate a proposal + + > createProposal [OwnerAddress] id0 value0 ... idN valueN + +OwnerAddress (optional) +> The address of the account which initiated the transaction. +> Default: the address of the login account. + +id0 +> The serial number of the parameter. Every parameter of TRON network has a serial number. Please refer to "http://tronscan.org/#/sr/committee" + +Value0 +> The modified value + +In the example, modification No.4 (modifying token issuance fee) costs 1000TRX as follows: + +```console +> createProposal 4 1000 +> listproposals # View initiated proposal +{ + "proposals": [ + { + "proposal_id": 1, + "proposer_address": "TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ", + "parameters": [ + { + "key": 4, + "value": 1000 + } + ], + "expiration_time": 1567498800000, + "create_time": 1567498308000 + } + ] +} +``` + +The corresponding id is 1. + +### Approve / Disapprove a proposal + + > approveProposal [OwnerAddress] id is_or_not_add_approval + +OwnerAddress (optional) +> The address of the account which initiated the transaction. +> Default: the address of the login account. + +id +> ID of the initiated proposal +> Example: 1 + +is_or_not_add_approval +> true for approve; false for disapprove + +Example: + +```console +> ApproveProposal 1 true # in favor of the offer +> ApproveProposal 1 false # Cancel the approved proposal +``` + +### Delete an existed proposal + + > deleteProposal [OwnerAddress] proposalId + +proposalId +> ID of the initiated proposal +> Example: 1 + +The proposal must be canceled by the supernode that initiated the proposal. + +Example： + + > DeleteProposal 1 + +### Obtain proposal information + +ListProposals +> Obtain a list of initiated proposals + +ListProposalsPaginated +> Use the paging mode to obtain the initiated proposal + +GetProposal +> Obtain proposal information based on the proposal ID + +## How to trade on the exchange + +The trading and price fluctuations of trading pairs are in accordance with the Bancor Agreement, +which can be found in TRON's [related documents](https://tronprotocol.github.io/documentation-en/clients/wallet-cli-command/#dex). + +### Create a trading pair + +> exchangeCreate [OwnerAddress] first_token_id first_token_balance second_token_id second_token_balance + +OwnerAddress (optional) +> The address of the account which initiated the transaction. +> Default: the address of the login account. + +First_token_id, first_token_balance +> ID and amount of the first token + +second_token_id, second_token_balance +> ID and amount of the second token +> +> The ID is the ID of the issued TRC10 token. +> If it is TRX, the ID is "_". +> The amount must be greater than 0, and less than 1,000,000,000,000,000. + +Example: + +> exchangeCreate 1000001 10000 _ 10000 + # Create trading pairs with the IDs of 1000001 and TRX, with amount 10000 for both. + +### get exchange by id +> getExchange +Query exchange pair based on id (Confirmed state). + +Example: + +```console +> getExchange 1 +``` + +### Capital injection + +> exchangeInject [OwnerAddress] exchange_id token_id quant + +OwnerAddress (optional) +> The address of the account which initiated the transaction. +> Default: the address of the login account. + +exchange_id +> The ID of the trading pair to be funded + +token_id, quant +> TokenId and quantity (unit in base unit) of capital injection + +When conducting a capital injection, depending on its quantity (quant), a proportion +of each token in the trading pair will be withdrawn from the account, and injected into the trading +pair. Depending on the difference in the balance of the transaction, the same amount of money for +the same token would vary. + +### Transactions + +> exchangeTransaction [OwnerAddress] exchange_id token_id quant expected + +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. + +Example： + +> ExchangeTransaction 1 1000001 100 80 + +It is expected to acquire the 80 TRX by exchanging 1000001 from the trading pair ID of 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). + +### Capital Withdrawal + +> exchangeWithdraw [OwnerAddress] exchange_id token_id quant + +OwnerAddress (optional) +> The address of the account which initiated the transaction. +> Default: the address of the login account. + +Exchange_id + +> +The ID of the trading pair to be withdrawn + +Token_id, quant +> TokenId and quantity (unit in base unit) of capital withdrawal + +When conducting a capital withdrawal, depending on its quantity (quant), a proportion of each token +in the transaction pair is withdrawn from the trading pair, and injected into the account. Depending on the difference in the balance of the transaction, the same amount of money for the same token would vary. + +### Obtain information on trading pairs + +ListExchanges +> List trading pairs + +ListExchangesPaginated +> List trading pairs by page + +## 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 accesses: + +- owner: access to the owner of account +- active: access to other features of accounts, and access that authorizes a certain feature. Block production authorization is not included if it's for witness purposes. +- witness: only for witness, block production authorization will be granted to one of the other users. + +The rest of the users will be granted + +```console +> Updateaccountpermission TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ {"owner_permission":{"type":0,"permission_name":"owner","threshold":1,"keys":[{"address":"TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ","weight":1}]},"witness_permission":{"type":1,"permission_name":"witness","threshold":1,"keys":[{"address":"TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ","weight":1}]},"active_permissions":[{"type":2,"permission_name":"active12323","threshold":2,"operations":"7fff1fc0033e0000000000000000000000000000000000000000000000000000","keys":[{"address":"TNhXo1GbRNCuorvYu5JFWN3m2NYr9QQpVR","weight":1},{"address":"TKwhcDup8L2PH5r6hxp5CQvQzZqJLmKvZP","weight":1}]}]} +``` +or +```console +wallet> updateAccountPermission +=== UpdateAccountPermission Interactive Mode === + +Select permission to modify: +1. owner_permission +2. witness_permission +3. active_permissions +4. Add new active_permission +5. Delete active_permission +6. Show preview and Confirm +7. Exit +> +``` + +The account TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ gives the owner access to itself, active access to +TNhXo1GbRNCuorvYu5JFWN3m2NYr9QQpVR and TKwhcDup8L2PH5r6hxp5CQvQzZqJLmKvZP. Active access will +need signatures from both accounts in order to take effect. + +If the account is not a witness, it's not necessary to set witness_permission, otherwise an error will occur. + +### Signed transaction + +> SendCoin TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW 10000000000000000 + +Will show "Please confirm and input your permission id, if input y or Y means default 0, other +non-numeric characters will cancel transaction." + +This will require the transfer authorization of active access. Enter: 2 + +Then select accounts and put in local password, i.e. TNhXo1GbRNCuorvYu5JFWN3m2NYr9QQpVR needs a +private key TNhXo1GbRNCuorvYu5JFWN3m2NYr9QQpVR to sign a transaction. + +Select another account and enter the local password. i.e. TKwhcDup8L2PH5r6hxp5CQvQzZqJLmKvZP will +need a private key of TKwhcDup8L2PH5r6hxp5CQvQzZqJLmKvZP to sign a transaction. + +The weight of each account is 1, threshold of access is 2. When the requirements are met, users +will be notified with “Send 10000000000000000 Sun to TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW +successful !!”. + +This is how multiple accounts user multi-signature when using the same cli. +Use the instruction addTransactionSign according to the obtained transaction hex string if +signing at multiple cli. After signing, the users will need to broadcast final transactions +manually. + +## Obtain weight information according to transaction + + > getTransactionSignWeight + 0a8c010a020318220860e195d3609c86614096eadec79d2d5a6e080112680a2d747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e5472616e73666572436f6e747261637412370a1541a7d8a35b260395c14aa456297662092ba3b76fc01215415a523b449890854c8fc460ab602df9f31fe4293f18808084fea6dee11128027094bcb8bd9d2d1241c18ca91f1533ecdd83041eb0005683c4a39a2310ec60456b1f0075b4517443cf4f601a69788f001d4bc03872e892a5e25c618e38e7b81b8b1e69d07823625c2b0112413d61eb0f8868990cfa138b19878e607af957c37b51961d8be16168d7796675384e24043d121d01569895fcc7deb37648c59f538a8909115e64da167ff659c26101 + +The information displays as follows: + +```json +{ + "result":{ + "code":"PERMISSION_ERROR", + "message":"Signature count is 2 more than key counts of permission : 1" + }, + "permission":{ + "operations":"7fff1fc0033e0100000000000000000000000000000000000000000000000000", + "keys":[ + { + "address":"TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ", + "weight":1 + } + ], + "threshold":1, + "id":2, + "type":"Active", + "permission_name":"active" + }, + "transaction":{ + "result":{ + "result":true + }, + "txid":"7da63b6a1f008d03ef86fa871b24a56a501a8bbf15effd7aca635de6c738df4b", + "transaction":{ + "signature":[ + "c18ca91f1533ecdd83041eb0005683c4a39a2310ec60456b1f0075b4517443cf4f601a69788f001d4bc03872e892a5e25c618e38e7b81b8b1e69d07823625c2b01", + "3d61eb0f8868990cfa138b19878e607af957c37b51961d8be16168d7796675384e24043d121d01569895fcc7deb37648c59f538a8909115e64da167ff659c26101" + ], + "txID":"7da63b6a1f008d03ef86fa871b24a56a501a8bbf15effd7aca635de6c738df4b", + "raw_data":{ + "contract":[ + { + "parameter":{ + "value":{ + "amount":10000000000000000, + "owner_address":"TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ", + "to_address":"TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW" + }, + "type_url":"type.googleapis.com/protocol.TransferContract" + }, + "type":"TransferContract", + "Permission_id":2 + } + ], + "ref_block_bytes":"0318", + "ref_block_hash":"60e195d3609c8661", + "expiration":1554123306262, + "timestamp":1554101706260 + }, + "raw_data_hex":"0a020318220860e195d3609c86614096eadec79d2d5a6e080112680a2d747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e5472616e73666572436f6e747261637412370a1541a7d8a35b260395c14aa456297662092ba3b76fc01215415a523b449890854c8fc460ab602df9f31fe4293f18808084fea6dee11128027094bcb8bd9d2d" + } + } +} +``` + +### Get signature information according to transactions + + > getTransactionApprovedList + 0a8c010a020318220860e195d3609c86614096eadec79d2d5a6e080112680a2d747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e5472616e73666572436f6e747261637412370a1541a7d8a35b260395c14aa456297662092ba3b76fc01215415a523b449890854c8fc460ab602df9f31fe4293f18808084fea6dee11128027094bcb8bd9d2d1241c18ca91f1533ecdd83041eb0005683c4a39a2310ec60456b1f0075b4517443cf4f601a69788f001d4bc03872e892a5e25c618e38e7b81b8b1e69d07823625c2b0112413d61eb0f8868990cfa138b19878e607af957c37b51961d8be16168d7796675384e24043d121d01569895fcc7deb37648c59f538a8909115e64da167ff659c26101 + +```json +{ + "result":{ + + }, + "approved_list":[ + "TKwhcDup8L2PH5r6hxp5CQvQzZqJLmKvZP", + "TNhXo1GbRNCuorvYu5JFWN3m2NYr9QQpVR" + ], + "transaction":{ + "result":{ + "result":true + }, + "txid":"7da63b6a1f008d03ef86fa871b24a56a501a8bbf15effd7aca635de6c738df4b", + "transaction":{ + "signature":[ + "c18ca91f1533ecdd83041eb0005683c4a39a2310ec60456b1f0075b4517443cf4f601a69788f001d4bc03872e892a5e25c618e38e7b81b8b1e69d07823625c2b01", + "3d61eb0f8868990cfa138b19878e607af957c37b51961d8be16168d7796675384e24043d121d01569895fcc7deb37648c59f538a8909115e64da167ff659c26101" + ], + "txID":"7da63b6a1f008d03ef86fa871b24a56a501a8bbf15effd7aca635de6c738df4b", + "raw_data":{ + "contract":[ + { + "parameter":{ + "value":{ + "amount":10000000000000000, + "owner_address":"TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ", + "to_address":"TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW" + }, + "type_url":"type.googleapis.com/protocol.TransferContract" + }, + "type":"TransferContract", + "Permission_id":2 + } + ], + "ref_block_bytes":"0318", + "ref_block_hash":"60e195d3609c8661", + "expiration":1554123306262, + "timestamp":1554101706260 + }, + "raw_data_hex":"0a020318220860e195d3609c86614096eadec79d2d5a6e080112680a2d747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e5472616e73666572436f6e747261637412370a1541a7d8a35b260395c14aa456297662092ba3b76fc01215415a523b449890854c8fc460ab602df9f31fe4293f18808084fea6dee11128027094bcb8bd9d2d" + } + } +} +``` + +## How to use smart contract + +### deploy smart contracts + +> DeployContract [ownerAddress] contractName ABI byteCode constructor params isHex fee_limit consume_user_resource_percent origin_energy_limit value token_value token_id(e.g: TRXTOKEN, use # if don't provided) library:address,...> + +OwnerAddress +> The address of the account that initiated the transaction, optional, default is the address of the login account. + +contractName +> Name of smart contract + +ABI +> Compile generated ABI code + +byteCode +> Compile generated byte code + +constructor, params, isHex +> Define the format of the bytecode, which determines the way to parse byteCode from parameters + +fee_limit +> Transaction allows for the most consumed TRX + +consume_user_resource_percent +> Percentage of user resource consumed, in the range [0, 100] + +origin_energy_limit +> The most amount of developer Energy consumed by trigger contract once + +value +> The amount of trx transferred to the contract account + +token_value +> Number of TRX10 + +token_id +> TRX10 Id + +Example: + +``` +> deployContract normalcontract544 [{"constant":false,"inputs":[{"name":"i","type":"uint256"}],"name": "findArgsByIndexTest","outputs":[{"name":"z","type":"uint256"}],"payable":false,"stateMutability":"nonpayable","type":"function"}] +608060405234801561001057600080fd5b50610134806100206000396000f3006080604052600436106100405763ffffffff7c0100000000000000000000000000000000000000000000000000000000600035041663329000b58114610045575b600080fd5b34801561005157600080fd5b5061005d60043561006f565b60408051918252519081900360200190f35b604080516003808252608082019092526000916060919060208201838038833901905050905060018160008151811015156100a657fe5b602090810290910101528051600290829060019081106100c257fe5b602090810290910101528051600390829060029081106100de57fe5b6020908102909101015280518190849081106100f657fe5b906020019060200201519150509190505600a165627a7a72305820b24fc247fdaf3644b3c4c94fcee380aa610ed83415061ff9e65d7fa94a5a50a00029 # # false 1000000000 75 50000 0 0 # +``` + +Get the result of the contract execution with the getTransactionInfoById command: + +```console +> getTransactionInfoById 4978dc64ff746ca208e51780cce93237ee444f598b24d5e9ce0da885fb3a3eb9 +{ + "id": "8c1f57a5e53b15bb0a0a0a0d4740eda9c31fbdb6a63bc429ec2113a92e8ff361", + "fee": 6170500, + "blockNumber": 1867, + "blockTimeStamp": 1567499757000, + "contractResult": [ + "6080604052600436106100405763ffffffff7c0100000000000000000000000000000000000000000000000000000000600035041663329000b58114610045575b600080fd5b34801561005157600080fd5b5061005d60043561006f565b60408051918252519081900360200190f35b604080516003808252608082019092526000916060919060208201838038833901905050905060018160008151811015156100a657fe5b602090810290910101528051600290829060019081106100c257fe5b602090810290910101528051600390829060029081106100de57fe5b6020908102909101015280518190849081106100f657fe5b906020019060200201519150509190505600a165627a7a72305820b24fc247fdaf3644b3c4c94fcee380aa610ed83415061ff9e65d7fa94a5a50a00029" + ], + "contract_address": "TJMKWmC6mwF1QVax8Sy2AcgT6MqaXmHEds", + "receipt": { + "energy_fee": 6170500, + "energy_usage_total": 61705, + "net_usage": 704, + "result": "SUCCESS" + } +} +``` + +### trigger smart contract + +> TriggerContract [ownerAddress] contractAddress method args isHex fee_limit value token_value token_id + +OwnerAddress +> The address of the account that initiated the transaction, optional, default is the address of the login account. + +contractAddress +> Smart contract address + +method +> The name of function and parameters, please refer to the example + +args +> Parameter value, if you want to call `receive`, pass '#' instead + +isHex +> The format of the parameters method and args, is hex string or not + +fee_limit +> The most amount of trx allows for the consumption + +token_value +> Number of TRX10 + +token_id +> TRC10 id, If not, use ‘#’ instead + +Example: + +```console +> triggerContract TGdtALTPZ1FWQcc5MW7aK3o1ASaookkJxG findArgsByIndexTest(uint256) 0 false +1000000000 0 0 # +# Get the result of the contract execution with the getTransactionInfoById command +> getTransactionInfoById 7d9c4e765ea53cf6749d8a89ac07d577141b93f83adc4015f0b266d8f5c2dec4 +{ + "id": "de289f255aa2cdda95fbd430caf8fde3f9c989c544c4917cf1285a088115d0e8", + "fee": 8500, + "blockNumber": 2076, + "blockTimeStamp": 1567500396000, + "contractResult": [ + "" + ], + "contract_address": "TJMKWmC6mwF1QVax8Sy2AcgT6MqaXmHEds", + "receipt": { + "energy_fee": 8500, + "energy_usage_total": 85, + "net_usage": 314, + "result": "REVERT" + }, + "result": "FAILED", + "resMessage": "REVERT opcode executed" +} +``` + +### trigger constant contract + +> TriggerConstantContract [ownerAddress] contractAddress method args isHex fee_limit value token_value token_id + +OwnerAddress +> The address of the account that initiated the transaction, optional, default is the address of the login account. + +contractAddress +> Smart contract address + +method +> The name of function and parameters, please refer to the example + +args +> Parameter value, if you want to call `receive`, pass '#' instead + +isHex +> The format of the parameters method and args, is hex string or not + +fee_limit +> The most amount of trx allows for the consumption + +token_value +> Number of TRX10 + +token_id +> TRC10 id, If not, use ‘#’ instead + +Example: + +```console +> TriggerConstantContract TSNEe5Tf4rnc9zPMNXfaTF5fZfHDDH8oyW TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs "balanceOf(address)" 000000000000000000000000a614f803b6fd780986a42c78ec9c7f77e6ded13c true +``` + +### clear contract abi + +> ClearContractABI [ownerAddress] contractAddress + +OwnerAddress +> The address of the account that initiated the transaction, optional, default is the address of the login account. + +contractAddress +> Contract address + +Example: + +```console +> ClearContractABI TSNEe5Tf4rnc9zPMNXfaTF5fZfHDDH8oyW TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs +``` + +### get details of a smart contract + +> GetContract contractAddress + +contractAddress +> smart contract address + +Example: + +```console +> GetContract TGdtALTPZ1FWQcc5MW7aK3o1ASaookkJxG +{ + "origin_address": "TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ", + "contract_address": "TJMKWmC6mwF1QVax8Sy2AcgT6MqaXmHEds", + "abi": { + "entrys": [ + { + "name": "findArgsByIndexTest", + "inputs": [ + { + "name": "i", + "type": "uint256" + } + ], + "outputs": [ + { + "name": "z", + "type": "uint256" + } + ], + "type": "Function", + "stateMutability": "Nonpayable" + } + ] + }, + "bytecode": "608060405234801561001057600080fd5b50610134806100206000396000f3006080604052600436106100405763ffffffff7c0100000000000000000000000000000000000000000000000000000000600035041663329000b58114610045575b600080fd5b34801561005157600080fd5b5061005d60043561006f565b60408051918252519081900360200190f35b604080516003808252608082019092526000916060919060208201838038833901905050905060018160008151811015156100a657fe5b602090810290910101528051600290829060019081106100c257fe5b602090810290910101528051600390829060029081106100de57fe5b6020908102909101015280518190849081106100f657fe5b906020019060200201519150509190505600a165627a7a72305820b24fc247fdaf3644b3c4c94fcee380aa610ed83415061ff9e65d7fa94a5a50a00029", + "consume_user_resource_percent": 75, + "name": "normalcontract544", + "origin_energy_limit": 50000, + "code_hash": "23423cece3b4866263c15357b358e5ac261c218693b862bcdb90fa792d5714e6" +} +``` +### get info of a smart contract + +> GetContractInfo contractAddress + +contractAddress +> smart contract address + +Example: + +```console +> GetContractInfo TGdtALTPZ1FWQcc5MW7aK3o1ASaookkJxG +``` + +### update smart contract parameters + +> UpdateEnergyLimit [ownerAddress] contract_address energy_limit # Update parameter energy_limit +> UpdateSetting [ownerAddress] contract_address consume_user_resource_percent # Update parameter consume_user_resource_percent + +### create2 + +> Create2 address code salt + +Predict the contract address generated after deploying a contract. Among them, address is the contract address for executing the create 2 instruction, code is the bytecode of the contract to be deployed, and salt is a random salt value. + +Example: + +```console +> Create2 TEDapYSVvAZ3aYH7w8N9tMEEFKaNKUD5Bp 5f805460ff1916600190811790915560649055606319600255 2132 +``` + +### estimate-energy + +> EstimateEnergy owner_address(use # if you own) contract_address method args isHex [value token_value token_id(e.g: TRXTOKEN, use # if don't provided)] + +Estimate the energy required for the successful execution of smart contract transactions. (Confirmed state). + +Example: + +```console +> EstimateEnergy TSNEe5Tf4rnc9zPMNXfaTF5fZfHDDH8oyW TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs "balanceOf(address)" 000000000000000000000000a614f803b6fd780986a42c78ec9c7f77e6ded13c true +``` + +## How to delegate resource + +### delegate resource + + > freezeBalance [OwnerAddress] frozen_balance frozen_duration [ResourceCode:0 BANDWIDTH, 1 ENERGY] [receiverAddress] + +The latter two parameters are optional parameters. If not set, the TRX is frozen to obtain +resources for its own use; if it is not empty, the acquired resources are used by 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 TRX, the unit is the smallest unit (Sun), the minimum is 1000000sun. + +frozen_duration +> frezen duration, 3 days + +ResourceCode +> 0 BANDWIDTH;1 ENERGY + +receiverAddress +> target account address + +### unfreeze delegated resource + + > unfreezeBalance [OwnerAddress] ResourceCode(0 BANDWIDTH, 1 CPU) [receiverAddress] + +The latter two parameters are optional. If they are not set, the BANDWIDTH resource is unfreeze +by default; when the receiverAddress is set, the delegate resources are unfreezed. + +### get resource delegation information + +getDelegatedResource fromAddress toAddress +> get the information from the fromAddress to the toAddress resource delegate + +getDelegatedResourceAccountIndex address +> get the information that address is delegated to other account resources + + +## How to freezev2 + +### freezev2/unfreezev2 resource + + > freezeBalanceV2 [OwnerAddress] frozen_balance [ResourceCode:0 BANDWIDTH,1 ENERGY,2 TRON_POWER] + +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 1000000sun. + +ResourceCode +> 0 BANDWIDTH;1 ENERGY + +Example: +```console +wallet> FreezeBalanceV2 TJAVcszse667FmSNCwU2fm6DmfM5D4AyDh 1000000000000000 0 +txid is 82244829971b4235d98a9f09ba67ddb09690ac2f879ad93e09ba3ec1ab29177d +wallet> GetTransactionById 82244829971b4235d98a9f09ba67ddb09690ac2f879ad93e09ba3ec1ab29177d +{ + "ret":[ + { + "contractRet":"SUCCESS" + } + ], + "signature":[ + "4faa3772fa3d3e4792e8126cafed2dc2c5c069cd09c29532f0119bc982bf356004772e16fad86e401f5818c35b96d214d693efab06997ca2f07044d4494f12fd01" + ], + "txID":"82244829971b4235d98a9f09ba67ddb09690ac2f879ad93e09ba3ec1ab29177d", + "raw_data":{ + "contract":[ + { + "parameter":{ + "value":{ + "frozen_balance":1000000000000000, + "owner_address":"4159e3741a68ec3e1ebba80ad809d5ccd31674236e" + }, + "type_url":"type.googleapis.com/protocol.FreezeBalanceV2Contract" + }, + "type":"FreezeBalanceV2Contract" + } + ], + "ref_block_bytes":"0000", + "ref_block_hash":"19b59068c6058ff4", + "expiration":1671109891800, + "timestamp":1671088291796 + }, + "raw_data_hex":"0a020000220819b59068c6058ff440d8ada5afd1305a5c083612580a34747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e467265657a6542616c616e63655632436f6e747261637412200a154159e3741a68ec3e1ebba80ad809d5ccd31674236e1080809aa6eaafe30170d4fffea4d130" +} +``` + + > unfreezeBalanceV2 [OwnerAddress] unfreezeBalance ResourceCode(0 BANDWIDTH,1 ENERGY,2 TRON_POWER) + +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 + +Example: +```console +wallet> UnFreezeBalanceV2 TJAVcszse667FmSNCwU2fm6DmfM5D4AyDh 9000000 0 +txid is dcfea1d92fc928d24c88f7f71a03ae8105d0b5b112d6d48be93d3b9c73bea634 +wallet> GetTransactionById dcfea1d92fc928d24c88f7f71a03ae8105d0b5b112d6d48be93d3b9c73bea634 +{ + "ret":[ + { + "contractRet":"SUCCESS" + } + ], + "signature":[ + "f73a278f742c11e8e5ede693ca09b0447a804fcb28ea2bfdfd8545bb05da7be44bd08cfaa92bd4d159178f763fcf753f28d5296bd0c3d4557532cce3b256b9da00" + ], + "txID":"dcfea1d92fc928d24c88f7f71a03ae8105d0b5b112d6d48be93d3b9c73bea634", + "raw_data":{ + "contract":[ + { + "parameter":{ + "value":{ + "owner_address":"4159e3741a68ec3e1ebba80ad809d5ccd31674236e", + "unfreeze_balance":9000000 + }, + "type_url":"type.googleapis.com/protocol.UnfreezeBalanceV2Contract" + }, + "type":"UnfreezeBalanceV2Contract" + } + ], + "ref_block_bytes":"0000", + "ref_block_hash":"19b59068c6058ff4", + "expiration":1671119916913, + "timestamp":1671098316907 + }, + "raw_data_hex":"0a020000220819b59068c6058ff440f19e89b4d1305a5a083712560a36747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e556e667265657a6542616c616e63655632436f6e7472616374121c0a154159e3741a68ec3e1ebba80ad809d5ccd31674236e10c0a8a50470ebf0e2a9d130" +} +``` + +### delegate/undelegate resource + + > delegateResource [OwnerAddress] balance ResourceCode(0 BANDWIDTH,1 ENERGY), ReceiverAddress [lock] + +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 1000000sun. + +ResourceCode +> 0 BANDWIDTH;1 ENERGY + +ReceiverAddress +> The address of the account + +lock +> default is false, set true if need lock delegate for 3 days + +Example: +```console +wallet> DelegateResource TJAVcszse667FmSNCwU2fm6DmfM5D4AyDh 10000000 0 TQ4gjjpAjLNnE67UFbmK5wVt5fzLfyEVs3 true +txid is 363ac0b82b6ad3e0d3cad90f7d72b3eceafe36585432a3e013389db36152b6ed +wallet> GetTransactionById 363ac0b82b6ad3e0d3cad90f7d72b3eceafe36585432a3e013389db36152b6ed +{ + "ret":[ + { + "contractRet":"SUCCESS" + } + ], + "signature":[ + "1f57fd78456136faadc5091b47f5fd27a8e1181621e49129df6a4062499429fb48ee72e5f9a9ff5bfb7f2575f01f4076f7d4b89ca382d36af46a6fa4bc749f4301" + ], + "txID":"363ac0b82b6ad3e0d3cad90f7d72b3eceafe36585432a3e013389db36152b6ed", + "raw_data":{ + "contract":[ + { + "parameter":{ + "value":{ + "balance":10000000, + "receiver_address":"419a9afe56e155ef0ff3f680d00ecf19deff60bdca", + "lock":true, + "owner_address":"4159e3741a68ec3e1ebba80ad809d5ccd31674236e" + }, + "type_url":"type.googleapis.com/protocol.DelegateResourceContract" + }, + "type":"DelegateResourceContract" + } + ], + "ref_block_bytes":"0000", + "ref_block_hash":"19b59068c6058ff4", + "expiration":1671120059226, + "timestamp":1671098459216 + }, + "raw_data_hex":"0a020000220819b59068c6058ff440daf691b4d1305a720839126e0a35747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e44656c65676174655265736f75726365436f6e747261637412350a154159e3741a68ec3e1ebba80ad809d5ccd31674236e1880ade2042215419a9afe56e155ef0ff3f680d00ecf19deff60bdca280170d0c8eba9d130" +} + +``` + + > unDelegateResource [OwnerAddress] balance ResourceCode(0 BANDWIDTH,1 ENERGY), ReceiverAddress + +OwnerAddress +> The address of the account that initiated the transaction, optional, default is the address of the login account. + +balance +> The amount of unDelegate, the unit is the smallest unit (Sun) + +ResourceCode +> 0 BANDWIDTH;1 ENERGY + +ReceiverAddress +> The address of the account + +Example: +```console +wallet> UnDelegateResource TJAVcszse667FmSNCwU2fm6DmfM5D4AyDh 1000000 0 TQ4gjjpAjLNnE67UFbmK5wVt5fzLfyEVs3 +txid is feb334794cf361fd351728026ccf7319e6ae90eba622b9eb53c626cdcae4965c +wallet> GetTransactionById feb334794cf361fd351728026ccf7319e6ae90eba622b9eb53c626cdcae4965c +{ + "ret":[ + { + "contractRet":"SUCCESS" + } + ], + "signature":[ + "85a41a4e44780ffbe0841a44fd71cf621f129d98e84984cfca68e03364f781aa7f9d44177af0b40d82da052feec9f47a399ed6e51be66c5db07cb13477dcde8c01" + ], + "txID":"feb334794cf361fd351728026ccf7319e6ae90eba622b9eb53c626cdcae4965c", + "raw_data":{ + "contract":[ + { + "parameter":{ + "value":{ + "balance":1000000, + "receiver_address":"419a9afe56e155ef0ff3f680d00ecf19deff60bdca", + "owner_address":"4159e3741a68ec3e1ebba80ad809d5ccd31674236e" + }, + "type_url":"type.googleapis.com/protocol.UnDelegateResourceContract" + }, + "type":"UnDelegateResourceContract" + } + ], + "ref_block_bytes":"0000", + "ref_block_hash":"19b59068c6058ff4", + "expiration":1671120342283, + "timestamp":1671098742280 + }, + "raw_data_hex":"0a020000220819b59068c6058ff4408b9aa3b4d1305a71083a126d0a37747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e556e44656c65676174655265736f75726365436f6e747261637412320a154159e3741a68ec3e1ebba80ad809d5ccd31674236e18c0843d2215419a9afe56e155ef0ff3f680d00ecf19deff60bdca7088ecfca9d130" +} +``` +### withdraw expire unfreeze +> withdrawExpireUnfreeze [OwnerAddress] + +OwnerAddress +> The address of the account that initiated the transaction, optional, default is the address of the login account. + +Example: +```console +wallet> withdrawexpireunfreeze TJAVcszse667FmSNCwU2fm6DmfM5D4AyDh +txid is e5763ab8dfb1e7ed076770d55cf3c1ddaf36d75e23ec8330f99df7e98f54a147 +wallet> GetTransactionById e5763ab8dfb1e7ed076770d55cf3c1ddaf36d75e23ec8330f99df7e98f54a147 +{ + "ret":[ + { + "contractRet":"SUCCESS" + } + ], + "signature":[ + "f8f02b5aa634b8666862a6d2ed68fcfd90afc616d14062952b0b09f0404d9bca6c4d3dc6dab082784950ff1ded235a07dab0d738c8a202be9451d5ca92b8eece01" + ], + "txID":"e5763ab8dfb1e7ed076770d55cf3c1ddaf36d75e23ec8330f99df7e98f54a147", + "raw_data":{ + "contract":[ + { + "parameter":{ + "value":{ + "owner_address":"4159e3741a68ec3e1ebba80ad809d5ccd31674236e" + }, + "type_url":"type.googleapis.com/protocol.WithdrawExpireUnfreezeContract" + }, + "type":"WithdrawExpireUnfreezeContract" + } + ], + "ref_block_bytes":"0000", + "ref_block_hash":"19b59068c6058ff4", + "expiration":1671122055318, + "timestamp":1671100455315 + }, + "raw_data_hex":"0a020000220819b59068c6058ff44096e18bb5d1305a5a083812560a3b747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e5769746864726177457870697265556e667265657a65436f6e747261637412170a154159e3741a68ec3e1ebba80ad809d5ccd31674236e7093b3e5aad130" +} +``` +> cancelAllUnfreezeV2 [OwnerAddress] + +OwnerAddress +> The address of the account that initiated the transaction, optional, default is the address of the login account. + +Example: +```console +wallet> cancelAllUnfreezeV2 TJAVcszse667FmSNCwU2fm6DmfM5D4AyDh +txid is e5763ab8dfb1e7ed076770d55cf3c1ddaf36d75e23ec8330f99df7e98f54a147 +wallet> GetTransactionById e5763ab8dfb1e7ed076770d55cf3c1ddaf36d75e23ec8330f99df7e98f54a147 +{ + "ret":[ + { + "contractRet":"SUCCESS" + } + ], + "signature":[ + "f8f02b5aa634b8666862a6d2ed68fcfd90afc616d14062952b0b09f0404d9bca6c4d3dc6dab082784950ff1ded235a07dab0d738c8a202be9451d5ca92b8eece01" + ], + "txID":"e5763ab8dfb1e7ed076770d55cf3c1ddaf36d75e23ec8330f99df7e98f54a147", + "raw_data":{ + "contract":[ + { + "parameter":{ + "value":{ + "owner_address":"4159e3741a68ec3e1ebba80ad809d5ccd31674236e" + }, + "type_url":"type.googleapis.com/protocol.CancelAllUnfreezeV2" + }, + "type":"CancelAllUnfreezeV2Contract" + } + ], + "ref_block_bytes":"0000", + "ref_block_hash":"19b59068c6058ff4", + "expiration":1671122055318, + "timestamp":1671100455315 + }, + "raw_data_hex":"0a020000220819b59068c6058ff44096e18bb5d1305a5a083812560a3b747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e5769746864726177457870697265556e667265657a65436f6e747261637412170a154159e3741a68ec3e1ebba80ad809d5ccd31674236e7093b3e5aad130" +} +``` + +### get resource delegation information use v2 API + + > getDelegatedResourceV2 fromAddress toAddress +> get the information from the fromAddress to the toAddress resource delegate use v2 API + +fromAddress +> The address of the account that start the delegate + +toAddress +> The address of the account that receive the delegate + +Example: +```console +wallet> getDelegatedResourceV2 TJAVcszse667FmSNCwU2fm6DmfM5D4AyDh TQ4gjjpAjLNnE67UFbmK5wVt5fzLfyEVs3 +{ + "delegatedResource": [ + { + "from": "TJAVcszse667FmSNCwU2fm6DmfM5D4AyDh", + "to": "TQ4gjjpAjLNnE67UFbmK5wVt5fzLfyEVs3", + "frozen_balance_for_bandwidth": 10000000 + } + ] +} +``` + + > getDelegatedResourceAccountIndexV2 address +> get the information that address is delegated to other account resources use v2 API + +address +> The address of the account that start the delegate or receive the delegate + +Example: +```console +wallet> getDelegatedResourceAccountIndexV2 TJAVcszse667FmSNCwU2fm6DmfM5D4AyDh +{ + "account": "TJAVcszse667FmSNCwU2fm6DmfM5D4AyDh", + "toAccounts": [ + "TQ4gjjpAjLNnE67UFbmK5wVt5fzLfyEVs3" + ] +} +``` + + > getcandelegatedmaxsize ownerAddress type +> get the max size that the ownerAddress can delegate use delegateResource + +ownerAddress +> The address of the account that start the delegate, optional, default is the address of the login account. + +type +> 0 bandwidth, 1 energy + +Example: +```console +wallet> getCanDelegatedMaxSize TJAVcszse667FmSNCwU2fm6DmfM5D4AyDh 0 +{ + "max_size": 999999978708334 +} +``` + + > getavailableunfreezecount ownerAddress +> get the available unfreeze count that the ownerAddress can call unfreezeBalanceV2 + +ownerAddress +> The address of the account that initiated the transaction, optional, default is the address of the login account. + +Example: +```console +wallet> getAvailableUnfreezeCount TJAVcszse667FmSNCwU2fm6DmfM5D4AyDh +{ + "count": 31 +} +``` + + > getcanwithdrawunfreezeamount ownerAddress timestamp +> get the withdraw unfreeze amount that the ownerAddress can get by withdrawexpireunfreeze + +ownerAddress +> The address of the account that initiated the transaction, optional, default is the address of the login account. + +timestamp +> get can withdraw unfreeze amount until timestamp, + + +Example: +```console +wallet> getCanWithdrawUnfreezeAmount TJAVcszse667FmSNCwU2fm6DmfM5D4AyDh 1671100335000 +{ + "amount": 9000000 +} +``` +## Get resource prices and memo fee + > getbandwidthprices +> get historical unit price of bandwidth + +Example: +```console +wallet> getBandwidthPrices +{ + "prices": "0:10,1606537680000:40,1614238080000:140,1626581880000:1000,1626925680000:140,1627731480000:1000" +} +``` + > getenergyprices +> get historical unit price of energy + +Example: +```console +wallet> getEnergyPrices +{ + "prices": "0:100,1575871200000:10,1606537680000:40,1614238080000:140,1635739080000:280,1681895880000:420" +} +``` + > getmemofee +> get memo fee + +Example: +```console +wallet> getMemoFee +{ + "prices": "0:0,1675492680000:1000000" +} +``` + +### get chain parameters + +> GetChainParameters + +Show all parameters that the blockchain committee can set. +Example: + +```console +> GetChainParameters +``` + +## import and export mnemonic + >ImportWalletByMnemonic +>Import wallet, you need to set a password, mnemonic + +Example: +```console +wallet> ImportWalletByMnemonic +Please input password. +password: +Please input password again. +password: +Please enter 12 words (separated by spaces) [Attempt 1/3]: +``` + +> ExportWalletMnemonic +>export mnemonic of the address in the wallet + +Example: +```console +wallet> ExportWalletMnemonic +Please input your password. +password: +exportWalletMnemonic successful !! +a*ert tw*st co*rect mat*er pa*s g*ther p*t p*sition s*op em*ty coc*nut aband*n +``` + +## generate sub account + >GenerateSubAccount +>generate subaccount using the mnemonic in the wallet + +Example: +```console +wallet> GenerateSubAccount +Please input your password. +password: + +=== Sub Account Generator === +----------------------------- +Default Address: TYEhEg7b7tXm92UDbRDXPtJNU6T9xVGbbo +Default Path: m/44'/195'/0'/0/1 +----------------------------- + +1. Generate Default Path +2. Change Account +3. Custom Path + +Enter your choice (1-3): 1 +mnemonic file : ./Mnemonic/TYEhEg7b7tXm92UDbRDXPtJNU6T9xVGbbo.json +Generate a sub account successful, keystore file name is TYEhEg7b7tXm92UDbRDXPtJNU6T9xVGbbo.json +generateSubAccount successful. +``` +## clear wallet keystore + >ClearWalletKeystore +>clear wallet keystore of the login account + +Example: +```console +wallet> ClearWalletKeystore + +Warning: Dangerous operation! +This operation will permanently delete the Wallet&Mnemonic files of the Address: TABWx7yFhWrvZHbwKcCmFLyPLWjd2dZ2Rq +Warning: The private key and mnemonic words will be permanently lost and cannot be recovered! +Continue? (y/Y to proceed):y + +Final confirmation: +Please enter: 'DELETE' to confirm the delete operation: +Confirm: (DELETE): DELETE + +File deleted successfully: +- /wallet-cli/Wallet/TABWx8yFhWrvZHbwKcCmFLyPLWjd2dZ2Rq.json +- /wallet-cli/Mnemonic/TABWx8yFhWrvZHbwKcCmFLyPLWjd2dZ2Rq.json +ClearWalletKeystore successful !!! +``` +## export import wallet keystore + >ExportWalletKeystore +>export the wallet keystore to the format of tronlink wallet + +Example: +```console +wallet> ExportWalletKeystore tronlink /tmp +Please input your password. +password: +exported keystore file : /tmp/TYdhEg8b7tXm92UDbRDXPtJNU6T9xVGbbo.json +exportWalletKeystore successful !! +``` + >ImportWalletByKeystore +>import the keystore file of tronlink wallet to wallet-cli + +Example: +```console +wallet> ImportWalletByKeystore tronlink /tmp/tronlink.json +Please input password. +password: +Please input password again. +password: +fileName = TYQq6zp51unQDNELmT4xKMWh5WLcwpCDZJ.json +importWalletByKeystore successful !! +``` +## import wallet by ledger + >ImportWalletByLedger +>import the derived account of ledger to wallet-cli + +Example: +```console +wallet> ImportWalletByLedger +((Note:This will pair Ledger to user your hardward 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. +password: +Please input password again. +password: +------------------------------------------------- +Default Account Address: TAT1dA8F9HXGqmhvMCjxCKAD29YxDRw81y +Default Path: m/44'/195'/0'/0/0 +------------------------------------------------- +1. Import Default Account +2. Change Path +3. Custom Path +Select an option: 1 +Import a wallet by Ledger successful, keystore file : ./Wallet/Ledger-TAT1dA8F9HXGqmhvMCjxCKAD29YxDRw81y.json +You are now logged in, and you can perform operations using this account. +``` +## login all +> LoginAll +>Multiple Keystore accounts can be logged in with a unified password + +Example: +```console +wallet> loginall +Please input your password. +password: +Use user defined config file in current dir +[========================================] 100% +The 1th keystore file name is TJEEKTmaVTYSpJAxahtyuofnDSpe2seajB.json +The 2th keystore file name is TX1L9xonuUo1AHsjUZ3QzH8wCRmKm56Xew.json +The 3th keystore file name is TVuVqnJFuuDxN36bhEbgDQS7rNGA5dSJB7.json +The 4th keystore file name is Ledger-TRvVXgqddDGYRMx3FWf2tpVxXQQXDZxJQe.json +The 5th keystore file name is TYXFDtn86VPFKg4mkwMs45DKDcpAyqsada.json +Please choose between 1 and 5 +5 +LoginAll successful !!! +``` + +## logout +> Logout +> Log out of the current wallet account. + +Example: +```console +wallet> Logout +Logout successful !!! +``` + +## lock +> Lock +>To use the lock function of the login account, it is necessary to configure **lockAccount = true** in the **config.conf**. +The current login account is locked, which means that signatures and transactions are not allowed. + +Example: +```console +wallet> lock +lock successful !!! +``` + +## unlock +> Unlock +>To use the unlock function of the login account, it is necessary to configure **lockAccount = true** in the **config.conf**. +After the current login account is locked, it can be unlocked. By default, it will be unlocked again after 300 seconds. Unlocking can specify parameters in seconds. + +Example: +```console +wallet> unlock 60 +Please input your password. +password: +unlock successful !!! +``` + +## switch network + > SwitchNetwork +>This command allows for flexible network switching at any time. +>`switchnetwork local` will switch to the network configured in local config.conf. + +Example: +```console +wallet> switchnetwork +Please select network： +1. MAIN +2. NILE +3. SHASTA +Enter numbers to select a network (1-3):1 +Now, current network is : MAIN +SwitchNetwork successful !!! +``` +```console +wallet> switchnetwork main +Now, current network is : MAIN +SwitchNetwork successful !!! +``` + +```console +wallet> switchnetwork empty localhost:50052 +Now, current network is : CUSTOM +SwitchNetwork successful !!! +``` + +## current network + > CurrentNetwork +>View current network. + +Example: +```console +wallet> currentnetwork +currentNetwork: NILE +``` + +```console +wallet> currentnetwork +current network: CUSTOM +fullNode: EMPTY, solidityNode: localhost:50052 +``` +## GasFree + +Wallet-cli now supports GasFree integration. This guide explains the new commands and provides instructions on how to use them. + +For more details, please refer to [GasFree Documentation](https://gasfree.io/specification) and [TronLink User Guide For GasFree](https://support.tronlink.org/hc/en-us/articles/38903684778393-GasFree-User-Guide). + +Prerequisites +API Credentials: Users must obtain the API Key and API Secret from GasFree for authentication. Please refer to the official [application form](https://docs.google.com/forms/d/e/1FAIpQLSc5EB1X8JN7LA4SAVAG99VziXEY6Kv6JxmlBry9rUBlwI-GaQ/viewform) for instructions on setting up API authentication. + +New Commands: + +### Gas Free info +> GasFreeInfo +Query GasFree Information +Function: Retrieve the basic info, including the GasFree address associated with your current wallet address. +Note: The GasFree address is automatically activated upon the first transfer, which may incur an activation fee. + +Example: +```console +wallet> gasfreeinfo +balanceOf(address):70a08231 +{ + "gasFreeAddress":"TCtSt8fCkZcVdrGpaVHUr6P8EmdjysswMF", + "active":true, + "tokenBalance":998696000, + "activateFee":0, + "transferFee":2000, + "maxTransferValue":998694000 +} +gasFreeInfo: successful !! +``` + +```console +wallet> gasfreeinfo TRvVXgqddDGYRMx3FWf2tpVxXQQXDZxJQe +balanceOf(address):70a08231 +{ + "gasFreeAddress":"TCtSt8fCkZcVdrGpaVHUr6P8EmdjysswMF", + "active":true, + "tokenBalance":998696000, + "activateFee":0, + "transferFee":2000, + "maxTransferValue":998694000 +} +gasFreeInfo: successful !! +``` +### Gas Free transfer +> GasFreeTransfer +Submit GasFree Transfer +Function: Submit a gas-free token transfer request. + +Example: +```console +wallet> gasfreetransfer TEkj3ndMVEmFLYaFrATMwMjBRZ1EAZkucT 100000 + +GasFreeTransfer result: { + "code":200, + "data":{ + "amount":100000, + "providerAddress":"TKtWbdzEq5ss9vTS9kwRhBp5mXmBfBns3E", + "apiKey":"", + "accountAddress":"TUUSMd58eC3fKx3fn7whxJyr1FR56tgaP8", + "signature":"", + "targetAddress":"TEkj3ndMVEmFLYaFrATMwMjBRZ1EAZkucT", + "maxFee":2000000, + "version":1, + "nonce":8, + "tokenAddress":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf", + "createdAt":1747909635678, + "expiredAt":1747909695000, + "estimatedTransferFee":2000, + "id":"6c3ff67e-0bf4-4c09-91ca-0c7c254b01a0", + "state":"WAITING", + "estimatedActivateFee":0, + "gasFreeAddress":"TNER12mMVWruqopsW9FQtKxCGfZcEtb3ER", + "updatedAt":1747909635678 + } +} +GasFreeTransfer successful !!! +``` + +### Gas Free trace +> GasFreeTrace +Track Transfer Status +Function: Check the progress of a GasFree transfer using the traceId obtained from GasFreeTransfer. + +Example: +```console +wallet> gasfreetrace 6c3ff67e-0bf4-4c09-91ca-0c7c254b01a0 +GasFreeTrace result: { + "code":200, + "data":{ + "amount":100000, + "providerAddress":"TKtWbdzEq5ss9vTS9kwRhBp5mXmBfBns3E", + "txnTotalCost":102000, + "accountAddress":"TUUSMd58eC3fKx3fn7whxJyr1FR56tgaP8", + "txnActivateFee":0, + "estimatedTotalCost":102000, + "targetAddress":"TEkj3ndMVEmFLYaFrATMwMjBRZ1EAZkucT", + "txnBlockTimestamp":1747909638000, + "txnTotalFee":2000, + "nonce":8, + "estimatedTotalFee":2000, + "tokenAddress":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf", + "txnHash":"858f9a00776163b1f8a34467b9c5727657f8971a9f4e9d492f0a247fac0384f9", + "txnBlockNum":57175988, + "createdAt":1747909635678, + "expiredAt":1747909695000, + "estimatedTransferFee":2000, + "txnState":"ON_CHAIN", + "id":"6c3ff67e-0bf4-4c09-91ca-0c7c254b01a0", + "state":"CONFIRMING", + "estimatedActivateFee":0, + "gasFreeAddress":"TNER12mMVWruqopsW9FQtKxCGfZcEtb3ER", + "txnTransferFee":2000, + "txnAmount":100000 + } +} +GasFreeTrace: successful!! +``` + +## switch wallet + > SwitchWallet +>After logging in with the LoginAll command, you can switch wallets + +Example: +```console +wallet> switchwallet +The 1th keystore file name is TJEEKTmaVTYSpJAxahtyuofnDSpe2seajB.json +The 2th keystore file name is TX1L9xonuUo1AHsjUZ3QzH8wCRmKm56Xew.json +The 3th keystore file name is TVuVqnJFuuDxN36bhEbgDQS7rNGA5dSJB7.json +The 4th keystore file name is Ledger-TRvVXgqddDGYRMx3FWf2tpVxXQQXDZxJQe.json +The 5th keystore file name is TYXFDtn86VPFKg4mkwMs45DKDcpAyqsada.json +Please choose between 1 and 5 +5 +SwitchWallet successful !!! +``` + +## reset wallet + > ResetWallet +>Use the resetWallet command to delete all local wallet's Keystore files and mnemonic files, and guide you to re register or import the wallet through prompts + +Example: +```console +wallet> resetwallet +User defined config file doesn't exists, use default config file in jar + +Warning: Dangerous operation! +This operation will permanently delete the Wallet&Mnemonic files +Warning: The private key and mnemonic words will be permanently lost and cannot be recovered! +Continue? (y/Y to proceed, c/C to cancel): +y + +Final confirmation: +Please enter: 'DELETE' to confirm the delete operation: +Confirm: (DELETE): DELETE +resetWallet successful !!! +Now, you can RegisterWallet or ImportWallet again. Or import the wallet through other means. +``` + +## create account +> CreateAccount +>This command can create a new account with an inactive address and burn a 1-trx handling fee for it + +Example: +```console +wallet> createaccount TDJ13zZzT3w91WMBm98gC3mwL7NbA6sQPA +{ + "raw_data":{ + "contract":[ + { + "parameter":{ + "value":{ + "owner_address":"TQLaB7L8o3ikjRVcN7tTjMZsRYPJ23XZbd", + "account_address":"TDJ13zZzT3w91WMBm98gC3mwL7NbA6sQPA" + }, + "type_url":"type.googleapis.com/protocol.AccountCreateContract" + }, + "type":"AccountCreateContract" + } + ], + "ref_block_bytes":"91a4", + "ref_block_hash":"2bfcd3bb597f3d40", + "expiration":1745333676000, + "timestamp":1745333618318 + }, + "raw_data_hex":"0a0291a422082bfcd3bb597f3d4040e0cff9efe5325a6612640a32747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e4163636f756e74437265617465436f6e7472616374122e0a15419d9c2bb5ee381a4396dd49ce42292e756b2e5e4b12154124764e4674179d4578cfc4c833c1ac1a09f6ce56708e8df6efe532" +} +Before sign transaction hex string is 0a84010a0291a422082bfcd3bb597f3d4040e0cff9efe5325a6612640a32747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e4163636f756e74437265617465436f6e7472616374122e0a15419d9c2bb5ee381a4396dd49ce42292e756b2e5e4b12154124764e4674179d4578cfc4c833c1ac1a09f6ce56708e8df6efe532 +Please confirm and input your permission id, if input y/Y means default 0, other non-numeric characters will cancel transaction. +y +Please choose your key for sign. +The 1th keystore file name is TJEEKTmaVTYSpJAxahtyuofnDSpe2seajB.json +The 2th keystore file name is TX1L9xonuUo1AHsjUZ3QzH8wCRmKm56Xew.json +The 3th keystore file name is TVuVqnJFuuDxN36bhEbgDQS7rNGA5dSJB7.json +The 4th keystore file name is Ledger-TRvVXgqddDGYRMx3FWf2tpVxXQQXDZxJQe.json +The 5th keystore file name is TYXFDtn86VPFKg4mkwMs45DKDcpAyqsada.json +Please choose between 1 and 5 +1 +After sign transaction hex string is 0a84010a0291a422082bfcd3bb597f3d404083bd9cfae5325a6612640a32747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e4163636f756e74437265617465436f6e7472616374122e0a15419d9c2bb5ee381a4396dd49ce42292e756b2e5e4b12154124764e4674179d4578cfc4c833c1ac1a09f6ce56708e8df6efe5321241ce53add4f75fe1838aa7e0a4e2411b3bbfce1d2164d68dac18507ed87e22ae503f65592a1161640834b3c0cef43c28f20b2d335120cc78b6f745a82ea95e451100 +TxId is 26d6fcdfdc0018097ec4166eb140e19ebd597bea2212579d2f6d921b0ad6e56f +CreateAccount successful !! +``` + +### set account id + +> SetAccountId [owner_address] account_id + +Sets a custom unique identifier (Account ID) for an account. + +Example: + +```console +> SetAccountId TEDapYSVvAZ3aYH7w8N9tMEEFKaNKUD5Bp 100 +``` + +### update account + +> UpdateAccount [owner_address] account_name + +Modify account name. + +Example: + +```console +> UpdateAccount test-name +``` + +### Modify wallet name +> ModifyWalletName new_wallet_name + +Modify wallet's name. + +Example: +```console +wallet> ModifyWalletName new-name +Modify Wallet Name successful !! +``` + +### View backup records +> ViewBackupRecords + +View backup records. You can configure the maximum number of records that `maxRecords` can retain in `config.conf`, excluding the number of buffer records. + +Example: +```console +wallet> ViewBackupRecords + +=== View Backup Records === +1. View all records +2. Filter by time range +Choose an option (1-2): 1 +``` +### View transaction history +> ViewTransactionHistory + +View transaction history. You can configure the maximum number of records that `maxRecords` can retain in `config.conf`, excluding the number of buffer records. + +Example: +```console +wallet> ViewTransactionHistory +==================================== + TRANSACTION VIEWER +==================================== + +MAIN MENU: +1. View all transactions +2. Filter by time range +3. Help +4. Exit +Select option: 1 +``` + + +## Wallet related commands + +**RegisterWallet** +> Register your wallet, you need to set the wallet password and generate the address and private key. + +**BackupWallet** +> Back up your wallet, you need to enter your wallet password and export the private key.hex string format, such +as: 1234567890123456789012345678901234567890123456789012345678901234 + +**BackupWallet2Base64** +> Back up your wallet, you need to enter your wallet password and export the private key.base64 format, such as: ch1jsHTxjUHBR+BMlS7JNGd3ejC28WdFvEeo6uUHZUU= + +**ChangePassword** +> Modify the password of an account + +**ImportWallet** +> Import wallet, you need to set a password, hex String format + +**ImportWalletByBase64** +> Import wallet, you need to set a password, base64 format + +## Account related commands + +**GenerateAddress** +> Generate an address and print out the address and private key + +**GetAccount** +> Get account information based on address +**GetAccountById** +> Get account details information through account id + +**GetAccountNet** +> The usage of bandwidth + +**GetAccountResource** +> The usage of bandwidth and energy + +**GetAddress** +> Get the address of the current login account + +**GetBalance** +> Get the balance of the current login account + +## How to get transaction information + +**GetTransactionById** +> Get transaction information based on transaction id + +**GetTransactionCountByBlockNum** +> Get the number of transactions in the block based on the block height + +**GetTransactionInfoById** +> Get transaction-info based on transaction id, generally used to check the result of a smart contract trigger + +**GetTransactionInfoByBlockNum** +> Get the list of transaction information in the block based on the block height + +## How to get block information + +**GetBlock** +> Get the block according to the block number; if you do not pass the parameter, get the latest block + +**GetBlockById** +> Get block based on blockID + +**GetBlockByIdOrNum** +> Get blocks based on their ID or block height. If no parameters are passed, Get the header block. + +**GetBlockByLatestNum n** +> Get the latest n blocks, where 0 < n < 100 + +**GetBlockByLimitNext startBlockId endBlockId** +> Get the block in the range [startBlockId, endBlockId) + +## Some others + +**GetNextMaintenanceTime** +> Get the start time of the next maintain period + +**ListNodes** +> Get other peer information + +**ListWitnesses** +> Get all miner node information + +**BroadcastTransaction** +> Broadcast the transaction, where the transaction is in hex string format. + +## How to use tron-dex to sell asset + +### MarketSellAsset + +Create an order to sell asset + +> MarketSellAsset owner_address sell_token_id sell_token_quantity buy_token_id buy_token_quantity + +ownerAddress +> The address of the account that initiated the transaction + +sell_token_id, sell_token_quantity +> ID and amount of the token want to sell + +buy_token_id, buy_token_quantity +> ID and amount of the token want to buy + +Example: + +```console +MarketSellAsset TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW 1000001 200 _ 100 + +Get the result of the contract execution with the getTransactionInfoById command: +getTransactionInfoById 10040f993cd9452b25bf367f38edadf11176355802baf61f3c49b96b4480d374 + +{ + "id": "10040f993cd9452b25bf367f38edadf11176355802baf61f3c49b96b4480d374", + "blockNumber": 669, + "blockTimeStamp": 1578983493000, + "contractResult": [ + "" + ], + "receipt": { + "net_usage": 264 + } +} +``` + +### GetMarketOrderByAccount + +Get the order created by account(just include active status) + +> GetMarketOrderByAccount ownerAddress + +ownerAddress +> The address of the account that created market order + +Example: + +```console +GetMarketOrderByAccount TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW +{ + "orders": [ + { + "order_id": "fc9c64dfd48ae58952e85f05ecb8ec87f55e19402493bb2df501ae9d2da75db0", + "owner_address": "TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW", + "create_time": 1578983490000, + "sell_token_id": "_", + "sell_token_quantity": 100, + "buy_token_id": "1000001", + "buy_token_quantity": 200, + "sell_token_quantity_remain": 100 + } + ] +} +``` + +### GetMarketOrderById + +Get the specific order by order_id + +> GetMarketOrderById orderId + +Example: + +```console +GetMarketOrderById fc9c64dfd48ae58952e85f05ecb8ec87f55e19402493bb2df501ae9d2da75db0 +{ + "order_id": "fc9c64dfd48ae58952e85f05ecb8ec87f55e19402493bb2df501ae9d2da75db0", + "owner_address": "TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW", + "create_time": 1578983490000, + "sell_token_id": "_", + "sell_token_quantity": 100, + "buy_token_id": "1000001", + "buy_token_quantity": 200, +} +``` + +### GetMarketPairList + +Get market pair list + +Example: + +```console +GetMarketPairList +{ + "orderPair": [ + { + "sell_token_id": "_", + "buy_token_id": "1000001" + } + ] +} +``` + +### GetMarketOrderListByPair + +Get order list by pair + +> GetMarketOrderListByPair sell_token_id buy_token_id + +sell_token_id +> ID of the token want to sell + +buy_token_id +> ID of the token want to buy + +Example: + +```console +GetMarketOrderListByPair _ 1000001 +{ + "orders": [ + { + "order_id": "fc9c64dfd48ae58952e85f05ecb8ec87f55e19402493bb2df501ae9d2da75db0", + "owner_address": "TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW", + "create_time": 1578983490000, + "sell_token_id": "_", + "sell_token_quantity": 100, + "buy_token_id": "1000001", + "buy_token_quantity": 200, + "sell_token_quantity_remain": 100 + } + ] +} +``` + +### GetMarketPriceByPair + +Get market price by pair + +> GetMarketPriceByPair sell_token_id buy_token_id + +sell_token_id +> ID of the token want to sell + +buy_token_id +> ID of the token want to buy + +Example: + +```console +GetMarketPriceByPair _ 1000001 +{ + "sell_token_id": "_", + "buy_token_id": "1000001", + "prices": [ + { + "sell_token_quantity": 100, + "buy_token_quantity": 200 + } + ] +} +``` + +### MarketCancelOrder + +Cancel the order + +> MarketCancelOrder owner_address order_id + +owner_address +> the account address who have created the order + +order_id +> the order id which want to cancel + +Example: + +```console +MarketCancelOrder TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW fc9c64dfd48ae58952e85f05ecb8ec87f55e19402493bb2df501ae9d2da75db0 +``` + +Get the result of the contract execution with the getTransactionInfoById command: +```console +getTransactionInfoById b375787a098498623403c755b1399e82910385251b643811936d914c9f37bd27 +{ + "id": "b375787a098498623403c755b1399e82910385251b643811936d914c9f37bd27", + "blockNumber": 1582, + "blockTimeStamp": 1578986232000, + "contractResult": [ + "" + ], + "receipt": { + "net_usage": 283 + } +} +``` +### Address book +> AddressBook + +Addition, deletion, modification, and search of address book. + +Example: +```console +wallet> AddressBook + +MAIN MENU: +1. addAddress +2. editAddress +3. delAddress +4. getAddressBook +Select option: 1 +``` +### show receiving qr code +> show-receiving-qr-code + +Display Receive Payment QR Code for the current address. +Executing this command requires installing 'qrencode' on the terminal in advance. +Debian/Ubuntu: +sudo apt install qrencode +CentOS: +sudo yum install qrencode +RHEL/Fedora: +sudo dnf install qrencode +macOS: +brew install qrencode + +Example: +```console +wallet> ShowReceivingQrCode +█████████████████████████████████████ +████ ▄▄▄▄▄ ██▄▀▀ ▄ ▀▄▀ ▀▀█ ▄▄▄▄▄ ████ +████ █ █ █▄ ▀▄ ▀▄▀▀███ █ █ ████ +████ █▄▄▄█ ██▀▄██▀▄▀▄▀ ▀██ █▄▄▄█ ████ +████▄▄▄▄▄▄▄█ ▀ █ ▀ ▀ ▀ ▀ █▄▄▄▄▄▄▄████ +████▄ █▄▄▄▄▄█ ██ ▀▀██▀ ██▀▄▀▀████ +████▄█▀▄█▀▄▀▄▄█▀█▄█▀▄ █▀██▄ █▄▄ ▄████ +████ █▄█▄ ▄▄▄██▀ ▀█▀▄██▄█▄▄ █ █ ▄████ +████ ▄▀▄▀▄▄▀ ▄█▄ ▀ ▀█ █ ██▀▀█▄▄▄████ +████▄█▀ ██▄██ ▄ ██ ██ █ ▄▄▄ ▄████ +████▄▀▀ ▀█▄█▀▄▀▀█▄█▄█▀ ▀▄▀█ ▄▄▄ ▄████ +████▄██▄█▄▄▄▀ ▄▀ ▀██ ▄▄ ▄▄▄ ▄▄▄████ +████ ▄▄▄▄▄ █ █▀▄ ▀ █▄▀▄ █▄█ ▄█▄ ████ +████ █ █ █▄▀▀ ██ ▄▄ █ ▄ ▄▄▄██████ +████ █▄▄▄█ █ ▀█▀█▄█▄▀▀█▄ ▄█ ██▀▄████ +████▄▄▄▄▄▄▄█▄▄██▄██ ▀▀▄▄▄▄█ ▀ ████ +█████████████████████████████████████ +TEDapYSVvAZ3aYH7w8N9tMEEFKaNKUD5Bp +``` +### get usdt balance +> GetUSDTBalance + +Get the current USDT balance of the account. + +Example: +```console +wallet> getusdtbalance +balanceOf(address):70a08231 +Execution result = { + "constant_result": [ + "0000000000000000000000000000000000000000000000000000000000000000" + ], + "result": { + "result": true + }, + "energy_used": 4062, + "energy_penalty": 3127 +} +USDT balance = 0 +``` +### get usdt transfer by id +> GetUsdtTransferById + +Get USDT transfer transaction summary based on transaction ID. + +Example: +```console +wallet> GetUsdtTransferById b0044dcb188568d11e77da926d96630f3e878583c5d5f4b3a72d2b984802143a +{ + "id":"b0044dcb188568d11e77da926d96630f3e878583c5d5f4b3a72d2b984802143a", + "type":"TriggerSmartContract(transferUSDT)", + "from":"TUUSMd58eC3fKx3fn7whxJyr1FR56tgaP8", + "to":"TGDjv2KKD4UqEmFTnZgLzup5WWjTex4Mvq", + "amount":100, + "tronscanQueryUrl":"https://nile.tronscan.org/#/transaction/b0044dcb188568d11e77da926d96630f3e878583c5d5f4b3a72d2b984802143a" +} +``` +### transfer usdt +> TransferUSDT + +Make a USDT transfer. + +Example: +```console +wallet> transferusdt TR311sD6KasRnofj5RnFiFBA2rH8RH2kYk 1 +balanceOf(address):70a08231 +Execution result = { + "constant_result": [ + "000000000000000000000000000000000000000000000000000000006544ae57" + ], + "result": { + "result": true + }, + "energy_used": 935 +} +USDT balance = 1698999895 +transfer(address,uint256):a9059cbb +It is estimated that 345 bandwidth and 29650 energy will be consumed. +Execution result = { + "constant_result": [ + "0000000000000000000000000000000000000000000000000000000000000000" + ], + "result": { + "result": true + }, + "energy_used": 29650, + "logs": [ + { + "address": "NaMomAhUzuFzMNFzzQHVNsR8xbmP3A5LT", + "topics": [ + "ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef", + "000000000000000000000000caf9798d70a3c609b600f163e53cfe8f586e1b9f", + "000000000000000000000000a5418b8da12e73075abb46375e7a15c758ea21fc" + ], + "data": "0000000000000000000000000000000000000000000000000000000000000001" + } + ] +} +{ + "raw_data":{ + "contract":[ + { + "parameter":{ + "value":{ + "data":"a9059cbb000000000000000000000041a5418b8da12e73075abb46375e7a15c758ea21fc0000000000000000000000000000000000000000000000000000000000000001", + "owner_address":"TUUSMd58eC3fKx3fn7whxJyr1FR56tgaP8", + "contract_address":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf" + }, + "type_url":"type.googleapis.com/protocol.TriggerSmartContract" + }, + "type":"TriggerSmartContract" + } + ], + "ref_block_bytes":"08c7", + "ref_block_hash":"c02252c2ae3b92e1", + "expiration":1761639507000, + "fee_limit":1000000000, + "timestamp":1761639448851 + }, + "raw_data_hex":"0a0208c72208c02252c2ae3b92e140b8c896cfa2335aae01081f12a9010a31747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e54726967676572536d617274436f6e747261637412740a1541caf9798d70a3c609b600f163e53cfe8f586e1b9f121541eca9bc828a3005b9a3b909f2cc5c2a54794de05f2244a9059cbb000000000000000000000041a5418b8da12e73075abb46375e7a15c758ea21fc000000000000000000000000000000000000000000000000000000000000000170938293cfa23390018094ebdc03" +} +Before sign transaction hex string is 0ad4010a0208c72208c02252c2ae3b92e140b8c896cfa2335aae01081f12a9010a31747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e54726967676572536d617274436f6e747261637412740a1541caf9798d70a3c609b600f163e53cfe8f586e1b9f121541eca9bc828a3005b9a3b909f2cc5c2a54794de05f2244a9059cbb000000000000000000000041a5418b8da12e73075abb46375e7a15c758ea21fc000000000000000000000000000000000000000000000000000000000000000170938293cfa23390018094ebdc03 +Please confirm and input your permission id, if input y/Y means default 0, other non-numeric characters will cancel transaction. +y +Please choose your key for sign. + +No. Address Name +1 TUUSMd58eC3fKx3fn7whxJyr1FR56tgaP8 test +Please choose No. between 1 and 1, or enter search to search wallets +1 +Please input your password. +Lxc1992117 +After sign transaction hex string is 0ad4010a0208c72208c02252c2ae3b92e1409fb0b9d9a2335aae01081f12a9010a31747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e54726967676572536d617274436f6e747261637412740a1541caf9798d70a3c609b600f163e53cfe8f586e1b9f121541eca9bc828a3005b9a3b909f2cc5c2a54794de05f2244a9059cbb000000000000000000000041a5418b8da12e73075abb46375e7a15c758ea21fc000000000000000000000000000000000000000000000000000000000000000170938293cfa23390018094ebdc031241a776830e5cd054c6a94631b6d62704e249e7587ab3f036e5e4fac15cbf49e671262532e094e1a32ad858272da3e101958102df61b0f72f26756a94b608883a6f01 +TxId is 9c8d4b84e9a71ccaad86b0a96f790067d3fc7ea85c26b425e5d748b81d31a8b8 +Transfer 1 to TR311sD6KasRnofj5RnFiFBA2rH8RH2kYk broadcast successful. +Please check the given transaction id to get the result on blockchain using getTransactionInfoById command. +``` +### tronlink multi sign +> TronlinkMultiSign + +Create multi sign transactions and view the multi sign transaction list through the tronlink service. + +Example: +```console +wallet> tronlinkmultisign + +=== Multi-Sign Manager === +1. Multi-sign transaction list +2. Create multi-sign transaction +0. Exit +Please enter the number to operate: +``` + +### encoding converter +> EncodingConverter + +A Useful Encoding Converter. + +Example: +```console +wallet> EncodingConverter + +============================== + Encoding Converter (CLI) +============================== +1) TRON - EVM Address +2) Base64 Encode / Decode +3) Base58Check Encode / Decode +4) Public Key -> Address +5) Private Key -> Public Key & Address +0) Exit +> +``` + +### How to get privateKey through mnemonic +> GetPrivateKeyByMnemonic + +Get the private key through mnemonics. + +Example: +```console +wallet> GetPrivateKeyByMnemonic + +Please enter 12 or 24 words (separated by spaces) [Attempt 1/3]: +``` +### Get paginated now witness list +> GetPaginatedNowWitnessList + +Get paginated now witness list. + +Example: +```console +wallet> getPaginatedNowWitnessList 0 2 +{ + "witnesses": [ + { + "address": "TJmka325yjJKeFpQDwKSQAoNwEyNGhsaEV", + "voteCount": 5405926918, + "url": "http://sr-8.com", + "totalProduced": 1801675, + "totalMissed": 456, + "latestBlockNum": 64577529, + "latestSlotNum": 590063589, + "isJobs": true + }, + { + "address": "TFFLWM7tmKiwGtbh2mcz2rBssoFjHjSShG", + "voteCount": 2322244615, + "url": "http://sr-27.com", + "totalProduced": 1807756, + "totalMissed": 619, + "latestBlockNum": 64577530, + "latestSlotNum": 590063590, + "isJobs": true + } + ] +} +``` diff --git a/build.gradle b/java/build.gradle similarity index 99% rename from build.gradle rename to java/build.gradle index c2aadba5..b6cb8f48 100644 --- a/build.gradle +++ b/java/build.gradle @@ -81,7 +81,7 @@ dependencies { implementation group: 'com.typesafe', name: 'config', version: '1.3.2' implementation group: 'org.apache.commons', name: 'commons-lang3', version: '3.14.0' implementation group: 'com.alibaba', name: 'fastjson', version: '1.2.83' - implementation group: 'com.fasterxml.jackson.core', name: 'jackson-databind', version: '2.16.1' + implementation group: 'com.fasterxml.jackson.core', name: 'jackson-databind', version: '2.18.8' compileOnly 'org.projectlombok:lombok:1.18.24' annotationProcessor 'org.projectlombok:lombok:1.18.24' diff --git a/docs/plan-standard-cli-ledger.md b/java/docs/plan-standard-cli-ledger.md similarity index 100% rename from docs/plan-standard-cli-ledger.md rename to java/docs/plan-standard-cli-ledger.md diff --git a/docs/qa-ledger-smoke.md b/java/docs/qa-ledger-smoke.md similarity index 100% rename from docs/qa-ledger-smoke.md rename to java/docs/qa-ledger-smoke.md diff --git a/docs/spike-standard-cli-ledger.md b/java/docs/spike-standard-cli-ledger.md similarity index 100% rename from docs/spike-standard-cli-ledger.md rename to java/docs/spike-standard-cli-ledger.md diff --git a/docs/standard-cli-contract-spec.md b/java/docs/standard-cli-contract-spec.md similarity index 100% rename from docs/standard-cli-contract-spec.md rename to java/docs/standard-cli-contract-spec.md diff --git a/docs/standard-cli-user-manual.md b/java/docs/standard-cli-user-manual.md similarity index 100% rename from docs/standard-cli-user-manual.md rename to java/docs/standard-cli-user-manual.md diff --git a/gradle.properties b/java/gradle.properties similarity index 100% rename from gradle.properties rename to java/gradle.properties diff --git a/gradle/wrapper/gradle-wrapper.jar b/java/gradle/wrapper/gradle-wrapper.jar similarity index 100% rename from gradle/wrapper/gradle-wrapper.jar rename to java/gradle/wrapper/gradle-wrapper.jar diff --git a/gradle/wrapper/gradle-wrapper.properties b/java/gradle/wrapper/gradle-wrapper.properties similarity index 100% rename from gradle/wrapper/gradle-wrapper.properties rename to java/gradle/wrapper/gradle-wrapper.properties diff --git a/gradlew b/java/gradlew similarity index 100% rename from gradlew rename to java/gradlew diff --git a/gradlew.bat b/java/gradlew.bat similarity index 100% rename from gradlew.bat rename to java/gradlew.bat diff --git a/lombok.config b/java/lombok.config similarity index 100% rename from lombok.config rename to java/lombok.config diff --git a/qa/commands/alias.sh b/java/qa/commands/alias.sh similarity index 87% rename from qa/commands/alias.sh rename to java/qa/commands/alias.sh index be84c959..4583eaa5 100755 --- a/qa/commands/alias.sh +++ b/java/qa/commands/alias.sh @@ -1,6 +1,9 @@ #!/usr/bin/env bash set -euo pipefail +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +cd "$(cd "$SCRIPT_DIR/../.." && pwd)" + CLI="${CLI:-./gradlew -q run}" run_cli() { diff --git a/qa/config.sh b/java/qa/config.sh similarity index 100% rename from qa/config.sh rename to java/qa/config.sh diff --git a/qa/contracts.tsv b/java/qa/contracts.tsv similarity index 100% rename from qa/contracts.tsv rename to java/qa/contracts.tsv diff --git a/qa/lib/case_resolver.py b/java/qa/lib/case_resolver.py similarity index 100% rename from qa/lib/case_resolver.py rename to java/qa/lib/case_resolver.py diff --git a/qa/lib/cli.sh b/java/qa/lib/cli.sh similarity index 100% rename from qa/lib/cli.sh rename to java/qa/lib/cli.sh diff --git a/qa/lib/report.sh b/java/qa/lib/report.sh similarity index 100% rename from qa/lib/report.sh rename to java/qa/lib/report.sh diff --git a/qa/lib/semantic.sh b/java/qa/lib/semantic.sh similarity index 100% rename from qa/lib/semantic.sh rename to java/qa/lib/semantic.sh diff --git a/qa/manifest.tsv b/java/qa/manifest.tsv similarity index 100% rename from qa/manifest.tsv rename to java/qa/manifest.tsv diff --git a/qa/run.sh b/java/qa/run.sh similarity index 99% rename from qa/run.sh rename to java/qa/run.sh index 352c2bab..2a9c8c42 100644 --- a/qa/run.sh +++ b/java/qa/run.sh @@ -277,7 +277,7 @@ if [ "$NO_BUILD" -eq 1 ]; then echo "Skipping build (--no-build)." elif build_required; then echo "Building wallet-cli..." - ./gradlew shadowJar qaJar -q + (cd "$PROJECT_DIR" && ./gradlew shadowJar qaJar -q) echo "Build complete." else echo "Build skipped (wallet-cli.jar is up to date)." diff --git a/qa/task_runner.sh b/java/qa/task_runner.sh similarity index 100% rename from qa/task_runner.sh rename to java/qa/task_runner.sh diff --git a/qa/wallet-cli-runtime b/java/qa/wallet-cli-runtime similarity index 100% rename from qa/wallet-cli-runtime rename to java/qa/wallet-cli-runtime diff --git a/settings.gradle b/java/settings.gradle similarity index 100% rename from settings.gradle rename to java/settings.gradle diff --git a/src/main/.gitignore b/java/src/main/.gitignore similarity index 100% rename from src/main/.gitignore rename to java/src/main/.gitignore diff --git a/src/main/java/org/tron/common/crypto/ECKey.java b/java/src/main/java/org/tron/common/crypto/ECKey.java similarity index 100% rename from src/main/java/org/tron/common/crypto/ECKey.java rename to java/src/main/java/org/tron/common/crypto/ECKey.java diff --git a/src/main/java/org/tron/common/crypto/Hash.java b/java/src/main/java/org/tron/common/crypto/Hash.java similarity index 100% rename from src/main/java/org/tron/common/crypto/Hash.java rename to java/src/main/java/org/tron/common/crypto/Hash.java diff --git a/src/main/java/org/tron/common/crypto/HashInterface.java b/java/src/main/java/org/tron/common/crypto/HashInterface.java similarity index 100% rename from src/main/java/org/tron/common/crypto/HashInterface.java rename to java/src/main/java/org/tron/common/crypto/HashInterface.java diff --git a/src/main/java/org/tron/common/crypto/SM3Hash.java b/java/src/main/java/org/tron/common/crypto/SM3Hash.java similarity index 100% rename from src/main/java/org/tron/common/crypto/SM3Hash.java rename to java/src/main/java/org/tron/common/crypto/SM3Hash.java diff --git a/src/main/java/org/tron/common/crypto/Sha256Sm3Hash.java b/java/src/main/java/org/tron/common/crypto/Sha256Sm3Hash.java similarity index 100% rename from src/main/java/org/tron/common/crypto/Sha256Sm3Hash.java rename to java/src/main/java/org/tron/common/crypto/Sha256Sm3Hash.java diff --git a/src/main/java/org/tron/common/crypto/SignInterface.java b/java/src/main/java/org/tron/common/crypto/SignInterface.java similarity index 100% rename from src/main/java/org/tron/common/crypto/SignInterface.java rename to java/src/main/java/org/tron/common/crypto/SignInterface.java diff --git a/src/main/java/org/tron/common/crypto/SignUtils.java b/java/src/main/java/org/tron/common/crypto/SignUtils.java similarity index 100% rename from src/main/java/org/tron/common/crypto/SignUtils.java rename to java/src/main/java/org/tron/common/crypto/SignUtils.java diff --git a/src/main/java/org/tron/common/crypto/SignatureInterface.java b/java/src/main/java/org/tron/common/crypto/SignatureInterface.java similarity index 100% rename from src/main/java/org/tron/common/crypto/SignatureInterface.java rename to java/src/main/java/org/tron/common/crypto/SignatureInterface.java diff --git a/src/main/java/org/tron/common/crypto/SymmEncoder.java b/java/src/main/java/org/tron/common/crypto/SymmEncoder.java similarity index 100% rename from src/main/java/org/tron/common/crypto/SymmEncoder.java rename to java/src/main/java/org/tron/common/crypto/SymmEncoder.java diff --git a/src/main/java/org/tron/common/crypto/cryptohash/Digest.java b/java/src/main/java/org/tron/common/crypto/cryptohash/Digest.java similarity index 100% rename from src/main/java/org/tron/common/crypto/cryptohash/Digest.java rename to java/src/main/java/org/tron/common/crypto/cryptohash/Digest.java diff --git a/src/main/java/org/tron/common/crypto/cryptohash/DigestEngine.java b/java/src/main/java/org/tron/common/crypto/cryptohash/DigestEngine.java similarity index 100% rename from src/main/java/org/tron/common/crypto/cryptohash/DigestEngine.java rename to java/src/main/java/org/tron/common/crypto/cryptohash/DigestEngine.java diff --git a/src/main/java/org/tron/common/crypto/cryptohash/Keccak256.java b/java/src/main/java/org/tron/common/crypto/cryptohash/Keccak256.java similarity index 100% rename from src/main/java/org/tron/common/crypto/cryptohash/Keccak256.java rename to java/src/main/java/org/tron/common/crypto/cryptohash/Keccak256.java diff --git a/src/main/java/org/tron/common/crypto/cryptohash/Keccak512.java b/java/src/main/java/org/tron/common/crypto/cryptohash/Keccak512.java similarity index 100% rename from src/main/java/org/tron/common/crypto/cryptohash/Keccak512.java rename to java/src/main/java/org/tron/common/crypto/cryptohash/Keccak512.java diff --git a/src/main/java/org/tron/common/crypto/cryptohash/KeccakCore.java b/java/src/main/java/org/tron/common/crypto/cryptohash/KeccakCore.java similarity index 100% rename from src/main/java/org/tron/common/crypto/cryptohash/KeccakCore.java rename to java/src/main/java/org/tron/common/crypto/cryptohash/KeccakCore.java diff --git a/src/main/java/org/tron/common/crypto/jce/ECAlgorithmParameters.java b/java/src/main/java/org/tron/common/crypto/jce/ECAlgorithmParameters.java similarity index 100% rename from src/main/java/org/tron/common/crypto/jce/ECAlgorithmParameters.java rename to java/src/main/java/org/tron/common/crypto/jce/ECAlgorithmParameters.java diff --git a/src/main/java/org/tron/common/crypto/jce/ECKeyAgreement.java b/java/src/main/java/org/tron/common/crypto/jce/ECKeyAgreement.java similarity index 100% rename from src/main/java/org/tron/common/crypto/jce/ECKeyAgreement.java rename to java/src/main/java/org/tron/common/crypto/jce/ECKeyAgreement.java diff --git a/src/main/java/org/tron/common/crypto/jce/ECKeyFactory.java b/java/src/main/java/org/tron/common/crypto/jce/ECKeyFactory.java similarity index 100% rename from src/main/java/org/tron/common/crypto/jce/ECKeyFactory.java rename to java/src/main/java/org/tron/common/crypto/jce/ECKeyFactory.java diff --git a/src/main/java/org/tron/common/crypto/jce/ECKeyPairGenerator.java b/java/src/main/java/org/tron/common/crypto/jce/ECKeyPairGenerator.java similarity index 100% rename from src/main/java/org/tron/common/crypto/jce/ECKeyPairGenerator.java rename to java/src/main/java/org/tron/common/crypto/jce/ECKeyPairGenerator.java diff --git a/src/main/java/org/tron/common/crypto/jce/ECSignatureFactory.java b/java/src/main/java/org/tron/common/crypto/jce/ECSignatureFactory.java similarity index 100% rename from src/main/java/org/tron/common/crypto/jce/ECSignatureFactory.java rename to java/src/main/java/org/tron/common/crypto/jce/ECSignatureFactory.java diff --git a/src/main/java/org/tron/common/crypto/jce/TronCastleProvider.java b/java/src/main/java/org/tron/common/crypto/jce/TronCastleProvider.java similarity index 100% rename from src/main/java/org/tron/common/crypto/jce/TronCastleProvider.java rename to java/src/main/java/org/tron/common/crypto/jce/TronCastleProvider.java diff --git a/src/main/java/org/tron/common/crypto/sm2/SM2.java b/java/src/main/java/org/tron/common/crypto/sm2/SM2.java similarity index 100% rename from src/main/java/org/tron/common/crypto/sm2/SM2.java rename to java/src/main/java/org/tron/common/crypto/sm2/SM2.java diff --git a/src/main/java/org/tron/common/crypto/sm2/SM2Signer.java b/java/src/main/java/org/tron/common/crypto/sm2/SM2Signer.java similarity index 100% rename from src/main/java/org/tron/common/crypto/sm2/SM2Signer.java rename to java/src/main/java/org/tron/common/crypto/sm2/SM2Signer.java diff --git a/src/main/java/org/tron/common/enums/NetType.java b/java/src/main/java/org/tron/common/enums/NetType.java similarity index 100% rename from src/main/java/org/tron/common/enums/NetType.java rename to java/src/main/java/org/tron/common/enums/NetType.java diff --git a/src/main/java/org/tron/common/utils/AbiUtil.java b/java/src/main/java/org/tron/common/utils/AbiUtil.java similarity index 100% rename from src/main/java/org/tron/common/utils/AbiUtil.java rename to java/src/main/java/org/tron/common/utils/AbiUtil.java diff --git a/src/main/java/org/tron/common/utils/BIUtil.java b/java/src/main/java/org/tron/common/utils/BIUtil.java similarity index 100% rename from src/main/java/org/tron/common/utils/BIUtil.java rename to java/src/main/java/org/tron/common/utils/BIUtil.java diff --git a/src/main/java/org/tron/common/utils/Base58.java b/java/src/main/java/org/tron/common/utils/Base58.java similarity index 100% rename from src/main/java/org/tron/common/utils/Base58.java rename to java/src/main/java/org/tron/common/utils/Base58.java diff --git a/src/main/java/org/tron/common/utils/Bech32.java b/java/src/main/java/org/tron/common/utils/Bech32.java similarity index 100% rename from src/main/java/org/tron/common/utils/Bech32.java rename to java/src/main/java/org/tron/common/utils/Bech32.java diff --git a/src/main/java/org/tron/common/utils/ByteArray.java b/java/src/main/java/org/tron/common/utils/ByteArray.java similarity index 100% rename from src/main/java/org/tron/common/utils/ByteArray.java rename to java/src/main/java/org/tron/common/utils/ByteArray.java diff --git a/src/main/java/org/tron/common/utils/ByteArrayWrapper.java b/java/src/main/java/org/tron/common/utils/ByteArrayWrapper.java similarity index 100% rename from src/main/java/org/tron/common/utils/ByteArrayWrapper.java rename to java/src/main/java/org/tron/common/utils/ByteArrayWrapper.java diff --git a/src/main/java/org/tron/common/utils/ByteUtil.java b/java/src/main/java/org/tron/common/utils/ByteUtil.java similarity index 100% rename from src/main/java/org/tron/common/utils/ByteUtil.java rename to java/src/main/java/org/tron/common/utils/ByteUtil.java diff --git a/src/main/java/org/tron/common/utils/CaseInsensitiveCommandCompleter.java b/java/src/main/java/org/tron/common/utils/CaseInsensitiveCommandCompleter.java similarity index 100% rename from src/main/java/org/tron/common/utils/CaseInsensitiveCommandCompleter.java rename to java/src/main/java/org/tron/common/utils/CaseInsensitiveCommandCompleter.java diff --git a/src/main/java/org/tron/common/utils/CommandHelpUtil.java b/java/src/main/java/org/tron/common/utils/CommandHelpUtil.java similarity index 100% rename from src/main/java/org/tron/common/utils/CommandHelpUtil.java rename to java/src/main/java/org/tron/common/utils/CommandHelpUtil.java diff --git a/src/main/java/org/tron/common/utils/DataWord.java b/java/src/main/java/org/tron/common/utils/DataWord.java similarity index 100% rename from src/main/java/org/tron/common/utils/DataWord.java rename to java/src/main/java/org/tron/common/utils/DataWord.java diff --git a/src/main/java/org/tron/common/utils/DecodeUtil.java b/java/src/main/java/org/tron/common/utils/DecodeUtil.java similarity index 100% rename from src/main/java/org/tron/common/utils/DecodeUtil.java rename to java/src/main/java/org/tron/common/utils/DecodeUtil.java diff --git a/src/main/java/org/tron/common/utils/DomainValidator.java b/java/src/main/java/org/tron/common/utils/DomainValidator.java similarity index 100% rename from src/main/java/org/tron/common/utils/DomainValidator.java rename to java/src/main/java/org/tron/common/utils/DomainValidator.java diff --git a/src/main/java/org/tron/common/utils/FastByteComparisons.java b/java/src/main/java/org/tron/common/utils/FastByteComparisons.java similarity index 100% rename from src/main/java/org/tron/common/utils/FastByteComparisons.java rename to java/src/main/java/org/tron/common/utils/FastByteComparisons.java diff --git a/src/main/java/org/tron/common/utils/FilePermissionUtils.java b/java/src/main/java/org/tron/common/utils/FilePermissionUtils.java similarity index 100% rename from src/main/java/org/tron/common/utils/FilePermissionUtils.java rename to java/src/main/java/org/tron/common/utils/FilePermissionUtils.java diff --git a/src/main/java/org/tron/common/utils/FileUtil.java b/java/src/main/java/org/tron/common/utils/FileUtil.java similarity index 100% rename from src/main/java/org/tron/common/utils/FileUtil.java rename to java/src/main/java/org/tron/common/utils/FileUtil.java diff --git a/src/main/java/org/tron/common/utils/Hash.java b/java/src/main/java/org/tron/common/utils/Hash.java similarity index 100% rename from src/main/java/org/tron/common/utils/Hash.java rename to java/src/main/java/org/tron/common/utils/Hash.java diff --git a/src/main/java/org/tron/common/utils/HttpSelfFormatFieldName.java b/java/src/main/java/org/tron/common/utils/HttpSelfFormatFieldName.java similarity index 100% rename from src/main/java/org/tron/common/utils/HttpSelfFormatFieldName.java rename to java/src/main/java/org/tron/common/utils/HttpSelfFormatFieldName.java diff --git a/src/main/java/org/tron/common/utils/HttpUtils.java b/java/src/main/java/org/tron/common/utils/HttpUtils.java similarity index 100% rename from src/main/java/org/tron/common/utils/HttpUtils.java rename to java/src/main/java/org/tron/common/utils/HttpUtils.java diff --git a/src/main/java/org/tron/common/utils/JsonFormat.java b/java/src/main/java/org/tron/common/utils/JsonFormat.java similarity index 100% rename from src/main/java/org/tron/common/utils/JsonFormat.java rename to java/src/main/java/org/tron/common/utils/JsonFormat.java diff --git a/src/main/java/org/tron/common/utils/JsonFormatUtil.java b/java/src/main/java/org/tron/common/utils/JsonFormatUtil.java similarity index 100% rename from src/main/java/org/tron/common/utils/JsonFormatUtil.java rename to java/src/main/java/org/tron/common/utils/JsonFormatUtil.java diff --git a/src/main/java/org/tron/common/utils/MultiTxWebSocketClient.java b/java/src/main/java/org/tron/common/utils/MultiTxWebSocketClient.java similarity index 100% rename from src/main/java/org/tron/common/utils/MultiTxWebSocketClient.java rename to java/src/main/java/org/tron/common/utils/MultiTxWebSocketClient.java diff --git a/src/main/java/org/tron/common/utils/PathUtil.java b/java/src/main/java/org/tron/common/utils/PathUtil.java similarity index 100% rename from src/main/java/org/tron/common/utils/PathUtil.java rename to java/src/main/java/org/tron/common/utils/PathUtil.java diff --git a/src/main/java/org/tron/common/utils/Sha256Hash.java b/java/src/main/java/org/tron/common/utils/Sha256Hash.java similarity index 100% rename from src/main/java/org/tron/common/utils/Sha256Hash.java rename to java/src/main/java/org/tron/common/utils/Sha256Hash.java diff --git a/src/main/java/org/tron/common/utils/TransactionUtils.java b/java/src/main/java/org/tron/common/utils/TransactionUtils.java similarity index 100% rename from src/main/java/org/tron/common/utils/TransactionUtils.java rename to java/src/main/java/org/tron/common/utils/TransactionUtils.java diff --git a/src/main/java/org/tron/common/utils/Utils.java b/java/src/main/java/org/tron/common/utils/Utils.java similarity index 100% rename from src/main/java/org/tron/common/utils/Utils.java rename to java/src/main/java/org/tron/common/utils/Utils.java diff --git a/src/main/java/org/tron/common/zksnark/JLibrustzcash.java b/java/src/main/java/org/tron/common/zksnark/JLibrustzcash.java similarity index 100% rename from src/main/java/org/tron/common/zksnark/JLibrustzcash.java rename to java/src/main/java/org/tron/common/zksnark/JLibrustzcash.java diff --git a/src/main/java/org/tron/common/zksnark/JLibsodium.java b/java/src/main/java/org/tron/common/zksnark/JLibsodium.java similarity index 100% rename from src/main/java/org/tron/common/zksnark/JLibsodium.java rename to java/src/main/java/org/tron/common/zksnark/JLibsodium.java diff --git a/src/main/java/org/tron/common/zksnark/JLibsodiumParam.java b/java/src/main/java/org/tron/common/zksnark/JLibsodiumParam.java similarity index 100% rename from src/main/java/org/tron/common/zksnark/JLibsodiumParam.java rename to java/src/main/java/org/tron/common/zksnark/JLibsodiumParam.java diff --git a/src/main/java/org/tron/common/zksnark/LibrustzcashParam.java b/java/src/main/java/org/tron/common/zksnark/LibrustzcashParam.java similarity index 100% rename from src/main/java/org/tron/common/zksnark/LibrustzcashParam.java rename to java/src/main/java/org/tron/common/zksnark/LibrustzcashParam.java diff --git a/src/main/java/org/tron/core/config/Configuration.java b/java/src/main/java/org/tron/core/config/Configuration.java similarity index 100% rename from src/main/java/org/tron/core/config/Configuration.java rename to java/src/main/java/org/tron/core/config/Configuration.java diff --git a/src/main/java/org/tron/core/config/Parameter.java b/java/src/main/java/org/tron/core/config/Parameter.java similarity index 100% rename from src/main/java/org/tron/core/config/Parameter.java rename to java/src/main/java/org/tron/core/config/Parameter.java diff --git a/src/main/java/org/tron/core/converter/EncodingConverter.java b/java/src/main/java/org/tron/core/converter/EncodingConverter.java similarity index 100% rename from src/main/java/org/tron/core/converter/EncodingConverter.java rename to java/src/main/java/org/tron/core/converter/EncodingConverter.java diff --git a/src/main/java/org/tron/core/dao/AddressEntry.java b/java/src/main/java/org/tron/core/dao/AddressEntry.java similarity index 100% rename from src/main/java/org/tron/core/dao/AddressEntry.java rename to java/src/main/java/org/tron/core/dao/AddressEntry.java diff --git a/src/main/java/org/tron/core/dao/BackupRecord.java b/java/src/main/java/org/tron/core/dao/BackupRecord.java similarity index 100% rename from src/main/java/org/tron/core/dao/BackupRecord.java rename to java/src/main/java/org/tron/core/dao/BackupRecord.java diff --git a/src/main/java/org/tron/core/dao/Tx.java b/java/src/main/java/org/tron/core/dao/Tx.java similarity index 100% rename from src/main/java/org/tron/core/dao/Tx.java rename to java/src/main/java/org/tron/core/dao/Tx.java diff --git a/src/main/java/org/tron/core/exception/BadItemException.java b/java/src/main/java/org/tron/core/exception/BadItemException.java similarity index 100% rename from src/main/java/org/tron/core/exception/BadItemException.java rename to java/src/main/java/org/tron/core/exception/BadItemException.java diff --git a/src/main/java/org/tron/core/exception/CancelException.java b/java/src/main/java/org/tron/core/exception/CancelException.java similarity index 100% rename from src/main/java/org/tron/core/exception/CancelException.java rename to java/src/main/java/org/tron/core/exception/CancelException.java diff --git a/src/main/java/org/tron/core/exception/CipherException.java b/java/src/main/java/org/tron/core/exception/CipherException.java similarity index 100% rename from src/main/java/org/tron/core/exception/CipherException.java rename to java/src/main/java/org/tron/core/exception/CipherException.java diff --git a/src/main/java/org/tron/core/exception/EncodingException.java b/java/src/main/java/org/tron/core/exception/EncodingException.java similarity index 100% rename from src/main/java/org/tron/core/exception/EncodingException.java rename to java/src/main/java/org/tron/core/exception/EncodingException.java diff --git a/src/main/java/org/tron/core/exception/StoreException.java b/java/src/main/java/org/tron/core/exception/StoreException.java similarity index 100% rename from src/main/java/org/tron/core/exception/StoreException.java rename to java/src/main/java/org/tron/core/exception/StoreException.java diff --git a/src/main/java/org/tron/core/exception/TronException.java b/java/src/main/java/org/tron/core/exception/TronException.java similarity index 100% rename from src/main/java/org/tron/core/exception/TronException.java rename to java/src/main/java/org/tron/core/exception/TronException.java diff --git a/src/main/java/org/tron/core/exception/ZksnarkException.java b/java/src/main/java/org/tron/core/exception/ZksnarkException.java similarity index 100% rename from src/main/java/org/tron/core/exception/ZksnarkException.java rename to java/src/main/java/org/tron/core/exception/ZksnarkException.java diff --git a/src/main/java/org/tron/core/handler/MultiTxMessageHandler.java b/java/src/main/java/org/tron/core/handler/MultiTxMessageHandler.java similarity index 100% rename from src/main/java/org/tron/core/handler/MultiTxMessageHandler.java rename to java/src/main/java/org/tron/core/handler/MultiTxMessageHandler.java diff --git a/src/main/java/org/tron/core/manager/BackupRecordManager.java b/java/src/main/java/org/tron/core/manager/BackupRecordManager.java similarity index 100% rename from src/main/java/org/tron/core/manager/BackupRecordManager.java rename to java/src/main/java/org/tron/core/manager/BackupRecordManager.java diff --git a/src/main/java/org/tron/core/manager/TxHistoryManager.java b/java/src/main/java/org/tron/core/manager/TxHistoryManager.java similarity index 100% rename from src/main/java/org/tron/core/manager/TxHistoryManager.java rename to java/src/main/java/org/tron/core/manager/TxHistoryManager.java diff --git a/src/main/java/org/tron/core/manager/UpdateAccountPermissionInteractive.java b/java/src/main/java/org/tron/core/manager/UpdateAccountPermissionInteractive.java similarity index 100% rename from src/main/java/org/tron/core/manager/UpdateAccountPermissionInteractive.java rename to java/src/main/java/org/tron/core/manager/UpdateAccountPermissionInteractive.java diff --git a/src/main/java/org/tron/core/service/AddressBookInteractive.java b/java/src/main/java/org/tron/core/service/AddressBookInteractive.java similarity index 100% rename from src/main/java/org/tron/core/service/AddressBookInteractive.java rename to java/src/main/java/org/tron/core/service/AddressBookInteractive.java diff --git a/src/main/java/org/tron/core/service/AddressBookService.java b/java/src/main/java/org/tron/core/service/AddressBookService.java similarity index 100% rename from src/main/java/org/tron/core/service/AddressBookService.java rename to java/src/main/java/org/tron/core/service/AddressBookService.java diff --git a/src/main/java/org/tron/core/viewer/AddressBookView.java b/java/src/main/java/org/tron/core/viewer/AddressBookView.java similarity index 100% rename from src/main/java/org/tron/core/viewer/AddressBookView.java rename to java/src/main/java/org/tron/core/viewer/AddressBookView.java diff --git a/src/main/java/org/tron/core/viewer/BackupRecordsViewer.java b/java/src/main/java/org/tron/core/viewer/BackupRecordsViewer.java similarity index 100% rename from src/main/java/org/tron/core/viewer/BackupRecordsViewer.java rename to java/src/main/java/org/tron/core/viewer/BackupRecordsViewer.java diff --git a/src/main/java/org/tron/core/viewer/TxHistoryViewer.java b/java/src/main/java/org/tron/core/viewer/TxHistoryViewer.java similarity index 100% rename from src/main/java/org/tron/core/viewer/TxHistoryViewer.java rename to java/src/main/java/org/tron/core/viewer/TxHistoryViewer.java diff --git a/src/main/java/org/tron/core/zen/ZenUtils.java b/java/src/main/java/org/tron/core/zen/ZenUtils.java similarity index 100% rename from src/main/java/org/tron/core/zen/ZenUtils.java rename to java/src/main/java/org/tron/core/zen/ZenUtils.java diff --git a/src/main/java/org/tron/core/zen/address/DiversifierT.java b/java/src/main/java/org/tron/core/zen/address/DiversifierT.java similarity index 100% rename from src/main/java/org/tron/core/zen/address/DiversifierT.java rename to java/src/main/java/org/tron/core/zen/address/DiversifierT.java diff --git a/src/main/java/org/tron/core/zen/address/ExpandedSpendingKey.java b/java/src/main/java/org/tron/core/zen/address/ExpandedSpendingKey.java similarity index 100% rename from src/main/java/org/tron/core/zen/address/ExpandedSpendingKey.java rename to java/src/main/java/org/tron/core/zen/address/ExpandedSpendingKey.java diff --git a/src/main/java/org/tron/core/zen/address/FullViewingKey.java b/java/src/main/java/org/tron/core/zen/address/FullViewingKey.java similarity index 100% rename from src/main/java/org/tron/core/zen/address/FullViewingKey.java rename to java/src/main/java/org/tron/core/zen/address/FullViewingKey.java diff --git a/src/main/java/org/tron/core/zen/address/IncomingViewingKey.java b/java/src/main/java/org/tron/core/zen/address/IncomingViewingKey.java similarity index 100% rename from src/main/java/org/tron/core/zen/address/IncomingViewingKey.java rename to java/src/main/java/org/tron/core/zen/address/IncomingViewingKey.java diff --git a/src/main/java/org/tron/core/zen/address/KeyIo.java b/java/src/main/java/org/tron/core/zen/address/KeyIo.java similarity index 100% rename from src/main/java/org/tron/core/zen/address/KeyIo.java rename to java/src/main/java/org/tron/core/zen/address/KeyIo.java diff --git a/src/main/java/org/tron/core/zen/address/PaymentAddress.java b/java/src/main/java/org/tron/core/zen/address/PaymentAddress.java similarity index 100% rename from src/main/java/org/tron/core/zen/address/PaymentAddress.java rename to java/src/main/java/org/tron/core/zen/address/PaymentAddress.java diff --git a/src/main/java/org/tron/core/zen/address/SpendingKey.java b/java/src/main/java/org/tron/core/zen/address/SpendingKey.java similarity index 100% rename from src/main/java/org/tron/core/zen/address/SpendingKey.java rename to java/src/main/java/org/tron/core/zen/address/SpendingKey.java diff --git a/src/main/java/org/tron/demo/Debug.java b/java/src/main/java/org/tron/demo/Debug.java similarity index 100% rename from src/main/java/org/tron/demo/Debug.java rename to java/src/main/java/org/tron/demo/Debug.java diff --git a/src/main/java/org/tron/demo/ECKeyDemo.java b/java/src/main/java/org/tron/demo/ECKeyDemo.java similarity index 100% rename from src/main/java/org/tron/demo/ECKeyDemo.java rename to java/src/main/java/org/tron/demo/ECKeyDemo.java diff --git a/src/main/java/org/tron/demo/SelectFileDemo.java b/java/src/main/java/org/tron/demo/SelectFileDemo.java similarity index 100% rename from src/main/java/org/tron/demo/SelectFileDemo.java rename to java/src/main/java/org/tron/demo/SelectFileDemo.java diff --git a/src/main/java/org/tron/demo/TransactionSignDemoForSM2.java b/java/src/main/java/org/tron/demo/TransactionSignDemoForSM2.java similarity index 100% rename from src/main/java/org/tron/demo/TransactionSignDemoForSM2.java rename to java/src/main/java/org/tron/demo/TransactionSignDemoForSM2.java diff --git a/src/main/java/org/tron/gasfree/GasFreeApi.java b/java/src/main/java/org/tron/gasfree/GasFreeApi.java similarity index 100% rename from src/main/java/org/tron/gasfree/GasFreeApi.java rename to java/src/main/java/org/tron/gasfree/GasFreeApi.java diff --git a/src/main/java/org/tron/gasfree/request/GasFreeSubmitRequest.java b/java/src/main/java/org/tron/gasfree/request/GasFreeSubmitRequest.java similarity index 100% rename from src/main/java/org/tron/gasfree/request/GasFreeSubmitRequest.java rename to java/src/main/java/org/tron/gasfree/request/GasFreeSubmitRequest.java diff --git a/src/main/java/org/tron/gasfree/response/GasFreeAddressResponse.java b/java/src/main/java/org/tron/gasfree/response/GasFreeAddressResponse.java similarity index 100% rename from src/main/java/org/tron/gasfree/response/GasFreeAddressResponse.java rename to java/src/main/java/org/tron/gasfree/response/GasFreeAddressResponse.java diff --git a/src/main/java/org/tron/keystore/CheckStrength.java b/java/src/main/java/org/tron/keystore/CheckStrength.java similarity index 100% rename from src/main/java/org/tron/keystore/CheckStrength.java rename to java/src/main/java/org/tron/keystore/CheckStrength.java diff --git a/src/main/java/org/tron/keystore/ClearWalletUtils.java b/java/src/main/java/org/tron/keystore/ClearWalletUtils.java similarity index 100% rename from src/main/java/org/tron/keystore/ClearWalletUtils.java rename to java/src/main/java/org/tron/keystore/ClearWalletUtils.java diff --git a/src/main/java/org/tron/keystore/Credentials.java b/java/src/main/java/org/tron/keystore/Credentials.java similarity index 100% rename from src/main/java/org/tron/keystore/Credentials.java rename to java/src/main/java/org/tron/keystore/Credentials.java diff --git a/src/main/java/org/tron/keystore/CredentialsEckey.java b/java/src/main/java/org/tron/keystore/CredentialsEckey.java similarity index 100% rename from src/main/java/org/tron/keystore/CredentialsEckey.java rename to java/src/main/java/org/tron/keystore/CredentialsEckey.java diff --git a/src/main/java/org/tron/keystore/CredentialsSM2.java b/java/src/main/java/org/tron/keystore/CredentialsSM2.java similarity index 100% rename from src/main/java/org/tron/keystore/CredentialsSM2.java rename to java/src/main/java/org/tron/keystore/CredentialsSM2.java diff --git a/src/main/java/org/tron/keystore/SKeyCapsule.java b/java/src/main/java/org/tron/keystore/SKeyCapsule.java similarity index 100% rename from src/main/java/org/tron/keystore/SKeyCapsule.java rename to java/src/main/java/org/tron/keystore/SKeyCapsule.java diff --git a/src/main/java/org/tron/keystore/SKeyEncryptor.java b/java/src/main/java/org/tron/keystore/SKeyEncryptor.java similarity index 100% rename from src/main/java/org/tron/keystore/SKeyEncryptor.java rename to java/src/main/java/org/tron/keystore/SKeyEncryptor.java diff --git a/src/main/java/org/tron/keystore/StringUtils.java b/java/src/main/java/org/tron/keystore/StringUtils.java similarity index 100% rename from src/main/java/org/tron/keystore/StringUtils.java rename to java/src/main/java/org/tron/keystore/StringUtils.java diff --git a/src/main/java/org/tron/keystore/Wallet.java b/java/src/main/java/org/tron/keystore/Wallet.java similarity index 100% rename from src/main/java/org/tron/keystore/Wallet.java rename to java/src/main/java/org/tron/keystore/Wallet.java diff --git a/src/main/java/org/tron/keystore/WalletFile.java b/java/src/main/java/org/tron/keystore/WalletFile.java similarity index 100% rename from src/main/java/org/tron/keystore/WalletFile.java rename to java/src/main/java/org/tron/keystore/WalletFile.java diff --git a/src/main/java/org/tron/keystore/WalletUtils.java b/java/src/main/java/org/tron/keystore/WalletUtils.java similarity index 100% rename from src/main/java/org/tron/keystore/WalletUtils.java rename to java/src/main/java/org/tron/keystore/WalletUtils.java diff --git a/src/main/java/org/tron/ledger/LedgerAddressUtil.java b/java/src/main/java/org/tron/ledger/LedgerAddressUtil.java similarity index 100% rename from src/main/java/org/tron/ledger/LedgerAddressUtil.java rename to java/src/main/java/org/tron/ledger/LedgerAddressUtil.java diff --git a/src/main/java/org/tron/ledger/LedgerConst.java b/java/src/main/java/org/tron/ledger/LedgerConst.java similarity index 100% rename from src/main/java/org/tron/ledger/LedgerConst.java rename to java/src/main/java/org/tron/ledger/LedgerConst.java diff --git a/src/main/java/org/tron/ledger/LedgerFileUtil.java b/java/src/main/java/org/tron/ledger/LedgerFileUtil.java similarity index 100% rename from src/main/java/org/tron/ledger/LedgerFileUtil.java rename to java/src/main/java/org/tron/ledger/LedgerFileUtil.java diff --git a/src/main/java/org/tron/ledger/LedgerSignUtil.java b/java/src/main/java/org/tron/ledger/LedgerSignUtil.java similarity index 100% rename from src/main/java/org/tron/ledger/LedgerSignUtil.java rename to java/src/main/java/org/tron/ledger/LedgerSignUtil.java diff --git a/src/main/java/org/tron/ledger/TronLedgerGetAddress.java b/java/src/main/java/org/tron/ledger/TronLedgerGetAddress.java similarity index 100% rename from src/main/java/org/tron/ledger/TronLedgerGetAddress.java rename to java/src/main/java/org/tron/ledger/TronLedgerGetAddress.java diff --git a/src/main/java/org/tron/ledger/console/ConsoleColor.java b/java/src/main/java/org/tron/ledger/console/ConsoleColor.java similarity index 100% rename from src/main/java/org/tron/ledger/console/ConsoleColor.java rename to java/src/main/java/org/tron/ledger/console/ConsoleColor.java diff --git a/src/main/java/org/tron/ledger/console/ImportAccount.java b/java/src/main/java/org/tron/ledger/console/ImportAccount.java similarity index 100% rename from src/main/java/org/tron/ledger/console/ImportAccount.java rename to java/src/main/java/org/tron/ledger/console/ImportAccount.java diff --git a/src/main/java/org/tron/ledger/console/TronLedgerImportAccount.java b/java/src/main/java/org/tron/ledger/console/TronLedgerImportAccount.java similarity index 100% rename from src/main/java/org/tron/ledger/console/TronLedgerImportAccount.java rename to java/src/main/java/org/tron/ledger/console/TronLedgerImportAccount.java diff --git a/src/main/java/org/tron/ledger/listener/BaseListener.java b/java/src/main/java/org/tron/ledger/listener/BaseListener.java similarity index 100% rename from src/main/java/org/tron/ledger/listener/BaseListener.java rename to java/src/main/java/org/tron/ledger/listener/BaseListener.java diff --git a/src/main/java/org/tron/ledger/listener/LedgerEventListener.java b/java/src/main/java/org/tron/ledger/listener/LedgerEventListener.java similarity index 100% rename from src/main/java/org/tron/ledger/listener/LedgerEventListener.java rename to java/src/main/java/org/tron/ledger/listener/LedgerEventListener.java diff --git a/src/main/java/org/tron/ledger/listener/TransactionSignManager.java b/java/src/main/java/org/tron/ledger/listener/TransactionSignManager.java similarity index 100% rename from src/main/java/org/tron/ledger/listener/TransactionSignManager.java rename to java/src/main/java/org/tron/ledger/listener/TransactionSignManager.java diff --git a/src/main/java/org/tron/ledger/sdk/ApduExchangeHandler.java b/java/src/main/java/org/tron/ledger/sdk/ApduExchangeHandler.java similarity index 100% rename from src/main/java/org/tron/ledger/sdk/ApduExchangeHandler.java rename to java/src/main/java/org/tron/ledger/sdk/ApduExchangeHandler.java diff --git a/src/main/java/org/tron/ledger/sdk/ApduMessageBuilder.java b/java/src/main/java/org/tron/ledger/sdk/ApduMessageBuilder.java similarity index 100% rename from src/main/java/org/tron/ledger/sdk/ApduMessageBuilder.java rename to java/src/main/java/org/tron/ledger/sdk/ApduMessageBuilder.java diff --git a/src/main/java/org/tron/ledger/sdk/BIP32PathParser.java b/java/src/main/java/org/tron/ledger/sdk/BIP32PathParser.java similarity index 100% rename from src/main/java/org/tron/ledger/sdk/BIP32PathParser.java rename to java/src/main/java/org/tron/ledger/sdk/BIP32PathParser.java diff --git a/src/main/java/org/tron/ledger/sdk/ByteArrayBuilder.java b/java/src/main/java/org/tron/ledger/sdk/ByteArrayBuilder.java similarity index 100% rename from src/main/java/org/tron/ledger/sdk/ByteArrayBuilder.java rename to java/src/main/java/org/tron/ledger/sdk/ByteArrayBuilder.java diff --git a/src/main/java/org/tron/ledger/sdk/CommonUtil.java b/java/src/main/java/org/tron/ledger/sdk/CommonUtil.java similarity index 100% rename from src/main/java/org/tron/ledger/sdk/CommonUtil.java rename to java/src/main/java/org/tron/ledger/sdk/CommonUtil.java diff --git a/src/main/java/org/tron/ledger/sdk/LedgerConstant.java b/java/src/main/java/org/tron/ledger/sdk/LedgerConstant.java similarity index 100% rename from src/main/java/org/tron/ledger/sdk/LedgerConstant.java rename to java/src/main/java/org/tron/ledger/sdk/LedgerConstant.java diff --git a/src/main/java/org/tron/ledger/sdk/LedgerProtocol.java b/java/src/main/java/org/tron/ledger/sdk/LedgerProtocol.java similarity index 100% rename from src/main/java/org/tron/ledger/sdk/LedgerProtocol.java rename to java/src/main/java/org/tron/ledger/sdk/LedgerProtocol.java diff --git a/src/main/java/org/tron/ledger/wrapper/ContractTypeChecker.java b/java/src/main/java/org/tron/ledger/wrapper/ContractTypeChecker.java similarity index 100% rename from src/main/java/org/tron/ledger/wrapper/ContractTypeChecker.java rename to java/src/main/java/org/tron/ledger/wrapper/ContractTypeChecker.java diff --git a/src/main/java/org/tron/ledger/wrapper/DebugConfig.java b/java/src/main/java/org/tron/ledger/wrapper/DebugConfig.java similarity index 100% rename from src/main/java/org/tron/ledger/wrapper/DebugConfig.java rename to java/src/main/java/org/tron/ledger/wrapper/DebugConfig.java diff --git a/src/main/java/org/tron/ledger/wrapper/HidServicesWrapper.java b/java/src/main/java/org/tron/ledger/wrapper/HidServicesWrapper.java similarity index 100% rename from src/main/java/org/tron/ledger/wrapper/HidServicesWrapper.java rename to java/src/main/java/org/tron/ledger/wrapper/HidServicesWrapper.java diff --git a/src/main/java/org/tron/ledger/wrapper/LedgerSignResult.java b/java/src/main/java/org/tron/ledger/wrapper/LedgerSignResult.java similarity index 100% rename from src/main/java/org/tron/ledger/wrapper/LedgerSignResult.java rename to java/src/main/java/org/tron/ledger/wrapper/LedgerSignResult.java diff --git a/src/main/java/org/tron/ledger/wrapper/LedgerUserHelper.java b/java/src/main/java/org/tron/ledger/wrapper/LedgerUserHelper.java similarity index 100% rename from src/main/java/org/tron/ledger/wrapper/LedgerUserHelper.java rename to java/src/main/java/org/tron/ledger/wrapper/LedgerUserHelper.java diff --git a/src/main/java/org/tron/ledger/wrapper/TransOwnerChecker.java b/java/src/main/java/org/tron/ledger/wrapper/TransOwnerChecker.java similarity index 100% rename from src/main/java/org/tron/ledger/wrapper/TransOwnerChecker.java rename to java/src/main/java/org/tron/ledger/wrapper/TransOwnerChecker.java diff --git a/src/main/java/org/tron/mnemonic/Mnemonic.java b/java/src/main/java/org/tron/mnemonic/Mnemonic.java similarity index 100% rename from src/main/java/org/tron/mnemonic/Mnemonic.java rename to java/src/main/java/org/tron/mnemonic/Mnemonic.java diff --git a/src/main/java/org/tron/mnemonic/MnemonicFile.java b/java/src/main/java/org/tron/mnemonic/MnemonicFile.java similarity index 100% rename from src/main/java/org/tron/mnemonic/MnemonicFile.java rename to java/src/main/java/org/tron/mnemonic/MnemonicFile.java diff --git a/src/main/java/org/tron/mnemonic/MnemonicUtils.java b/java/src/main/java/org/tron/mnemonic/MnemonicUtils.java similarity index 100% rename from src/main/java/org/tron/mnemonic/MnemonicUtils.java rename to java/src/main/java/org/tron/mnemonic/MnemonicUtils.java diff --git a/src/main/java/org/tron/mnemonic/SubAccount.java b/java/src/main/java/org/tron/mnemonic/SubAccount.java similarity index 100% rename from src/main/java/org/tron/mnemonic/SubAccount.java rename to java/src/main/java/org/tron/mnemonic/SubAccount.java diff --git a/src/main/java/org/tron/multi/AuthInfo.java b/java/src/main/java/org/tron/multi/AuthInfo.java similarity index 100% rename from src/main/java/org/tron/multi/AuthInfo.java rename to java/src/main/java/org/tron/multi/AuthInfo.java diff --git a/src/main/java/org/tron/multi/MultiConfig.java b/java/src/main/java/org/tron/multi/MultiConfig.java similarity index 100% rename from src/main/java/org/tron/multi/MultiConfig.java rename to java/src/main/java/org/tron/multi/MultiConfig.java diff --git a/src/main/java/org/tron/multi/MultiSignService.java b/java/src/main/java/org/tron/multi/MultiSignService.java similarity index 100% rename from src/main/java/org/tron/multi/MultiSignService.java rename to java/src/main/java/org/tron/multi/MultiSignService.java diff --git a/src/main/java/org/tron/multi/MultiTxSummaryParser.java b/java/src/main/java/org/tron/multi/MultiTxSummaryParser.java similarity index 100% rename from src/main/java/org/tron/multi/MultiTxSummaryParser.java rename to java/src/main/java/org/tron/multi/MultiTxSummaryParser.java diff --git a/src/main/java/org/tron/multi/Permission.java b/java/src/main/java/org/tron/multi/Permission.java similarity index 100% rename from src/main/java/org/tron/multi/Permission.java rename to java/src/main/java/org/tron/multi/Permission.java diff --git a/src/main/java/org/tron/test/Test.java b/java/src/main/java/org/tron/test/Test.java similarity index 100% rename from src/main/java/org/tron/test/Test.java rename to java/src/main/java/org/tron/test/Test.java diff --git a/src/main/java/org/tron/walletcli/ApiClientFactory.java b/java/src/main/java/org/tron/walletcli/ApiClientFactory.java similarity index 100% rename from src/main/java/org/tron/walletcli/ApiClientFactory.java rename to java/src/main/java/org/tron/walletcli/ApiClientFactory.java diff --git a/src/main/java/org/tron/walletcli/Client.java b/java/src/main/java/org/tron/walletcli/Client.java similarity index 100% rename from src/main/java/org/tron/walletcli/Client.java rename to java/src/main/java/org/tron/walletcli/Client.java diff --git a/src/main/java/org/tron/walletcli/WalletApiWrapper.java b/java/src/main/java/org/tron/walletcli/WalletApiWrapper.java similarity index 100% rename from src/main/java/org/tron/walletcli/WalletApiWrapper.java rename to java/src/main/java/org/tron/walletcli/WalletApiWrapper.java diff --git a/src/main/java/org/tron/walletcli/cli/ActiveWalletConfig.java b/java/src/main/java/org/tron/walletcli/cli/ActiveWalletConfig.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/ActiveWalletConfig.java rename to java/src/main/java/org/tron/walletcli/cli/ActiveWalletConfig.java diff --git a/src/main/java/org/tron/walletcli/cli/CliAbortException.java b/java/src/main/java/org/tron/walletcli/cli/CliAbortException.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/CliAbortException.java rename to java/src/main/java/org/tron/walletcli/cli/CliAbortException.java diff --git a/src/main/java/org/tron/walletcli/cli/CliUsageException.java b/java/src/main/java/org/tron/walletcli/cli/CliUsageException.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/CliUsageException.java rename to java/src/main/java/org/tron/walletcli/cli/CliUsageException.java diff --git a/src/main/java/org/tron/walletcli/cli/CommandContext.java b/java/src/main/java/org/tron/walletcli/cli/CommandContext.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/CommandContext.java rename to java/src/main/java/org/tron/walletcli/cli/CommandContext.java diff --git a/src/main/java/org/tron/walletcli/cli/CommandDefinition.java b/java/src/main/java/org/tron/walletcli/cli/CommandDefinition.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/CommandDefinition.java rename to java/src/main/java/org/tron/walletcli/cli/CommandDefinition.java diff --git a/src/main/java/org/tron/walletcli/cli/CommandErrorException.java b/java/src/main/java/org/tron/walletcli/cli/CommandErrorException.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/CommandErrorException.java rename to java/src/main/java/org/tron/walletcli/cli/CommandErrorException.java diff --git a/src/main/java/org/tron/walletcli/cli/CommandHandler.java b/java/src/main/java/org/tron/walletcli/cli/CommandHandler.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/CommandHandler.java rename to java/src/main/java/org/tron/walletcli/cli/CommandHandler.java diff --git a/src/main/java/org/tron/walletcli/cli/CommandRegistry.java b/java/src/main/java/org/tron/walletcli/cli/CommandRegistry.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/CommandRegistry.java rename to java/src/main/java/org/tron/walletcli/cli/CommandRegistry.java diff --git a/src/main/java/org/tron/walletcli/cli/GlobalOptions.java b/java/src/main/java/org/tron/walletcli/cli/GlobalOptions.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/GlobalOptions.java rename to java/src/main/java/org/tron/walletcli/cli/GlobalOptions.java diff --git a/src/main/java/org/tron/walletcli/cli/OptionDef.java b/java/src/main/java/org/tron/walletcli/cli/OptionDef.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/OptionDef.java rename to java/src/main/java/org/tron/walletcli/cli/OptionDef.java diff --git a/src/main/java/org/tron/walletcli/cli/OutputFormatter.java b/java/src/main/java/org/tron/walletcli/cli/OutputFormatter.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/OutputFormatter.java rename to java/src/main/java/org/tron/walletcli/cli/OutputFormatter.java diff --git a/src/main/java/org/tron/walletcli/cli/ParsedOptions.java b/java/src/main/java/org/tron/walletcli/cli/ParsedOptions.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/ParsedOptions.java rename to java/src/main/java/org/tron/walletcli/cli/ParsedOptions.java diff --git a/src/main/java/org/tron/walletcli/cli/StandardCliRunner.java b/java/src/main/java/org/tron/walletcli/cli/StandardCliRunner.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/StandardCliRunner.java rename to java/src/main/java/org/tron/walletcli/cli/StandardCliRunner.java diff --git a/src/main/java/org/tron/walletcli/cli/StdinPasswordReader.java b/java/src/main/java/org/tron/walletcli/cli/StdinPasswordReader.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/StdinPasswordReader.java rename to java/src/main/java/org/tron/walletcli/cli/StdinPasswordReader.java diff --git a/src/main/java/org/tron/walletcli/cli/aliases/AliasEntry.java b/java/src/main/java/org/tron/walletcli/cli/aliases/AliasEntry.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/aliases/AliasEntry.java rename to java/src/main/java/org/tron/walletcli/cli/aliases/AliasEntry.java diff --git a/src/main/java/org/tron/walletcli/cli/aliases/AliasResolutionException.java b/java/src/main/java/org/tron/walletcli/cli/aliases/AliasResolutionException.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/aliases/AliasResolutionException.java rename to java/src/main/java/org/tron/walletcli/cli/aliases/AliasResolutionException.java diff --git a/src/main/java/org/tron/walletcli/cli/aliases/AliasResolver.java b/java/src/main/java/org/tron/walletcli/cli/aliases/AliasResolver.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/aliases/AliasResolver.java rename to java/src/main/java/org/tron/walletcli/cli/aliases/AliasResolver.java diff --git a/src/main/java/org/tron/walletcli/cli/aliases/AliasStore.java b/java/src/main/java/org/tron/walletcli/cli/aliases/AliasStore.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/aliases/AliasStore.java rename to java/src/main/java/org/tron/walletcli/cli/aliases/AliasStore.java diff --git a/src/main/java/org/tron/walletcli/cli/aliases/AliasStoreLoader.java b/java/src/main/java/org/tron/walletcli/cli/aliases/AliasStoreLoader.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/aliases/AliasStoreLoader.java rename to java/src/main/java/org/tron/walletcli/cli/aliases/AliasStoreLoader.java diff --git a/src/main/java/org/tron/walletcli/cli/aliases/AliasType.java b/java/src/main/java/org/tron/walletcli/cli/aliases/AliasType.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/aliases/AliasType.java rename to java/src/main/java/org/tron/walletcli/cli/aliases/AliasType.java diff --git a/src/main/java/org/tron/walletcli/cli/aliases/AliasValidation.java b/java/src/main/java/org/tron/walletcli/cli/aliases/AliasValidation.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/aliases/AliasValidation.java rename to java/src/main/java/org/tron/walletcli/cli/aliases/AliasValidation.java diff --git a/src/main/java/org/tron/walletcli/cli/aliases/ResolutionResult.java b/java/src/main/java/org/tron/walletcli/cli/aliases/ResolutionResult.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/aliases/ResolutionResult.java rename to java/src/main/java/org/tron/walletcli/cli/aliases/ResolutionResult.java diff --git a/src/main/java/org/tron/walletcli/cli/commands/AliasCommands.java b/java/src/main/java/org/tron/walletcli/cli/commands/AliasCommands.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/commands/AliasCommands.java rename to java/src/main/java/org/tron/walletcli/cli/commands/AliasCommands.java diff --git a/src/main/java/org/tron/walletcli/cli/commands/CommandSupport.java b/java/src/main/java/org/tron/walletcli/cli/commands/CommandSupport.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/commands/CommandSupport.java rename to java/src/main/java/org/tron/walletcli/cli/commands/CommandSupport.java diff --git a/src/main/java/org/tron/walletcli/cli/commands/ContractCommands.java b/java/src/main/java/org/tron/walletcli/cli/commands/ContractCommands.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/commands/ContractCommands.java rename to java/src/main/java/org/tron/walletcli/cli/commands/ContractCommands.java diff --git a/src/main/java/org/tron/walletcli/cli/commands/ExchangeCommands.java b/java/src/main/java/org/tron/walletcli/cli/commands/ExchangeCommands.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/commands/ExchangeCommands.java rename to java/src/main/java/org/tron/walletcli/cli/commands/ExchangeCommands.java diff --git a/src/main/java/org/tron/walletcli/cli/commands/MiscCommands.java b/java/src/main/java/org/tron/walletcli/cli/commands/MiscCommands.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/commands/MiscCommands.java rename to java/src/main/java/org/tron/walletcli/cli/commands/MiscCommands.java diff --git a/src/main/java/org/tron/walletcli/cli/commands/ProposalCommands.java b/java/src/main/java/org/tron/walletcli/cli/commands/ProposalCommands.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/commands/ProposalCommands.java rename to java/src/main/java/org/tron/walletcli/cli/commands/ProposalCommands.java diff --git a/src/main/java/org/tron/walletcli/cli/commands/QueryCommands.java b/java/src/main/java/org/tron/walletcli/cli/commands/QueryCommands.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/commands/QueryCommands.java rename to java/src/main/java/org/tron/walletcli/cli/commands/QueryCommands.java diff --git a/src/main/java/org/tron/walletcli/cli/commands/StakingCommands.java b/java/src/main/java/org/tron/walletcli/cli/commands/StakingCommands.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/commands/StakingCommands.java rename to java/src/main/java/org/tron/walletcli/cli/commands/StakingCommands.java diff --git a/src/main/java/org/tron/walletcli/cli/commands/TransactionCommands.java b/java/src/main/java/org/tron/walletcli/cli/commands/TransactionCommands.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/commands/TransactionCommands.java rename to java/src/main/java/org/tron/walletcli/cli/commands/TransactionCommands.java diff --git a/src/main/java/org/tron/walletcli/cli/commands/WalletCommands.java b/java/src/main/java/org/tron/walletcli/cli/commands/WalletCommands.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/commands/WalletCommands.java rename to java/src/main/java/org/tron/walletcli/cli/commands/WalletCommands.java diff --git a/src/main/java/org/tron/walletcli/cli/commands/WitnessCommands.java b/java/src/main/java/org/tron/walletcli/cli/commands/WitnessCommands.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/commands/WitnessCommands.java rename to java/src/main/java/org/tron/walletcli/cli/commands/WitnessCommands.java diff --git a/src/main/java/org/tron/walletcli/cli/ledger/LedgerPorts.java b/java/src/main/java/org/tron/walletcli/cli/ledger/LedgerPorts.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/ledger/LedgerPorts.java rename to java/src/main/java/org/tron/walletcli/cli/ledger/LedgerPorts.java diff --git a/src/main/java/org/tron/walletcli/cli/ledger/LedgerSignOutcome.java b/java/src/main/java/org/tron/walletcli/cli/ledger/LedgerSignOutcome.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/ledger/LedgerSignOutcome.java rename to java/src/main/java/org/tron/walletcli/cli/ledger/LedgerSignOutcome.java diff --git a/src/main/java/org/tron/walletcli/cli/ledger/LedgerSigner.java b/java/src/main/java/org/tron/walletcli/cli/ledger/LedgerSigner.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/ledger/LedgerSigner.java rename to java/src/main/java/org/tron/walletcli/cli/ledger/LedgerSigner.java diff --git a/src/main/java/org/tron/walletcli/cli/ledger/NonInteractiveLedgerSigner.java b/java/src/main/java/org/tron/walletcli/cli/ledger/NonInteractiveLedgerSigner.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/ledger/NonInteractiveLedgerSigner.java rename to java/src/main/java/org/tron/walletcli/cli/ledger/NonInteractiveLedgerSigner.java diff --git a/src/main/java/org/tron/walletcli/cli/ledger/ProductionLedgerPorts.java b/java/src/main/java/org/tron/walletcli/cli/ledger/ProductionLedgerPorts.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/ledger/ProductionLedgerPorts.java rename to java/src/main/java/org/tron/walletcli/cli/ledger/ProductionLedgerPorts.java diff --git a/src/main/java/org/tron/walletcli/cli/ledger/SystemOutSuppressor.java b/java/src/main/java/org/tron/walletcli/cli/ledger/SystemOutSuppressor.java similarity index 100% rename from src/main/java/org/tron/walletcli/cli/ledger/SystemOutSuppressor.java rename to java/src/main/java/org/tron/walletcli/cli/ledger/SystemOutSuppressor.java diff --git a/src/main/java/org/tron/walletserver/ApiClient.java b/java/src/main/java/org/tron/walletserver/ApiClient.java similarity index 100% rename from src/main/java/org/tron/walletserver/ApiClient.java rename to java/src/main/java/org/tron/walletserver/ApiClient.java diff --git a/src/main/java/org/tron/walletserver/WalletApi.java b/java/src/main/java/org/tron/walletserver/WalletApi.java similarity index 100% rename from src/main/java/org/tron/walletserver/WalletApi.java rename to java/src/main/java/org/tron/walletserver/WalletApi.java diff --git a/src/main/protos/.gitignore b/java/src/main/protos/.gitignore similarity index 100% rename from src/main/protos/.gitignore rename to java/src/main/protos/.gitignore diff --git a/src/main/protos/.travis.yml b/java/src/main/protos/.travis.yml similarity index 100% rename from src/main/protos/.travis.yml rename to java/src/main/protos/.travis.yml diff --git a/src/main/protos/Chinese version of TRON Protocol document.md b/java/src/main/protos/Chinese version of TRON Protocol document.md similarity index 100% rename from src/main/protos/Chinese version of TRON Protocol document.md rename to java/src/main/protos/Chinese version of TRON Protocol document.md diff --git a/src/main/protos/English version of TRON Protocol document.md b/java/src/main/protos/English version of TRON Protocol document.md similarity index 100% rename from src/main/protos/English version of TRON Protocol document.md rename to java/src/main/protos/English version of TRON Protocol document.md diff --git a/src/main/protos/LICENSE b/java/src/main/protos/LICENSE similarity index 100% rename from src/main/protos/LICENSE rename to java/src/main/protos/LICENSE diff --git a/src/main/protos/README.md b/java/src/main/protos/README.md similarity index 100% rename from src/main/protos/README.md rename to java/src/main/protos/README.md diff --git a/src/main/protos/api/api.proto b/java/src/main/protos/api/api.proto similarity index 100% rename from src/main/protos/api/api.proto rename to java/src/main/protos/api/api.proto diff --git a/src/main/protos/api/zksnark.proto b/java/src/main/protos/api/zksnark.proto similarity index 100% rename from src/main/protos/api/zksnark.proto rename to java/src/main/protos/api/zksnark.proto diff --git a/src/main/protos/core/Discover.proto b/java/src/main/protos/core/Discover.proto similarity index 100% rename from src/main/protos/core/Discover.proto rename to java/src/main/protos/core/Discover.proto diff --git a/src/main/protos/core/Tron.proto b/java/src/main/protos/core/Tron.proto similarity index 100% rename from src/main/protos/core/Tron.proto rename to java/src/main/protos/core/Tron.proto diff --git a/src/main/protos/core/TronInventoryItems.proto b/java/src/main/protos/core/TronInventoryItems.proto similarity index 100% rename from src/main/protos/core/TronInventoryItems.proto rename to java/src/main/protos/core/TronInventoryItems.proto diff --git a/src/main/protos/core/contract/account_contract.proto b/java/src/main/protos/core/contract/account_contract.proto similarity index 100% rename from src/main/protos/core/contract/account_contract.proto rename to java/src/main/protos/core/contract/account_contract.proto diff --git a/src/main/protos/core/contract/asset_issue_contract.proto b/java/src/main/protos/core/contract/asset_issue_contract.proto similarity index 100% rename from src/main/protos/core/contract/asset_issue_contract.proto rename to java/src/main/protos/core/contract/asset_issue_contract.proto diff --git a/src/main/protos/core/contract/balance_contract.proto b/java/src/main/protos/core/contract/balance_contract.proto similarity index 100% rename from src/main/protos/core/contract/balance_contract.proto rename to java/src/main/protos/core/contract/balance_contract.proto diff --git a/src/main/protos/core/contract/common.proto b/java/src/main/protos/core/contract/common.proto similarity index 100% rename from src/main/protos/core/contract/common.proto rename to java/src/main/protos/core/contract/common.proto diff --git a/src/main/protos/core/contract/exchange_contract.proto b/java/src/main/protos/core/contract/exchange_contract.proto similarity index 100% rename from src/main/protos/core/contract/exchange_contract.proto rename to java/src/main/protos/core/contract/exchange_contract.proto diff --git a/src/main/protos/core/contract/market_contract.proto b/java/src/main/protos/core/contract/market_contract.proto similarity index 100% rename from src/main/protos/core/contract/market_contract.proto rename to java/src/main/protos/core/contract/market_contract.proto diff --git a/src/main/protos/core/contract/proposal_contract.proto b/java/src/main/protos/core/contract/proposal_contract.proto similarity index 100% rename from src/main/protos/core/contract/proposal_contract.proto rename to java/src/main/protos/core/contract/proposal_contract.proto diff --git a/src/main/protos/core/contract/shield_contract.proto b/java/src/main/protos/core/contract/shield_contract.proto similarity index 100% rename from src/main/protos/core/contract/shield_contract.proto rename to java/src/main/protos/core/contract/shield_contract.proto diff --git a/src/main/protos/core/contract/smart_contract.proto b/java/src/main/protos/core/contract/smart_contract.proto similarity index 100% rename from src/main/protos/core/contract/smart_contract.proto rename to java/src/main/protos/core/contract/smart_contract.proto diff --git a/src/main/protos/core/contract/storage_contract.proto b/java/src/main/protos/core/contract/storage_contract.proto similarity index 100% rename from src/main/protos/core/contract/storage_contract.proto rename to java/src/main/protos/core/contract/storage_contract.proto diff --git a/src/main/protos/core/contract/vote_asset_contract.proto b/java/src/main/protos/core/contract/vote_asset_contract.proto similarity index 100% rename from src/main/protos/core/contract/vote_asset_contract.proto rename to java/src/main/protos/core/contract/vote_asset_contract.proto diff --git a/src/main/protos/core/contract/witness_contract.proto b/java/src/main/protos/core/contract/witness_contract.proto similarity index 100% rename from src/main/protos/core/contract/witness_contract.proto rename to java/src/main/protos/core/contract/witness_contract.proto diff --git a/src/main/protos/core/tron/account.proto b/java/src/main/protos/core/tron/account.proto similarity index 100% rename from src/main/protos/core/tron/account.proto rename to java/src/main/protos/core/tron/account.proto diff --git a/src/main/protos/core/tron/block.proto b/java/src/main/protos/core/tron/block.proto similarity index 100% rename from src/main/protos/core/tron/block.proto rename to java/src/main/protos/core/tron/block.proto diff --git a/src/main/protos/core/tron/delegated_resource.proto b/java/src/main/protos/core/tron/delegated_resource.proto similarity index 100% rename from src/main/protos/core/tron/delegated_resource.proto rename to java/src/main/protos/core/tron/delegated_resource.proto diff --git a/src/main/protos/core/tron/p2p.proto b/java/src/main/protos/core/tron/p2p.proto similarity index 100% rename from src/main/protos/core/tron/p2p.proto rename to java/src/main/protos/core/tron/p2p.proto diff --git a/src/main/protos/core/tron/proposal.proto b/java/src/main/protos/core/tron/proposal.proto similarity index 100% rename from src/main/protos/core/tron/proposal.proto rename to java/src/main/protos/core/tron/proposal.proto diff --git a/src/main/protos/core/tron/transaction.proto b/java/src/main/protos/core/tron/transaction.proto similarity index 100% rename from src/main/protos/core/tron/transaction.proto rename to java/src/main/protos/core/tron/transaction.proto diff --git a/src/main/protos/core/tron/vote.proto b/java/src/main/protos/core/tron/vote.proto similarity index 100% rename from src/main/protos/core/tron/vote.proto rename to java/src/main/protos/core/tron/vote.proto diff --git a/src/main/protos/core/tron/witness.proto b/java/src/main/protos/core/tron/witness.proto similarity index 100% rename from src/main/protos/core/tron/witness.proto rename to java/src/main/protos/core/tron/witness.proto diff --git a/src/main/protos/install-googleapis.sh b/java/src/main/protos/install-googleapis.sh similarity index 100% rename from src/main/protos/install-googleapis.sh rename to java/src/main/protos/install-googleapis.sh diff --git a/src/main/protos/install-protobuf.sh b/java/src/main/protos/install-protobuf.sh similarity index 100% rename from src/main/protos/install-protobuf.sh rename to java/src/main/protos/install-protobuf.sh diff --git a/src/main/resources/aliases/main.json b/java/src/main/resources/aliases/main.json similarity index 100% rename from src/main/resources/aliases/main.json rename to java/src/main/resources/aliases/main.json diff --git a/src/main/resources/aliases/nile.json b/java/src/main/resources/aliases/nile.json similarity index 100% rename from src/main/resources/aliases/nile.json rename to java/src/main/resources/aliases/nile.json diff --git a/src/main/resources/aliases/shasta.json b/java/src/main/resources/aliases/shasta.json similarity index 100% rename from src/main/resources/aliases/shasta.json rename to java/src/main/resources/aliases/shasta.json diff --git a/src/main/resources/banner.txt b/java/src/main/resources/banner.txt similarity index 100% rename from src/main/resources/banner.txt rename to java/src/main/resources/banner.txt diff --git a/src/main/resources/commands.txt b/java/src/main/resources/commands.txt similarity index 100% rename from src/main/resources/commands.txt rename to java/src/main/resources/commands.txt diff --git a/src/main/resources/config.conf b/java/src/main/resources/config.conf similarity index 100% rename from src/main/resources/config.conf rename to java/src/main/resources/config.conf diff --git a/src/main/resources/help_summary.txt b/java/src/main/resources/help_summary.txt similarity index 100% rename from src/main/resources/help_summary.txt rename to java/src/main/resources/help_summary.txt diff --git a/src/main/resources/logback.xml b/java/src/main/resources/logback.xml similarity index 100% rename from src/main/resources/logback.xml rename to java/src/main/resources/logback.xml diff --git a/src/test/java/org/tron/common/utils/FormatMessageStringTest.java b/java/src/test/java/org/tron/common/utils/FormatMessageStringTest.java similarity index 100% rename from src/test/java/org/tron/common/utils/FormatMessageStringTest.java rename to java/src/test/java/org/tron/common/utils/FormatMessageStringTest.java diff --git a/src/test/java/org/tron/common/utils/JsonFormatUtilTest.java b/java/src/test/java/org/tron/common/utils/JsonFormatUtilTest.java similarity index 100% rename from src/test/java/org/tron/common/utils/JsonFormatUtilTest.java rename to java/src/test/java/org/tron/common/utils/JsonFormatUtilTest.java diff --git a/src/test/java/org/tron/common/utils/TransactionUtilsTest.java b/java/src/test/java/org/tron/common/utils/TransactionUtilsTest.java similarity index 100% rename from src/test/java/org/tron/common/utils/TransactionUtilsTest.java rename to java/src/test/java/org/tron/common/utils/TransactionUtilsTest.java diff --git a/src/test/java/org/tron/common/utils/UtilsPasswordTest.java b/java/src/test/java/org/tron/common/utils/UtilsPasswordTest.java similarity index 100% rename from src/test/java/org/tron/common/utils/UtilsPasswordTest.java rename to java/src/test/java/org/tron/common/utils/UtilsPasswordTest.java diff --git a/src/test/java/org/tron/core/manager/UpdateAccountPermissionInteractiveTest.java b/java/src/test/java/org/tron/core/manager/UpdateAccountPermissionInteractiveTest.java similarity index 100% rename from src/test/java/org/tron/core/manager/UpdateAccountPermissionInteractiveTest.java rename to java/src/test/java/org/tron/core/manager/UpdateAccountPermissionInteractiveTest.java diff --git a/src/test/java/org/tron/keystore/ClearWalletUtilsTest.java b/java/src/test/java/org/tron/keystore/ClearWalletUtilsTest.java similarity index 100% rename from src/test/java/org/tron/keystore/ClearWalletUtilsTest.java rename to java/src/test/java/org/tron/keystore/ClearWalletUtilsTest.java diff --git a/src/test/java/org/tron/keystore/StringUtilsTest.java b/java/src/test/java/org/tron/keystore/StringUtilsTest.java similarity index 100% rename from src/test/java/org/tron/keystore/StringUtilsTest.java rename to java/src/test/java/org/tron/keystore/StringUtilsTest.java diff --git a/src/test/java/org/tron/qa/QARunner.java b/java/src/test/java/org/tron/qa/QARunner.java similarity index 100% rename from src/test/java/org/tron/qa/QARunner.java rename to java/src/test/java/org/tron/qa/QARunner.java diff --git a/src/test/java/org/tron/qa/QASecretImporter.java b/java/src/test/java/org/tron/qa/QASecretImporter.java similarity index 100% rename from src/test/java/org/tron/qa/QASecretImporter.java rename to java/src/test/java/org/tron/qa/QASecretImporter.java diff --git a/src/test/java/org/tron/walletcli/ClientMainTest.java b/java/src/test/java/org/tron/walletcli/ClientMainTest.java similarity index 100% rename from src/test/java/org/tron/walletcli/ClientMainTest.java rename to java/src/test/java/org/tron/walletcli/ClientMainTest.java diff --git a/src/test/java/org/tron/walletcli/CryptoVectorTest.java b/java/src/test/java/org/tron/walletcli/CryptoVectorTest.java similarity index 100% rename from src/test/java/org/tron/walletcli/CryptoVectorTest.java rename to java/src/test/java/org/tron/walletcli/CryptoVectorTest.java diff --git a/src/test/java/org/tron/walletcli/WalletApiWrapperTest.java b/java/src/test/java/org/tron/walletcli/WalletApiWrapperTest.java similarity index 100% rename from src/test/java/org/tron/walletcli/WalletApiWrapperTest.java rename to java/src/test/java/org/tron/walletcli/WalletApiWrapperTest.java diff --git a/src/test/java/org/tron/walletcli/cli/ActiveWalletConfigTest.java b/java/src/test/java/org/tron/walletcli/cli/ActiveWalletConfigTest.java similarity index 100% rename from src/test/java/org/tron/walletcli/cli/ActiveWalletConfigTest.java rename to java/src/test/java/org/tron/walletcli/cli/ActiveWalletConfigTest.java diff --git a/src/test/java/org/tron/walletcli/cli/CommandDefinitionTest.java b/java/src/test/java/org/tron/walletcli/cli/CommandDefinitionTest.java similarity index 100% rename from src/test/java/org/tron/walletcli/cli/CommandDefinitionTest.java rename to java/src/test/java/org/tron/walletcli/cli/CommandDefinitionTest.java diff --git a/src/test/java/org/tron/walletcli/cli/GlobalOptionsTest.java b/java/src/test/java/org/tron/walletcli/cli/GlobalOptionsTest.java similarity index 100% rename from src/test/java/org/tron/walletcli/cli/GlobalOptionsTest.java rename to java/src/test/java/org/tron/walletcli/cli/GlobalOptionsTest.java diff --git a/src/test/java/org/tron/walletcli/cli/OutputFormatterResolvedTest.java b/java/src/test/java/org/tron/walletcli/cli/OutputFormatterResolvedTest.java similarity index 100% rename from src/test/java/org/tron/walletcli/cli/OutputFormatterResolvedTest.java rename to java/src/test/java/org/tron/walletcli/cli/OutputFormatterResolvedTest.java diff --git a/src/test/java/org/tron/walletcli/cli/OutputFormatterTest.java b/java/src/test/java/org/tron/walletcli/cli/OutputFormatterTest.java similarity index 100% rename from src/test/java/org/tron/walletcli/cli/OutputFormatterTest.java rename to java/src/test/java/org/tron/walletcli/cli/OutputFormatterTest.java diff --git a/src/test/java/org/tron/walletcli/cli/ParsedOptionsAliasTest.java b/java/src/test/java/org/tron/walletcli/cli/ParsedOptionsAliasTest.java similarity index 100% rename from src/test/java/org/tron/walletcli/cli/ParsedOptionsAliasTest.java rename to java/src/test/java/org/tron/walletcli/cli/ParsedOptionsAliasTest.java diff --git a/src/test/java/org/tron/walletcli/cli/StandardCliRunnerTest.java b/java/src/test/java/org/tron/walletcli/cli/StandardCliRunnerTest.java similarity index 100% rename from src/test/java/org/tron/walletcli/cli/StandardCliRunnerTest.java rename to java/src/test/java/org/tron/walletcli/cli/StandardCliRunnerTest.java diff --git a/src/test/java/org/tron/walletcli/cli/StdinPasswordReaderTest.java b/java/src/test/java/org/tron/walletcli/cli/StdinPasswordReaderTest.java similarity index 100% rename from src/test/java/org/tron/walletcli/cli/StdinPasswordReaderTest.java rename to java/src/test/java/org/tron/walletcli/cli/StdinPasswordReaderTest.java diff --git a/src/test/java/org/tron/walletcli/cli/aliases/AliasEntryTest.java b/java/src/test/java/org/tron/walletcli/cli/aliases/AliasEntryTest.java similarity index 100% rename from src/test/java/org/tron/walletcli/cli/aliases/AliasEntryTest.java rename to java/src/test/java/org/tron/walletcli/cli/aliases/AliasEntryTest.java diff --git a/src/test/java/org/tron/walletcli/cli/aliases/AliasResolverTest.java b/java/src/test/java/org/tron/walletcli/cli/aliases/AliasResolverTest.java similarity index 100% rename from src/test/java/org/tron/walletcli/cli/aliases/AliasResolverTest.java rename to java/src/test/java/org/tron/walletcli/cli/aliases/AliasResolverTest.java diff --git a/src/test/java/org/tron/walletcli/cli/aliases/AliasStoreLoaderTest.java b/java/src/test/java/org/tron/walletcli/cli/aliases/AliasStoreLoaderTest.java similarity index 100% rename from src/test/java/org/tron/walletcli/cli/aliases/AliasStoreLoaderTest.java rename to java/src/test/java/org/tron/walletcli/cli/aliases/AliasStoreLoaderTest.java diff --git a/src/test/java/org/tron/walletcli/cli/aliases/AliasStoreTest.java b/java/src/test/java/org/tron/walletcli/cli/aliases/AliasStoreTest.java similarity index 100% rename from src/test/java/org/tron/walletcli/cli/aliases/AliasStoreTest.java rename to java/src/test/java/org/tron/walletcli/cli/aliases/AliasStoreTest.java diff --git a/src/test/java/org/tron/walletcli/cli/aliases/AliasValidationTest.java b/java/src/test/java/org/tron/walletcli/cli/aliases/AliasValidationTest.java similarity index 100% rename from src/test/java/org/tron/walletcli/cli/aliases/AliasValidationTest.java rename to java/src/test/java/org/tron/walletcli/cli/aliases/AliasValidationTest.java diff --git a/src/test/java/org/tron/walletcli/cli/commands/StakingResourceGuardTest.java b/java/src/test/java/org/tron/walletcli/cli/commands/StakingResourceGuardTest.java similarity index 100% rename from src/test/java/org/tron/walletcli/cli/commands/StakingResourceGuardTest.java rename to java/src/test/java/org/tron/walletcli/cli/commands/StakingResourceGuardTest.java diff --git a/src/test/java/org/tron/walletcli/cli/commands/StandardCliCommandRoutingTest.java b/java/src/test/java/org/tron/walletcli/cli/commands/StandardCliCommandRoutingTest.java similarity index 100% rename from src/test/java/org/tron/walletcli/cli/commands/StandardCliCommandRoutingTest.java rename to java/src/test/java/org/tron/walletcli/cli/commands/StandardCliCommandRoutingTest.java diff --git a/src/test/java/org/tron/walletcli/cli/commands/TransactionCommandsTest.java b/java/src/test/java/org/tron/walletcli/cli/commands/TransactionCommandsTest.java similarity index 100% rename from src/test/java/org/tron/walletcli/cli/commands/TransactionCommandsTest.java rename to java/src/test/java/org/tron/walletcli/cli/commands/TransactionCommandsTest.java diff --git a/src/test/java/org/tron/walletcli/cli/ledger/LedgerSignOutcomeTest.java b/java/src/test/java/org/tron/walletcli/cli/ledger/LedgerSignOutcomeTest.java similarity index 100% rename from src/test/java/org/tron/walletcli/cli/ledger/LedgerSignOutcomeTest.java rename to java/src/test/java/org/tron/walletcli/cli/ledger/LedgerSignOutcomeTest.java diff --git a/src/test/java/org/tron/walletcli/cli/ledger/NonInteractiveLedgerSignerTest.java b/java/src/test/java/org/tron/walletcli/cli/ledger/NonInteractiveLedgerSignerTest.java similarity index 100% rename from src/test/java/org/tron/walletcli/cli/ledger/NonInteractiveLedgerSignerTest.java rename to java/src/test/java/org/tron/walletcli/cli/ledger/NonInteractiveLedgerSignerTest.java diff --git a/src/test/java/org/tron/walletcli/cli/ledger/SystemOutSuppressorTest.java b/java/src/test/java/org/tron/walletcli/cli/ledger/SystemOutSuppressorTest.java similarity index 100% rename from src/test/java/org/tron/walletcli/cli/ledger/SystemOutSuppressorTest.java rename to java/src/test/java/org/tron/walletcli/cli/ledger/SystemOutSuppressorTest.java diff --git a/src/test/java/org/tron/walletserver/WalletApiTest.java b/java/src/test/java/org/tron/walletserver/WalletApiTest.java similarity index 100% rename from src/test/java/org/tron/walletserver/WalletApiTest.java rename to java/src/test/java/org/tron/walletserver/WalletApiTest.java diff --git a/ts/README.md b/ts/README.md index f32a56c5..13c8a69a 100644 --- a/ts/README.md +++ b/ts/README.md @@ -1,359 +1,160 @@ -# wallet-cli +# wallet-cli — TypeScript implementation -An agent-first TypeScript CLI wallet for TRON, with deterministic commands, structured JSON, discoverable schemas, and secure secret input. Privacy-sensitive operations such as import, backup, and delete retain guided, human-friendly interactions. +The agent-first implementation of wallet-cli, built for automation: every command has a stable JSON envelope, deterministic exit codes, and discoverable schemas; interactive prompts are kept only for secret input (import / backup / delete). For what wallet-cli is and how the two implementations compare, see the [repository overview](../README.md); for the original, see the [Java implementation](../java/README.md). -> Currently supports TRON mainnet, Nile, and Shasta. EVM chains are not yet supported by this version. +## Key features -## Contents +- **Agent-first** — stable JSON output, deterministic exit codes, and discoverable schemas, built for scripts, CI, and AI agents (details in [The contract, in one paragraph](#the-contract-in-one-paragraph)). +- **Encrypted local storage** — software keystores are encrypted on disk; secrets are never passed via argv or environment variables. +- **Software and Ledger signing** — sign in software, or on a Ledger device (the private key never leaves the device). +- **Covers the main TRON capabilities** — HD wallets, TRX and TRC20/TRC10 transfers, staking / resource delegation, voting / rewards, smart-contract calls and deployment, message signing, and on-chain queries. -- [Features](#features) -- [Quick Start](#quick-start) -- [Common Tasks](#common-tasks) -- [Automation and Agent Integration](#automation-and-agent-integration) -- [Security](#security) -- [Development](#development) +## Supported chains -## Features +Three TRON networks are supported today. Networks are identified by a canonical `family:chain` id (all `tron` today): -| Category | Capabilities | -| --- | --- | -| Wallets | Create BIP39 HD wallets, import mnemonics or private keys, derive accounts, rename, back up, and delete | -| External accounts | Watch-only addresses, Ledger TRON App, and on-device signing | -| Accounts | TRX balance, raw account data, transaction history, token portfolio, and best-effort USD valuation | -| Tokens | TRC10 and TRC20 metadata and balances, plus a custom token address book | -| Transactions | TRX, TRC10, and TRC20 transfers; dry-run; sign-only; broadcast; status and receipt queries | -| Contracts | Constant calls, state-changing calls, contract metadata, and deployment | -| Stake 2.0 | Stake, unstake, delegate and reclaim resources, cancel pending unstakes, and withdraw expired unstakes | -| Signing | TIP-191/V2 message signing | -| Automation | Stable JSON envelopes, deterministic exit codes, and a complete command JSON Schema | +| 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 | -## Quick Start +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). -### 1. Install +## Install -Node.js 20 or later is required. +**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). ```bash npm install -g @tron-walletcli/wallet-cli ``` -Verify the installation: +Note the scope: the package is `@tron-walletcli/wallet-cli`, not the bare `wallet-cli` name (which is an unrelated third-party package). -```bash -wallet-cli --version -wallet-cli --help -``` - -### 2. Create your first wallet - -```bash -wallet-cli create --label main -``` - -The CLI prompts you to set a master password. It encrypts your local keys and cannot be recovered by this tool if lost. - -Inspect your wallets and make `main` the active account: - -```bash -wallet-cli list -wallet-cli use main -wallet-cli current -``` - -### 3. Start on testnet - -For your first transaction, set Nile as the default network: - -```bash -wallet-cli config defaultNetwork tron:nile -wallet-cli account balance -``` - -You can also select a network for one command without changing the default: - -```bash -wallet-cli account balance --network tron:nile -``` - -### 4. Dry-run before sending - -Build and estimate a transaction without signing or broadcasting it: - -```bash -wallet-cli tx send \ - --network tron:nile \ - --to T... \ - --amount 1 \ - --dry-run -``` - -After checking the recipient, amount, and estimated cost, send it: - -```bash -wallet-cli tx send \ - --network tron:nile \ - --to T... \ - --amount 1 \ - --wait -``` - -The CLI prompts for the master password when a signature is required. Without `--wait`, it returns the txid immediately after a successful broadcast. With `--wait`, it polls until the transaction is confirmed, fails, or reaches the wait timeout. - -## Common Tasks - -### Import an existing wallet - -In an interactive terminal, mnemonic and private-key prompts hide their input: - -```bash -wallet-cli import mnemonic --label imported -wallet-cli import private-key --label hot -``` - -Register an address that can be monitored but cannot sign: - -```bash -wallet-cli import watch --address T... --label treasury -``` - -Derive the next account from an HD wallet. Find its seed ID with `wallet-cli list`: +Verify: ```bash -wallet-cli derive --seed-id wlt_ab12cd34 --label operations -``` - -### Use a Ledger device - -Connect and unlock the Ledger, open the TRON App, and register its first account: - -```bash -wallet-cli import ledger --app tron --index 0 --label cold -wallet-cli use cold -wallet-cli account balance -``` - -Ledger private keys are never written locally. Signing requires confirmation on the device. You can also provide a derivation path with `--path`, or locate an account with `--address` and `--scan-limit`. - -### Query accounts and assets - -```bash -wallet-cli account balance -wallet-cli account portfolio -wallet-cli account history --limit 10 -wallet-cli account info --output json -``` - -Wallet-bound commands use the active account by default. Override it with a label, account ID, or address: - -```bash -wallet-cli account balance --account treasury -``` - -### Work with TRC10 and TRC20 tokens - -The mainnet address book includes USDT and USDC. Add a custom TRC20 contract to use its symbol in later commands: - -```bash -wallet-cli token add --contract TR7... -wallet-cli token list -wallet-cli token balance --contract TR7... -wallet-cli tx send --to T... --token USDT --amount 5 --dry-run -``` - -You can also use `--contract` directly. Use `--asset-id` for TRC10 tokens: - -```bash -wallet-cli tx send --to T... --contract TR7... --amount 5 -wallet-cli tx send --to T... --asset-id 1002000 --raw-amount 1000000 -``` - -### Inspect transactions and sign offline - -```bash -wallet-cli tx status --txid -wallet-cli tx info --txid --output json -``` - -Commands that change chain state support three execution modes: - -- Default: build, sign, and broadcast. -- `--dry-run`: build and estimate without signing or broadcasting. -- `--sign-only`: sign and output the transaction without broadcasting. Submit it later with `tx broadcast --tx-stdin`. - -Use command help for the complete set of options: - -```bash -wallet-cli tx send --help -wallet-cli tx broadcast --help -``` - -### Interact with smart contracts - -Inspect a contract and make a read-only call: - -```bash -wallet-cli contract info --contract T... -wallet-cli contract call \ - --contract T... \ - --method 'balanceOf(address)' \ - --params '[{"type":"address","value":"T..."}]' -``` - -Dry-run a state-changing call before submitting it: - -```bash -wallet-cli contract send \ - --contract T... \ - --method 'transfer(address,uint256)' \ - --params '[{"type":"address","value":"T..."},{"type":"uint256","value":"1000000"}]' \ - --dry-run +wallet-cli --version ``` -Deploy a contract: - -```bash -wallet-cli contract deploy \ - --abi '[...]' \ - --bytecode 60... \ - --fee-limit 1000000000 \ - --params '[100,"T..."]' \ - --dry-run +```console + # shows the installed version ``` -### Use Stake 2.0 +Upgrade with `npm update -g @tron-walletcli/wallet-cli`; uninstall with `npm uninstall -g @tron-walletcli/wallet-cli`. -Stake amounts are specified in SUN (1 TRX = 1,000,000 SUN): +**From source** (contributors, or to run unreleased changes) — additionally requires Git: ```bash -wallet-cli stake freeze --amount-sun 1000000 --resource energy --dry-run -wallet-cli stake delegate --amount-sun 1000000 --receiver T... --resource energy --dry-run -wallet-cli stake undelegate --amount-sun 1000000 --receiver T... --resource energy --dry-run -wallet-cli stake unfreeze --amount-sun 1000000 --resource energy --dry-run -wallet-cli stake withdraw --dry-run +git clone https://github.com/tronprotocol/wallet-cli.git +cd wallet-cli/ts +npm ci && npm run build +npm link # puts `wallet-cli` on your PATH (or run: node dist/index.js) ``` -### Sign a message +**Create your first wallet.** `create` prompts for a master password, then shows the new account: ```bash -wallet-cli message sign --message 'hello' -``` - -## Automation and Agent Integration - -### JSON output - -```bash -wallet-cli account balance --output json -wallet-cli tx info --txid --output json +wallet-cli create --label main ``` -JSON mode uses the `wallet-cli.result.v1` envelope and writes exactly one terminal frame to stdout. Exit codes are deterministic: - -| Exit code | Meaning | -| --- | --- | -| `0` | Success | -| `1` | Execution, authentication, device, or chain error | -| `2` | Invalid command usage or arguments | - -### Discover commands - -Agents do not need to parse human-readable help. Retrieve every command, input schema, example, and prerequisite in one call: - -```bash -wallet-cli --json-schema +```console +✅ Created wallet "main" + Account ID wlt_2dbv24de.0 + TRON address TTVdGTBXY5mmY3nJFGUp7Vo898kUJ6gtFQ + Active yes ``` -Retrieve the input schema for one command: - ```bash -wallet-cli tx send --json-schema +wallet-cli list ``` -### Provide secrets safely - -Use stdin flags in non-interactive environments. Do not put passwords, mnemonics, or private keys directly in argv or exported environment variables: - -```bash -printf '%s\n' "$WALLET_PASSWORD" | wallet-cli message sign --message 'hello' --password-stdin --output json -printf '%s\n' "$MNEMONIC" | wallet-cli import mnemonic --label main --mnemonic-stdin -printf '%s\n' "$PRIVATE_KEY" | wallet-cli import private-key --label hot --private-key-stdin +```console +HD wlt_2dbv24de +└─ [0] main TTVdGTBXY5mmY3nJFGUp7Vo898kUJ6gtFQ (active) ``` -These examples assume the shell variables are populated securely and are not exported. Only one `*-stdin` flag may consume stdin in each invocation. Use an interactive terminal when one operation requires two secrets. - -### Source secrets from a password manager - -Because secrets are read from stdin, you can pipe them straight from a password manager. The secret is never written to argv, an environment variable, a temp file, or shell history — the manager keeps it encrypted at rest, and the CLI consumes it once and discards it. This pairs well with the no-`MASTER_PASSWORD`-env design: the password manager is where the secret lives, the pipe is how it travels. - -**1Password (`op read`):** +Next: fund it on a testnet, check the balance, and send TRX → [Getting started](docs/guide/getting-started.md). -```bash -# 1. Store the master password once (op stores it encrypted). -op item create --category=password --title='wallet-cli master' password='' +## Start here -# 2. Use it via pipe — nothing sensitive touches argv or history. -op read 'op://Private/wallet-cli master/password' | \ - wallet-cli create --label main --password-stdin -``` +- 🚀 **First time?** → [Getting started: create a wallet and send your first transaction](docs/guide/getting-started.md) +- 📖 **Looking up a command?** → [Command index](#commands) below, or `wallet-cli --help` +- 🤖 **Calling from a script, CI, or an AI agent?** → [Machine interface: JSON envelope, exit codes, script safety](docs/machine-interface.md) · [Agent skill](skills/wallet-cli/SKILL.md) +- 🔐 **Using a Ledger hardware wallet?** → [Ledger guide](docs/guide/ledger.md) +- 🧭 **Something failed?** → [Troubleshooting](docs/troubleshooting.md) -**macOS Keychain (`security`):** +## The contract, in one paragraph -```bash -# 1. Store the master password once (omit the value after -w to be prompted, so it stays out of history). -security add-generic-password -s wallet-cli-master -a "$USER" -w +Every command supports `-o json` and then prints **exactly one** terminal JSON frame on stdout, schema [`wallet-cli.result.v1`](docs/machine-interface.md#the-result-envelope). Exit codes are fixed: `0` success, `1` execution failure, `2` usage error. Secrets (passwords, mnemonics, private keys) are never accepted via argv or environment variables — only via stdin flags or interactive TTY prompts; mnemonic/private-key import and `change-password` are interactive-only (no stdin path at all). Details: [machine-interface.md](docs/machine-interface.md). -# 2. Use it via pipe. -security find-generic-password -s wallet-cli-master -w | \ - wallet-cli create --label main --password-stdin -``` +## Commands -Only one `*-stdin` flag may consume stdin per invocation, so commands that need two secrets at once (for example `import mnemonic`, which needs both a mnemonic and a password) can pipe one secret and must supply the other interactively. +Every command — including every subcommand — has a reference page; run `wallet-cli --help` for the built-in equivalent. -Use `WALLET_CLI_HOME` to isolate test or automation data. The default data directory is `~/.wallet-cli`: +### Wallets and accounts -```bash -WALLET_CLI_HOME=/tmp/wallet-cli-demo wallet-cli list --output json -``` +| Command | Description | +|---|---| +| [`create`](docs/commands/create.md) | Create a new HD wallet (BIP39 seed) | +| [`import mnemonic`](docs/commands/import/mnemonic.md) | Import a BIP39 mnemonic phrase (interactive-only) | +| [`import private-key`](docs/commands/import/private-key.md) | Import a raw private key (interactive-only) | +| [`import ledger`](docs/commands/import/ledger.md) | Register a Ledger account (watch-only; signs on device) | +| [`import watch`](docs/commands/import/watch.md) | Register a watch-only address (no secret) | +| [`list`](docs/commands/list.md) | List wallets / accounts | +| [`use`](docs/commands/use.md) / [`current`](docs/commands/current.md) | Set / show the active account | +| [`derive`](docs/commands/derive.md) | Derive the next HD account from a seed wallet | +| [`rename`](docs/commands/rename.md) / [`backup`](docs/commands/backup.md) / [`delete`](docs/commands/delete.md) | Manage accounts (backup writes secret + metadata, mode 0600) | +| [`change-password`](docs/commands/change-password.md) | Change the master password (re-encrypt all software keystores) | -## Security +### Transactions -- Mnemonics and private keys are encrypted locally using scrypt, AES-128-CTR, and a Keccak MAC. -- The keystore uses one master password. Secrets are not accepted through argv or CLI-specific environment variables. -- Configuration, keystore, and backup data are written with restricted permissions. `backup` creates `0600` files and never overwrites an existing file. -- Ledger accounts store only the address and derivation path locally; signing remains on the hardware device. -- Watch-only accounts can query data but cannot sign. -- Test on Nile and use `--dry-run` before sending production transactions. Backup files contain secret material capable of restoring an account and must be protected like private keys. +| Command | Description | +|---|---| +| [`tx send`](docs/commands/tx/send.md) | Send native TRX or TRC20/TRC10 tokens | +| [`tx broadcast`](docs/commands/tx/broadcast.md) | Broadcast a presigned transaction | +| [`tx status`](docs/commands/tx/status.md) | Show confirmation status (confirmed / failed / pending / not_found) | +| [`tx info`](docs/commands/tx/info.md) | Show full transaction detail + receipt | -Back up an account: +### On-chain queries -```bash -wallet-cli backup main --out ~/main-backup.json -``` +| Command | Description | +|---|---| +| [`account balance`](docs/commands/account/balance.md) | Show the native TRX balance | +| [`account info`](docs/commands/account/info.md) | Show raw account data incl. resources | +| [`account history`](docs/commands/account/history.md) | Show transaction history (requires TronGrid) | +| [`account portfolio`](docs/commands/account/portfolio.md) | Native + token balances with best-effort USD value | +| [`block`](docs/commands/block.md) | Get a block (latest if omitted) | +| [`chain params`](docs/commands/chain/params.md) | On-chain governance parameters | +| [`chain prices`](docs/commands/chain/prices.md) | Energy/bandwidth unit price and memo fee | +| [`chain node`](docs/commands/chain/node.md) | Connected node status (version / sync / peers) | -## Configuration and Command Reference +### Tokens, contracts, staking, signing -```bash -wallet-cli config -wallet-cli networks -wallet-cli COMMAND --help -``` +| Command | Description | +|---|---| +| [`token`](docs/commands/token/index.md) | Manage the token address book and query tokens ([balance](docs/commands/token/balance.md) · [info](docs/commands/token/info.md) · [add](docs/commands/token/add.md) · [list](docs/commands/token/list.md) · [remove](docs/commands/token/remove.md)) | +| [`contract`](docs/commands/contract/index.md) | Call, send, deploy, and inspect smart contracts ([call](docs/commands/contract/call.md) · [send](docs/commands/contract/send.md) · [deploy](docs/commands/contract/deploy.md) · [info](docs/commands/contract/info.md)) | +| [`stake`](docs/commands/stake/index.md) | Stake / delegate resources & query state ([freeze](docs/commands/stake/freeze.md) · [unfreeze](docs/commands/stake/unfreeze.md) · [withdraw](docs/commands/stake/withdraw.md) · [cancel-unfreeze](docs/commands/stake/cancel-unfreeze.md) · [delegate](docs/commands/stake/delegate.md) · [undelegate](docs/commands/stake/undelegate.md) · [info](docs/commands/stake/info.md) · [delegated](docs/commands/stake/delegated.md)) | +| [`vote`](docs/commands/vote/index.md) | Vote for super representatives ([cast](docs/commands/vote/cast.md) · [list](docs/commands/vote/list.md) · [status](docs/commands/vote/status.md)) | +| [`reward`](docs/commands/reward/index.md) | Query / withdraw voting rewards ([balance](docs/commands/reward/balance.md) · [withdraw](docs/commands/reward/withdraw.md)) | +| [`message`](docs/commands/message/index.md) | Sign arbitrary messages ([sign](docs/commands/message/sign.md)) | -Global options include `--network`, `--account`, `--output text|json`, `--timeout`, and `--verbose`. Broadcasting commands also support `--wait` and `--wait-timeout`. +### Local configuration -## Development +| Command | Description | +|---|---| +| [`config`](docs/commands/config.md) | Show / get / set configuration values | +| [`networks`](docs/commands/networks.md) | List known networks (`tron:mainnet`, `tron:nile`, `tron:shasta`) | -```bash -npm ci -npm run typecheck -npm run depcruise -npm test -npm run build -``` +## Documentation map -The Nile live suite uses an isolated `WALLET_CLI_HOME` and does not copy or print private material: - -```bash -npm run test:live:nile -``` +| You want to… | Read | +|---|---| +| Learn by doing | [guide/](docs/guide/index.md) — [getting started](docs/guide/getting-started.md) · [sending tokens](docs/guide/send-tokens.md) · [staking](docs/guide/stake-and-resources.md) · [Ledger](docs/guide/ledger.md) · [scripting](docs/guide/scripting.md) | +| Look up a command | [commands/](docs/commands/index.md) | +| Integrate programmatically | [machine-interface.md](docs/machine-interface.md) | +| Understand TRON mechanics | [concepts/](docs/concepts/index.md) — [networks](docs/concepts/networks.md) · [accounts & HD](docs/concepts/accounts-and-hd.md) · [energy & bandwidth](docs/concepts/energy-bandwidth.md) · [security](docs/concepts/security.md) | +| Fix an error | [troubleshooting.md](docs/troubleshooting.md) | -For the design and CLI contracts, see the [architecture source of truth](./docs/typescript-wallet-cli-architecture-source-of-truth.md) and the [architecture overview](./docs/architecture.md). +> All copy-pasteable examples in this documentation run against the **Nile testnet** (`--network tron:nile`). Mainnet commands move real funds; they appear only as annotated, non-copyable descriptions. diff --git a/ts/docs/architecture.md b/ts/docs/architecture.md deleted file mode 100644 index fe3b8985..00000000 --- a/ts/docs/architecture.md +++ /dev/null @@ -1,230 +0,0 @@ -# wallet-cli architecture — English summary - -This document is a non-normative English overview. The single, authoritative architecture and -behavior contract is -[typescript-wallet-cli-architecture-source-of-truth.zh-TW.md](./typescript-wallet-cli-architecture-source-of-truth.zh-TW.md). - -## 1. Dependency model - -```mermaid -flowchart LR - BOOTSTRAP[bootstrap
process lifecycle + composition root] --> INBOUND[adapters/inbound
CLI] - BOOTSTRAP --> OUTBOUND[adapters/outbound
filesystem / TRON / Ledger / price] - INBOUND --> APPLICATION[application
contracts / use cases / ports] - OUTBOUND --> APPLICATION - APPLICATION --> DOMAIN[domain
pure rules and values] -``` - -Rules: - -1. `domain` imports neither application, adapters nor bootstrap. -2. Production `application` imports neither adapters nor bootstrap. -3. Inbound and outbound adapters never import each other or bootstrap. -4. `bootstrap/composition.ts` is the only general composition root. -5. Chain-specific adapter and use-case construction belongs to a family plugin. -6. Circular dependencies are forbidden. -7. Type-only dependencies must follow the same conceptual direction even when the dependency - checker would ignore their runtime edge. - -## 2. Package tree - -```text -src/ -├── index.ts -├── bootstrap/ -│ ├── argv.ts -│ ├── runner.ts -│ ├── composition.ts -│ ├── family-registry.ts -│ └── families/ -│ ├── types.ts -│ └── tron.ts -├── domain/ -│ ├── address/ -│ ├── amounts/ -│ ├── derivation/ -│ ├── errors/ -│ ├── family/ -│ ├── resources/ -│ ├── sources/ -│ ├── types/ -│ └── wallet/ -├── application/ -│ ├── contracts/ -│ │ ├── execution-policy.ts -│ │ ├── execution-scope.ts -│ │ └── progress.ts -│ ├── ports/ -│ │ ├── chain/ -│ │ ├── network-registry.ts -│ │ └── prompt.ts -│ ├── services/ -│ │ ├── capability/ -│ │ ├── pipeline/ -│ │ ├── signer/ -│ │ └── target/ -│ └── use-cases/ -│ └── tron/ -└── adapters/ - ├── inbound/cli/ - │ ├── commands/ - │ ├── contracts/ - │ ├── context/ - │ ├── help/ - │ ├── input/ - │ ├── output/ - │ ├── registry/ - │ ├── render/ - │ └── shell/ - └── outbound/ - ├── chain/tron/ - ├── config/ - ├── keystore/ - ├── ledger/ - ├── persistence/ - ├── price/ - └── tokenbook/ -``` - -## 3. Responsibilities - -### Domain - -Contains pure wallet, account, address, amount, derivation, source, family and transaction value -rules. Domain code performs no filesystem, network, device, terminal or process I/O. - -### Application - -Defines what the product does and which external capabilities it requires. - -- `contracts`: adapter-neutral execution policy, scopes and progress events. -- `ports`: capabilities required by application workflows, implemented by inbound or outbound adapters. -- `services`: reusable orchestration such as signer resolution and transaction pipeline. -- `use-cases`: wallet/config and family-specific workflows. - -Application services consume ports such as `WalletRepository`, `ChainGatewayProvider`, -`LedgerDevice`, `TokenRepository`, `PriceProvider`, `NetworkRegistry`, `PromptPort` and -`BackupWriter`. They never construct or import filesystem, TronWeb, Ledger transport, CoinGecko, -Zod, yargs, CLI rendering or output-envelope implementations. - -### Inbound CLI adapter - -Owns yargs, zod command schemas, help/catalog generation, TTY input, stream discipline, output -envelopes and human rendering. A command definition translates CLI input into a use-case call; it -does not implement persistence or provider transport. CLI-only contracts (`CommandDefinition`, -`ExecutionContext`, globals, session and output envelopes) live under `inbound/cli/contracts`. - -### Outbound adapters - -Implement application ports: - -- encrypted file keystore and atomic persistence; -- YAML configuration document; -- secure backup writer; -- TRON gateway and TronGrid history reader; -- Ledger device transport; -- token repository and price provider. - -### Bootstrap - -- `argv.ts`: pre-yargs global scan required to select output and secret channels. -- `composition.ts`: constructs process-scoped adapters and shared services. -- `runner.ts`: executes one invocation and owns the terminal error boundary. -- `family-registry.ts`: enabled plugin list and family-keyed projections. -- `families/*.ts`: family-specific gateway/signing/use-case/command composition. - -## 4. Command flow - -```mermaid -flowchart LR - ARGV[argv] --> SHELL[yargs shell] - SHELL --> DEF[CommandDefinition] - DEF --> TARGET[target + capability gates] - TARGET --> USECASE[application use case] - USECASE --> PORT[application port] - PORT --> ADAPTER[outbound adapter] - USECASE --> RESULT[typed result] - RESULT --> FORMAT[text or JSON formatter] - FORMAT --> STREAM[one terminal frame] -``` - -Zod remains the single source for command input shape, defaults, validation, help fields and JSON -Schema. Global flags remain table-driven. Business execution modes and confirmation behavior have -one implementation in application services, not duplicate command helpers. - -## 5. Transaction flow - -```mermaid -flowchart LR - RESOLVE[resolve signer] --> BUILD[build] - BUILD --> ESTIMATE[estimate] - ESTIMATE --> MODE{mode} - MODE -->|dry-run| PLAN[plan] - MODE -->|sign| SIGN[software or Ledger sign] - SIGN --> BROADCAST{broadcast?} - BROADCAST -->|no| SIGNED[signed transaction] - BROADCAST -->|yes| SUBMIT[submitted receipt] - SUBMIT --> CONFIRM{wait?} - CONFIRM --> FINAL[submitted / confirmed / failed] -``` - -Chain-specific builders and confirmation readers are provided by the family gateway. The shared -pipeline knows only signer and broadcaster ports. - -## 6. Chain-family extension - -A family plugin owns the concrete composition for one chain family: - -The complete EVM implementation order, public discovery requirements, network contract and -acceptance checklist are defined in [evm-development-plan.zh-TW.md](./evm-development-plan.zh-TW.md). - -```ts -interface FamilyPlugin { - meta: FamilyMeta & { family: F } - signStrategy: SignStrategy - createGateway(network: NetworkDescriptor): ChainGatewayMap[F] - createModule(dependencies: FamilyApplicationDependencies): ChainModule -} -``` - -Adding EVM requires: - -1. Add `evm` to `ChainFamily` and `FamilyMeta` facts. -2. Extend the discriminated `NetworkDescriptor` union. -3. Extend `ChainGatewayMap` with an `EvmGateway` port. -4. Implement EVM address codec, gateway and signing strategy. -5. Implement EVM use cases and CLI command module without changing TRON use cases. -6. Add `bootstrap/families/evm.ts` and one registry entry. -7. Add routing, signer, capability, output and contract tests. - -Only genuinely shared capabilities receive shared ports. TRON staking/resource methods and EVM -gas/nonce methods stay in their family gateways; no universal gateway may accumulate unrelated -chain operations. - -## 7. Behavioral invariants - -- JSON success and error use `wallet-cli.result.v1`. -- Usage errors exit 2; execution errors exit 1; success/meta requests exit 0. -- JSON stdout contains exactly one terminal frame. -- Progress and diagnostics use stderr. -- Unknown exceptions are redacted. -- A run consumes stdin through at most one secret channel. -- Secrets never enter logs, envelopes, argv or environment variables. -- Dry-run does not decrypt, sign or broadcast. -- Watch-only accounts never sign. -- Every persistent mutation is locked and atomically replaced. -- Already-broadcast transactions do not become command failures solely because confirmation times - out. - -## 8. Verification gates - -```bash -npm run typecheck -npm run depcruise -npm test -npm run build -npm run test:live:nile -``` - -`test:live:nile` exercises the live surface in an isolated wallet home and emits a raw log without -exposing the test secret. diff --git a/ts/docs/commands/account/balance.md b/ts/docs/commands/account/balance.md new file mode 100644 index 00000000..d937acb9 --- /dev/null +++ b/ts/docs/commands/account/balance.md @@ -0,0 +1,53 @@ +# wallet-cli account balance + +Show the native TRX balance. + +## Synopsis + +``` +wallet-cli account balance [options] +``` + +## Description + +Fetches the native TRX balance of the active account (or `--account`) from the node. Read-only; no unlock needed. + +## Options + +Only the [global options](../index.md#global-options-every-command) (`--account`, `--network`, …). + +## Examples + +```bash +wallet-cli account balance --network tron:nile +``` + +```console +Label main +Balance 1976.489 TRX +``` + +```bash +wallet-cli account balance --network tron:nile -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"account.balance","data":{"address":"TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ","balance":"1976489000","decimals":6,"symbol":"TRX"},"meta":{"durationMs":1114,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +## Output + +| Field | Type | Meaning | +|---|---|---| +| `address` | string | Queried base58 address | +| `balance` | string | Raw balance in SUN (`"1976489000"` = 1976.489 TRX) | +| `decimals` | number | `6` for TRX | +| `symbol` | string | `TRX` | + +## Exit status + +`0` · `1` execution failure (node unreachable, timeout) · `2` usage error. + +## See also + +[`account portfolio`](portfolio.md) — includes tokens · [`account info`](info.md) · [Units: TRX vs SUN](../../concepts/networks.md#fees-the-tron-resource-model) diff --git a/ts/docs/commands/account/history.md b/ts/docs/commands/account/history.md new file mode 100644 index 00000000..3ce273ab --- /dev/null +++ b/ts/docs/commands/account/history.md @@ -0,0 +1,66 @@ +# wallet-cli account history + +Show transaction history (requires TronGrid). + +## Synopsis + +``` +wallet-cli account history [--limit ] [--only ] [options] +``` + +## Description + +Lists recent transfers touching the account, newest first. History is served by **TronGrid**, not plain node RPC — on networks/endpoints without TronGrid this command fails while `balance`/`info` still work. + +## Options + +| Option | Description | +|---|---| +| `--limit ` | Max records, 1–200 (default 20) | +| `--only ` | Filter by transfer type; omit for all | + +Plus the [global options](../index.md#global-options-every-command). + +## Examples + +```bash +wallet-cli account history --limit 3 --network tron:nile +``` + +```console +"main" recent transactions +| Time | Type | Amount | From / To | Status | +| ----------- | -------- | ------ | ---------------------------------- | ------ | +| 07-11 22:35 | Transfer | 1 TRX | TGkbaCYB4kRBc3Q6wjqkACefUvRwf2KzkH | ✅ | +| 07-11 15:58 | Transfer | 1 TRX | TGkbaCYB4kRBc3Q6wjqkACefUvRwf2KzkH | ✅ | +| 07-11 15:58 | Transfer | 1 TRX | TGkbaCYB4kRBc3Q6wjqkACefUvRwf2KzkH | ✅ | +``` + +```bash +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"}} +``` + +## Output + +| Field | Type | Meaning | +|---|---|---| +| `address` / `only` / `count` | — | Query echo and record count | +| `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`) | +| `records[].amount` | string | Transfer amount; empty when not a value transfer | +| `records[].symbol` | string | Asset symbol (e.g. `TRX`) | +| `records[].from` / `to` / `counterparty` | string | Addresses (may be empty per type) | +| `records[].status` | string | `ok` or failure marker | + +## Exit status + +`0` · `1` execution failure (incl. TronGrid unavailable) · `2` usage error (limit out of 1–200). + +## See also + +[`tx info`](../tx/info.md) · [`account portfolio`](portfolio.md) · [Troubleshooting](../../troubleshooting.md#not-an-error-code-but-frequently-asked) diff --git a/ts/docs/commands/account/index.md b/ts/docs/commands/account/index.md new file mode 100644 index 00000000..fc12c1e6 --- /dev/null +++ b/ts/docs/commands/account/index.md @@ -0,0 +1,24 @@ +# wallet-cli account + +Query on-chain account state. + +## Synopsis + +``` +wallet-cli account COMMAND +``` + +All subcommands read the chain for the **active account** by default; override with `--account ` or change the default with `wallet-cli use `. + +## Subcommands + +| Command | Description | Data source | +|---|---|---| +| [`account balance`](balance.md) | Native balance (TRX/SUN) | node RPC | +| [`account info`](info.md) | Raw account data incl. bandwidth/energy | node RPC | +| [`account history`](history.md) | Transaction history | **TronGrid required** | +| [`account portfolio`](portfolio.md) | Native + token balances, best-effort USD | node RPC + price source | + +## See also + +[`list`](../list.md) — local accounts (no chain access) · [Networks & resources](../../concepts/networks.md) diff --git a/ts/docs/commands/account/info.md b/ts/docs/commands/account/info.md new file mode 100644 index 00000000..21355759 --- /dev/null +++ b/ts/docs/commands/account/info.md @@ -0,0 +1,61 @@ +# wallet-cli account info + +Show the account's raw on-chain data plus a normalized bandwidth/energy resource summary. + +## Synopsis + +``` +wallet-cli account info [options] +``` + +## Description + +Returns the node's full account object — balances, permissions, stakes — plus a normalized `resources` summary of bandwidth and energy. This is where you check whether an account has the resources to transact without burning TRX. + +## Options + +Only the [global options](../index.md#global-options-every-command). + +## Examples + +```bash +wallet-cli account info --network tron:nile +``` + +```console +Label main +Address TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ +Balance 1969.421 TRX +Staked 12 TRX (energy 12 + bandwidth 0) +Energy used 0 / 888 +Bandwidth used 374 / 600 +Created 2026-06-30 +Permissions owner 1-of-1, 1 active group +``` + +```bash +wallet-cli account info --network tron:nile -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"account.info","data":{"address":"TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ","account":{"balance":"1976489000","create_time":1782787719000,"owner_permission":{…},"active_permission":[…],"frozenV2":[{},{"type":"ENERGY","amount":"12000000"},{"type":"TRON_POWER"}],…},"resources":{"bandwidth":{"used":0,"limit":600},"energy":{"used":0,"limit":888}}},"meta":{"durationMs":1914,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +## Output + +| Field | Type | Meaning | +|---|---|---| +| `address` | string | Queried base58 address | +| `account` | object | Account object returned as-is by the TRON node: `balance` (SUN string), timestamps, `owner_permission` / `active_permission` (multi-sig keys & thresholds), `frozenV2` (staked amounts by type), etc.; fields are determined by the node, wallet-cli does not reshape them | +| `resources.bandwidth` | object | `used` / `limit` (bytes) | +| `resources.energy` | object | `used` / `limit` | + +The `resources` block is normalized by wallet-cli — stable, safe to program against; `account` is returned as-is by the node, its fields vary with the node/protocol and are not guaranteed stable. + +## Exit status + +`0` · `1` execution failure · `2` usage error. + +## See also + +[`account balance`](balance.md) · `stake freeze` — obtain resources · [Resource model](../../concepts/networks.md#fees-the-tron-resource-model) diff --git a/ts/docs/commands/account/portfolio.md b/ts/docs/commands/account/portfolio.md new file mode 100644 index 00000000..54342261 --- /dev/null +++ b/ts/docs/commands/account/portfolio.md @@ -0,0 +1,60 @@ +# wallet-cli account portfolio + +Show native + token balances with best-effort USD value. + +## Synopsis + +``` +wallet-cli account portfolio [options] +``` + +## Description + +Aggregates the account's native TRX and address-book token balances into one view, attaching USD prices from an external price source **best-effort**: when a price is unavailable (typical on testnets), `priceUsd` / `valueUsd` are `null` and the command still succeeds. Expect this to be the slowest `account` query — it fans out to the price source. + +## Options + +Only the [global options](../index.md#global-options-every-command). + +## Examples + +```bash +wallet-cli account portfolio --network tron:nile +``` + +```console +"main" Portfolio +| Token | Balance | Price (USD) | Value (USD) | +| ----- | -------- | ----------- | ----------- | +| TRX | 1969.421 | - | - | +Total ≈ - +``` + +```bash +wallet-cli account portfolio --network tron:nile -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"account.portfolio","data":{"network":"tron:nile","account":"wlt_4473p34m.0","address":"TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ","priceSource":"coingecko","holdings":[{"kind":"native","symbol":"TRX","decimals":6,"rawBalance":"1976489000","balance":"1976.489","priceUsd":null,"valueUsd":null}],"totalValueUsd":null},"meta":{"durationMs":11031,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +## Output + +| Field | Type | Meaning | +|---|---|---| +| `network` / `account` / `address` | string | Query context | +| `priceSource` | string | e.g. `coingecko` | +| `holdings[].kind` | string | `native` or token kinds | +| `holdings[].symbol` / `decimals` | — | Token identity | +| `holdings[].rawBalance` | string | Base units | +| `holdings[].balance` | string | Human units | +| `holdings[].priceUsd` / `valueUsd` | number\|null | **Best-effort estimate**; `null` when unpriced | +| `totalValueUsd` | number\|null | Sum of priced holdings, `null` if none priced | + +## Exit status + +`0` (even with all prices `null`) · `1` execution failure · `2` usage error. + +## See also + +[`account balance`](balance.md) · `token` — manage the address book that defines which tokens appear here diff --git a/ts/docs/commands/backup.md b/ts/docs/commands/backup.md new file mode 100644 index 00000000..69b4d08c --- /dev/null +++ b/ts/docs/commands/backup.md @@ -0,0 +1,78 @@ +# wallet-cli backup + +Export an account's secret + metadata to a 0600 file. + +## Synopsis + +``` +wallet-cli backup [--out ] [options] +``` + +## Arguments + +- `account` — account or wallet to export, by accountId, label, or address + +## Options + +| Option | Description | +|---|---| +| `--out ` | output file path; omit to write /backups/-.json; mode 0600, never overwritten | +| `--password-stdin` | read the master password from stdin (fd 0) | + +Plus [global options](index.md). + +## Notes + +The file contains recoverable secret material — move it to secure storage and treat it as the key itself. See [Security](../concepts/security.md). + +## Examples + +In the examples, `$PW` is your master password (from an environment variable, password manager, etc.), fed on stdin via `--password-stdin`. + +```bash +printf '%s' "$PW" | wallet-cli backup main --password-stdin +``` + +```console +⚠️ Backup written /backups/wlt_d1qbj2fb.0-1783751611076.json + Account ID wlt_d1qbj2fb.0 + Secret recovery phrase + File mode 0600 + Bytes 277 + +⚠️ Secret material was written only to the backup file, never to stdout. +``` + +```bash +printf '%s' "$PW" | wallet-cli backup main --out ./main-backup.json --password-stdin -o 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":"TJToBi4Ngr6JT3HqZHfCkKvuQTvqm73HHp"},"seedId":"wlt_d1qbj2fb","secretType":"mnemonic","out":"./main-backup.json","fileMode":"0600","bytes":277},"meta":{"durationMs":1387,"warnings":[]}} +``` + +## Output + +`data` is the backed-up account plus the backup file details. The secret is written only to the file, never to stdout. Local command — no `chain` block. + +| Field | Type | Meaning | +|---|---|---| +| `accountId` | string | Account id | +| `label` | string | Account label | +| `type` | string | Account type (backupable: `seed` / `privateKey`) | +| `index` | number \| null | HD derivation index; `null` for private-key accounts | +| `active` | boolean | Whether it is the active account | +| `addresses.tron` | string | Base58 TRON address | +| `seedId` | string | Owning seed wallet id (`seed` accounts only) | +| `secretType` | string | Kind of exported secret, e.g. `mnemonic` | +| `out` | string | Backup file path | +| `fileMode` | string | File permissions, always `0600` | +| `bytes` | number | File size in bytes | + +## Exit status + +`0` success · `1` execution failure · `2` usage error. See [machine-interface](../machine-interface.md). + +## See also + +[Security model](../concepts/security.md) · [`delete`](delete.md) diff --git a/ts/docs/commands/block.md b/ts/docs/commands/block.md new file mode 100644 index 00000000..4900f09f --- /dev/null +++ b/ts/docs/commands/block.md @@ -0,0 +1,61 @@ +# wallet-cli block + +Get a block (latest if omitted). + +## Synopsis + +``` +wallet-cli block [] [options] +``` + +## Arguments + +- `number` — block height to fetch; omit for the latest block + +## Options + +[Global options](index.md) only. + +## Notes + +Requires `--network` (or config.defaultNetwork). + +## Examples + +```bash +wallet-cli block --network tron:nile +``` + +```console +Number #69,093,315 +Time 2026-07-11 15:29:21 UTC +Transactions 212 +``` + +```bash +wallet-cli block 69093315 --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"}} +``` + +## Output + +`data.block` is the raw TRON block as returned by the node, unmodified. Its exact shape follows the node's block structure; the key fields are below (large hashes and the full transaction list are elided as `…` above). + +| Field | Type | Meaning | +|---|---|---| +| `block.blockID` | string | Block hash | +| `block.block_header.raw_data.number` | number | Block height | +| `block.block_header.raw_data.timestamp` | number | Block time (ms since epoch, UTC) | +| `block.block_header.raw_data.witness_address` | string | Producing SR, hex (`41…`) | +| `block.transactions` | array | Transactions in the block (omitted when empty) | + +## Exit status + +`0` success · `1` execution failure · `2` usage error. See [machine-interface](../machine-interface.md). + +## See also + +[Networks](../concepts/networks.md) diff --git a/ts/docs/commands/chain/index.md b/ts/docs/commands/chain/index.md new file mode 100644 index 00000000..a30c37d2 --- /dev/null +++ b/ts/docs/commands/chain/index.md @@ -0,0 +1,23 @@ +# wallet-cli chain + +Query chain params, prices & node info. + +Three read-only queries for fee estimation, staking/voting decisions, and troubleshooting. Not to be confused with [`networks`](../networks.md), which lists locally known networks without touching a node — `chain` queries the node selected by `--network`. + +## Synopsis + +``` +wallet-cli chain COMMAND +``` + +## Subcommands + +| Command | Page | Description | +|---|---|---| +| `chain params` | [params.md](params.md) | On-chain governance parameters | +| `chain prices` | [prices.md](prices.md) | Energy/bandwidth unit price and memo fee | +| `chain node` | [node.md](node.md) | Connected node status (version / sync / peers) | + +## See also + +[`networks`](../networks.md) · [Energy & bandwidth](../../concepts/energy-bandwidth.md) · [Troubleshooting](../../troubleshooting.md) diff --git a/ts/docs/commands/chain/node.md b/ts/docs/commands/chain/node.md new file mode 100644 index 00000000..064bf06f --- /dev/null +++ b/ts/docs/commands/chain/node.md @@ -0,0 +1,62 @@ +# wallet-cli chain node + +Connected node status (version / sync / peers). + +## Synopsis + +``` +wallet-cli chain node [options] +``` + +## Description + +Shows the connected node's version, head/solid block heights, sync state, and peer counts. Its job in troubleshooting: separate "the node is out of sync" from "something is wrong with my transaction" before you start debugging the latter. + +How the numbers are made: version, block heights, and peers come from the node's `getnodeinfo`; the "how long ago" freshness check compares the latest block header's timestamp with the local clock — a block age within 3 block intervals (TRON produces a block every 3 s, so 9 s) counts as `in sync`. Public gateways (e.g. TronGrid) may hide some fields (peers, machine info); those rows show `—` (json `null`). + +## Options + +No command-specific options; the [global options](../index.md#global-options-every-command) only (`--network`). + +## Examples + +```bash +wallet-cli chain node --network tron:nile +``` + +```console +Endpoint https://nile.trongrid.io +Version java-tron 4.7.7 +Head block 69,093,315 2026-07-11 15:29:21 (~2s ago — in sync) +Solid block 69,093,296 (19 blocks behind head) +Peers 30 connected / 27 active +``` + +```bash +wallet-cli chain node --network tron:nile -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"chain.node","data":{"endpoint":"https://nile.trongrid.io","version":"java-tron 4.7.7","p2pVersion":"11111","headBlock":{"number":69093315,"timestamp":1783783761000},"solidBlock":{"number":69093296},"lagBlocks":19,"inSync":true,"peers":{"connected":30,"active":27}},"meta":{"durationMs":24,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +## Output + +| Field | Type | Meaning | +|---|---|---| +| `endpoint` | string | Node URL queried | +| `version` | string | Node software version | +| `p2pVersion` | string | P2P protocol version | +| `headBlock` | object | Latest block `{number, timestamp}` | +| `solidBlock` | object | Solidified block `{number}` | +| `lagBlocks` | number | Head − solid block gap | +| `inSync` | boolean | Whether the head block is fresh (≤ 9 s old) | +| `peers` | object \| null | `{connected, active}`; `null` when the endpoint hides it | + +## Exit status + +`0` success · `1` execution failure (`rpc_error`, `timeout`) · `2` usage error. + +## See also + +[`chain params`](params.md) · [`networks`](../networks.md) · [Troubleshooting](../../troubleshooting.md) diff --git a/ts/docs/commands/chain/params.md b/ts/docs/commands/chain/params.md new file mode 100644 index 00000000..40eb3d82 --- /dev/null +++ b/ts/docs/commands/chain/params.md @@ -0,0 +1,86 @@ +# wallet-cli chain params + +Show on-chain governance parameters. + +## Synopsis + +``` +wallet-cli chain params [--key ] [options] +``` + +## Description + +Lists the chain's governance parameters — network-wide system settings changed by SR proposals (this CLI does not create proposals). `--key` returns a single one. Keys pass through exactly as the chain returns them; text output adds thousands separators and units (SUN / ms) for known numeric keys, `-o json` keeps raw values. + +Frequently used keys: + +| Key | Meaning | +|---|---| +| `getEnergyFee` | Energy unit price (SUN/energy) — the burn rate when you lack energy; core input to fee estimation | +| `getTransactionFee` | Bandwidth unit price (SUN/byte) — the burn rate once free bandwidth is spent | +| `getCreateAccountFee` | System-side account creation fee (SUN) — part of the extra cost of sending to a fresh address | +| `getWitnessPayPerBlock` | SR reward per block produced (SUN) — feeds the voting-reward pool | +| `getMaintenanceTimeInterval` | Maintenance cycle length (ms; 21,600,000 = 6 h) — the vote-tally / SR-ranking period | + +For the fee-relevant prices in friendlier form, use [`chain prices`](prices.md). + +## Options + +| Option | Description | +|---|---| +| `--key ` | Return only this parameter (e.g. `getEnergyFee`) | + +Plus the [global options](../index.md#global-options-every-command). + +## Examples + +A single parameter with `--key`: + +```bash +wallet-cli chain params --key getEnergyFee --network tron:nile +``` + +```console +Key getEnergyFee +Value 210 SUN +``` + +All parameters (excerpt): + +```bash +wallet-cli chain params --network tron:nile +``` + +```console +Key Value +getEnergyFee 210 SUN +getTransactionFee 1,000 SUN +getCreateAccountFee 100,000 SUN +getWitnessPayPerBlock 16,000,000 SUN +getMaintenanceTimeInterval 21,600,000 ms +``` + +```bash +wallet-cli chain params --network tron:nile -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"chain.params","data":{"params":[{"key":"getEnergyFee","value":210},{"key":"getTransactionFee","value":1000},{"key":"getCreateAccountFee","value":100000}]},"meta":{"durationMs":19,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +## Output + +`data.params[]` — one entry per parameter: + +| Field | Type | Meaning | +|---|---|---| +| `key` | string | Parameter name, verbatim from the chain | +| `value` | number | Raw chain value, no unit suffix (text adds SUN / ms) | + +## Exit status + +`0` success · `1` execution failure (`rpc_error`; `not_found` — `--key` doesn't exist) · `2` usage error (`invalid_value`). + +## See also + +[`chain prices`](prices.md) · [`chain node`](node.md) diff --git a/ts/docs/commands/chain/prices.md b/ts/docs/commands/chain/prices.md new file mode 100644 index 00000000..a0df8ffe --- /dev/null +++ b/ts/docs/commands/chain/prices.md @@ -0,0 +1,59 @@ +# wallet-cli chain prices + +Show energy/bandwidth unit price and the memo fee. + +## Synopsis + +``` +wallet-cli chain prices [options] +``` + +## Description + +Shows the current energy unit price, bandwidth unit price, and memo fee — the inputs to "will this burn TRX, and how much". Read-only; no account or password. + +The node returns a price *history* timeline; text shows only the current value (the last segment), while `-o json` keeps the full `history`. + +**Units**: unit prices stay in **SUN** (1 TRX = 1,000,000 SUN) — the industry convention, and `--fee-limit` etc. are SUN-denominated; the memo fee, being an ordinary amount, is shown in TRX. json is uniformly SUN. + +## Options + +No command-specific options; the [global options](../index.md#global-options-every-command) only (`--network`). + +## Examples + +```bash +wallet-cli chain prices --network tron:nile +``` + +```console +Energy price 210 SUN / unit (current) +Bandwidth price 1,000 SUN / unit (current) +Memo fee 1 TRX +``` + +```bash +wallet-cli chain prices --network tron:nile -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"chain.prices","data":{"energy":{"currentSunPerUnit":210,"history":[{"since":1542607200000,"price":100},{"since":1670515200000,"price":210}]},"bandwidth":{"currentSunPerUnit":1000,"history":[{"since":1542607200000,"price":10},{"since":1614456000000,"price":1000}]},"memoFeeSun":"1000000"},"meta":{"durationMs":21,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +## Output + +| Field | Type | Meaning | +|---|---|---| +| `energy.currentSunPerUnit` | number | Current energy price, SUN per unit | +| `energy.history[]` | array | `{since (epoch ms), price}` price timeline | +| `bandwidth.currentSunPerUnit` | number | Current bandwidth price, SUN per unit | +| `bandwidth.history[]` | array | `{since, price}` price timeline | +| `memoFeeSun` | string | Memo fee, in SUN | + +## Exit status + +`0` success · `1` execution failure (`rpc_error`, `timeout`) · `2` usage error. + +## See also + +[`chain params`](params.md) · [`chain node`](node.md) · [Energy & bandwidth](../../concepts/energy-bandwidth.md) · [`tx send`](../tx/send.md) diff --git a/ts/docs/commands/change-password.md b/ts/docs/commands/change-password.md new file mode 100644 index 00000000..320b10e9 --- /dev/null +++ b/ts/docs/commands/change-password.md @@ -0,0 +1,59 @@ +# wallet-cli change-password + +Change the master password (re-encrypt all software wallet keystores). + +## Synopsis + +``` +wallet-cli change-password [--yes] +``` + +## Description + +The master password decrypts **every software wallet's** keystore, so changing it means: verify the old password, set a new one, then decrypt-and-re-encrypt every software keystore atomically. Ledger and watch-only accounts hold no secrets and are unaffected. + +**Interactive-only**: old password, new password, and confirmation are all hidden TTY prompts. There is no stdin or argv path — the command handles two high-value secrets at once and runs rarely, so nothing may pass through pipes, shell history, or the process list. Without a TTY it fails with `tty_required`. + +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`). +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. + +## Options + +| Option | Description | +|---|---| +| `--yes` | Skip the final confirmation prompt (step 3) | + +Plus the [global options](index.md#global-options-every-command). + +## Examples + +```bash +wallet-cli change-password +``` + +```console +? Current master password (hidden): +? New master password (hidden): +? Confirm new password (hidden): +? Re-encrypt 3 software wallet(s) with the new password? [y/N]: y +✅ Master password changed — re-encrypted 3 software wallet(s) + Wallets wallet1, wallet2, imported-1 + +⚠️ Ledger / watch-only accounts have no secrets and are unaffected. +``` + +## 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. + +## 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. + +## See also + +[`backup`](backup.md) · [Security model](../concepts/security.md) · [machine-interface → Secret handling](../machine-interface.md#secret-handling) diff --git a/ts/docs/commands/config.md b/ts/docs/commands/config.md new file mode 100644 index 00000000..48c3469d --- /dev/null +++ b/ts/docs/commands/config.md @@ -0,0 +1,96 @@ +# wallet-cli config + +Show / get / set configuration values. + +## Synopsis + +``` +wallet-cli config [] [] [options] +``` + +## Arguments + +- `key` — config key to read or set; omit to show the whole effective config +- `value` — new value; omit to read the key + +## Options + +[Global options](index.md) only. + +## Notes + +Known keys: + +| Key | Values | Built-in default | Meaning | +|---|---|---|---| +| `defaultNetwork` | network id | `tron:mainnet` | Network used when `--network` is omitted | +| `defaultOutput` | `text` \| `json` | `text` | Output format when `-o` is omitted | +| `timeoutMs` | integer ms | `60000` | Default per RPC/device call timeout (`--timeout` overrides) | +| `waitTimeoutMs` | integer ms ≥ 0 | `60000` | Default `--wait` polling cap for broadcast commands | +| `networks` | — | — | Known networks (read-only list) | + +Precedence for a value that has both a flag and a config key (highest first): command-line flag > config value > built-in default — e.g. `--timeout` > config `timeoutMs` > built-in 60000. + +An invalid value returns `invalid_value` (exit 2). + +## Examples + +Show the whole effective config: + +```bash +wallet-cli config +``` + +```console +defaultNetwork tron:mainnet +defaultOutput text +timeoutMs 60000 +waitTimeoutMs 60000 +networks tron:mainnet, tron:nile, tron:shasta +``` + +Read one key, then set it: + +```bash +wallet-cli config timeoutMs +``` + +```console +timeoutMs 60000 +``` + +```bash +wallet-cli config timeoutMs 120000 +``` + +```console +✅ Set config + Key timeoutMs + Value 120000 +``` + +```bash +wallet-cli config timeoutMs 120000 -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"config","data":{"key":"timeoutMs","value":120000,"input":"120000"},"meta":{"durationMs":3,"warnings":[]}} +``` + +## Output + +`data` varies by mode. Local command — no `chain` block. + +| Mode | `data` fields | +|---|---| +| show all (no args) | one field per key: `defaultNetwork`, `defaultOutput`, `timeoutMs`, `waitTimeoutMs`, `networks` (array of network ids) | +| read (``) | `key`, `value` | +| set (` `) | `key`, `value`, `input` (the raw string as typed) | + +## Exit status + +`0` success · `1` execution failure · `2` usage error. See [machine-interface](../machine-interface.md). + +## See also + +[Networks](../concepts/networks.md) · [machine-interface](../machine-interface.md) diff --git a/ts/docs/commands/contract/call.md b/ts/docs/commands/contract/call.md new file mode 100644 index 00000000..7ae73427 --- /dev/null +++ b/ts/docs/commands/contract/call.md @@ -0,0 +1,60 @@ +# wallet-cli contract call + +Read-only contract call (triggerConstantContract). + +## Synopsis + +``` +wallet-cli contract call --contract
--method [--params ] [options] +``` + +## Description + +Calls a contract method as a constant (read-only) call: nothing is signed, nothing is broadcast, no fee is spent. The active account (or `--account`) is used as the caller address — some methods (e.g. `balanceOf`-style views with `msg.sender`) care about who asks. + +Parameters are a JSON array of `{type, value}` objects matching the method signature. + +## Options + +| Option | Description | +|---|---| +| `--contract ` | **Required.** Contract address | +| `--method ` | **Required.** Function signature, e.g. `balanceOf(address)` | +| `--params ` | JSON array of ABI parameters as `{type,value}`; omit to pass none | + +Plus the [global options](../index.md#global-options-every-command). + +## Examples + +```bash +wallet-cli contract call --contract TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf --method "balanceOf(address)" --params '[{"type":"address","value":"TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ"}]' --network tron:nile +``` + +```console +Method balanceOf +Result 0000000000000000000000000000000000000000000000000000000000000000 (raw) +``` + +```bash +wallet-cli contract call --contract TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf --method "balanceOf(address)" --params '[{"type":"address","value":"TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ"}]' --network tron:nile -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"contract.call","data":{"contract":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf","method":"balanceOf(address)","result":["0000000000000000000000000000000000000000000000000000000000000000"]},"meta":{"durationMs":15,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +## Output + +| Field | Type | Meaning | +|---|---|---| +| `contract` | string | Contract address called | +| `method` | string | Method signature invoked | +| `result` | string[] | Raw ABI-encoded return words (hex); decode per the method's return type | + +## Exit status + +`0` success · `1` execution failure (`rpc_error`, revert) · `2` usage error (`invalid_value` — bad signature or params JSON). + +## See also + +[`contract send`](send.md) · [`contract info`](info.md) · [`token balance`](../token/balance.md) diff --git a/ts/docs/commands/contract/deploy.md b/ts/docs/commands/contract/deploy.md new file mode 100644 index 00000000..af1beaf2 --- /dev/null +++ b/ts/docs/commands/contract/deploy.md @@ -0,0 +1,76 @@ +# wallet-cli contract deploy + +Deploy a smart contract. + +## Synopsis + +``` +wallet-cli contract deploy --abi --bytecode --fee-limit + [--constructor-sig --params ] + [--dry-run | --sign-only] [--wait [--wait-timeout ]] [options] +``` + +## Description + +Deploys compiled contract bytecode from the active account (or `--account`) and reports the new contract address. `--fee-limit` is **required** here (deployments are energy-heavy; there is no safe default). Constructor arguments go via `--constructor-sig` + `--params`. + +Same execution model as other broadcast commands: `--dry-run` previews, `--sign-only` outputs a signed transaction for [`tx broadcast`](../tx/broadcast.md), default returns at submission, `--wait` blocks until confirmed/failed. + +Requires an account and the master password via `--password-stdin`; watch-only accounts fail with `watch_only_no_signer`. + +## Options + +| Option | Description | +|---|---| +| `--abi ` | **Required.** Contract ABI as a JSON array string | +| `--bytecode ` | **Required.** Compiled bytecode as hex (0x-prefixed or bare) | +| `--fee-limit ` | **Required.** Max energy fee to burn, in SUN | +| `--constructor-sig ` | Constructor signature, e.g. `constructor(uint256)`; omit when no constructor args | +| `--params ` | Constructor args as a JSON array of `{type,value}` | +| `--dry-run` | Estimate only; excludes `--sign-only` | +| `--sign-only` | Sign without broadcasting; excludes `--dry-run` | +| `--wait` / `--wait-timeout ` | 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 (from an environment variable, password manager, etc.), fed on stdin via `--password-stdin`. + +```bash +echo "$PW" | wallet-cli contract deploy --abi "$(cat MyToken.abi.json)" --bytecode "$(cat MyToken.bin)" --fee-limit 1000000000 --network tron:nile --password-stdin +``` + +```console +⏳ Contract deployed + Address TXg3jWThoa5AxuwRA4aRyFAhmRN9hjhQFU + TxID b7c... + Status pending — not yet on-chain +! Track it: wallet-cli tx info --network tron:nile --txid b7c... +``` + +```bash +echo "$PW" | wallet-cli contract deploy --abi "$(cat MyToken.abi.json)" --bytecode "$(cat MyToken.bin)" --fee-limit 1000000000 --network tron:nile --password-stdin -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"contract.deploy","data":{"kind":"contract-deploy","contractAddress":"TXg3jWThoa5AxuwRA4aRyFAhmRN9hjhQFU","stage":"submitted","txId":"b7c..."},"meta":{"durationMs":15,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +## Output + +`data` varies by stage: + +| Stage | Fields | +|---|---| +| default (submit) | `kind: "contract-deploy"`, `contractAddress` (deterministic new address), `stage: "submitted"`, `txId` | +| `--wait` (confirmed) | above, plus `confirmed`, `blockNumber`, `feeSun`, `failed` | + +## 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 (`invalid_value` — bad ABI/bytecode/params, missing `--fee-limit`). + +## See also + +[`contract info`](info.md) · [`contract send`](send.md) · [`tx status`](../tx/status.md) diff --git a/ts/docs/commands/contract/index.md b/ts/docs/commands/contract/index.md new file mode 100644 index 00000000..ccc7774a --- /dev/null +++ b/ts/docs/commands/contract/index.md @@ -0,0 +1,22 @@ +# wallet-cli contract + +Call, send, deploy, and inspect smart contracts. + +## Synopsis + +``` +wallet-cli contract COMMAND +``` + +## Subcommands + +| Command | Page | Description | +|---|---|---| +| `contract call` | [call.md](call.md) | Read-only call (triggerConstantContract) | +| `contract send` | [send.md](send.md) | State-changing call (triggerSmartContract) | +| `contract deploy` | [deploy.md](deploy.md) | Deploy a smart contract | +| `contract info` | [info.md](info.md) | Show contract ABI + metadata | + +## See also + +[Energy & bandwidth](../../concepts/energy-bandwidth.md) · [`tx status`](../tx/status.md) diff --git a/ts/docs/commands/contract/info.md b/ts/docs/commands/contract/info.md new file mode 100644 index 00000000..3989c1ad --- /dev/null +++ b/ts/docs/commands/contract/info.md @@ -0,0 +1,62 @@ +# wallet-cli contract info + +Show contract ABI + metadata. + +## Synopsis + +``` +wallet-cli contract info --contract
[options] +``` + +## Description + +Fetches a deployed contract's ABI and metadata (getContract + getContractInfo combined): name, method list, origin address, bytecode, energy settings. Useful before crafting a [`contract call`](call.md) / [`contract send`](send.md) — the ABI tells you the exact method signatures. Read-only — no account or password involved. + +## Options + +| Option | Description | +|---|---| +| `--contract ` | **Required.** Contract address | + +Plus the [global options](../index.md#global-options-every-command). + +## Examples + +```bash +wallet-cli contract info --contract TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf --network tron:nile +``` + +```console +Contract TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf +Name TetherToken +Methods 33 (name / deprecate / approve …) +``` + +```bash +wallet-cli contract info --contract TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf --network tron:nile -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"contract.info","data":{"address":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf","name":"TetherToken","functionCount":33,"methods":["name","deprecate","approve","deprecated","addBlackList","totalSupply","transferFrom","…"],"contract":{"origin_address":"41…","contract_address":"41…","abi":{},"bytecode":"…","name":"TetherToken"},"info":{"smart_contract":{},"runtimecode":"…","contract_state":{}}},"meta":{"durationMs":15,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +## Output + +| Field | Type | Meaning | +|---|---|---| +| `address` | string | Contract address | +| `name` | string | Contract name | +| `functionCount` | number | Number of ABI functions | +| `methods` | string[] | Function names | +| `contract` | object | Raw `getContract` (ABI, bytecode, origin) — json only | +| `info` | object | Raw `getContractInfo` (runtime code, contract state) — json only | + +Text output shows the human summary; the raw `contract` / `info` detail is json-only. + +## Exit status + +`0` success · `1` execution failure (`rpc_error`; address is not a contract) · `2` usage error. + +## See also + +[`contract call`](call.md) · [`contract deploy`](deploy.md) · [`token info`](../token/info.md) diff --git a/ts/docs/commands/contract/send.md b/ts/docs/commands/contract/send.md new file mode 100644 index 00000000..9dd68f26 --- /dev/null +++ b/ts/docs/commands/contract/send.md @@ -0,0 +1,112 @@ +# wallet-cli contract send + +State-changing contract call (triggerSmartContract). + +## Synopsis + +``` +wallet-cli contract send --contract
--method [--params ] + [--call-value-sun ] [--fee-limit ] + [--dry-run | --sign-only] [--wait [--wait-timeout ]] [options] +``` + +## Description + +Builds, signs, and broadcasts a state-changing contract call from the active account (or `--account`). Parameters follow the same `{type,value}` JSON-array convention as [`contract call`](call.md); `--call-value-sun` attaches native TRX to the call. + +Two early exits: `--dry-run` previews the energy cost (estimateEnergy) without signing or broadcasting; `--sign-only` signs and prints the transaction for a later [`tx broadcast`](../tx/broadcast.md). + +**By default the command returns at submission** (`stage: "submitted"`) — add `--wait` to block until confirmed/failed. With `--wait`, an on-chain execution failure (revert / `OUT_OF_ENERGY`) comes back as `stage: "failed"` with the `result` reason. + +Requires an account and the master password via `--password-stdin`; watch-only accounts fail with `watch_only_no_signer`. + +## Options + +| Option | Description | +|---|---| +| `--contract ` | **Required.** Contract address | +| `--method ` | **Required.** Function signature, e.g. `transfer(address,uint256)` | +| `--params ` | JSON array of ABI parameters as `{type,value}` | +| `--call-value-sun ` | Native TRX attached to the call, in SUN (default 0) | +| `--fee-limit ` | Max energy fee to burn, in SUN (default 100000000) | +| `--dry-run` | Estimate energy only, no signature/broadcast; excludes `--sign-only` | +| `--sign-only` | Sign without broadcasting; excludes `--dry-run` | +| `--wait` / `--wait-timeout ` | 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 (from an environment variable, password manager, etc.), fed on stdin via `--password-stdin`. + +Default — broadcasts and returns the **submitted** receipt: + +```bash +echo "$PW" | wallet-cli contract send --contract TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf --method "transfer(address,uint256)" --params '[{"type":"address","value":"TSx72ViULFepRGCS4PM5dP4FqD1d8qggCc"},{"type":"uint256","value":"1000000"}]' --network tron:nile --password-stdin +``` + +```console +⏳ Called transfer + TxID c8d... + Status pending — not yet on-chain +! Track it: wallet-cli tx info --network tron:nile --txid c8d... +``` + +```bash +echo "$PW" | wallet-cli contract send --contract TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf --method "transfer(address,uint256)" --params '[...]' --network tron:nile --password-stdin -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"contract.send","data":{"kind":"contract-send","stage":"submitted","txId":"c8d...","method":"transfer(address,uint256)","contract":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf"},"meta":{"durationMs":15,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +With `--wait`, blocks until confirmed — on success: + +```bash +echo "$PW" | wallet-cli contract send --contract TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf --method "transfer(address,uint256)" --params '[...]' --network tron:nile --wait --password-stdin +``` + +```console +✅ Called transfer + Contract TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf + TxID 0adc5737b724d35c486a05a169b64a01ad311ed27f79d308f245b00c69b3bc42 + Block #69,095,391 + Energy 14,584 + Fee 0.345 TRX + Status success +``` + +An on-chain failure (e.g. out of energy) returns `stage: "failed"`: + +```bash +echo "$PW" | wallet-cli contract send --contract TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf --method "transfer(address,uint256)" --params '[...]' --network tron:nile --wait --password-stdin +``` + +```console +❌ Called transfer + TxID c8d... + Block #66,000,123 + Energy 31,200 + Status failed + Reason OUT_OF_ENERGY +``` + +## Output + +`data` varies by stage: + +| Mode | Fields | +|---|---| +| default (submit) | `kind: "contract-send"`, `stage: "submitted"`, `txId`, `method`, `contract` | +| `--wait` (confirmed/failed) | above, but `stage: "confirmed"` or `"failed"`, plus `confirmed`, `blockNumber`, `feeSun`, `energyUsed`, `result` (`SUCCESS` / `OUT_OF_ENERGY`, etc.), `failed` | +| `--dry-run` | `kind`, `mode: "dry-run"`, `fee` (`feeModel`, estimated `energy`, `availableEnergy`), unsigned `tx` | +| `--sign-only` | `kind`, `mode: "sign-only"`, `signed` (feed to `tx broadcast`), `fee`, `method`, `contract` | + +## Exit status + +`0` submitted (or built/signed in early-exit modes) · `1` execution failure (`watch_only_no_signer`, `auth_failed`, `rpc_error`, `timeout` — on timeout the tx may still be in flight; check [`tx status`](../tx/status.md)) · `2` usage error (`invalid_value`, conflicting modes). + +## See also + +[`contract call`](call.md) · [`contract deploy`](deploy.md) · [`tx broadcast`](../tx/broadcast.md) · [Energy & bandwidth](../../concepts/energy-bandwidth.md) diff --git a/ts/docs/commands/create.md b/ts/docs/commands/create.md new file mode 100644 index 00000000..fd8a16ed --- /dev/null +++ b/ts/docs/commands/create.md @@ -0,0 +1,80 @@ +# wallet-cli create + +Create a new HD wallet (BIP39 seed). + +## Synopsis + +``` +wallet-cli create [options] +``` + +## Description + +Generates a new BIP39 seed, derives account #0, encrypts everything under your master password, and stores it locally. The mnemonic is **not printed** — the seed is encrypted at rest; run [`backup`](backup.md) to export the recovery phrase to a `0600` file. Further accounts can be derived from the same seed later with [`derive`](derive.md). + +Requires the **master password**: pass `--password-stdin` for non-interactive use, or enter it at the TTY prompt. The password must be at least 8 characters and include an uppercase letter, a lowercase letter, a digit, and a special character (`!@#$%^&*()-_=+[]{};:,.?`); a weaker one fails with `weak_password` (exit 2). + +## Options + +| Option | Description | +|---|---| +| `--label ` | Human-friendly unique account label, 1–64 chars; omit to auto-generate | +| `--password-stdin` | Read the master password from stdin (fd 0); only one `*-stdin` flag can consume stdin per run | + +Plus the [global options](index.md#global-options-every-command). + +## Examples + +In the examples, `$PW` is your master password (from an environment variable, password manager, etc.), fed on stdin via `--password-stdin`. + +Interactive — prompts for the master password, then shows the new account: + +```bash +wallet-cli create --label main +``` + +```console +? Set master password (hidden): +? Confirm master password: +✅ Created wallet "main" + Account ID wlt_2dbv24de.0 + Type HD + TRON address TTVdGTBXY5mmY3nJFGUp7Vo898kUJ6gtFQ + Active yes + +⚠️ Recovery phrase is encrypted locally and was not printed. +⚠️ Run `backup` soon and store the file offline. +``` + +Non-interactive (password piped from stdin): + +```bash +printf '%s' "$PW" | wallet-cli create --label main --password-stdin -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"create","data":{"status":"created","accountId":"wlt_2dbv24de.0","label":"main","type":"seed","index":0,"active":true,"addresses":{"tron":"TTVdGTBXY5mmY3nJFGUp7Vo898kUJ6gtFQ"},"seedId":"wlt_2dbv24de"},"meta":{"durationMs":38,"warnings":[]}} +``` + +## Output + +`data` describes the created account (local command — no `chain` block). No mnemonic field is ever returned. + +| Field | Type | Meaning | +|---|---|---| +| `status` | string | `"created"` | +| `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 | Whether it became the active account | +| `addresses.tron` | string | Base58 TRON address | +| `seedId` | string | Owning seed wallet id | + +## Exit status + +`0` created · `1` execution failure · `2` usage error (e.g. label already taken / invalid, `weak_password`). See [machine-interface](../machine-interface.md#exit-codes). + +## See also + +[`import mnemonic`](import/mnemonic.md) · [`list`](list.md) · [`derive`](derive.md) · [`backup`](backup.md) · [Getting started](../guide/getting-started.md) diff --git a/ts/docs/commands/current.md b/ts/docs/commands/current.md new file mode 100644 index 00000000..f2dbddb0 --- /dev/null +++ b/ts/docs/commands/current.md @@ -0,0 +1,65 @@ +# wallet-cli current + +Show the current (active) account. + +## Synopsis + +``` +wallet-cli current [options] +``` + +## Options + +[Global options](index.md) only. + +## Examples + +```bash +wallet-cli current +``` + +```console +Active account: main-1 + TRON address TRs9HgTuY3dT3yDasdFdP9WQHqL37891Ax +``` + +```bash +wallet-cli current -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"current","data":{"accountId":"wlt_758891fa.1","label":"main-1","type":"seed","index":1,"active":true,"addresses":{"tron":"TRs9HgTuY3dT3yDasdFdP9WQHqL37891Ax"},"seedId":"wlt_758891fa"},"meta":{"durationMs":13,"warnings":[]}} +``` + +With no active account yet, it fails with `missing_wallet_address` (exit 1): + +```bash +wallet-cli current +``` + +```console +error [missing_wallet_address]: no active account; import one first +``` + +## Output + +`data` is the current active account. Local command — no `chain` block. + +| Field | Type | Meaning | +|---|---|---| +| `accountId` | string | Active account id | +| `label` | string | Account label | +| `type` | string | `seed` / `privateKey` / `watch` / `ledger` | +| `index` | number \| null | HD derivation index; `null` for non-HD accounts | +| `active` | boolean | Always `true` | +| `addresses.tron` | string | Base58 TRON address | +| `seedId` | string | Owning seed wallet id (`seed` accounts only) | +| `family` | string | Chain family, e.g. `tron` (`watch` accounts only) | + +## Exit status + +`0` success · `1` execution failure · `2` usage error. See [machine-interface](../machine-interface.md). + +## See also + +[`use`](use.md) · [`list`](list.md) diff --git a/ts/docs/commands/delete.md b/ts/docs/commands/delete.md new file mode 100644 index 00000000..db92b1ad --- /dev/null +++ b/ts/docs/commands/delete.md @@ -0,0 +1,79 @@ +# wallet-cli delete + +Delete a wallet/account and clean orphan labels. + +## Synopsis + +``` +wallet-cli delete [--yes] [options] +``` + +## Arguments + +- `account` — account or wallet to delete, by accountId, label, or address + +## Options + +| Option | Description | +|---|---| +| `--yes` | skip the interactive confirmation; required for non-TTY deletion | + +Plus [global options](index.md). + +## Notes + +Deleting an HD wallet cascades from the seed root — all derived accounts go with it. On-chain assets are untouched; re-import the mnemonic to regain access. Back up first. Metadata-only — no master password needed. + +## Examples + +Without `--yes`, deletion prompts for confirmation — you must type the account label exactly: + +```bash +wallet-cli delete solo +``` + +```console +? Delete solo? Type the exact label "solo" to confirm: solo +✅ Deleted wallet wlt_p7cg790g + Secret removed yes +``` + +Deleting an HD root cascades to the whole wallet (all derived accounts + keys): + +```bash +wallet-cli delete main --yes +``` + +```console +✅ Deleted wallet wlt_teh9fafq + Secret removed yes +``` + +Deleting a single HD sub-account removes only that account, keeping the seed key (you can `derive` again); the JSON shows the deletion scope, whether the key was removed too, and the account active afterwards: + +```bash +wallet-cli delete main-1 --yes -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"delete","data":{"accountId":"wlt_teh9fafq.1","scope":"account","secretRemoved":false,"newActive":"wlt_teh9fafq.0"},"meta":{"durationMs":14,"warnings":[]}} +``` + +## Output + +`data` describes the deletion result. Local command — no `chain` block. + +| Field | Type | Meaning | +|---|---|---| +| `accountId` | string | Id of the deleted account/wallet (`wlt_….N` for a sub-account, the wallet id `wlt_…` for a wallet) | +| `scope` | string | `account` (only that account) or `wallet` (cascaded whole wallet) | +| `secretRemoved` | boolean | Whether the key was removed (deleting an HD sub-account keeps the seed = `false`; deleting a wallet = `true`) | +| `newActive` | string \| null | New active account id after deletion; `null` if none remain | + +## Exit status + +`0` success · `1` execution failure · `2` usage error. See [machine-interface](../machine-interface.md). + +## See also + +[`backup`](backup.md) · [Accounts & HD](../concepts/accounts-and-hd.md) diff --git a/ts/docs/commands/derive.md b/ts/docs/commands/derive.md new file mode 100644 index 00000000..d0c75dab --- /dev/null +++ b/ts/docs/commands/derive.md @@ -0,0 +1,70 @@ +# wallet-cli derive + +Derive the next HD account from a seed wallet (by --seed-id). + +## Synopsis + +``` +wallet-cli derive --seed-id [--index ] [--label ] [options] +``` + +## Options + +| Option | Description | +|---|---| +| `--seed-id ` | seed id of the HD wallet to derive from — the HD group header in `list` [required] | +| `--index ` | explicit HD account index; omit to use the next free index | +| `--label ` | label for the new account, 1-64 chars; omit to auto-generate | +| `--password-stdin` | read the master password from stdin (fd 0) | + +Plus [global options](index.md). + +## Notes + +Private-key and Ledger accounts have no seed and cannot derive. See [Accounts & HD](../concepts/accounts-and-hd.md). + +## Examples + +In the examples, `$PW` is your master password (from an environment variable, password manager, etc.), fed on stdin via `--password-stdin`. + +```bash +printf '%s' "$PW" | wallet-cli derive --seed-id wlt_y8cz6xda --password-stdin +``` + +```console +✅ Derived sub-account "main-1" + Address TWCa1W6BkcXZnRGxeZZw9jh8eNgULDVGzj + Active yes + Note shares master mnemonic; no separate backup needed +``` + +```bash +printf '%s' "$PW" | wallet-cli derive --seed-id wlt_y8cz6xda --password-stdin -o json +``` + +```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"},"seedId":"wlt_y8cz6xda"},"meta":{"durationMs":1013,"warnings":[]}} +``` + +## Output + +`data` is the newly derived account (always an HD `seed` account). Local command — no `chain` block. + +| Field | Type | Meaning | +|---|---|---| +| `status` | string | `"created"` | +| `accountId` | string | Stable id `.` | +| `label` | string | Account label (default `-`, e.g. `main-1`) | +| `type` | string | Always `"seed"` | +| `index` | number | HD derivation index | +| `active` | boolean | Always `true` (the new account is made active) | +| `addresses.tron` | string | Base58 TRON address | +| `seedId` | string | Owning seed wallet id | + +## Exit status + +`0` success · `1` execution failure · `2` usage error. See [machine-interface](../machine-interface.md). + +## See also + +[`create`](create.md) · [`list`](list.md) diff --git a/ts/docs/commands/import/index.md b/ts/docs/commands/import/index.md new file mode 100644 index 00000000..50aa6aa5 --- /dev/null +++ b/ts/docs/commands/import/index.md @@ -0,0 +1,24 @@ +# wallet-cli import + +Import a wallet from an existing secret or device. + +## Synopsis + +``` +wallet-cli import COMMAND +``` + +## Subcommands + +| Command | Description | +|---|---| +| [`import mnemonic`](mnemonic.md) | Import a BIP39 mnemonic phrase | +| [`import private-key`](private-key.md) | Import a raw private key | +| `import ledger` | Register a Ledger account (watch-only locally; signs on device) — `wallet-cli import ledger --help` | +| `import watch` | Register a watch-only address (no secret) — `wallet-cli import watch --help` | + +All secret-bearing variants take secrets via stdin flags or TTY prompt only — never argv/env. See [machine-interface → Secret handling](../../machine-interface.md#secret-handling). + +## See also + +[`create`](../create.md) · [`list`](../list.md) · [Getting started](../../guide/getting-started.md) diff --git a/ts/docs/commands/import/ledger.md b/ts/docs/commands/import/ledger.md new file mode 100644 index 00000000..542a945c --- /dev/null +++ b/ts/docs/commands/import/ledger.md @@ -0,0 +1,74 @@ +# wallet-cli import ledger + +Register a Ledger account (watch-only; signs on device). + +## Synopsis + +``` +wallet-cli import ledger --app tron (--index | --path | --address ) [--label ] [options] +``` + +## Options + +| Option | Description | +|---|---| +| `--app ` | Ledger app to open, selecting the derivation scheme [required] | +| `--index ` | HD account index to import (mutually exclusive with --path/--address) | +| `--path ` | explicit BIP32 path, e.g. m/44'/195'/0'/0/0 | +| `--address ` | known address to locate by bounded scan | +| `--scan-limit ` | indexes to scan with --address (default 20) | +| `--label ` | unique account label, 1-64 chars | + +Plus [global options](../index.md). + +## Notes + +Creates a watch-only entry; no secret is stored. Requires the device unlocked with the TRON app open. See [Ledger guide](../../guide/ledger.md). + +## Examples + +```bash +wallet-cli import ledger --app tron --index 0 --label cold +``` + +```console +✅ Registered Ledger account "cold" + Account ID wlt_7h2k9d3m + App tron + Path m/44'/195'/0'/0/0 + Address TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ + +⚠️ No private key is stored locally. Signing requires device confirmation. +``` + +```bash +wallet-cli import ledger --app tron --index 0 --label cold -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"import.ledger","data":{"status":"created","accountId":"wlt_7h2k9d3m","label":"cold","type":"ledger","index":null,"active":true,"addresses":{"tron":"TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ"},"family":"tron","path":"m/44'/195'/0'/0/0"},"meta":{"durationMs":812,"warnings":[]}} +``` + +## Output + +`data` carries the newly registered Ledger account — address and derivation path only, no secret. Local command — no `chain` block. + +| Field | Type | Meaning | +|---|---|---| +| `status` | string | `"created"`, or `"existing"` if the account was already registered | +| `accountId` | string | Stable account id | +| `label` | string | Account label | +| `type` | string | `"ledger"` (signs on device) | +| `index` | number \| null | Non-HD account, always `null` (device index lives in `path`) | +| `active` | boolean | Became the active account | +| `addresses.tron` | string | Base58 TRON address | +| `family` | string | Chain family of the address (e.g. `tron`) | +| `path` | string | BIP32 derivation path on the device | + +## Exit status + +`0` success · `1` execution failure · `2` usage error. See [machine-interface](../../machine-interface.md). + +## See also + +[Ledger guide](../../guide/ledger.md) · [`import watch`](watch.md) diff --git a/ts/docs/commands/import/mnemonic.md b/ts/docs/commands/import/mnemonic.md new file mode 100644 index 00000000..84edb2df --- /dev/null +++ b/ts/docs/commands/import/mnemonic.md @@ -0,0 +1,85 @@ +# wallet-cli import mnemonic + +Import a BIP39 mnemonic phrase. **Interactive-only.** + +> **Note**: there are no `--mnemonic-stdin` / `--password-stdin` flags. The mnemonic and master password are entered **only** via hidden TTY prompts — a mnemonic can recover all funds, and stdin paths leak too easily into pipes, shell history, and process lists. Importing is rare enough that forcing human input costs little. + +## Synopsis + +``` +wallet-cli import mnemonic [--label ] +``` + +## Description + +Restores an HD wallet from an existing BIP39 mnemonic: derives account #0 and stores the seed encrypted under your master password. The imported wallet becomes active. + +The interactive flow (all secrets hidden, never echoed, never in argv): + +1. **Master password** — set on first use (with confirmation), or entered to unlock. +2. **Label** — optional display name; empty auto-generates one (e.g. `wallet_ad8f21`). +3. **Recovery phrase** — pasted hidden; an AI or script driving the CLI never sees it. +4. **Validate + store** — bad word count / checksum → `invalid_mnemonic`, re-prompt; on success the addresses are derived and the seed is written encrypted, never in plaintext. + +Without a TTY the command fails with `tty_required` — there is no non-interactive path. + +## Options + +| Option | Description | +|---|---| +| `--label ` | Human-friendly unique account label, 1–64 chars; omit to auto-generate | + +Plus the [global options](../index.md#global-options-every-command). + +## Examples + +```bash +wallet-cli import mnemonic --label restored +``` + +```console +? Set master password (hidden): +? Confirm master password: +? Paste recovery phrase (hidden): +✅ Imported wallet "restored" + Account ID wlt_d66fvems.0 + Type HD + TRON address TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH + Active yes + +⚠️ Recovery phrase was read from hidden input and was not printed. +``` + +```bash +wallet-cli import mnemonic --label restored -o json +``` + +```console +? 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":[]}} +``` + +## Output + +`data` carries the imported account — addresses only, never any secret. Local command — no `chain` block. + +| Field | Type | Meaning | +|---|---|---| +| `status` | string | `"created"` | +| `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 | +| `seedId` | string | Owning seed wallet id | + +## 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). + +## See also + +[`import private-key`](private-key.md) · [`create`](../create.md) · [`change-password`](../change-password.md) · [Troubleshooting](../../troubleshooting.md) diff --git a/ts/docs/commands/import/private-key.md b/ts/docs/commands/import/private-key.md new file mode 100644 index 00000000..8e9840a9 --- /dev/null +++ b/ts/docs/commands/import/private-key.md @@ -0,0 +1,77 @@ +# wallet-cli import private-key + +Import a raw private key. **Interactive-only.** + +> **Note**: there are no `--private-key-stdin` / `--password-stdin` flags. The private key and master password are entered **only** via hidden TTY prompts — a private key is as sensitive as a mnemonic, so the same constraint applies. + +## Synopsis + +``` +wallet-cli import private-key [--label ] +``` + +## Description + +Imports a single account from a raw private key and stores it encrypted under your master password. Unlike mnemonic imports, a private-key account has no seed — nothing can be derived from it. The imported wallet becomes active. + +The interactive flow mirrors [`import mnemonic`](mnemonic.md): master password (hidden) → label → private key (hidden, never echoed) → validate (`invalid_private_key` re-prompts) and store encrypted. Without a TTY the command fails with `tty_required` — there is no non-interactive path. + +## Options + +| Option | Description | +|---|---| +| `--label ` | Human-friendly unique account label, 1–64 chars; omit to auto-generate | + +Plus the [global options](../index.md#global-options-every-command). + +## Examples + +```bash +wallet-cli import private-key --label hot +``` + +```console +? Set master password (hidden): +? Confirm master password: +? Paste private key (hidden): +✅ Imported wallet "hot" + Account ID wlt_2qnr6j1f + Type private key + TRON address TMVQGm1qAQYVdetCeGRRkTWYYrLXuHK2HC + Active yes + +⚠️ Private key was read from hidden input and was not printed. +``` + +```bash +wallet-cli import private-key --label hot -o json +``` + +```console +? 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":[]}} +``` + +## Output + +`data` carries the imported account — addresses only, never any secret. Local command — no `chain` block. + +| Field | Type | Meaning | +|---|---|---| +| `status` | string | `"created"` | +| `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 | + +## 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). + +## See also + +[`import mnemonic`](mnemonic.md) · [`backup`](../backup.md) · [`change-password`](../change-password.md) · [machine-interface → Secret handling](../../machine-interface.md#secret-handling) diff --git a/ts/docs/commands/import/watch.md b/ts/docs/commands/import/watch.md new file mode 100644 index 00000000..cbc39c8a --- /dev/null +++ b/ts/docs/commands/import/watch.md @@ -0,0 +1,65 @@ +# wallet-cli import watch + +Register a watch-only address (no secret). + +## Synopsis + +``` +wallet-cli import watch --address [--label ] [options] +``` + +## Options + +| Option | Description | +|---|---| +| `--address ` | watch-only address to track; TRON base58 T…; family auto-detected [required] | +| `--label ` | unique account label, 1-64 chars | + +Plus [global options](../index.md). + +## Notes + +Cannot sign — queries only. Useful for monitoring cold-storage balances. + +## Examples + +```bash +wallet-cli import watch --address TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ --label cold +``` + +```console +✅ Added watch-only account "cold" + Address TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ + Note read-only; signing operations will be rejected +``` + +```bash +wallet-cli import watch --address TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ --label cold -o json +``` + +```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":[]}} +``` + +## Output + +`data` carries the newly registered watch-only account — address only, no secret. Local command — no `chain` block. + +| Field | Type | Meaning | +|---|---|---| +| `status` | string | `"created"` | +| `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 | +| `addresses.tron` | string | Base58 TRON address | +| `family` | string | Chain family of the address (e.g. `tron`) | + +## Exit status + +`0` success · `1` execution failure · `2` usage error. See [machine-interface](../../machine-interface.md). + +## See also + +[`import ledger`](ledger.md) · [`account balance`](../account/balance.md) diff --git a/ts/docs/commands/index.md b/ts/docs/commands/index.md new file mode 100644 index 00000000..991dd398 --- /dev/null +++ b/ts/docs/commands/index.md @@ -0,0 +1,110 @@ +# Command Reference + +Every command — including every subcommand — has its own page, following a fixed layout (Synopsis · Description · Options · Examples · Output · Exit status · See also). Command-group pages list and link their subcommands. + +## Wallets and accounts + +| Command | Page | +|---|---| +| `create` | [create.md](create.md) | +| `import mnemonic` | [import/mnemonic.md](import/mnemonic.md) *(interactive-only)* | +| `import private-key` | [import/private-key.md](import/private-key.md) *(interactive-only)* | +| `import ledger` | [import/ledger.md](import/ledger.md) | +| `import watch` | [import/watch.md](import/watch.md) | +| `list` | [list.md](list.md) | +| `use` | [use.md](use.md) | +| `current` | [current.md](current.md) | +| `derive` | [derive.md](derive.md) | +| `rename` | [rename.md](rename.md) | +| `backup` | [backup.md](backup.md) | +| `delete` | [delete.md](delete.md) | +| `change-password` | [change-password.md](change-password.md) | + +## Transactions + +| Command | Page | +|---|---| +| `tx` (group) | [tx/index.md](tx/index.md) | +| `tx send` | [tx/send.md](tx/send.md) | +| `tx broadcast` | [tx/broadcast.md](tx/broadcast.md) | +| `tx status` | [tx/status.md](tx/status.md) | +| `tx info` | [tx/info.md](tx/info.md) | + +## On-chain queries + +| Command | Page | +|---|---| +| `account` (group) | [account/index.md](account/index.md) | +| `account balance` | [account/balance.md](account/balance.md) | +| `account info` | [account/info.md](account/info.md) | +| `account history` | [account/history.md](account/history.md) | +| `account portfolio` | [account/portfolio.md](account/portfolio.md) | +| `block` | [block.md](block.md) | +| `chain` (group) | [chain/index.md](chain/index.md) | +| `chain params` | [chain/params.md](chain/params.md) | +| `chain prices` | [chain/prices.md](chain/prices.md) | +| `chain node` | [chain/node.md](chain/node.md) | + +## Tokens and contracts + +| Command | Page | +|---|---| +| `token` (group) | [token/index.md](token/index.md) | +| `token balance` | [token/balance.md](token/balance.md) | +| `token info` | [token/info.md](token/info.md) | +| `token add` | [token/add.md](token/add.md) | +| `token list` | [token/list.md](token/list.md) | +| `token remove` | [token/remove.md](token/remove.md) | +| `contract` (group) | [contract/index.md](contract/index.md) | +| `contract call` | [contract/call.md](contract/call.md) | +| `contract send` | [contract/send.md](contract/send.md) | +| `contract deploy` | [contract/deploy.md](contract/deploy.md) | +| `contract info` | [contract/info.md](contract/info.md) | + +## Staking, voting, rewards + +| Command | Page | +|---|---| +| `stake` (group) | [stake/index.md](stake/index.md) | +| `stake freeze` | [stake/freeze.md](stake/freeze.md) | +| `stake unfreeze` | [stake/unfreeze.md](stake/unfreeze.md) | +| `stake withdraw` | [stake/withdraw.md](stake/withdraw.md) | +| `stake cancel-unfreeze` | [stake/cancel-unfreeze.md](stake/cancel-unfreeze.md) | +| `stake delegate` | [stake/delegate.md](stake/delegate.md) | +| `stake undelegate` | [stake/undelegate.md](stake/undelegate.md) | +| `stake info` | [stake/info.md](stake/info.md) | +| `stake delegated` | [stake/delegated.md](stake/delegated.md) | +| `vote` (group) | [vote/index.md](vote/index.md) | +| `vote cast` | [vote/cast.md](vote/cast.md) | +| `vote list` | [vote/list.md](vote/list.md) | +| `vote status` | [vote/status.md](vote/status.md) | +| `reward` (group) | [reward/index.md](reward/index.md) | +| `reward balance` | [reward/balance.md](reward/balance.md) | +| `reward withdraw` | [reward/withdraw.md](reward/withdraw.md) | + +## Signing + +| Command | Page | +|---|---| +| `message` (group) | [message/index.md](message/index.md) | +| `message sign` | [message/sign.md](message/sign.md) | + +## Local + +| Command | Page | +|---|---| +| `config` | [config.md](config.md) | +| `networks` | [networks.md](networks.md) | + +## Global options (every command) + +``` +-o, --output result format (default: config.defaultOutput, built-in text) +--network canonical network id (chain commands; falls back to config.defaultNetwork) +--account accountId, label, or address (wallet-bound commands; falls back to active) +--timeout per RPC/device call timeout, ms (default: config.timeoutMs, built-in 60000) +-v, --verbose extra diagnostic output +-h, --help / -V, --version +``` + +Broadcast (✍️) commands additionally take `--wait` / `--wait-timeout ` (cap default: config `waitTimeoutMs`, built-in 60000) and `--dry-run` / `--sign-only`. diff --git a/ts/docs/commands/list.md b/ts/docs/commands/list.md new file mode 100644 index 00000000..272092bc --- /dev/null +++ b/ts/docs/commands/list.md @@ -0,0 +1,70 @@ +# wallet-cli list + +List wallets/accounts (no unlock needed). + +## Synopsis + +``` +wallet-cli list [options] +``` + +## Description + +Enumerates every locally stored account across all seed wallets and imports: HD accounts are grouped by seed, the rest by type (private key / watch-only / Ledger), marking the active one. Reads only metadata — the master password is not required. + +## Options + +Only the [global options](index.md#global-options-every-command). + +## Examples + +```bash +wallet-cli list +``` + +```console +HD wlt_jj2vgz7m +├─ [0] main TJxvjVUpQ2sVqW4WYN7iX96qWDLFoUU9NN (active) +└─ [1] main-1 TJ4Pa3iF6ppS13RkeL8GHxNyaUfuyncqgS + +private key +└─ hot TMVQGm1qAQYVdetCeGRRkTWYYrLXuHK2HC + +watch-only +└─ cold TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH +``` + +HD accounts are grouped by seed and carry an `[index]`; non-HD entries (private key / watch-only / Ledger) are grouped by type and have no `[index]`. + +```bash +wallet-cli list -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"list","data":[{"accountId":"wlt_jj2vgz7m.0","label":"main","type":"seed","index":0,"active":true,"addresses":{"tron":"TJxvjVUpQ2sVqW4WYN7iX96qWDLFoUU9NN"},"seedId":"wlt_jj2vgz7m"},{"accountId":"wlt_jj2vgz7m.1","label":"main-1","type":"seed","index":1,"active":false,"addresses":{"tron":"TJ4Pa3iF6ppS13RkeL8GHxNyaUfuyncqgS"},"seedId":"wlt_jj2vgz7m"},{"accountId":"wlt_w64e61jy","label":"hot","type":"privateKey","index":null,"active":false,"addresses":{"tron":"TMVQGm1qAQYVdetCeGRRkTWYYrLXuHK2HC"}},{"accountId":"wlt_bnd7sz5e","label":"cold","type":"watch","index":null,"active":false,"addresses":{"tron":"TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH"},"family":"tron"}],"meta":{"durationMs":13,"warnings":[]}} +``` + +## Output + +`data` is an array; one entry per account: + +| Field | Type | Meaning | +|---|---|---| +| `accountId` | string | Stable id; `.` for HD accounts, a standalone `wlt_…` for non-HD | +| `label` | string | Human label (rename with `rename`) | +| `type` | string | `seed` (HD), `privateKey`, `watch`, `ledger` | +| `index` | number \| null | HD derivation index within the seed; `null` for non-HD accounts | +| `active` | boolean | Whether this is the account commands default to | +| `addresses.tron` | string | Base58 TRON address | +| `seedId` | string | Owning seed wallet id (`seed` accounts only) | +| `family` | string | Chain family of the address, e.g. `tron` (`watch` accounts only) | + +Local command — no `chain` block. + +## Exit status + +`0` · `2` usage error. See [machine-interface](../machine-interface.md#exit-codes). + +## See also + +`use` · `current` · [`create`](create.md) · [`account balance`](account/balance.md) diff --git a/ts/docs/commands/message/index.md b/ts/docs/commands/message/index.md new file mode 100644 index 00000000..89e05850 --- /dev/null +++ b/ts/docs/commands/message/index.md @@ -0,0 +1,19 @@ +# wallet-cli message + +Sign arbitrary messages. + +## Synopsis + +``` +wallet-cli message COMMAND +``` + +## Subcommands + +| Command | Page | Description | +|---|---|---| +| `message sign` | [sign.md](sign.md) | Sign an arbitrary message (TIP-191/V2 · EIP-191) | + +## See also + +[Security model](../../concepts/security.md) diff --git a/ts/docs/commands/message/sign.md b/ts/docs/commands/message/sign.md new file mode 100644 index 00000000..c6073902 --- /dev/null +++ b/ts/docs/commands/message/sign.md @@ -0,0 +1,76 @@ +# wallet-cli message sign + +Sign an arbitrary message (TIP-191/V2 · EIP-191). + +## Synopsis + +``` +wallet-cli message sign (--message | --message-stdin) [options] +``` + +## Description + +Signs a message with the active account's key (or `--account`) using TRON's TIP-191/V2 personal-message scheme (EIP-191 compatible). Signing only — nothing is broadcast; `--network` is optional and can be omitted for fully offline signing. + +**stdin has a single consumer (fd 0)**: `--message-stdin` and `--password-stdin` cannot both be used in one run (`secret_source_error`). In practice: + +- **Ledger accounts** confirm on the device and need no master password — fd 0 is free, so you can pipe the message via `--message-stdin`. +- **Software accounts** need `--password-stdin` for non-interactive use — the message must then go inline via `--message`. + +Watch-only accounts cannot sign (`watch_only_no_signer`). + +## Options + +| Option | Description | +|---|---| +| `--message ` | Message text to sign; exactly one of `--message` / `--message-stdin` | +| `--message-stdin` | Read the message from stdin (fd 0) | +| `--password-stdin` | Master password from stdin (software accounts) | + +Plus the [global options](../index.md#global-options-every-command). + +## Examples + +In the examples, `$PW` is your master password (from an environment variable, password manager, etc.), fed on stdin via `--password-stdin`. + +Software account — password via stdin, message inline: + +```bash +echo "$PW" | wallet-cli message sign --message "hello" --password-stdin +``` + +```console +✅ Signed + Address TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ + Signature 0x9f3c... +``` + +```bash +echo "$PW" | wallet-cli message sign --message "hello" --password-stdin -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"message.sign","data":{"address":"TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ","message":"hello","signature":"0x9f3c..."},"meta":{"durationMs":15,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +Ledger account — message via stdin, confirm on device: + +```bash +cat challenge.txt | wallet-cli message sign --message-stdin --network tron:nile +``` + +## Output + +| Field | Type | Meaning | +|---|---|---| +| `address` | string | Signer's base58 address | +| `message` | string | The message that was signed | +| `signature` | string | Signature, 0x-prefixed hex | + +## Exit status + +`0` signed · `1` execution failure (`watch_only_no_signer`, `auth_failed`; two stdin flags → `secret_source_error`) · `2` usage error (both or neither message source → `invalid_option` / `missing_option`). + +## See also + +[Security model](../../concepts/security.md) · [machine-interface → Secret handling](../../machine-interface.md#secret-handling) diff --git a/ts/docs/commands/networks.md b/ts/docs/commands/networks.md new file mode 100644 index 00000000..94295d38 --- /dev/null +++ b/ts/docs/commands/networks.md @@ -0,0 +1,54 @@ +# wallet-cli networks + +List known networks. + +## Synopsis + +``` +wallet-cli networks [options] +``` + +## Options + +[Global options](index.md) only. + +## Examples + +```bash +wallet-cli networks +``` + +```console +| Network | Family | Chain | Fee model | +| ------------ | ------ | ------- | ------------- | +| tron:mainnet | tron | mainnet | tron-resource | +| tron:nile | tron | nile | tron-resource | +| tron:shasta | tron | shasta | tron-resource | +``` + +```bash +wallet-cli networks -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"networks","data":[{"id":"tron:mainnet","family":"tron","chainId":"mainnet","feeModel":"tron-resource"},{"id":"tron:nile","family":"tron","chainId":"nile","feeModel":"tron-resource"},{"id":"tron:shasta","family":"tron","chainId":"shasta","feeModel":"tron-resource"}],"meta":{"durationMs":2,"warnings":[]}} +``` + +## Output + +`data` is an array, one entry per known network. Local command — no `chain` block. + +| Field | Type | Meaning | +|---|---|---| +| `id` | string | Canonical network id (`family:chain`) | +| `family` | string | Chain family, e.g. `tron` | +| `chainId` | string | Chain identifier within the family, e.g. `mainnet` | +| `feeModel` | string | Fee model, e.g. `tron-resource` | + +## Exit status + +`0` success · `1` execution failure · `2` usage error. See [machine-interface](../machine-interface.md). + +## See also + +[Networks concept](../concepts/networks.md) · [`config`](config.md) diff --git a/ts/docs/commands/rename.md b/ts/docs/commands/rename.md new file mode 100644 index 00000000..35f29a69 --- /dev/null +++ b/ts/docs/commands/rename.md @@ -0,0 +1,69 @@ +# wallet-cli rename + +Rename an account label. + +## Synopsis + +``` +wallet-cli rename --label [options] +``` + +## Arguments + +- `account` — accountId, current label, or address to rename + +## Options + +| Option | Description | +|---|---| +| `--label ` | new unique label, 1-64 chars [required] | + +Plus [global options](index.md). + +## Notes + +The stable handle is always the `accountId`; only the label changes. Metadata-only — no master password needed. + +## Examples + +```bash +wallet-cli rename main --label primary +``` + +```console +✅ Renamed account + Old label main + New label primary +``` + +```bash +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"},"seedId":"wlt_0y2z0gvr"},"meta":{"durationMs":14,"warnings":[]}} +``` + +## Output + +`data` is the renamed account, plus `previousLabel`. Local command — no `chain` block. + +| Field | Type | Meaning | +|---|---|---| +| `previousLabel` | string | The old label before renaming | +| `accountId` | string | Stable account id (unchanged by rename) | +| `label` | string | The new label | +| `type` | string | `seed` / `privateKey` / `watch` / `ledger` | +| `index` | number \| null | HD derivation index; `null` for non-HD accounts | +| `active` | boolean | Whether it is the active account | +| `addresses.tron` | string | Base58 TRON address | +| `seedId` | string | Owning seed wallet id (`seed` accounts only) | +| `family` | string | Chain family, e.g. `tron` (`watch` accounts only) | + +## Exit status + +`0` success · `1` execution failure · `2` usage error. See [machine-interface](../machine-interface.md). + +## See also + +[`list`](list.md) · [`use`](use.md) diff --git a/ts/docs/commands/reward/balance.md b/ts/docs/commands/reward/balance.md new file mode 100644 index 00000000..b9599959 --- /dev/null +++ b/ts/docs/commands/reward/balance.md @@ -0,0 +1,70 @@ +# wallet-cli reward balance + +Show claimable reward and withdraw status. + +## Synopsis + +``` +wallet-cli reward balance [options] +``` + +## Description + +Shows the currently claimable voting/block reward and whether it can be withdrawn now. Read-only — the "check before you claim" companion to [`reward withdraw`](withdraw.md), so you never have to probe the 24-hour limit by triggering its `withdraw_too_frequent` error. + +`Withdraw status` derives from the account's on-chain `latest_withdraw_time` + 24 h: past it (or never withdrawn) → `available now`; otherwise `available from (~relative)`. + +## Options + +No command-specific options; the [global options](../index.md#global-options-every-command) only (`--network` / `--account`). + +## Examples + +Claimable right now: + +```bash +wallet-cli reward balance --account main --network tron:nile +``` + +```console +Label main +Claimable 123.456789 TRX +Withdraw status available now +``` + +Within 24 h of the last withdrawal: + +```bash +wallet-cli reward balance --account main --network tron:nile +``` + +```console +Label main +Claimable 5.678901 TRX +Withdraw status available from 2026-07-06 09:30 (~18h) +``` + +```bash +wallet-cli reward balance --account main --network tron:nile -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"reward.balance","data":{"address":"TQk...","rewardSun":"123456789","withdrawableNow":true,"withdrawableAt":null},"meta":{"durationMs":14,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +## Output + +| Field | Type | Meaning | +|---|---|---| +| `address` | string | Queried account | +| `rewardSun` | string | Claimable reward, in SUN | +| `withdrawableNow` | boolean | Whether it can be withdrawn now | +| `withdrawableAt` | number \| null | When it becomes withdrawable (epoch ms); `null` when already withdrawable | + +## Exit status + +`0` success · `1` execution failure (`rpc_error`) · `2` usage error (`invalid_value`). + +## See also + +[`reward withdraw`](withdraw.md) · [`vote status`](../vote/status.md) diff --git a/ts/docs/commands/reward/index.md b/ts/docs/commands/reward/index.md new file mode 100644 index 00000000..8131bc04 --- /dev/null +++ b/ts/docs/commands/reward/index.md @@ -0,0 +1,22 @@ +# wallet-cli reward + +Query / withdraw voting rewards. + +Rewards accrue continuously from your votes ([`vote cast`](../vote/cast.md)) — plus block rewards if you are an SR — and can be withdrawn **at most once every 24 hours** (an on-chain rule; earlier attempts are rejected). + +## Synopsis + +``` +wallet-cli reward COMMAND +``` + +## Subcommands + +| Command | Page | Description | +|---|---|---| +| `reward balance` | [balance.md](balance.md) | Show claimable reward and withdraw status | +| `reward withdraw` | [withdraw.md](withdraw.md) | Withdraw accrued rewards to balance | + +## See also + +[`vote`](../vote/index.md) · [`stake info`](../stake/info.md) diff --git a/ts/docs/commands/reward/withdraw.md b/ts/docs/commands/reward/withdraw.md new file mode 100644 index 00000000..8a5a1bdb --- /dev/null +++ b/ts/docs/commands/reward/withdraw.md @@ -0,0 +1,86 @@ +# wallet-cli reward withdraw + +Withdraw accrued rewards to balance. + +## Synopsis + +``` +wallet-cli reward withdraw [--dry-run | --sign-only] [--wait [--wait-timeout ]] [options] +``` + +## Description + +Moves your accumulated voting rewards (plus block rewards if you are an SR) into the account's available balance. The chain allows this **at most once every 24 hours** — check first with [`reward balance`](balance.md); an early attempt fails with `withdraw_too_frequent`, and an empty balance with `no_reward`. + +`Amount` in the receipt: at the `submitted` stage it is the claimable amount read at broadcast time; the `--wait` confirmed receipt shows the actual on-chain amount (they differ only by seconds of accrual — negligible). + +**By default the command returns at submission**; `--wait` blocks until confirmed. Requires an account and the master password via `--password-stdin`; watch-only accounts fail with `watch_only_no_signer`. + +## Options + +| Option | Description | +|---|---| +| `--dry-run` | Build and estimate only, no signature/broadcast; excludes `--sign-only` | +| `--sign-only` | Sign without broadcasting; excludes `--dry-run` | +| `--wait` / `--wait-timeout ` | 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 (from an environment variable, password manager, etc.), fed on stdin via `--password-stdin`. + +Default — broadcasts and returns the **submitted** receipt: + +```bash +echo "$PW" | wallet-cli reward withdraw --network tron:nile --password-stdin +``` + +```console +⏳ Submitted — withdraw voting/block rewards + TxID a1b... + Amount 123.456789 TRX + Status pending — next withdrawal available in ~24h +! Track it: wallet-cli tx info --network tron:nile --txid a1b... +``` + +```bash +echo "$PW" | wallet-cli reward withdraw --network tron:nile --password-stdin -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"reward.withdraw","data":{"kind":"reward-withdraw","stage":"submitted","txId":"a1b...","rewardSun":"123456789"},"meta":{"durationMs":17,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +Add `--wait` to block until confirmed (adds real block / fee): + +```bash +echo "$PW" | wallet-cli reward withdraw --network tron:nile --wait --password-stdin +``` + +```console +✅ Withdrew voting/block rewards + TxID c7d... + Amount 123.456789 TRX + Block 84,121,010 + Fee 0.268 TRX + Status success — next withdrawal available in ~24h +``` + +## Output + +`data` varies by stage: + +| Stage | Fields | +|---|---| +| default (submit) | `kind: "reward-withdraw"`, `stage: "submitted"`, `txId`, `rewardSun` (string) | +| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed`, `blockNumber`, `feeSun`, `failed` | + +## Exit status + +`0` submitted · `1` execution failure (`watch_only_no_signer`, `auth_failed`, `withdraw_too_frequent` — < 24 h since last withdrawal, `no_reward` — nothing to claim) · `2` usage error. + +## See also + +[`reward balance`](balance.md) · [`vote cast`](../vote/cast.md) · [`stake withdraw`](../stake/withdraw.md) (unstaked TRX is a different command) diff --git a/ts/docs/commands/stake/cancel-unfreeze.md b/ts/docs/commands/stake/cancel-unfreeze.md new file mode 100644 index 00000000..778d1c26 --- /dev/null +++ b/ts/docs/commands/stake/cancel-unfreeze.md @@ -0,0 +1,82 @@ +# wallet-cli stake cancel-unfreeze + +Cancel all pending unstakes (roll back to frozen). + +## Synopsis + +``` +wallet-cli stake cancel-unfreeze [--dry-run | --sign-only] [--wait [--wait-timeout ]] [options] +``` + +## Description + +Cancels **every** unstake still in its waiting period and rolls those amounts back to staked — resource allowance and voting power return accordingly. It is all-or-nothing: TRON has no per-entry cancel. Any entries that have already expired are withdrawn to balance as part of the same transaction. + +**By default the command returns at submission**; `--wait` blocks until confirmed. Requires an account and the master password via `--password-stdin`; watch-only accounts fail with `watch_only_no_signer`. + +## Options + +| Option | Description | +|---|---| +| `--dry-run` | Estimate only, no signature/broadcast; excludes `--sign-only` | +| `--sign-only` | Sign without broadcasting; excludes `--dry-run` | +| `--wait` / `--wait-timeout ` | 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 (from an environment variable, password manager, etc.), fed on stdin via `--password-stdin`. + +Default — returns the **submitted** receipt: + +```bash +echo "$PW" | wallet-cli stake cancel-unfreeze --network tron:nile --password-stdin +``` + +```console +⏳ Cancelled pending unstakes + TxID 9ec... + Status pending — not yet on-chain +! Track it: wallet-cli tx info --network tron:nile --txid 9ec... +``` + +```bash +echo "$PW" | wallet-cli stake cancel-unfreeze --network tron:nile --password-stdin -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"stake.cancel-unfreeze","data":{"kind":"stake-cancel","stage":"submitted","txId":"9ec..."},"meta":{"durationMs":15,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +Add `--wait` to block until confirmed: + +```bash +echo "$PW" | wallet-cli stake cancel-unfreeze --network tron:nile --wait --password-stdin +``` + +```console +✅ Cancelled pending unstakes + TxID d3b... + Block #68,762,990 + Fee 0.25 TRX + Status success +``` + +## Output + +`data` varies by stage: + +| Stage | Fields | +|---|---| +| default (submit) | `kind: "stake-cancel"`, `stage: "submitted"`, `txId` | +| `--wait` (confirmed) | above, plus `confirmed`, `blockNumber`, `feeSun`, `failed` | + +## 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. + +## See also + +[`stake unfreeze`](unfreeze.md) · [`stake info`](info.md) diff --git a/ts/docs/commands/stake/delegate.md b/ts/docs/commands/stake/delegate.md new file mode 100644 index 00000000..faa5a328 --- /dev/null +++ b/ts/docs/commands/stake/delegate.md @@ -0,0 +1,80 @@ +# wallet-cli stake delegate + +Delegate resource to another address. + +## Synopsis + +``` +wallet-cli stake delegate --receiver
--amount-sun + [--resource energy|bandwidth] [--lock [--lock-period ]] + [--dry-run | --sign-only] [--wait [--wait-timeout ]] [options] +``` + +## Description + +Lends the resource backed by your staked TRX to another address — the receiver gets the energy/bandwidth; the TRX itself never leaves your stake. Amount is expressed as the staked-TRX backing, in SUN. The receiver must be a different address than the owner. + +`--lock` makes the delegation non-reclaimable for a period (`--lock-period` in blocks, ~3 s per block) — a guarantee for the receiver. Without it you can [`stake undelegate`](undelegate.md) any time. + +Check how much you can still delegate with [`stake delegated`](delegated.md) (`Max delegatable`). + +**By default the command returns at submission**; `--wait` blocks until confirmed. Requires an account and the master password via `--password-stdin`; watch-only accounts fail with `watch_only_no_signer`. + +## Options + +| Option | Description | +|---|---| +| `--amount-sun ` | **Required.** Staked-TRX amount backing the delegated resource, in SUN | +| `--receiver ` | **Required.** Address receiving the resource (must differ from owner) | +| `--resource ` | Resource type to delegate (default `bandwidth`) | +| `--lock` | Lock the delegation; prevents early undelegation | +| `--lock-period ` | Lock duration in blocks (~3 s/block); requires `--lock` | +| `--dry-run` | Estimate only, no signature/broadcast; excludes `--sign-only` | +| `--sign-only` | Sign without broadcasting; excludes `--dry-run` | +| `--wait` / `--wait-timeout ` | 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 (from an environment variable, password manager, etc.), fed on stdin via `--password-stdin`. + +Default — returns the **submitted** receipt: + +```bash +echo "$PW" | wallet-cli stake delegate --receiver TYzp9RbQmtAjCtyGeHb9W7GRwjDKtjUvvx --amount-sun 1000000000 --resource energy --network tron:nile --password-stdin +``` + +```console +⏳ Delegated 1,000 TRX of energy + To TYzp9RbQmtAjCtyGeHb9W7GRwjDKtjUvvx + TxID b7c... + Status pending — not yet on-chain +! Track it: wallet-cli tx info --network tron:nile --txid b7c... +``` + +```bash +echo "$PW" | wallet-cli stake delegate --receiver TYzp9RbQmtAjCtyGeHb9W7GRwjDKtjUvvx --amount-sun 1000000000 --resource energy --network tron:nile --password-stdin -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"stake.delegate","data":{"kind":"stake-delegate","stage":"submitted","txId":"b7c...","amountSun":"1000000000","resource":"energy","receiver":"TYzp9RbQmtAjCtyGeHb9W7GRwjDKtjUvvx"},"meta":{"durationMs":15,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +## Output + +`data` varies by stage: + +| Stage | Fields | +|---|---| +| default (submit) | `kind: "stake-delegate"`, `stage: "submitted"`, `txId`, `amountSun` (string), `resource`, `receiver` | +| `--wait` (confirmed) | above, plus `confirmed`, `blockNumber`, `feeSun`, `failed` | + +## 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 (`invalid_value` — receiver = owner, `--lock-period` without `--lock`). + +## See also + +[`stake undelegate`](undelegate.md) · [`stake delegated`](delegated.md) · [Energy & bandwidth](../../concepts/energy-bandwidth.md) diff --git a/ts/docs/commands/stake/delegated.md b/ts/docs/commands/stake/delegated.md new file mode 100644 index 00000000..4fd3c56a --- /dev/null +++ b/ts/docs/commands/stake/delegated.md @@ -0,0 +1,93 @@ +# wallet-cli stake delegated + +Delegation details and max delegatable size. + +## Synopsis + +``` +wallet-cli stake delegated [--direction out|in] [--resource energy|bandwidth] + [--to
] [options] +``` + +## Description + +Read-only listing of resource delegations, in either direction: `out` (default — what you delegated to others, plus **Max delegatable**, how much you can still delegate) or `in` (what others delegated to you; no max — that concept only exists outbound). `--to` narrows to one counterparty (out only). + +**The lock column flips meaning with the viewpoint.** Both directions read the same on-chain expiry field, but: + +- **out** → `Locked until`: a lock *you* set — you cannot reclaim before it expires (`not locked` when reclaimable anytime); +- **in** → `Guaranteed until`: the delegator cannot reclaim before then — your guaranteed floor (`none — reclaimable anytime` warns the resource can vanish whenever the delegator wants it back). + +json keeps the raw `lockedUntil` timestamp in both directions — no viewpoint translation at the machine layer. + +## Options + +| Option | Description | +|---|---| +| `--direction ` | `out` = delegated to others (default); `in` = delegated to me | +| `--resource ` | Filter to a single resource type (default both) | +| `--to ` | Only the delegation to this receiver (out only) | + +Plus the [global options](../index.md#global-options-every-command). + +## Examples + +Outbound (default) — includes **Max delegatable**: + +```bash +wallet-cli stake delegated --direction out --account main --network tron:nile +``` + +```console +Label main +Direction out (delegated to others) + +Max delegatable + Energy 58,500 (≈ 900 TRX) + Bandwidth 900 (≈ 300 TRX) + +Delegations (2) + Receiver Resource Amount Locked until + TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub energy 500 TRX 2026-07-08 08:00 (~3 days) + TXe4Kd8nP2rF9gH5jL3mV6cW1bN7yS0aQz bandwidth 100 TRX not locked +``` + +```bash +wallet-cli stake delegated --direction out --account main --network tron:nile -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"stake.delegated","data":{"address":"TQk...","direction":"out","canDelegateMaxSun":{"energy":"900000000","bandwidth":"300000000"},"delegations":[{"receiver":"TBy6...","resource":"energy","amountSun":"500000000","lockedUntil":1783468800000},{"receiver":"TXe4...","resource":"bandwidth","amountSun":"100000000","lockedUntil":null}]},"meta":{"durationMs":28,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +Inbound (`--direction in`) — the lock column becomes `Guaranteed until`, no Max delegatable: + +```bash +wallet-cli stake delegated --direction in --account main --network tron:nile +``` + +```console +Label main +Direction in (delegated to me) + +Delegations (1) + From Resource Amount Guaranteed until + TBy6mQ7Y3nJ8sD2fWpXk4LhVc9Ra1Zt5Ub energy 500 TRX 2026-07-08 08:00 (~3 days) +``` + +## Output + +| Field | Type | Meaning | +|---|---|---| +| `address` | string | Queried account | +| `direction` | string | `out` / `in` | +| `canDelegateMaxSun` | object | `{energy, bandwidth}` SUN strings — max still delegatable (out only) | +| `delegations[]` | array | Each: `receiver` (out) or `from` (in), `resource`, `amountSun` (string), `lockedUntil` (epoch ms or `null`) | + +## Exit status + +`0` success · `1` execution failure (`rpc_error`) · `2` usage error (`invalid_value`). + +## See also + +[`stake delegate`](delegate.md) · [`stake undelegate`](undelegate.md) · [`stake info`](info.md) diff --git a/ts/docs/commands/stake/freeze.md b/ts/docs/commands/stake/freeze.md new file mode 100644 index 00000000..18c20b74 --- /dev/null +++ b/ts/docs/commands/stake/freeze.md @@ -0,0 +1,86 @@ +# wallet-cli stake freeze + +Stake TRX for energy/bandwidth. + +## Synopsis + +``` +wallet-cli stake freeze --amount-sun [--resource energy|bandwidth] + [--dry-run | --sign-only] [--wait [--wait-timeout ]] [options] +``` + +## Description + +Stakes TRX from the active account's balance (Stake 2.0) in exchange for a steady allowance of the chosen resource — `energy` (smart-contract execution) or `bandwidth` (transaction bytes, the default). Staking also grants voting power: 1 staked TRX = 1 TP, spendable via [`vote cast`](../vote/cast.md). + +Amount is in SUN (1 TRX = 1,000,000 SUN). Staked TRX stays yours; to get it back, [`stake unfreeze`](unfreeze.md) and, after the waiting period, [`stake withdraw`](withdraw.md). + +**By default the command returns at submission**; `--wait` blocks until confirmed. Requires an account and the master password via `--password-stdin`; watch-only accounts fail with `watch_only_no_signer`. + +## Options + +| Option | Description | +|---|---| +| `--amount-sun ` | **Required.** Amount to stake, in SUN | +| `--resource ` | Resource type to obtain (default `bandwidth`) | +| `--dry-run` | Estimate only, no signature/broadcast; excludes `--sign-only` | +| `--sign-only` | Sign without broadcasting; excludes `--dry-run` | +| `--wait` / `--wait-timeout ` | 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 (from an environment variable, password manager, etc.), fed on stdin via `--password-stdin`. + +Default — stake 1,000 TRX for energy, returns the **submitted** receipt: + +```bash +echo "$PW" | wallet-cli stake freeze --amount-sun 1000000000 --resource energy --network tron:nile --password-stdin +``` + +```console +⏳ Staked 1,000 TRX for energy + TxID c3d... + Status pending — not yet on-chain +! Track it: wallet-cli tx info --network tron:nile --txid c3d... +``` + +```bash +echo "$PW" | wallet-cli stake freeze --amount-sun 1000000000 --resource energy --network tron:nile --password-stdin -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"stake.freeze","data":{"kind":"stake-freeze","stage":"submitted","txId":"c3d...","amountSun":"1000000000","resource":"energy"},"meta":{"durationMs":15,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +Add `--wait` to block until confirmed: + +```bash +echo "$PW" | wallet-cli stake freeze --amount-sun 1000000000 --resource energy --network tron:nile --wait --password-stdin +``` + +```console +✅ Staked 1,000 TRX for energy + TxID c3d... + Block #68,762,990 + Status success +``` + +## Output + +`data` varies by stage: + +| Stage | Fields | +|---|---| +| default (submit) | `kind: "stake-freeze"`, `stage: "submitted"`, `txId`, `amountSun` (string), `resource` | +| `--wait` (confirmed) | above, plus `confirmed`, `blockNumber`, `feeSun`, `failed` | + +## 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. + +## See also + +[`stake info`](info.md) · [`stake unfreeze`](unfreeze.md) · [`stake delegate`](delegate.md) · [Staking guide](../../guide/stake-and-resources.md) diff --git a/ts/docs/commands/stake/index.md b/ts/docs/commands/stake/index.md new file mode 100644 index 00000000..c0c47bf3 --- /dev/null +++ b/ts/docs/commands/stake/index.md @@ -0,0 +1,28 @@ +# wallet-cli stake + +Stake / delegate resources, and inspect staking state. + +Staking lifecycle: `freeze ──► unfreeze ──(waiting period)──► withdraw`; `cancel-unfreeze` rolls all pending unstakes back to frozen; `delegate` / `undelegate` lend resource to others / take it back. `info` and `delegated` are the read-only queries to run before operating. + +## Synopsis + +``` +wallet-cli stake COMMAND +``` + +## Subcommands + +| Command | Page | Description | +|---|---|---| +| `stake freeze` | [freeze.md](freeze.md) | Stake TRX for energy/bandwidth | +| `stake unfreeze` | [unfreeze.md](unfreeze.md) | Unstake TRX | +| `stake withdraw` | [withdraw.md](withdraw.md) | Withdraw expired unfrozen TRX | +| `stake cancel-unfreeze` | [cancel-unfreeze.md](cancel-unfreeze.md) | Cancel all pending unstakes | +| `stake delegate` | [delegate.md](delegate.md) | Delegate resource to another address | +| `stake undelegate` | [undelegate.md](undelegate.md) | Reclaim delegated resource | +| `stake info` | [info.md](info.md) | Staking & resource overview | +| `stake delegated` | [delegated.md](delegated.md) | Delegation details and max delegatable size | + +## See also + +[Staking guide](../../guide/stake-and-resources.md) · [Energy & bandwidth](../../concepts/energy-bandwidth.md) · [`vote`](../vote/index.md) diff --git a/ts/docs/commands/stake/info.md b/ts/docs/commands/stake/info.md new file mode 100644 index 00000000..90cd183f --- /dev/null +++ b/ts/docs/commands/stake/info.md @@ -0,0 +1,70 @@ +# wallet-cli stake info + +Staking & resource overview. + +## Synopsis + +``` +wallet-cli stake info [options] +``` + +## Description + +One read-only screen of the account's staking state: staked amounts, voting power (TP), energy/bandwidth usage, pending unstakes, currently withdrawable TRX, and remaining unfreeze slots. The "look before you leap" for [`stake unfreeze`](unfreeze.md) / [`stake withdraw`](withdraw.md) / [`vote cast`](../vote/cast.md). + +Reading the fields: + +- **Staked** — the parenthesis splits the staked TRX by resource direction (TRX staked toward energy vs. bandwidth) — *not* the resource units obtained. The actual allowances are the `Energy` / `Bandwidth` limits (dynamic, network-wide conversion). +- **Voting power** — same source as [`vote status`](../vote/status.md): 1 TP = 1 staked TRX. Shown here to bridge stake → vote. +- **Unfreezing** — Stake 2.0 allows max **32 concurrent pending unstakes**; `N more allowed` is the chain's remaining count. When full, withdraw expired entries before unstaking more. +- **Withdrawable** — what [`stake withdraw`](withdraw.md) would claim right now. + +## Options + +No command-specific options; the [global options](../index.md#global-options-every-command) only (`--network` / `--account`). + +## Examples + +```bash +wallet-cli stake info --account main --network tron:nile +``` + +```console +Label main +Staked 1,500 TRX (for energy 1,000 TRX + for bandwidth 500 TRX) +Voting power 1,500 TP (used 1,000 / available 500) +Energy used 12,000 / 65,000 +Bandwidth used 600 / 1,500 +Unfreezing 2 pending (max 32 at a time, 30 more allowed) + 1) 500 TRX withdrawable 2026-07-15 (in ~10 days) + 2) 300 TRX withdrawable 2026-07-16 (in ~11 days) +Withdrawable 0 TRX now +``` + +```bash +wallet-cli stake info --account main --network tron:nile -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"stake.info","data":{"address":"TQk...","staked":{"energySun":"1000000000","bandwidthSun":"500000000"},"votingPower":{"total":1500,"used":1000,"available":500},"resource":{"energy":{"used":12000,"limit":65000},"bandwidth":{"used":600,"limit":1500}},"unfreezing":[{"amountSun":"500000000","withdrawableAt":1784073600000},{"amountSun":"300000000","withdrawableAt":1784160000000}],"withdrawableSun":"0","unfreeze":{"used":2,"max":32,"remaining":30}},"meta":{"durationMs":22,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +## Output + +| Field | Type | Meaning | +|---|---|---| +| `address` | string | Queried account | +| `staked.energySun` / `.bandwidthSun` | string | Staked TRX by direction, in SUN (not resource units) | +| `votingPower.total` / `.used` / `.available` | number | TP total / spent / spendable | +| `resource.energy` / `.bandwidth` | object | `{used, limit}` in resource units | +| `unfreezing[]` | array | Pending unstakes: `{amountSun, withdrawableAt (epoch ms)}` | +| `withdrawableSun` | string | Currently withdrawable TRX, in SUN | +| `unfreeze` | object | Slot usage `{used, max, remaining}` | + +## Exit status + +`0` success · `1` execution failure (`rpc_error`) · `2` usage error (`invalid_value`). + +## See also + +[`stake delegated`](delegated.md) · [`vote status`](../vote/status.md) · [Staking guide](../../guide/stake-and-resources.md) diff --git a/ts/docs/commands/stake/undelegate.md b/ts/docs/commands/stake/undelegate.md new file mode 100644 index 00000000..618c6059 --- /dev/null +++ b/ts/docs/commands/stake/undelegate.md @@ -0,0 +1,76 @@ +# wallet-cli stake undelegate + +Reclaim delegated resource. + +## Synopsis + +``` +wallet-cli stake undelegate --receiver
--amount-sun + [--resource energy|bandwidth] + [--dry-run | --sign-only] [--wait [--wait-timeout ]] [options] +``` + +## Description + +Takes back resource you previously delegated with [`stake delegate`](delegate.md). Identify the delegation by receiver + resource type; amount is the staked-TRX backing in SUN. Locked delegations cannot be reclaimed before their lock expires — see the `Locked until` column in [`stake delegated`](delegated.md). + +Reclaiming is immediate (no waiting period — the TRX was staked all along, only the resource moves back). + +**By default the command returns at submission**; `--wait` blocks until confirmed. Requires an account and the master password via `--password-stdin`; watch-only accounts fail with `watch_only_no_signer`. + +## Options + +| Option | Description | +|---|---| +| `--amount-sun ` | **Required.** Staked-TRX amount backing the resource to reclaim, in SUN | +| `--receiver ` | **Required.** Address that previously received the delegation | +| `--resource ` | Resource type to reclaim (default `bandwidth`) | +| `--dry-run` | Estimate only, no signature/broadcast; excludes `--sign-only` | +| `--sign-only` | Sign without broadcasting; excludes `--dry-run` | +| `--wait` / `--wait-timeout ` | 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 (from an environment variable, password manager, etc.), fed on stdin via `--password-stdin`. + +Default — returns the **submitted** receipt: + +```bash +echo "$PW" | wallet-cli stake undelegate --receiver TYzp9RbQmtAjCtyGeHb9W7GRwjDKtjUvvx --amount-sun 1000000000 --resource energy --network tron:nile --password-stdin +``` + +```console +⏳ Reclaimed 1,000 TRX of energy + From TYzp9RbQmtAjCtyGeHb9W7GRwjDKtjUvvx + TxID c8d... + Status pending — not yet on-chain +! Track it: wallet-cli tx info --network tron:nile --txid c8d... +``` + +```bash +echo "$PW" | wallet-cli stake undelegate --receiver TYzp9RbQmtAjCtyGeHb9W7GRwjDKtjUvvx --amount-sun 1000000000 --resource energy --network tron:nile --password-stdin -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"stake.undelegate","data":{"kind":"stake-undelegate","stage":"submitted","txId":"c8d...","amountSun":"1000000000","resource":"energy","receiver":"TYzp9RbQmtAjCtyGeHb9W7GRwjDKtjUvvx"},"meta":{"durationMs":15,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +## Output + +`data` varies by stage: + +| Stage | Fields | +|---|---| +| default (submit) | `kind: "stake-undelegate"`, `stage: "submitted"`, `txId`, `amountSun` (string), `resource`, `receiver` | +| `--wait` (confirmed) | above, plus `confirmed`, `blockNumber`, `feeSun`, `failed` | + +## 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 (`invalid_value`). + +## See also + +[`stake delegate`](delegate.md) · [`stake delegated`](delegated.md) diff --git a/ts/docs/commands/stake/unfreeze.md b/ts/docs/commands/stake/unfreeze.md new file mode 100644 index 00000000..0f515ca7 --- /dev/null +++ b/ts/docs/commands/stake/unfreeze.md @@ -0,0 +1,86 @@ +# wallet-cli stake unfreeze + +Unstake TRX. + +## Synopsis + +``` +wallet-cli stake unfreeze --amount-sun [--resource energy|bandwidth] + [--dry-run | --sign-only] [--wait [--wait-timeout ]] [options] +``` + +## Description + +Starts unstaking: the amount leaves the staked pool and enters a **redemption waiting period** before it can be claimed with [`stake withdraw`](withdraw.md). The corresponding resource allowance and voting power (TP) drop immediately — votes backed by the unstaked TRX lapse. + +Stake 2.0 allows at most **32 pending unstakes** per account at a time; check remaining slots with [`stake info`](info.md). A pending unstake can be rolled back with [`stake cancel-unfreeze`](cancel-unfreeze.md). + +**By default the command returns at submission**; `--wait` blocks until confirmed. Requires an account and the master password via `--password-stdin`; watch-only accounts fail with `watch_only_no_signer`. + +## Options + +| Option | Description | +|---|---| +| `--amount-sun ` | **Required.** Amount to unstake, in SUN | +| `--resource ` | Resource type to release (default `bandwidth`) | +| `--dry-run` | Estimate only, no signature/broadcast; excludes `--sign-only` | +| `--sign-only` | Sign without broadcasting; excludes `--dry-run` | +| `--wait` / `--wait-timeout ` | 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 (from an environment variable, password manager, etc.), fed on stdin via `--password-stdin`. + +Default — returns the **submitted** receipt: + +```bash +echo "$PW" | wallet-cli stake unfreeze --amount-sun 1000000000 --resource energy --network tron:nile --password-stdin +``` + +```console +⏳ Unstaked 1,000 TRX + TxID d4e... + Status pending — not yet on-chain +! Track it: wallet-cli tx info --network tron:nile --txid d4e... +``` + +```bash +echo "$PW" | wallet-cli stake unfreeze --amount-sun 1000000000 --resource energy --network tron:nile --password-stdin -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"stake.unfreeze","data":{"kind":"stake-unfreeze","stage":"submitted","txId":"d4e...","amountSun":"1000000000","resource":"energy"},"meta":{"durationMs":15,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +Add `--wait` to block until confirmed: + +```bash +echo "$PW" | wallet-cli stake unfreeze --amount-sun 1000000000 --resource energy --network tron:nile --wait --password-stdin +``` + +```console +✅ Unstaked 1,000 TRX + TxID d4e... + Block #68,763,004 + Status success — withdrawable after the waiting period +``` + +## Output + +`data` varies by stage: + +| Stage | Fields | +|---|---| +| default (submit) | `kind: "stake-unfreeze"`, `stage: "submitted"`, `txId`, `amountSun` (string), `resource` | +| `--wait` (confirmed) | above, plus `confirmed`, `blockNumber`, `feeSun`, `failed` | + +## 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. + +## See also + +[`stake withdraw`](withdraw.md) · [`stake cancel-unfreeze`](cancel-unfreeze.md) · [`stake info`](info.md) diff --git a/ts/docs/commands/stake/withdraw.md b/ts/docs/commands/stake/withdraw.md new file mode 100644 index 00000000..1ec441d7 --- /dev/null +++ b/ts/docs/commands/stake/withdraw.md @@ -0,0 +1,83 @@ +# wallet-cli stake withdraw + +Withdraw expired unfrozen TRX. + +## Synopsis + +``` +wallet-cli stake withdraw [--dry-run | --sign-only] [--wait [--wait-timeout ]] [options] +``` + +## Description + +Claims every pending unstake whose waiting period has expired, moving the TRX back into the account's available balance. One call sweeps all expired entries — there is nothing to select. See what is currently withdrawable (and when the rest matures) with [`stake info`](info.md). + +Withdrawing also frees up unstake slots (max 32 pending unstakes per account). + +**By default the command returns at submission**; `--wait` blocks until confirmed. Requires an account and the master password via `--password-stdin`; watch-only accounts fail with `watch_only_no_signer`. + +## Options + +| Option | Description | +|---|---| +| `--dry-run` | Estimate only, no signature/broadcast; excludes `--sign-only` | +| `--sign-only` | Sign without broadcasting; excludes `--dry-run` | +| `--wait` / `--wait-timeout ` | 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 (from an environment variable, password manager, etc.), fed on stdin via `--password-stdin`. + +Default — returns the **submitted** receipt: + +```bash +echo "$PW" | wallet-cli stake withdraw --network tron:nile --password-stdin +``` + +```console +⏳ Withdrew expired TRX to balance + TxID e5f... + Status pending — not yet on-chain +! Track it: wallet-cli tx info --network tron:nile --txid e5f... +``` + +```bash +echo "$PW" | wallet-cli stake withdraw --network tron:nile --password-stdin -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"stake.withdraw","data":{"kind":"stake-withdraw","stage":"submitted","txId":"e5f..."},"meta":{"durationMs":15,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +Add `--wait` to block until confirmed: + +```bash +echo "$PW" | wallet-cli stake withdraw --network tron:nile --wait --password-stdin +``` + +```console +✅ Withdrew expired TRX to balance + TxID e5f... + Block #68,763,120 + Status success +``` + +## Output + +`data` varies by stage: + +| Stage | Fields | +|---|---| +| default (submit) | `kind: "stake-withdraw"`, `stage: "submitted"`, `txId` | +| `--wait` (confirmed) | above, plus `confirmed`, `blockNumber`, `feeSun`, `failed` | + +## 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. + +## See also + +[`stake unfreeze`](unfreeze.md) · [`stake info`](info.md) · [`reward withdraw`](../reward/withdraw.md) (voting rewards are a separate command) diff --git a/ts/docs/commands/token/add.md b/ts/docs/commands/token/add.md new file mode 100644 index 00000000..4d214bb5 --- /dev/null +++ b/ts/docs/commands/token/add.md @@ -0,0 +1,66 @@ +# wallet-cli token add + +Add a token to the address book (fetches symbol/decimals). + +## Synopsis + +``` +wallet-cli token add (--contract
| --asset-id ) [options] +``` + +## Description + +Fetches the token's symbol and decimals from the chain and adds it to the local token address book. The book is scoped to **network + account**: a token added on `tron:nile` for one account does not appear for other networks or accounts. + +Once added, the token can be used by symbol elsewhere — e.g. `tx send --token USDT`. The book has two layers: **official** (bundled, read-only) and **user** (the ones you add). If the token is already bundled in the official layer, it fails with `token_already_listed` (no need to add it again); if you have already added it before, adding it again does not error — it re-fetches the token's metadata (symbol/decimals/name) and updates it, returning `action: refreshed`. + +## Options + +| Option | Description | +|---|---| +| `--contract ` | TRC20 contract address; exactly one of `--contract` / `--asset-id` | +| `--asset-id ` | TRC10 numeric asset id; exactly one of `--asset-id` / `--contract` | + +Plus the [global options](../index.md#global-options-every-command). + +## Examples + +```bash +wallet-cli token add --contract TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf --network tron:nile +``` + +```console +✅ Added to token book + Name Tether USD + Symbol USDT + Decimals 6 +``` + +```bash +wallet-cli token add --contract TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf --network tron:nile -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"token.add","data":{"network":"tron:nile","account":"wlt_b2.0","action":"added","token":{"kind":"trc20","id":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf","symbol":"USDT","decimals":6,"name":"Tether USD"}},"meta":{"durationMs":15,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +## Output + +| Field | Type | Meaning | +|---|---|---| +| `network` | string | Network the entry is scoped to | +| `account` | string | Account the entry is scoped to | +| `action` | string | `"added"` (first time) / `"refreshed"` (already in user layer, metadata refreshed) | +| `token.kind` | string | `trc20` / `trc10` | +| `token.id` | string | Contract address or asset id | +| `token.symbol` | string | Fetched symbol | +| `token.decimals` | number | Fetched decimals | +| `token.name` | string | Fetched name | + +## 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`). + +## See also + +[`token list`](list.md) · [`token remove`](remove.md) · [`tx send`](../tx/send.md) diff --git a/ts/docs/commands/token/balance.md b/ts/docs/commands/token/balance.md new file mode 100644 index 00000000..4dbce7e3 --- /dev/null +++ b/ts/docs/commands/token/balance.md @@ -0,0 +1,60 @@ +# wallet-cli token balance + +Show a single token balance (TRC20 or TRC10). + +## Synopsis + +``` +wallet-cli token balance (--contract
| --asset-id ) [options] +``` + +## Description + +Queries one token balance for the active account (or `--account`). Pass exactly one selector: `--contract` for a TRC20 token, `--asset-id` for a TRC10 asset. Read-only — no password, nothing is signed. + +## Options + +| Option | Description | +|---|---| +| `--contract ` | TRC20 contract address; exactly one of `--contract` / `--asset-id` | +| `--asset-id ` | TRC10 numeric asset id; exactly one of `--asset-id` / `--contract` | + +Plus the [global options](../index.md#global-options-every-command). + +## Examples + +```bash +wallet-cli token balance --contract TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf --network tron:nile +``` + +```console +Label main +Symbol USDT +Balance 1,204.56 +``` + +```bash +wallet-cli token balance --contract TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf --network tron:nile -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"token.balance","data":{"address":"TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ","token":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf","balance":"1204560000","symbol":"USDT","decimals":6},"meta":{"durationMs":15,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +## Output + +| Field | Type | Meaning | +|---|---|---| +| `address` | string | Queried account (base58) | +| `token` | string | Contract address (TRC20) or asset id (TRC10) | +| `balance` | string | Raw balance in token base units (`"1204560000"` ÷ 10^`decimals`) | +| `symbol` | string | Token symbol | +| `decimals` | number | Token decimals | + +## Exit status + +`0` success · `1` execution failure (`rpc_error`, `timeout`) · `2` usage error (`invalid_value` — missing or conflicting selector). + +## See also + +[`token info`](info.md) · [`account portfolio`](../account/portfolio.md) · [`tx send`](../tx/send.md) diff --git a/ts/docs/commands/token/index.md b/ts/docs/commands/token/index.md new file mode 100644 index 00000000..7d1e9dc9 --- /dev/null +++ b/ts/docs/commands/token/index.md @@ -0,0 +1,23 @@ +# wallet-cli token + +Manage the token address book and query tokens. + +## Synopsis + +``` +wallet-cli token COMMAND +``` + +## Subcommands + +| Command | Page | Description | +|---|---|---| +| `token balance` | [balance.md](balance.md) | Show a single token balance (--contract / --asset-id) | +| `token info` | [info.md](info.md) | Show token metadata (name/symbol/decimals/totalSupply) | +| `token add` | [add.md](add.md) | Add a token to the address book (fetches symbol/decimals) | +| `token list` | [list.md](list.md) | List the address book (official + user) | +| `token remove` | [remove.md](remove.md) | Remove a user-added token | + +## See also + +[Sending tokens](../../guide/send-tokens.md) · [`tx send`](../tx/send.md) diff --git a/ts/docs/commands/token/info.md b/ts/docs/commands/token/info.md new file mode 100644 index 00000000..17fb90f4 --- /dev/null +++ b/ts/docs/commands/token/info.md @@ -0,0 +1,60 @@ +# wallet-cli token info + +Show token metadata (name / symbol / decimals / totalSupply). + +## Synopsis + +``` +wallet-cli token info (--contract
| --asset-id ) [options] +``` + +## Description + +Fetches a token's metadata straight from the chain — a pure RPC read that never touches your accounts. Pass exactly one selector: `--contract` for TRC20, `--asset-id` for TRC10. + +## Options + +| Option | Description | +|---|---| +| `--contract ` | TRC20 contract address; exactly one of `--contract` / `--asset-id` | +| `--asset-id ` | TRC10 numeric asset id; exactly one of `--asset-id` / `--contract` | + +Plus the [global options](../index.md#global-options-every-command). + +## Examples + +```bash +wallet-cli token info --contract TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf --network tron:nile +``` + +```console +Name Tether USD +Symbol USDT +Decimals 6 +``` + +```bash +wallet-cli token info --contract TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf --network tron:nile -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"token.info","data":{"contract":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf","name":"Tether USD","symbol":"USDT","decimals":6,"totalSupply":"17600000000030000000"},"meta":{"durationMs":15,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +## Output + +| Field | Type | Meaning | +|---|---|---| +| `contract` | string | TRC20 contract address (or `assetId` for TRC10) | +| `name` | string | Token name | +| `symbol` | string | Token symbol | +| `decimals` | number | Token decimals | +| `totalSupply` | string | Total supply, raw integer in base units | + +## Exit status + +`0` success · `1` execution failure (`token_metadata_unavailable` — the contract does not expose ERC20-style metadata; `rpc_error`) · `2` usage error (`invalid_value`). + +## See also + +[`token add`](add.md) · [`token balance`](balance.md) · [`contract info`](../contract/info.md) diff --git a/ts/docs/commands/token/list.md b/ts/docs/commands/token/list.md new file mode 100644 index 00000000..e9544e28 --- /dev/null +++ b/ts/docs/commands/token/list.md @@ -0,0 +1,60 @@ +# wallet-cli token list + +List the token address book (official + user). + +## Synopsis + +``` +wallet-cli token list [options] +``` + +## Description + +Lists every token visible to the active account (or `--account`) on the selected network: the bundled **official** layer plus your **user** additions. The `source` column tells them apart. These are the symbols `tx send --token ` resolves against. Read-only, local + metadata only — no password. + +## Options + +No command-specific options; the [global options](../index.md#global-options-every-command) only (`--network` / `--account` set the book's scope). + +## Examples + +```bash +wallet-cli token list --network tron:nile +``` + +```console +| Symbol | Name | Source | Contract / ID | +| ------ | ---------- | ------ | ---------------------------------- | +| USDT | Tether USD | user | TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf | +``` + +> The `official` layer is only bundled on **mainnet** (e.g. USDT, USDC); testnets have no official layer, so everything listed is a `user` entry you added with `token add`. + +```bash +wallet-cli token list --network tron:nile -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"token.list","data":{"network":"tron:nile","account":"wlt_b2.0","tokens":[{"kind":"trc20","id":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf","symbol":"USDT","decimals":6,"name":"Tether USD","source":"user"}]},"meta":{"durationMs":13,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +## Output + +`data`: `network`, `account`, and `tokens[]` — one entry per token: + +| Field | Type | Meaning | +|---|---|---| +| `kind` | string | `trc20` / `trc10` | +| `id` | string | Contract address or asset id | +| `symbol` | string | Token symbol (used by `tx send --token`) | +| `decimals` | number | Token decimals | +| `name` | string | Token name | +| `source` | string | `official` (bundled) / `user` (added by you) | + +## Exit status + +`0` success · `1` execution failure · `2` usage error. + +## See also + +[`token add`](add.md) · [`token remove`](remove.md) · [Sending tokens](../../guide/send-tokens.md) diff --git a/ts/docs/commands/token/remove.md b/ts/docs/commands/token/remove.md new file mode 100644 index 00000000..2e006b52 --- /dev/null +++ b/ts/docs/commands/token/remove.md @@ -0,0 +1,60 @@ +# wallet-cli token remove + +Remove a user-added token from the address book. + +## Synopsis + +``` +wallet-cli token remove (--contract
| --asset-id ) [options] +``` + +## Description + +Removes a token you added from the user layer of the address book (same network + account scope as [`token add`](add.md)). Official-layer tokens cannot be removed — trying returns `token_is_official`. + +Purely local — the token and your balance on-chain are unaffected; only the local symbol mapping goes away. + +## Options + +| Option | Description | +|---|---| +| `--contract ` | TRC20 contract address to remove; exactly one of `--contract` / `--asset-id` | +| `--asset-id ` | TRC10 numeric asset id to remove; exactly one of `--asset-id` / `--contract` | + +Plus the [global options](../index.md#global-options-every-command). + +## Examples + +```bash +wallet-cli token remove --contract TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf --network tron:nile +``` + +```console +✅ Removed from token book + Name Tether USD + Symbol USDT +``` + +```bash +wallet-cli token remove --contract TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf --network tron:nile -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"token.remove","data":{"network":"tron:nile","account":"wlt_b2.0","removed":{"kind":"trc20","id":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf","symbol":"USDT","decimals":6,"name":"Tether USD"}},"meta":{"durationMs":15,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +## Output + +| Field | Type | Meaning | +|---|---|---| +| `network` | string | Network the entry was scoped to | +| `account` | string | Account the entry was scoped to | +| `removed` | object | The deleted token entry (`kind`, `id`, `symbol`, `decimals`, `name`) | + +## 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`). + +## See also + +[`token add`](add.md) · [`token list`](list.md) diff --git a/ts/docs/commands/tx/broadcast.md b/ts/docs/commands/tx/broadcast.md new file mode 100644 index 00000000..f4fd1ca6 --- /dev/null +++ b/ts/docs/commands/tx/broadcast.md @@ -0,0 +1,75 @@ +# wallet-cli tx broadcast + +Broadcast a presigned transaction. + +## Synopsis + +``` +wallet-cli tx broadcast (--transaction | --tx-stdin) --network [options] +``` + +## Description + +Submits a transaction that was signed elsewhere — typically the `data.signed` object from [`tx send --sign-only`](send.md) on an offline or key-holding machine. No wallet unlock is needed; the transaction is already signed. + +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). Exactly one of `--transaction` / `--tx-stdin`. + +## Options + +| Option | Description | +|---|---| +| `--transaction ` | Signed TRON transaction JSON inline | +| `--tx-stdin` | Read the signed transaction JSON from stdin (fd 0) | +| `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default 60000) | + +Plus the [global options](../index.md#global-options-every-command). + +## Examples + +Two-machine flow: + +```bash +# Signer (offline / key-holding): --sign-only emits the signed tx under data.signed +wallet-cli tx send --to T... --amount 1 --network tron:nile --sign-only -o json + +# Take the data.signed object from that output, save it as signed.json, copy to the broadcaster + +# Broadcaster: read from stdin and broadcast +wallet-cli tx broadcast --tx-stdin --network tron:nile < signed.json +``` + +Broadcast receipt (text and json): + +```bash +wallet-cli tx broadcast --tx-stdin --network tron:nile < signed.json +``` + +```console +⏳ Broadcast + TxID 72a315303323125708f426c77b94c5215afd8964ed27d67e49c29b56e29078f5 + Status pending — not yet on-chain +! Track it: wallet-cli tx info --network tron:nile --txid 72a315303323125708f426c77b94c5215afd8964ed27d67e49c29b56e29078f5 +``` + +```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"}} +``` + +## Output + +`data` varies by stage: + +| Stage | Fields | +|---|---| +| default (submit) | `kind`, `stage: "submitted"`, `txId` | +| `--wait` (confirmed/failed) | above, plus `confirmed`, `blockNumber`, `failed`, and result fields | + +As with `tx send`, the default return point is **submission** — confirm via `--wait` or [`tx status`](status.md). + +## Exit status + +`0` submitted · `1` execution failure (node rejected the tx, timeout) · `2` usage error (both/neither transaction sources). + +## See also + +[`tx send --sign-only`](send.md) · [`tx status`](status.md) · [Scripting guide](../../guide/scripting.md#sign-here-broadcast-there) diff --git a/ts/docs/commands/tx/index.md b/ts/docs/commands/tx/index.md new file mode 100644 index 00000000..969fb1c2 --- /dev/null +++ b/ts/docs/commands/tx/index.md @@ -0,0 +1,33 @@ +# wallet-cli tx + +Build, send, broadcast, and inspect transactions. + +## Synopsis + +``` +wallet-cli tx COMMAND +``` + +## Subcommands + +| Command | Description | +|---|---| +| [`tx send`](send.md) | Send native TRX or TRC20/TRC10 tokens with human `--amount` | +| [`tx broadcast`](broadcast.md) | Broadcast a presigned transaction | +| [`tx status`](status.md) | Show confirmation status of a transaction | +| [`tx info`](info.md) | Show full transaction detail + receipt | + +## The transaction lifecycle + +``` +build ──sign──> submit ──solidify──> 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). + +## See also + +[`account history`](../account/index.md) · [Networks & fees](../../concepts/networks.md) · [Scripting guide](../../guide/scripting.md) diff --git a/ts/docs/commands/tx/info.md b/ts/docs/commands/tx/info.md new file mode 100644 index 00000000..fc24d207 --- /dev/null +++ b/ts/docs/commands/tx/info.md @@ -0,0 +1,74 @@ +# wallet-cli tx info + +Show full transaction detail + receipt. + +## Synopsis + +``` +wallet-cli tx info --txid [options] +``` + +## Description + +Fetches the complete transaction object and its execution receipt (resource consumption, contract result). Use this for forensics and fee analysis; for a simple "did it land?" check, [`tx status`](status.md) is cheaper — its four state values are stable, so you can program against them. + +Note the failure-mode difference: where `tx status` answers `not_found` with exit 0, `tx info` on an unknown txid is a plain **error** (`rpc_error`, exit 1) — there is no detail to show (see the examples below). + +## Options + +| Option | Description | +|---|---| +| `--txid ` | **Required.** TRON transaction id/hash | + +Plus the [global options](../index.md#global-options-every-command). + +## Examples + +```bash +wallet-cli tx info --txid 52332505ab6b605aff626aaef2b07f3718d4bac8f45cdab1c0ea9465eb98e065 --network tron:nile +``` + +```console +TxID 52332505ab6b605aff626aaef2b07f3718d4bac8f45cdab1c0ea9465eb98e065 +From TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ +To TGkbaCYB4kRBc3Q6wjqkACefUvRwf2KzkH +Amount 1 TRX +Status SUCCESS +Block #69,084,269 +``` + +`-o json` returns the full detail (`transaction` is the raw tx, `info` is the receipt; elided as `{…}` here): + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"tx.info","data":{"txid":"52332505ab6b605aff626aaef2b07f3718d4bac8f45cdab1c0ea9465eb98e065","from":"TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ","to":"TGkbaCYB4kRBc3Q6wjqkACefUvRwf2KzkH","amount":"1","symbol":"TRX","status":"SUCCESS","blockNumber":69084269,"transaction":{…},"info":{…}},"meta":{"durationMs":1396,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +An unknown txid errors out (`rpc_error`, exit 1) — unlike `tx status`'s `not_found` (exit 0): + +```json +{"schema":"wallet-cli.result.v1","success":false,"command":"tx.info","error":{"code":"rpc_error","message":"TRON getTransaction failed: Transaction not found"},"meta":{"durationMs":1033,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +## Output + +`data` is structured transaction detail: a human-readable summary at the top level, `transaction` holds the raw tx object, `info` holds the execution receipt. Shapes follow the node's transaction model; only the fields listed in [machine-interface](../../machine-interface.md) are guaranteed stable, the rest may vary with the node model. + +| Field | Type | Meaning | +|---|---|---| +| `txid` | string | Transaction id | +| `from` | string | Sender address | +| `to` | string | Recipient address | +| `amount` | string | Transfer amount (human units) | +| `symbol` | string | Asset symbol (e.g. `TRX`) | +| `status` | string | Execution result (e.g. `SUCCESS`) | +| `blockNumber` | number | Block height | +| `transaction` | object | Raw TRON transaction object (`raw_data`, `signature`, `txID`, …) | +| `info` | object | Execution receipt (`receipt` resource usage, `contractResult`, `blockTimeStamp`, …) | + +## Exit status + +`0` found · `1` execution failure — including *not found* (`rpc_error`) · `2` usage error. + +## See also + +[`tx status`](status.md) · [`account history`](../account/history.md) · [Fees & resources](../../concepts/networks.md#fees-the-tron-resource-model) diff --git a/ts/docs/commands/tx/send.md b/ts/docs/commands/tx/send.md new file mode 100644 index 00000000..63e44db9 --- /dev/null +++ b/ts/docs/commands/tx/send.md @@ -0,0 +1,99 @@ +# wallet-cli tx send + +Send native TRX or TRC20/TRC10 tokens with human `--amount`. + +## Synopsis + +``` +wallet-cli tx send --to
(--amount | --raw-amount ) + [--token | --contract
| --asset-id ] + [--dry-run | --sign-only] [--fee-limit ] [options] +``` + +## Description + +Builds, signs, and submits a transfer from the active account (or `--account`). What is sent depends on which selector you pass: + +- **none** → native TRX; +- `--token ` → token resolved from the local address book; +- `--contract
` → TRC20 by contract address; +- `--asset-id ` → TRC10 by numeric asset id. + +Amounts: `--amount` is human units (TRX, or token units respecting the token's decimals); `--raw-amount` is the raw integer (SUN or token base units). Exactly one of the two. + +Two early exits: `--dry-run` builds and estimates only — no signature, no broadcast, nothing leaves your machine; `--sign-only` signs and prints the transaction for a later [`tx broadcast`](broadcast.md). + +**By default the command returns at submission** (`stage: "submitted"`), not confirmation — add `--wait` to block until confirmed/failed, or poll [`tx status`](status.md). + +Requires an account and the master password via `--password-stdin` — signing commands do not show an interactive prompt, so without it the command fails with `auth_required`. + +## Options + +| Option | Description | +|---|---| +| `--to ` | **Required.** Recipient TRON base58 address | +| `--amount ` | Human amount; mutually exclusive with `--raw-amount` | +| `--raw-amount ` | Raw integer amount in SUN / token base units | +| `--token ` | Token symbol from the address book; excludes `--contract`, `--asset-id` | +| `--contract ` | TRC20 contract address | +| `--asset-id ` | TRC10 numeric asset id | +| `--fee-limit ` | Max TRX energy fee to burn for TRC20 transfers, in SUN (default 100000000) | +| `--dry-run` | Build and estimate only; excludes `--sign-only` | +| `--sign-only` | Sign without broadcasting; excludes `--dry-run` | +| `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default 60000; on cap returns the submitted receipt) | +| `--password-stdin` | Master password from stdin | + +Plus the [global options](../index.md#global-options-every-command). + +## Examples + +> **Password**: except for `--dry-run`, the examples below omit the password to keep the focus on the selector flags. A real send needs the master password on stdin — prefix with `printf '%s' "$PW" |` and append `--password-stdin` (see the description above). + +```bash +# 1 TRX on Nile +wallet-cli tx send --to TSx72ViULFepRGCS4PM5dP4FqD1d8qggCc --amount 1 --network tron:nile + +# TRC20 by address-book symbol; TRC10 by asset id +wallet-cli tx send --to T... --token USDT --amount 5 --network tron:nile +wallet-cli tx send --to T... --asset-id 1002000 --raw-amount 1000000 --network tron:nile + +# rehearse without signing +wallet-cli tx send --to TSx72ViULFepRGCS4PM5dP4FqD1d8qggCc --amount 1 --network tron:nile --dry-run -o json +``` + +Submit receipt (default mode, text and json): + +```bash +printf '%s' "$PW" | wallet-cli tx send --to TGkbaCYB4kRBc3Q6wjqkACefUvRwf2KzkH --amount 1 --network tron:nile --password-stdin +``` + +```console +⏳ Sent 1 TRX + To TGkbaCYB4kRBc3Q6wjqkACefUvRwf2KzkH + TxID 4574b646adc694e99a1f64e548b2bdf9da62621c2d833f77354f67b751fbd0c4 + Status pending — not yet on-chain +! Track it: wallet-cli tx info --network tron:nile --txid 4574b646adc694e99a1f64e548b2bdf9da62621c2d833f77354f67b751fbd0c4 +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"tx.send","data":{"kind":"send","stage":"submitted","txId":"4574b646adc694e99a1f64e548b2bdf9da62621c2d833f77354f67b751fbd0c4","rawAmount":"1000000","to":"TGkbaCYB4kRBc3Q6wjqkACefUvRwf2KzkH"},"meta":{"durationMs":2172,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +## Output + +`data` varies by mode: + +| Mode | Fields | +|---|---| +| default (submit) | `kind: "send"`, `stage: "submitted"`, `txId`, `rawAmount` (string), `to` | +| `--wait` (confirmed) | the above, but `stage: "confirmed"`, plus `confirmed`, `blockNumber`, `netUsed` (bandwidth used) or `feeSun` (fee burned), `failed` | +| `--dry-run` | `kind`, `mode: "dry-run"`, `fee` (`feeModel`, e.g. `bandwidthBurnSunIfNoFreeze`), unsigned `tx` (TRON tx object incl. `txID`, `raw_data`), `rawAmount`, `to` | +| `--sign-only` | `kind`, `mode: "sign-only"`, `signed` (full signed TRON tx incl. `signature[]` — feed to `tx broadcast`), `fee`, `rawAmount`, `to` | + +## Exit status + +`0` submitted (or built/signed in early-exit modes) · `1` execution failure (`rpc_error`, `timeout` — **on timeout the tx may still be in flight; check `tx status` before resending**) · `2` usage error (conflicting selectors/amounts/modes). + +## See also + +[`tx status`](status.md) · [`tx broadcast`](broadcast.md) · [Fees & resources](../../concepts/networks.md#fees-the-tron-resource-model) · [Script safety](../../machine-interface.md#script-safety-never-mistake-submitted-for-confirmed) diff --git a/ts/docs/commands/tx/status.md b/ts/docs/commands/tx/status.md new file mode 100644 index 00000000..8b306447 --- /dev/null +++ b/ts/docs/commands/tx/status.md @@ -0,0 +1,66 @@ +# wallet-cli tx status + +Show confirmation status of a transaction. + +## Synopsis + +``` +wallet-cli tx status --txid [options] +``` + +## Description + +Reports which step a transaction is at, using **four states**. After sending, scripts and agents poll it to learn whether the tx made it on-chain and succeeded. These four state values are **stable — they won't be renamed or dropped across versions** — so you can program against them (see the `wallet-cli.result.v1` output contract in [machine-interface](../../machine-interface.md)). + +| `data.state` | Meaning | Terminal? | +|---|---|---| +| `confirmed` | Solidified on chain; `blockNumber` present | yes | +| `failed` | Included and reverted / rejected | yes | +| `pending` | Seen by the node, not yet solidified | no — keep polling | +| `not_found` | Unknown to the queried node (wrong network? not propagated yet?) | no — poll within your own deadline | + +## Options + +| Option | Description | +|---|---| +| `--txid ` | **Required.** TRON transaction id/hash | + +Plus the [global options](../index.md#global-options-every-command). + +## Examples + +```bash +wallet-cli tx status --txid 7d9b6a08505537f7fd51ed4fb4223ce89098403d26e8d3fe07bdb3d625a46364 --network tron:nile +``` + +```console +TxID 7d9b6a08505537f7fd51ed4fb4223ce89098403d26e8d3fe07bdb3d625a46364 +Status confirmed ✅ +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"tx.status","data":{"txid":"7d9b6a08505537f7fd51ed4fb4223ce89098403d26e8d3fe07bdb3d625a46364","state":"confirmed","confirmed":true,"failed":false,"blockNumber":68822193},"meta":{"durationMs":1006,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +An unknown txid is a **success** with `state: "not_found"` (exit 0) — the query worked; the answer is "not there": + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"tx.status","data":{"txid":"0000…0000","state":"not_found","confirmed":false,"failed":false},"meta":{"durationMs":1022,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +## Output + +| Field | Type | Meaning | +|---|---|---| +| `txid` | string | Echo of the queried id | +| `state` | string | `confirmed` / `failed` / `pending` / `not_found` | +| `confirmed` / `failed` | boolean | Direct-branch conveniences mirroring `state` | +| `blockNumber` | number | Present when confirmed | + +## Exit status + +`0` query answered (including `not_found`) · `1` execution failure (node unreachable, timeout) · `2` usage error. + +## See also + +[`tx info`](info.md) — full detail + receipt · [`tx send`](send.md) · [Script safety](../../machine-interface.md#script-safety-never-mistake-submitted-for-confirmed) diff --git a/ts/docs/commands/use.md b/ts/docs/commands/use.md new file mode 100644 index 00000000..e6783d7e --- /dev/null +++ b/ts/docs/commands/use.md @@ -0,0 +1,62 @@ +# wallet-cli use + +Set the active account. + +## Synopsis + +``` +wallet-cli use [options] +``` + +## Arguments + +- `account` — accountId, label, or address to make active + +## Options + +[Global options](index.md) only. + +## Examples + +```bash +wallet-cli use main-1 +``` + +```console +✅ Active account: main-1 + TRON address TRs9HgTuY3dT3yDasdFdP9WQHqL37891Ax +``` + +You can also select by accountId or address: `wallet-cli use wlt_758891fa.1` / `wallet-cli use TRs9Hg…`. + +```bash +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"},"seedId":"wlt_758891fa"},"meta":{"durationMs":14,"warnings":[]}} +``` + +## Output + +`data` is the account switched to, plus `previous` (the account that was active before). Local command — no `chain` block. + +| Field | Type | Meaning | +|---|---|---| +| `previous` | string | Account id that was active before | +| `accountId` | string | Now-active account id | +| `label` | string | Account label | +| `type` | string | `seed` / `privateKey` / `watch` / `ledger` | +| `index` | number \| null | HD derivation index; `null` for non-HD accounts | +| `active` | boolean | Always `true` (just made active) | +| `addresses.tron` | string | Base58 TRON address | +| `seedId` | string | Owning seed wallet id (`seed` accounts only) | +| `family` | string | Chain family, e.g. `tron` (`watch` accounts only) | + +## Exit status + +`0` success · `1` execution failure · `2` usage error. See [machine-interface](../machine-interface.md). + +## See also + +[`current`](current.md) · [`list`](list.md) diff --git a/ts/docs/commands/vote/cast.md b/ts/docs/commands/vote/cast.md new file mode 100644 index 00000000..a45c0939 --- /dev/null +++ b/ts/docs/commands/vote/cast.md @@ -0,0 +1,93 @@ +# wallet-cli vote cast + +Cast or replace your full vote allocation. + +## Synopsis + +``` +wallet-cli vote cast --for ... [--dry-run | --sign-only] + [--wait [--wait-timeout ]] [options] +``` + +## Description + +Submits your **complete** voting distribution — this is TRON's on-chain semantics, not a CLI choice: the set of `--for` entries you pass *replaces* all prior votes, and any SR not listed drops to zero. To change votes, just send a new `vote cast`; there is no un-vote step. + +Two hard rules from the chain: + +- **Total votes ≥ 1** — you cannot vote everything down to zero. To stop voting entirely, unstake the backing TRX ([`stake unfreeze`](../stake/unfreeze.md)); TP falls and the votes lapse. +- **At most 30 entries per transaction** (java-tron `MAX_VOTE_NUMBER`). Since a cast is the full distribution, an account holds votes on at most 30 SRs — only 27 are ever elected, so normal voting never hits this. + +Votes take effect at the next maintenance cycle (~6 h). Each vote uses 1 TP (it is allocated, not spent — re-casting or unstaking frees it); available TP = staked TRX minus votes already placed ([`vote status`](status.md)). + +**By default the command returns at submission** (`stage: "submitted"`), not confirmation — add `--wait` to block until confirmed/failed. Requires an account and the master password via `--password-stdin`; watch-only accounts fail with `watch_only_no_signer`. + +## Options + +| Option | Description | +|---|---| +| `--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` | +| `--sign-only` | Sign without broadcasting (feed to [`tx broadcast`](../tx/broadcast.md)); excludes `--dry-run` | +| `--wait` / `--wait-timeout ` | Poll after broadcast until confirmed/failed (cap default: config `waitTimeoutMs`, built-in 60000) | +| `--password-stdin` | Master password from stdin (fd 0) | + +Plus the [global options](../index.md#global-options-every-command). + +## Examples + +In the examples, `$PW` is your master password (from an environment variable, password manager, etc.), fed on stdin via `--password-stdin`. + +Default — broadcasts and returns the **submitted** receipt without waiting: + +```bash +echo "$PW" | wallet-cli vote cast --for TZ4...=600 --for TT5...=400 --network tron:nile --password-stdin +``` + +```console +⏳ Submitted — vote 1,000 TP across 2 SRs + TxID e5f... + Votes TZ4...=600, TT5...=400 + Status pending — tallied at next maintenance cycle (~6h) +! Track it: wallet-cli tx info --network tron:nile --txid e5f... +``` + +```bash +echo "$PW" | wallet-cli vote cast --for TZ4...=600 --for TT5...=400 --network tron:nile --password-stdin -o json +``` + +```json +{"schema":"wallet-cli.result.v1","success":true,"command":"vote.cast","data":{"kind":"vote-cast","stage":"submitted","txId":"e5f...","votes":[{"witness":"TZ4...","count":600},{"witness":"TT5...","count":400}],"totalVotes":1000},"meta":{"durationMs":18,"warnings":[]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +Add `--wait` to block until the vote is confirmed on chain (adds real block / fee): + +```bash +echo "$PW" | wallet-cli vote cast --for TZ4...=600 --for TT5...=400 --network tron:nile --wait --password-stdin +``` + +```console +✅ Voted 1,000 TP across 2 SRs + TxID f8a... + Votes TZ4...=600, TT5...=400 + Block 84,121,055 + Fee 0 TRX + Status success — tallied at next maintenance cycle (~6h) +``` + +## Output + +`data` varies by stage: + +| Stage | Fields | +|---|---| +| default (submit) | `kind: "vote-cast"`, `stage: "submitted"`, `txId`, `votes[]` (`witness`, `count`), `totalVotes` | +| `--wait` (confirmed) | above, plus `stage: "confirmed"`, `confirmed` (boolean), `blockNumber`, `feeSun`, `failed` | + +## 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). + +## See also + +[`vote status`](status.md) · [`vote list`](list.md) · [`reward withdraw`](../reward/withdraw.md) · [`stake freeze`](../stake/freeze.md) · [Script safety](../../machine-interface.md#script-safety-never-mistake-submitted-for-confirmed) diff --git a/ts/docs/commands/vote/index.md b/ts/docs/commands/vote/index.md new file mode 100644 index 00000000..26380474 --- /dev/null +++ b/ts/docs/commands/vote/index.md @@ -0,0 +1,23 @@ +# wallet-cli vote + +Vote for super representatives (SR). + +Voting spends **Tron Power (TP)**: 1 TP = 1 staked TRX ([`stake freeze`](../stake/freeze.md)). Votes are tallied at the next maintenance cycle (~6 h) and then earn rewards continuously — query and claim them with [`reward`](../reward/index.md). + +## Synopsis + +``` +wallet-cli vote COMMAND +``` + +## Subcommands + +| Command | Page | Description | +|---|---|---| +| `vote cast` | [cast.md](cast.md) | Cast/replace your full vote allocation | +| `vote list` | [list.md](list.md) | List super representatives and candidates | +| `vote status` | [status.md](status.md) | Your current votes, voting power, and reward overview | + +## See also + +[`reward`](../reward/index.md) · [`stake info`](../stake/info.md) · [Staking guide](../../guide/stake-and-resources.md) diff --git a/ts/docs/commands/vote/list.md b/ts/docs/commands/vote/list.md new file mode 100644 index 00000000..6340fd62 --- /dev/null +++ b/ts/docs/commands/vote/list.md @@ -0,0 +1,71 @@ +# wallet-cli vote list + +List super representatives and candidates. + +## Synopsis + +``` +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. + +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`). +- **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. + +## Options + +| Option | Description | +|---|---| +| `--limit ` | Max ranks to return (default 27, max 127). By default only the 27 elected SRs are listed, so a higher limit has no effect unless you also pass `--candidates` | +| `--candidates` | Also list non-elected candidates (ranks 28+), so `--limit` can reach beyond 27 up to 127 | + +Plus the [global options](../index.md#global-options-every-command). + +## Examples + +```bash +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 +``` + +```bash +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"}} +``` + +## Output + +`data.witnesses[]` — one entry per rank: + +| Field | Type | Meaning | +|---|---|---| +| `rank` | number | Rank by vote count (1 = most votes) | +| `name` | string | SR name | +| `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`) | +| `aprPct` | number \| null | Estimated voter APR; `null` when the estimate source is unavailable | + +## Exit status + +`0` success · `1` execution failure (`rpc_error`) · `2` usage error (`invalid_value` — limit out of range). + +## See also + +[`vote cast`](cast.md) · [`vote status`](status.md) diff --git a/ts/docs/commands/vote/status.md b/ts/docs/commands/vote/status.md new file mode 100644 index 00000000..ef5142ff --- /dev/null +++ b/ts/docs/commands/vote/status.md @@ -0,0 +1,67 @@ +# wallet-cli vote status + +Your current votes, voting power, and reward overview. + +## Synopsis + +``` +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. + +- **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%. +- **0% warning** — if any votes sit on an SR with a 0% reward ratio, text output appends a `!` line and json adds a `zero_reward_ratio` entry (`{code, message}`) to `meta.warnings`. +- **Claimable** — same source as [`reward balance`](../reward/balance.md); claim with [`reward withdraw`](../reward/withdraw.md). + +## Options + +No command-specific options; the [global options](../index.md#global-options-every-command) only (`--network` / `--account`). + +## Examples + +```bash +wallet-cli vote status --account main --network tron:nile +``` + +```console +Label main +Voting power 1,500 TP (used 1,000 / available 500) +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 +! 400 votes are on an SR with 0% reward ratio — they earn you nothing +``` + +```bash +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":[{"code":"zero_reward_ratio","message":"400 votes on TT5... (Binance Staking) earn nothing: reward ratio is 0%"}]},"chain":{"family":"tron","network":"tron:nile","chainId":"nile"}} +``` + +## Output + +| Field | Type | Meaning | +|---|---|---| +| `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` | + +Zero-reward-ratio warnings appear in `meta.warnings` as `{code: "zero_reward_ratio", message}`. + +## Exit status + +`0` success · `1` execution failure (`rpc_error`) · `2` usage error (`invalid_value`). + +## See also + +[`vote cast`](cast.md) · [`vote list`](list.md) · [`reward balance`](../reward/balance.md) · [`stake info`](../stake/info.md) diff --git a/ts/docs/concepts/accounts-and-hd.md b/ts/docs/concepts/accounts-and-hd.md new file mode 100644 index 00000000..a27bb4a6 --- /dev/null +++ b/ts/docs/concepts/accounts-and-hd.md @@ -0,0 +1,43 @@ +# Accounts and HD Wallets + +How wallet-cli organizes what you see in `list`. + +## Seeds and accounts + +A **seed wallet** is one BIP39 mnemonic; it can derive many **accounts**. Ids reflect that: + +``` +wlt_4473p34m ← seedId (one mnemonic) +wlt_4473p34m.0 ← accountId = seedId.index (one address) +wlt_4473p34m.1 +``` + +`create` makes a new seed plus account #0; `derive --seed-id wlt_…` adds the next account (or an explicit `--index`) from the same mnemonic. Restoring the mnemonic elsewhere re-derives the same addresses — which is why the mnemonic is the real backup and the master password is only local protection. Note that `create` does not print the mnemonic; run [`backup`](../commands/backup.md) to export it to an offline file. + +## Account types + +| Type | Created by | Secret stored locally? | Can sign? | +|---|---|---|---| +| `seed` | `create`, `import mnemonic`, `derive` | encrypted seed | yes | +| private-key | `import private-key` | encrypted key; **no derivation possible** | yes | +| ledger | `import ledger` | none (watch-only entry) | on the device | +| watch | `import watch` | none | no — queries only | + +## The active account + +Most wallet-bound commands need an account. Resolution order: + +1. `--account ` on the command; +2. otherwise the **active** account — set with `use `, shown by `current` and the `(active)` marker in `list`. + +Labels are unique, 1–64 chars, renameable (`rename`) — the stable handle is always the `accountId`. + +## Lifecycle + +- `backup ` exports secret + metadata to a file created with mode **0600** and never overwritten (default under `/backups/`). Treat the file as the secret it contains. +- `delete` removes accounts; **deleting an HD wallet cascades from the seed root** — all derived accounts of that seed go with it. The on-chain assets are untouched: re-import the mnemonic to regain access. +- Losing the master password is unrecoverable locally; the escape hatch is always the mnemonic → `import mnemonic`. + +## See also + +[`list`](../commands/list.md) · [`create`](../commands/create.md) · [`import`](../commands/import/index.md) · [Security model](security.md) diff --git a/ts/docs/concepts/energy-bandwidth.md b/ts/docs/concepts/energy-bandwidth.md new file mode 100644 index 00000000..06934f9a --- /dev/null +++ b/ts/docs/concepts/energy-bandwidth.md @@ -0,0 +1,47 @@ +# Energy and Bandwidth + +TRON's fee model, and why `stake` exists. Units first: **1 TRX = 1,000,000 SUN**; all CLI amounts named `*-sun` and all JSON amounts are raw SUN strings. + +## Two resources instead of gas + +| Resource | Consumed by | Free allowance | +|---|---|---| +| **Bandwidth** | every transaction's bytes | small daily per-account quota | +| **Energy** | smart-contract execution (TRC20 transfers included) | none | + +When a transaction needs more than you have, the node **burns TRX** from your balance to cover the difference. For contract calls, `--fee-limit` (on `tx send` / `contract` commands, default 100000000 SUN) caps that burn — a safety valve against a buggy or hostile contract consuming unbounded energy. + +Check your standing anytime: + +```bash +wallet-cli account info --network tron:nile -o json | jq '.data.resources' +``` + +```json +{ "bandwidth": { "used": 0, "limit": 600 }, "energy": { "used": 0, "limit": 888 } } +``` + +## How you obtain resources: staking + +Staking locks TRX (it remains yours) in exchange for a continuous resource quota plus TRON Power (governance votes). The `stake` command group maps 1:1 onto the chain operations: + +| Command | Chain operation | Effect | +|---|---|---| +| `stake freeze` | FreezeBalanceV2 | Lock TRX for `--resource energy\|bandwidth` | +| `stake unfreeze` | UnfreezeBalanceV2 | Request unlock; resources drop immediately, TRX enters a **waiting period** (14 days on mainnet) | +| `stake withdraw` | WithdrawExpireUnfreeze | Claim unstakes whose waiting period has expired | +| `stake cancel-unfreeze` | CancelAllUnfreezeV2 | Roll **all** pending unstakes back to staked | +| `stake delegate` | DelegateResourceV2 | Lend resource quota to `--receiver` (optionally `--lock` for `--lock-period` blocks, ~3 s/block) | +| `stake undelegate` | UnDelegateResourceV2 | Reclaim a delegation | + +Delegation moves the **resource quota**, never the TRX — the stake stays on the owner's account. A common setup: a cold account holds the stake and delegates energy to a hot account that does the transacting. + +## Practical consequences + +- A "free" TRX transfer isn't always free: past the bandwidth quota, it burns TRX. +- A TRC20 transfer with zero energy burns noticeably more — check `--dry-run`'s `fee` block before complaining about balances. +- `rpc_error` mentioning bandwidth/energy/balance during send → fund, stake, or wait for the daily quota; see [Troubleshooting](../troubleshooting.md#rpc_error-exit-1). + +## See also + +[Staking walkthrough](../guide/stake-and-resources.md) · [Networks](networks.md) · [`account info`](../commands/account/info.md) diff --git a/ts/docs/concepts/index.md b/ts/docs/concepts/index.md new file mode 100644 index 00000000..c2be2584 --- /dev/null +++ b/ts/docs/concepts/index.md @@ -0,0 +1,12 @@ +# Concepts + +How TRON and wallet-cli work underneath the commands. Read these once and the command pages stop feeling arbitrary. + +| Concept | What it explains | +|---|---| +| [Networks](networks.md) | Canonical network ids (`tron:mainnet` / `tron:nile` / `tron:shasta`) and how a command picks one | +| [Accounts and HD wallets](accounts-and-hd.md) | Seeds, derived accounts, account types, the active account, backup and delete | +| [Energy and bandwidth](energy-bandwidth.md) | TRON's fee model and why `stake` exists | +| [Security model](security.md) | Key storage, secret handling, recovery, and what remains your responsibility | + +Doing rather than understanding? See the [guides](../guide/index.md). Looking up a command? See the [command reference](../commands/index.md). diff --git a/ts/docs/concepts/networks.md b/ts/docs/concepts/networks.md new file mode 100644 index 00000000..030f8705 --- /dev/null +++ b/ts/docs/concepts/networks.md @@ -0,0 +1,40 @@ +# Networks + +wallet-cli addresses networks by **canonical id** — `family:chain`: + +```bash +wallet-cli networks -o json +``` + +```console +{"schema":"wallet-cli.result.v1","success":true,"command":"networks","data":[ + {"id":"tron:mainnet","family":"tron","chainId":"mainnet","feeModel":"tron-resource"}, + {"id":"tron:nile","family":"tron","chainId":"nile","feeModel":"tron-resource"}, + {"id":"tron:shasta","family":"tron","chainId":"shasta","feeModel":"tron-resource"}], + "meta":{"durationMs":16,"warnings":[]}} +``` + +| Id | What it is | TRX value | +|---|---|---| +| `tron:mainnet` | Production TRON | **Real money** | +| `tron:nile` | Primary testnet; faucet at nileex.io | none — use freely | +| `tron:shasta` | Alternative testnet | none | + +## How a command picks its network + +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. + +Your **address is the same on every network**, but 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`. + +## Fees: the `tron-resource` model + +TRON does not charge gas the way EVM chains do. Transactions consume **bandwidth** (bytes) and, for smart-contract calls, **energy**; shortfalls are covered by burning TRX, and staking TRX earns a continuous quota. Full model, the staking commands, and the unstake waiting period: [Energy & bandwidth](energy-bandwidth.md). + +Units: **1 TRX = 1,000,000 SUN**. JSON payloads carry raw SUN as strings (`"balance": "1976489000"` = 1976.489 TRX); text output shows human TRX. + +## See also + +- [`account info`](../commands/account/info.md) — shows your current bandwidth/energy usage and limits +- [Getting started](../guide/getting-started.md) — funding an account on Nile diff --git a/ts/docs/concepts/security.md b/ts/docs/concepts/security.md new file mode 100644 index 00000000..fb038d12 --- /dev/null +++ b/ts/docs/concepts/security.md @@ -0,0 +1,45 @@ +# Security Model + +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. + +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. + +The recovery object is the BIP39 mnemonic, but `create` never prints it — the seed is stored encrypted. Run [`backup`](../commands/backup.md) to export the plaintext mnemonic to a `0600` file and keep that file offline. Lose both password and backup and the funds are gone; lose only the password and `import mnemonic` (using the phrase from your backup) restores everything. + +## Secrets in transit: stdin or TTY, never argv/env + +Anything in a command's arguments or environment leaks into shell history, `ps` output, and CI logs. wallet-cli therefore refuses secrets there — they enter only via: + +- interactive TTY prompts, or +- explicit stdin flags: `--password-stdin`, `--tx-stdin` — **one `*-stdin` flag per run**, so a pipeline can never silently feed the wrong secret to the wrong prompt. The highest-value secrets go further: mnemonics and private keys are accepted **only** via hidden TTY input (`import mnemonic` / `import private-key` / `change-password` have no stdin path at all). + +Corollary for scripts: source the piped secret from a secret store, not from a tracked file. See [machine-interface → Secret handling](../machine-interface.md#secret-handling). + +## Error output is redaction-safe + +Unexpected internal exceptions are collapsed to a generic `internal_error` message before reaching the output envelope, so a third-party library error that happens to echo key material can never leak through a result or a log that captured it. + +## Files that contain secrets + +`backup` writes secret + metadata with file mode **0600** and never overwrites an existing file. After exporting: move it to your secure storage and treat the file exactly like the key it contains — it is outside wallet-cli's protection from that moment. + +## Choosing a key posture + +| Posture | Setup | Trade-off | +|---|---|---| +| Software key | `create` / `import` | Convenient; host compromise = key compromise | +| Ledger | `import ledger` | Key never on host; every send confirmed on-device — see [Ledger guide](../guide/ledger.md) | +| Watch-only | `import watch` | No signing at all; safe for monitoring balances of cold storage | +| Split sign/broadcast | `--sign-only` + `tx broadcast` | Signing machine needs no network — see [Scripting](../guide/scripting.md#sign-here-broadcast-there) | + +## What wallet-cli cannot do for you + +Verify recipients (the chain is irreversible), protect a compromised host's TTY, or secure where you keep the mnemonic and backups. On mainnet, `--dry-run` first is cheap insurance. + +## See also + +[Accounts & HD](accounts-and-hd.md) · [machine-interface](../machine-interface.md) · [Troubleshooting](../troubleshooting.md) diff --git a/ts/docs/evm-development-plan.md b/ts/docs/evm-development-plan.md deleted file mode 100644 index 2fc00530..00000000 --- a/ts/docs/evm-development-plan.md +++ /dev/null @@ -1,593 +0,0 @@ -# wallet-cli EVM Support Development Plan - -> Status: to be implemented -> Applies to: `ts-refactor` -> Purpose: list the full scope of everything that must be modified, added, and accepted when extending the current TRON-only CLI to TRON + EVM. This document deliberately does not expand into the implementation details of functions and RPC payloads. - -## 1. Definition of Done - -EVM support cannot merely mean "can connect to an Ethereum RPC". When complete, all of the following must hold simultaneously: - -1. `evm` is a formal `ChainFamily`, no longer simulated by a type cast in tests. -2. It can resolve Ethereum mainnet `evm:1`, as well as any `evm:` added in the config file, e.g. `evm:11155111`, `evm:8453`, `evm:31337`. -3. An EVM network can be selected by canonical id or a unique alias, and can be set as `defaultNetwork`. -4. seed, private key, watch-only, and the Ledger Ethereum app all have explicit EVM behavior. -5. EVM has its own gateway, signing strategy, use cases, and CLI command module, and does not stuff EVM methods into the TRON gateway. -6. `wallet-cli --help`, family help, command help, `--json-schema`, and `wallet-cli networks` all let a user/agent discover EVM. -7. Text and JSON output correctly present EVM address, chain id, native currency, gas, fee, nonce, transaction hash, and receipt. -8. The existing TRON commands, output, secret handling, and exit-code contract remain unchanged. - -Development dependency order: - -```text -public contract → Domain → Persistence/Config → Application ports → EVM adapters - → EVM use cases → CLI commands → Bootstrap → Help/Output → Tests/Docs -``` - -### 1.1 The Real Code-Change Classification - -The "locations involved" that appear later in this document include modifications, references, and verification — it does not mean every file must change. Based on the current code, the actual classification is as follows. - -#### Definitely added - -- `application/ports/chain/evm-gateway.ts` -- `adapters/outbound/chain/evm/*` -- `application/use-cases/evm/*` -- `adapters/inbound/cli/commands/evm/*` -- `bootstrap/families/evm.ts` -- EVM confirmation, fixtures, unit/integration/live tests -- Explorer/history adapter (added only if EVM history/ABI metadata is to be provided) - -#### Definitely modified - -- Domain family/address/network/wallet/transaction types -- Config builtins, custom-network validation, and network display -- Keystore schema migration and the EVM-address backfill for old wallets -- `ChainGatewayMap` and the family plugin registry -- The file location of the generic gateway registry (currently misplaced in `chain/tron/provider.ts`) -- The outbound Ledger dispatcher (if Ledger EVM is exposed) -- Token builtin/normalization and the CoinGecko network mapping -- Root/family/merged command help, the global `--network` description, and the wallet help examples -- The family renderer, EVM transaction/fee text output -- Dependencies, architecture docs, help/golden baselines - -#### In principle not modified, only adding EVM tests to verify reusability - -- `application/services/transaction-mode.ts` -- `application/services/pipeline/index.ts` -- `application/services/signer/index.ts` -- `application/services/signer/software.ts` -- `application/services/signer/ledger.ts` -- `application/services/target/index.ts` -- `application/contracts/execution-policy.ts` -- `application/contracts/execution-scope.ts` -- `application/ports/chain/broadcaster.ts` -- `application/ports/ledger-device.ts` -- `application/ports/network-registry.ts` -- `application/ports/token-repository.ts` -- `application/ports/price-provider.ts` -- `adapters/inbound/cli/registry/index.ts` -- `adapters/inbound/cli/shell/index.ts` -- `adapters/inbound/cli/command-id.ts` -- `adapters/inbound/cli/context/index.ts` -- `adapters/inbound/cli/arity/index.ts` -- `adapters/inbound/cli/output/envelope.ts` -- stream, secret, prompt, and output formatter infrastructure - -#### Modified only if a public decision requires it - -- `CapabilityRegistry` and bootstrap capability composition: needed only if history/indexer, legacy/EIP-1559, etc. require per-network gating. -- Help catalog: EVM commands enter the catalog automatically via the registry; modification is needed only to add a families/networks summary at the top level of the catalog. -- `WalletService`: the existing family detection and repository delegation are reusable; usually only tests are needed, and migration should stay in the persistence adapter. -- Shared transaction types/pipeline: types must be extended with display fields, but the pipeline control flow is in principle unchanged. - -If the implementation must modify one of the above "in principle not modified" modules, you should first point out which family-neutral capability the current abstraction lacks; you must not add `if (family === "evm")` just because the EVM adapter is awkward to write. - -## 2. Public Decisions to Lock Before Development - -The following decisions must be written into the architecture contract first, otherwise help, the network schema, the command schema, and the tests will be revised repeatedly. - -### 2.1 Network identity - -Network aliases are deferred while selector input accepts canonical ids only. Alias-related requirements below remain future work for when that feature is restored. - -- The EVM canonical network id is fixed as `evm:`. -- The `xxx` in `evm:xxx` is the EIP-155 chain id, not a name; the actual value must be a positive-integer string. -- Minimum builtin networks: - - `evm:1`, with recommended aliases `eth`, `ethereum`. - - One public testnet, recommended `evm:11155111`, alias `sepolia`. -- Other networks are added via `config.yaml`; whether to additionally build in Base, Polygon, BSC, etc. is a product decision. -- An alias must be globally unique; a duplicate alias must keep the `ambiguous_network_alias` error. -- The chain id reported by RPC must match the configured value; the mismatch must not be ignored before signing or broadcast. -- `defaultNetwork` is still recommended to remain `tron:mainnet`, unless there is a separate product migration decision. - -The recommended public shape of a custom network: - -```yaml -defaultNetwork: evm:1 -networks: - evm:1: - family: evm - chainId: "1" - aliases: [eth, ethereum] - rpcUrl: https://example.invalid - feeModel: eip1559 - nativeCurrency: - name: Ether - symbol: ETH - decimals: 18 - - evm:31337: - family: evm - chainId: "31337" - aliases: [local] - rpcUrl: http://127.0.0.1:8545 - feeModel: eip1559 - nativeCurrency: - name: Ether - symbol: ETH - decimals: 18 -``` - -### 2.2 The First-Version Command Surface - -The same logical path selects the TRON or EVM implementation via `--network`. A separate top-level `ethereum ...` execution grammar must not be created for EVM. - -| Command group | First-version EVM requirement | Notes | -| --- | --- | --- | -| wallet lifecycle | supported | create/import/derive show the EVM address afterward; watch can recognize `0x...`. | -| `account balance` | supported | uses the network native currency. | -| `account info` | supported | EVM semantics are defined by the EVM use case, not by imitating the TRON resource fields. | -| `account history` | explicit decision | standard JSON-RPC has no address history; an explorer/indexer adapter is required, otherwise it must not claim availability in the help/capability of an unsupported network. | -| `account portfolio` | supported | native coin + ERC-20 token book + price provider. | -| `token add/list/remove/balance/info` | supported | the EVM token kind is `erc20`. | -| `tx send/broadcast/status/info` | supported | native/ERC-20, legacy/EIP-1559, raw signed tx. | -| `contract call/send/deploy/info` | supported or explicitly degraded | if `contract info` needs ABI metadata, there must be an explorer source; with only bytecode, the help must describe it truthfully. | -| `message sign` | supported | software and Ledger behavior are consistent. | -| `block` | supported | latest or a specified block. | -| `stake ...` | no EVM implementation | stays TRON-only; root/family help must mark it. | - -### 2.3 SDK and Hardware Wallet - -- Select a single EVM SDK; the current architecture recommends `viem`, added to production dependencies. -- If full Ledger EVM support is claimed, add an Ethereum Ledger app adapter and the corresponding package (e.g. `@ledgerhq/hw-app-eth`). -- If the first version does not do Ledger EVM, `FAMILIES.evm.ledger`, `import ledger --help`, and the README must not show the Ethereum app. - -## 3. Phased Development Checklist - -### Phase 0: Contract and Test Baseline - -- [ ] Confirm the network id, builtin networks, command matrix, Ledger, and history/indexer decisions in Section 2. -- [ ] Build EVM address, transaction, receipt, legacy fee, EIP-1559 fee, ERC-20, block, and RPC error fixtures. -- [ ] Establish a new multichain help/golden baseline; the existing TRON-only help parity must no longer serve as the sole truth for the entire root help. -- [ ] Define the upgrade strategy and rollback behavior for the old `wallets.json` version. - -### Phase 1: Domain - -Locations involved: - -- `src/domain/family/index.ts` -- `src/domain/address/index.ts` -- `src/domain/types/network.ts` -- `src/domain/types/tx.ts` -- `src/domain/types/token.ts` -- `src/domain/types/wallet.ts` -- `src/domain/sources/index.ts` -- `src/domain/derivation/index.ts` -- `src/domain/wallet/index.ts` -- `src/domain/errors/index.ts` - -Work list: - -- [ ] Add `evm` to `ChainFamily` and `FAMILIES`. -- [ ] Register the EVM BIP44 coin type `60`, smallest unit `wei`, address codec, and Ledger metadata. -- [ ] Add EVM address derive, validate, normalize/checksum rules and tests. -- [ ] Restore `NetworkDescriptor` to a discriminated union keyed by `family`. -- [ ] Add `EvmNetworkDescriptor`: `rpcUrl`, decimal chain id, fee model, native currency, and optional explorer/history config. -- [ ] Verify that the canonical id's family and chain id are consistent with the descriptor. -- [ ] Extend the transaction view: gas, gas price, max fee, priority fee, effective gas price, nonce, EVM receipt/status, and other fields. -- [ ] Remove TRON-only naming assumptions from the shared view; when keeping backward-compatible TRON JSON fields, document them explicitly. -- [ ] Confirm the family constraint of the `erc20` token kind and contract-address normalization. -- [ ] Update seed/private-key address derivation, dedup, account projection, and family-detection tests. -- [ ] Complete typed errors for network/chain mismatch, invalid chain id, invalid EVM address, etc. - -### Phase 2: Wallet Persistence and Migration - -Locations involved: - -- `src/adapters/outbound/keystore/index.ts` -- `src/domain/types/wallet.ts` -- `src/domain/wallet/index.ts` -- `src/application/ports/account-store.ts` -- `src/application/ports/wallet-repository.ts` -- `src/application/use-cases/wallet-service.ts` -- `src/adapters/outbound/persistence/backup-writer.ts` -- wallet/keystore tests and migration fixtures - -Work list: - -- [ ] Raise the `wallets.json` schema version. -- [ ] Handle existing seed/private-key wallets that have only a TRON cached address; adding `evm` to `ChainAddresses` must not invalidate old files. -- [ ] Define the timing for the EVM address's lazy backfill / explicit migration, and the UX when a master password is needed. -- [ ] Ensure migration uses an atomic write and lock, and a failure does not corrupt the original file. -- [ ] Newly created and newly imported seed/private-key wallets generate both a TRON and an EVM address. -- [ ] `derive` for a new account generates addresses for both families. -- [ ] watch-only automatically recognizes TRON/EVM; an EVM address is normalized before storage. -- [ ] Ledger/watch remain single-family sources. -- [ ] list/current/use/rename/delete/backup and address lookup support EVM addresses. -- [ ] Backup metadata includes both known TRON/EVM addresses; for an old wallet not yet backfilled, the field must not be fabricated. -- [ ] Verify behavior for the same private key, a different BIP44 seed path, old-data migration, and dedup. - -### Phase 3: Config and NetworkRegistry - -Locations involved: - -- `src/adapters/outbound/config/builtins.ts` -- `src/adapters/outbound/config/index.ts` -- `src/adapters/outbound/config/yaml-config-document.ts` -- `src/application/ports/network-registry.ts` -- `src/application/use-cases/config-service.ts` -- `src/adapters/inbound/cli/commands/config.ts` -- `src/adapters/inbound/cli/commands/network.ts` - -Work list: - -- [ ] Add the `evm:1` and the chosen-testnet builtin descriptors. -- [ ] Apply runtime schema validation to a user-defined network, no longer casting directly to `NetworkDescriptor`. -- [ ] Support any valid `evm:`, and reject inconsistencies among `family`, id, and chain id. -- [ ] Validate `rpcUrl`, native currency, fee model, aliases, and the optional indexer/explorer fields. -- [ ] When alias support is restored, `NetworkRegistry.resolve()` supports the EVM canonical id, case-insensitive aliases, and the ambiguity check. -- [ ] `config defaultNetwork evm:1`, alias setting, and persistence work. -- [ ] `wallet-cli networks` displays builtin and custom EVM networks, the native symbol, and a safe summary of RPC/fee model/capabilities. -- [ ] Do not leak any API key that the RPC URL may contain in ordinary output; a redaction rule is needed. -- [ ] The network RPC client verifies the remote chain id on first use. - -### Phase 4: Application Ports and Shared Services - -Locations involved: - -- `src/application/ports/chain/evm-gateway.ts` (added) -- `src/application/ports/chain/gateway-provider.ts` -- `src/application/services/evm-confirmation.ts` (added) -- `src/application/services/capability/index.ts` (modified only if per-network capability is needed) - -The following shared modules are expected to only gain EVM reuse tests, with no production-code change: `Broadcaster`, `LedgerDevice`, -`TxPipeline`, `SignerResolver`, software/device signer, `TargetResolver`, `transactionMode`. - -Work list: - -- [ ] Define `EvmGateway`, holding only the read/build/estimate/broadcast capabilities EVM needs. -- [ ] Add `evm` to `ChainGatewayMap`, preserving the typed family lookup. -- [ ] Use EVM fixtures to verify that the shared `Broadcaster`, `TxPipeline`, `Signer`, and `SignStrategy` can carry an EVM transaction directly; the control flow is expected to be unchanged. -- [ ] Implement EVM confirmation normalization, preserving the existing contract of returning a submitted receipt after a `--wait` timeout. -- [ ] Support the legacy and EIP-1559 fee models; a network-specific trait must not be misjudged by a family-wide command capability as supported by all EVM networks. -- [ ] Adjust the capability registration to distinguish "the family has this command" from "this network has an indexer / EIP-1559 / etc. capability". -- [ ] Preserve the invariants: watch-only cannot sign, a wrong-family account is blocked, and dry-run does not decrypt the private key. - -### Phase 5: EVM Outbound Adapters - -Recommended new locations: - -```text -src/adapters/outbound/chain/evm/ -├── index.ts -├── provider.ts -├── evm.ts -├── signing-strategy.ts -├── evm-responses.ts -└── history-reader.ts # added only if history/indexer support is decided -``` - -Work list: - -- [ ] Implement a per-network EVM JSON-RPC client/gateway. -- [ ] Implement native balance, nonce/code, block, transaction, receipt, and fee/gas reads. -- [ ] Implement native/ERC-20 transfer, contract call/send/deploy, estimate, and raw transaction broadcast. -- [ ] Implement software transaction signing and personal-message signing. -- [ ] Validate every RPC response before normalizing, to avoid passing a provider-specific shape into a use case. -- [ ] Uniformly handle errors such as revert reason, replacement/nonce, insufficient funds, underpriced fee, chain mismatch, and timeout. -- [ ] If supporting account history / ABI metadata, add a separate explorer/indexer adapter; do not pretend standard JSON-RPC can provide it. -- [ ] Add EVM adapter unit tests with a mocked transport, not relying on a public RPC. - -### Phase 6: Ledger EVM Adapter - -Locations involved: - -- `src/adapters/outbound/ledger/index.ts` or split into family-specific device adapters -- `src/application/ports/ledger-device.ts` -- `src/application/services/signer/ledger.ts` -- `src/application/services/ledger-account.ts` -- `src/adapters/inbound/cli/commands/wallet.ts` -- `src/bootstrap/composition.ts` -- package dependencies and tsup bundling config - -Work list: - -- [ ] Add Ethereum Ledger app transport, address, transaction signing, and message signing. -- [ ] The EVM derivation path uses coin type 60, and supports the existing flow for index/path/address scan. -- [ ] `import ledger --app ethereum` appears in the schema, help, interactive choices, and tests. -- [ ] The precheck compares the device address with the cached address. -- [ ] Classify user rejection, wrong app, locked device, wrong seed, and transport error. -- [ ] Update the tsup `noExternal` / native addon config and the Ledger emulator/real-device verification. - -### Phase 7: EVM Application Use Cases - -Recommended new locations: - -```text -src/application/use-cases/evm/ -├── account-service.ts -├── token-service.ts -├── transaction-service.ts -├── contract-service.ts -└── block-service.ts -``` - -Work list: - -- [ ] Implement EVM account balance/info/portfolio; handle history per the Section 2 decision. -- [ ] Implement ERC-20 metadata, balance, and token book workflows. -- [ ] Implement native/ERC-20 send, signed raw tx broadcast, status/info. -- [ ] Implement the agreed first-version semantics of contract call/send/deploy/info. -- [ ] Implement EVM block query. -- [ ] Reuse `MessageService`, `TxPipeline`, `TransactionMode`, the token repository, and the price port; do not reuse a use case carrying TRON semantics. -- [ ] All returned shapes use a family-aware, stably-emittable normalized view. - -### Phase 8: EVM CLI Command Module - -Recommended new locations: - -```text -src/adapters/inbound/cli/commands/evm/ -├── index.ts -├── account.ts -├── token.ts -├── tx.ts -├── contract.ts -├── message.ts -└── block.ts -``` - -Shared locations involved: - -- `src/adapters/inbound/cli/commands/shared.ts` -- `src/adapters/inbound/cli/schemas/index.ts` -- `src/adapters/inbound/cli/arity/index.ts` -- `src/adapters/inbound/cli/registry/index.ts` -- `src/adapters/inbound/cli/shell/index.ts` -- `src/adapters/inbound/cli/context/index.ts` -- `src/adapters/inbound/cli/command-id.ts` - -Work list: - -- [ ] Each EVM command registers `family: "evm"`, the logical path, capability, requirements, Zod fields, examples, and formatter. -- [ ] EVM address, hash, hex data, ABI, quantity, gas, fee, nonce, and block identifier use an EVM-specific schema. -- [ ] `tx send` handles both native and ERC-20, but does not expose TRC10/TRC20 flags. -- [ ] The legacy/EIP-1559 command flags, mutual-exclusion conditions, and defaults are driven by a single schema that drives both help and JSON Schema. -- [ ] EVM does not register `stake` commands. -- [ ] Logical routing selects the EVM implementation via `--network evm:`; the same path for TRON/EVM does not pollute each other's fields or examples. -- [ ] The command id is stable as `evm.`, e.g. `evm.tx.send`. - -### Phase 9: Bootstrap and Family Composition - -Locations involved: - -- `src/bootstrap/families/evm.ts` (added) -- `src/bootstrap/families/types.ts` -- `src/bootstrap/family-registry.ts` -- `src/bootstrap/composition.ts` -- `src/bootstrap/runner.test.ts` -- `src/adapters/outbound/chain/tron/provider.ts` (may be renamed to a family-neutral gateway-registry location) - -Work list: - -- [ ] Build the `evmFamily` plugin: meta, gateway factory, sign strategy, use cases, command module. -- [ ] Add `evmFamily` to `FAMILY_REGISTRY`. -- [ ] `familyMap()` is complete for both TRON/EVM factories and signing strategies. -- [ ] The gateway cache is still isolated by canonical network id, not sharing a client across different chains. -- [ ] Capability composition is produced correctly from family commands + per-network traits. -- [ ] Bootstrap tests expect the enabled families to be `tron`, `evm`, and verify the command registration of both. - -### Phase 10: Help, Discovery, and Machine Catalog - -This phase is a necessary condition for publicly supporting EVM; it must not be treated as a documentation wrap-up. - -Locations involved: - -- `src/adapters/inbound/cli/help/index.ts` -- `src/adapters/inbound/cli/help/catalog.ts` -- `src/adapters/inbound/cli/globals/index.ts` -- `src/adapters/inbound/cli/registry/index.ts` -- `src/adapters/inbound/cli/commands/network.ts` -- help/golden tests and baselines - -Must support and test: - -- [ ] `wallet-cli --help` - - Shows the supported families: TRON, EVM. - - Explains that the command implementation is selected by `--network`. - - Has at least one `--network evm:1` example. - - `stake` is clearly marked TRON-only. -- [ ] `wallet-cli evm --help` - - Shows the EVM-available command tree, without `stake`. - - If the `evm` prefix is used only for help/catalog discovery and cannot be used for ordinary execution, it must say so explicitly in the output. -- [ ] `wallet-cli evm tx send --help` - - Shows only EVM fields, EVM examples, the fee-model explanation, and the EVM address format. -- [ ] `wallet-cli tx send --help` - - The merged logical help must clearly mark family-specific flags/examples; it must not just take the metadata of the registry's first family. -- [ ] `wallet-cli tx send --network evm:1 --help` - - Meta parsing must correctly consume the `--network` value and parse it into EVM help; it must not treat `evm:1` as a command positional. -- [ ] `wallet-cli networks --help` - - Explains the canonical id `evm:`, aliases, and the source of custom networks. -- [ ] `wallet-cli --json-schema` - - The full catalog includes the `evm.*` commands. - - The top level of the catalog should add an enabled-families and available-networks summary. -- [ ] `wallet-cli evm --json-schema` - - Emits only EVM chain commands; the schema and examples contain no TRON-only flags. -- [ ] `--json-schema` for each EVM leaf - - The input schema, requires, capability, examples, and stdin flags are correct. -- [ ] global `--network` description - - The examples include at least `tron:nile`, `evm:1`, an alias, and the config fallback. -- [ ] unknown/disabled family, unknown EVM network, and family/network mismatch all emit a clear usage error and exit 2. - -### Phase 11: Text and JSON Output - -Locations involved: - -- `src/adapters/inbound/cli/render/index.ts` -- `src/adapters/inbound/cli/render/scalars.ts` -- `src/adapters/inbound/cli/output/envelope.ts` -- `src/adapters/inbound/cli/contracts/envelope.ts` -- formatter/envelope/golden tests - -Work list: - -- [ ] Add EVM hooks to `FAMILY_RENDER`. -- [ ] Display the native amount per the network `nativeCurrency`, not assuming every EVM network is ETH. -- [ ] EVM transaction info/receipt shows hash, from/to/value, nonce, gas, fee, status, block, and contract address. -- [ ] Both legacy and EIP-1559 fee text render correctly. -- [ ] wallet/list/current/import/derive show both TRON and EVM addresses, and the address is not wrongly abbreviated or mislabeled by family. -- [ ] The `networks` text table shows the EVM chain id, native symbol, and fee model. -- [ ] The JSON envelope keeps `wallet-cli.result.v1` and emits: - - `command: "evm...."` - - `chain.family: "evm"` - - `chain.network: "evm:"` - - `chain.chainId: ""` -- [ ] All wei, gas, fee, nonce, and block quantities avoid JavaScript number precision loss; JSON uses a stable string rule. -- [ ] error, warning, and progress still obey the stdout/stderr and single-terminal-frame contract. - -### Phase 12: Token Book and Price Provider - -Locations involved: - -- `src/adapters/outbound/tokenbook/builtins.ts` -- `src/adapters/outbound/tokenbook/index.ts` -- `src/application/ports/token-repository.ts` -- `src/adapters/outbound/price/coingecko.ts` -- `src/application/ports/price-provider.ts` - -Work list: - -- [ ] Add official ERC-20 token entries for the chosen builtin EVM networks; a testnet may keep an empty list. -- [ ] The ERC-20 contract id uses a consistent normalized/checksummed comparison to avoid case-based duplicates. -- [ ] Confirm the token book scope is still `(networkId, accountRef)`, so different EVM chains do not share a list. -- [ ] The CoinGecko native-coin id and asset platform must not be derived from the `evm:` prefix alone; they must be decided by the actual network mapping/config. -- [ ] When a custom EVM network has no price mapping, return null/warning, and do not fail the portfolio command. -- [ ] token price lookup, official/user merge, remove protection, and portfolio tests cover EVM. - -### Phase 13: Tests and Quality Gates - -#### Unit tests - -- [ ] EVM address derive/validate/checksum. -- [ ] BIP44 coin type 60 and seed/private-key address derivation. -- [ ] network descriptor validation, canonical id, arbitrary chain id, aliases, RPC chain mismatch. -- [ ] wallet migration, backfill, dedup, watch/Ledger family pinning. -- [ ] EVM gateway RPC normalization and typed errors. -- [ ] software/Ledger transaction and message signing. -- [ ] legacy/EIP-1559 transaction build, estimate, broadcast, confirmation. -- [ ] ERC-20, contract, block, account, and portfolio use cases. -- [ ] EVM commands, registry routing, target/capability gates, renderers, envelopes. - -#### CLI/golden tests - -- [ ] root/family/group/leaf `--help`. -- [ ] root/family/leaf `--json-schema`. -- [ ] `networks` text + JSON include `evm:1` and custom `evm:31337`. -- [ ] `config defaultNetwork evm:1` and alias round trip. -- [ ] `--network evm:1` routes to an `evm.*` command id. -- [ ] The same logical command yields a different schema, client, and output under TRON/EVM. -- [ ] wrong-family account, unknown chain, alias collision, unsupported network trait. -- [ ] JSON one-frame, exit `0/1/2`, stderr progress, secret redaction. -- [ ] All old TRON golden tests still pass; the expected output of the root help switches to the new multichain baseline. - -#### Integration/live tests - -- [ ] Add a local EVM suite, recommended Anvil, covering account, native/ERC-20 send, contract, block, sign-only, broadcast, `--wait`. -- [ ] Add a public EVM testnet smoke suite, using an isolated wallet home and secret source, not logging the private key. -- [ ] Keep the Nile live suite, confirming the EVM changes cause no TRON regression. -- [ ] If supporting Ledger EVM, add Speculos or real-device smoke tests. - -#### Required commands - -```bash -npm run typecheck -npm run depcruise -npm test -npm run build -npm run test:parity:help -npm run test:live:nile -# new: EVM local integration suite -# new: EVM public-testnet smoke suite -``` - -### Phase 14: User Documentation and Release - -Locations involved: - -- `README.md` -- `docs/architecture.md` -- network/config example docs -- command/help baselines -- release notes and migration notes - -Work list: - -- [ ] Change the README to TRON + EVM, adding `evm:1`, custom chain, wallet, and send examples. -- [ ] Mark the architecture diagram and the family-extension section as EVM-implemented, no longer writing it as a future item. -- [ ] The docs list the builtin networks, canonical id, aliases, custom-network schema, and how to set `defaultNetwork`. -- [ ] Explain that the same wallet has different TRON/EVM derivation paths, and that watch/Ledger are single-family. -- [ ] Explain optional capabilities such as EVM history, contract metadata, price, and Ledger, and their network requirements. -- [ ] Provide the behavior of upgrading from the old wallets schema, the backup recommendation, and the failure-recovery method. -- [ ] Before release, run end-to-end acceptance once each with a brand-new home and an old-version home. - -## 4. Master Table of File Changes - -| Layer | Modified | Added | -| --- | --- | --- | -| Domain | family, address, network, wallet, tx, token, errors | EVM codec/types (may cohere within existing modules) | -| Application contracts/ports | gateway map, ledger/transaction contracts, capabilities | `evm-gateway.ts` | -| Application services | signer, pipeline, target, capability | `evm-confirmation.ts` | -| Application use cases | shared message/wallet integration | `use-cases/evm/*` | -| Outbound adapters | config, keystore, ledger, tokenbook, price, gateway registry | `chain/evm/*` | -| Inbound CLI | schemas, shell, registry, help, render, output, wallet/network commands | `commands/evm/*` | -| Bootstrap | family types, registry, composition, tests | `families/evm.ts` | -| Tooling | dependencies, tsup, test scripts, baselines | EVM local/live scripts and fixtures | -| Docs | README, architecture, network/config docs | migration/release notes | - -## 5. Unacceptable Shortcuts - -- Do not merely add `evm` to the union without handling the old-wallet address-cache migration. -- Do not type-cast a custom network directly in `ConfigLoader` without validation. -- Do not add EVM RPC methods into `TronGateway` or create a universal gateway that contains all chains' methods. -- Do not let all EVM networks automatically gain explorer, history, or EIP-1559 capability just because the family has the command. -- Do not let root help, leaf help, and JSON Schema still show only TRON examples. -- Do not hardcode all EVM native currencies as ETH. -- Do not convert a bigint fee/value into an unsafe JavaScript number. -- Do not leak an API key / private key in the RPC URL, an error, a verbose log, the JSON envelope, or a test artifact. -- Do not break TRON command ids, the JSON envelope, exit codes, or the stdout/stderr discipline by adding EVM. - -## 6. Final Acceptance Examples - -EVM may be declared publicly supported only when all of the following behaviors hold: - -```bash -wallet-cli --help -wallet-cli evm --help -wallet-cli evm tx send --help -wallet-cli tx send --network evm:1 --help -wallet-cli --json-schema -wallet-cli evm --json-schema - -wallet-cli networks -wallet-cli config defaultNetwork evm:1 -wallet-cli account balance --network evm:1 -wallet-cli account balance --network evm:31337 -wallet-cli tx send --network evm:1 --to 0x... --amount 0.01 -wallet-cli token balance --network evm:1 --contract 0x... -wallet-cli contract call --network evm:1 --contract 0x... ... -wallet-cli block --network evm:1 -wallet-cli message sign --network evm:1 --message hello -``` - -Here `evm:31337` must be providable by the user's config; it is not required that every chain id become a builtin network. diff --git a/ts/docs/guide/getting-started.md b/ts/docs/guide/getting-started.md new file mode 100644 index 00000000..b50e8887 --- /dev/null +++ b/ts/docs/guide/getting-started.md @@ -0,0 +1,101 @@ +# Getting Started + +Create a wallet, fund it on the Nile testnet, check the balance, and send your first transaction — about 10 minutes end to end. Everything here runs on **Nile** (test TRX, no real value). + +Prerequisite: wallet-cli is installed — `wallet-cli --version` prints a version number. If it doesn't, see [Install](../../README.md#install). + +## 1. Create a wallet + +```bash +wallet-cli create --label main +``` + +You will be prompted for a **master password** — it encrypts all local secrets and cannot be recovered if you lose it. It must be at least 8 characters and include an uppercase letter, a lowercase letter, a digit, and a special character. + +**Tip — a password manager is preferable.** It generates a strong, unique password and keeps it out of your shell history, process list, and plaintext files. Any password manager with a command-line tool works — the examples here use 1Password's `op` purely as an illustration (install and sign in — [docs](https://developer.1password.com/docs/cli/)). Save your chosen master password as an item, then create the wallet by reading it back: + +```bash +op read "op://Private/wallet-cli/password" | wallet-cli create --label main --password-stdin +``` + +`create` does **not** print your recovery phrase — the seed is encrypted locally. To get a written backup, run [`backup`](../commands/backup.md), which writes a `0600` file containing the plaintext BIP39 mnemonic; store that file offline. It is the only way to restore the wallet on another machine. + +Already have a mnemonic or private key? Use [`import mnemonic`](../commands/import/mnemonic.md) or [`import private-key`](../commands/import/private-key.md) instead. + +Confirm the new account exists: + +```bash +wallet-cli list +``` + +```console +HD wlt_4473p34m +└─ [0] main TMSgJxtPw29AFEHMXsjGo4kWV7UwbCToHJ (active) +``` + +The `T…` string is your TRON address, same on every network. `(active)` marks the account commands act on by default; switch with `wallet-cli use