@xchainjs/xchain-tron 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 THORChain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# `@xchainjs/xchain-tron`
+
+## Modules
+
+- `client` - Custom client for Tron
+- `clientKeystore` - Keystore client for Tron
+
+## Installation
+
+```
+yarn add @xchainjs/xchain-tron
+```
+
+Following peer dependencies have to be installed into your project. These are not included in `@xchainjs/xchain-tron`.
+
+```
+yarn add @xchainjs/xchain-client @xchainjs/xchain-crypto @xchainjs/xchain-util
+```
+
+## Usage
+
+### Basic Transfer
+
+```typescript
+import { ClientKeystore as Client, AssetTRX } from '@xchainjs/xchain-tron'
+import { assetToBase, assetAmount } from '@xchainjs/xchain-util'
+
+const client = new Client({ phrase: 'your mnemonic phrase' })
+
+// Simple transfer
+const txHash = await client.transfer({
+  asset: AssetTRX,
+  amount: assetToBase(assetAmount('1', 6)), // 1 TRX
+})
+```

package/lib/client.d.ts

@@ -0,0 +1,153 @@
+import { AssetInfo, Fees, Balance, TxHash, BaseXChainClient, ExplorerProviders, TxParams, PreparedTx, TxsPage, TxHistoryParams, Tx, FeesWithRates, FeeRate } from '@xchainjs/xchain-client';
+import { Address } from '@xchainjs/xchain-util';
+import { TronWeb } from 'tronweb';
+import { TRONClientParams, TronTransaction, TronSignedTransaction, ApproveParams, IsApprovedParams, TronGetApprovedParams } from './types';
+import { TronGrid } from './utils/trongrid';
+export declare const defaultTRONParams: TRONClientParams;
+export declare abstract class Client extends BaseXChainClient {
+    protected explorerProviders: ExplorerProviders;
+    protected tronWeb: TronWeb;
+    protected tronGrid: TronGrid;
+    constructor(params?: TRONClientParams);
+    /**
+     * Get TRX asset info.
+     * @returns {AssetInfo} TRX asset information.
+     */
+    getAssetInfo(): AssetInfo;
+    /**
+     * Get the explorer URL.
+     *
+     * @returns {string} The explorer URL.
+     */
+    getExplorerUrl(): string;
+    /**
+     * Get the explorer url for the given address.
+     *
+     * @param {Address} address
+     * @returns {string} The explorer url for the given address.
+     */
+    getExplorerAddressUrl(address: Address): string;
+    /**
+     * Get the explorer url for the given transaction id.
+     *
+     * @param {string} txID
+     * @returns {string} The explorer url for the given transaction id.
+     */
+    getExplorerTxUrl(txID: TxHash): string;
+    /**
+     * Validate the given Tron address.
+     * @param {string} address Tron address to validate.
+     * @returns {boolean} `true` if the address is valid, `false` otherwise.
+     */
+    validateAddress(address: string): boolean;
+    /**
+     * Get token balance and info directly from contract
+     */
+    fetchTokenMetadata: ({ contractAddress }: {
+        contractAddress: string;
+    }) => Promise<{
+        decimals: number;
+        symbol: any;
+    }>;
+    /**
+     * Get token balance and info directly from contract
+     */
+    fetchTokenBalance: ({ contractAddress, address }: {
+        contractAddress: string;
+        address: string;
+    }) => Promise<bigint>;
+    /**
+     * Get current chain parameters including resource prices
+     */
+    getChainParameters: () => Promise<{
+        bandwidthFee: number;
+        createAccountFee: number;
+        energyFee: number;
+    }>;
+    /**
+     * Check if an address exists on the blockchain
+     */
+    accountExists: (address: string) => Promise<boolean>;
+    /**
+     * Get account resources (bandwidth and energy)
+     */
+    getAccountResources: (address: string) => Promise<{
+        bandwidth: {
+            free: number;
+            total: number;
+            used: number;
+        };
+        energy: {
+            total: number;
+            used: number;
+        };
+    }>;
+    /**
+     * Retrieves the balance of a given address.
+     * @param {Address} address - The address to retrieve the balance for.
+     * @param {TokenAsset[]} assets - Assets to retrieve the balance for (optional).
+     * @returns {Promise<Balance[]>} An array containing the balance of the address.
+     */
+    getBalance(address: Address): Promise<Balance[]>;
+    /**
+     * Get transaction fees.
+     * @param {TxParams} params - Tx param
+     * @returns {Fees} The average, fast, and fastest fees.
+     */
+    getFees(params?: TxParams): Promise<Fees>;
+    createTransaction: (params: TxParams) => Promise<import("tronweb/lib/esm/types").Transaction<import("tronweb/lib/esm/types").ContractParamter>>;
+    /**
+     * Return signed tx
+     * @param transaction TronTransaction
+     * @param walletIndex wallet index
+     * @returns Transaction signed by phrase
+     */
+    abstract signTransaction(transaction: TronTransaction, walletIndex?: number): Promise<TronSignedTransaction>;
+    /**
+     * Transfer TRON Asset
+     * @param {TxParams} params The transfer options.
+     * @returns {TxHash} The transaction hash.
+     */
+    transfer(params: TxParams): Promise<string>;
+    /**
+     * Check the current allowance for a spender on a token
+     */
+    getApprovedAmount: ({ contractAddress, spenderAddress, from }: TronGetApprovedParams) => Promise<bigint>;
+    /**
+     * Check TRC20 allowance.
+     * @param {Address} contractAddress The contract address.
+     * @param {Address} spenderAddress The spender address.
+     * @param {BaseAmount} amount The amount to check if it's allowed to spend or not (optional).
+     * @param {number} walletIndex (optional) HD wallet index
+     * @param {IsApprovedParams} params - Parameters for checking allowance.
+     * @returns {boolean} `true` if the allowance is approved, `false` otherwise.
+     */
+    isApproved({ contractAddress, spenderAddress, amount, walletIndex }: IsApprovedParams): Promise<boolean>;
+    /**
+     * Approves an allowance for spending tokens.
+     *
+     * @param {ApproveParams} params - Parameters for approving an allowance.
+     * @param {Address} contractAddress The contract address.
+     * @param {Address} spenderAddress The spender address.
+     * @param {BaseAmount} amount The amount of token. By default, it will be unlimited token allowance. (optional)
+     * @param {number} walletIndex (optional) HD wallet index
+     * @returns {TransactionResponse} The result of the approval transaction.
+     * @throws Error If gas estimation fails.
+     */
+    approve({ contractAddress, spenderAddress, amount, walletIndex }: ApproveParams): Promise<string>;
+    broadcastTransaction(signedTx: TronSignedTransaction): Promise<TxHash>;
+    getTransactions(params?: TxHistoryParams): Promise<TxsPage>;
+    /**
+     * Get the transaction details of a given transaction ID.
+     *
+     * @param {string} txId The transaction ID.
+     * @returns {Tx} The transaction details.
+     */
+    getTransactionData(txId: string): Promise<Tx>;
+    broadcastTx(_signedTx: string): Promise<TxHash>;
+    prepareTx(_: TxParams & {
+        sender: Address;
+    }): Promise<PreparedTx>;
+    getFeesWithRates(): Promise<FeesWithRates>;
+    getFeeRates(): Promise<FeeRate>;
+}

