@zebec-network/tron-transfer-sdk 1.0.0

package/README.md

@@ -0,0 +1,589 @@
+# @zebec-network/tron-transfer-sdk
+
+A small TypeScript SDK for sending **TRX** (TRON's native coin) and **TRC-20 tokens** such as **USDT** from one TRON address to another, on either **mainnet** or **testnet** (Nile or Shasta).
+
+It wraps [TronWeb](https://tronweb.network) with two functions, `transferTrx` and `transferToken`. Each one takes care of the fiddly parts of a transfer:
+
+- **Unit conversion.** You pass amounts in whole units (`"10"` TRX, `"2.5"` USDT). The SDK converts them to on-chain units with exact integer math, so there are no floating-point rounding errors.
+- **Pre-flight checks.** Addresses, amounts and the sender's balance are checked before anything is sent. This matters for tokens: a TRC-20 transfer that fails on-chain still burns TRX in fees.
+- **Build, sign, broadcast.** The transaction is signed locally with the private key from your `.env`. The key never leaves your machine.
+- **Confirmation.** By default the SDK waits until the transaction is in a block and verifies it actually succeeded. The network accepting a transaction does not mean it executed, especially for token transfers.
+- **Readable errors.** Node error messages are decoded, and every failure after broadcast carries the transaction ID.
+
+---
+
+## Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Quick start](#quick-start)
+- [API reference](#api-reference)
+- [Types](#types)
+- [How a transfer works](#how-a-transfer-works)
+- [Fees and resources](#fees-and-resources)
+- [Error handling](#error-handling)
+- [Networks and token addresses](#networks-and-token-addresses)
+- [Example CLI](#example-cli)
+- [Development](#development)
+- [Project structure](#project-structure)
+- [Dependencies](#dependencies)
+- [Security](#security)
+- [Troubleshooting](#troubleshooting)
+- [References](#references)
+
+---
+
+## Requirements
+
+| Requirement    | Version / notes                                                                                                                                             |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Node.js        | **20 or newer** (developed and tested on Node 26)                                                                                                           |
+| Package format | **ES modules only** (`"type": "module"`). Load it with `import`, not `require()`.                                                                           |
+| TypeScript     | Optional for consumers. If you use it, set `"moduleResolution"` to `"nodenext"`, `"node16"` or `"bundler"`, and turn on `"skipLibCheck": true` (see below). |
+| A TRON account | Its hex private key, funded with TRX for fees (and holding the token, for token transfers)                                                                  |
+| TronGrid key   | **Required for mainnet** (`api.trongrid.io`); optional on testnets. Get one at [trongrid.io](https://www.trongrid.io).                                      |
+
+> **Why `skipLibCheck`?** TronWeb's bundled type definitions don't pass strict type-checking under `nodenext` resolution. Your own code is still fully checked; this only skips checking the `.d.ts` files inside `node_modules`.
+
+---
+
+## Installation
+
+```bash
+npm install @zebec-network/tron-transfer-sdk
+# or
+yarn add @zebec-network/tron-transfer-sdk
+```
+
+Then import it:
+
+```ts
+import { transferTrx, transferToken } from '@zebec-network/tron-transfer-sdk';
+```
+
+To work on the SDK itself, see [Development](#development).
+
+---
+
+## Configuration
+
+The SDK reads its settings from environment variables. It loads a `.env` file from the **current working directory** automatically when it's imported, via `dotenv`. Variables already set in the real environment take precedence over `.env`, so you can also configure it without a file (for example in CI or a container).
+
+Copy the template and fill in your values:
+
+```bash
+cp .env.example .env
+```
+
+### Variables
+
+**General**
+
+| Variable             | Required | Default     | Description                                                                                                                               |
+| -------------------- | -------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `TRON_NETWORK`       | No       | `testnet`   | Which network calls use when they don't pass `network`: `testnet` or `mainnet`. Not in `.env.example`; add it only to change the default. |
+| `TRON_FEE_LIMIT_SUN` | No       | `100000000` | Max TRX, in SUN, that one token transfer may burn for energy. `100000000` SUN = 100 TRX.                                                  |
+
+**Per network.** Replace `<NET>` with `TESTNET` or `MAINNET`:
+
+| Variable                   | Required                 | Description                                                                                                                                                 |
+| -------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `TRON_<NET>_FULL_HOST`     | Yes                      | Full-node URL, e.g. `https://nile.trongrid.io` or `https://api.trongrid.io`.                                                                                |
+| `TRON_<NET>_PRIVATE_KEY`   | Yes                      | Sender's private key: 64 hex characters. A leading `0x` is accepted and stripped.                                                                           |
+| `TRON_<NET>_API_KEY`       | Mainnet on TronGrid: yes | TronGrid API key, sent as the `TRON-PRO-API-KEY` header. Keyless mainnet requests to `api.trongrid.io` get HTTP 429, so the SDK refuses to run without one. |
+| `TRON_<NET>_USDT_CONTRACT` | No                       | Default token for `transferToken` when no `tokenAddress` is passed.                                                                                         |
+
+**Tests only**
+
+| Variable              | Description                                                                             |
+| --------------------- | --------------------------------------------------------------------------------------- |
+| `TRON_TEST_NETWORK`   | Network the tests use: `testnet` (default) or `mainnet`. Mainnet tests move real funds. |
+| `TRON_TEST_RECIPIENT` | Address that receives the live transfers when `TRON_TEST_NETWORK=testnet`.              |
+| `TRON_MAIN_RECIPIENT` | Address that receives the live transfers when `TRON_TEST_NETWORK=mainnet`.              |
+
+### Example `.env` for Nile testnet
+
+```dotenv
+TRON_TEST_NETWORK=testnet
+TRON_FEE_LIMIT_SUN=100000000
+
+TRON_TESTNET_FULL_HOST=https://nile.trongrid.io
+TRON_TESTNET_API_KEY=
+TRON_TESTNET_PRIVATE_KEY=<64-hex-char private key>
+TRON_TESTNET_USDT_CONTRACT=TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf
+
+TRON_MAINNET_FULL_HOST=https://api.trongrid.io
+TRON_MAINNET_API_KEY=<your TronGrid key>
+TRON_MAINNET_PRIVATE_KEY=
+TRON_MAINNET_USDT_CONTRACT=TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t
+
+TRON_TEST_RECIPIENT=<a second testnet address>
+TRON_MAIN_RECIPIENT=<a second mainnet address, only for mainnet test runs>
+```
+
+Configuration is read on **every call**, so each call checks only the network it uses. You can leave the mainnet key empty while working on testnet.
+
+---
+
+## Quick start
+
+```ts
+import { transferTrx, transferToken, TronTransferError } from '@zebec-network/tron-transfer-sdk';
+
+// Send 10 TRX on the network set by TRON_NETWORK
+const trx = await transferTrx({ to: 'TXYZ...recipient', amount: '10' });
+console.log(trx.txid, trx.blockNumber, trx.feeSun);
+
+// Send 5 USDT (uses TRON_<NET>_USDT_CONTRACT)
+const usdt = await transferToken({ to: 'TXYZ...recipient', amount: '5' });
+
+// Send any other TRC-20 token, explicitly on mainnet
+await transferToken({
+  to: 'TXYZ...recipient',
+  amount: '1.25',
+  tokenAddress: 'T...tokenContract',
+  network: 'mainnet',
+});
+
+// Handle failures
+try {
+  await transferTrx({ to: 'TXYZ...recipient', amount: '1' });
+} catch (error) {
+  if (error instanceof TronTransferError && error.txid) {
+    // The transaction reached the network; look it up before retrying.
+    console.error(`Failed after broadcast: ${error.txid}`);
+  }
+  throw error;
+}
+```
+
+---
+
+## API reference
+
+Everything below is exported from the package root.
+
+### `transferTrx(params)`
+
+Sends native TRX from the account configured for the network.
+
+```ts
+function transferTrx(params: TransferTrxParams): Promise<TransferResult>;
+```
+
+| Param                   | Type                     | Default        | Description                                         |
+| ----------------------- | ------------------------ | -------------- | --------------------------------------------------- |
+| `to`                    | `string`                 | required       | Recipient base58 address (`T...`).                  |
+| `amount`                | `string \| number`       | required       | Amount in **TRX**, not SUN. Up to 6 decimal places. |
+| `network`               | `'testnet' \| 'mainnet'` | `TRON_NETWORK` | Network for this call.                              |
+| `waitForConfirmation`   | `boolean`                | `true`         | Wait for the block and verify success.              |
+| `confirmationTimeoutMs` | `number`                 | `60000`        | How long to wait for confirmation.                  |
+
+Before sending, it checks that:
+
+- `to` is a valid address and isn't the sender;
+- `amount` is positive and has at most 6 decimals;
+- the sender's TRX balance is at least `amount`.
+
+The balance check reads the full node's latest state, not the roughly one-minute-old "solidified" state that `trx.getBalance()` returns. It doesn't account for fees, so a transfer of your entire balance can still be rejected by the node if bandwidth has to be paid for.
+
+```ts
+await transferTrx({ to: 'TXYZ...', amount: '0.5' }); // 500,000 SUN
+await transferTrx({ to: 'TXYZ...', amount: 12 }); // 12 TRX
+await transferTrx({ to: 'TXYZ...', amount: '1', waitForConfirmation: false }); // return right after broadcast
+```
+
+### `transferToken(params)`
+
+Sends a TRC-20 token by calling its `transfer(address,uint256)` function. The default token is the USDT contract configured for the network.
+
+```ts
+function transferToken(params: TransferTokenParams): Promise<TransferResult>;
+```
+
+| Param                   | Type                     | Default                    | Description                                                |
+| ----------------------- | ------------------------ | -------------------------- | ---------------------------------------------------------- |
+| `to`                    | `string`                 | required                   | Recipient base58 address.                                  |
+| `amount`                | `string \| number`       | required                   | Amount in **whole tokens** (e.g. `"5"` USDT).              |
+| `tokenAddress`          | `string`                 | `TRON_<NET>_USDT_CONTRACT` | TRC-20 contract address.                                   |
+| `feeLimitSun`           | `number`                 | `TRON_FEE_LIMIT_SUN`       | Max TRX (in SUN) this transfer may burn for energy.        |
+| `network`               | `'testnet' \| 'mainnet'` | `TRON_NETWORK`             | Network for this call.                                     |
+| `waitForConfirmation`   | `boolean`                | `true`                     | Wait for the block and verify the contract call succeeded. |
+| `confirmationTimeoutMs` | `number`                 | `60000`                    | How long to wait for confirmation.                         |
+
+Before sending, it:
+
+1. validates `to` and `tokenAddress`;
+2. reads the token's `decimals()` from the contract, so any TRC-20 token works, not only 6-decimal ones;
+3. converts `amount` using those decimals, rejecting amounts with too many decimal places;
+4. reads `balanceOf(sender)` and refuses if the balance is too low.
+
+The sender also needs **TRX** to pay for energy; see [Fees and resources](#fees-and-resources).
+
+```ts
+await transferToken({ to: 'TXYZ...', amount: '5' }); // 5 USDT
+await transferToken({ to: 'TXYZ...', amount: '0.25', tokenAddress: 'T...' }); // any TRC-20
+await transferToken({ to: 'TXYZ...', amount: '100', feeLimitSun: 30_000_000 }); // cap fees at 30 TRX
+```
+
+### `TronTransferError`
+
+The error class for transfer failures. It extends `Error` and adds:
+
+| Property | Type                  | Description                                                                                                                      |
+| -------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `txid`   | `string \| undefined` | Set when the transaction **reached the network**. If present, fees may have been charged; check the transaction before retrying. |
+
+The `message` includes the txid when there is one. See [Error handling](#error-handling) for the full list of failures.
+
+### `loadConfig(network?)`
+
+Reads and validates configuration from the environment. `transferTrx` and `transferToken` call it for you; it's exported for advanced use.
+
+```ts
+function loadConfig(network?: TronNetwork): NetworkConfig;
+```
+
+It defaults to `TRON_NETWORK`, and throws `Error` on missing or invalid variables.
+
+### `createTronWeb(config)`
+
+Creates a TronWeb instance from a `NetworkConfig`, with the private key and API key header set. Use it to call TronWeb directly for anything the SDK doesn't cover:
+
+```ts
+import { createTronWeb, loadConfig } from '@zebec-network/tron-transfer-sdk';
+
+const tronWeb = createTronWeb(loadConfig('testnet'));
+const account = await tronWeb.trx.getAccount('TXYZ...');
+```
+
+```ts
+function createTronWeb(config: NetworkConfig): TronWeb;
+```
+
+### `toBaseUnits(amount, decimals)`
+
+Converts a human-readable amount into the smallest unit using exact `bigint` math. This is the same conversion the transfer functions use.
+
+```ts
+function toBaseUnits(amount: Amount, decimals: number): bigint;
+
+toBaseUnits('1.5', 6); // 1500000n
+toBaseUnits(10, 6); // 10000000n
+toBaseUnits('0.000001', 6); // 1n
+toBaseUnits('1.0000001', 6); // throws: more than 6 decimal places
+```
+
+It rejects zero, negative, non-numeric and over-precise amounts. It also rejects numbers that JavaScript prints in exponent form (such as `1e21`); pass those as strings.
+
+---
+
+## Types
+
+All types are exported from the package root.
+
+```ts
+type TronNetwork = 'mainnet' | 'testnet';
+
+/** Human-readable amount, e.g. "10" TRX or "2.5" USDT. Prefer strings to avoid float rounding. */
+type Amount = string | number;
+
+interface TransferOptions {
+  network?: TronNetwork; // default: TRON_NETWORK
+  waitForConfirmation?: boolean; // default: true
+  confirmationTimeoutMs?: number; // default: 60_000
+}
+
+interface TransferTrxParams extends TransferOptions {
+  to: string;
+  amount: Amount; // in TRX
+}
+
+interface TransferTokenParams extends TransferOptions {
+  to: string;
+  amount: Amount; // in whole tokens
+  tokenAddress?: string; // default: TRON_<NET>_USDT_CONTRACT
+  feeLimitSun?: number; // default: TRON_FEE_LIMIT_SUN
+}
+
+interface TransferResult {
+  txid: string;
+  network: TronNetwork;
+  from: string; // sender, derived from the private key
+  to: string;
+  rawAmount: string; // smallest unit: SUN for TRX, base units for tokens
+  confirmed: boolean; // false when waitForConfirmation is false
+  blockNumber?: number; // set when confirmed
+  feeSun?: number; // total fee paid, in SUN; set when confirmed
+}
+
+interface NetworkConfig {
+  network: TronNetwork;
+  fullHost: string;
+  apiKey: string | undefined;
+  privateKey: string;
+  usdtContract: string | undefined;
+  feeLimitSun: number;
+}
+```
+
+`rawAmount` is a string because token base units can exceed JavaScript's safe integer range. Use `BigInt(result.rawAmount)` to do arithmetic on it.
+
+Example result:
+
+```json
+{
+  "txid": "1a7cdfebe0d9dd0d6cfdeba64d6d8d7acd06be7f38dfa4e34bbfa6850f54b170",
+  "network": "testnet",
+  "from": "TVrt71K6kXpYx8mPdBbadEYZVikTWwFuv6",
+  "to": "TADdZ38GMHSebqx9bxAqGdZth2zWNMcGBa",
+  "rawAmount": "1",
+  "confirmed": true,
+  "blockNumber": 71387491,
+  "feeSun": 265000
+}
+```
+
+---
+
+## How a transfer works
+
+```
+load config ─► validate inputs ─► check balance ─► build tx ─► sign locally ─► broadcast ─► wait for block ─► verify result
+```
+
+1. **Load config** for the network and derive the sender address from the private key.
+2. **Validate** the recipient, the amount, and (for tokens) the contract address and its `decimals()`.
+3. **Check balance:** TRX via the full node, tokens via `balanceOf`.
+4. **Build** the transaction: `transactionBuilder.sendTrx` for TRX, or `transactionBuilder.triggerSmartContract` calling `transfer(address,uint256)` for tokens.
+5. **Sign** it locally with `trx.sign`. The private key is never sent anywhere.
+6. **Broadcast** it with `trx.sendRawTransaction`. If the node rejects it, the SDK throws with the decoded reason.
+7. **Wait for confirmation.** The SDK polls `getUnconfirmedTransactionInfo` every ~3 s (one TRON block) until the transaction appears in a block, up to `confirmationTimeoutMs`.
+8. **Verify.** If the transaction failed on-chain (for example a token contract revert or running out of energy), the SDK throws a `TronTransferError` with the txid.
+
+### Why confirmation is on by default
+
+A successful broadcast only means a node **accepted** the transaction. For a TRC-20 transfer, the contract call can still **revert** when it executes, and the TRX spent on energy is burned anyway. Only after the transaction is in a block can you tell whether it succeeded. With `waitForConfirmation: false` you get back `{ txid, confirmed: false }` right away, and checking the outcome is up to you.
+
+"Confirmed" here means **included in a block**. TRON considers a block irreversible ("solidified") after roughly 19 more blocks, about a minute. For high-value flows, you may want to wait for that too, using TronWeb's `trx.getTransactionInfo`.
+
+---
+
+## Fees and resources
+
+TRON charges fees in two resources. Each account gets some bandwidth free every day; beyond that, fees are paid by **burning TRX** from the sender.
+
+| Resource      | Used by                                              | If you don't have enough                                                                           |
+| ------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| **Bandwidth** | Every transaction (roughly proportional to its size) | TRX is burned. Accounts get free bandwidth daily; after that, a TRX transfer costs about 0.27 TRX. |
+| **Energy**    | Smart-contract calls, i.e. token transfers           | TRX is burned, capped by `feeLimitSun`. Staking TRX for energy avoids this.                        |
+
+Things to keep in mind:
+
+- **Token transfers need TRX.** A USDT transfer typically uses roughly 65k energy to an address that already holds USDT, and roughly double that to one that doesn't. If the sender has no staked energy, that is paid for in TRX, and the amount depends on the network's current energy price.
+- **`feeLimitSun` is a ceiling, not a price.** If a contract call needs more energy than the limit allows, it fails with `OUT_OF_ENERGY` and the TRX spent so far is still burned. The default of 100 TRX is generous for USDT.
+- **New accounts cost extra.** Sending TRX to an address that has never been used creates it on-chain. This costs the sender an extra ~1 TRX, plus a little bandwidth.
+- `TransferResult.feeSun` reports the **total** fee actually paid (bandwidth + energy), in SUN.
+
+---
+
+## Error handling
+
+There are two error types:
+
+- **`TronTransferError`**: anything about the transfer itself (addresses, balances, broadcast, on-chain result).
+- **Plain `Error`**: configuration problems (from `loadConfig`) and invalid amounts (from `toBaseUnits`). These are thrown before anything touches the network.
+
+| When         | Message (abridged)                                                | Type                | `txid` set? |
+| ------------ | ----------------------------------------------------------------- | ------------------- | ----------- |
+| Config       | `Missing required environment variable …`                         | `Error`             | –           |
+| Config       | `… PRIVATE_KEY must be a 64-character hex string.`                | `Error`             | –           |
+| Config       | `TRON_NETWORK must be "mainnet" or "testnet" …`                   | `Error`             | –           |
+| Config       | `TRON_FEE_LIMIT_SUN must be a positive integer …`                 | `Error`             | –           |
+| Amount       | `Invalid amount …` / `Amount must be greater than zero …`         | `Error`             | –           |
+| Amount       | `Amount … has more than N decimal places.`                        | `Error`             | –           |
+| Validation   | `Invalid recipient address …`                                     | `TronTransferError` | No          |
+| Validation   | `Recipient address is the same as the sender address.`            | `TronTransferError` | No          |
+| Validation   | `Invalid token contract address …`                                | `TronTransferError` | No          |
+| Validation   | `No token address given and TRON_<NET>_USDT_CONTRACT is not set.` | `TronTransferError` | No          |
+| Validation   | `Call to decimals() on … failed … Is this a TRC-20 contract …?`   | `TronTransferError` | No          |
+| Balance      | `Insufficient TRX balance …` / `Insufficient token balance …`     | `TronTransferError` | No          |
+| Build        | `Failed to build token transfer: …`                               | `TronTransferError` | No          |
+| Broadcast    | `Broadcast rejected: <code> <reason>`                             | `TronTransferError` | Yes         |
+| On-chain     | `Transaction failed on-chain: <reason>`                           | `TronTransferError` | Yes         |
+| Confirmation | `Transaction was broadcast but not confirmed within …`            | `TronTransferError` | Yes         |
+
+Guidance for retries:
+
+- **No `txid`:** nothing was sent and no fees were charged. It's safe to fix the problem and retry.
+- **`txid` set:** the transaction reached the network. For a confirmation timeout, it may still succeed. **Look the txid up on an explorer (or with `trx.getTransactionInfo`) before retrying**, or you may send twice.
+
+Errors from TronWeb or the network itself, such as connection failures, HTTP 429 rate limiting, or an unreachable node, are passed through unchanged.
+
+---
+
+## Networks and token addresses
+
+| Network            | Full host                        | USDT contract                        | Explorer                                           | Faucet                                          |
+| ------------------ | -------------------------------- | ------------------------------------ | -------------------------------------------------- | ----------------------------------------------- |
+| **Mainnet**        | `https://api.trongrid.io`        | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` | [tronscan.org](https://tronscan.org)               | –                                               |
+| **Nile** testnet   | `https://nile.trongrid.io`       | `TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf` | [nile.tronscan.org](https://nile.tronscan.org)     | [nileex.io](https://nileex.io/join/getJoinPage) |
+| **Shasta** testnet | `https://api.shasta.trongrid.io` | `TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs` | [shasta.tronscan.org](https://shasta.tronscan.org) | [shasta.tronex.io](https://shasta.tronex.io)    |
+
+The SDK has one `testnet` slot. Choose Nile or Shasta by setting `TRON_TESTNET_FULL_HOST` and `TRON_TESTNET_USDT_CONTRACT` to the matching pair. Testnet tokens have no real value.
+
+Always double-check a mainnet token contract address against the issuer or [tronscan.org](https://tronscan.org). Tokens sent to the wrong contract or address can't be recovered.
+
+---
+
+## Example CLI
+
+[`examples/transfer.ts`](examples/transfer.ts) is a small command-line wrapper around both functions. It runs directly from TypeScript through ts-node, so no build is needed, and it uses the network set by `TRON_NETWORK`.
+
+```bash
+npm run example -- trx   <toAddress> <amount>
+npm run example -- token <toAddress> <amount> [tokenAddress]
+
+# e.g.
+npm run example -- trx   TADdZ38GMHSebqx9bxAqGdZth2zWNMcGBa 1
+npm run example -- token TADdZ38GMHSebqx9bxAqGdZth2zWNMcGBa 2.5
+```
+
+It prints the `TransferResult` as JSON, or the error message with a non-zero exit code. **These are real transfers** on whichever network is configured.
+
+---
+
+## Development
+
+Clone the repository and install dependencies:
+
+```bash
+git clone https://github.com/Zebec-Fintech-Labs/tron-transfer-sdk.git
+cd tron-transfer-sdk
+npm install
+cp .env.example .env
+```
+
+### Scripts
+
+| Script              | Description                                                                             |
+| ------------------- | --------------------------------------------------------------------------------------- |
+| `npm run build`     | Cleans `dist/` and compiles `src/` into it (JS, `.d.ts`, source maps).                  |
+| `npm run clean`     | Removes the `dist/` directory.                                                          |
+| `npm run format`    | Formats the codebase with Prettier.                                                     |
+| `npm test`          | Runs the Mocha test suite via ts-mocha, against the network set by `TRON_TEST_NETWORK`. |
+| `npm run typecheck` | Type-checks `src/`, `test/` and `examples/`.                                            |
+| `npm run example`   | Runs the [example CLI](#example-cli).                                                   |
+
+### Running tests
+
+The tests use **Mocha** through **ts-mocha**, with Node's built-in `node:assert`. They make **live transfers** on the network set by `TRON_TEST_NETWORK` (default `testnet`); there are no mocks.
+
+```bash
+npm test
+```
+
+They need these variables in `.env` (see [Configuration](#configuration)):
+
+| Test network        | Required variables                                                                                                                                             |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `testnet` (default) | `TRON_TESTNET_FULL_HOST`, `TRON_TESTNET_PRIVATE_KEY` (sender funded with TRX, plus USDT from the faucet), `TRON_TESTNET_USDT_CONTRACT`, `TRON_TEST_RECIPIENT`  |
+| `mainnet`           | `TRON_TEST_NETWORK=mainnet`, `TRON_MAINNET_FULL_HOST`, `TRON_MAINNET_API_KEY`, `TRON_MAINNET_PRIVATE_KEY`, `TRON_MAINNET_USDT_CONTRACT`, `TRON_MAIN_RECIPIENT` |
+
+Use a recipient you control so you can reuse the funds. **On mainnet the tests spend real TRX and USDT.**
+
+What's covered (19 tests):
+
+| File                                                       | Live transfers                                                                                                            | Validation (nothing is sent)                                                                             |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| [`test/transferTrx.test.ts`](test/transferTrx.test.ts)     | 0.5 TRX with recipient balance check; 0.5 TRX as a number; `waitForConfirmation: false`                                   | Bad address, self-send, zero / negative / non-numeric / over-precise amounts, insufficient balance       |
+| [`test/transferToken.test.ts`](test/transferToken.test.ts) | 0.5 USDT via the default contract with balance check; 0.25 USDT via explicit `tokenAddress`; `waitForConfirmation: false` | Bad recipient, self-send, bad token address, non-TRC-20 address, too many decimals, insufficient balance |
+
+- **Cost per run:** about 1 TRX and 0.75 USDT go to the recipient, plus network fees (up to ~0.3 TRX per TRX transfer once the sender's free bandwidth is used up; USDT transfers also burn TRX for energy unless the sender has staked energy).
+- **Duration:** about 25 s.
+- The test files run one after the other with a generous timeout (`-t 1000000`), since each live transfer waits for a block.
+
+---
+
+## Project structure
+
+```
+tron-transfer-sdk/
+├── src/
+│   ├── index.ts          # Public exports
+│   ├── services.ts       # transferTrx, transferToken, TronTransferError
+│   ├── config.ts         # Env loading and validation (loadConfig)
+│   ├── client.ts         # TronWeb instance factory (createTronWeb)
+│   ├── types.ts          # Public parameter and result types
+│   └── utils.ts          # Exact amount conversion (toBaseUnits)
+├── test/
+│   ├── helpers.ts        # Shared test setup and balance readers
+│   ├── transferTrx.test.ts
+│   └── transferToken.test.ts
+├── examples/
+│   └── transfer.ts       # Example CLI
+├── dist/                 # Build output (the only folder that gets published)
+├── .env.example          # Configuration template
+├── .mocharc.json         # Mocha: test paths + ts-node ESM loader
+├── .prettierrc.json      # Formatting rules
+├── tsconfig.json         # Type-checking for src, test, examples (editor, typecheck, tests)
+└── tsconfig.build.json   # Build config: src/ → dist/
+```
+
+---
+
+## Dependencies
+
+### Runtime
+
+| Package                                                     | Why                                                                                                   |
+| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| [`tronweb`](https://www.npmjs.com/package/tronweb) `^6.5.1` | The official TRON JavaScript SDK: builds, signs and broadcasts transactions, and talks to full nodes. |
+| [`dotenv`](https://www.npmjs.com/package/dotenv) `^18`      | Loads `.env` when the SDK is imported.                                                                |
+
+### Development
+
+| Package                       | Why                                                                                                                                |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `typescript` `^6`             | Compiler. **Pinned to 6** because ts-node (and so ts-mocha) needs TypeScript's JavaScript API, which TypeScript 7 no longer ships. |
+| `ts-node`                     | Runs TypeScript directly for the tests and the example CLI.                                                                        |
+| `mocha` `^11`, `ts-mocha`     | Test runner. Mocha stays on 11 because ts-mocha doesn't support 12 yet.                                                            |
+| `@types/mocha`, `@types/node` | Type definitions.                                                                                                                  |
+| `prettier`                    | Code formatting.                                                                                                                   |
+| `rimraf`                      | Cross-platform `dist/` cleanup.                                                                                                    |
+
+### A note on the test setup
+
+The package is ESM (`"type": "module"`). ts-mocha on its own only sets up a CommonJS hook, which Mocha bypasses when it loads ES-module test files. [`.mocharc.json`](.mocharc.json) therefore also registers `ts-node/esm` as a Node loader. It silences two harmless warnings that loader triggers on recent Node versions (`ExperimentalWarning` and `DEP0180`).
+
+---
+
+## Troubleshooting
+
+| Symptom                                                    | Likely cause and fix                                                                                                                                                       |
+| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Missing required environment variable TRON_…`             | `.env` isn't in the **current working directory** of the process, or the variable is empty. Run from the folder containing `.env`, or set the variable in the environment. |
+| HTTP 429 / rate-limit errors on mainnet                    | Set `TRON_MAINNET_API_KEY`.                                                                                                                                                |
+| `Insufficient TRX balance` right after funding the account | The new funds haven't reached the node yet. Wait one or two blocks (~6 s) and retry.                                                                                       |
+| `Call to decimals() on … failed`                           | The token address isn't a TRC-20 contract **on the selected network**. A common mistake is using the mainnet USDT address on testnet, or vice versa.                       |
+| `Transaction failed on-chain: OUT_OF_ENERGY`               | `feeLimitSun` was too low, or the sender ran out of TRX for energy. Raise the limit or add TRX, and check the txid.                                                        |
+| `Transaction was broadcast but not confirmed within …`     | The network is slow or congested. Look up the txid **before** retrying; it may still succeed.                                                                              |
+| `Broadcast rejected: … balance is not sufficient`          | The balance covers the amount but not the fees. Leave some TRX for bandwidth and energy.                                                                                   |
+| TypeScript errors inside `node_modules/tronweb/...`        | Enable `"skipLibCheck": true` in your tsconfig.                                                                                                                            |
+| `ERR_REQUIRE_ESM` or `require() of ES Module`              | The package is ESM-only. Use `import`, or dynamic `import()` from CommonJS.                                                                                                |
+
+---
+
+## References
+
+- [Source repository](https://github.com/Zebec-Fintech-Labs/tron-transfer-sdk) ([issues](https://github.com/Zebec-Fintech-Labs/tron-transfer-sdk/issues))
+- [TRON: Send your first transaction](https://developers.tron.network/docs/send-first-transaction)
+- [TRON: TRC-20 contract interaction](https://developers.tron.network/docs/trc20-contract-interaction)
+- [TRON: Resource model (bandwidth and energy)](https://developers.tron.network/docs/resource-model)
+- [TronWeb documentation](https://tronweb.network/docu/docs/intro)
+- [TronGrid (API keys)](https://www.trongrid.io)
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,4 @@
+import { TronWeb } from 'tronweb';
+import type { NetworkConfig } from './config.js';
+export declare function createTronWeb(config: NetworkConfig): TronWeb;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAM5D"}

package/dist/client.js

@@ -0,0 +1,9 @@
+import { TronWeb } from 'tronweb';
+export function createTronWeb(config) {
+    return new TronWeb({
+        fullHost: config.fullHost,
+        privateKey: config.privateKey,
+        ...(config.apiKey ? { headers: { 'TRON-PRO-API-KEY': config.apiKey } } : {}),
+    });
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAGlC,MAAM,UAAU,aAAa,CAAC,MAAqB;IACjD,OAAO,IAAI,OAAO,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC7E,CAAC,CAAC;AACL,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,16 @@
+import 'dotenv/config';
+export type TronNetwork = 'mainnet' | 'testnet';
+export interface NetworkConfig {
+    network: TronNetwork;
+    fullHost: string;
+    apiKey: string | undefined;
+    privateKey: string;
+    usdtContract: string | undefined;
+    feeLimitSun: number;
+}
+/**
+ * Reads the configuration for a network from environment variables.
+ * Defaults to the network named by TRON_NETWORK.
+ */
+export declare function loadConfig(network?: TronNetwork): NetworkConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,eAAe,CAAC;AAEvB,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC;AAEhD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,WAAW,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;CACrB;AAkCD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,WAAmD,GAAG,aAAa,CAuBtG"}

package/dist/config.js

@@ -0,0 +1,55 @@
+import 'dotenv/config';
+const DEFAULT_FEE_LIMIT_SUN = 100_000_000; // 100 TRX
+function readEnv(name) {
+    const value = process.env[name]?.trim();
+    return value ? value : undefined;
+}
+function requireEnv(name) {
+    const value = readEnv(name);
+    if (!value) {
+        throw new Error(`Missing required environment variable ${name}. See .env.example.`);
+    }
+    return value;
+}
+function parseNetwork(value) {
+    const network = (value ?? 'testnet').toLowerCase();
+    if (network !== 'mainnet' && network !== 'testnet') {
+        throw new Error(`TRON_NETWORK must be "mainnet" or "testnet", got "${value}".`);
+    }
+    return network;
+}
+function parseFeeLimit(value) {
+    if (value === undefined)
+        return DEFAULT_FEE_LIMIT_SUN;
+    const feeLimit = Number(value);
+    if (!Number.isSafeInteger(feeLimit) || feeLimit <= 0) {
+        throw new Error(`TRON_FEE_LIMIT_SUN must be a positive integer (in SUN), got "${value}".`);
+    }
+    return feeLimit;
+}
+/**
+ * Reads the configuration for a network from environment variables.
+ * Defaults to the network named by TRON_NETWORK.
+ */
+export function loadConfig(network = parseNetwork(readEnv('TRON_NETWORK'))) {
+    const prefix = `TRON_${network.toUpperCase()}`;
+    const privateKey = requireEnv(`${prefix}_PRIVATE_KEY`).replace(/^0x/i, '');
+    if (!/^[0-9a-fA-F]{64}$/.test(privateKey)) {
+        throw new Error(`${prefix}_PRIVATE_KEY must be a 64-character hex string.`);
+    }
+    const fullHost = requireEnv(`${prefix}_FULL_HOST`);
+    const apiKey = readEnv(`${prefix}_API_KEY`);
+    if (network === 'mainnet' && !apiKey && /(^|\.)trongrid\.io$/i.test(new URL(fullHost).hostname)) {
+        // Keyless TronGrid mainnet requests get HTTP 429 after a few calls, often mid-transfer.
+        throw new Error(`${prefix}_API_KEY is required for ${fullHost}. Get one at https://www.trongrid.io.`);
+    }
+    return {
+        network,
+        fullHost,
+        apiKey,
+        privateKey,
+        usdtContract: readEnv(`${prefix}_USDT_CONTRACT`),
+        feeLimitSun: parseFeeLimit(readEnv('TRON_FEE_LIMIT_SUN')),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,eAAe,CAAC;AAavB,MAAM,qBAAqB,GAAG,WAAW,CAAC,CAAC,UAAU;AAErD,SAAS,OAAO,CAAC,IAAY;IAC3B,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC;IACxC,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACnC,CAAC;AAED,SAAS,UAAU,CAAC,IAAY;IAC9B,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,yCAAyC,IAAI,qBAAqB,CAAC,CAAC;IACtF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,YAAY,CAAC,KAAyB;IAC7C,MAAM,OAAO,GAAG,CAAC,KAAK,IAAI,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC;IACnD,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QACnD,MAAM,IAAI,KAAK,CAAC,qDAAqD,KAAK,IAAI,CAAC,CAAC;IAClF,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,aAAa,CAAC,KAAyB;IAC9C,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,qBAAqB,CAAC;IACtD,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC/B,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CAAC,gEAAgE,KAAK,IAAI,CAAC,CAAC;IAC7F,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,UAAuB,YAAY,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IACrF,MAAM,MAAM,GAAG,QAAQ,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC;IAC/C,MAAM,UAAU,GAAG,UAAU,CAAC,GAAG,MAAM,cAAc,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAE3E,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,GAAG,MAAM,iDAAiD,CAAC,CAAC;IAC9E,CAAC;IAED,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,MAAM,YAAY,CAAC,CAAC;IACnD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,MAAM,UAAU,CAAC,CAAC;IAC5C,IAAI,OAAO,KAAK,SAAS,IAAI,CAAC,MAAM,IAAI,sBAAsB,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;QAChG,wFAAwF;QACxF,MAAM,IAAI,KAAK,CAAC,GAAG,MAAM,4BAA4B,QAAQ,uCAAuC,CAAC,CAAC;IACxG,CAAC;IAED,OAAO;QACL,OAAO;QACP,QAAQ;QACR,MAAM;QACN,UAAU;QACV,YAAY,EAAE,OAAO,CAAC,GAAG,MAAM,gBAAgB,CAAC;QAChD,WAAW,EAAE,aAAa,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC;KAC1D,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { transferTrx, transferToken, TronTransferError } from './services.js';
+export { loadConfig } from './config.js';
+export type { NetworkConfig, TronNetwork } from './config.js';
+export { createTronWeb } from './client.js';
+export { toBaseUnits } from './utils.js';
+export type { Amount, TransferOptions, TransferResult, TransferTokenParams, TransferTrxParams } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,YAAY,EAAE,MAAM,EAAE,eAAe,EAAE,cAAc,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { transferTrx, transferToken, TronTransferError } from './services.js';
+export { loadConfig } from './config.js';
+export { createTronWeb } from './client.js';
+export { toBaseUnits } from './utils.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/services.d.ts

@@ -0,0 +1,23 @@
+import type { TransferResult, TransferTokenParams, TransferTrxParams } from './types.js';
+/** Thrown for any failed transfer. `txid` is set when the transaction reached the network. */
+export declare class TronTransferError extends Error {
+    readonly txid: string | undefined;
+    constructor(message: string, txid?: string);
+}
+/**
+ * Sends native TRX from the account configured in .env.
+ *
+ * @example
+ * await transferTrx({ to: 'TXYZ...', amount: '10' }); // 10 TRX
+ */
+export declare function transferTrx(params: TransferTrxParams): Promise<TransferResult>;
+/**
+ * Sends a TRC-20 token (USDT by default) from the account configured in .env.
+ * The sender needs TRX to pay for energy; up to `feeLimitSun` may be burned.
+ *
+ * @example
+ * await transferToken({ to: 'TXYZ...', amount: '5' }); // 5 USDT
+ * await transferToken({ to: 'TXYZ...', amount: '1.25', tokenAddress: 'T...' }); // any TRC-20
+ */
+export declare function transferToken(params: TransferTokenParams): Promise<TransferResult>;
+//# sourceMappingURL=services.d.ts.map

package/dist/services.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"services.d.ts","sourceRoot":"","sources":["../src/services.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAmB,cAAc,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAO1G,8FAA8F;AAC9F,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEtB,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;CAK3C;AAqHD;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CAqBpF;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC,CAwCxF"}

package/dist/services.js

@@ -0,0 +1,148 @@
+import { TronWeb } from 'tronweb';
+import { createTronWeb } from './client.js';
+import { loadConfig } from './config.js';
+import { sleep, toBaseUnits } from './utils.js';
+const TRX_DECIMALS = 6; // 1 TRX = 1,000,000 SUN
+const DEFAULT_CONFIRMATION_TIMEOUT_MS = 60_000;
+const CONFIRMATION_POLL_INTERVAL_MS = 3_000; // roughly one TRON block
+/** Thrown for any failed transfer. `txid` is set when the transaction reached the network. */
+export class TronTransferError extends Error {
+    txid;
+    constructor(message, txid) {
+        super(txid ? `${message} (txid: ${txid})` : message);
+        this.name = 'TronTransferError';
+        this.txid = txid;
+    }
+}
+function openSession(network) {
+    const config = loadConfig(network);
+    const from = TronWeb.address.fromPrivateKey(config.privateKey);
+    if (!from) {
+        throw new TronTransferError('Could not derive an address from the configured private key.');
+    }
+    return { config, tronWeb: createTronWeb(config), from };
+}
+function assertRecipient(to, from) {
+    if (!TronWeb.isAddress(to)) {
+        throw new TronTransferError(`Invalid recipient address "${to}".`);
+    }
+    if (TronWeb.address.toHex(to) === TronWeb.address.toHex(from)) {
+        throw new TronTransferError('Recipient address is the same as the sender address.');
+    }
+}
+/** Node error messages are often hex-encoded UTF-8; decode them when possible. */
+function decodeNodeMessage(message) {
+    if (!message)
+        return 'unknown error';
+    if (/^[0-9a-fA-F]+$/.test(message) && message.length % 2 === 0) {
+        return Buffer.from(message, 'hex').toString('utf8');
+    }
+    return message;
+}
+async function signAndBroadcast(tronWeb, transaction) {
+    const signed = (await tronWeb.trx.sign(transaction));
+    const broadcast = await tronWeb.trx.sendRawTransaction(signed);
+    if (!broadcast.result) {
+        throw new TronTransferError(`Broadcast rejected: ${broadcast.code ?? 'ERROR'} ${decodeNodeMessage(broadcast.message)}`, broadcast.txid || signed.txID);
+    }
+    return broadcast.txid || signed.txID;
+}
+/** Polls until the transaction is in a block, then throws if it failed on-chain. */
+async function waitForConfirmation(tronWeb, txid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        await sleep(CONFIRMATION_POLL_INTERVAL_MS);
+        const info = await tronWeb.trx.getUnconfirmedTransactionInfo(txid);
+        if (!info?.id)
+            continue;
+        const receiptResult = info.receipt?.result;
+        if (info.result === 'FAILED' || (receiptResult && receiptResult !== 'SUCCESS')) {
+            const reason = decodeNodeMessage(info.resMessage) || receiptResult || 'FAILED';
+            throw new TronTransferError(`Transaction failed on-chain: ${reason}`, txid);
+        }
+        return info;
+    }
+    throw new TronTransferError(`Transaction was broadcast but not confirmed within ${timeoutMs}ms. Check its status before retrying to avoid a double send`, txid);
+}
+async function finalize(session, txid, to, rawAmount, options) {
+    const result = {
+        txid,
+        network: session.config.network,
+        from: session.from,
+        to,
+        rawAmount: rawAmount.toString(),
+        confirmed: false,
+    };
+    if (options.waitForConfirmation === false)
+        return result;
+    const info = await waitForConfirmation(session.tronWeb, txid, options.confirmationTimeoutMs ?? DEFAULT_CONFIRMATION_TIMEOUT_MS);
+    return { ...result, confirmed: true, blockNumber: info.blockNumber, feeSun: info.fee ?? 0 };
+}
+async function callConstant(session, contractAddress, functionSelector, parameters = []) {
+    const response = await session.tronWeb.transactionBuilder.triggerConstantContract(contractAddress, functionSelector, {}, parameters, session.from);
+    const hex = response.constant_result?.[0];
+    if (!response.result?.result || typeof hex !== 'string' || hex.length === 0) {
+        throw new TronTransferError(`Call to ${functionSelector} on ${contractAddress} failed: ${decodeNodeMessage(response.result?.message)}. Is this a TRC-20 contract on the ${session.config.network}?`);
+    }
+    return BigInt(`0x${hex}`);
+}
+/**
+ * Sends native TRX from the account configured in .env.
+ *
+ * @example
+ * await transferTrx({ to: 'TXYZ...', amount: '10' }); // 10 TRX
+ */
+export async function transferTrx(params) {
+    const session = openSession(params.network);
+    const { tronWeb, from } = session;
+    assertRecipient(params.to, from);
+    const amountSun = toBaseUnits(params.amount, TRX_DECIMALS);
+    if (amountSun > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new TronTransferError(`Amount ${params.amount} TRX is too large.`);
+    }
+    // getBalance() reads solidified state (~1 min behind); use the full node's latest view instead.
+    const balanceSun = BigInt(await tronWeb.trx.getUnconfirmedBalance(from));
+    if (balanceSun < amountSun) {
+        throw new TronTransferError(`Insufficient TRX balance: have ${balanceSun} SUN, need ${amountSun} SUN (plus fees if bandwidth is exhausted).`);
+    }
+    const transaction = await tronWeb.transactionBuilder.sendTrx(params.to, Number(amountSun), from);
+    const txid = await signAndBroadcast(tronWeb, transaction);
+    return finalize(session, txid, params.to, amountSun, params);
+}
+/**
+ * Sends a TRC-20 token (USDT by default) from the account configured in .env.
+ * The sender needs TRX to pay for energy; up to `feeLimitSun` may be burned.
+ *
+ * @example
+ * await transferToken({ to: 'TXYZ...', amount: '5' }); // 5 USDT
+ * await transferToken({ to: 'TXYZ...', amount: '1.25', tokenAddress: 'T...' }); // any TRC-20
+ */
+export async function transferToken(params) {
+    const session = openSession(params.network);
+    const { tronWeb, from, config } = session;
+    assertRecipient(params.to, from);
+    const tokenAddress = params.tokenAddress ?? config.usdtContract;
+    if (!tokenAddress) {
+        throw new TronTransferError(`No token address given and TRON_${config.network.toUpperCase()}_USDT_CONTRACT is not set.`);
+    }
+    if (!TronWeb.isAddress(tokenAddress)) {
+        throw new TronTransferError(`Invalid token contract address "${tokenAddress}".`);
+    }
+    const decimals = Number(await callConstant(session, tokenAddress, 'decimals()'));
+    const amount = toBaseUnits(params.amount, decimals);
+    // A TRC-20 transfer that reverts still burns energy, so check the balance up front.
+    const balance = await callConstant(session, tokenAddress, 'balanceOf(address)', [{ type: 'address', value: from }]);
+    if (balance < amount) {
+        throw new TronTransferError(`Insufficient token balance: have ${balance}, need ${amount} (base units).`);
+    }
+    const { result, transaction } = await tronWeb.transactionBuilder.triggerSmartContract(tokenAddress, 'transfer(address,uint256)', { feeLimit: params.feeLimitSun ?? config.feeLimitSun, callValue: 0 }, [
+        { type: 'address', value: params.to },
+        { type: 'uint256', value: amount.toString() },
+    ], from);
+    if (!result?.result) {
+        throw new TronTransferError(`Failed to build token transfer: ${decodeNodeMessage(result?.message)}`);
+    }
+    const txid = await signAndBroadcast(tronWeb, transaction);
+    return finalize(session, txid, params.to, amount, params);
+}
+//# sourceMappingURL=services.js.map

package/dist/services.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"services.js","sourceRoot":"","sources":["../src/services.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,45 @@
+import type { TronNetwork } from './config.js';
+/** Human-readable amount, e.g. "10" TRX or "2.5" USDT. Strings avoid floating-point rounding. */
+export type Amount = string | number;
+export interface TransferOptions {
+    /** Network to use. Defaults to TRON_NETWORK from .env. */
+    network?: TronNetwork;
+    /**
+     * Wait until the transaction is included in a block and check it succeeded.
+     * Broadcast success alone does not mean a TRC-20 transfer executed. Default: true.
+     */
+    waitForConfirmation?: boolean;
+    /** How long to wait for confirmation, in milliseconds. Default: 60_000. */
+    confirmationTimeoutMs?: number;
+}
+export interface TransferTrxParams extends TransferOptions {
+    /** Recipient base58 address (T...). */
+    to: string;
+    /** Amount in TRX (not SUN). */
+    amount: Amount;
+}
+export interface TransferTokenParams extends TransferOptions {
+    /** Recipient base58 address (T...). */
+    to: string;
+    /** Amount in whole tokens (e.g. "5" USDT), converted using the token's decimals. */
+    amount: Amount;
+    /** TRC-20 contract address. Defaults to the USDT contract configured for the network. */
+    tokenAddress?: string;
+    /** Max TRX (in SUN) to burn for energy. Defaults to TRON_FEE_LIMIT_SUN. */
+    feeLimitSun?: number;
+}
+export interface TransferResult {
+    txid: string;
+    network: TronNetwork;
+    from: string;
+    to: string;
+    /** Amount in the smallest unit (SUN for TRX, token base units for TRC-20). */
+    rawAmount: string;
+    /** True once the transaction is confirmed in a block; false if confirmation was not awaited. */
+    confirmed: boolean;
+    /** Block number, when confirmed. */
+    blockNumber?: number;
+    /** Total fee paid in SUN, when confirmed. */
+    feeSun?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,iGAAiG;AACjG,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAErC,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,2EAA2E;IAC3E,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACxD,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAoB,SAAQ,eAAe;IAC1D,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,oFAAoF;IACpF,MAAM,EAAE,MAAM,CAAC;IACf,yFAAyF;IACzF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,WAAW,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,8EAA8E;IAC9E,SAAS,EAAE,MAAM,CAAC;IAClB,gGAAgG;IAChG,SAAS,EAAE,OAAO,CAAC;IACnB,oCAAoC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/utils.d.ts

@@ -0,0 +1,8 @@
+import type { Amount } from './types.js';
+/**
+ * Converts a human-readable amount into the smallest unit using exact integer math,
+ * e.g. toBaseUnits("1.5", 6) === 1_500_000n.
+ */
+export declare function toBaseUnits(amount: Amount, decimals: number): bigint;
+export declare function sleep(ms: number): Promise<void>;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAmBpE;AAaD,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C"}

package/dist/utils.js

@@ -0,0 +1,35 @@
+/**
+ * Converts a human-readable amount into the smallest unit using exact integer math,
+ * e.g. toBaseUnits("1.5", 6) === 1_500_000n.
+ */
+export function toBaseUnits(amount, decimals) {
+    const text = typeof amount === 'number' ? numberToPlainString(amount) : amount.trim();
+    const match = /^(\d+)(?:\.(\d*))?$/.exec(text);
+    if (!match) {
+        throw new Error(`Invalid amount "${amount}". Use a positive decimal like "10" or "0.5".`);
+    }
+    const whole = match[1] ?? '0';
+    const fraction = match[2] ?? '';
+    if (fraction.length > decimals) {
+        throw new Error(`Amount "${amount}" has more than ${decimals} decimal places.`);
+    }
+    const units = BigInt(whole + fraction.padEnd(decimals, '0'));
+    if (units <= 0n) {
+        throw new Error(`Amount must be greater than zero, got "${amount}".`);
+    }
+    return units;
+}
+function numberToPlainString(value) {
+    if (!Number.isFinite(value)) {
+        throw new Error(`Invalid amount ${value}.`);
+    }
+    const text = String(value);
+    if (/e/i.test(text)) {
+        throw new Error(`Amount ${value} is too large or small for a number; pass it as a string instead.`);
+    }
+    return text;
+}
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,QAAgB;IAC1D,MAAM,IAAI,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IAEtF,MAAM,KAAK,GAAG,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,mBAAmB,MAAM,+CAA+C,CAAC,CAAC;IAC5F,CAAC;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC;IAC9B,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAChC,IAAI,QAAQ,CAAC,MAAM,GAAG,QAAQ,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,WAAW,MAAM,mBAAmB,QAAQ,kBAAkB,CAAC,CAAC;IAClF,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC;IAC7D,IAAI,KAAK,IAAI,EAAE,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,0CAA0C,MAAM,IAAI,CAAC,CAAC;IACxE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,mBAAmB,CAAC,KAAa;IACxC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,kBAAkB,KAAK,GAAG,CAAC,CAAC;IAC9C,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC3B,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,UAAU,KAAK,mEAAmE,CAAC,CAAC;IACtG,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,EAAU;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@zebec-network/tron-transfer-sdk",
+  "version": "1.0.0",
+  "description": "Minimal SDK for transferring TRX and TRC-20 tokens (e.g. USDT) on TRON mainnet and testnet",
+  "main": "dist/index.js",
+  "type": "module",
+  "types": "dist/index.d.ts",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^26.6.3",
+    "mocha": "^11.7.5",
+    "prettier": "^3.9.9",
+    "rimraf": "^6.1.3",
+    "ts-mocha": "^11.1.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^6.0.3"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "clean": "rimraf ./dist",
+    "format": "prettier --write .",
+    "test": "ts-mocha -p ./tsconfig.json -t 1000000",
+    "typecheck": "tsc --noEmit",
+    "example": "node --loader ts-node/esm --disable-warning=ExperimentalWarning --disable-warning=DEP0180 examples/transfer.ts"
+  },
+  "dependencies": {
+    "dotenv": "^18.0.4",
+    "tronweb": "^6.5.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zebec-Fintech-Labs/tron-transfer-sdk.git"
+  }
+}