multi-chain-balance-diff 0.1.3 → 0.1.6

package/README.md

@@ -11,7 +11,7 @@ mcbd --address 0x... --network mainnet --json | jq '.native.diff'
 
 ## What
 
-CLI that fetches balance at block N and block N-50, computes the difference, outputs JSON or pretty-prints. Supports Ethereum, Polygon, Base, Arbitrum, Optimism, BNB Chain, Avalanche, Fantom, zkSync Era, Solana, Helium, and TON.
+CLI that fetches balance at block N and block N-50, computes the difference, outputs JSON or pretty-prints. Supports Ethereum, Polygon, Base, Arbitrum, Optimism, BNB Chain, Avalanche, Fantom, zkSync Era, Scroll, Solana, Helium, and TON.
 
 ## Who
 
@@ -42,6 +42,8 @@ mcbd --address $FEE_WALLET --network base --alert-if-diff "<-0.1"
 # exit 0 = OK, exit 1 = threshold breached, exit 2 = RPC error
 ```
 
+> 📁 See [`.github/examples/`](./.github/examples/) for ready-to-use GitHub Actions workflows.
+
 ### 3. DeFi/Rewards: Staking reward accrual verification
 
 ```bash
@@ -114,6 +116,7 @@ mcbd --address 0x... --alert-if-diff ">0.01"   # CI threshold
 | `avalanche` | EVM | AVAX | USDC, USDT |
 | `fantom` | EVM | FTM | USDC, USDT, DAI |
 | `zksync` | EVM | ETH | USDC, USDT |
+| `scroll` | EVM | ETH | USDC, USDT, WETH |
 | `solana` | Solana | SOL | USDC, BONK, JUP |
 | `helium` | Solana | SOL | HNT, MOBILE, IOT, DC |
 | `ton` | TON | TON | — |
@@ -136,6 +139,7 @@ mcbd --address 0x... --alert-if-diff ">0.01"   # CI threshold
 | `--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`) |
+| `--webhook` | POST JSON payload to URL when alert triggers |
 
 **Exit codes:** `0` OK · `1` diff triggered · `2` RPC failure/timeout · `130` SIGINT
 
