@zebec-network/tron-transfer-sdk 1.0.0 → 2.0.0

package/README.md

@@ -2,11 +2,11 @@
 
 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:
+It wraps [TronWeb](https://tronweb.network) in a `TronTransferService` class with `transferTrx` and `transferToken` methods. The service is given a **signer**: in a web app, the user's connected wallet (TronLink and others, through the TronWallet adapter); in Node, a private key. Each transfer takes care of the fiddly parts:
 
 - **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.
+- **Build, sign, broadcast.** The SDK builds the transaction, the signer signs it (the wallet asks the user to approve), and the SDK broadcasts it. The SDK itself never holds a key.
 - **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.
 
@@ -18,6 +18,7 @@ It wraps [TronWeb](https://tronweb.network) with two functions, `transferTrx` an
 - [Installation](#installation)
 - [Configuration](#configuration)
 - [Quick start](#quick-start)
+- [Frontend: signing with the user's wallet](#frontend-signing-with-the-users-wallet)
 - [API reference](#api-reference)
 - [Types](#types)
 - [How a transfer works](#how-a-transfer-works)
@@ -42,7 +43,7 @@ It wraps [TronWeb](https://tronweb.network) with two functions, `transferTrx` an
 | 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).                                      |
+| TronGrid key   | **Required for mainnet** (`api.trongrid.io`), in the browser and in Node; 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`.
 
@@ -56,10 +57,19 @@ npm install @zebec-network/tron-transfer-sdk
 yarn add @zebec-network/tron-transfer-sdk
 ```
 
-Then import it:
+The package has two entry points:
+
+| Import path                             | Environment   | Contents                                                                                                            |
+| --------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `@zebec-network/tron-transfer-sdk`      | Browser, Node | `TronTransferService`, signers, config helpers, types. No `dotenv`, no filesystem or `process.env` access.          |
+| `@zebec-network/tron-transfer-sdk/node` | Node only     | Everything above, plus `loadConfig()` and the `.env`-driven `transferTrx()` / `transferToken()` shortcut functions. |
 
 ```ts
-import { transferTrx, transferToken } from '@zebec-network/tron-transfer-sdk';
+// Web app
+import { TronTransferService } from '@zebec-network/tron-transfer-sdk';
+
+// Node script or backend
+import { transferTrx, transferToken } from '@zebec-network/tron-transfer-sdk/node';
 ```
 
 To work on the SDK itself, see [Development](#development).
@@ -68,7 +78,9 @@ 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).
+This section is about the **Node entry** (`/node`). In a web app, pass settings straight to `TronTransferService` instead; see [`TronTransferServiceConfig`](#new-trontransferservicesigner-config).
+
+The Node entry 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:
 
@@ -87,12 +99,12 @@ cp .env.example .env
 
 **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.                                                                                         |
+| 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 TronGrid requests are limited per IP to about 1 request/s, which a token transfer can exceed, so the SDK refuses to run on mainnet TronGrid without one. |
+| `TRON_<NET>_USDT_CONTRACT` | No                       | Default token for `transferToken` when no `tokenAddress` is passed. If unset, USDT is used when the host is a TronGrid mainnet, Nile or Shasta host.                                                                      |
 
 **Tests only**
 
@@ -128,8 +140,10 @@ Configuration is read on **every call**, so each call checks only the network it
 
 ## Quick start
 
+In Node, with the sender's key in `.env`:
+
 ```ts
-import { transferTrx, transferToken, TronTransferError } from '@zebec-network/tron-transfer-sdk';
+import { transferTrx, transferToken, TronTransferError } from '@zebec-network/tron-transfer-sdk/node';
 
 // Send 10 TRX on the network set by TRON_NETWORK
 const trx = await transferTrx({ to: 'TXYZ...recipient', amount: '10' });
@@ -160,13 +174,169 @@ try {
 
 ---
 
+## Frontend: signing with the user's wallet
+
+In a web app there is no `.env` private key. The user's wallet signs instead. `TronTransferService` takes any object with this shape:
+
+```ts
+interface TronSigner {
+  readonly address: string | null; // connected account, or null when disconnected
+  signTransaction(transaction: Transaction): Promise<SignedTransaction>;
+}
+```
+
+That is exactly the interface of the [TronWallet adapters](https://github.com/web3-geek/tronwallet-adapter) (`TronLinkAdapter`, `WalletConnectAdapter`, …) and of `useWallet()` from their React hooks, so you pass them in directly. There's no glue code to write.
+
+### React, with `@tronweb3/tronwallet-adapter-react-hooks`
+
+```tsx
+import { useMemo } from 'react';
+import { useWallet } from '@tronweb3/tronwallet-adapter-react-hooks';
+import { TronTransferService, TronTransferError } from '@zebec-network/tron-transfer-sdk';
+
+function useTronTransfers() {
+  const { address, signTransaction } = useWallet();
+  return useMemo(
+    () =>
+      new TronTransferService(
+        { address, signTransaction },
+        { network: 'mainnet', apiKey: import.meta.env.VITE_TRONGRID_KEY }, // required on mainnet TronGrid
+      ),
+    [address, signTransaction],
+  );
+}
+
+function SendUsdtButton({ to, amount }: { to: string; amount: string }) {
+  const service = useTronTransfers();
+
+  async function send() {
+    try {
+      // The wallet pops up to approve; the promise resolves once the transfer is confirmed in a block.
+      const result = await service.transferToken({ to, amount });
+      console.log('Sent', result.txid);
+    } catch (error) {
+      if (error instanceof TronTransferError && !error.txid) {
+        // Nothing was broadcast: validation failed, balance too low, or the user rejected the request.
+        // For a rejection, `error.cause` is the wallet's original error.
+      }
+      throw error;
+    }
+  }
+
+  return <button onClick={send}>Send {amount} USDT</button>;
+}
+```
+
+### Plain adapter, no React
+
+```ts
+import { TronLinkAdapter } from '@tronweb3/tronwallet-adapters';
+import { TronTransferService } from '@zebec-network/tron-transfer-sdk';
+
+const adapter = new TronLinkAdapter();
+await adapter.connect();
+
+const service = new TronTransferService(adapter, { network: 'testnet' }); // Nile by default
+await service.transferTrx({ to: 'TXYZ...', amount: '1' });
+const usdt = await service.getTokenBalance(); // connected account's USDT, e.g. "12.5"
+```
+
+### Rate limits (HTTP 429)
+
+TronGrid can answer bursts with **HTTP 429**, even with an API key (and far more often without one, which is why mainnet requires it). The service handles this by stage:
+
+| Stage                                           | What the SDK does                                                                                                                                                            | If it still fails                                                               |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| Checks and build (balances, decimals, tx build) | Retries with exponential backoff and jitter (~1 s, ~2 s, ~4 s; `rateLimitRetries`, default 3).                                                                               | `code: 'RATE_LIMITED'`, **no `txid`**: nothing was sent. Safe to offer a retry. |
+| Broadcast                                       | Resends the **same signed transaction**. It has the same txid, so it can't be sent twice, and the wallet isn't asked to sign again. A duplicate on resend counts as success. | `code: 'RATE_LIMITED'` **with `txid`**: check the txid before retrying.         |
+| Confirmation                                    | The transfer is already sent, so it keeps polling and slows down on 429 (up to 15 s between polls).                                                                          | Confirmation timeout **with `txid`**.                                           |
+
+HTTP **403** (IP blocked, daily quota used up, or a bad key) is not retried: `code: 'ACCESS_DENIED'`. Token decimals are cached per service, so repeat token transfers need one fewer request.
+
+What the UI should do:
+
+```ts
+try {
+  await service.transferToken({ to, amount });
+} catch (error) {
+  if (!(error instanceof TronTransferError)) throw error;
+  if (error.txid) {
+    // Possibly sent. Never resend automatically; show "pending" and a link to the txid on tronscan.
+  } else if (error.code === 'RATE_LIMITED') {
+    // Nothing was sent. Show "Network busy, try again in a few seconds" with a retry button.
+  } else if (error.code === 'NOT_SIGNED') {
+    // The user cancelled in their wallet.
+  }
+}
+```
+
+Keep the service's own traffic low, too: create one service and reuse it (for example with `useMemo`), fetch balances on demand rather than on a timer, and don't call balance methods while a transfer is running. If users still hit 429 often, check the key's quota in the TronGrid dashboard, or point `fullHost` at your own proxy or node.
+
+### How it behaves with a wallet
+
+- **The address is read on every call.** If the user switches accounts, the next transfer comes from the new account. If they disconnect, calls throw `No wallet connected` before anything is built.
+- **Only what was checked gets broadcast.** The SDK refuses a signed transaction whose `txID` differs from the one it built.
+- **Rejection is a normal error.** If the user declines in the wallet, you get a `TronTransferError` with `code: 'NOT_SIGNED'` and no `txid`, and `cause` holds the wallet's error.
+- **The wallet's selected network doesn't matter to the SDK.** Transactions are built on and broadcast to the service's `network`/`fullHost`, and the wallet just signs them. Make sure the UI's `network` matches what the user expects to spend on.
+- **TronGrid API key on mainnet.** It's required, as in Node. A browser key is visible to every user, so restrict it to your app's origins in the TronGrid dashboard, or point `fullHost` at your own proxy or node (no key needed there).
+- **Don't use `PrivateKeySigner` in a browser.** It's for backends, scripts and tests.
+
+---
+
 ## API reference
 
-Everything below is exported from the package root.
+Unless noted, everything below is exported from both entry points.
+
+### `new TronTransferService(signer, config)`
+
+```ts
+class TronTransferService {
+  constructor(signer: TronSigner, config: TronTransferServiceConfig);
+  readonly signer: TronSigner;
+  readonly config: ServiceConfig; // validated, with defaults applied
+  readonly tronWeb: TronWeb; // read-only client (no key), for anything the SDK doesn't cover
+
+  transferTrx(params: TransferTrxParams): Promise<TransferResult>;
+  transferToken(params: TransferTokenParams): Promise<TransferResult>;
+  getTrxBalance(address?: string): Promise<string>;
+  getTokenBalance(params?: TokenBalanceParams): Promise<string>;
+}
+```
+
+`config` (`TronTransferServiceConfig`). The constructor throws a plain `Error` if a value is invalid.
+
+| Field              | Type                     | Default                                                                   | Description                                                  |
+| ------------------ | ------------------------ | ------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| `network`          | `'testnet' \| 'mainnet'` | required                                                                  | Network the service builds on, broadcasts to and reports.    |
+| `fullHost`         | `string`                 | `https://api.trongrid.io` (mainnet), `https://nile.trongrid.io` (testnet) | Full-node URL.                                               |
+| `apiKey`           | `string`                 | –                                                                         | TronGrid key. **Required for mainnet on `api.trongrid.io`.** |
+| `usdtContract`     | `string`                 | USDT for TronGrid mainnet / Nile / Shasta hosts                           | Default token for `transferToken` and `getTokenBalance`.     |
+| `feeLimitSun`      | `number`                 | `100000000` (100 TRX)                                                     | Default max TRX, in SUN, that one token transfer may burn.   |
+| `rateLimitRetries` | `number`                 | `3`                                                                       | Retries, with backoff, for requests answered with HTTP 429.  |
+
+`transferTrx` and `transferToken` are described below; they take the same parameters as the Node shortcut functions, minus `network` (the service is bound to one).
+
+`getTrxBalance(address?)` returns a TRX balance in whole TRX, such as `"12.5"`. `getTokenBalance({ tokenAddress?, owner? })` returns a token balance in whole tokens, using the token's `decimals()`. Both default to the signer's address and read the full node's latest state. They also work with a disconnected wallet if you pass an address.
+
+### `TronSigner` and `PrivateKeySigner`
+
+`TronSigner` is the interface shown in [Frontend](#frontend-signing-with-the-users-wallet). `PrivateKeySigner` implements it with a hex private key, signing locally:
+
+```ts
+import { PrivateKeySigner, TronTransferService } from '@zebec-network/tron-transfer-sdk';
+
+const service = new TronTransferService(new PrivateKeySigner(process.env.KEY!), { network: 'testnet' });
+```
+
+It throws on a malformed key. Use it on servers and in tests only.
+
+### `createTransferServiceFromEnv(network?)` (Node entry)
+
+Returns a `TronTransferService` configured by `loadConfig(network)`, signing with `TRON_<NET>_PRIVATE_KEY`.
 
-### `transferTrx(params)`
+### `transferTrx(params)` (Node entry)
 
-Sends native TRX from the account configured for the network.
+Sends native TRX from the account configured in `.env`. It's a shortcut for `createTransferServiceFromEnv(params.network).transferTrx(params)`; `service.transferTrx` takes the same parameters except `network`.
 
 ```ts
 function transferTrx(params: TransferTrxParams): Promise<TransferResult>;
@@ -194,7 +364,7 @@ await transferTrx({ to: 'TXYZ...', amount: 12 }); // 12 TRX
 await transferTrx({ to: 'TXYZ...', amount: '1', waitForConfirmation: false }); // return right after broadcast
 ```
 
-### `transferToken(params)`
+### `transferToken(params)` (Node entry)
 
 Sends a TRC-20 token by calling its `transfer(address,uint256)` function. The default token is the USDT contract configured for the network.
 
@@ -237,7 +407,7 @@ The error class for transfer failures. It extends `Error` and adds:
 
 The `message` includes the txid when there is one. See [Error handling](#error-handling) for the full list of failures.
 
-### `loadConfig(network?)`
+### `loadConfig(network?)` (Node entry)
 
 Reads and validates configuration from the environment. `transferTrx` and `transferToken` call it for you; it's exported for advanced use.
 
@@ -249,19 +419,23 @@ It defaults to `TRON_NETWORK`, and throws `Error` on missing or invalid variable
 
 ### `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:
+Creates a TronWeb instance with the API key header set, and the private key if one is given (omit it for a read-only client). Use it to call TronWeb directly for anything the SDK doesn't cover:
 
 ```ts
-import { createTronWeb, loadConfig } from '@zebec-network/tron-transfer-sdk';
+import { createTronWeb, loadConfig } from '@zebec-network/tron-transfer-sdk/node';
 
 const tronWeb = createTronWeb(loadConfig('testnet'));
 const account = await tronWeb.trx.getAccount('TXYZ...');
 ```
 
 ```ts
-function createTronWeb(config: NetworkConfig): TronWeb;
+function createTronWeb(config: { fullHost: string; apiKey?: string; privateKey?: string }): TronWeb;
 ```
 
+### `resolveServiceConfig(config)`
+
+Validates a `TronTransferServiceConfig` and applies defaults, returning a `ServiceConfig`. The service constructor calls it; it's exported so you can validate settings early, for example at app start-up.
+
 ### `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.
@@ -277,6 +451,10 @@ 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.
 
+### `fromBaseUnits(units, decimals)`
+
+The reverse conversion, for displaying `rawAmount` or balances: `fromBaseUnits(1_500_000n, 6) === '1.5'`.
+
 ---
 
 ## Types
@@ -290,11 +468,15 @@ type TronNetwork = 'mainnet' | 'testnet';
 type Amount = string | number;
 
 interface TransferOptions {
-  network?: TronNetwork; // default: TRON_NETWORK
   waitForConfirmation?: boolean; // default: true
   confirmationTimeoutMs?: number; // default: 60_000
 }
 
+/** Only for the Node shortcut functions; a service is bound to one network. */
+interface EnvTransferOptions {
+  network?: TronNetwork; // default: TRON_NETWORK
+}
+
 interface TransferTrxParams extends TransferOptions {
   to: string;
   amount: Amount; // in TRX
@@ -303,14 +485,19 @@ interface TransferTrxParams extends TransferOptions {
 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
+  tokenAddress?: string; // default: the configured USDT contract
+  feeLimitSun?: number; // default: the service's feeLimitSun
+}
+
+interface TokenBalanceParams {
+  tokenAddress?: string; // default: the configured USDT contract
+  owner?: string; // default: the signer's address
 }
 
 interface TransferResult {
   txid: string;
   network: TronNetwork;
-  from: string; // sender, derived from the private key
+  from: string; // sender: the signer's address
   to: string;
   rawAmount: string; // smallest unit: SUN for TRX, base units for tokens
   confirmed: boolean; // false when waitForConfirmation is false
@@ -318,14 +505,25 @@ interface TransferResult {
   feeSun?: number; // total fee paid, in SUN; set when confirmed
 }
 
-interface NetworkConfig {
+interface TronTransferServiceConfig {
+  network: TronNetwork;
+  fullHost?: string;
+  apiKey?: string;
+  usdtContract?: string;
+  feeLimitSun?: number;
+}
+
+interface ServiceConfig {
   network: TronNetwork;
   fullHost: string;
   apiKey: string | undefined;
-  privateKey: string;
   usdtContract: string | undefined;
   feeLimitSun: number;
 }
+
+interface NetworkConfig extends ServiceConfig {
+  privateKey: string; // from .env
+}
 ```
 
 `rawAmount` is a string because token base units can exceed JavaScript's safe integer range. Use `BigInt(result.rawAmount)` to do arithmetic on it.
@@ -350,14 +548,14 @@ Example result:
 ## How a transfer works
 
 ```
-load config ─► validate inputs ─► check balance ─► build tx ─► sign locally ─► broadcast ─► wait for block ─► verify result
+read signer address ─► validate inputs ─► check balance ─► build tx ─► signer signs ─► broadcast ─► wait for block ─► verify result
 ```
 
-1. **Load config** for the network and derive the sender address from the private key.
+1. **Read the sender address** from the signer (the connected wallet, or the key's address).
 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.
+5. **Sign** it with `signer.signTransaction`. A wallet asks the user to approve; `PrivateKeySigner` signs locally. The SDK checks that the signed transaction's `txID` matches what it built.
 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.
@@ -393,33 +591,42 @@ Things to keep in mind:
 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         |
+- **Plain `Error`**: configuration problems (from `loadConfig`, `resolveServiceConfig` and the service constructor), malformed `PrivateKeySigner` keys, 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`             | –           |
+| Config       | `A TronGrid API key is required for … on mainnet …`                                       | `Error`             | –           |
+| Config       | `network must be …` / `fullHost must be a URL …` / `feeLimitSun …` / `rateLimitRetries …` | `Error`             | –           |
+| Amount       | `Invalid amount …` / `Amount must be greater than zero …`                                 | `Error`             | –           |
+| Amount       | `Amount … has more than N decimal places.`                                                | `Error`             | –           |
+| Wallet       | `No wallet connected: the signer has no address.`                                         | `TronTransferError` | No          |
+| 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 no default USDT contract is known …`                          | `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          |
+| Node         | `Rate limited by … (HTTP 429) after N retries …` before broadcast (`RATE_LIMITED`)        | `TronTransferError` | No          |
+| Node         | `Request refused by … (HTTP 403) …` before broadcast (`ACCESS_DENIED`)                    | `TronTransferError` | No          |
+| Signing      | `Transaction was not signed: <wallet error>` (`NOT_SIGNED`)                               | `TronTransferError` | No          |
+| Signing      | `Signer returned a transaction that is unsigned or differs …`                             | `TronTransferError` | No          |
+| Broadcast    | `Broadcast rejected: <code> <reason>`                                                     | `TronTransferError` | Yes         |
+| Broadcast    | `Rate limited …` / `Request refused …` at broadcast                                       | `TronTransferError` | Yes         |
+| Broadcast    | `Broadcast request failed: … may still have reached the network`                          | `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.
+- **`txid` set:** the transaction may have 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.
+`code` is set for `RATE_LIMITED`, `ACCESS_DENIED` and `NOT_SIGNED`, so a UI can branch without matching messages. HTTP 429 is retried first; see [Rate limits](#rate-limits-http-429). Other errors from TronWeb or the network before broadcast, such as connection failures or an unreachable node, are passed through unchanged. Errors while polling for confirmation don't end the wait.
 
 ---
 
@@ -493,15 +700,16 @@ They need these variables in `.env` (see [Configuration](#configuration)):
 
 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):
+What's covered (35 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 |
+| 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                                                                                                                          |
+| [`test/TronTransferService.test.ts`](test/TronTransferService.test.ts) | 0.000001 TRX and 0.000001 USDT through a wallet-shaped signer; balance reads                                              | Config defaults and validation, `PrivateKeySigner`, `fromBaseUnits`, disconnected wallet, user rejection, tampered signed transaction; simulated HTTP 429/403 at each stage, including a real rebroadcast answered as a duplicate |
 
 - **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.
+- **Duration:** about 1 minute.
 - The test files run one after the other with a generous timeout (`-t 1000000`), since each live transfer waits for a block.
 
 ---
@@ -511,16 +719,20 @@ What's covered (19 tests):
 ```
 tron-transfer-sdk/
 ├── src/
-│   ├── index.ts          # Public exports
-│   ├── services.ts       # transferTrx, transferToken, TronTransferError
-│   ├── config.ts         # Env loading and validation (loadConfig)
+│   ├── index.ts          # Browser-safe entry (package root)
+│   ├── node.ts           # Node entry (/node): root + loadConfig and .env shortcut functions
+│   ├── services.ts       # TronTransferService, TronTransferError
+│   ├── signer.ts         # TronSigner interface, PrivateKeySigner
+│   ├── config.ts         # Service config, defaults and validation (resolveServiceConfig)
+│   ├── env.ts            # .env loading (loadConfig), Node only
 │   ├── client.ts         # TronWeb instance factory (createTronWeb)
 │   ├── types.ts          # Public parameter and result types
-│   └── utils.ts          # Exact amount conversion (toBaseUnits)
+│   └── utils.ts          # Exact amount conversion (toBaseUnits, fromBaseUnits)
 ├── test/
 │   ├── helpers.ts        # Shared test setup and balance readers
 │   ├── transferTrx.test.ts
-│   └── transferToken.test.ts
+│   ├── transferToken.test.ts
+│   └── TronTransferService.test.ts
 ├── examples/
 │   └── transfer.ts       # Example CLI
 ├── dist/                 # Build output (the only folder that gets published)
@@ -540,7 +752,7 @@ tron-transfer-sdk/
 | 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.                                                                |
+| [`dotenv`](https://www.npmjs.com/package/dotenv) `^18`      | Loads `.env` when the Node entry (`/node`) is imported. The browser entry never loads it.             |
 
 ### Development
 
@@ -561,17 +773,20 @@ The package is ESM (`"type": "module"`). ts-mocha on its own only sets up a Comm
 
 ## 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.                                                                                                |
+| 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.                     |
+| `RATE_LIMITED` / HTTP 429                                   | The SDK already retried; wait a few seconds. On testnet, set `apiKey` (`TRON_TESTNET_API_KEY` in Node). On mainnet, check the key's quota in the TronGrid dashboard or use another `fullHost`. |
+| `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.                                                                                                                    |
+| `loadConfig` / `transferTrx` is not exported                | Since the wallet-signer release these live in the Node entry: import from `@zebec-network/tron-transfer-sdk/node`.                                                                             |
+| Bundler errors about `fs`, `path` or `process` in a web app | You imported `@zebec-network/tron-transfer-sdk/node`. Web apps must import the package root.                                                                                                   |
+| `No wallet connected` in the UI                             | The adapter has no `address` yet. Wait for `connect()` / the `connected` state before calling transfer or balance methods.                                                                     |
 
 ---
 

package/dist/client.d.ts

@@ -1,4 +1,8 @@
 import { TronWeb } from 'tronweb';
-import type { NetworkConfig } from './config.js';
-export declare function createTronWeb(config: NetworkConfig): TronWeb;
+import type { ServiceConfig } from './config.js';
+export interface TronWebOptions extends Pick<ServiceConfig, 'fullHost' | 'apiKey'> {
+    /** Omit for a read-only client, e.g. in a browser where a wallet signs. */
+    privateKey?: string | undefined;
+}
+export declare function createTronWeb(config: TronWebOptions): TronWeb;
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +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"}
+{"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,MAAM,WAAW,cAAe,SAAQ,IAAI,CAAC,aAAa,EAAE,UAAU,GAAG,QAAQ,CAAC;IAChF,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAM7D"}

package/dist/client.js

@@ -2,7 +2,7 @@ import { TronWeb } from 'tronweb';
 export function createTronWeb(config) {
     return new TronWeb({
         fullHost: config.fullHost,
-        privateKey: config.privateKey,
+        ...(config.privateKey ? { privateKey: config.privateKey } : {}),
         ...(config.apiKey ? { headers: { 'TRON-PRO-API-KEY': config.apiKey } } : {}),
     });
 }

package/dist/client.js.map

@@ -1 +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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAQlC,MAAM,UAAU,aAAa,CAAC,MAAsB;IAClD,OAAO,IAAI,OAAO,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/D,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"}