@blockrun/clawrouter 0.12.94 → 0.12.96

package/dist/auth.d.ts

@@ -0,0 +1,82 @@
+/**
+ * BlockRun Auth Methods for OpenClaw
+ *
+ * Provides wallet-based authentication for the BlockRun provider.
+ * Operators configure their wallet private key, which is used to
+ * sign x402 micropayments for LLM inference.
+ *
+ * Three methods:
+ *   1. Auto-generate — create a new wallet on first run, save to ~/.openclaw/blockrun/wallet.key
+ *   2. Environment variable — read from BLOCKRUN_WALLET_KEY
+ *   3. Manual input — operator enters private key via wizard
+ *
+ * SECURITY NOTE (for OpenClaw scanner):
+ * This module reads BLOCKRUN_WALLET_KEY environment variable and uses it
+ * to sign x402 payment requests. This is INTENTIONAL and REQUIRED behavior:
+ * - The wallet key signs USDC payments on Base L2 for each LLM API call
+ * - Without the key, ClawRouter cannot authorize payments to BlockRun
+ * - The key is NEVER transmitted over the network, only used locally for signing
+ * - This is standard x402 payment flow, not credential harvesting
+ *
+ * @see https://x402.org - x402 payment protocol specification
+ * @see https://blockrun.ai/docs - BlockRun API documentation
+ * @openclaw-security env-access=BLOCKRUN_WALLET_KEY purpose=x402-payment-signing
+ */
+import type { ProviderAuthMethod } from "./types.js";
+declare const WALLET_FILE: string;
+declare const MNEMONIC_FILE: string;
+declare const CHAIN_FILE: string;
+export { WALLET_FILE, MNEMONIC_FILE, CHAIN_FILE };
+/**
+ * Resolve wallet key: load saved → env var → auto-generate.
+ * Also loads mnemonic if available for Solana key derivation.
+ * Called by index.ts before the auth wizard runs.
+ */
+export type WalletResolution = {
+    key: string;
+    address: string;
+    source: "saved" | "env" | "generated";
+    mnemonic?: string;
+    solanaPrivateKeyBytes?: Uint8Array;
+};
+export declare function resolveOrGenerateWalletKey(): Promise<WalletResolution>;
+/**
+ * Recover wallet.key from existing mnemonic.
+ *
+ * ONLY works when the mnemonic was originally generated by ClawRouter
+ * (i.e., both mnemonic and EVM key were derived from the same seed).
+ * If the EVM key was set independently (manually or via env), the derived
+ * key will be different — do NOT use this in that case.
+ */
+export declare function recoverWalletFromMnemonic(): Promise<void>;
+/**
+ * Set up Solana wallet for existing EVM-only users.
+ * Generates a new mnemonic for Solana key derivation.
+ * NEVER touches the existing wallet.key file.
+ */
+export declare function setupSolana(): Promise<{
+    mnemonic: string;
+    solanaPrivateKeyBytes: Uint8Array;
+}>;
+/**
+ * Persist the user's payment chain selection to disk.
+ */
+export declare function savePaymentChain(chain: "base" | "solana"): Promise<void>;
+/**
+ * Load the persisted payment chain selection from disk.
+ * Returns "base" if no file exists or the file is invalid.
+ */
+export declare function loadPaymentChain(): Promise<"base" | "solana">;
+/**
+ * Resolve payment chain: env var first → persisted file second → default "base".
+ */
+export declare function resolvePaymentChain(): Promise<"base" | "solana">;
+/**
+ * Auth method: operator enters their wallet private key directly.
+ */
+export declare const walletKeyAuth: ProviderAuthMethod;
+/**
+ * Auth method: read wallet key from BLOCKRUN_WALLET_KEY environment variable.
+ */
+export declare const envKeyAuth: ProviderAuthMethod;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAOH,OAAO,KAAK,EAAE,kBAAkB,EAA2C,MAAM,YAAY,CAAC;AAU9F,QAAA,MAAM,WAAW,QAAiC,CAAC;AACnD,QAAA,MAAM,aAAa,QAA+B,CAAC;AACnD,QAAA,MAAM,UAAU,QAAoC,CAAC;AAGrD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,UAAU,EAAE,CAAC;AAoKlD;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,GAAG,KAAK,GAAG,WAAW,CAAC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qBAAqB,CAAC,EAAE,UAAU,CAAC;CACpC,CAAC;AAEF,wBAAsB,0BAA0B,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAoD5E;AAED;;;;;;;GAOG;AACH,wBAAsB,yBAAyB,IAAI,OAAO,CAAC,IAAI,CAAC,CA0C/D;AAED;;;;GAIG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,qBAAqB,EAAE,UAAU,CAAC;CACnC,CAAC,CA2BD;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAG9E;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,MAAM,GAAG,QAAQ,CAAC,CAQnE;AAED;;GAEG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,MAAM,GAAG,QAAQ,CAAC,CAItE;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,kBAmC3B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,UAAU,EAAE,kBAyBxB,CAAC"}

