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

package/dist/config.d.ts

@@ -1,16 +1,33 @@
-import 'dotenv/config';
 export type TronNetwork = 'mainnet' | 'testnet';
-export interface NetworkConfig {
+/** Settings passed to TronTransferService. Everything except `network` has a default. */
+export interface TronTransferServiceConfig {
+    network: TronNetwork;
+    /** Full-node URL. Defaults to TronGrid: api.trongrid.io on mainnet, nile.trongrid.io on testnet. */
+    fullHost?: string | undefined;
+    /** TronGrid API key, sent as the TRON-PRO-API-KEY header. Required for mainnet on api.trongrid.io. */
+    apiKey?: string | undefined;
+    /** Default token for transferToken(). Defaults to USDT when `fullHost` is a known TronGrid host. */
+    usdtContract?: string | undefined;
+    /** Max TRX (in SUN) one token transfer may burn for energy. Default: 100_000_000 (100 TRX). */
+    feeLimitSun?: number | undefined;
+    /** How many times to retry a request the node answers with HTTP 429, with backoff. Default: 3. */
+    rateLimitRetries?: number | undefined;
+}
+/** A validated TronTransferServiceConfig with defaults applied. */
+export interface ServiceConfig {
     network: TronNetwork;
     fullHost: string;
     apiKey: string | undefined;
-    privateKey: string;
     usdtContract: string | undefined;
     feeLimitSun: number;
+    rateLimitRetries: number;
+}
+/** A ServiceConfig plus the sender's private key, as read from .env by loadConfig(). */
+export interface NetworkConfig extends ServiceConfig {
+    privateKey: string;
 }
-/**
- * Reads the configuration for a network from environment variables.
- * Defaults to the network named by TRON_NETWORK.
- */
-export declare function loadConfig(network?: TronNetwork): NetworkConfig;
+export declare const DEFAULT_FEE_LIMIT_SUN = 100000000;
+export declare const DEFAULT_RATE_LIMIT_RETRIES = 3;
+/** Validates a service config and fills in the defaults for its network. */
+export declare function resolveServiceConfig(config: TronTransferServiceConfig): ServiceConfig;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC;AAEhD,yFAAyF;AACzF,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,WAAW,CAAC;IACrB,oGAAoG;IACpG,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,sGAAsG;IACtG,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,oGAAoG;IACpG,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,+FAA+F;IAC/F,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,kGAAkG;IAClG,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAED,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,WAAW,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,wFAAwF;AACxF,MAAM,WAAW,aAAc,SAAQ,aAAa;IAClD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,qBAAqB,YAAc,CAAC;AACjD,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAsB5C,4EAA4E;AAC5E,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,yBAAyB,GAAG,aAAa,CAgCrF"}

package/dist/config.js

@@ -1,55 +1,49 @@
-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.`);
+import { TronWeb } from 'tronweb';
+export const DEFAULT_FEE_LIMIT_SUN = 100_000_000; // 100 TRX
+export const DEFAULT_RATE_LIMIT_RETRIES = 3;
+const DEFAULT_FULL_HOST = {
+    mainnet: 'https://api.trongrid.io',
+    testnet: 'https://nile.trongrid.io',
+};
+// USDT is deployed at a different address on each network, so the default follows the host.
+const USDT_BY_HOST = {
+    'api.trongrid.io': 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
+    'nile.trongrid.io': 'TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf',
+    'api.shasta.trongrid.io': 'TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs',
+};
+function parseHost(fullHost) {
+    try {
+        return new URL(fullHost);
+    }
+    catch {
+        throw new Error(`fullHost must be a URL such as https://nile.trongrid.io, got "${fullHost}".`);
     }
-    return value;
 }
