@swapkit/toolboxes 1.0.0-beta.16 → 1.0.0-beta.18

package/src/tron/toolbox.ts

@@ -0,0 +1,328 @@
+import {
+  AssetValue,
+  Chain,
+  NetworkDerivationPath,
+  SKConfig,
+  SwapKitError,
+  derivationPathToString,
+  updateDerivationPath,
+  warnOnce,
+} from "@swapkit/helpers";
+import { TronWeb } from "tronweb";
+import { P, match } from "ts-pattern";
+
+import { trc20ABI } from "./helpers/trc20.abi.js";
+import type {
+  TronSignedTransaction,
+  TronSigner,
+  TronToolboxOptions,
+  TronTransaction,
+  TronTransferParams,
+} from "./types.js";
+
+export async function getTronAddressValidator() {
+  const { TronWeb } = await import("tronweb");
+  return (address: string) => TronWeb.isAddress(address);
+}
+
+export async function getTronPrivateKeyFromMnemonic({
+  phrase,
+  derivationPath: customPath,
+  index,
+}: {
+  phrase: string;
+  derivationPath?: string;
+  index?: number;
+}) {
+  const derivationPathToUse =
+    customPath ||
+    derivationPathToString(
+      updateDerivationPath(NetworkDerivationPath[Chain.Tron], { index: index || 0 }),
+    );
+
+  const { HDKey } = await import("@scure/bip32");
+  const { mnemonicToSeedSync } = await import("@scure/bip39");
+
+  const seed = mnemonicToSeedSync(phrase);
+  const hdKey = HDKey.fromMasterSeed(seed);
+  const derived = hdKey.derive(derivationPathToUse);
+
+  if (!derived.privateKey) {
+    throw new SwapKitError("toolbox_tron_no_signer");
+  }
+
+  return Buffer.from(derived.privateKey).toString("hex");
+}
+
+async function createKeysForPath({
+  phrase,
+  derivationPath,
+}: {
+  phrase: string;
+  derivationPath: string;
+}): Promise<TronSigner> {
+  const { HDKey } = await import("@scure/bip32");
+  const { mnemonicToSeedSync } = await import("@scure/bip39");
+
+  const seed = mnemonicToSeedSync(phrase);
+  const hdKey = HDKey.fromMasterSeed(seed);
+  const derived = hdKey.derive(derivationPath);
+
+  if (!derived.privateKey) {
+    throw new SwapKitError("toolbox_tron_no_signer");
+  }
+
+  // Convert private key to hex string for TronWeb
+  const privateKeyHex = Buffer.from(derived.privateKey).toString("hex");
+
+  // Create TronWeb instance with the derived private key
+  const tronWebWithKey = new TronWeb({
+    fullHost: SKConfig.get("rpcUrls")[Chain.Tron],
+    privateKey: privateKeyHex,
+  });
+
+  const address = tronWebWithKey.address.fromPrivateKey(privateKeyHex);
+
+  return {
+    getAddress: () => Promise.resolve(typeof address === "string" ? address : ""),
+    signTransaction: async (transaction: TronTransaction) => {
+      const signedTx = await tronWebWithKey.trx.sign(transaction, privateKeyHex);
+      return signedTx;
+    },
+  };
+}
+
+export const createTronToolbox = async (options: TronToolboxOptions = {}) => {
+  // Always get configuration from SKConfig
+  const rpcUrl = SKConfig.get("rpcUrls")[Chain.Tron];
+  // Note: TRON API key support can be added to SKConfig apiKeys when needed
+  const headers = undefined; // No API key needed for basic TronGrid access
+
+  const tronWeb = new TronWeb({
+    fullHost: rpcUrl,
+    headers,
+  });
+
+  // Handle derivation path and index
+  const index = "index" in options ? options.index || 0 : 0;
+  const derivationPath = derivationPathToString(
+    "derivationPath" in options && options.derivationPath
+      ? options.derivationPath
+      : updateDerivationPath(NetworkDerivationPath[Chain.Tron], { index }),
+  );
+
+  // Create signer based on options using pattern matching
+  const signer: TronSigner | undefined = await match(options)
+    .with({ phrase: P.string }, async ({ phrase }) => createKeysForPath({ phrase, derivationPath }))
+    .with({ signer: P.any }, ({ signer }) => Promise.resolve(signer as TronSigner))
+    .otherwise(() => Promise.resolve(undefined));
+
+  const getAddress = async () => {
+    if (!signer) throw new SwapKitError("toolbox_tron_no_signer");
+    return await signer.getAddress();
+  };
+
+  const validateAddress = (address: string) => {
+    return tronWeb.isAddress(address);
+  };
+
+  const getContractAddress = (assetValue: AssetValue) => {
+    // Use asset.address for TRC20 contracts instead of parsing string
+    return assetValue.address;
+  };
+
+  const calculateFeeLimit = () => {
+    return 100_000_000; // 100 TRX in SUN
+  };
+
+  const getBalance = async (address: string, scamFilter = true) => {
+    const { getBalance: getBalanceFromApi } = await import("../utils.js");
+
+    try {
+      // Use SwapKit API for comprehensive balance fetching (includes TRX + TRC20 tokens)
+      const apiBalances = await getBalanceFromApi(Chain.Tron)(address, scamFilter);
+
+      // If API returns balances, use those
+      if (apiBalances.length > 0) {
+        return apiBalances;
+      }
+
+      // Fallback to on-chain TRX balance if API fails or returns empty
+      const trxBalanceInSun = await tronWeb.trx.getBalance(address);
+      return [
+        AssetValue.from({
+          chain: Chain.Tron,
+          value: trxBalanceInSun,
+          fromBaseDecimal: 6, // TRX has 6 decimals
+        }),
+      ];
+    } catch (error) {
+      warnOnce(
+        true,
+        `Failed to get Tron balance for ${address}: ${error instanceof Error ? error.message : error}`,
+      );
+
+      // Final fallback: try to get just the native TRX balance
+      try {
+        const trxBalanceInSun = await tronWeb.trx.getBalance(address);
+        return [
+          AssetValue.from({
+            chain: Chain.Tron,
+            value: trxBalanceInSun,
+            fromBaseDecimal: 6,
+          }),
+        ];
+      } catch (fallbackError) {
+        warnOnce(
+          true,
+          `Failed to get native TRX balance for ${address}: ${fallbackError instanceof Error ? fallbackError.message : fallbackError}`,
+        );
+        return [];
+      }
+    }
+  };
+
+  const transfer = async ({ recipient, assetValue, memo }: TronTransferParams) => {
+    if (!signer) throw new SwapKitError("toolbox_tron_no_signer");
+
+    const from = await getAddress();
+    const isNative = assetValue.isGasAsset;
+
+    if (isNative) {
+      // Native TRX Transfer (amount in SUN - base units)
+      const transaction = await tronWeb.transactionBuilder.sendTrx(
+        recipient,
+        assetValue.getBaseValue("number"),
+        from,
+      );
+
+      // Add memo if provided
+      if (memo) {
+        const transactionWithMemo = await tronWeb.transactionBuilder.addUpdateData(
+          transaction,
+          memo,
+          "utf8",
+        );
+        const signedTx = await signer.signTransaction(transactionWithMemo);
+        const { txid } = await tronWeb.trx.sendRawTransaction(signedTx);
+        return txid;
+      }
+
+      const signedTx = await signer.signTransaction(transaction);
+      const { txid } = await tronWeb.trx.sendRawTransaction(signedTx);
+      return txid;
+    }
+
+    // TRC20 Token Transfer
+    const contractAddress = getContractAddress(assetValue);
+    if (!contractAddress) {
+      throw new SwapKitError("toolbox_tron_invalid_token_identifier", {
+        identifier: assetValue.toString(),
+      });
+    }
+
+    const feeLimit = calculateFeeLimit();
+    const contract = await tronWeb.contract(trc20ABI, contractAddress);
+
+    if (!contract.methods?.transfer) {
+      throw new SwapKitError("toolbox_tron_token_transfer_failed");
+    }
+
+    const txid = await contract.methods
+      .transfer(recipient, assetValue.getBaseValue("string"))
+      .send({
+        from,
+        feeLimit,
+        callValue: 0,
+      });
+
+    if (!txid) {
+      throw new SwapKitError("toolbox_tron_token_transfer_failed");
+    }
+
+    return txid;
+  };
+
+  const estimateTransactionFee = ({ assetValue }: TronTransferParams) => {
+    const isNative = assetValue.isGasAsset;
+
+    if (isNative) {
+      // Native TRX transfers typically consume bandwidth, which is free up to daily limit
+      // Return a minimal fee estimation for bandwidth cost
+      return AssetValue.from({ chain: Chain.Tron, value: 1 }); // 1 TRX
+    }
+
+    // TRC20 transfers consume energy, estimate higher fee
+    return AssetValue.from({ chain: Chain.Tron, value: 10 }); // 10 TRX
+  };
+
+  const createTransaction = async (params: TronTransferParams) => {
+    if (!signer) throw new SwapKitError("toolbox_tron_no_signer");
+
+    const { recipient, assetValue, memo } = params;
+    const from = await getAddress();
+    const isNative = assetValue.isGasAsset;
+
+    if (isNative) {
+      const transaction = await tronWeb.transactionBuilder.sendTrx(
+        recipient,
+        assetValue.getBaseValue("number"),
+        from,
+      );
+
+      if (memo) {
+        return tronWeb.transactionBuilder.addUpdateData(transaction, memo, "utf8");
+      }
+
+      return transaction;
+    }
+
+    // For TRC20, we would need to build the transaction manually
+    // This is a simplified version - in practice, you'd build the contract call transaction
+    const contractAddress = getContractAddress(assetValue);
+    if (!contractAddress) {
+      throw new SwapKitError("toolbox_tron_invalid_token_identifier", {
+        identifier: assetValue.toString(),
+      });
+    }
+
+    // Build TRC20 transfer transaction
+    const functionSelector = "transfer(address,uint256)";
+    const parameter = [
+      { type: "address", value: recipient },
+      { type: "uint256", value: assetValue.getBaseValue("string") },
+    ];
+
+    const result = await tronWeb.transactionBuilder.triggerSmartContract(
+      contractAddress,
+      functionSelector,
+      {},
+      parameter,
+      from,
+    );
+
+    return result.transaction;
+  };
+
+  const signTransaction = async (transaction: TronTransaction) => {
+    if (!signer) throw new SwapKitError("toolbox_tron_no_signer");
+    return await signer.signTransaction(transaction);
+  };
+
+  const broadcastTransaction = async (signedTx: TronSignedTransaction) => {
+    const { txid } = await tronWeb.trx.sendRawTransaction(signedTx);
+    return txid;
+  };
+
+  return {
+    tronWeb,
+    getAddress,
+    validateAddress,
+    getBalance,
+    transfer,
+    estimateTransactionFee,
+    createTransaction,
+    signTransaction,
+    broadcastTransaction,
+  };
+};