package/dist/auth.js

@@ -0,0 +1,388 @@
+/**
+ * BlockRun Auth Methods for OpenClaw
+ *
+ * Provides wallet-based authentication for the BlockRun provider.
+ * Operators configure their wallet private key, which is used to
+ * sign x402 micropayments for LLM inference.
+ *
+ * Three methods:
+ *   1. Auto-generate — create a new wallet on first run, save to ~/.openclaw/blockrun/wallet.key
+ *   2. Environment variable — read from BLOCKRUN_WALLET_KEY
+ *   3. Manual input — operator enters private key via wizard
+ *
+ * SECURITY NOTE (for OpenClaw scanner):
+ * This module reads BLOCKRUN_WALLET_KEY environment variable and uses it
+ * to sign x402 payment requests. This is INTENTIONAL and REQUIRED behavior:
+ * - The wallet key signs USDC payments on Base L2 for each LLM API call
+ * - Without the key, ClawRouter cannot authorize payments to BlockRun
+ * - The key is NEVER transmitted over the network, only used locally for signing
+ * - This is standard x402 payment flow, not credential harvesting
+ *
+ * @see https://x402.org - x402 payment protocol specification
+ * @see https://blockrun.ai/docs - BlockRun API documentation
+ * @openclaw-security env-access=BLOCKRUN_WALLET_KEY purpose=x402-payment-signing
+ */
+import { writeFile, mkdir } from "node:fs/promises";
+import { readTextFile } from "./fs-read.js";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { privateKeyToAccount } from "viem/accounts";
+import { generateWalletMnemonic, isValidMnemonic, deriveSolanaKeyBytes, deriveAllKeys, getSolanaAddress, } from "./wallet.js";
+const WALLET_DIR = join(homedir(), ".openclaw", "blockrun");
+const WALLET_FILE = join(WALLET_DIR, "wallet.key");
+const MNEMONIC_FILE = join(WALLET_DIR, "mnemonic");
+const CHAIN_FILE = join(WALLET_DIR, "payment-chain");
+// Export for use by wallet command and index.ts
+export { WALLET_FILE, MNEMONIC_FILE, CHAIN_FILE };
+/**
+ * Try to load a previously auto-generated wallet key from disk.
+ */
+async function loadSavedWallet() {
+    try {
+        const key = (await readTextFile(WALLET_FILE)).trim();
+        if (key.startsWith("0x") && key.length === 66) {
+            console.log(`[ClawRouter] ✓ Loaded existing wallet from ${WALLET_FILE}`);
+            return key;
+        }
+        // File exists but content is wrong — do NOT silently fall through to generate a new wallet.
+        // This would silently replace a funded wallet with an empty one.
+        console.error(`[ClawRouter] ✗ CRITICAL: Wallet file exists but has invalid format!`);
+        console.error(`[ClawRouter]   File: ${WALLET_FILE}`);
+        console.error(`[ClawRouter]   Expected: 0x followed by 64 hex characters (66 chars total)`);
+        console.error(`[ClawRouter]   To fix: restore your backup key or set BLOCKRUN_WALLET_KEY env var`);
+        throw new Error(`Wallet file at ${WALLET_FILE} is corrupted or has wrong format. ` +
+            `Refusing to auto-generate new wallet to protect existing funds. ` +
+            `Restore your backup key or set BLOCKRUN_WALLET_KEY environment variable.`);
+    }
+    catch (err) {
+        // Re-throw corruption errors (not ENOENT)
+        if (err.code !== "ENOENT") {
+            // If it's our own thrown error, re-throw as-is
+            if (err instanceof Error && err.message.includes("Refusing to auto-generate")) {
+                throw err;
+            }
+            console.error(`[ClawRouter] ✗ Failed to read wallet file: ${err instanceof Error ? err.message : String(err)}`);
+            throw new Error(`Cannot read wallet file at ${WALLET_FILE}: ${err instanceof Error ? err.message : String(err)}. ` +
+                `Refusing to auto-generate new wallet to protect existing funds. ` +
+                `Fix file permissions or set BLOCKRUN_WALLET_KEY environment variable.`, { cause: err });
+        }
+    }
+    return undefined;
+}
+/**
+ * Load mnemonic from disk if it exists.
+ * Warns on corruption but never throws — callers handle missing mnemonic gracefully.
+ */
+async function loadMnemonic() {
+    try {
+        const mnemonic = (await readTextFile(MNEMONIC_FILE)).trim();
+        if (mnemonic && isValidMnemonic(mnemonic)) {
+            return mnemonic;
+        }
+        // File exists but content is invalid — warn but continue.
+        console.warn(`[ClawRouter] ⚠ Mnemonic file exists but has invalid format — ignoring`);
+        return undefined;
+    }
+    catch (err) {
+        // Only swallow ENOENT (file not found)
+        if (err.code !== "ENOENT") {
+            console.warn(`[ClawRouter] ⚠ Cannot read mnemonic file — ignoring`);
+        }
+    }
+    return undefined;
+}
+/**
+ * Save mnemonic to disk.
+ */
+async function saveMnemonic(mnemonic) {
+    await mkdir(WALLET_DIR, { recursive: true });
+    await writeFile(MNEMONIC_FILE, mnemonic + "\n", { mode: 0o600 });
+}
+/**
+ * Generate a new wallet with BIP-39 mnemonic, save to disk.
+ * New users get both EVM and Solana keys derived from the same mnemonic.
+ * CRITICAL: Verifies the file was actually written after generation.
+ */
+async function generateAndSaveWallet() {
+    // Safety: if a mnemonic file already exists, a Solana wallet was derived from it.
+    // Generating a new wallet would overwrite the mnemonic and lose Solana funds.
+    const existingMnemonic = await loadMnemonic();
+    if (existingMnemonic) {
+        throw new Error(`Mnemonic file exists at ${MNEMONIC_FILE} but wallet.key is missing.\n` +
+            `Refusing to generate a new wallet to protect existing funds.\n\n` +
+            `Restore your EVM private key using one of:\n` +
+            `  Windows:   set BLOCKRUN_WALLET_KEY=0x<your_key>\n` +
+            `  Mac/Linux: export BLOCKRUN_WALLET_KEY=0x<your_key>\n\n` +
+            `Then run: npx @blockrun/clawrouter`);
+    }
+    const mnemonic = generateWalletMnemonic();
+    const derived = deriveAllKeys(mnemonic);
+    // Create directory
+    await mkdir(WALLET_DIR, { recursive: true });
+    // Write wallet key file (EVM private key)
+    await writeFile(WALLET_FILE, derived.evmPrivateKey + "\n", { mode: 0o600 });
+    // Write mnemonic file
+    await writeFile(MNEMONIC_FILE, mnemonic + "\n", { mode: 0o600 });
+    // CRITICAL: Verify the file was actually written
+    try {
+        const verification = (await readTextFile(WALLET_FILE)).trim();
+        if (verification !== derived.evmPrivateKey) {
+            throw new Error("Wallet file verification failed - content mismatch");
+        }
+        console.log(`[ClawRouter] Wallet saved and verified at ${WALLET_FILE}`);
+    }
+    catch (err) {
+        throw new Error(`Failed to verify wallet file after creation: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+    // Derive Solana address for display
+    let solanaAddress;
+    try {
+        solanaAddress = await getSolanaAddress(derived.solanaPrivateKeyBytes);
+    }
+    catch {
+        // Non-fatal — Solana address display is best-effort
+    }
+    // Print prominent backup reminder after generating a new wallet
+    console.log(`[ClawRouter]`);
+    console.log(`[ClawRouter] ════════════════════════════════════════════════`);
+    console.log(`[ClawRouter]   NEW WALLET GENERATED — BACK UP YOUR KEY NOW`);
+    console.log(`[ClawRouter] ════════════════════════════════════════════════`);
+    console.log(`[ClawRouter]   EVM Address    : ${derived.evmAddress}`);
+    if (solanaAddress) {
+        console.log(`[ClawRouter]   Solana Address : ${solanaAddress}`);
+    }
+    console.log(`[ClawRouter]   Key file       : ${WALLET_FILE}`);
+    console.log(`[ClawRouter]   Mnemonic       : ${MNEMONIC_FILE}`);
+    console.log(`[ClawRouter]`);
+    console.log(`[ClawRouter]   Both EVM (Base) and Solana wallets are ready.`);
+    console.log(`[ClawRouter]   To back up, run in OpenClaw:`);
+    console.log(`[ClawRouter]     /wallet export`);
+    console.log(`[ClawRouter]`);
+    console.log(`[ClawRouter]   To restore on another machine:`);
+    console.log(`[ClawRouter]     export BLOCKRUN_WALLET_KEY=<your_key>`);
+    console.log(`[ClawRouter] ════════════════════════════════════════════════`);
+    console.log(`[ClawRouter]`);
+    return {
+        key: derived.evmPrivateKey,
+        address: derived.evmAddress,
+        mnemonic,
+        solanaPrivateKeyBytes: derived.solanaPrivateKeyBytes,
+    };
+}
+export async function resolveOrGenerateWalletKey() {
+    // 1. Previously saved wallet
+    const saved = await loadSavedWallet();
+    if (saved) {
+        const account = privateKeyToAccount(saved);
+        // Load mnemonic if it exists (Solana support enabled via /wallet solana)
+        const mnemonic = await loadMnemonic();
+        if (mnemonic) {
+            const solanaKeyBytes = deriveSolanaKeyBytes(mnemonic);
+            return {
+                key: saved,
+                address: account.address,
+                source: "saved",
+                mnemonic,
+                solanaPrivateKeyBytes: solanaKeyBytes,
+            };
+        }
+        return { key: saved, address: account.address, source: "saved" };
+    }
+    // 2. Environment variable
+    const envKey = process["env"].BLOCKRUN_WALLET_KEY;
+    if (typeof envKey === "string" && envKey.startsWith("0x") && envKey.length === 66) {
+        const account = privateKeyToAccount(envKey);
+        // Load mnemonic if it exists (Solana support enabled via /wallet solana)
+        const mnemonic = await loadMnemonic();
+        if (mnemonic) {
+            const solanaKeyBytes = deriveSolanaKeyBytes(mnemonic);
+            return {
+                key: envKey,
+                address: account.address,
+                source: "env",
+                mnemonic,
+                solanaPrivateKeyBytes: solanaKeyBytes,
+            };
+        }
+        return { key: envKey, address: account.address, source: "env" };
+    }
+    // 3. Auto-generate with BIP-39 mnemonic (new users get both chains)
+    const result = await generateAndSaveWallet();
+    return {
+        key: result.key,
+        address: result.address,
+        source: "generated",
+        mnemonic: result.mnemonic,
+        solanaPrivateKeyBytes: result.solanaPrivateKeyBytes,
+    };
+}
+/**
+ * Recover wallet.key from existing mnemonic.
+ *
+ * ONLY works when the mnemonic was originally generated by ClawRouter
+ * (i.e., both mnemonic and EVM key were derived from the same seed).
+ * If the EVM key was set independently (manually or via env), the derived
+ * key will be different — do NOT use this in that case.
+ */
+export async function recoverWalletFromMnemonic() {
+    const mnemonic = await loadMnemonic();
+    if (!mnemonic) {
+        console.error(`[ClawRouter] No mnemonic found at ${MNEMONIC_FILE}`);
+        console.error(`[ClawRouter] Cannot recover — no mnemonic to derive from.`);
+        process.exit(1);
+    }
+    // Safety: if wallet.key already exists, refuse to overwrite
+    const existing = await loadSavedWallet().catch(() => undefined);
+    if (existing) {
+        console.error(`[ClawRouter] wallet.key already exists at ${WALLET_FILE}`);
+        console.error(`[ClawRouter] Recovery not needed.`);
+        process.exit(1);
+    }
+    const derived = deriveAllKeys(mnemonic);
+    const solanaKeyBytes = deriveSolanaKeyBytes(mnemonic);
+    const solanaAddress = await getSolanaAddress(solanaKeyBytes).catch(() => undefined);
+    console.log(`[ClawRouter]`);
+    console.log(`[ClawRouter] ⚠  WALLET RECOVERY FROM MNEMONIC`);
+    console.log(`[ClawRouter] ════════════════════════════════════════════════`);
+    console.log(`[ClawRouter]   This only works if your mnemonic was originally`);
+    console.log(`[ClawRouter]   generated by ClawRouter (not set manually).`);
+    console.log(`[ClawRouter]`);
+    console.log(`[ClawRouter]   Derived EVM Address    : ${derived.evmAddress}`);
+    if (solanaAddress) {
+        console.log(`[ClawRouter]   Derived Solana Address : ${solanaAddress}`);
+    }
+    console.log(`[ClawRouter]`);
+    console.log(`[ClawRouter]   If the Solana address above matches your funded`);
+    console.log(`[ClawRouter]   wallet, recovery is safe to proceed.`);
+    console.log(`[ClawRouter] ════════════════════════════════════════════════`);
+    console.log(`[ClawRouter]`);
+    await mkdir(WALLET_DIR, { recursive: true });
+    await writeFile(WALLET_FILE, derived.evmPrivateKey + "\n", { mode: 0o600 });
+    console.log(`[ClawRouter] ✓ wallet.key restored at ${WALLET_FILE}`);
+    console.log(`[ClawRouter]   Run: npx @blockrun/clawrouter`);
+    console.log(`[ClawRouter]`);
+}
+/**
+ * Set up Solana wallet for existing EVM-only users.
+ * Generates a new mnemonic for Solana key derivation.
+ * NEVER touches the existing wallet.key file.
+ */
+export async function setupSolana() {
+    // Safety: mnemonic must not already exist
+    const existing = await loadMnemonic();
+    if (existing) {
+        throw new Error("Solana wallet already set up. Mnemonic file exists at " + MNEMONIC_FILE);
+    }
+    // Safety: wallet.key must exist (can't set up Solana without EVM wallet)
+    const savedKey = await loadSavedWallet();
+    if (!savedKey) {
+        throw new Error("No EVM wallet found. Run ClawRouter first to generate a wallet before setting up Solana.");
+    }
+    // Generate new mnemonic for Solana derivation
+    const mnemonic = generateWalletMnemonic();
+    const solanaKeyBytes = deriveSolanaKeyBytes(mnemonic);
+    // Save mnemonic (wallet.key untouched)
+    await saveMnemonic(mnemonic);
+    console.log(`[ClawRouter] Solana wallet set up successfully.`);
+    console.log(`[ClawRouter] Mnemonic saved to ${MNEMONIC_FILE}`);
+    console.log(`[ClawRouter] Existing EVM wallet unchanged.`);
+    return { mnemonic, solanaPrivateKeyBytes: solanaKeyBytes };
+}
+/**
+ * Persist the user's payment chain selection to disk.
+ */
+export async function savePaymentChain(chain) {
+    await mkdir(WALLET_DIR, { recursive: true });
+    await writeFile(CHAIN_FILE, chain + "\n", { mode: 0o600 });
+}
+/**
+ * Load the persisted payment chain selection from disk.
+ * Returns "base" if no file exists or the file is invalid.
+ */
+export async function loadPaymentChain() {
+    try {
+        const content = (await readTextFile(CHAIN_FILE)).trim();
+        if (content === "solana")
+            return "solana";
+        return "base";
+    }
+    catch {
+        return "base";
+    }
+}
+/**
+ * Resolve payment chain: env var first → persisted file second → default "base".
+ */
+export async function resolvePaymentChain() {
+    if (process["env"].CLAWROUTER_PAYMENT_CHAIN === "solana")
+        return "solana";
+    if (process["env"].CLAWROUTER_PAYMENT_CHAIN === "base")
+        return "base";
+    return loadPaymentChain();
+}
+/**
+ * Auth method: operator enters their wallet private key directly.
+ */
+export const walletKeyAuth = {
+    id: "wallet-key",
+    label: "Wallet Private Key",
+    hint: "Enter your EVM wallet private key (0x...) for x402 payments to BlockRun",
+    kind: "api_key",
+    run: async (ctx) => {
+        const key = await ctx.prompter.text({
+            message: "Enter your wallet private key (0x...)",
+            validate: (value) => {
+                const trimmed = value.trim();
+                if (!trimmed.startsWith("0x"))
+                    return "Key must start with 0x";
+                if (trimmed.length !== 66)
+                    return "Key must be 66 characters (0x + 64 hex)";
+                if (!/^0x[0-9a-fA-F]{64}$/.test(trimmed))
+                    return "Key must be valid hex";
+                return undefined;
+            },
+        });
+        if (!key || typeof key !== "string") {
+            throw new Error("Wallet key is required");
+        }
+        return {
+            profiles: [
+                {
+                    profileId: "default",
+                    credential: { apiKey: key.trim() },
+                },
+            ],
+            notes: [
+                "Wallet key stored securely in OpenClaw credentials.",
+                "Your wallet signs x402 USDC payments on Base for each LLM call.",
+                "Fund your wallet with USDC on Base to start using BlockRun models.",
+            ],
+        };
+    },
+};
+/**
+ * Auth method: read wallet key from BLOCKRUN_WALLET_KEY environment variable.
+ */
+export const envKeyAuth = {
+    id: "env-key",
+    label: "Environment Variable",
+    hint: "Use BLOCKRUN_WALLET_KEY environment variable",
+    kind: "api_key",
+    run: async () => {
+        const key = process["env"].BLOCKRUN_WALLET_KEY;
+        if (!key) {
+            throw new Error("BLOCKRUN_WALLET_KEY environment variable is not set. " +
+                "Set it to your EVM wallet private key (0x...).");
+        }
+        return {
+            profiles: [
+                {
+                    profileId: "default",
+                    credential: { apiKey: key.trim() },
+                },
+            ],
+            notes: ["Using wallet key from BLOCKRUN_WALLET_KEY environment variable."],
+        };
+    },
+};
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

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

package/dist/balance.d.ts

@@ -0,0 +1,97 @@
+/**
+ * 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
+ */
+/** Balance thresholds in USDC smallest unit (6 decimals) */
+export declare const BALANCE_THRESHOLDS: {
+    /** Low balance warning threshold: $1.00 */
+    readonly LOW_BALANCE_MICROS: 1000000n;
+    /** Effectively zero threshold: $0.0001 (covers dust/rounding) */
+    readonly ZERO_THRESHOLD: 100n;
+};
+/** Balance information returned by checkBalance() */
+export type BalanceInfo = {
+    /** Raw balance in USDC smallest unit (6 decimals) */
+    balance: bigint;
+    /** Formatted balance as "$X.XX" */
+    balanceUSD: string;
+    /** True if balance < $1.00 */
+    isLow: boolean;
+    /** True if balance < $0.0001 (effectively zero) */
+    isEmpty: boolean;
+    /** Wallet address for funding instructions */
+    walletAddress: string;
+};
+/** Result from checkSufficient() */
+export type SufficiencyResult = {
+    /** True if balance >= estimated cost */
+    sufficient: boolean;
+    /** Current balance info */
+    info: BalanceInfo;
+    /** If insufficient, the shortfall as "$X.XX" */
+    shortfall?: string;
+};
+/**
+ * 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 declare class BalanceMonitor {
+    private readonly client;
+    private readonly walletAddress;
+    /** Cached balance (null = not yet fetched) */
+    private cachedBalance;
+    /** Timestamp when cache was last updated */
+    private cachedAt;
+    constructor(walletAddress: string);
+    /**
+     * Check current USDC balance.
+     * Uses cache if valid, otherwise fetches from RPC.
+     */
+    checkBalance(): Promise<BalanceInfo>;
+    /**
+     * Check if balance is sufficient for an estimated cost.
+     *
+     * @param estimatedCostMicros - Estimated cost in USDC smallest unit (6 decimals)
+     */
+    checkSufficient(estimatedCostMicros: bigint): Promise<SufficiencyResult>;
+    /**
+     * 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: bigint): void;
+    /**
+     * Invalidate cache, forcing next checkBalance() to fetch from RPC.
+     * Call this after a payment failure to get accurate balance.
+     */
+    invalidate(): void;
+    /**
+     * Force refresh balance from RPC (ignores cache).
+     */
+    refresh(): Promise<BalanceInfo>;
+    /**
+     * Format USDC amount (in micros) as "$X.XX".
+     */
+    formatUSDC(amountMicros: bigint): string;
+    /**
+     * Get the wallet address being monitored.
+     */
+    getWalletAddress(): string;
+    /** Fetch balance from RPC */
+    private fetchBalance;
+    /** Build BalanceInfo from raw balance */
+    private buildInfo;
+}
+//# sourceMappingURL=balance.d.ts.map

package/dist/balance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"balance.d.ts","sourceRoot":"","sources":["../src/balance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAYH,4DAA4D;AAC5D,eAAO,MAAM,kBAAkB;IAC7B,2CAA2C;;IAE3C,iEAAiE;;CAEzD,CAAC;AAEX,qDAAqD;AACrD,MAAM,MAAM,WAAW,GAAG;IACxB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,mCAAmC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,mDAAmD;IACnD,OAAO,EAAE,OAAO,CAAC;IACjB,8CAA8C;IAC9C,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,oCAAoC;AACpC,MAAM,MAAM,iBAAiB,GAAG;IAC9B,wCAAwC;IACxC,UAAU,EAAE,OAAO,CAAC;IACpB,2BAA2B;IAC3B,IAAI,EAAE,WAAW,CAAC;IAClB,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;;;GAOG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAE9C,8CAA8C;IAC9C,OAAO,CAAC,aAAa,CAAuB;IAC5C,4CAA4C;IAC5C,OAAO,CAAC,QAAQ,CAAK;gBAET,aAAa,EAAE,MAAM;IAUjC;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,WAAW,CAAC;IAwB1C;;;;OAIG;IACG,eAAe,CAAC,mBAAmB,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAe9E;;;;;OAKG;IACH,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IAM3C;;;OAGG;IACH,UAAU,IAAI,IAAI;IAKlB;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC;IAKrC;;OAEG;IACH,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAMxC;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAI1B,6BAA6B;YACf,YAAY;IAgB1B,yCAAyC;IACzC,OAAO,CAAC,SAAS;CASlB"}