@swapkit/toolboxes 1.0.0-beta.23 → 1.0.0-beta.25

package/src/substrate/balance.ts

@@ -0,0 +1,92 @@
+import type { ApiPromise } from "@polkadot/api";
+import { AssetValue, Chain, SwapKitNumber } from "@swapkit/helpers";
+
+/**
+ * Get balance for standard Substrate chains (Polkadot, etc.)
+ * Uses api.query.system.account to query free and reserved balances
+ */
+export async function getSubstrateBalance(
+  api: ApiPromise,
+  gasAsset: AssetValue,
+  address: string,
+): Promise<AssetValue[]> {
+  try {
+    const account = await api.query.system?.account?.(address);
+
+    if (!account) {
+      return [gasAsset.set(0)];
+    }
+
+    const {
+      // @ts-expect-error
+      data: { free },
+    } = account;
+
+    // Convert the free balance to string using SwapKitNumber for proper decimal handling
+    const freeBalance = SwapKitNumber.fromBigInt(
+      BigInt(free.toString()),
+      gasAsset.decimal,
+    ).getValue("string");
+
+    return [gasAsset.set(freeBalance)];
+  } catch (error) {
+    console.error("Error fetching substrate balance:", error);
+    return [gasAsset.set(0)];
+  }
+}
+
+/**
+ * Get balance for Chainflip chain
+ * Uses api.query.flip.account to query FLIP balances
+ */
+export async function getChainflipBalance(
+  api: ApiPromise,
+  gasAsset: AssetValue,
+  address: string,
+): Promise<AssetValue[]> {
+  try {
+    // Chainflip uses a custom flip pallet for account balances
+    const flipAccount = await api.query.flip?.account?.(address);
+
+    if (!flipAccount) {
+      return [gasAsset.set(0)];
+    }
+
+    // Extract balance from the flip account structure
+    // The structure has a balance field directly
+    //@ts-expect-error
+    const balance = flipAccount.balance || flipAccount.data?.balance;
+
+    if (!balance || balance.isEmpty) {
+      return [gasAsset.set(0)];
+    }
+
+    // Convert balance to string using SwapKitNumber
+    const balanceStr = SwapKitNumber.fromBigInt(
+      BigInt(balance.toString()),
+      gasAsset.decimal,
+    ).getValue("string");
+
+    return [gasAsset.set(balanceStr)];
+  } catch (error) {
+    console.error("Error fetching chainflip balance:", error);
+    return [gasAsset.set(0)];
+  }
+}
+
+/**
+ * Factory function to create chain-specific balance getter
+ */
+export function createBalanceGetter(chain: Chain, api: ApiPromise) {
+  return function getBalance(address: string): Promise<AssetValue[]> {
+    const gasAsset = AssetValue.from({ chain });
+
+    switch (chain) {
+      case Chain.Chainflip:
+        return getChainflipBalance(api, gasAsset, address);
+
+      default:
+        return getSubstrateBalance(api, gasAsset, address);
+    }
+  };
+}

package/src/substrate/substrate.ts

@@ -19,7 +19,7 @@ import {
 } from "@swapkit/helpers";
 
 import { P, match } from "ts-pattern";
