multi-chain-balance-diff 0.1.0

package/src/adapters/baseAdapter.js

@@ -0,0 +1,121 @@
+/**
+ * Base Chain Adapter Interface
+ * 
+ * Defines the contract that all chain adapters must implement.
+ * This enables the balance service to work with any blockchain
+ * without knowing the underlying implementation details.
+ * 
+ * Supported chain types:
+ * - EVM (Ethereum, Polygon, Arbitrum, etc.) via ethers.js
+ * - Solana (including Helium tokens) via @solana/web3.js
+ * 
+ * Future: Cosmos, Bitcoin, etc.
+ */
+
+class BaseAdapter {
+  constructor(networkConfig) {
+    if (new.target === BaseAdapter) {
+      throw new Error('BaseAdapter is abstract and cannot be instantiated directly');
+    }
+    this.networkConfig = networkConfig;
+    this.connection = null;
+  }
+
+  /**
+   * Get the chain type identifier.
+   * @returns {string} Chain type ('evm', 'solana', etc.)
+   */
+  getChainType() {
+    throw new Error('getChainType() must be implemented');
+  }
+
+  /**
+   * Connect to the network RPC.
+   * @returns {Promise<void>}
+   */
+  async connect() {
+    throw new Error('connect() must be implemented');
+  }
+
+  /**
+   * Get current block/slot number.
+   * @returns {Promise<number>}
+   */
+  async getCurrentBlock() {
+    throw new Error('getCurrentBlock() must be implemented');
+  }
+
+  /**
+   * Get native balance for an address.
+   * @param {string} address - Wallet address
+   * @param {number|string} blockTag - Block number or 'latest'
+   * @returns {Promise<{raw: bigint, formatted: string, decimals: number}>}
+   */
+  async getNativeBalance(address, blockTag = 'latest') {
+    throw new Error('getNativeBalance() must be implemented');
+  }
+
+  /**
+   * Get native balance diff over N blocks/slots.
+   * @param {string} address - Wallet address
+   * @param {number} blocksBack - Number of blocks to look back
+   * @returns {Promise<{current: object, previous: object, diff: bigint, currentBlock: number, previousBlock: number}>}
+   */
+  async getNativeBalanceDiff(address, blocksBack) {
+    const currentBlock = await this.getCurrentBlock();
+    const previousBlock = Math.max(0, currentBlock - blocksBack);
+
+    const [current, previous] = await Promise.all([
+      this.getNativeBalance(address, currentBlock),
+      this.getNativeBalance(address, previousBlock),
+    ]);
+
+    return {
+      current,
+      previous,
+      diff: current.raw - previous.raw,
+      currentBlock,
+      previousBlock,
+    };
+  }
+
+  /**
+   * Get token balances for an address.
+   * @param {string} address - Wallet address
+   * @param {object[]} tokens - Token configurations
+   * @returns {Promise<object[]>} Array of token balances
+   */
+  async getTokenBalances(address, tokens) {
+    throw new Error('getTokenBalances() must be implemented');
+  }
+
+  /**
+   * Validate an address format.
+   * @param {string} address - Address to validate
+   * @returns {boolean} True if valid
+   */
+  isValidAddress(address) {
+    throw new Error('isValidAddress() must be implemented');
+  }
+
+  /**
+   * Format a raw balance to human-readable string.
+   * @param {bigint} raw - Raw balance
+   * @param {number} decimals - Token decimals
+   * @returns {string} Formatted balance
+   */
+  formatBalance(raw, decimals) {
+    throw new Error('formatBalance() must be implemented');
+  }
+
+  /**
+   * Get explorer URL for an address.
+   * @param {string} address - Wallet address
+   * @returns {string} Block explorer URL
+   */
+  getExplorerUrl(address) {
+    return `${this.networkConfig.blockExplorer}/address/${address}`;
+  }
+}
+
+module.exports = BaseAdapter;

package/src/adapters/evmAdapter.js

