multi-chain-balance-diff 0.1.0 → 0.1.2

package/README.md

@@ -110,8 +110,13 @@ mcbd --address 0x... --alert-if-diff ">0.01"   # CI threshold
 | `base` | EVM | ETH | USDC, cbETH, DAI |
 | `arbitrum` | EVM | ETH | USDC, ARB, GMX |
 | `optimism` | EVM | ETH | USDC, OP, SNX |
+| `bnb` | EVM | BNB | USDT, USDC, BUSD |
+| `avalanche` | EVM | AVAX | USDC, USDT |
+| `fantom` | EVM | FTM | USDC, USDT, DAI |
+| `zksync` | EVM | ETH | USDC, USDT |
 | `solana` | Solana | SOL | USDC, BONK, JUP |
 | `helium` | Solana | SOL | HNT, MOBILE, IOT, DC |
+| `ton` | TON | TON | — |
 
 ## Options
 
@@ -130,8 +135,9 @@ mcbd --address 0x... --alert-if-diff ">0.01"   # CI threshold
 | `--no-tokens` | Skip ERC-20/SPL token checks |
 | `--alert-if-diff` | Exit 1 if diff matches condition (e.g., `">0.01"`, `"<-1"`) |
 | `--alert-pct` | Exit 1 if diff exceeds % of balance (e.g., `">5"`, `"<-10"`) |
+| `--timeout` | RPC request timeout in seconds (default: `30`) |
 
-**Exit codes:** `0` OK · `1` diff triggered · `2` RPC failure · `130` SIGINT
+**Exit codes:** `0` OK · `1` diff triggered · `2` RPC failure/timeout · `130` SIGINT
 
 ---
 
@@ -148,6 +154,39 @@ mcbd --address 0x... --alert-if-diff ">0.01"   # CI threshold
 
 ---
 
+## Configuration
+
+### Custom RPC Endpoints
+
+Override default public RPCs with environment variables:
+
+| Variable | Network |
+|----------|---------|
+| `RPC_URL_ETH` | Ethereum Mainnet |
+| `RPC_URL_POLYGON` | Polygon |
+| `RPC_URL_BASE` | Base |
+| `RPC_URL_ARBITRUM` | Arbitrum |
+| `RPC_URL_OPTIMISM` | Optimism |
+| `RPC_URL_SOLANA` | Solana / Helium |
+| `RPC_URL_SEPOLIA` | Sepolia testnet |
+
+```bash
+# Use private RPC for reliability
+export RPC_URL_ETH=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY
+mcbd -a 0x... -n mainnet --json
+```
+
+### Timeout
+
+Default timeout is 30 seconds. Adjust for slow or unreliable RPCs:
+
+```bash
+mcbd -a 0x... -n mainnet --timeout 60    # 60 seconds
+mcbd -a 0x... -n solana --timeout 10     # 10 seconds (fast-fail)
+```
+
+---
+
 ## Common Failure Modes
 
 ### RPC Rate Limits
@@ -155,17 +194,24 @@ mcbd --address 0x... --alert-if-diff ">0.01"   # CI threshold
 Public RPCs have strict rate limits. Symptoms: `429 Too Many Requests` or slow responses.
 
 ```bash
-# Solution: Use a private RPC (Alchemy, Infura, QuickNode)
-export ETH_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY
+# Solution: Use a private RPC
+export RPC_URL_ETH=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY
+```
+
+### Timeout / Slow RPC
+
+```bash
+# Increase timeout for slow networks
+mcbd -a 0x... -n mainnet --timeout 60
 ```
 
 ### Unavailable Chain / RPC Down
 
 ```json
-{"schemaVersion":"0.1.0","error":"connect ECONNREFUSED 127.0.0.1:8545","code":"ECONNREFUSED","exitCode":2}
+{"schemaVersion":"0.1.0","error":"connect ECONNREFUSED","code":"ECONNREFUSED","exitCode":2}
 ```
 