@@ -185,6 +189,26 @@ mcbd -a 0x... -n mainnet --timeout 60    # 60 seconds
 mcbd -a 0x... -n solana --timeout 10     # 10 seconds (fast-fail)
 ```
 
+### Webhooks
+
+POST JSON payload to a URL when an alert triggers:
+
+```bash
+# Slack webhook
+mcbd -a 0xTreasury -n mainnet --alert-if-diff "<-1" \
+  --webhook https://hooks.slack.com/services/XXX/YYY/ZZZ --json
+
+# Discord webhook
+mcbd -a 0xTreasury -n base --alert-pct "<-5" \
+  --webhook https://discord.com/api/webhooks/XXX/YYY --json
+
+# Custom endpoint
+mcbd -a 0xTreasury -n polygon --alert-if-diff ">0.1" \
+  --webhook https://your-server.com/balance-alert --json
+```
+
+The webhook payload includes the full JSON output plus a `webhook.sentAt` timestamp.
+
 ---
 
 ## Common Failure Modes
@@ -360,6 +384,25 @@ MIT
 
 ---
 
+## Author
+
+Built by [Alex Alexapolsky](https://www.linkedin.com/in/alexey-a-181a614/) ([@metawake](https://github.com/metawake)). Available for Web3 infra consulting and contract work.
+
+⭐ **If you find this useful, [star the repo](https://github.com/metawake/multi-chain-balance-diff)** — it helps others discover it.
+
+## Support Development
+
+If this tool saves you time or money, consider supporting its development:
+
+**ETH donations (any EVM chain):**
+```
+0x0a542565b3615e8fc934cc3cc4921a0c22e5dc5e
+```
+
+💡 *Hint: This tool monitors balance changes — you can use it to verify your own donation went through!*
+
+---
+
 <!--
 GitHub repo description (1 sentence):
 CLI tool to fetch and diff wallet balances across EVM and Solana chains. JSON output, CI-friendly exit codes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "multi-chain-balance-diff",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "description": "CLI tool to fetch and compare wallet balances across EVM and Solana chains",
   "main": "src/index.js",
   "bin": {
@@ -29,8 +29,12 @@
     "crypto",
     "wallet"
   ],
-  "author": "",
+  "author": "Alex Alexapolsky (https://github.com/metawake)",
   "license": "MIT",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/metawake"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/metawake/multi-chain-balance-diff.git"

package/schema/mcbd-output.schema.json

@@ -296,3 +296,6 @@
 }
 
 
+
+
+

package/src/adapters/baseAdapter.js

@@ -120,3 +120,6 @@ class BaseAdapter {
 
 module.exports = BaseAdapter;
 
+
+
+

package/src/adapters/evmAdapter.js

@@ -134,3 +134,6 @@ class EVMAdapter extends BaseAdapter {
 module.exports = EVMAdapter;
 
 
+
+
+

package/src/adapters/solanaAdapter.js

@@ -207,3 +207,6 @@ class SolanaAdapter extends BaseAdapter {
 module.exports = SolanaAdapter;
 
 
+
+
+

package/src/adapters/tonAdapter.js

@@ -93,3 +93,6 @@ class TonAdapter extends BaseAdapter {
 
 module.exports = TonAdapter;
 
+
+
+

package/src/config/networks.js

@@ -178,6 +178,21 @@ const networks = {
     ],
   },
 
+  scroll: {
+    name: 'Scroll',
+    chainType: 'evm',
+    chainId: 534352,
+    rpcUrl: process.env.RPC_URL_SCROLL || 'https://rpc.scroll.io',
+    nativeSymbol: 'ETH',
+    nativeDecimals: 18,
+    blockExplorer: 'https://scrollscan.com',
+    tokens: [
+      { symbol: 'USDC', address: '0x06eFdBFf2a14a7c8E15944D1F4A48F9F95F663A4', decimals: 6 },
+      { symbol: 'USDT', address: '0xf55BEC9cafDbE8730f096Aa55dad6D22d44099Df', decimals: 6 },
+      { symbol: 'WETH', address: '0x5300000000000000000000000000000000000004', decimals: 18 },
+    ],
+  },
+
   // ==========================================================================
   // Solana Networks
   // ==========================================================================

package/src/index.js

@@ -59,6 +59,7 @@ program
   .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')
+  .option('--webhook <url>', 'POST JSON payload to URL when alert triggers')
   .parse(process.argv);
 
 const options = program.opts();
@@ -310,6 +311,88 @@ function checkPercentageThreshold(diffRaw, previousRaw, decimals, threshold) {
   }
 }
 
+// ==========================================================================
+// Webhook Support
+// ==========================================================================
+
+/**
+ * POST JSON payload to webhook URL
+ * @param {string} url - Webhook URL
+ * @param {object} payload - JSON payload to send
+ * @returns {Promise<{success: boolean, statusCode?: number, error?: string}>}
+ */
+async function sendWebhook(url, payload) {
+  try {
+    const urlObj = new URL(url);
+    const isHttps = urlObj.protocol === 'https:';
+    const http = isHttps ? require('https') : require('http');
+    
+    const postData = JSON.stringify(payload);
+    
+    const requestOptions = {
+      hostname: urlObj.hostname,
+      port: urlObj.port || (isHttps ? 443 : 80),
+      path: urlObj.pathname + urlObj.search,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(postData),
+        'User-Agent': `multi-chain-balance-diff/${VERSION}`,
+      },
+      timeout: 10000, // 10 second timeout for webhook
+    };
+
+    return new Promise((resolve) => {
+      const req = http.request(requestOptions, (res) => {
+        resolve({ success: res.statusCode >= 200 && res.statusCode < 300, statusCode: res.statusCode });
+      });
+
+      req.on('error', (error) => {
+        resolve({ success: false, error: error.message });
+      });
+
+      req.on('timeout', () => {
+        req.destroy();
+        resolve({ success: false, error: 'Request timeout' });
+      });
+
+      req.write(postData);
+      req.end();
+    });
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Build and send webhook if configured and alert triggered
+ */
+async function maybeNotifyWebhook(payload, alertTriggered) {
+  if (!options.webhook || !alertTriggered) {
+    return null;
+  }
+
+  const webhookPayload = {
+    ...payload,
+    webhook: {
+      sentAt: new Date().toISOString(),
+      trigger: 'alert',
+    },
+  };
+
+  const result = await sendWebhook(options.webhook, webhookPayload);
+  
+  if (!options.json) {
+    if (result.success) {
+      console.log(`${c('green')}✓ Webhook sent${c('reset')}`);
+    } else {
+      console.log(`${c('red')}✗ Webhook failed: ${result.error || `HTTP ${result.statusCode}`}${c('reset')}`);
+    }
+  }
+
+  return result;
+}
+
 // ==========================================================================
 // Network List Command
 // ==========================================================================
@@ -479,10 +562,15 @@ function printPrettyOutput(networkConfig, address, balanceDiff, tokenBalances, a
 
   if (!isMulti) {
     printSeparator('═');
+    printSponsorHint();
     console.log();
   }
 }
 
+function printSponsorHint() {
+  console.log(`  ${c('dim')}★ Tips: 0x0a54...dc5e · github.com/metawake/multi-chain-balance-diff${c('reset')}`);
+}
+
 function printMultiAddressSummary(networkConfig, results, blocksBack) {
   console.log();
   printSeparator('═');
@@ -512,6 +600,7 @@ function printMultiAddressSummary(networkConfig, results, blocksBack) {
   const totalDiffColored = formatDiffColored(totalDiff, networkConfig.nativeSymbol, networkConfig.nativeDecimals);
   console.log(`  ${c('bright')}Total:${c('reset')}      ${totalFormatted.padStart(12)} ${networkConfig.nativeSymbol}  ${totalDiffColored}`);
   printSeparator('═');
+  printSponsorHint();
   console.log();
 }
 
@@ -938,6 +1027,9 @@ async function main() {
         console.log(`${c('yellow')}⚠️  Alert: threshold ${which} triggered${c('reset')}\n`);
       }
     }
+
+    // Send webhook if configured and alert triggered
+    await maybeNotifyWebhook(output, anyAlertTriggered);
     
     process.exit(anyAlertTriggered ? EXIT_DIFF : EXIT_OK);
   }
@@ -999,6 +1091,9 @@ async function main() {
       }
     }
 
+    // Send webhook if configured and alert triggered
+    await maybeNotifyWebhook(output, alertTriggered);
+
     // Exit with appropriate code
     process.exit(alertTriggered ? EXIT_DIFF : EXIT_OK);
 

package/src/services/balanceService.js

@@ -155,3 +155,6 @@ module.exports = {
   formatBalanceDiff,
 };
 
+
+
+