@@ -0,0 +1,126 @@
+/**
+ * EVM Chain Adapter
+ * 
+ * Handles all EVM-compatible chains (Ethereum, Polygon, Arbitrum, etc.)
+ * using ethers.js. The EVM standard ensures consistent behavior across
+ * all compatible networks.
+ */
+
+const { ethers } = require('ethers');
+const BaseAdapter = require('./baseAdapter');
+
+// Minimal ERC-20 ABI for balance queries
+const ERC20_ABI = [
+  'function balanceOf(address owner) view returns (uint256)',
+  'function decimals() view returns (uint8)',
+  'function symbol() view returns (string)',
+];
+
+class EVMAdapter extends BaseAdapter {
+  constructor(networkConfig) {
+    super(networkConfig);
+    this.provider = null;
+  }
+
+  getChainType() {
+    return 'evm';
+  }
+
+  async connect() {
+    this.provider = new ethers.JsonRpcProvider(this.networkConfig.rpcUrl);
+    // Verify connection by fetching network
+    await this.provider.getNetwork();
+    this.connection = this.provider;
+  }
+
+  async getCurrentBlock() {
+    return this.provider.getBlockNumber();
+  }
+
+  async getNativeBalance(address, blockTag = 'latest') {
+    const raw = await this.provider.getBalance(address, blockTag);
+    return {
+      raw,
+      formatted: this.formatBalance(raw, 18),
+      decimals: 18,
+    };
+  }
+
+  async getTokenBalances(address, tokens) {
+    const results = await Promise.all(
+      tokens.map(token => this._getTokenBalance(address, token))
+    );
+    
+    // Filter out failed fetches and zero balances
+    return results.filter(result => 
+      result !== null && result.raw > 0n
+    );
+  }
+
+  async _getTokenBalance(address, tokenConfig) {
+    try {
+      const contract = new ethers.Contract(
+        tokenConfig.address,
+        ERC20_ABI,
+        this.provider
+      );
+      
+      const raw = await contract.balanceOf(address);
+      
+      return {
+        symbol: tokenConfig.symbol,
+        address: tokenConfig.address,
+        raw,
+        formatted: this.formatBalance(raw, tokenConfig.decimals),
+        decimals: tokenConfig.decimals,
+      };
+    } catch (error) {
+      // Token contract might not exist or be inaccessible
+      return null;
+    }
+  }
+
+  isValidAddress(address) {
+    try {
+      ethers.getAddress(address);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  formatBalance(raw, decimals = 18) {
+    const formatted = ethers.formatUnits(raw, decimals);
+    // Trim trailing zeros but keep reasonable precision
+    return parseFloat(formatted).toString();
+  }
+
+  /**
+   * Format balance with symbol for display.
+   * @param {bigint} raw - Raw balance in wei
+   * @param {string} symbol - Currency symbol
+   * @param {number} decimals - Decimals
+   * @returns {string} e.g., "1.234 ETH"
+   */
+  formatBalanceWithSymbol(raw, symbol, decimals = 18) {
+    const value = parseFloat(ethers.formatUnits(raw, decimals));
+    const display = value.toFixed(6).replace(/\.?0+$/, '');
+    return `${display} ${symbol}`;
+  }
+
+  /**
+   * Format balance diff with +/- prefix.
+   * @param {bigint} diff - Diff in wei
+   * @param {string} symbol - Currency symbol
+   * @param {number} decimals - Decimals
+   * @returns {string} e.g., "+0.01 ETH"
+   */
+  formatDiff(diff, symbol, decimals = 18) {
+    const value = parseFloat(ethers.formatUnits(diff, decimals));
+    const prefix = value >= 0 ? '+' : '';
+    const display = value.toFixed(6).replace(/\.?0+$/, '');
+    return `${prefix}${display} ${symbol}`;
+  }
+}
+
+module.exports = EVMAdapter;

package/src/adapters/index.js

@@ -0,0 +1,70 @@
+/**
+ * Chain Adapter Factory
+ * 
+ * Returns the appropriate adapter based on network configuration.
+ * This is the main entry point for multi-chain support.
+ * 
+ * Usage:
+ *   const adapter = createAdapter(networkConfig);
+ *   await adapter.connect();
+ *   const balance = await adapter.getNativeBalance(address);
+ */
+
+const EVMAdapter = require('./evmAdapter');
+const SolanaAdapter = require('./solanaAdapter');
+
+/**
+ * Chain type to adapter class mapping.
+ */
+const ADAPTER_MAP = {
+  evm: EVMAdapter,
+  solana: SolanaAdapter,
+};
+
+/**
+ * Create an adapter for the given network configuration.
+ * 
+ * @param {object} networkConfig - Network configuration from networks.js
+ * @returns {BaseAdapter} Chain-specific adapter instance
+ * @throws {Error} If chain type is not supported
+ */
+function createAdapter(networkConfig) {
+  // Determine chain type (default to 'evm' for backwards compatibility)
+  const chainType = networkConfig.chainType || 'evm';
+  
+  const AdapterClass = ADAPTER_MAP[chainType];
+  
+  if (!AdapterClass) {
+    throw new Error(
+      `Unsupported chain type: ${chainType}. ` +
+      `Supported types: ${Object.keys(ADAPTER_MAP).join(', ')}`
+    );
+  }
+  
+  return new AdapterClass(networkConfig);
+}
+
+/**
+ * Get list of supported chain types.
+ * @returns {string[]}
+ */
+function getSupportedChainTypes() {
+  return Object.keys(ADAPTER_MAP);
+}
+
+/**
+ * Check if a chain type is supported.
+ * @param {string} chainType 
+ * @returns {boolean}
+ */
+function isChainTypeSupported(chainType) {
+  return chainType in ADAPTER_MAP;
+}
+
+module.exports = {
+  createAdapter,
+  getSupportedChainTypes,
+  isChainTypeSupported,
+  EVMAdapter,
+  SolanaAdapter,
+};

package/src/adapters/solanaAdapter.js

@@ -0,0 +1,179 @@
+/**
+ * Solana Chain Adapter
+ * 
+ * Handles Solana blockchain and SPL tokens, including:
+ * - Native SOL balance
+ * - SPL token balances (HNT, MOBILE, IOT for Helium ecosystem)
+ * 
+ * Uses @solana/web3.js for RPC communication.
+ */
+
+const { 
+  Connection, 
+  PublicKey, 
+  LAMPORTS_PER_SOL,
+} = require('@solana/web3.js');
+const BaseAdapter = require('./baseAdapter');
+
+// SPL Token Program ID
+const TOKEN_PROGRAM_ID = new PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA');
+
+class SolanaAdapter extends BaseAdapter {
+  constructor(networkConfig) {
+    super(networkConfig);
+    this.conn = null;
+  }
+
+  getChainType() {
+    return 'solana';
+  }
+
+  async connect() {
+    this.conn = new Connection(
+      this.networkConfig.rpcUrl,
+      { commitment: 'confirmed' }
+    );
+    // Verify connection
+    await this.conn.getSlot();
+    this.connection = this.conn;
+  }
+
+  async getCurrentBlock() {
+    // Solana uses "slots" instead of blocks
+    return this.conn.getSlot();
+  }
+
+  async getNativeBalance(address, slotTag = 'latest') {
+    const pubkey = new PublicKey(address);
+    
+    let raw;
+    if (slotTag === 'latest') {
+      raw = await this.conn.getBalance(pubkey);
+    } else {
+      // Historical balance query with specific slot
+      // Note: Many RPC nodes don't support historical queries
+      // We use getBalanceAndContext for better reliability
+      try {
+        const result = await this.conn.getBalance(pubkey, {
+          minContextSlot: slotTag,
+        });
+        raw = result;
+      } catch (error) {
+        // Fallback to current if historical not supported
+        raw = await this.conn.getBalance(pubkey);
+      }
+    }
+
+    return {
+      raw: BigInt(raw),
+      formatted: this.formatBalance(BigInt(raw), 9), // SOL has 9 decimals
+      decimals: 9,
+    };
+  }
+
+  async getTokenBalances(address, tokens) {
+    const pubkey = new PublicKey(address);
+    
+    try {
+      // Fetch all token accounts for this wallet
+      const tokenAccounts = await this.conn.getParsedTokenAccountsByOwner(
+        pubkey,
+        { programId: TOKEN_PROGRAM_ID }
+      );
+
+      // Build lookup map from mint address to our token config
+      const tokenLookup = new Map();
+      for (const token of tokens) {
+        // Solana tokens use 'mint' instead of 'address'
+        const mintAddress = token.mint || token.address;
+        if (mintAddress) {
+          tokenLookup.set(mintAddress, token);
+        }
+      }
+
+      // Process token accounts
+      const results = [];
+      for (const { account } of tokenAccounts.value) {
+        const parsed = account.data.parsed?.info;
+        if (!parsed) continue;
+
+        const mint = parsed.mint;
+        const tokenConfig = tokenLookup.get(mint);
+        
+        if (tokenConfig) {
+          const amount = parsed.tokenAmount;
+          const raw = BigInt(amount.amount);
+          
+          if (raw > 0n) {
+            results.push({
+              symbol: tokenConfig.symbol,
+              mint: mint,
+              raw,
+              formatted: amount.uiAmountString || this.formatBalance(raw, amount.decimals),
+              decimals: amount.decimals,
+            });
+          }
+        }
+      }
+
+      return results;
+    } catch (error) {
+      console.warn(`Warning: Could not fetch SPL tokens: ${error.message}`);
+      return [];
+    }
+  }
+
+  isValidAddress(address) {
+    try {
+      new PublicKey(address);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  formatBalance(raw, decimals = 9) {
+    const divisor = BigInt(10 ** decimals);
+    const whole = raw / divisor;
+    const fraction = raw % divisor;
+    
+    if (fraction === 0n) {
+      return whole.toString();
+    }
+    
+    // Format fraction with proper padding
+    const fractionStr = fraction.toString().padStart(decimals, '0');
+    // Trim trailing zeros
+    const trimmed = fractionStr.replace(/0+$/, '');
+    
+    return `${whole}.${trimmed}`;
+  }
+
+  /**
+   * Format balance with symbol for display.
+   */
+  formatBalanceWithSymbol(raw, symbol, decimals = 9) {
+    return `${this.formatBalance(raw, decimals)} ${symbol}`;
+  }
+
+  /**
+   * Format balance diff with +/- prefix.
+   */
+  formatDiff(diff, symbol, decimals = 9) {
+    const formatted = this.formatBalance(diff < 0n ? -diff : diff, decimals);
+    const prefix = diff >= 0n ? '+' : '-';
+    return `${prefix}${formatted} ${symbol}`;
+  }
+
+  /**
+   * Get Solana-specific explorer URL.
+   */
+  getExplorerUrl(address) {
+    // Determine if mainnet or devnet based on RPC
+    const isDevnet = this.networkConfig.rpcUrl.includes('devnet');
+    const cluster = isDevnet ? '?cluster=devnet' : '';
+    return `https://explorer.solana.com/address/${address}${cluster}`;
+  }
+}
+
+module.exports = SolanaAdapter;