package/src/tron/types.ts

@@ -0,0 +1,22 @@
+import type { DerivationPathArray, GenericTransferParams } from "@swapkit/helpers";
+import type { Contract, Types } from "tronweb";
+
+// Re-export TronWeb types for convenience
+export type TronTransaction = Types.Transaction;
+export type TronContract = Contract;
+export type TronSignedTransaction = Types.SignedTransaction;
+
+// Signer interface compatible with TronWeb and wallet implementations
+export interface TronSigner {
+  getAddress(): Promise<string>;
+  signTransaction(transaction: TronTransaction): Promise<TronSignedTransaction>;
+}
+
+export type TronToolboxOptions =
+  | { signer?: TronSigner }
+  | { phrase?: string; derivationPath?: DerivationPathArray; index?: number }
+  | {};
+
+export interface TronTransferParams extends GenericTransferParams {
+  // No additional fields needed - all inherited from GenericTransferParams
+}

package/src/utxo/helpers/api.ts

@@ -1,4 +1,11 @@
-import { Chain, RequestClient, SKConfig, type UTXOChain, warnOnce } from "@swapkit/helpers";
+import {
+  Chain,
+  RequestClient,
+  SKConfig,
+  SwapKitError,
+  type UTXOChain,
+  warnOnce,
+} from "@swapkit/helpers";
 import { networks } from "bitcoinjs-lib";
 import { uniqid } from "../../utils";
 
