@cryptforge/blockchain-evm 0.1.0

package/dist/index.js

@@ -0,0 +1,1146 @@
+'use strict';
+
+var ethers = require('ethers');
+
+// src/EVMAdapter.ts
+var EVMAdapter = class {
+  /**
+   * Create a new EVM blockchain adapter
+   * @param config - Chain configuration
+   */
+  constructor(config) {
+    this.chainData = config.chainData;
+    this.coinType = config.coinType ?? 60;
+    this.standardDecimals = config.standardDecimals ?? 18;
+    this.account = config.account ?? 0;
+    this.change = config.change ?? 0;
+    this.addressIndex = config.addressIndex ?? 0;
+    this.networks = {};
+    if (config.networks) {
+      for (const [key, value] of Object.entries(config.networks)) {
+        if (value !== void 0) {
+          this.networks[key] = value;
+        }
+      }
+    }
+    this.currentNetworkKey = config.defaultNetwork ?? "mainnet";
+    this.dataProvider = config.dataProvider;
+  }
+  /**
+   * Get the BIP44 derivation path for this chain
+   * @returns BIP44 path string (e.g., "m/44'/60'/0'/0/0")
+   */
+  getDerivationPath() {
+    return `m/44'/${this.coinType}'/${this.account}'/${this.change}/${this.addressIndex}`;
+  }
+  /**
+   * Get the current network configuration
+   * @returns Current network configuration, or undefined if no network is configured
+   */
+  getNetwork() {
+    return this.networks[this.currentNetworkKey];
+  }
+  /**
+   * Get the current network key (e.g., 'mainnet', 'testnet')
+   * @returns Current network key
+   */
+  getCurrentNetworkKey() {
+    return this.currentNetworkKey;
+  }
+  /**
+   * Set the active network
+   * @param networkKey - Network key to switch to (e.g., 'mainnet', 'testnet')
+   * @throws Error if the network key doesn't exist
+   */
+  setNetwork(networkKey) {
+    if (!this.networks[networkKey]) {
+      throw new Error(
+        `Network "${networkKey}" is not configured for ${this.chainData.name}. Available networks: ${Object.keys(this.networks).join(", ")}`
+      );
+    }
+    this.currentNetworkKey = networkKey;
+  }
+  /**
+   * Get all available network keys
+   * @returns Array of network keys (e.g., ['mainnet', 'testnet'])
+   */
+  getAvailableNetworks() {
+    return Object.keys(this.networks);
+  }
+  /**
+   * Check if a network is configured
+   * @param networkKey - Network key to check
+   * @returns True if the network exists
+   */
+  hasNetwork(networkKey) {
+    return networkKey in this.networks;
+  }
+  /**
+   * Derive EVM keys from a BIP39 mnemonic.
+   * Uses the BIP44 derivation path specified in the configuration.
+   *
+   * @param mnemonic - BIP39 mnemonic phrase
+   * @returns KeyData with derived keys and address
+   */
+  async deriveKeys(mnemonic) {
+    if (!ethers.ethers.Mnemonic.isValidMnemonic(mnemonic)) {
+      throw new Error("Invalid mnemonic phrase");
+    }
+    const path = this.getDerivationPath();
+    const hdNode = ethers.ethers.HDNodeWallet.fromPhrase(mnemonic, void 0, path);
+    const privateKeyHex = hdNode.privateKey;
+    const privateKeyBuffer = this.hexToBytes(privateKeyHex.slice(2));
+    const publicKeyHex = hdNode.publicKey;
+    const publicKeyBuffer = this.hexToBytes(publicKeyHex.slice(2));
+    const address = hdNode.address;
+    const seed = this.hexToBytes(ethers.ethers.id(mnemonic).slice(2));
+    return {
+      mnemonic,
+      seed,
+      privateKey: privateKeyBuffer,
+      privateKeyHex: privateKeyHex.slice(2),
+      // Without 0x prefix
+      publicKey: publicKeyBuffer,
+      publicKeyHex: publicKeyHex.slice(2),
+      // Without 0x prefix
+      address,
+      path
+    };
+  }
+  /**
+   * Derive keys at a specific address index
+   * @param mnemonic - BIP39 mnemonic phrase
+   * @param addressIndex - Address index in the BIP44 path
+   * @returns KeyData with derived keys
+   */
+  async deriveKeysAtIndex(mnemonic, addressIndex) {
+    if (!ethers.ethers.Mnemonic.isValidMnemonic(mnemonic)) {
+      throw new Error("Invalid mnemonic phrase");
+    }
+    const path = `m/44'/${this.coinType}'/${this.account}'/${this.change}/${addressIndex}`;
+    const hdNode = ethers.ethers.HDNodeWallet.fromPhrase(mnemonic, void 0, path);
+    const privateKeyHex = hdNode.privateKey;
+    const privateKeyBuffer = this.hexToBytes(privateKeyHex.slice(2));
+    const publicKeyHex = hdNode.publicKey;
+    const publicKeyBuffer = this.hexToBytes(publicKeyHex.slice(2));
+    const address = hdNode.address;
+    const seed = this.hexToBytes(ethers.ethers.id(mnemonic).slice(2));
+    return {
+      mnemonic,
+      seed,
+      privateKey: privateKeyBuffer,
+      privateKeyHex: privateKeyHex.slice(2),
+      // Without 0x prefix
+      publicKey: publicKeyBuffer,
+      publicKeyHex: publicKeyHex.slice(2),
+      // Without 0x prefix
+      address,
+      path
+    };
+  }
+  /**
+   * Derive keys at a custom derivation path
+   * @param mnemonic - BIP39 mnemonic phrase
+   * @param path - Full BIP44 derivation path
+   * @returns KeyData with derived keys
+   */
+  async deriveKeysAtPath(mnemonic, path) {
+    if (!ethers.ethers.Mnemonic.isValidMnemonic(mnemonic)) {
+      throw new Error("Invalid mnemonic phrase");
+    }
+    const hdNode = ethers.ethers.HDNodeWallet.fromPhrase(mnemonic, void 0, path);
+    const privateKeyHex = hdNode.privateKey;
+    const privateKeyBuffer = this.hexToBytes(privateKeyHex.slice(2));
+    const publicKeyHex = hdNode.publicKey;
+    const publicKeyBuffer = this.hexToBytes(publicKeyHex.slice(2));
+    const address = hdNode.address;
+    const seed = this.hexToBytes(ethers.ethers.id(mnemonic).slice(2));
+    return {
+      mnemonic,
+      seed,
+      privateKey: privateKeyBuffer,
+      privateKeyHex: privateKeyHex.slice(2),
+      // Without 0x prefix
+      publicKey: publicKeyBuffer,
+      publicKeyHex: publicKeyHex.slice(2),
+      // Without 0x prefix
+      address,
+      path
+    };
+  }
+  /**
+   * Get address at a specific index (read-only, no private key)
+   * @param mnemonic - BIP39 mnemonic phrase
+   * @param index - Address index
+   * @returns Address and public key information
+   */
+  async getAddressAtIndex(mnemonic, index) {
+    if (!ethers.ethers.Mnemonic.isValidMnemonic(mnemonic)) {
+      throw new Error("Invalid mnemonic phrase");
+    }
+    const path = `m/44'/${this.coinType}'/${this.account}'/${this.change}/${index}`;
+    const hdNode = ethers.ethers.HDNodeWallet.fromPhrase(mnemonic, void 0, path);
+    return {
+      address: hdNode.address,
+      publicKey: hdNode.publicKey.slice(2),
+      // Without 0x prefix
+      path
+    };
+  }
+  /**
+   * Get multiple addresses starting from an index
+   * @param mnemonic - BIP39 mnemonic phrase
+   * @param startIndex - Starting address index
+   * @param count - Number of addresses to generate
+   * @returns Array of addresses with metadata
+   */
+  async getAddresses(mnemonic, startIndex, count) {
+    if (!ethers.ethers.Mnemonic.isValidMnemonic(mnemonic)) {
+      throw new Error("Invalid mnemonic phrase");
+    }
+    const addresses = [];
+    for (let i = 0; i < count; i++) {
+      const index = startIndex + i;
+      const path = `m/44'/${this.coinType}'/${this.account}'/${this.change}/${index}`;
+      const hdNode = ethers.ethers.HDNodeWallet.fromPhrase(mnemonic, void 0, path);
+      addresses.push({
+        address: hdNode.address,
+        path,
+        index
+      });
+    }
+    return addresses;
+  }
+  /**
+   * Sign a message with a private key
+   * @param privateKey - Private key as Uint8Array
+   * @param message - Message to sign (string or Uint8Array)
+   * @returns Signature
+   */
+  async signMessage(privateKey, message) {
+    const privateKeyHex = "0x" + this.bytesToHex(privateKey);
+    const wallet = new ethers.ethers.Wallet(privateKeyHex);
+    const messageStr = typeof message === "string" ? message : new TextDecoder().decode(message);
+    const signature = await wallet.signMessage(messageStr);
+    return { signature };
+  }
+  /**
+   * Sign a transaction with a private key
+   * @param privateKey - Private key as Uint8Array
+   * @param transaction - Chain-specific transaction object
+   * @returns Signed transaction and signature
+   */
+  async signTransaction(privateKey, transaction) {
+    const privateKeyHex = "0x" + this.bytesToHex(privateKey);
+    const wallet = new ethers.ethers.Wallet(privateKeyHex);
+    const signedTransaction = await wallet.signTransaction(transaction);
+    const tx = ethers.ethers.Transaction.from(signedTransaction);
+    const signature = tx.signature ? ethers.ethers.Signature.from(tx.signature).serialized : "";
+    return {
+      signedTransaction,
+      signature
+    };
+  }
+  /**
+   * Verify a signature against a public key
+   * @param message - Original message
+   * @param signature - Signature to verify
+   * @param publicKey - Public key (hex string)
+   * @returns True if signature is valid
+   */
+  async verifySignature(message, signature, publicKey) {
+    try {
+      const messageStr = typeof message === "string" ? message : new TextDecoder().decode(message);
+      const recoveredAddress = ethers.ethers.verifyMessage(messageStr, signature);
+      const publicKeyWithPrefix = publicKey.startsWith("0x") ? publicKey : "0x" + publicKey;
+      const computedAddress = ethers.ethers.computeAddress(publicKeyWithPrefix);
+      return recoveredAddress.toLowerCase() === computedAddress.toLowerCase();
+    } catch (error) {
+      return false;
+    }
+  }
+  /**
+   * Set or update the data provider
+   * @param provider - The blockchain data provider to use
+   */
+  setDataProvider(provider) {
+    this.dataProvider = provider;
+  }
+  /**
+   * Get the current data provider
+   * @returns The current data provider, or undefined if not set
+   */
+  getDataProvider() {
+    return this.dataProvider;
+  }
+  /**
+   * Ensure a data provider is configured
+   * @throws Error if no data provider is set
+   */
+  ensureProvider() {
+    if (!this.dataProvider) {
+      throw new Error(
+        `No data provider configured for ${this.chainData.name}. Please provide a BlockchainDataProvider (e.g., AlchemyProvider) in the adapter configuration.`
+      );
+    }
+  }
+  /**
+   * Get native token balance for an address
+   * @param address - Wallet address
+   * @returns TokenBalance object with native token information
+   * @throws Error if no data provider is configured
+   */
+  async getNativeBalance(address) {
+    this.ensureProvider();
+    return this.dataProvider.getNativeBalance(address);
+  }
+  /**
+   * Get all ERC-20 token balances for an address
+   * @param address - Wallet address
+   * @returns Array of token balances with metadata
+   * @throws Error if no data provider is configured
+   */
+  async getTokenBalances(address) {
+    this.ensureProvider();
+    return this.dataProvider.getTokenBalances(address);
+  }
+  /**
+   * Get balance for a specific ERC-20 token
+   * @param address - Wallet address
+   * @param tokenAddress - Token contract address
+   * @returns Balance in smallest unit as string
+   * @throws Error if no data provider is configured
+   */
+  async getTokenBalance(address, tokenAddress) {
+    this.ensureProvider();
+    return this.dataProvider.getTokenBalance(address, tokenAddress);
+  }
+  /**
+   * Get all transactions for an address
+   * @param address - Wallet address
+   * @param options - Optional filtering and pagination options
+   * @returns Array of transactions
+   * @throws Error if no data provider is configured
+   */
+  async getTransactions(address, options) {
+    this.ensureProvider();
+    return this.dataProvider.getTransactions(address, options);
+  }
+  /**
+   * Get all ERC-20 token transfers for an address
+   * @param address - Wallet address
+   * @param options - Optional filtering and pagination options
+   * @returns Array of token transfers
+   * @throws Error if no data provider is configured
+   */
+  async getTokenTransfers(address, options) {
+    this.ensureProvider();
+    return this.dataProvider.getTokenTransfers(address, options);
+  }
+  /**
+   * Validate if an address is a valid ERC-20 token contract
+   * @param tokenAddress - Token contract address
+   * @returns True if valid ERC-20, false otherwise
+   */
+  async validateTokenContract(tokenAddress) {
+    try {
+      const network = this.getNetwork();
+      if (!network) {
+        throw new Error(`No network configured for ${this.chainData.name}`);
+      }
+      const provider = new ethers.ethers.JsonRpcProvider(network.rpcUrl);
+      const contract = new ethers.ethers.Contract(
+        tokenAddress,
+        ["function symbol() view returns (string)"],
+        provider
+      );
+      const symbol = await contract.symbol();
+      return typeof symbol === "string" && symbol.length > 0;
+    } catch (error) {
+      return false;
+    }
+  }
+  /**
+   * Send native tokens (ETH, S, etc.)
+   * @param params - Transaction parameters including private key
+   * @returns Transaction receipt
+   */
+  async sendNativeToken(params) {
+    try {
+      const network = this.getNetwork();
+      if (!network) {
+        throw new Error(`No network configured for ${this.chainData.name}`);
+      }
+      const privateKeyHex = "0x" + this.bytesToHex(params.privateKey);
+      const wallet = new ethers.ethers.Wallet(privateKeyHex);
+      const provider = new ethers.ethers.JsonRpcProvider(network.rpcUrl);
+      const connectedSigner = wallet.connect(provider);
+      const tx = await connectedSigner.sendTransaction({
+        to: params.to,
+        value: params.amount
+      });
+      return {
+        hash: tx.hash,
+        from: tx.from,
+        to: tx.to,
+        value: tx.value.toString(),
+        chainId: network.chainId,
+        status: "pending",
+        nonce: tx.nonce
+      };
+    } catch (error) {
+      throw new Error(
+        `Failed to send native token: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  /**
+   * Send ERC-20 tokens
+   * Private key must be obtained from AuthClient after password verification
+   * @param params - Transaction parameters including private key and token address
+   * @returns Transaction receipt
+   */
+  async sendToken(params) {
+    try {
+      const isValidToken = await this.validateTokenContract(
+        params.tokenAddress
+      );
+      if (!isValidToken) {
+        throw new Error(
+          `Invalid ERC-20 token contract: ${params.tokenAddress}`
+        );
+      }
+      const network = this.getNetwork();
+      if (!network) {
+        throw new Error(`No network configured for ${this.chainData.name}`);
+      }
+      const privateKeyHex = "0x" + this.bytesToHex(params.privateKey);
+      const wallet = new ethers.ethers.Wallet(privateKeyHex);
+      const provider = new ethers.ethers.JsonRpcProvider(network.rpcUrl);
+      const connectedSigner = wallet.connect(provider);
+      const tokenContract = new ethers.ethers.Contract(
+        params.tokenAddress,
+        [
+          "function transfer(address to, uint256 amount) returns (bool)",
+          "function decimals() view returns (uint8)",
+          "function symbol() view returns (string)"
+        ],
+        connectedSigner
+      );
+      const tx = await tokenContract.transfer(params.to, params.amount);
+      return {
+        hash: tx.hash,
+        from: tx.from,
+        to: params.tokenAddress,
+        // For token transfers, 'to' is the contract address
+        value: "0",
+        // Native value is 0 for token transfers
+        chainId: network.chainId,
+        status: "pending",
+        nonce: tx.nonce
+      };
+    } catch (error) {
+      throw new Error(
+        `Failed to send token: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  /**
+   * Wait for transaction confirmation and return detailed status
+   * @param hash - Transaction hash
+   * @returns Transaction status update
+   */
+  async getTransactionStatus(hash) {
+    try {
+      const network = this.getNetwork();
+      if (!network) {
+        throw new Error(`No network configured for ${this.chainData.name}`);
+      }
+      const provider = new ethers.ethers.JsonRpcProvider(network.rpcUrl);
+      const receipt = await provider.getTransactionReceipt(hash);
+      if (!receipt) {
+        return {
+          hash,
+          status: "pending"
+        };
+      }
+      const currentBlock = await provider.getBlockNumber();
+      const confirmations = currentBlock - receipt.blockNumber + 1;
+      return {
+        hash,
+        status: receipt.status === 1 ? "confirmed" : "failed",
+        blockNumber: receipt.blockNumber,
+        confirmations,
+        gasUsed: receipt.gasUsed.toString(),
+        error: receipt.status === 0 ? "Transaction failed" : void 0
+      };
+    } catch (error) {
+      throw new Error(
+        `Failed to get transaction status: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  // Helper methods for byte/hex conversion
+  bytesToHex(bytes) {
+    return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  hexToBytes(hex) {
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+      bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+  }
+};
+
+// src/utils/formatBalance.ts
+var formatBalance = (balance, decimals) => {
+  const divisor = Math.pow(10, decimals);
+  const balanceNum = parseFloat(balance) / divisor;
+  return balanceNum.toLocaleString("en-US", {
+    minimumFractionDigits: 0,
+    maximumFractionDigits: decimals,
+    useGrouping: false
+  });
+};
+
+// src/providers/AlchemyProvider.ts
+var AlchemyProvider = class {
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.network = config.network;
+    this.provider = new ethers.ethers.JsonRpcProvider(config.rpcUrl);
+    this.nativeTokenSymbol = config.nativeTokenSymbol;
+    this.nativeTokenName = config.nativeTokenName;
+    this.nativeTokenDecimals = config.nativeTokenDecimals ?? 18;
+    this.cmc_id = config.cmc_id;
+    console.log(`\u2705 AlchemyProvider initialized for ${config.network}`);
+  }
+  /**
+   * Get native token balance (e.g., ETH, S) for an address using RPC
+   */
+  async getNativeBalance(address) {
+    try {
+      const balance = await this.provider.getBalance(address);
+      const balanceStr = balance.toString();
+      return {
+        contractAddress: "native",
+        // Native token doesn't have a contract address
+        balance: balanceStr,
+        balanceFormatted: formatBalance(balanceStr, this.nativeTokenDecimals),
+        symbol: this.nativeTokenSymbol,
+        name: this.nativeTokenName,
+        decimals: this.nativeTokenDecimals,
+        logo: `https://s2.coinmarketcap.com/static/img/coins/128x128/${this.cmc_id}.png`,
+        isNFT: false
+      };
+    } catch (error) {
+      throw new Error(
+        `Failed to fetch native balance: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  /**
+   * Get all ERC-20 token balances for an address using Alchemy Portfolio API
+   */
+  async getTokenBalances(address) {
+    try {
+      const url = `https://api.g.alchemy.com/data/v1/${this.apiKey}/assets/tokens/by-address`;
+      const response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          addresses: [
+            {
+              address,
+              networks: [this.network]
+            }
+          ],
+          withMetadata: true,
+          includeNativeTokens: false,
+          // We get native balance separately
+          includeErc20Tokens: true
+        })
+      });
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(
+          `Portfolio API request failed: ${response.status} ${errorText}`
+        );
+      }
+      const data = await response.json();
+      const tokens = data.data?.tokens || [];
+      const tokenBalances = [];
+      for (const token of tokens) {
+        if (token.error) {
+          console.warn(
+            `Error fetching token ${token.tokenAddress}:`,
+            token.error
+          );
+          continue;
+        }
+        let balance = token.tokenBalance || "0";
+        if (balance.startsWith("0x")) {
+          balance = BigInt(balance).toString();
+        }
+        if (balance === "0") {
+          continue;
+        }
+        const decimals = token.tokenMetadata?.decimals ?? 18;
+        tokenBalances.push({
+          contractAddress: token.tokenAddress,
+          balance,
+          balanceFormatted: formatBalance(balance, decimals),
+          symbol: token.tokenMetadata?.symbol || "UNKNOWN",
+          name: token.tokenMetadata?.name || "Unknown Token",
+          decimals,
+          logo: token.tokenMetadata?.logo,
+          // This endpoint returns ERC-20 tokens only, not NFTs
+          isNFT: false
+        });
+      }
+      return tokenBalances;
+    } catch (error) {
+      throw new Error(
+        `Failed to fetch token balances: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  /**
+   * Get balance for a specific ERC-20 token using RPC
+   */
+  async getTokenBalance(address, tokenAddress) {
+    try {
+      const contract = new ethers.ethers.Contract(
+        tokenAddress,
+        ["function balanceOf(address) view returns (uint256)"],
+        this.provider
+      );
+      const balance = await contract.balanceOf(address);
+      return balance.toString();
+    } catch (error) {
+      throw new Error(
+        `Failed to fetch token balance: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  /**
+   * Get all transactions for an address using Alchemy's getAssetTransfers API
+   */
+  async getTransactions(address, options = {}) {
+    try {
+      const transactions = [];
+      const sentTransfers = await this.fetchAssetTransfers({
+        fromAddress: address,
+        category: ["external", "internal"],
+        order: options.sort === "asc" ? "asc" : "desc",
+        maxCount: options.offset ? `0x${options.offset.toString(16)}` : "0x64",
+        // Default 100
+        withMetadata: true
+      });
+      const receivedTransfers = await this.fetchAssetTransfers({
+        toAddress: address,
+        category: ["external", "internal"],
+        order: options.sort === "asc" ? "asc" : "desc",
+        maxCount: options.offset ? `0x${options.offset.toString(16)}` : "0x64",
+        withMetadata: true
+      });
+      const allTransfers = [
+        ...sentTransfers.transfers,
+        ...receivedTransfers.transfers
+      ];
+      const uniqueHashes = /* @__PURE__ */ new Set();
+      for (const transfer of allTransfers) {
+        if (uniqueHashes.has(transfer.hash)) continue;
+        uniqueHashes.add(transfer.hash);
+        transactions.push({
+          hash: transfer.hash,
+          from: transfer.from,
+          to: transfer.to || "",
+          value: transfer.value ? transfer.value.toString() : "0",
+          timestamp: transfer.metadata?.blockTimestamp ? new Date(transfer.metadata.blockTimestamp).getTime() / 1e3 : 0,
+          blockNumber: parseInt(transfer.blockNum, 16),
+          gasUsed: "0",
+          // Not provided by getAssetTransfers
+          gasPrice: "0",
+          // Not provided by getAssetTransfers
+          status: "success",
+          // Transfers API only returns successful transactions
+          isError: false
+        });
+      }
+      transactions.sort(
+        (a, b) => options.sort === "asc" ? a.blockNumber - b.blockNumber : b.blockNumber - a.blockNumber
+      );
+      return transactions;
+    } catch (error) {
+      throw new Error(
+        `Failed to fetch transactions: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  /**
+   * Get all ERC-20 token transfers for an address using Alchemy's getAssetTransfers API
+   */
+  async getTokenTransfers(address, options = {}) {
+    try {
+      const tokenTransfers = [];
+      const sentTransfers = await this.fetchAssetTransfers({
+        fromAddress: address,
+        category: ["erc20"],
+        order: options.sort === "asc" ? "asc" : "desc",
+        maxCount: options.offset ? `0x${options.offset.toString(16)}` : "0x64",
+        withMetadata: true
+      });
+      const receivedTransfers = await this.fetchAssetTransfers({
+        toAddress: address,
+        category: ["erc20"],
+        order: options.sort === "asc" ? "asc" : "desc",
+        maxCount: options.offset ? `0x${options.offset.toString(16)}` : "0x64",
+        withMetadata: true
+      });
+      const allTransfers = [
+        ...sentTransfers.transfers,
+        ...receivedTransfers.transfers
+      ];
+      const uniqueIds = /* @__PURE__ */ new Set();
+      for (const transfer of allTransfers) {
+        if (uniqueIds.has(transfer.uniqueId)) continue;
+        uniqueIds.add(transfer.uniqueId);
+        tokenTransfers.push({
+          hash: transfer.hash,
+          from: transfer.from,
+          to: transfer.to || "",
+          value: transfer.value ? transfer.value.toString() : "0",
+          timestamp: transfer.metadata?.blockTimestamp ? new Date(transfer.metadata.blockTimestamp).getTime() / 1e3 : 0,
+          blockNumber: parseInt(transfer.blockNum, 16),
+          tokenAddress: transfer.rawContract?.address || "",
+          tokenSymbol: transfer.asset || "UNKNOWN",
+          tokenName: transfer.asset || "Unknown Token",
+          tokenDecimal: transfer.rawContract?.decimal || "18"
+        });
+      }
+      tokenTransfers.sort(
+        (a, b) => options.sort === "asc" ? a.blockNumber - b.blockNumber : b.blockNumber - a.blockNumber
+      );
+      return tokenTransfers;
+    } catch (error) {
+      throw new Error(
+        `Failed to fetch token transfers: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  /**
+   * Helper method to fetch asset transfers from Alchemy API
+   */
+  async fetchAssetTransfers(params) {
+    const response = await fetch(this.provider._getConnection().url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "alchemy_getAssetTransfers",
+        params: [
+          {
+            fromBlock: "0x0",
+            toBlock: "latest",
+            ...params,
+            excludeZeroValue: true
+          }
+        ]
+      })
+    });
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(
+        `getAssetTransfers request failed: ${response.status} ${errorText}`
+      );
+    }
+    const data = await response.json();
+    if (data.error) {
+      throw new Error(`Alchemy API error: ${data.error.message}`);
+    }
+    return data.result || { transfers: [] };
+  }
+};
+
+// src/providers/EtherscanProvider.ts
+var EtherscanProvider = class {
+  /**
+   * Create an Etherscan provider using API V2
+   * @param config - Provider configuration
+   */
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.chainId = config.chainId;
+    this.nativeTokenSymbol = config.nativeTokenSymbol;
+    this.nativeTokenName = config.nativeTokenName;
+    this.nativeTokenDecimals = config.nativeTokenDecimals ?? 18;
+    this.cmc_id = config.cmc_id;
+    this.baseUrl = config.baseUrl ?? "https://api.etherscan.io/v2/api";
+  }
+  /**
+   * Get native token balance for an address
+   * @param address - Wallet address
+   * @returns TokenBalance object with native token information
+   */
+  async getNativeBalance(address) {
+    const params = new URLSearchParams({
+      chainid: this.chainId.toString(),
+      module: "account",
+      action: "balance",
+      address,
+      tag: "latest",
+      apikey: this.apiKey
+    });
+    const url = `${this.baseUrl}?${params.toString()}`;
+    const response = await this.fetchWithRetry(url);
+    const data = await response.json();
+    if (data.status !== "1") {
+      throw new Error(
+        `Etherscan API error: ${data.message} (result: ${data.result})`
+      );
+    }
+    return {
+      contractAddress: "native",
+      // Native token doesn't have a contract address
+      balance: data.result,
+      balanceFormatted: formatBalance(data.result, this.nativeTokenDecimals),
+      symbol: this.nativeTokenSymbol,
+      name: this.nativeTokenName,
+      decimals: this.nativeTokenDecimals,
+      logo: `https://s2.coinmarketcap.com/static/img/coins/128x128/${this.cmc_id}.png`,
+      isNFT: false
+    };
+  }
+  /**
+   * Get all ERC-20 token balances for an address
+   * @param address - Wallet address
+   * @returns Array of token balances with metadata
+   *
+   * Note: This endpoint prefers the Etherscan API Pro endpoint for better performance,
+   * but automatically falls back to a free-tier compatible approach if needed.
+   */
+  async getTokenBalances(address) {
+    const params = new URLSearchParams({
+      chainid: this.chainId.toString(),
+      module: "account",
+      action: "addresstokenbalance",
+      address,
+      page: "1",
+      offset: "100",
+      apikey: this.apiKey
+    });
+    const url = `${this.baseUrl}?${params.toString()}`;
+    const response = await this.fetchWithRetry(url);
+    const data = await response.json();
+    if (data.status !== "1") {
+      if (data.result && typeof data.result === "string" && data.result.includes("API Pro")) {
+        return this.getTokenBalancesFallback(address);
+      }
+      if (data.result && typeof data.result === "string" && data.result.includes("rate limit")) {
+        console.warn("Rate limit hit, using fallback method with delays...");
+        await this.delay(1e3);
+        return this.getTokenBalancesFallback(address);
+      }
+      throw new Error(
+        `Etherscan API error: ${data.message} (result: ${data.result})`
+      );
+    }
+    if (!Array.isArray(data.result)) {
+      throw new Error("Unexpected API response format");
+    }
+    return data.result.map((token) => {
+      const decimals = parseInt(token.TokenDivisor, 10);
+      return {
+        contractAddress: token.TokenAddress,
+        balance: token.TokenQuantity,
+        balanceFormatted: formatBalance(token.TokenQuantity, decimals),
+        symbol: token.TokenSymbol,
+        name: token.TokenName,
+        decimals,
+        // This endpoint returns ERC-20 tokens only, not NFTs
+        isNFT: false
+      };
+    });
+  }
+  /**
+   * Free-tier fallback for getTokenBalances
+   * Discovers tokens via transfer history and fetches individual balances
+   * Rate-limited to respect Etherscan free tier limits (3 calls/sec)
+   * @param address - Wallet address
+   * @returns Array of token balances with metadata
+   */
+  async getTokenBalancesFallback(address) {
+    const transfers = await this.getTokenTransfers(address, {
+      page: 1,
+      offset: 1e4
+      // Get more transfers to discover more tokens
+    });
+    if (transfers.length === 0) {
+      return [];
+    }
+    const uniqueTokens = /* @__PURE__ */ new Map();
+    for (const transfer of transfers) {
+      if (!uniqueTokens.has(transfer.tokenAddress)) {
+        uniqueTokens.set(transfer.tokenAddress, {
+          symbol: transfer.tokenSymbol,
+          name: transfer.tokenName,
+          decimals: parseInt(transfer.tokenDecimal, 10)
+        });
+      }
+    }
+    await this.delay(1e3);
+    const balances = [];
+    const batchSize = 2;
+    const delayMs = 1e3;
+    const tokenEntries = Array.from(uniqueTokens.entries());
+    for (let i = 0; i < tokenEntries.length; i++) {
+      const [contractAddress, metadata] = tokenEntries[i];
+      try {
+        const balance = await this.getTokenBalance(address, contractAddress);
+        if (balance !== "0") {
+          balances.push({
+            contractAddress,
+            balance,
+            balanceFormatted: formatBalance(balance, metadata.decimals),
+            symbol: metadata.symbol,
+            name: metadata.name,
+            decimals: metadata.decimals,
+            // This endpoint returns ERC-20 tokens only, not NFTs
+            isNFT: false
+          });
+        }
+      } catch (error) {
+        console.warn(
+          `Failed to fetch balance for token ${contractAddress}:`,
+          error
+        );
+      }
+      if ((i + 1) % batchSize === 0 && i + 1 < tokenEntries.length) {
+        await this.delay(delayMs);
+      }
+    }
+    return balances;
+  }
+  /**
+   * Helper method to add delay (for rate limiting)
+   * @param ms - Milliseconds to delay
+   */
+  delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  /**
+   * Wrapper for fetch with automatic retry on rate limit
+   * @param url - URL to fetch
+   * @param maxRetries - Maximum number of retries (default: 2)
+   * @returns Response
+   */
+  async fetchWithRetry(url, maxRetries = 2) {
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      const response = await fetch(url);
+      if (!response.ok) {
+        if (response.status === 429) {
+          if (attempt < maxRetries) {
+            const delayMs = 1e3 * (attempt + 1);
+            console.warn(
+              `Rate limit hit (429), retrying in ${delayMs}ms... (attempt ${attempt + 1}/${maxRetries})`
+            );
+            await this.delay(delayMs);
+            continue;
+          }
+        }
+        throw new Error(
+          `HTTP error! status: ${response.status} ${response.statusText}`
+        );
+      }
+      return response;
+    }
+    throw new Error("Max retries exceeded");
+  }
+  /**
+   * Get balance for a specific ERC-20 token
+   * @param address - Wallet address
+   * @param tokenAddress - Token contract address
+   * @returns Balance in smallest unit as string
+   */
+  async getTokenBalance(address, tokenAddress) {
+    const params = new URLSearchParams({
+      chainid: this.chainId.toString(),
+      module: "account",
+      action: "tokenbalance",
+      contractaddress: tokenAddress,
+      address,
+      tag: "latest",
+      apikey: this.apiKey
+    });
+    const url = `${this.baseUrl}?${params.toString()}`;
+    const response = await this.fetchWithRetry(url);
+    const data = await response.json();
+    if (data.status !== "1") {
+      throw new Error(
+        `Etherscan API error: ${data.message} (result: ${data.result})`
+      );
+    }
+    return data.result;
+  }
+  /**
+   * Get all transactions for an address
+   * @param address - Wallet address
+   * @param options - Optional filtering and pagination options
+   * @returns Array of transactions
+   */
+  async getTransactions(address, options) {
+    const params = new URLSearchParams({
+      chainid: this.chainId.toString(),
+      module: "account",
+      action: "txlist",
+      address,
+      startblock: (options?.startBlock ?? 0).toString(),
+      endblock: (options?.endBlock ?? 99999999).toString(),
+      page: (options?.page ?? 1).toString(),
+      offset: (options?.offset ?? 100).toString(),
+      sort: options?.sort ?? "desc",
+      apikey: this.apiKey
+    });
+    const url = `${this.baseUrl}?${params.toString()}`;
+    const response = await this.fetchWithRetry(url);
+    const data = await response.json();
+    if (data.status !== "1") {
+      if (data.message === "No transactions found") {
+        return [];
+      }
+      throw new Error(
+        `Etherscan API error: ${data.message} (result: ${data.result})`
+      );
+    }
+    return data.result.map((tx) => ({
+      hash: tx.hash,
+      from: tx.from,
+      to: tx.to,
+      value: tx.value,
+      timestamp: parseInt(tx.timeStamp, 10),
+      blockNumber: parseInt(tx.blockNumber, 10),
+      gasUsed: tx.gasUsed,
+      gasPrice: tx.gasPrice,
+      status: tx.txreceipt_status === "1" ? "success" : tx.txreceipt_status === "0" ? "failed" : "pending",
+      isError: tx.isError === "1"
+    }));
+  }
+  /**
+   * Get all ERC-20 token transfers for an address
+   * @param address - Wallet address
+   * @param options - Optional filtering and pagination options
+   * @returns Array of token transfers
+   */
+  async getTokenTransfers(address, options) {
+    const params = new URLSearchParams({
+      chainid: this.chainId.toString(),
+      module: "account",
+      action: "tokentx",
+      address,
+      startblock: (options?.startBlock ?? 0).toString(),
+      endblock: (options?.endBlock ?? 99999999).toString(),
+      page: (options?.page ?? 1).toString(),
+      offset: (options?.offset ?? 100).toString(),
+      sort: options?.sort ?? "desc",
+      apikey: this.apiKey
+    });
+    const url = `${this.baseUrl}?${params.toString()}`;
+    const response = await this.fetchWithRetry(url);
+    const data = await response.json();
+    if (data.status !== "1") {
+      if (data.message === "No transactions found") {
+        return [];
+      }
+      throw new Error(
+        `Etherscan API error: ${data.message} (result: ${data.result})`
+      );
+    }
+    return data.result.map((tx) => ({
+      hash: tx.hash,
+      from: tx.from,
+      to: tx.to,
+      value: tx.value,
+      timestamp: parseInt(tx.timeStamp, 10),
+      blockNumber: parseInt(tx.blockNumber, 10),
+      tokenAddress: tx.contractAddress,
+      tokenSymbol: tx.tokenSymbol,
+      tokenName: tx.tokenName,
+      tokenDecimal: tx.tokenDecimal
+    }));
+  }
+};
+
+// src/chains/ethereum.ts
+var EthereumAdapter = new EVMAdapter({
+  chainData: {
+    name: "Ethereum",
+    symbol: "ETH",
+    tokenStandard: "ERC20",
+    chainId: 60,
+    cmc_id: 1027,
+    // CoinMarketCap ID for Ethereum
+    decimals: 18
+  },
+  coinType: 60,
+  // Standard Ethereum BIP44 coin type
+  standardDecimals: 18,
+  networks: {
+    mainnet: {
+      name: "Ethereum Mainnet",
+      rpcUrl: "https://mainnet.infura.io/v3/YOUR_INFURA_API_KEY",
+      // Replace with your API key
+      explorerUrl: "https://etherscan.io",
+      chainId: 1
+    },
+    testnet: {
+      name: "Ethereum Testnet (Sepolia)",
+      rpcUrl: "https://sepolia.infura.io/v3/YOUR_INFURA_API_KEY",
+      // Replace with your API key
+      explorerUrl: "https://sepolia.etherscan.io",
+      chainId: 11155111
+    }
+  },
+  defaultNetwork: "mainnet"
+});
+
+// src/chains/sonic.ts
+var SonicAdapter = new EVMAdapter({
+  chainData: {
+    name: "Sonic",
+    symbol: "S",
+    tokenStandard: "ERC20",
+    chainId: 60,
+    cmc_id: 32684,
+    // CoinMarketCap ID for Sonic
+    decimals: 18
+  },
+  coinType: 60,
+  // Uses standard Ethereum coin type (EVM-compatible)
+  standardDecimals: 18,
+  networks: {
+    mainnet: {
+      name: "Sonic Mainnet",
+      rpcUrl: "https://rpc.sonic.soniclabs.com",
+      explorerUrl: "https://sonicscan.org",
+      chainId: 146
+    },
+    testnet: {
+      name: "Sonic Testnet",
+      rpcUrl: "https://rpc.blaze.soniclabs.com",
+      explorerUrl: "https://testnet.sonicscan.org",
+      chainId: 57054
+    }
+  },
+  defaultNetwork: "mainnet"
+});
+
+exports.AlchemyProvider = AlchemyProvider;
+exports.EVMAdapter = EVMAdapter;
+exports.EthereumAdapter = EthereumAdapter;
+exports.EtherscanProvider = EtherscanProvider;
+exports.SonicAdapter = SonicAdapter;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map