@blockrun/clawrouter 0.11.12 → 0.11.14

package/dist/index.d.ts

@@ -464,6 +464,48 @@ declare class BalanceMonitor {
     private buildInfo;
 }
 
+/**
+ * Solana USDC Balance Monitor
+ *
+ * Checks USDC balance on Solana mainnet with caching.
+ * Absorbed from @blockrun/clawwallet's solana-adapter.ts (balance portion only).
+ */
+type SolanaBalanceInfo = {
+    balance: bigint;
+    balanceUSD: string;
+    isLow: boolean;
+    isEmpty: boolean;
+    walletAddress: string;
+};
+/** Result from checkSufficient() */
+type SolanaSufficiencyResult = {
+    sufficient: boolean;
+    info: SolanaBalanceInfo;
+    shortfall?: string;
+};
+declare class SolanaBalanceMonitor {
+    private readonly rpc;
+    private readonly walletAddress;
+    private cachedBalance;
+    private cachedAt;
+    constructor(walletAddress: string, rpcUrl?: string);
+    checkBalance(): Promise<SolanaBalanceInfo>;
+    deductEstimated(amountMicros: bigint): void;
+    invalidate(): void;
+    refresh(): Promise<SolanaBalanceInfo>;
+    /**
+     * Check if balance is sufficient for an estimated cost.
+     */
+    checkSufficient(estimatedCostMicros: bigint): Promise<SolanaSufficiencyResult>;
+    /**
+     * Format USDC amount (in micros) as "$X.XX".
+     */
+    formatUSDC(amountMicros: bigint): string;
+    getWalletAddress(): string;
+    private fetchBalance;
+    private buildInfo;
+}
+
 /**
  * Session Persistence Store
  *
@@ -581,12 +623,13 @@ declare function hashRequestContent(lastUserContent: string, toolCallNames?: str
  *     before the x402 flow, preventing OpenClaw's 10-15s timeout from firing.
  *   - Response dedup: hashes request bodies and caches responses for 30s,
  *     preventing double-charging when OpenClaw retries after timeout.
- *   - Payment cache: after first 402, pre-signs subsequent requests to skip
- *     the 402 round trip (~200ms savings per request).
  *   - Smart routing: when model is "blockrun/auto", classify query and pick cheapest model.
  *   - Usage logging: log every request as JSON line to ~/.openclaw/blockrun/logs/
  */
 