@@ -28,11 +35,13 @@ async function broadcastUTXOTx({ chain, txHash }: { chain: Chain; txHash: string
   }>(rpcUrl, { headers: { "Content-Type": "application/json" }, body });
 
   if (response.error) {
-    throw new Error(`failed to broadcast a transaction: ${response.error?.message}`);
+    throw new SwapKitError("toolbox_utxo_broadcast_failed", { error: response.error?.message });
   }
 
   if (response.result.includes('"code":-26')) {
-    throw new Error("Invalid transaction: the transaction amount was too low");
+    throw new SwapKitError("toolbox_utxo_invalid_transaction", {
+      error: "Transaction amount was too low",
+    });
   }
 
   return response.result;
@@ -93,7 +102,8 @@ async function getSuggestedTxFee(chain: Chain) {
 async function blockchairRequest<T>(url: string, apiKey?: string): Promise<T> {
   try {
     const response = await RequestClient.get<BlockchairResponse<T>>(url);
-    if (!response || response.context.code !== 200) throw new Error(`failed to query ${url}`);
+    if (!response || response.context.code !== 200)
+      throw new SwapKitError("toolbox_utxo_api_error", { error: `Failed to query ${url}` });
 
     return response.data as T;
   } catch (error) {
@@ -102,14 +112,16 @@ async function blockchairRequest<T>(url: string, apiKey?: string): Promise<T> {
       `${url}${apiKey ? `&key=${apiKey}` : ""}`,
     );
 
-    if (!response || response.context.code !== 200) throw new Error(`failed to query ${url}`);
+    if (!response || response.context.code !== 200)
+      throw new SwapKitError("toolbox_utxo_api_error", { error: `Failed to query ${url}` });
 
     return response.data as T;
   }
 }
 
 async function getAddressData({ address, chain, apiKey }: BlockchairParams<{ address?: string }>) {
-  if (!address) throw new Error("address is required");
+  if (!address)
+    throw new SwapKitError("toolbox_utxo_invalid_params", { error: "Address is required" });
 
   try {
     const response = await blockchairRequest<BlockchairAddressResponse>(
@@ -134,7 +146,8 @@ async function getUnconfirmedBalance({
 }
 
 async function getRawTx({ chain, apiKey, txHash }: BlockchairParams<{ txHash?: string }>) {
-  if (!txHash) throw new Error("txHash is required");
+  if (!txHash)
+    throw new SwapKitError("toolbox_utxo_invalid_params", { error: "TxHash is required" });
 
   try {
     const rawTxResponse = await blockchairRequest<BlockchairRawTransactionResponse>(
@@ -143,7 +156,7 @@ async function getRawTx({ chain, apiKey, txHash }: BlockchairParams<{ txHash?: s
     );
     return rawTxResponse?.[txHash]?.raw_transaction || "";
   } catch (error) {
-    console.error(error);
+    console.error("Failed to fetch raw transaction:", error);
     return "";
   }
 }
@@ -181,7 +194,8 @@ async function getUnspentUtxos({
   offset = 0,
   limit = 100,
 }: BlockchairFetchUnspentUtxoParams): Promise<Awaited<ReturnType<typeof fetchUnspentUtxoBatch>>> {
-  if (!address) throw new Error("address is required");
+  if (!address)
+    throw new SwapKitError("toolbox_utxo_invalid_params", { error: "Address is required" });
 
   try {
     const txs = await fetchUnspentUtxoBatch({ chain, address, apiKey, offset, limit });
@@ -198,7 +212,7 @@ async function getUnspentUtxos({
 
     return [...txs, ...nextBatch];
   } catch (error) {
-    console.error(error);
+    console.error("Failed to fetch unspent UTXOs:", error);
     return [];
   }
 }
@@ -282,7 +296,7 @@ export function getUtxoNetwork() {
         return coininfo.dogecoin.main.toBitcoinJS();
       }
       default:
-        throw new Error("Invalid chain");
+        throw new SwapKitError("toolbox_utxo_not_supported", { chain });
     }
   };
 }

package/src/utxo/helpers/bchaddrjs.ts

@@ -1,5 +1,6 @@
+import { SwapKitError } from "@swapkit/helpers";
 import base58check from "bs58check";
-// @ts-expect-error
+// @ts-ignore
 import cashaddr from "cashaddrjs";
 
 enum Format {
@@ -83,7 +84,7 @@ function decodeAddress(address: string) {
   } catch (_error) {
     // Try to decode as bitpay if cashaddr decoding fails.
   }
-  throw new Error("Received an invalid Bitcoin Cash address as input.");
+  throw new SwapKitError("toolbox_utxo_invalid_address", { address });
 }
 
 function decodeBase58Address(address: string) {
@@ -91,8 +92,7 @@ function decodeBase58Address(address: string) {
     const payload = base58check.decode(address);
 
     // BASE_58_CHECK_PAYLOAD_LENGTH
-    if (payload.length !== 21)
-      throw new Error("Received an invalid Bitcoin Cash address as input.");
+    if (payload.length !== 21) throw new SwapKitError("toolbox_utxo_invalid_address", { address });
     const versionByte = payload[0];
     const hash = Array.prototype.slice.call(payload, 1);
 
@@ -116,10 +116,10 @@ function decodeBase58Address(address: string) {
         return { hash, format: Format.Bitpay, network: UtxoNetwork.Mainnet, type: Type.P2SH };
 
       default:
-        throw new Error("Received an invalid Bitcoin Cash address as input.");
+        throw new SwapKitError("toolbox_utxo_invalid_address", { address });
     }
   } catch (_error) {
-    throw new Error("Received an invalid Bitcoin Cash address as input.");
+    throw new SwapKitError("toolbox_utxo_invalid_address", { address });
   }
 }
 
@@ -141,7 +141,7 @@ function decodeCashAddress(address: string) {
     }
   }
 
-  throw new Error("Received an invalid Bitcoin Cash address as input.");
+  throw new SwapKitError("toolbox_utxo_invalid_address", { address });
 }
 
 function decodeCashAddressWithPrefix(address: string): DecodedType {
@@ -155,7 +155,7 @@ function decodeCashAddressWithPrefix(address: string): DecodedType {
       type: type === "P2PKH" ? Type.P2PKH : Type.P2SH,
     };
   } catch (_error) {
-    throw new Error("Received an invalid Bitcoin Cash address as input.");
+    throw new SwapKitError("toolbox_utxo_invalid_address", { address });
   }
 }
 

package/src/utxo/helpers/coinselect.ts

@@ -1,4 +1,4 @@
-import { Chain, type UTXOChain } from "@swapkit/helpers";
+import { Chain, SwapKitError, type UTXOChain } from "@swapkit/helpers";
 
 import {
   TX_OVERHEAD,
@@ -21,7 +21,7 @@ export const getDustThreshold = (chain: UTXOChain) => {
     case Chain.Dogecoin:
       return 100000;
     default:
-      throw new Error("Invalid Chain");
+      throw new SwapKitError("toolbox_utxo_not_supported", { chain });
   }
 };
 

package/src/utxo/helpers/txSize.ts

@@ -1,3 +1,4 @@
+import { SwapKitError } from "@swapkit/helpers";
 import { opcodes, script } from "bitcoinjs-lib";
 import type {
   TargetOutput,
@@ -60,7 +61,7 @@ export const getScriptTypeForAddress = (address: string) => {
   ) {
     return UTXOScriptType.P2PKH;
   }
-  throw new Error("Invalid address");
+  throw new SwapKitError("toolbox_utxo_invalid_address", { address });
 };
 
 export const calculateTxSize = ({ inputs, outputs, feeRate }: UTXOCalculateTxSizeParams) => {

package/src/utxo/toolbox/bitcoinCash.ts

@@ -10,6 +10,7 @@ import {
   type DerivationPathArray,
   FeeOption,
   NetworkDerivationPath,
+  SwapKitError,
   derivationPathToString,
   updateDerivationPath,
 } from "@swapkit/helpers";
@@ -137,7 +138,8 @@ async function createTransaction({
   feeRate,
   sender,
 }: UTXOBuildTxParams) {
-  if (!bchValidateAddress(recipient)) throw new Error("Invalid address");
+  if (!bchValidateAddress(recipient))
+    throw new SwapKitError("toolbox_utxo_invalid_address", { address: recipient });
   const utxos = await getUtxoApi(chain).scanUTXOs({
     address: stripToCashAddress(sender),
     fetchTxHex: true,
@@ -159,7 +161,8 @@ async function createTransaction({
   });
 
   // .inputs and .outputs will be undefined if no solution was found
-  if (!(inputs && outputs)) throw new Error("Balance insufficient for transaction");
+  if (!(inputs && outputs))
+    throw new SwapKitError("toolbox_utxo_insufficient_balance", { sender, assetValue });
   const getNetwork = await getUtxoNetwork();
   const builder = new TransactionBuilder(getNetwork(chain)) as TransactionBuilderType;
 
@@ -204,8 +207,11 @@ function transfer({
     ...rest
   }: UTXOTransferParams) {
     const from = await signer?.getAddress();
-    if (!(signer && from)) throw new Error("Signer must provider address");
-    if (!recipient) throw new Error("Recipient address must be provided");
+    if (!(signer && from)) throw new SwapKitError("toolbox_utxo_no_signer");
+    if (!recipient)
+      throw new SwapKitError("toolbox_utxo_invalid_params", {
+        error: "Recipient address must be provided",
+      });
 
     const feeRate = rest.feeRate || (await getFeeRates())[feeOptionKey];
 
@@ -228,7 +234,8 @@ function transfer({
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: TODO: refactor
 async function buildTx({ assetValue, recipient, memo, feeRate, sender }: UTXOBuildTxParams) {
   const recipientCashAddress = toCashAddress(recipient);
-  if (!bchValidateAddress(recipientCashAddress)) throw new Error("Invalid address");
+  if (!bchValidateAddress(recipientCashAddress))
+    throw new SwapKitError("toolbox_utxo_invalid_address", { address: recipientCashAddress });
 
   const utxos = await getUtxoApi(chain).scanUTXOs({
     address: stripToCashAddress(sender),
@@ -259,7 +266,8 @@ async function buildTx({ assetValue, recipient, memo, feeRate, sender }: UTXOBui
   });
 
   // .inputs and .outputs will be undefined if no solution was found
-  if (!(inputs && outputs)) throw new Error("Balance insufficient for transaction");
+  if (!(inputs && outputs))
+    throw new SwapKitError("toolbox_utxo_insufficient_balance", { sender, assetValue });
   const getNetwork = await getUtxoNetwork();
   const psbt = new Psbt({ network: getNetwork(chain) }); // Network-specific
 

package/src/utxo/toolbox/index.ts

@@ -2,6 +2,7 @@ import {
   Chain,
   type ChainSigner,
   type DerivationPathArray,
+  SwapKitError,
   type UTXOChain,
 } from "@swapkit/helpers";
 import type { Psbt } from "bitcoinjs-lib";
@@ -65,7 +66,7 @@ export async function getUtxoToolbox<T extends keyof UTXOToolboxes>(
     }
 
     default:
-      throw new Error(`Chain ${chain} is not supported`);
+      throw new SwapKitError("toolbox_utxo_not_supported", { chain });
   }
 }