-Exit code `2` indicates RPC failure. Check network connectivity and RPC URL validity.
+Exit code `2` indicates RPC failure. Check network connectivity and RPC URL.
 
 ### Invalid Address Format
 
@@ -176,15 +222,6 @@ $ mcbd --address invalid --network mainnet --json
 
 EVM addresses must be `0x` + 40 hex chars. Solana addresses are base58 encoded.
 
-### Missing Environment Variables
-
-If using custom RPC endpoints via env vars, ensure they're set before running:
-
-```bash
-# Check if RPC env is set
-[ -z "$ETH_RPC_URL" ] && echo "Warning: Using public RPC (rate limited)"
-```
-
 ---
 
 ## Watch Mode for CI/Cron

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "multi-chain-balance-diff",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "CLI tool to fetch and compare wallet balances across EVM and Solana chains",
   "main": "src/index.js",
   "bin": {
@@ -14,7 +14,7 @@
   ],
   "scripts": {
     "start": "node src/index.js",
-    "test": "node --test 'tests/*.test.js'"
+    "test": "node --test tests/*.test.js"
   },
   "keywords": [
     "ethereum",
@@ -44,9 +44,9 @@
   },
   "dependencies": {
     "@solana/web3.js": "^1.95.0",
+    "@ton/ton": "^15.4.0",
     "commander": "^12.1.0",
     "dotenv": "^16.4.5",
     "ethers": "^6.13.4"
   }
 }
-

package/schema/mcbd-output.schema.json

@@ -295,3 +295,4 @@
   }
 }
 
+

package/src/adapters/baseAdapter.js

@@ -119,3 +119,4 @@ class BaseAdapter {
 }
 
 module.exports = BaseAdapter;
+

package/src/adapters/evmAdapter.js

@@ -6,7 +6,7 @@
  * all compatible networks.
  */
 
-const { ethers } = require('ethers');
+const { ethers, FetchRequest } = require('ethers');
 const BaseAdapter = require('./baseAdapter');
 
 // Minimal ERC-20 ABI for balance queries
@@ -16,10 +16,14 @@ const ERC20_ABI = [
   'function symbol() view returns (string)',
 ];
 
