multi-chain-balance-diff 0.1.0

package/README.md

@@ -0,0 +1,332 @@
+# multi-chain-balance-diff
+
+[![Tests](https://github.com/metawake/multi-chain-balance-diff/actions/workflows/test.yml/badge.svg)](https://github.com/metawake/multi-chain-balance-diff/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**Compare wallet balances across EVM and Solana chains. Returns structured diffs.**
+
+```bash
+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, Solana, Helium.
+
+## Who
+
+Infrastructure engineers, protocol developers, and operators who need scriptable balance checks without spinning up dashboards or paying for analytics platforms.
+
+## Why
+
+Portfolio trackers are UI-only. Analytics platforms are expensive and slow. Raw RPC calls require boilerplate. This fills the gap: a `diff`-like primitive for on-chain balances that fits into shell scripts, cron jobs, and CI pipelines.
+
+---
+
+## Use Cases
+
+### 1. Operations: Treasury monitoring
+
+```bash
+# Cron job: alert ops channel if treasury balance drops
+mcbd --address 0xTreasury --network mainnet --json \
+  | jq -e '.native.diffSign == "negative"' \
+  && curl -X POST $SLACK_WEBHOOK -d '{"text":"Treasury balance decreased"}'
+```
+
+### 2. CI/Monitoring: Post-deployment sanity check
+
+```bash
+# GitHub Actions: fail pipeline if fee wallet drained unexpectedly
+mcbd --address $FEE_WALLET --network base --alert-if-diff "<-0.1"
+# exit 0 = OK, exit 1 = threshold breached, exit 2 = RPC error
+```
+
+### 3. DeFi/Rewards: Staking reward accrual verification
+
+```bash
+# Verify staking rewards are accruing over 1000 blocks
+mcbd --address $STAKER --network mainnet --blocks 1000 --json \
+  | jq '.native.diff' 
+# Expected: positive value if rewards distributed
+```
+
+---
+
+## Install
+
+```bash
+npm install -g multi-chain-balance-diff
+```
+
+**One-shot (no install):**
+
+```bash
+npx multi-chain-balance-diff -a 0x... -n mainnet --json
+```
+
+---
+
+## Quickstart (60 seconds)
+
+```bash
+# 1. Check a wallet balance diff (uses public RPC)
+mcbd --address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --network mainnet
+
+# 2. Get JSON output, extract the diff
+mcbd -a 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 -n mainnet --json | jq '.native.diff'
+
+# 3. CI check: exit 1 if balance dropped more than 0.1 ETH
+mcbd -a 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 -n mainnet --alert-if-diff "<-0.1"
+echo "Exit code: $?"
+# 0 = OK, 1 = threshold triggered, 2 = RPC error
+```
+
+**One-liner for npx (no install):**
+
+```bash
+npx multi-chain-balance-diff -a 0x... -n mainnet --json
+```
+
+---
+
+## Usage
+
+```bash
+mcbd --address 0x... --network mainnet          # pretty output
+mcbd --address 0x... --json                     # structured output
+mcbd --address 0x... --blocks 1000              # custom lookback
+mcbd --address 0x... --watch --interval 30      # continuous monitoring
+mcbd --addresses 0xA,0xB,0xC --network base     # batch
+mcbd --address 0x... --alert-if-diff ">0.01"   # CI threshold
+```
+
+## Networks
+
+| Key | Type | Native | Tokens |
+|-----|------|--------|--------|
+| `mainnet` | EVM | ETH | USDC, USDT, stETH |
+| `polygon` | EVM | MATIC | USDC, USDT, WETH |
+| `base` | EVM | ETH | USDC, cbETH, DAI |
+| `arbitrum` | EVM | ETH | USDC, ARB, GMX |
+| `optimism` | EVM | ETH | USDC, OP, SNX |
+| `solana` | Solana | SOL | USDC, BONK, JUP |
+| `helium` | Solana | SOL | HNT, MOBILE, IOT, DC |
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `-a, --address` | Wallet address |
+| `-A, --addresses` | Multiple addresses (comma-sep or file path) |
+| `-n, --network` | Target network (default: `mainnet`) |
+| `-b, --blocks` | Lookback depth (default: `50`) |
+| `-w, --watch` | Continuous monitoring mode |
+| `-i, --interval` | Watch interval in seconds (default: `30`) |
+| `-c, --count` | Exit after N polls (watch mode) |
+| `--exit-on-error` | Exit immediately on RPC failure (watch mode) |
+| `--exit-on-diff` | Exit immediately when threshold triggers (watch mode) |
+| `--json` | JSON output |
+| `--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"`) |
+
+**Exit codes:** `0` OK · `1` diff triggered · `2` RPC failure · `130` SIGINT
+
+---
+
+## Exit Codes & Batch Semantics
+
+| Code | Meaning | When |
+|------|---------|------|
+| `0` | OK | No threshold triggered, all queries succeeded |
+| `1` | Diff triggered | Threshold condition matched (any address) |
+| `2` | RPC error | Network/connection failure |
+| `130` | SIGINT | User interrupted (Ctrl+C) |
+
+**Batch mode (`--addresses`)**: Returns exit `1` if *any* address triggers the threshold. Partial failures are included in JSON output with `error` field per address; successful queries still return data.
+
+---
+
+## Common Failure Modes
+
+### RPC Rate Limits
+
+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
+```
+
+### Unavailable Chain / RPC Down
+
+```json
+{"schemaVersion":"0.1.0","error":"connect ECONNREFUSED 127.0.0.1:8545","code":"ECONNREFUSED","exitCode":2}
+```
+
+Exit code `2` indicates RPC failure. Check network connectivity and RPC URL validity.
+
+### Invalid Address Format
+
+```bash
+$ mcbd --address invalid --network mainnet --json
+{"schemaVersion":"0.1.0","error":"Invalid EVM address: invalid"}
+```
+
+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
+
+Watch mode is designed for long-running monitoring, cron jobs, and CI pipelines.
+
+### Patterns
+
+```bash
+# One-shot: poll once, exit on threshold
+mcbd -a $ADDR -n base --count 1 --alert-if-diff ">0.01" --json
+
+# CI health check: 5 polls, fail fast on error or diff
+mcbd -a $ADDR -n mainnet --watch --count 5 \
+  --exit-on-error --exit-on-diff --alert-pct ">10" --json
+
+# Cron monitor: 10 polls over 5 minutes, log NDJSON
+mcbd -a $ADDR -n solana --watch --interval 30 --count 10 --json >> /var/log/balance.ndjson
+
+# Infinite watch with alerts (SIGINT to stop)
+mcbd -a $ADDR -n polygon --watch --interval 60 --alert-if-diff "<-1"
+```
+
+### Example Output
+
+**Normal operation (no diff):**
+
+```json
+{
+  "schemaVersion": "0.1.0",
+  "network": { "key": "mainnet", "name": "Ethereum Mainnet", "chainType": "evm", "chainId": 1 },
+  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
+  "explorer": "https://etherscan.io/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
+  "block": { "current": 19234567, "previous": 19234517 },
+  "native": {
+    "symbol": "ETH",
+    "decimals": 18,
+    "balance": "1.234567",
+    "balanceRaw": "1234567000000000000",
+    "diff": "0",
+    "diffRaw": "0",
+    "diffSign": "positive"
+  },
+  "tokens": [],
+  "timestamp": "2025-01-15T10:30:00.000Z"
+}
+```
+
+Exit: `0`
+
+**Diff detected (threshold triggered):**
+
+```json
+{
+  "schemaVersion": "0.1.0",
+  "network": { "key": "base", "name": "Base", "chainType": "evm", "chainId": 8453 },
+  "address": "0xTreasury...",
+  "block": { "current": 8765432, "previous": 8765382 },
+  "native": {
+    "symbol": "ETH",
+    "balance": "10.5",
+    "diff": "0.05",
+    "diffRaw": "50000000000000000",
+    "diffSign": "positive"
+  },
+  "alert": {
+    "threshold": ">0.01",
+    "thresholdPct": null,
+    "triggered": true,
+    "triggeredBy": "absolute"
+  },
+  "timestamp": "2025-01-15T10:30:00.000Z"
+}
+```
+
+Exit: `1`
+
+**Error state (RPC unavailable):**
+
+```json
+{
+  "schemaVersion": "0.1.0",
+  "error": "connect ECONNREFUSED 127.0.0.1:8545",
+  "code": "ECONNREFUSED",
+  "exitCode": 2
+}
+```
+
+Exit: `2`
+
+**Watch mode NDJSON stream:**
+
+```json
+{"schemaVersion":"0.1.0","type":"watch_start","timestamp":"2025-01-15T10:30:00.000Z","network":"mainnet","address":"0x...","interval":30,"count":3}
+{"schemaVersion":"0.1.0","timestamp":"2025-01-15T10:30:00.500Z","address":"0x...","block":19234567,"balance":"1.234","diff":"0","alert":false,"poll":1}
+{"schemaVersion":"0.1.0","timestamp":"2025-01-15T10:30:30.500Z","address":"0x...","block":19234569,"balance":"1.234","diff":"0","alert":false,"poll":2}
+{"schemaVersion":"0.1.0","timestamp":"2025-01-15T10:31:00.500Z","address":"0x...","block":19234571,"balance":"1.235","diff":"0.001","alert":true,"poll":3}
+{"schemaVersion":"0.1.0","type":"watch_end","timestamp":"2025-01-15T10:31:00.600Z","polls":3,"exitCode":1}
+```
+
+---
+
+## Extending
+
+```
+src/
+├── index.js              # CLI
+├── config/networks.js    # Chain definitions
+├── adapters/
+│   ├── baseAdapter.js    # Interface
+│   ├── evmAdapter.js     # ethers.js
+│   └── solanaAdapter.js  # @solana/web3.js
+```
+
+Add a chain: implement `BaseAdapter`, add to `networks.js`, register in `adapters/index.js`.
+
+## JSON Schema
+
+JSON output includes a `schemaVersion` field (e.g., `"0.1.0"`). Schema changes are versioned:
+
+- **Patch**: Documentation, new optional fields
+- **Minor**: New output types, additive changes  
+- **Major**: Breaking changes to existing fields
+
+See [`schema/mcbd-output.schema.json`](./schema/mcbd-output.schema.json) for the full specification.
+
+## Stability
+
+- JSON schema is versioned. Breaking changes = major version bump.
+- Adapter interface is stable. New chains can be added without breaking existing integrations.
+- See [CHANGELOG.md](./CHANGELOG.md) for release history.
+
+## License
+
+MIT
+
+---
+
+<!--
+GitHub repo description (1 sentence):
+CLI tool to fetch and diff wallet balances across EVM and Solana chains. JSON output, CI-friendly exit codes.
+
+GitHub topics:
+ethereum, solana, blockchain, cli, devops, monitoring, web3, defi
+-->

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "multi-chain-balance-diff",
+  "version": "0.1.0",
+  "description": "CLI tool to fetch and compare wallet balances across EVM and Solana chains",
+  "main": "src/index.js",
+  "bin": {
+    "multi-chain-balance-diff": "./src/index.js",
+    "mcbd": "./src/index.js",
+    "balance-diff": "./src/index.js"
+  },
+  "files": [
+    "src/",
+    "schema/"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node --test 'tests/*.test.js'"
+  },
+  "keywords": [
+    "ethereum",
+    "solana",
+    "web3",
+    "balance",
+    "multi-chain",
+    "cli",
+    "staking",
+    "defi",
+    "helium",
+    "crypto",
+    "wallet"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/metawake/multi-chain-balance-diff.git"
+  },
+  "bugs": {
+    "url": "https://github.com/metawake/multi-chain-balance-diff/issues"
+  },
+  "homepage": "https://github.com/metawake/multi-chain-balance-diff#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@solana/web3.js": "^1.95.0",
+    "commander": "^12.1.0",
+    "dotenv": "^16.4.5",
+    "ethers": "^6.13.4"
+  }
+}
+

package/schema/mcbd-output.schema.json

@@ -0,0 +1,297 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/metawake/multi-chain-balance-diff/schema/mcbd-output.schema.json",
+  "title": "multi-chain-balance-diff Output Schema",
+  "description": "JSON output schema for the mcbd CLI tool",
+  
+  "oneOf": [
+    { "$ref": "#/definitions/BalanceResult" },
+    { "$ref": "#/definitions/MultiAddressResult" },
+    { "$ref": "#/definitions/ErrorResult" },
+    { "$ref": "#/definitions/WatchStart" },
+    { "$ref": "#/definitions/WatchPoll" },
+    { "$ref": "#/definitions/WatchEnd" }
+  ],
+
+  "definitions": {
+    "BalanceResult": {
+      "type": "object",
+      "description": "Single address balance diff result",
+      "required": ["schemaVersion", "network", "address", "native", "timestamp"],
+      "properties": {
+        "schemaVersion": {
+          "type": "string",
+          "description": "Schema version (semver)",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$"
+        },
+        "network": { "$ref": "#/definitions/NetworkInfo" },
+        "address": {
+          "type": "string",
+          "description": "Wallet address"
+        },
+        "explorer": {
+          "type": "string",
+          "format": "uri",
+          "description": "Block explorer URL for address"
+        },
+        "block": { "$ref": "#/definitions/BlockRange" },
+        "slot": { "$ref": "#/definitions/BlockRange" },
+        "native": { "$ref": "#/definitions/NativeBalance" },
+        "tokens": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/TokenBalance" }
+        },
+        "alert": { "$ref": "#/definitions/AlertInfo" },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    },
+
+    "MultiAddressResult": {
+      "type": "object",
+      "description": "Multi-address batch result",
+      "required": ["schemaVersion", "network", "addresses", "summary", "timestamp"],
+      "properties": {
+        "schemaVersion": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$"
+        },
+        "network": { "$ref": "#/definitions/NetworkInfo" },
+        "addresses": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/BalanceResult" }
+        },
+        "summary": {
+          "type": "object",
+          "properties": {
+            "totalAddresses": { "type": "integer" },
+            "successCount": { "type": "integer" },
+            "errorCount": { "type": "integer" }
+          },
+          "required": ["totalAddresses", "successCount", "errorCount"]
+        },
+        "alert": { "$ref": "#/definitions/AlertInfo" },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    },
+
+    "ErrorResult": {
+      "type": "object",
+      "description": "Error response",
+      "required": ["schemaVersion", "error"],
+      "properties": {
+        "schemaVersion": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$"
+        },
+        "error": {
+          "type": "string",
+          "description": "Error message"
+        },
+        "code": {
+          "type": ["string", "null"],
+          "description": "Error code (e.g., ECONNREFUSED)"
+        },
+        "exitCode": {
+          "type": "integer",
+          "description": "Process exit code"
+        }
+      }
+    },
+
+    "WatchStart": {
+      "type": "object",
+      "description": "Watch mode start event (NDJSON)",
+      "required": ["schemaVersion", "type", "timestamp", "network", "address", "interval"],
+      "properties": {
+        "schemaVersion": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$"
+        },
+        "type": {
+          "const": "watch_start"
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "network": { "type": "string" },
+        "address": { "type": "string" },
+        "interval": { "type": "integer" },
+        "count": { "type": ["integer", "null"] },
+        "threshold": { "type": ["string", "null"] },
+        "thresholdPct": { "type": ["string", "null"] }
+      }
+    },
+
+    "WatchPoll": {
+      "type": "object",
+      "description": "Watch mode poll event (NDJSON)",
+      "required": ["schemaVersion", "timestamp", "address"],
+      "properties": {
+        "schemaVersion": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$"
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "address": { "type": "string" },
+        "block": { "type": "integer" },
+        "slot": { "type": "integer" },
+        "balance": { "type": "string" },
+        "balanceRaw": { "type": "string" },
+        "diff": { "type": "string" },
+        "diffRaw": { "type": "string" },
+        "diffSign": {
+          "type": "string",
+          "enum": ["positive", "negative"]
+        },
+        "alert": { "type": "boolean" },
+        "poll": { "type": "integer" },
+        "error": { "type": "string" },
+        "isRpcError": { "type": "boolean" }
+      }
+    },
+
+    "WatchEnd": {
+      "type": "object",
+      "description": "Watch mode end event (NDJSON)",
+      "required": ["schemaVersion", "type", "timestamp", "polls", "exitCode"],
+      "properties": {
+        "schemaVersion": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$"
+        },
+        "type": {
+          "const": "watch_end"
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "polls": { "type": "integer" },
+        "exitCode": { "type": "integer" },
+        "reason": { "type": "string" }
+      }
+    },
+
+    "NetworkInfo": {
+      "type": "object",
+      "required": ["key", "name", "chainType"],
+      "properties": {
+        "key": {
+          "type": "string",
+          "description": "Network identifier (e.g., mainnet, polygon, solana)"
+        },
+        "name": {
+          "type": "string",
+          "description": "Human-readable network name"
+        },
+        "chainType": {
+          "type": "string",
+          "enum": ["evm", "solana"]
+        },
+        "chainId": {
+          "type": "integer",
+          "description": "EVM chain ID (null for Solana)"
+        }
+      }
+    },
+
+    "BlockRange": {
+      "type": "object",
+      "required": ["current", "previous"],
+      "properties": {
+        "current": {
+          "type": "integer",
+          "description": "Current block/slot number"
+        },
+        "previous": {
+          "type": "integer",
+          "description": "Previous block/slot for diff comparison"
+        }
+      }
+    },
+
+    "NativeBalance": {
+      "type": "object",
+      "required": ["symbol", "decimals", "balance", "balanceRaw", "diff", "diffRaw", "diffSign"],
+      "properties": {
+        "symbol": {
+          "type": "string",
+          "description": "Native token symbol (ETH, MATIC, SOL, etc.)"
+        },
+        "decimals": {
+          "type": "integer",
+          "description": "Token decimals"
+        },
+        "balance": {
+          "type": "string",
+          "description": "Formatted current balance"
+        },
+        "balanceRaw": {
+          "type": "string",
+          "description": "Raw balance in smallest unit (wei, lamports, etc.)"
+        },
+        "diff": {
+          "type": "string",
+          "description": "Absolute value of balance difference (formatted)"
+        },
+        "diffRaw": {
+          "type": "string",
+          "description": "Raw diff value (signed)"
+        },
+        "diffSign": {
+          "type": "string",
+          "enum": ["positive", "negative"]
+        }
+      }
+    },
+
+    "TokenBalance": {
+      "type": "object",
+      "required": ["symbol", "decimals", "balance", "balanceRaw"],
+      "properties": {
+        "symbol": { "type": "string" },
+        "address": {
+          "type": "string",
+          "description": "Token contract address (EVM) or mint (Solana)"
+        },
+        "decimals": { "type": "integer" },
+        "balance": { "type": "string" },
+        "balanceRaw": { "type": "string" }
+      }
+    },
+
+    "AlertInfo": {
+      "type": "object",
+      "properties": {
+        "threshold": {
+          "type": ["string", "null"],
+          "description": "Absolute threshold (e.g., >0.01)"
+        },
+        "thresholdPct": {
+          "type": ["string", "null"],
+          "description": "Percentage threshold (e.g., >5)"
+        },
+        "triggered": {
+          "type": "boolean",
+          "description": "Whether alert condition was met"
+        },
+        "triggeredBy": {
+          "type": ["string", "null"],
+          "enum": ["absolute", "percentage", null]
+        }
+      },
+      "required": ["triggered"]
+    }
+  }
+}
+