-function parseNetwork(value) {
-    const network = (value ?? 'testnet').toLowerCase();
+/** Validates a service config and fills in the defaults for its network. */
+export function resolveServiceConfig(config) {
+    const { network } = config;
     if (network !== 'mainnet' && network !== 'testnet') {
-        throw new Error(`TRON_NETWORK must be "mainnet" or "testnet", got "${value}".`);
+        throw new Error(`network must be "mainnet" or "testnet", got "${network}".`);
     }
-    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}".`);
+    const fullHost = config.fullHost?.trim() || DEFAULT_FULL_HOST[network];
+    const { hostname } = parseHost(fullHost);
+    const apiKey = config.apiKey?.trim() || undefined;
+    if (network === 'mainnet' && !apiKey && /(^|\.)trongrid\.io$/i.test(hostname)) {
+        // Keyless TronGrid requests are limited per IP (about 1 request/s); a token transfer makes several in a row.
+        throw new Error(`A TronGrid API key is required for ${fullHost} on mainnet (apiKey, or TRON_MAINNET_API_KEY in .env). Get one at https://www.trongrid.io.`);
     }
-    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 usdtContract = config.usdtContract?.trim() || USDT_BY_HOST[hostname.toLowerCase()];
+    if (usdtContract && !TronWeb.isAddress(usdtContract)) {
+        throw new Error(`usdtContract must be a TRON address, got "${usdtContract}".`);
+    }
+    const feeLimitSun = config.feeLimitSun ?? DEFAULT_FEE_LIMIT_SUN;
+    if (!Number.isSafeInteger(feeLimitSun) || feeLimitSun <= 0) {
+        throw new Error(`feeLimitSun must be a positive integer (in SUN), got ${feeLimitSun}.`);
     }
-    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.`);
+    const rateLimitRetries = config.rateLimitRetries ?? DEFAULT_RATE_LIMIT_RETRIES;
+    if (!Number.isSafeInteger(rateLimitRetries) || rateLimitRetries < 0) {
+        throw new Error(`rateLimitRetries must be a non-negative integer, got ${rateLimitRetries}.`);
     }
-    return {
-        network,
-        fullHost,
-        apiKey,
-        privateKey,
-        usdtContract: readEnv(`${prefix}_USDT_CONTRACT`),
-        feeLimitSun: parseFeeLimit(readEnv('TRON_FEE_LIMIT_SUN')),
-    };
+    return { network, fullHost, apiKey, usdtContract, feeLimitSun, rateLimitRetries };
 }
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -1 +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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAkClC,MAAM,CAAC,MAAM,qBAAqB,GAAG,WAAW,CAAC,CAAC,UAAU;AAC5D,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC;AAE5C,MAAM,iBAAiB,GAAgC;IACrD,OAAO,EAAE,yBAAyB;IAClC,OAAO,EAAE,0BAA0B;CACpC,CAAC;AAEF,4FAA4F;AAC5F,MAAM,YAAY,GAA2B;IAC3C,iBAAiB,EAAE,oCAAoC;IACvD,kBAAkB,EAAE,oCAAoC;IACxD,wBAAwB,EAAE,oCAAoC;CAC/D,CAAC;AAEF,SAAS,SAAS,CAAC,QAAgB;IACjC,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,iEAAiE,QAAQ,IAAI,CAAC,CAAC;IACjG,CAAC;AACH,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,oBAAoB,CAAC,MAAiC;IACpE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IAC3B,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QACnD,MAAM,IAAI,KAAK,CAAC,gDAAgD,OAAO,IAAI,CAAC,CAAC;IAC/E,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,iBAAiB,CAAC,OAAO,CAAC,CAAC;IACvE,MAAM,EAAE,QAAQ,EAAE,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IACzC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;IAClD,IAAI,OAAO,KAAK,SAAS,IAAI,CAAC,MAAM,IAAI,sBAAsB,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9E,6GAA6G;QAC7G,MAAM,IAAI,KAAK,CACb,sCAAsC,QAAQ,4FAA4F,CAC3I,CAAC;IACJ,CAAC;IAED,MAAM,YAAY,GAAG,MAAM,CAAC,YAAY,EAAE,IAAI,EAAE,IAAI,YAAY,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;IACzF,IAAI,YAAY,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,YAAY,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CAAC,6CAA6C,YAAY,IAAI,CAAC,CAAC;IACjF,CAAC;IAED,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,IAAI,qBAAqB,CAAC;IAChE,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,WAAW,CAAC,IAAI,WAAW,IAAI,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,wDAAwD,WAAW,GAAG,CAAC,CAAC;IAC1F,CAAC;IAED,MAAM,gBAAgB,GAAG,MAAM,CAAC,gBAAgB,IAAI,0BAA0B,CAAC;IAC/E,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,gBAAgB,CAAC,IAAI,gBAAgB,GAAG,CAAC,EAAE,CAAC;QACpE,MAAM,IAAI,KAAK,CAAC,wDAAwD,gBAAgB,GAAG,CAAC,CAAC;IAC/F,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,CAAC;AACpF,CAAC"}

package/dist/env.d.ts

@@ -0,0 +1,8 @@
+import 'dotenv/config';
+import type { NetworkConfig, TronNetwork } from './config.js';
+/**
+ * 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=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AACA,OAAO,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAgC9D;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,WAAmD,GAAG,aAAa,CAgBtG"}

package/dist/env.js

@@ -0,0 +1,50 @@
+// Node-only: dotenv reads the filesystem when imported, so nothing in the browser entry imports this file.
+import 'dotenv/config';
+import { resolveServiceConfig } from './config.js';
+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 undefined;
+    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 config = resolveServiceConfig({
+        network,
+        fullHost: requireEnv(`${prefix}_FULL_HOST`),
+        apiKey: readEnv(`${prefix}_API_KEY`),
+        usdtContract: readEnv(`${prefix}_USDT_CONTRACT`),
+        feeLimitSun: parseFeeLimit(readEnv('TRON_FEE_LIMIT_SUN')),
+    });
+    return { ...config, privateKey };
+}
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA,2GAA2G;AAC3G,OAAO,eAAe,CAAC;AACvB,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGnD,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,SAAS,CAAC;IAC1C,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,MAAM,GAAG,oBAAoB,CAAC;QAClC,OAAO;QACP,QAAQ,EAAE,UAAU,CAAC,GAAG,MAAM,YAAY,CAAC;QAC3C,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,UAAU,CAAC;QACpC,YAAY,EAAE,OAAO,CAAC,GAAG,MAAM,gBAAgB,CAAC;QAChD,WAAW,EAAE,aAAa,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC;KAC1D,CAAC,CAAC;IACH,OAAO,EAAE,GAAG,MAAM,EAAE,UAAU,EAAE,CAAC;AACnC,CAAC"}

package/dist/index.d.ts

@@ -1,7 +1,11 @@
-export { transferTrx, transferToken, TronTransferError } from './services.js';
-export { loadConfig } from './config.js';
-export type { NetworkConfig, TronNetwork } from './config.js';
+export { TronTransferService, TronTransferError } from './services.js';
+export type { TronTransferErrorCode } from './services.js';
+export { PrivateKeySigner } from './signer.js';
+export type { TronSigner } from './signer.js';
+export { resolveServiceConfig, DEFAULT_FEE_LIMIT_SUN, DEFAULT_RATE_LIMIT_RETRIES } from './config.js';
+export type { NetworkConfig, ServiceConfig, TronNetwork, TronTransferServiceConfig } from './config.js';
 export { createTronWeb } from './client.js';
-export { toBaseUnits } from './utils.js';
-export type { Amount, TransferOptions, TransferResult, TransferTokenParams, TransferTrxParams } from './types.js';
+export type { TronWebOptions } from './client.js';
+export { fromBaseUnits, toBaseUnits } from './utils.js';
+export type { Amount, EnvTransferOptions, TokenBalanceParams, TransferOptions, TransferResult, TransferTokenParams, TransferTrxParams, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvE,YAAY,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AACtG,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AACxG,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACxD,YAAY,EACV,MAAM,EACN,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,5 +1,7 @@
-export { transferTrx, transferToken, TronTransferError } from './services.js';
-export { loadConfig } from './config.js';
+// Browser-safe entry: no dotenv, no filesystem or process.env access. The .env helpers live in ./node.
+export { TronTransferService, TronTransferError } from './services.js';
+export { PrivateKeySigner } from './signer.js';
+export { resolveServiceConfig, DEFAULT_FEE_LIMIT_SUN, DEFAULT_RATE_LIMIT_RETRIES } from './config.js';
 export { createTronWeb } from './client.js';
-export { toBaseUnits } from './utils.js';
+export { fromBaseUnits, toBaseUnits } from './utils.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,uGAAuG;AACvG,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAEtG,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/node.d.ts

@@ -0,0 +1,25 @@
+import type { TronNetwork } from './config.js';
+import { loadConfig } from './env.js';
+import { TronTransferService } from './services.js';
+import type { EnvTransferOptions, TransferResult, TransferTokenParams, TransferTrxParams } from './types.js';
+export * from './index.js';
+export { loadConfig };
+/** A TronTransferService that signs with TRON_<NET>_PRIVATE_KEY from .env. */
+export declare function createTransferServiceFromEnv(network?: TronNetwork): TronTransferService;
+/**
+ * Sends native TRX from the account configured in .env.
+ *
+ * @example
+ * await transferTrx({ to: 'TXYZ...', amount: '10' }); // 10 TRX
+ */
+export declare function transferTrx(params: TransferTrxParams & EnvTransferOptions): 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 & EnvTransferOptions): Promise<TransferResult>;
+//# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE7G,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB,8EAA8E;AAC9E,wBAAgB,4BAA4B,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,mBAAmB,CAGvF;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,CAGzG;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,CAG7G"}

package/dist/node.js

@@ -0,0 +1,33 @@
+import { loadConfig } from './env.js';
+import { TronTransferService } from './services.js';
+import { PrivateKeySigner } from './signer.js';
+export * from './index.js';
+export { loadConfig };
+/** A TronTransferService that signs with TRON_<NET>_PRIVATE_KEY from .env. */
+export function createTransferServiceFromEnv(network) {
+    const config = loadConfig(network);
+    return new TronTransferService(new PrivateKeySigner(config.privateKey), config);
+}
+/**
+ * Sends native TRX from the account configured in .env.
+ *
+ * @example
+ * await transferTrx({ to: 'TXYZ...', amount: '10' }); // 10 TRX
+ */
+export async function transferTrx(params) {
+    const { network, ...transfer } = params;
+    return createTransferServiceFromEnv(network).transferTrx(transfer);
+}
+/**
+ * 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 { network, ...transfer } = params;
+    return createTransferServiceFromEnv(network).transferToken(transfer);
+}
+//# sourceMappingURL=node.js.map

package/dist/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB,8EAA8E;AAC9E,MAAM,UAAU,4BAA4B,CAAC,OAAqB;IAChE,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;IACnC,OAAO,IAAI,mBAAmB,CAAC,IAAI,gBAAgB,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,CAAC;AAClF,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,MAA8C;IAC9E,MAAM,EAAE,OAAO,EAAE,GAAG,QAAQ,EAAE,GAAG,MAAM,CAAC;IACxC,OAAO,4BAA4B,CAAC,OAAO,CAAC,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;AACrE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAgD;IAClF,MAAM,EAAE,OAAO,EAAE,GAAG,QAAQ,EAAE,GAAG,MAAM,CAAC;IACxC,OAAO,4BAA4B,CAAC,OAAO,CAAC,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;AACvE,CAAC"}

package/dist/services.d.ts

@@ -1,23 +1,64 @@
-import type { TransferResult, TransferTokenParams, TransferTrxParams } from './types.js';
-/** Thrown for any failed transfer. `txid` is set when the transaction reached the network. */
+import { TronWeb } from 'tronweb';
+import type { ServiceConfig, TronTransferServiceConfig } from './config.js';
+import type { TronSigner } from './signer.js';
+import type { TokenBalanceParams, TransferResult, TransferTokenParams, TransferTrxParams } from './types.js';
+/**
+ * Machine-readable reason for some failures, for UIs to branch on:
+ * - `RATE_LIMITED`: the node answered HTTP 429 even after retries.
+ * - `ACCESS_DENIED`: the node answered HTTP 403 (IP blocked, daily quota used up, or a bad apiKey).
+ * - `NOT_SIGNED`: the signer threw, e.g. the user rejected the request in their wallet.
+ */
+export type TronTransferErrorCode = 'RATE_LIMITED' | 'ACCESS_DENIED' | 'NOT_SIGNED';
+/** Thrown for any failed transfer. `txid` is set when the transaction may have reached the network. */
 export declare class TronTransferError extends Error {
     readonly txid: string | undefined;
-    constructor(message: string, txid?: string);
+    readonly code: TronTransferErrorCode | undefined;
+    constructor(message: string, txid?: string, options?: {
+        cause?: unknown;
+        code?: TronTransferErrorCode;
+    });
 }
 /**
- * Sends native TRX from the account configured in .env.
+ * Sends TRX and TRC-20 tokens, with every transaction signed by `signer`.
  *
- * @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.
+ * In a browser, pass the connected wallet adapter (or `useWallet()`) as the signer: the SDK builds
+ * and checks the transaction, the wallet asks the user to approve it, and the SDK broadcasts it and
+ * waits for confirmation. The TronWeb client here never holds a private key.
  *
  * @example
- * await transferToken({ to: 'TXYZ...', amount: '5' }); // 5 USDT
- * await transferToken({ to: 'TXYZ...', amount: '1.25', tokenAddress: 'T...' }); // any TRC-20
+ * const service = new TronTransferService(adapter, { network: 'mainnet', apiKey: TRONGRID_KEY });
+ * await service.transferToken({ to: 'TXYZ...', amount: '5' }); // 5 USDT
  */
-export declare function transferToken(params: TransferTokenParams): Promise<TransferResult>;
+export declare class TronTransferService {
+    #private;
+    readonly signer: TronSigner;
+    readonly config: ServiceConfig;
+    readonly tronWeb: TronWeb;
+    constructor(signer: TronSigner, config: TronTransferServiceConfig);
+    /**
+     * Sends native TRX from the signer's account.
+     *
+     * @example
+     * await service.transferTrx({ to: 'TXYZ...', amount: '10' }); // 10 TRX
+     */
+    transferTrx(params: TransferTrxParams): Promise<TransferResult>;
+    /**
+     * Sends a TRC-20 token (USDT by default) from the signer's account.
+     * The sender needs TRX to pay for energy; up to `feeLimitSun` may be burned.
+     *
+     * @example
+     * await service.transferToken({ to: 'TXYZ...', amount: '5' }); // 5 USDT
+     * await service.transferToken({ to: 'TXYZ...', amount: '1.25', tokenAddress: 'T...' }); // any TRC-20
+     */
+    transferToken(params: TransferTokenParams): Promise<TransferResult>;
+    /**
+     * TRX balance in whole TRX (e.g. "12.5"), from the full node's latest state.
+     * Defaults to the signer's address.
+     */
+    getTrxBalance(address?: string): Promise<string>;
+    /**
+     * TRC-20 balance in whole tokens (e.g. "5.25"). Defaults to USDT and the signer's address.
+     */
+    getTokenBalance(params?: TokenBalanceParams): Promise<string>;
+}
 //# sourceMappingURL=services.d.ts.map

package/dist/services.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"services.d.ts","sourceRoot":"","sources":["../src/services.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAIlC,OAAO,KAAK,EAAE,aAAa,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EACV,kBAAkB,EAElB,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AASpB;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,cAAc,GAAG,eAAe,GAAG,YAAY,CAAC;AAEpF,uGAAuG;AACvG,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,GAAG,SAAS,CAAC;gBAErC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,qBAAqB,CAAA;KAAO;CAM5G;AAwCD;;;;;;;;;;GAUG;AACH,qBAAa,mBAAmB;;IAO5B,QAAQ,CAAC,MAAM,EAAE,UAAU;IAN7B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;gBAKf,MAAM,EAAE,UAAU,EAC3B,MAAM,EAAE,yBAAyB;IAMnC;;;;;OAKG;IACG,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC;IAwBrE;;;;;;;OAOG;IACG,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC;IAuCzE;;;OAGG;IACG,aAAa,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOtD;;OAEG;IACG,eAAe,CAAC,MAAM,GAAE,kBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC;CA8NxE"}