+// Default timeout: 30 seconds
+const DEFAULT_TIMEOUT_MS = 30000;
+
 class EVMAdapter extends BaseAdapter {
-  constructor(networkConfig) {
+  constructor(networkConfig, options = {}) {
     super(networkConfig);
     this.provider = null;
+    this.timeoutMs = options.timeoutMs || DEFAULT_TIMEOUT_MS;
   }
 
   getChainType() {
@@ -27,7 +31,11 @@ class EVMAdapter extends BaseAdapter {
   }
 
   async connect() {
-    this.provider = new ethers.JsonRpcProvider(this.networkConfig.rpcUrl);
+    // Create FetchRequest with timeout
+    const fetchRequest = new FetchRequest(this.networkConfig.rpcUrl);
+    fetchRequest.timeout = this.timeoutMs;
+    
+    this.provider = new ethers.JsonRpcProvider(fetchRequest);
     // Verify connection by fetching network
     await this.provider.getNetwork();
     this.connection = this.provider;
@@ -124,3 +132,5 @@ class EVMAdapter extends BaseAdapter {
 }
 
 module.exports = EVMAdapter;
+
+

package/src/adapters/index.js

@@ -12,6 +12,7 @@
 
 const EVMAdapter = require('./evmAdapter');
 const SolanaAdapter = require('./solanaAdapter');
+const TonAdapter = require('./tonAdapter');
 
 /**
  * Chain type to adapter class mapping.
@@ -19,16 +20,19 @@ const SolanaAdapter = require('./solanaAdapter');
 const ADAPTER_MAP = {
   evm: EVMAdapter,
   solana: SolanaAdapter,
+  ton: TonAdapter,
 };
 
 /**
  * Create an adapter for the given network configuration.
  * 
  * @param {object} networkConfig - Network configuration from networks.js
+ * @param {object} options - Adapter options
+ * @param {number} options.timeoutMs - RPC timeout in milliseconds (default: 30000)
  * @returns {BaseAdapter} Chain-specific adapter instance
  * @throws {Error} If chain type is not supported
  */
-function createAdapter(networkConfig) {
+function createAdapter(networkConfig, options = {}) {
   // Determine chain type (default to 'evm' for backwards compatibility)
   const chainType = networkConfig.chainType || 'evm';
   
@@ -41,7 +45,7 @@ function createAdapter(networkConfig) {
     );
   }
   
-  return new AdapterClass(networkConfig);
+  return new AdapterClass(networkConfig, options);
 }
 
 /**
@@ -67,4 +71,7 @@ module.exports = {
   isChainTypeSupported,
   EVMAdapter,
   SolanaAdapter,
+  TonAdapter,
 };
+
+

package/src/adapters/solanaAdapter.js

@@ -18,20 +18,48 @@ const BaseAdapter = require('./baseAdapter');
 // SPL Token Program ID
 const TOKEN_PROGRAM_ID = new PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA');
 
+// Default timeout: 30 seconds
+const DEFAULT_TIMEOUT_MS = 30000;
+
 class SolanaAdapter extends BaseAdapter {
-  constructor(networkConfig) {
+  constructor(networkConfig, options = {}) {
     super(networkConfig);
     this.conn = null;
+    this.timeoutMs = options.timeoutMs || DEFAULT_TIMEOUT_MS;
   }
 
   getChainType() {
     return 'solana';
   }
 
+  /**
+   * Create a fetch function with timeout support.
+   */
+  _createFetchWithTimeout() {
+    const timeoutMs = this.timeoutMs;
+    return async (url, options) => {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+      
+      try {
+        const response = await fetch(url, {
+          ...options,
+          signal: controller.signal,
+        });
+        return response;
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    };
+  }
+
   async connect() {
     this.conn = new Connection(
       this.networkConfig.rpcUrl,
-      { commitment: 'confirmed' }
+      { 
+        commitment: 'confirmed',
+        fetch: this._createFetchWithTimeout(),
+      }
     );
     // Verify connection
     await this.conn.getSlot();
@@ -177,3 +205,5 @@ class SolanaAdapter extends BaseAdapter {
 }
 
 module.exports = SolanaAdapter;
+
+

package/src/adapters/tonAdapter.js

@@ -0,0 +1,95 @@
+/**
+ * TON (The Open Network) Adapter
+ * 
+ * Handles TON blockchain balance queries.
+ * Uses @ton/ton SDK for RPC communication.
+ */
+
+const { TonClient, Address, fromNano } = require('@ton/ton');
+const BaseAdapter = require('./baseAdapter');
+
+// Default timeout: 30 seconds
+const DEFAULT_TIMEOUT_MS = 30000;
+
+class TonAdapter extends BaseAdapter {
+  constructor(networkConfig, options = {}) {
+    super(networkConfig);
+    this.client = null;
+    this.timeoutMs = options.timeoutMs || DEFAULT_TIMEOUT_MS;
+  }
+
+  getChainType() {
+    return 'ton';
+  }
+
+  async connect() {
+    this.client = new TonClient({
+      endpoint: this.networkConfig.rpcUrl,
+      timeout: this.timeoutMs,
+    });
+    // Verify connection by getting masterchain info
+    await this.client.getMasterchainInfo();
+    this.connection = this.client;
+  }
+
+  async getCurrentBlock() {
+    const info = await this.client.getMasterchainInfo();
+    return info.last.seqno;
+  }
+
+  async getNativeBalance(address, blockTag = 'latest') {
+    const addr = Address.parse(address);
+    
+    // TON doesn't easily support historical balance queries via standard API
+    // We fetch current balance
+    const balance = await this.client.getBalance(addr);
+    
+    return {
+      raw: balance,
+      formatted: this.formatBalance(balance, 9), // TON has 9 decimals
+      decimals: 9,
+    };
+  }
+
+  async getTokenBalances(address, tokens) {
+    // TON Jettons (tokens) require parsing wallet contract state
+    // This is more complex than EVM - simplified implementation
+    // Returns empty for now, can be extended later
+    return [];
+  }
+
+  isValidAddress(address) {
+    try {
+      Address.parse(address);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  formatBalance(raw, decimals = 9) {
+    // fromNano converts from nanoTON to TON
+    return fromNano(raw);
+  }
+
+  formatBalanceWithSymbol(raw, symbol, decimals = 9) {
+    return `${this.formatBalance(raw, decimals)} ${symbol}`;
+  }
+
+  formatDiff(diff, symbol, decimals = 9) {
+    const formatted = this.formatBalance(diff < 0n ? -diff : diff, decimals);
+    const prefix = diff >= 0n ? '+' : '-';
+    return `${prefix}${formatted} ${symbol}`;
+  }
+
+  getExplorerUrl(address) {
+    const isTestnet = this.networkConfig.rpcUrl.includes('testnet');
+    const baseUrl = isTestnet 
+      ? 'https://testnet.tonscan.org' 
+      : 'https://tonscan.org';
+    return `${baseUrl}/address/${address}`;
+  }
+}
+
+module.exports = TonAdapter;
+

package/src/config/networks.js

@@ -118,6 +118,66 @@ const networks = {
     ],
   },
 
+  bnb: {
+    name: 'BNB Chain',
+    chainType: 'evm',
+    chainId: 56,
+    rpcUrl: process.env.RPC_URL_BNB || 'https://bsc-dataseed.binance.org',
+    nativeSymbol: 'BNB',
+    nativeDecimals: 18,
+    blockExplorer: 'https://bscscan.com',
+    tokens: [
+      { symbol: 'USDT', address: '0x55d398326f99059fF775485246999027B3197955', decimals: 18 },
+      { symbol: 'USDC', address: '0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d', decimals: 18 },
+      { symbol: 'BUSD', address: '0xe9e7CEA3DedcA5984780Bafc599bD69ADd087D56', decimals: 18 },
+      { symbol: 'WBNB', address: '0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c', decimals: 18 },
+    ],
+  },
+
+  avalanche: {
+    name: 'Avalanche C-Chain',
+    chainType: 'evm',
+    chainId: 43114,
+    rpcUrl: process.env.RPC_URL_AVAX || 'https://api.avax.network/ext/bc/C/rpc',
+    nativeSymbol: 'AVAX',
+    nativeDecimals: 18,
+    blockExplorer: 'https://snowtrace.io',
+    tokens: [
+      { symbol: 'USDC', address: '0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E', decimals: 6 },
+      { symbol: 'USDT', address: '0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7', decimals: 6 },
+      { symbol: 'WAVAX', address: '0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7', decimals: 18 },
+    ],
+  },
+
+  fantom: {
+    name: 'Fantom Opera',
+    chainType: 'evm',
+    chainId: 250,
+    rpcUrl: process.env.RPC_URL_FTM || 'https://rpc.ftm.tools',
+    nativeSymbol: 'FTM',
+    nativeDecimals: 18,
+    blockExplorer: 'https://ftmscan.com',
+    tokens: [
+      { symbol: 'USDC', address: '0x04068DA6C83AFCFA0e13ba15A6696662335D5B75', decimals: 6 },
+      { symbol: 'USDT', address: '0x049d68029688eAbF473097a2fC38ef61633A3C7A', decimals: 6 },
+      { symbol: 'DAI', address: '0x8D11eC38a3EB5E956B052f67Da8Bdc9bef8Abf3E', decimals: 18 },
+    ],
+  },
+
+  zksync: {
+    name: 'zkSync Era',
+    chainType: 'evm',
+    chainId: 324,
+    rpcUrl: process.env.RPC_URL_ZKSYNC || 'https://mainnet.era.zksync.io',
+    nativeSymbol: 'ETH',
+    nativeDecimals: 18,
+    blockExplorer: 'https://explorer.zksync.io',
+    tokens: [
+      { symbol: 'USDC', address: '0x3355df6D4c9C3035724Fd0e3914dE96A5a83aaf4', decimals: 6 },
+      { symbol: 'USDT', address: '0x493257fD37EDB34451f62EDf8D2a0C418852bA4C', decimals: 6 },
+    ],
+  },
+
   // ==========================================================================
   // Solana Networks
   // ==========================================================================
@@ -179,6 +239,34 @@ const networks = {
     blockExplorer: 'https://explorer.solana.com',
     tokens: [],
   },
+
+  // ==========================================================================
+  // TON Networks
+  // ==========================================================================
+
+  ton: {
+    name: 'TON Mainnet',
+    chainType: 'ton',
+    chainId: null,
+    rpcUrl: process.env.RPC_URL_TON || 'https://toncenter.com/api/v2/jsonRPC',
+    nativeSymbol: 'TON',
+    nativeDecimals: 9,
+    blockExplorer: 'https://tonscan.org',
+    tokens: [
+      // Jettons can be added here later
+    ],
+  },
+
+  'ton-testnet': {
+    name: 'TON Testnet',
+    chainType: 'ton',
+    chainId: null,
+    rpcUrl: process.env.RPC_URL_TON_TESTNET || 'https://testnet.toncenter.com/api/v2/jsonRPC',
+    nativeSymbol: 'TON',
+    nativeDecimals: 9,
+    blockExplorer: 'https://testnet.tonscan.org',
+    tokens: [],
+  },
 };
 
 // ==========================================================================
@@ -232,3 +320,4 @@ module.exports = {
   getChainType,
 };
 
+

package/src/index.js

@@ -58,6 +58,7 @@ program
   .option('--config <path>', 'Path to config file')
   .option('--alert-if-diff <threshold>', 'Exit 1 if diff exceeds threshold (e.g., ">0.01", ">=1", "<-0.5")')
   .option('--alert-pct <threshold>', 'Exit 1 if diff exceeds % of balance (e.g., ">5", "<-10")')
+  .option('--timeout <seconds>', 'RPC request timeout in seconds', '30')
   .parse(process.argv);
 
 const options = program.opts();
@@ -325,6 +326,10 @@ function listNetworks() {
         const net = getNetwork(key);
         return { key, name: net.name, symbol: net.nativeSymbol };
       }),
+      ton: getNetworksByType('ton').map(key => {
+        const net = getNetwork(key);
+        return { key, name: net.name, symbol: net.nativeSymbol };
+      }),
     };
     console.log(JSON.stringify(networks, null, 2));
     return;
@@ -343,12 +348,18 @@ function listNetworks() {
     const net = getNetwork(key);
     console.log(`    ${c('cyan')}${key.padEnd(12)}${c('reset')} ${net.name} (${net.nativeSymbol})`);
   }
+
+  console.log('\n  TON Chains:');
+  for (const key of getNetworksByType('ton')) {
+    const net = getNetwork(key);
+    console.log(`    ${c('cyan')}${key.padEnd(12)}${c('reset')} ${net.name} (${net.nativeSymbol})`);
+  }
   
   console.log('\nUsage:');
   console.log('  mcbd --address <ADDR> --network mainnet');
   console.log('  mcbd --address <ADDR> --network base');
   console.log('  mcbd --address <ADDR> --network solana');
-  console.log('  mcbd --address <ADDR> --network helium --json\n');
+  console.log('  mcbd --address <ADDR> --network ton --json\n');
 }
 
 // ==========================================================================
@@ -803,8 +814,11 @@ async function main() {
     process.exit(1);
   }
 
+  // Parse timeout (convert seconds to milliseconds)
+  const timeoutMs = parseInt(options.timeout, 10) * 1000;
+
   // Create the appropriate adapter for this chain
-  const adapter = createAdapter(networkConfig);
+  const adapter = createAdapter(networkConfig, { timeoutMs });
 
   // Validate all addresses before connecting (fail fast)
   for (const addr of addresses) {

package/src/services/balanceService.js

@@ -154,3 +154,4 @@ module.exports = {
   formatBalance,
   formatBalanceDiff,
 };
+