@blockrun/clawrouter 0.12.95 → 0.12.97

package/dist/balance.js

@@ -0,0 +1,157 @@
+/**
+ * Balance Monitor for ClawRouter
+ *
+ * Monitors USDC balance on Base network with intelligent caching.
+ * Provides pre-request balance checks to prevent failed payments.
+ *
+ * Caching Strategy:
+ *   - TTL: 30 seconds (balance is cached to avoid excessive RPC calls)
+ *   - Optimistic deduction: after successful payment, subtract estimated cost from cache
+ *   - Invalidation: on payment failure, immediately refresh from RPC
+ */
+import { createPublicClient, http, erc20Abi } from "viem";
+import { base } from "viem/chains";
+import { RpcError } from "./errors.js";
+/** USDC contract address on Base mainnet */
+const USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+/** Cache TTL in milliseconds (30 seconds) */
+const CACHE_TTL_MS = 30_000;
+/** Balance thresholds in USDC smallest unit (6 decimals) */
+export const BALANCE_THRESHOLDS = {
+    /** Low balance warning threshold: $1.00 */
+    LOW_BALANCE_MICROS: 1000000n,
+    /** Effectively zero threshold: $0.0001 (covers dust/rounding) */
+    ZERO_THRESHOLD: 100n,
+};
+/**
+ * Monitors USDC balance on Base network.
+ *
+ * Usage:
+ *   const monitor = new BalanceMonitor("0x...");
+ *   const info = await monitor.checkBalance();
+ *   if (info.isLow) console.warn("Low balance!");
+ */
+export class BalanceMonitor {
+    client;
+    walletAddress;
+    /** Cached balance (null = not yet fetched) */
+    cachedBalance = null;
+    /** Timestamp when cache was last updated */
+    cachedAt = 0;
+    constructor(walletAddress) {
+        this.walletAddress = walletAddress;
+        this.client = createPublicClient({
+            chain: base,
+            transport: http(undefined, {
+                timeout: 10_000, // 10 second timeout to prevent hanging on slow RPC
+            }),
+        });
+    }
+    /**
+     * Check current USDC balance.
+     * Uses cache if valid, otherwise fetches from RPC.
+     */
+    async checkBalance() {
+        const now = Date.now();
+        // Use cache only when balance is positive and still fresh.
+        // Zero balance is never cached — always re-fetch so a funded wallet is
+        // detected on the next request without waiting for cache expiry.
+        if (this.cachedBalance !== null &&
+            this.cachedBalance > 0n &&
+            now - this.cachedAt < CACHE_TTL_MS) {
+            return this.buildInfo(this.cachedBalance);
+        }
+        // Fetch from RPC
+        const balance = await this.fetchBalance();
+        if (balance > 0n) {
+            this.cachedBalance = balance;
+            this.cachedAt = now;
+        }
+        return this.buildInfo(balance);
+    }
+    /**
+     * Check if balance is sufficient for an estimated cost.
+     *
+     * @param estimatedCostMicros - Estimated cost in USDC smallest unit (6 decimals)
+     */
+    async checkSufficient(estimatedCostMicros) {
+        const info = await this.checkBalance();
+        if (info.balance >= estimatedCostMicros) {
+            return { sufficient: true, info };
+        }
+        const shortfall = estimatedCostMicros - info.balance;
+        return {
+            sufficient: false,
+            info,
+            shortfall: this.formatUSDC(shortfall),
+        };
+    }
+    /**
+     * Optimistically deduct estimated cost from cached balance.
+     * Call this after a successful payment to keep cache accurate.
+     *
+     * @param amountMicros - Amount to deduct in USDC smallest unit
+     */
+    deductEstimated(amountMicros) {
+        if (this.cachedBalance !== null && this.cachedBalance >= amountMicros) {
+            this.cachedBalance -= amountMicros;
+        }
+    }
+    /**
+     * Invalidate cache, forcing next checkBalance() to fetch from RPC.
+     * Call this after a payment failure to get accurate balance.
+     */
+    invalidate() {
+        this.cachedBalance = null;
+        this.cachedAt = 0;
+    }
+    /**
+     * Force refresh balance from RPC (ignores cache).
+     */
+    async refresh() {
+        this.invalidate();
+        return this.checkBalance();
+    }
+    /**
+     * Format USDC amount (in micros) as "$X.XX".
+     */
+    formatUSDC(amountMicros) {
+        // USDC has 6 decimals
+        const dollars = Number(amountMicros) / 1_000_000;
+        return `$${dollars.toFixed(2)}`;
+    }
+    /**
+     * Get the wallet address being monitored.
+     */
+    getWalletAddress() {
+        return this.walletAddress;
+    }
+    /** Fetch balance from RPC */
+    async fetchBalance() {
+        try {
+            const balance = await this.client.readContract({
+                address: USDC_BASE,
+                abi: erc20Abi,
+                functionName: "balanceOf",
+                args: [this.walletAddress],
+            });
+            return balance;
+        }
+        catch (error) {
+            // Throw typed error instead of silently returning 0
+            // This allows callers to distinguish "node down" from "wallet empty"
+            throw new RpcError(error instanceof Error ? error.message : "Unknown error", error);
+        }
+    }
+    /** Build BalanceInfo from raw balance */
+    buildInfo(balance) {
+        return {
+            balance,
+            balanceUSD: this.formatUSDC(balance),
+            isLow: balance < BALANCE_THRESHOLDS.LOW_BALANCE_MICROS,
+            isEmpty: balance < BALANCE_THRESHOLDS.ZERO_THRESHOLD,
+            walletAddress: this.walletAddress,
+        };
+    }
+}
+//# sourceMappingURL=balance.js.map

package/dist/balance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"balance.js","sourceRoot":"","sources":["../src/balance.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -1 +1,16 @@
 #!/usr/bin/env node
+/**
+ * ClawRouter CLI
+ *
+ * Standalone proxy for deployed setups where the proxy needs to survive gateway restarts.
+ *
+ * Usage:
+ *   npx @blockrun/clawrouter              # Start standalone proxy
+ *   npx @blockrun/clawrouter --version    # Show version
+ *   npx @blockrun/clawrouter --port 8402  # Custom port
+ *
+ * For production deployments, use with PM2:
+ *   pm2 start "npx @blockrun/clawrouter" --name clawrouter
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;GAYG"}