-import { getBalance } from "../utils";
+import { createBalanceGetter } from "./balance";
 import { SubstrateNetwork, type SubstrateTransferParams } from "./types";
 
 export const PolkadotToolbox = ({ generic = false, ...signerParams }: ToolboxParams = {}) => {
@@ -36,7 +36,7 @@ export const ChainflipToolbox = async ({
     ...signerParams,
   });
 
-  return { ...toolbox, getBalance: getBalance(Chain.Chainflip) };
+  return { ...toolbox };
 };
 
 export type SubstrateToolboxes = {
@@ -208,11 +208,13 @@ export const BaseSubstrateToolbox = ({
   network,
   gasAsset,
   signer,
+  chain,
 }: {
   api: ApiPromise;
   network: SubstrateNetwork;
   gasAsset: AssetValue;
   signer?: IKeyringPair | Signer;
+  chain?: SubstrateChain;
 }) => ({
   api,
   network,
@@ -220,7 +222,7 @@ export const BaseSubstrateToolbox = ({
   decodeAddress,
   encodeAddress,
   convertAddress,
-  getBalance: getBalance(Chain.Polkadot),
+  getBalance: createBalanceGetter(chain || Chain.Polkadot, api),
   createKeyring: (phrase: string) => createKeyring(phrase, network.prefix),
   getAddress: (keyring?: IKeyringPair | Signer) => {
     const keyringPair = keyring || signer;
@@ -301,7 +303,7 @@ export async function createSubstrateToolbox({
     .with({ signer: P.any }, ({ signer }) => signer)
     .otherwise(() => undefined);
 
-  return BaseSubstrateToolbox({ api, signer, gasAsset, network });
+  return BaseSubstrateToolbox({ api, signer, gasAsset, network, chain });
 }
 
 export type ToolboxParams = {

package/src/tron/toolbox.ts

@@ -96,7 +96,7 @@ async function createKeysForPath({
 }
 
 export const createTronToolbox = async (options: TronToolboxOptions = {}) => {
-  const { TronWeb } = require("tronweb");
+  const { TronWeb } = await import("tronweb");
   // 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

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

@@ -59,6 +59,8 @@ function getDefaultTxFeeByChain(chain: Chain) {
       return 10000;
     case Chain.Litecoin:
       return 1;
+    case Chain.Zcash:
+      return 1;
     default:
       return 2;
   }
@@ -74,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:
@@ -277,6 +281,31 @@ export function getUtxoApi(chain: UTXOChain) {
   return utxoApi(chain);
 }
 
+// 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) {
@@ -295,6 +324,13 @@ export 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 SwapKitError("toolbox_utxo_not_supported", { chain });
     }

package/src/utxo/helpers/coinselect.ts

@@ -20,6 +20,8 @@ export const getDustThreshold = (chain: UTXOChain) => {
       return 5500;
     case Chain.Dogecoin:
       return 100000;
+    case Chain.Zcash:
+      return 546;
     default:
       throw new SwapKitError("toolbox_utxo_not_supported", { chain });
   }

package/src/utxo/index.ts

@@ -1,5 +1,6 @@
 export * from "./toolbox";
 export * from "./toolbox/bitcoinCash";
 export * from "./toolbox/utxo";
+export * from "./toolbox/zcash";
 export * from "./helpers";
 export * from "./types";

package/src/utxo/toolbox/index.ts

@@ -10,11 +10,13 @@ import type { Psbt } from "bitcoinjs-lib";
 import type { TransactionBuilderType, TransactionType, UTXOType } from "../types";
 import { createBCHToolbox } from "./bitcoinCash";
 import { createUTXOToolbox } from "./utxo";
+import { createZcashToolbox } from "./zcash";
 
 type BCHToolbox = Awaited<ReturnType<typeof createBCHToolbox>>;
 type CommonUTXOToolbox = Awaited<
-  ReturnType<typeof createUTXOToolbox<Exclude<UTXOChain, Chain.BitcoinCash>>>
+  ReturnType<typeof createUTXOToolbox<Exclude<UTXOChain, Chain.BitcoinCash | Chain.Zcash>>>
 >;
+type ZcashToolbox = Awaited<ReturnType<typeof createZcashToolbox>>;
 
 export type UTXOToolboxes = {
   [Chain.BitcoinCash]: BCHToolbox;
@@ -22,6 +24,7 @@ export type UTXOToolboxes = {
   [Chain.Dogecoin]: CommonUTXOToolbox;
   [Chain.Litecoin]: CommonUTXOToolbox;
   [Chain.Dash]: CommonUTXOToolbox;
+  [Chain.Zcash]: ZcashToolbox;
 };
 
 export type UTXOWallets = {
@@ -36,6 +39,9 @@ export type UtxoToolboxParams = {
   [Chain.Dogecoin]: { signer: ChainSigner<Psbt, Psbt> };
   [Chain.Litecoin]: { signer: ChainSigner<Psbt, Psbt> };
   [Chain.Dash]: { signer: ChainSigner<Psbt, Psbt> };
+  [Chain.Zcash]: {
+    signer?: ChainSigner<Psbt, Psbt>;
+  };
 };
 
 export async function getUtxoToolbox<T extends keyof UTXOToolboxes>(
@@ -54,15 +60,20 @@ export async function getUtxoToolbox<T extends keyof UTXOToolboxes>(
       return toolbox as UTXOToolboxes[T];
     }
 
+    case Chain.Zcash: {
+      const toolbox = await createZcashToolbox(params as UtxoToolboxParams[Chain.Zcash]);
+      return toolbox as UTXOToolboxes[T];
+    }
+
     case Chain.Bitcoin:
     case Chain.Dogecoin:
     case Chain.Litecoin:
     case Chain.Dash: {
       const toolbox = await createUTXOToolbox({
         chain,
-        ...(params as UtxoToolboxParams[Exclude<T, Chain.BitcoinCash>]),
+        ...(params as UtxoToolboxParams[Exclude<T, Chain.BitcoinCash | Chain.Zcash>]),
       });
-      return toolbox as UTXOToolboxes[Exclude<T, Chain.BitcoinCash>];
+      return toolbox as UTXOToolboxes[Exclude<T, Chain.BitcoinCash | Chain.Zcash>];
     }
 
     default:

package/src/utxo/toolbox/utxo.ts

@@ -42,6 +42,7 @@ import secp256k1 from "@bitcoinerlab/secp256k1";
 import { ECPair, HDNode } from "@psf/bitcoincashjs-lib";
 import { HDKey } from "@scure/bip32";
 import { mnemonicToSeedSync } from "@scure/bip39";
+import { validateZcashAddress } from "./zcash";
 
 export const nonSegwitChains = [Chain.Dash, Chain.Dogecoin];
 
@@ -153,6 +154,10 @@ export async function getUTXOAddressValidator() {
       return bchValidateAddress(address);
     }
 
+    if (chain === Chain.Zcash) {
+      return validateZcashAddress(address);
+    }
+
     try {
       initEccLib(secp256k1);
       btcLibAddress.toOutputScript(address, getNetwork(chain));
@@ -351,6 +356,7 @@ type CreateKeysForPathReturnType = {
   [Chain.Dash]: ECPairInterface;
   [Chain.Dogecoin]: ECPairInterface;
   [Chain.Litecoin]: ECPairInterface;
+  [Chain.Zcash]: ECPairInterface;
 };
 
 export async function getCreateKeysForPath<T extends keyof CreateKeysForPathReturnType>(
@@ -395,6 +401,7 @@ export async function getCreateKeysForPath<T extends keyof CreateKeysForPathRetu
     case Chain.Bitcoin:
     case Chain.Dogecoin:
     case Chain.Litecoin:
+    case Chain.Zcash:
     case Chain.Dash: {
       return function createKeysForPath({
         phrase,

package/src/utxo/toolbox/zcash.ts

@@ -0,0 +1,208 @@
+import secp256k1 from "@bitcoinerlab/secp256k1";
+import { HDKey } from "@scure/bip32";
+import { mnemonicToSeedSync } from "@scure/bip39";
+import {
+  Chain,
+  type ChainSigner,
+  type DerivationPathArray,
+  FeeOption,
+  NetworkDerivationPath,
+  SKConfig,
+  SwapKitError,
+  derivationPathToString,
+  updateDerivationPath,
+} from "@swapkit/helpers";
+import type { Psbt } from "bitcoinjs-lib";
+import { hash160 } from "bitcoinjs-lib/src/crypto";
+import bs58check from "bs58check";
+import ECPairFactory from "ecpair";
+import { P, match } from "ts-pattern";
+import { getUtxoNetwork } from "../helpers";
+import type { UTXOBuildTxParams, UTXOTransferParams } from "../types";
+import { createUTXOToolbox } from "./utxo";
+
+const chain = Chain.Zcash;
+const network = getUtxoNetwork()(chain);
+
+/**
+ * Custom Zcash address generation that handles 2-byte prefixes
+ *
+ * Zcash transparent addresses use 2-byte version prefixes, unlike Bitcoin's single byte.
+ * This is incompatible with bitcoinjs-lib's payment methods which expect UInt8 values.
+ *
+ * @param publicKey - The public key buffer to generate address from
+ * @param isTestnet - Whether to generate testnet or mainnet address
+ * @returns A valid Zcash transparent address (t1... for mainnet, tm... for testnet)
+ */
+function generateZcashAddress(publicKey: Buffer, isTestnet = false): string {
+  // Hash the public key using RIPEMD160(SHA256(pubkey))
+  const publicKeyHash = hash160(publicKey);
+
+  // Zcash uses 2-byte prefixes for transparent addresses
+  // These prefixes ensure addresses start with expected characters when base58 encoded
+  const prefix = isTestnet
+    ? Buffer.from([0x1c, 0xba]) // testnet prefix (results in tm... addresses)
+    : Buffer.from([0x1c, 0xb8]); // mainnet prefix (results in t1... addresses)
+
+  // Combine prefix + hash (22 bytes total: 2 byte prefix + 20 byte hash)
+  const payload = Buffer.concat([prefix, publicKeyHash]);
+
+  // Encode with base58check for final address
+  return bs58check.encode(payload);
+}
+
+export function validateZcashAddress(address: string) {
+  try {
+    // Shielded addresses are not supported
+    if (address.startsWith("z")) {
+      console.warn(
+        "Shielded Zcash addresses (z-addresses) are not supported. Use transparent addresses (t1/t3) only.",
+      );
+      return false;
+    }
+
+    const isMainnet = address.startsWith("t1");
+    const isTestnet = address.startsWith("t3");
+
+    if (!(isMainnet || isTestnet)) {
+      return false;
+    }
+
+    // Verify network matches address type
+    const { isStagenet } = SKConfig.get("envs");
+    if ((isMainnet && isStagenet) || (isTestnet && !isStagenet)) {
+      return false;
+    }
+
+    return validateBase58Check(address, network);
+  } catch {
+    return false;
+  }
+}
+
+function validateBase58Check(
+  address: string,
+  network: ReturnType<ReturnType<typeof getUtxoNetwork>>,
+) {
+  try {
+    const decoded = bs58check.decode(address);
+
+    if (decoded.length < 21) {
+      return false;
+    }
+
+    const version = decoded[0];
+    return version === network.pubKeyHash || version === network.scriptHash;
+  } catch {
+    return false;
+  }
+}
+
+const ECPair = ECPairFactory(secp256k1);
+
+type ZcashSigner = ChainSigner<Psbt, Psbt>;
+
+async function createZcashSignerFromPhrase({
+  phrase,
+  derivationPathString,
+}: {
+  phrase: string;
+  derivationPathString: string;
+}) {
+  const seed = mnemonicToSeedSync(phrase);
+  const root = HDKey.fromMasterSeed(seed);
+
+  const node = root.derive(derivationPathString);
+
+  if (!node.privateKey) {
+    throw new Error("Unable to derive private key");
+  }
+
+  const keyPair = ECPair.fromPrivateKey(Buffer.from(node.privateKey), { network });
+
+  const { isStagenet } = SKConfig.get("envs");
+  const address = generateZcashAddress(keyPair.publicKey, isStagenet);
+
+  return {
+    getAddress() {
+      return Promise.resolve(address);
+    },
+
+    signTransaction(psbt: Psbt) {
+      for (let i = 0; i < psbt.inputCount; i++) {
+        psbt.signInput(i, keyPair);
+      }
+      return Promise.resolve(psbt);
+    },
+  };
+}
+
+export async function createZcashToolbox(
+  toolboxParams:
+    | {
+        signer?: ZcashSigner;
+      }
+    | {
+        phrase?: string;
+        derivationPath?: DerivationPathArray;
+        index?: number;
+      },
+) {
+  const signer = await match(toolboxParams)
+    .with({ signer: P.not(P.nullish) }, ({ signer }) => Promise.resolve(signer))
+    .with({ phrase: P.string }, ({ phrase, derivationPath, index = 0 }) => {
+      // Handle derivation path processing at toolbox level
+      const baseDerivationPath = derivationPath ||
+        NetworkDerivationPath[Chain.Zcash] || [44, 133, 0, 0, 0];
+      const updatedDerivationPath = updateDerivationPath(baseDerivationPath, { index });
+      const derivationPathString = derivationPathToString(updatedDerivationPath);
+
+      return createZcashSignerFromPhrase({ phrase, derivationPathString });
+    })
+    .otherwise(() => Promise.resolve(undefined));
+
+  const { getFeeRates, broadcastTx, ...toolbox } = await createUTXOToolbox({
+    chain: Chain.Zcash,
+    signer,
+  });
+
+  function getAddressFromKeys(keys: { getAddress: () => string }) {
+    return keys.getAddress();
+  }
+
+  async function transfer({
+    recipient,
+    assetValue,
+    feeOptionKey = FeeOption.Fast,
+    ...rest
+  }: UTXOTransferParams) {
+    const from = await signer?.getAddress();
+    if (!(signer && from)) throw new SwapKitError("toolbox_utxo_no_signer");
+
+    const feeRate = rest.feeRate || (await getFeeRates())[feeOptionKey];
+
+    const buildTxParams: UTXOBuildTxParams = {
+      ...rest,
+      assetValue,
+      feeRate,
+      recipient,
+      sender: from,
+    };
+
+    const { psbt } = await toolbox.createTransaction(buildTxParams);
+    const signedPsbt = await signer.signTransaction(psbt);
+    signedPsbt.finalizeAllInputs();
+    const txHex = signedPsbt.extractTransaction().toHex();
+
+    return broadcastTx(txHex);
+  }
+
+  return {
+    ...toolbox,
+    broadcastTx,
+    getFeeRates,
+    transfer,
+    getAddressFromKeys,
+    validateAddress: validateZcashAddress,
+  };
+}