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

package/src/evm/__tests__/address-validation.test.ts

@@ -0,0 +1,86 @@
+import { beforeAll, describe, expect, test } from "bun:test";
+import { Chain } from "@swapkit/helpers";
+import { getEvmToolbox } from "../toolbox";
+
+const context: {
+  validateAddress: (address: string) => boolean;
+} = {} as any;
+
+beforeAll(async () => {
+  // Get EVM toolbox for address validation
+  const toolbox = await getEvmToolbox(Chain.Ethereum);
+  context.validateAddress = toolbox.validateAddress;
+});
+
+describe("EVM Address Validation", () => {
+  test("should validate valid EVM addresses", () => {
+    const validAddresses = [
+      "0xa052Ddf1c1739419B90FB7bf722843AD3e63114B", // User provided address
+      "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC contract
+      "0x6d6e022eE439C8aB8B7a7dBb0576f8090319CDc6", // Test address
+      "0xE29E61479420Dd1029A9946710Ac31A0d140e77F", // Another valid address
+      "0x0000000000000000000000000000000000000000", // Zero address
+      "0xFFfFfFffFFfffFFfFFfFFFFFffFFFffffFfFFFfF", // Max address
+      "0x1234567890123456789012345678901234567890", // Mixed case
+    ];
+
+    for (const address of validAddresses) {
+      expect(context.validateAddress(address)).toBe(true);
+    }
+  });
+
+  test("should reject invalid EVM addresses", () => {
+    const invalidAddresses = [
+      "", // Empty string
+      "invalid", // Random string
+      "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", // TRON address
+      "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa", // Bitcoin address
+      "cosmos1abc123", // Cosmos address
+      "0xa052Ddf1c1739419B90FB7bf722843AD3e63114", // Too short (missing 1 char)
+      "0xa052Ddf1c1739419B90FB7bf722843AD3e63114BB", // Too long (extra char)
+      "0XA052DDF1C1739419B90FB7BF722843AD3E63114B", // Uppercase 0X prefix
+      "0xG052Ddf1c1739419B90FB7bf722843AD3e63114B", // Invalid hex character
+      "0x", // Only prefix
+    ];
+
+    for (const address of invalidAddresses) {
+      expect(context.validateAddress(address)).toBe(false);
+    }
+  });
+
+  test("should handle case normalization properly", () => {
+    const address = "0xa052Ddf1c1739419B90FB7bf722843AD3e63114B"; // Proper checksum
+    const lowerCase = address.toLowerCase();
+
+    // Valid case variations should be accepted
+    expect(context.validateAddress(address)).toBe(true);
+    expect(context.validateAddress(lowerCase)).toBe(true);
+  });
+
+  test("should reject invalid checksum addresses", () => {
+    const invalidChecksumAddress = "0xA052dDF1C1739419b90fb7BF722843ad3E63114b"; // Invalid checksum
+
+    // Should reject mixed case with invalid checksum
+    expect(context.validateAddress(invalidChecksumAddress)).toBe(false);
+  });
+
+  test("should handle edge cases", () => {
+    const edgeCases = [null, undefined, 123, {}, [], true, false];
+
+    for (const testCase of edgeCases) {
+      // Should not throw but return false for invalid inputs
+      expect(context.validateAddress(testCase as any)).toBe(false);
+    }
+  });
+
+  test("should validate checksummed addresses", () => {
+    const checksummedAddresses = [
+      "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC with proper checksum
+      "0x6d6e022eE439C8aB8B7a7dBb0576f8090319CDc6", // Another checksummed address
+    ];
+
+    for (const address of checksummedAddresses) {
+      expect(context.validateAddress(address)).toBe(true);
+    }
+  });
+});

package/src/index.ts

@@ -192,6 +192,7 @@ export async function getToolbox<T extends keyof Toolboxes>(
       Chain.Dogecoin,
       Chain.BitcoinCash,
       Chain.Bitcoin,
+      Chain.Zcash,
       async () => {
         const { getUtxoToolbox } = await import("@swapkit/toolboxes/utxo");
         const utxoToolbox = await getUtxoToolbox(

package/src/near/toolbox.ts

@@ -117,8 +117,29 @@ export async function getNearToolbox(toolboxParams?: NearToolboxParams) {
   async function createTransaction(params: NearCreateTransactionParams) {
     const { recipient, assetValue, memo, feeRate: gas, attachedDeposit, sender: signerId } = params;
 
-    const { publicKey, nonce } = await getFullAccessPublicKey(provider, signerId);
+    // Handle NEP-141 token transfers
+    if (!assetValue.isGasAsset) {
+      const contractId = assetValue.address;
+      if (!contractId) {
+        throw new SwapKitError("toolbox_near_missing_contract_address");
+      }
+
+      return createContractFunctionCall({
+        sender: signerId,
+        contractId,
+        methodName: "ft_transfer",
+        args: {
+          receiver_id: recipient,
+          amount: assetValue.getBaseValue("string"),
+          memo: memo || null,
+        },
+        gas: gas.toString() || "100000000000000", // 100 TGas default
+        attachedDeposit: "1", // 1 yoctoNEAR required for NEP-141 transfers
+      });
+    }
 
+    // Native NEAR transfer
+    const { publicKey, nonce } = await getFullAccessPublicKey(provider, signerId);
     const baseAmount = assetValue.getBaseValue("bigint");
 
     const { SCHEMA } = await import("near-api-js/lib/transaction");

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,