@swapkit/toolboxes 1.0.0-beta.3 → 1.0.0-beta.31

package/src/tron/toolbox.ts

@@ -0,0 +1,336 @@
+import {
+  AssetValue,
+  Chain,
+  NetworkDerivationPath,
+  SKConfig,
+  SwapKitError,
+  derivationPathToString,
+  updateDerivationPath,
+  warnOnce,
+} from "@swapkit/helpers";
+import { P, match } from "ts-pattern";
+
+import { trc20ABI } from "./helpers/trc20.abi.js";
+import type {
+  TronCreateTransactionParams,
+  TronSignedTransaction,
+  TronSigner,
+  TronToolboxOptions,
+  TronTransaction,
+  TronTransferParams,
+} from "./types.js";
+
+import { TronWeb } from "tronweb";
+
+export async function getTronAddressValidator() {
+  return (address: string) => {
+    return 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;
+}) {
+  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 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 = assetValue.address;
+    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: TronCreateTransactionParams) => {
+    const { recipient, assetValue, memo, sender } = params;
+    const isNative = assetValue.isGasAsset;
+
+    if (isNative) {
+      const transaction = await tronWeb.transactionBuilder.sendTrx(
+        recipient,
+        assetValue.getBaseValue("number"),
+        sender,
+      );
+
+      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 = assetValue.address;
+    if (!contractAddress) {
+      throw new SwapKitError("toolbox_tron_invalid_token_identifier", {
+        identifier: assetValue.toString(),
+      });
+    }
+
+    // Build TRC20 transfer transaction
+    // First, try using triggerSmartContract (might work despite the known bug)
+    try {
+      const functionSelector = "transfer(address,uint256)";
+      const parameter = [
+        { type: "address", value: recipient },
+        { type: "uint256", value: assetValue.getBaseValue("string") },
+      ];
+
+      const options = {
+        feeLimit: calculateFeeLimit(),
+        callValue: 0,
+      };
+
+      const result = await tronWeb.transactionBuilder.triggerSmartContract(
+        contractAddress,
+        functionSelector,
+        options,
+        parameter,
+        sender,
+      );
+
+      return result.transaction;
+    } catch (error) {
+      // If both methods fail, throw a descriptive error
+      throw new SwapKitError("toolbox_tron_transaction_creation_failed", {
+        message:
+          "Failed to create TRC20 transaction. This might be due to TronWeb 6.0.3 bug. Use the transfer method directly instead.",
+        originalError: error instanceof Error ? error.message : String(error),
+      });
+    }
+  };
+
+  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: await getTronAddressValidator(),
+    getBalance,
+    transfer,
+    estimateTransactionFee,
+    createTransaction,
+    signTransaction,
+    broadcastTransaction,
+  };
+};

package/src/tron/types.ts

@@ -0,0 +1,31 @@
+import type {
+  DerivationPathArray,
+  GenericCreateTransactionParams,
+  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
+}
+
+export interface TronCreateTransactionParams
+  extends Omit<GenericCreateTransactionParams, "feeRate"> {
+  // No additional fields needed - all inherited from GenericCreateTransactionParams
+}

package/src/utxo/__tests__/zcash-integration.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from "bun:test";
+import { Chain, DerivationPath } from "@swapkit/helpers";
+import { getUtxoToolbox } from "../toolbox";
+
+describe("UTXO Toolbox Zcash Integration", () => {
+  const testPhrase =
+    "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about";
+
+  it("should create Zcash toolbox through main UTXO toolbox factory", async () => {
+    const toolbox = await getUtxoToolbox(Chain.Zcash);
+
+    expect(toolbox).toBeDefined();
+    expect(typeof toolbox.validateAddress).toBe("function");
+    expect(typeof toolbox.getBalance).toBe("function");
+    expect(typeof toolbox.getFeeRates).toBe("function");
+    expect(typeof toolbox.broadcastTx).toBe("function");
+    expect(typeof toolbox.createTransaction).toBe("function");
+    expect(typeof toolbox.transfer).toBe("function");
+  });
+
+  it("should create Zcash toolbox with phrase", async () => {
+    const toolbox = await getUtxoToolbox(Chain.Zcash, {
+      phrase: testPhrase,
+    });
+
+    expect(toolbox).toBeDefined();
+    expect(() => toolbox.getAddress()).not.toThrow();
+  });
+
+  it("should generate valid Zcash addresses", async () => {
+    const toolbox = await getUtxoToolbox(Chain.Zcash, {
+      phrase: testPhrase,
+    });
+
+    const address = await toolbox.getAddress();
+    expect(address).toBeDefined();
+    expect(typeof address).toBe("string");
+    expect(address?.startsWith("t1")).toBe(true); // Zcash mainnet addresses start with t1
+    expect(toolbox.validateAddress(address || "")).toBe(true);
+  });
+
+  it("should validate Zcash addresses correctly", async () => {
+    const toolbox = await getUtxoToolbox(Chain.Zcash);
+
+    // Valid Zcash mainnet address format
+    expect(toolbox.validateAddress("t1XVXWCvpMgBvUaed4XDqWtgQgJSu1Ghz7F")).toBe(true);
+
+    // Invalid addresses
+    expect(toolbox.validateAddress("1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2")).toBe(false); // Bitcoin address
+    expect(toolbox.validateAddress("zcash:qr5agtachyxvrwxu76vzszan5pnvuzy8dm")).toBe(false); // Wrong format
+    expect(toolbox.validateAddress("")).toBe(false); // Empty string
+    expect(toolbox.validateAddress("invalid")).toBe(false); // Invalid string
+  });
+
+  it("should reject shielded addresses", async () => {
+    const toolbox = await getUtxoToolbox(Chain.Zcash);
+
+    // Test z-address (shielded) - should be rejected with warning
+    const originalWarn = console.warn;
+    let warnCalled = false;
+    let warnMessage = "";
+
+    console.warn = (message: string) => {
+      warnCalled = true;
+      warnMessage = message;
+    };
+
+    const isValid = toolbox.validateAddress(
+      "zs1z7rejlpsa98s2rrrfkwmaxu2xldqmfq5nj2m3hq6s7r8qjq8eqqqq9p4e7x",
+    );
+
+    expect(isValid).toBe(false);
+    expect(warnCalled).toBe(true);
+    expect(warnMessage).toBe(
+      "Shielded Zcash addresses (z-addresses) are not supported. Use transparent addresses (t1/t3) only.",
+    );
+
+    console.warn = originalWarn;
+  });
+
+  it("should create keys for derivation path", async () => {
+    const toolbox = await getUtxoToolbox(Chain.Zcash, {
+      phrase: testPhrase,
+    });
+
+    const keys = await toolbox.createKeysForPath({
+      phrase: testPhrase,
+      derivationPath: DerivationPath.ZEC,
+    });
+
+    expect(keys).toBeDefined();
+    expect(keys.publicKey).toBeDefined();
+    expect(keys.privateKey).toBeDefined();
+    expect(typeof keys.toWIF).toBe("function");
+
+    const address = await toolbox.getAddress();
+    expect(address).toBeDefined();
+    expect(address?.startsWith("t1")).toBe(true);
+  });
+
+  it("should get WIF private key from mnemonic", async () => {
+    const toolbox = await getUtxoToolbox(Chain.Zcash, {
+      phrase: testPhrase,
+    });
+
+    const wif = await toolbox.getPrivateKeyFromMnemonic({
+      phrase: testPhrase,
+      derivationPath: DerivationPath.ZEC,
+    });
+
+    expect(typeof wif).toBe("string");
+    expect(wif.length).toBeGreaterThan(50); // WIF keys are typically 51-52 characters
+  });
+});