+/** Union type for chain-agnostic balance monitoring */
+type AnyBalanceMonitor = BalanceMonitor | SolanaBalanceMonitor;
+
 /**
  * Get the proxy port from pre-loaded configuration.
  * Port is validated at module load time, this just returns the cached value.
@@ -603,9 +646,22 @@ type InsufficientFundsInfo = {
     requiredUSD: string;
     walletAddress: string;
 };
+/**
+ * Wallet config: either a plain EVM private key string, or the full
+ * resolution object from resolveOrGenerateWalletKey() which may include
+ * Solana keys. Using the full object prevents callers from accidentally
+ * forgetting to forward Solana key bytes.
+ */
+type WalletConfig = string | {
+    key: string;
+    solanaPrivateKeyBytes?: Uint8Array;
+};
+type PaymentChain = "base" | "solana";
 type ProxyOptions = {
-    walletKey: string;
+    wallet: WalletConfig;
     apiBase?: string;
+    /** Payment chain: "base" (default) or "solana". Can also be set via CLAWROUTER_PAYMENT_CHAIN env var. */
+    paymentChain?: PaymentChain;
     /** Port to listen on (default: 8402) */
     port?: number;
     routingConfig?: Partial<RoutingConfig>;
@@ -654,7 +710,8 @@ type ProxyHandle = {
     port: number;
     baseUrl: string;
     walletAddress: string;
-    balanceMonitor: BalanceMonitor;
+    solanaAddress?: string;
+    balanceMonitor: AnyBalanceMonitor;
     close: () => Promise<void>;
 };
 /**
@@ -667,6 +724,66 @@ type ProxyHandle = {
  */
 declare function startProxy(options: ProxyOptions): Promise<ProxyHandle>;
 
+/**
+ * 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
+ */
+
+/**
+ * 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.
+ */
+type WalletResolution = {
+    key: string;
+    address: string;
+    source: "saved" | "env" | "generated";
+    mnemonic?: string;
+    solanaPrivateKeyBytes?: Uint8Array;
+};
+/**
+ * Set up Solana wallet for existing EVM-only users.
+ * Generates a new mnemonic for Solana key derivation.
+ * NEVER touches the existing wallet.key file.
+ */
+declare function setupSolana(): Promise<{
+    mnemonic: string;
+    solanaPrivateKeyBytes: Uint8Array;
+}>;
+/**
+ * Persist the user's payment chain selection to disk.
+ */
+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.
+ */
+declare function loadPaymentChain(): Promise<"base" | "solana">;
+/**
+ * Resolve payment chain: env var first → persisted file second → default "base".
+ */
+declare function resolvePaymentChain(): Promise<"base" | "solana">;
+
 /**
  * BlockRun ProviderPlugin for OpenClaw
  *
@@ -817,68 +934,154 @@ declare class RequestDeduplicator {
 }
 
 /**
- * Payment Parameter Cache
+ * Spend Control - Time-windowed spending limits
  *
- * Caches the 402 payment parameters (payTo, asset, network, etc.) after the first
- * request to each endpoint. On subsequent requests, pre-signs the payment and
- * attaches it to the first request, skipping the 402 round trip (~200ms savings).
- */
-type CachedPaymentParams = {
-    payTo: string;
-    asset: string;
-    scheme: string;
-    network: string;
-    extra?: {
-        name?: string;
-        version?: string;
+ * Absorbed from @blockrun/clawwallet. Chain-agnostic (works for both EVM and Solana).
+ *
+ * Features:
+ * - Per-request limits (e.g., max $0.10 per call)
+ * - Hourly limits (e.g., max $3.00 per hour)
+ * - Daily limits (e.g., max $20.00 per day)
+ * - Session limits (e.g., max $5.00 per session)
+ * - Rolling windows (last 1h, last 24h)
+ * - Persistent storage (~/.openclaw/blockrun/spending.json)
+ */
+type SpendWindow = "perRequest" | "hourly" | "daily" | "session";
+interface SpendLimits {
+    perRequest?: number;
+    hourly?: number;
+    daily?: number;
+    session?: number;
+}
+interface SpendRecord {
+    timestamp: number;
+    amount: number;
+    model?: string;
+    action?: string;
+}
+interface SpendingStatus {
+    limits: SpendLimits;
+    spending: {
+        hourly: number;
+        daily: number;
+        session: number;
     };
-    maxTimeoutSeconds?: number;
-    resourceUrl?: string;
-    resourceDescription?: string;
-    cachedAt: number;
-};
-declare class PaymentCache {
-    private cache;
-    private ttlMs;
-    constructor(ttlMs?: number);
-    /** Get cached payment params for an endpoint path. */
-    get(endpointPath: string): CachedPaymentParams | undefined;
-    /** Cache payment params from a 402 response. */
-    set(endpointPath: string, params: Omit<CachedPaymentParams, "cachedAt">): void;
-    /** Invalidate cache for an endpoint (e.g., if payTo changed). */
-    invalidate(endpointPath: string): void;
+    remaining: {
+        hourly: number | null;
+        daily: number | null;
+        session: number | null;
+    };
+    calls: number;
+}
+interface CheckResult {
+    allowed: boolean;
+    blockedBy?: SpendWindow;
+    remaining?: number;
+    reason?: string;
+    resetIn?: number;
+}
+interface SpendControlStorage {
+    load(): {
+        limits: SpendLimits;
+        history: SpendRecord[];
+    } | null;
+    save(data: {
+        limits: SpendLimits;
+        history: SpendRecord[];
+    }): void;
+}
+declare class FileSpendControlStorage implements SpendControlStorage {
+    private readonly spendingFile;
+    constructor();
+    load(): {
+        limits: SpendLimits;
+        history: SpendRecord[];
+    } | null;
+    save(data: {
+        limits: SpendLimits;
+        history: SpendRecord[];
+    }): void;
+}
+declare class InMemorySpendControlStorage implements SpendControlStorage {
+    private data;
+    load(): {
+        limits: SpendLimits;
+        history: SpendRecord[];
+    } | null;
+    save(data: {
+        limits: SpendLimits;
+        history: SpendRecord[];
+    }): void;
+}
+interface SpendControlOptions {
+    storage?: SpendControlStorage;
+    now?: () => number;
 }
+declare class SpendControl {
+    private limits;
+    private history;
+    private sessionSpent;
+    private sessionCalls;
+    private readonly storage;
+    private readonly now;
+    constructor(options?: SpendControlOptions);
+    setLimit(window: SpendWindow, amount: number): void;
+    clearLimit(window: SpendWindow): void;
+    getLimits(): SpendLimits;
+    check(estimatedCost: number): CheckResult;
+    record(amount: number, metadata?: {
+        model?: string;
+        action?: string;
+    }): void;
+    private getSpendingInWindow;
+    getSpending(window: "hourly" | "daily" | "session"): number;
+    getRemaining(window: "hourly" | "daily" | "session"): number | null;
+    getStatus(): SpendingStatus;
+    getHistory(limit?: number): SpendRecord[];
+    resetSession(): void;
+    private cleanup;
+    private save;
+    private load;
+}
+declare function formatDuration(seconds: number): string;
 
 /**
- * x402 Payment Implementation
- *
- * Based on BlockRun's proven implementation.
- * Handles 402 Payment Required responses with EIP-712 signed USDC transfers.
+ * Wallet Key Derivation
  *
- * Optimizations (v0.3.0):
- *   - Payment cache: after first 402, caches {payTo, asset, network} per endpoint.
- *     On subsequent requests, pre-signs payment and sends with first request,
- *     skipping the 402 round trip (~200ms savings).
- *   - Falls back to normal 402 flow if pre-signed payment is rejected.
+ * BIP-39 mnemonic generation + BIP-44 HD key derivation for EVM and Solana.
+ * Absorbed from @blockrun/clawwallet. No file I/O here - auth.ts handles persistence.
  */
-
-/** Pre-auth parameters for skipping the 402 round trip. */
-type PreAuthParams = {
-    estimatedAmount: string;
-};
-/** Result from createPaymentFetch — includes the fetch wrapper and payment cache. */
-type PaymentFetchResult = {
-    fetch: (input: RequestInfo | URL, init?: RequestInit, preAuth?: PreAuthParams) => Promise<Response>;
-    cache: PaymentCache;
+interface DerivedKeys {
+    mnemonic: string;
+    evmPrivateKey: `0x${string}`;
+    evmAddress: string;
+    solanaPrivateKeyBytes: Uint8Array;
+}
+/**
+ * Generate a 24-word BIP-39 mnemonic.
+ */
+declare function generateWalletMnemonic(): string;
+/**
+ * Validate a BIP-39 mnemonic.
+ */
+declare function isValidMnemonic(mnemonic: string): boolean;
+/**
+ * Derive EVM private key and address from a BIP-39 mnemonic.
+ * Path: m/44'/60'/0'/0/0 (standard Ethereum derivation)
+ */
+declare function deriveEvmKey(mnemonic: string): {
+    privateKey: `0x${string}`;
+    address: string;
 };
 /**
- * Create a fetch wrapper that handles x402 payment automatically.
- *
- * Supports pre-auth: if cached payment params + estimated amount are available,
- * pre-signs and attaches payment to the first request, skipping the 402 round trip.
- * Falls back to normal 402 flow if pre-signed payment is rejected.
+ * Derive 32-byte Solana private key from a BIP-39 mnemonic.
+ * Path: m/44'/501'/0'/0' (standard Solana derivation)
+ */
+declare function deriveSolanaKeyBytes(mnemonic: string): Uint8Array;
+/**
+ * Derive both EVM and Solana keys from a single mnemonic.
  */
-declare function createPaymentFetch(privateKey: `0x${string}`): PaymentFetchResult;
+declare function deriveAllKeys(mnemonic: string): DerivedKeys;
 
 /**
  * Typed Error Classes for ClawRouter
@@ -1125,4 +1328,4 @@ declare function buildPartnerTools(proxyBaseUrl: string): PartnerToolDefinition[
 
 declare const plugin: OpenClawPluginDefinition;
 
-export { type AggregatedStats, BALANCE_THRESHOLDS, BLOCKRUN_MODELS, type BalanceInfo, BalanceMonitor, type CachedLLMResponse, type CachedPaymentParams, type CachedResponse, DEFAULT_RETRY_CONFIG, DEFAULT_ROUTING_CONFIG, DEFAULT_SESSION_CONFIG, type DailyStats, EmptyWalletError, InsufficientFundsError, type InsufficientFundsInfo, type LowBalanceInfo, MODEL_ALIASES, OPENCLAW_MODELS, PARTNER_SERVICES, type PartnerServiceDefinition, type PartnerToolDefinition, PaymentCache, type PaymentFetchResult, type PreAuthParams, type ProxyHandle, type ProxyOptions, RequestDeduplicator, ResponseCache, type ResponseCacheConfig, type RetryConfig, type RoutingConfig, type RoutingDecision, RpcError, type SessionConfig, type SessionEntry, SessionStore, type SufficiencyResult, type Tier, type UsageEntry, blockrunProvider, buildPartnerTools, buildProviderModels, calculateModelCost, createPaymentFetch, plugin as default, fetchWithRetry, formatStatsAscii, getAgenticModels, getFallbackChain, getFallbackChainFiltered, getModelContextWindow, getPartnerService, getProxyPort, getSessionId, getStats, hashRequestContent, isAgenticModel, isBalanceError, isEmptyWalletError, isInsufficientFundsError, isRetryable, isRpcError, logUsage, resolveModelAlias, route, startProxy };
+export { type AggregatedStats, BALANCE_THRESHOLDS, BLOCKRUN_MODELS, type BalanceInfo, BalanceMonitor, type CachedLLMResponse, type CachedResponse, type CheckResult, DEFAULT_RETRY_CONFIG, DEFAULT_ROUTING_CONFIG, DEFAULT_SESSION_CONFIG, type DailyStats, type DerivedKeys, EmptyWalletError, FileSpendControlStorage, InMemorySpendControlStorage, InsufficientFundsError, type InsufficientFundsInfo, type LowBalanceInfo, MODEL_ALIASES, OPENCLAW_MODELS, PARTNER_SERVICES, type PartnerServiceDefinition, type PartnerToolDefinition, type PaymentChain, type ProxyHandle, type ProxyOptions, RequestDeduplicator, ResponseCache, type ResponseCacheConfig, type RetryConfig, type RoutingConfig, type RoutingDecision, RpcError, type SessionConfig, type SessionEntry, SessionStore, type SolanaBalanceInfo, SolanaBalanceMonitor, SpendControl, type SpendControlOptions, type SpendControlStorage, type SpendLimits, type SpendRecord, type SpendWindow, type SpendingStatus, type SufficiencyResult, type Tier, type UsageEntry, type WalletConfig, type WalletResolution, blockrunProvider, buildPartnerTools, buildProviderModels, calculateModelCost, plugin as default, deriveAllKeys, deriveEvmKey, deriveSolanaKeyBytes, fetchWithRetry, formatDuration, formatStatsAscii, generateWalletMnemonic, getAgenticModels, getFallbackChain, getFallbackChainFiltered, getModelContextWindow, getPartnerService, getProxyPort, getSessionId, getStats, hashRequestContent, isAgenticModel, isBalanceError, isEmptyWalletError, isInsufficientFundsError, isRetryable, isRpcError, isValidMnemonic, loadPaymentChain, logUsage, resolveModelAlias, resolvePaymentChain, route, savePaymentChain, setupSolana, startProxy };