package/lib/clientKeystore.d.ts

@@ -0,0 +1,22 @@
+import { TronTransaction, TronSignedTransaction, TRONClientParams } from './types';
+import { Client } from './client';
+export declare class ClientKeystore extends Client {
+    constructor(params?: TRONClientParams);
+    getSigner(walletIndex?: number): {
+        getAddress: () => string;
+        signTransaction: (transaction: TronTransaction) => Promise<import("tronweb/lib/esm/types").SignedTransaction<import("tronweb/lib/esm/types").ContractParamter> & TronTransaction>;
+    };
+    /**
+     * Get the current address synchronously.
+     */
+    getAddress(walletIndex?: number): string;
+    /**
+     * Get the current address asynchronously.
+     *
+     * @param {number} index The index of the address. Default 0
+     * @returns {Address} The TRON address related to the index provided.
+     * @throws {"Phrase must be provided"} Thrown if the phrase has not been set before.
+     */
+    getAddressAsync(walletIndex?: number): Promise<string>;
+    signTransaction(transaction: TronTransaction, walletIndex?: number): Promise<TronSignedTransaction>;
+}

package/lib/const.d.ts

@@ -0,0 +1,22 @@
+import { ExplorerProvider } from '@xchainjs/xchain-client';
+import { Asset, AnyAsset } from '@xchainjs/xchain-util';
+export declare const TRX_DECIMAL = 6;
+export declare const TRON_DERIVATION_PATH = "m/44'/195'/0'/0/";
+/**
+ * Chain identifier for Tron mainnet
+ */
+export declare const TRONChain: "TRON";
+export declare const AssetTRX: Asset;
+export declare const AssetTRONUSDT: AnyAsset;
+export declare const TRON_DEFAULT_RPC = "https://tron-rpc.publicnode.com";
+export declare const tronExplorerProviders: {
+    mainnet: ExplorerProvider;
+    stagenet: ExplorerProvider;
+    testnet: ExplorerProvider;
+};
+export declare const TRX_TRANSFER_BANDWIDTH = 268;
+export declare const TRC20_TRANSFER_ENERGY = 13000;
+export declare const TRC20_TRANSFER_BANDWIDTH = 345;
+export declare const TRON_USDT_CONTRACT = "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t";
+export declare const MAX_APPROVAL = "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff";
+export declare const TRX_FEE_LIMIT = 100000000;

package/lib/index.d.ts

@@ -0,0 +1,5 @@
+export { ClientKeystore as Client } from './clientKeystore';
+export { defaultTRONParams } from './client';
+export * from './const';
+export { validateAddress } from './utils';
+export * from './types';