package/src/utxo/helpers/api.ts

@@ -1,6 +1,17 @@
-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";
 
+// @ts-ignore
+import coininfo from "coininfo";
+
 type BlockchairParams<T> = T & { chain: Chain; apiKey?: string };
 type BlockchairFetchUnspentUtxoParams = BlockchairParams<{
   offset?: number;
@@ -24,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;
@@ -46,6 +59,8 @@ function getDefaultTxFeeByChain(chain: Chain) {
       return 10000;
     case Chain.Litecoin:
       return 1;
+    case Chain.Zcash:
+      return 1;
     default:
       return 2;
   }
@@ -61,6 +76,8 @@ function mapChainToBlockchairChain(chain: Chain) {
       return "dash";
     case Chain.Dogecoin:
       return "dogecoin";
+    case Chain.Zcash:
+      return "zcash";
     case Chain.Polkadot:
       return "polkadot";
     default:
@@ -89,7 +106,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) {
@@ -98,14 +116,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>(
@@ -130,7 +150,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>(
@@ -139,7 +160,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 "";
   }
 }
@@ -177,7 +198,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 });
@@ -194,7 +216,7 @@ async function getUnspentUtxos({
 
     return [...txs, ...nextBatch];
   } catch (error) {
-    console.error(error);
+    console.error("Failed to fetch unspent UTXOs:", error);
     return [];
   }
 }
@@ -259,11 +281,32 @@ export function getUtxoApi(chain: UTXOChain) {
   return utxoApi(chain);
 }
 
-export async function getUtxoNetwork() {
-  // @ts-ignore
-  const coininfo = await import("coininfo");
-  const { networks } = await import("bitcoinjs-lib");
-
+// Define Zcash network objects that match ECPair's expected interface
+const ZCASH_MAINNET = {
+  messagePrefix: "\x19Zcash Signed Message:\n",
+  bech32: "zc",
+  bip32: {
+    public: 0x0488b21e,
+    private: 0x0488ade4,
+  },
+  pubKeyHash: 0x1c, // 28 in decimal - correct for Zcash mainnet
+  scriptHash: 0x1c, // 28 in decimal
+  wif: 0x80, // 128 in decimal
+};
+
+const ZCASH_TESTNET = {
+  messagePrefix: "\x19Zcash Signed Message:\n",
+  bech32: "ztestsapling",
+  bip32: {
+    public: 0x043587cf,
+    private: 0x04358394,
+  },
+  pubKeyHash: 0x1d, // 29 in decimal - correct for Zcash testnet
+  scriptHash: 0x1c, // 28 in decimal
+  wif: 0xef, // 239 in decimal
+};
+
+export function getUtxoNetwork() {
   return function getNetwork(chain: Chain) {
     switch (chain) {
       case Chain.Bitcoin:
@@ -281,8 +324,15 @@ export async function getUtxoNetwork() {
         test.versions.bip32 = bip32;
         return coininfo.dogecoin.main.toBitcoinJS();
       }
+
+      case Chain.Zcash: {
+        // Get Zcash network configuration using our custom objects
+        const { isStagenet } = SKConfig.get("envs");
+        return isStagenet ? ZCASH_TESTNET : ZCASH_MAINNET;
+      }
+
       default:
-        throw new Error("Invalid chain");
+        throw new SwapKitError("toolbox_utxo_not_supported", { chain });
     }
   };
 }