@reefclaw/openclaw-plugin 0.1.12 → 0.1.14

package/ccxt/binance-public.d.ts

@@ -1,3 +1,4 @@
+import { type VenueReachabilityResult } from '@reefclaw/shared';
 import type { CcxtTicker, CcxtOHLCV } from '../types.js';
 import type { OrderBookDepth } from '../simulator/types.js';
 import type { PublicMarketDataApi } from './public-market-data-api.js';
@@ -18,17 +19,30 @@ export declare class BinancePublicApi implements PublicMarketDataApi {
     fetchOHLCV(symbol: string, timeframe?: string, limit?: number): Promise<CcxtOHLCV[] | null>;
     /** Probe Binance USD-M FUTURES reachability from this host — the readiness
      *  gate's core signal. Calls the futures-explicit implicit method so it hits
-     *  `fapi.binance.com` (a bare `fetchTime()` on this instance resolves to spot
-     *  `api.binance.com`, since the public client doesn't set defaultType:'future').
+     *  `fapi.binance.com` regardless of how the instance is configured. Keep it
+     *  explicit even though the client now sets `defaultType: 'future'`: this
+     *  probe must detect a futures-specific 451 geo-block, and it must not start
+     *  silently probing spot if that option is ever changed.
      *  HTTP 451 = Binance geo-restriction; the ban gate does NOT classify 451, so
      *  we inspect the message here. Ban-gate compliant (assertNotBanned/noteSuccess/
      *  noteBinanceError). Outcomes:
      *   - 'reachable'   clean response (driftMs = serverTime − localTime)
      *   - 'geo_blocked' HTTP 451 — host is in a restricted region (actionable)
      *   - 'unknown'     the ban/weight gate paused us — NOT a host problem
-     *   - 'unreachable' network / DNS / timeout / other error */
-    probeReachability(): Promise<{
-        outcome: 'reachable' | 'geo_blocked' | 'unreachable' | 'unknown';
-        driftMs: number | null;
-    }>;
+     *   - 'stalled'     THIS process was starved — we learned nothing (issue #265)
+     *   - 'unreachable' network / DNS / timeout / other error
+     *
+     *  ★ Self-stall detection: an error is evidence about BINANCE only if it
+     *  arrived on schedule. When the host starves the process the loop stops
+     *  running, ccxt's own timeout lands minutes late, and the old code blamed the
+     *  network — producing a confident "you are geo-blocked / check your firewall"
+     *  banner while the agent was in fact trading normally. Past
+     *  REACHABILITY_STALL_FACTOR× the request budget we report `stalled` and the
+     *  reporter renders it `unknown`. A 451 still wins: the server ANSWERED, so
+     *  that classification stands however late we noticed it. */
+    probeReachability(): Promise<VenueReachabilityResult>;
+    /** The request budget the stall yardstick is measured against. ccxt owns the
+     *  actual timeout, so read it from the instance rather than hardcoding a
+     *  second copy that could silently drift from it. */
+    private probeTimeoutMs;
 }

package/ccxt/binance-public.js

@@ -1,8 +1,39 @@
 // Thin wrapper around CCXT for Binance public API endpoints.
 // No API keys required — only uses public market data.
+//
+// ★ USD-M FUTURES, NOT SPOT. ReefClaw trades Binance USD-M perpetuals, so every
+// price this client serves must come from `fapi.binance.com`. `ccxt.binance` is
+// the combined spot+futures class and defaults to SPOT, so without an explicit
+// `defaultType: 'future'` the symbol-resolving reads (fetchTicker / fetchOHLCV /
+// fetchOrderBook) silently resolved to the spot market. That was wrong in two
+// ways at once:
+//   1. SILENT: every pair with a spot twin (BTC/USDT, ETH/USDT, …) returned
+//      SPOT prices on a perp product — charts, paper marks and paper fills all
+//      priced off the wrong book, diverging from the perp by the basis.
+//   2. LOUD: the 17 futures-ONLY contracts (1000FLOKI, 1000PEPE, 1000SHIB,
+//      1000BONK, 1000SATS, 1000RATS, 1000LUNC, 1000XEC, 1000CAT, …) have no
+//      spot market, so every fetch threw `binance does not have market symbol`.
+//      A user holding one got a dead feed: 100% ticker failure, marks frozen at
+//      entry, unrealized stuck at 0, and the frozen NAV then fed a phantom
+//      RED-zone drawdown -> auto-flatten. Observed on a live customer box
+//      2026-07-25 (1000FLOKI/USDT, 120/120 failed polls).
+// `fetchFundingRate` / `fetchOpenInterest` were always futures-correct (ccxt
+// routes them to fapi regardless) and `probeReachability` calls the futures
+// endpoint explicitly, so only the three symbol-resolving reads change.
+//
+// Weights are unchanged and already futures-calibrated in binance-ban-gate.ts
+// (ceiling 2000/2400 = the USD-M IP cap). Doc-verified against
+// https://developers.binance.com/docs/derivatives/usds-margined-futures/market-data/rest-api
+// (2026-07-25): host `fapi.binance.com`; /fapi/v1/ticker/24hr weight 1 for a
+// single symbol (gate charges 2), /fapi/v1/klines weight 1-10 by limit (gate
+// charges 2), /fapi/v1/depth weight 2-20 by limit (gate charges 5) — the gate
+// stays conservative on all three, so this never under-counts. It does mean the
+// calls now genuinely consume the futures budget the gate was already charging
+// them against (spot and futures have separate IP weight pools).
 import { createRequire } from 'node:module';
 import { logger } from '../logger.js';
 import { assertNotBanned, noteBinanceError, noteSuccess, BinanceBannedError } from './binance-ban-gate.js';
+import { REACHABILITY_STALL_FACTOR } from '@reefclaw/shared';
 const TAG = 'binance-public';
 // Load ccxt via CJS require — OpenClaw's ESM loader gives wrong module shape
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -26,8 +57,12 @@ export class BinancePublicApi {
         }
         this.exchange = new BinanceClass({
             enableRateLimit: true,
+            // ★ Load-bearing — see the file header. Without this ccxt.binance serves
+            // SPOT, which mispriced every perp read and hard-failed the futures-only
+            // 1000x contracts. Pinned by binance-public.test.ts.
+            options: { defaultType: 'future' },
         });
-        logger.info(TAG, 'Binance public API initialized (no auth)');
+        logger.info(TAG, 'Binance public API initialized (no auth, USD-M futures)');
     }
     /** Fetch raw CCXT ticker (includes funding rate, OI, info). Returns null on error. */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -146,16 +181,29 @@ export class BinancePublicApi {
     }
     /** Probe Binance USD-M FUTURES reachability from this host — the readiness
      *  gate's core signal. Calls the futures-explicit implicit method so it hits
-     *  `fapi.binance.com` (a bare `fetchTime()` on this instance resolves to spot
-     *  `api.binance.com`, since the public client doesn't set defaultType:'future').
+     *  `fapi.binance.com` regardless of how the instance is configured. Keep it
+     *  explicit even though the client now sets `defaultType: 'future'`: this
+     *  probe must detect a futures-specific 451 geo-block, and it must not start
+     *  silently probing spot if that option is ever changed.
      *  HTTP 451 = Binance geo-restriction; the ban gate does NOT classify 451, so
      *  we inspect the message here. Ban-gate compliant (assertNotBanned/noteSuccess/
      *  noteBinanceError). Outcomes:
      *   - 'reachable'   clean response (driftMs = serverTime − localTime)
      *   - 'geo_blocked' HTTP 451 — host is in a restricted region (actionable)
      *   - 'unknown'     the ban/weight gate paused us — NOT a host problem
-     *   - 'unreachable' network / DNS / timeout / other error */
+     *   - 'stalled'     THIS process was starved — we learned nothing (issue #265)
+     *   - 'unreachable' network / DNS / timeout / other error
+     *
+     *  ★ Self-stall detection: an error is evidence about BINANCE only if it
+     *  arrived on schedule. When the host starves the process the loop stops
+     *  running, ccxt's own timeout lands minutes late, and the old code blamed the
+     *  network — producing a confident "you are geo-blocked / check your firewall"
+     *  banner while the agent was in fact trading normally. Past
+     *  REACHABILITY_STALL_FACTOR× the request budget we report `stalled` and the
+     *  reporter renders it `unknown`. A 451 still wins: the server ANSWERED, so
+     *  that classification stands however late we noticed it. */
     async probeReachability() {
+        const startedAt = Date.now();
         try {
             assertNotBanned('reachabilityProbe');
             const r = await this.exchange.fapiPublicGetTime({});
@@ -173,8 +221,24 @@ export class BinancePublicApi {
             }
             const msg = err instanceof Error ? err.message : String(err);
             const geo = msg.includes('451');
-            logger.warn(TAG, `probeReachability failed${geo ? ' (HTTP 451 geo-block)' : ''}: ${msg}`);
-            return { outcome: geo ? 'geo_blocked' : 'unreachable', driftMs: null };
+            if (geo) {
+                logger.warn(TAG, `probeReachability failed (HTTP 451 geo-block): ${msg}`);
+                return { outcome: 'geo_blocked', driftMs: null };
+            }
+            const elapsedMs = Date.now() - startedAt;
+            if (elapsedMs > this.probeTimeoutMs() * REACHABILITY_STALL_FACTOR) {
+                logger.warn(TAG, `probeReachability inconclusive: this process was starved — a ${this.probeTimeoutMs()}ms probe took ${Math.round(elapsedMs / 1000)}s (${msg}). Reporting reachability as unknown, NOT as a Binance failure.`);
+                return { outcome: 'stalled', driftMs: null, stallMs: elapsedMs };
+            }
+            logger.warn(TAG, `probeReachability failed: ${msg}`);
+            return { outcome: 'unreachable', driftMs: null };
         }
     }
+    /** The request budget the stall yardstick is measured against. ccxt owns the
+     *  actual timeout, so read it from the instance rather than hardcoding a
+     *  second copy that could silently drift from it. */
+    probeTimeoutMs() {
+        const t = Number(this.exchange?.timeout);
+        return Number.isFinite(t) && t > 0 ? t : 10_000;
+    }
 }

package/config/operator-provenance.d.ts

@@ -0,0 +1,6 @@
+export interface ProvenanceVerdict {
+    ok: boolean;
+    /** Agent-legible refusal — returned verbatim as the tool error. */
+    error?: string;
+}
+export declare function verifyOperatorProvenance(provided: unknown, configPath?: string): ProvenanceVerdict;

package/config/operator-provenance.js

@@ -0,0 +1,50 @@
+// Operator-provenance gate for the state-mutating operator tools
+// (audit 2026-07-26 F12).
+//
+// "Operator-only. Never called by the agent." was PROSE in four tool
+// descriptions — nothing enforced it, and `acknowledged:true` is
+// caller-supplied, so a tool-capable agent could walk the PAPER→LIVE ladder,
+// clear the exchange credentials, or disable the stop-loss requirement with
+// one impulsive call. The dashboard path (browser → relay → skill bridge →
+// gateway) now proves provenance: the bridge injects the rc_* connection
+// token it already authenticates with, and the plugin compares it against
+// its own copy. The chat redaction guards keep rc_* tokens OUT of the
+// agent's context, so the agent cannot produce one conversationally.
+//
+// THREAT-MODEL HONESTY: the agent runs on the operator's own box and could
+// read plugin-config with exec tools — this gate defends against one-call
+// LLM impulsivity (the realistic failure mode), not a deliberately
+// adversarial agent, which owns the box and could edit the config directly.
+//
+// Fail direction: OPEN when no connection token is configured (a pure-local
+// dev box has no dashboard to inject provenance — same
+// infrastructure-absent ⇒ allow direction as the entitlement gate);
+// CLOSED on a missing or mismatched token when one IS configured.
+// Read per call (no restart needed after a token rotation — F10 philosophy).
+import { timingSafeEqual } from 'node:crypto';
+import { readPluginConfig } from './plugin-config-io.js';
+import { resolveIngestToken } from './user-data-stream-config.js';
+const REFUSAL = 'operator_only: this tool changes safety-critical operator settings and accepts requests ' +
+    'ONLY from the ReefClaw dashboard (operator provenance token missing or invalid). Do not ' +
+    'retry and do not attempt to obtain the token — if this change is wanted, the OPERATOR ' +
+    'makes it from the dashboard Settings panel.';
+export function verifyOperatorProvenance(provided, configPath) {
+    let expected;
+    try {
+        expected = resolveIngestToken(readPluginConfig(configPath))?.trim() || undefined;
+    }
+    catch {
+        expected = undefined;
+    }
+    if (!expected)
+        return { ok: true }; // unconfigured box — nothing to prove against
+    const given = typeof provided === 'string' ? provided.trim() : '';
+    if (given.length === 0)
+        return { ok: false, error: REFUSAL };
+    const a = Buffer.from(given, 'utf8');
+    const b = Buffer.from(expected, 'utf8');
+    if (a.length !== b.length || !timingSafeEqual(a, b)) {
+        return { ok: false, error: REFUSAL };
+    }
+    return { ok: true };
+}

package/config/plugin-config-io.d.ts

@@ -46,8 +46,12 @@ export interface PluginConfigFile {
     hl?: {
         marketSlippagePct?: number;
     };
+    /** MICRO_LIVE per-order notional cap in quote-USD (USDT on Binance, USDC on
+     *  Hyperliquid). Default 50 when the mode is MICRO_LIVE and no value is set.
+     *  `sizeCapPercent` used to be accepted here but was NEVER enforced by any
+     *  adapter (dead config implying protection it didn't provide) — it is no
+     *  longer read; loadMicroLiveConfig warns when it is present. */
     microLive?: {
-        sizeCapPercent?: number;
         maxPositionUSDT?: number;
     };
     /** Exchange-native bracket orders (STOP_MARKET + TAKE_PROFIT_MARKET).
@@ -202,6 +206,16 @@ export declare function defaultConfigPath(): string;
  *  the override to the default (same read-at-build-time pattern as
  *  loadBracketMode). */
 export declare function loadStopWatcherIntervalMs(path?: string): number | undefined;
+/** Best-effort read of the operator's micro-live notional cap
+ *  (`microLive.maxPositionUSDT`). Read at every adapter CONSTRUCTION — boot
+ *  AND runtime reconnects — so a mode flip or credential save can't silently
+ *  reset a raised OR lowered cap back to the $50 default (audit 2026-07-26
+ *  F8; same read-at-build-time pattern as loadBracketMode /
+ *  loadStopWatcherIntervalMs). Returns undefined when unset/garbage — the
+ *  adapters then apply their own MICRO_LIVE default. */
+export declare function loadMicroLiveConfig(path?: string): {
+    maxPositionUSDT?: number;
+} | undefined;
 /** Read the config file. Returns `{}` if the file doesn't exist.
  *  Throws if the file exists but is unreadable or not valid JSON — callers
  *  should treat that as an abort signal, not silently overwrite. */

package/config/plugin-config-io.js

@@ -8,6 +8,7 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
+import { logger } from '../logger.js';
 /** The connection the AGENT saves during onboarding lives in OpenClaw's own
  *  config (`skills.entries.reefclaw.config` in ~/.openclaw/openclaw.json) —
  *  the connector reads it there, and since the chat-install flow never writes
@@ -53,6 +54,29 @@ export function loadStopWatcherIntervalMs(path) {
     catch { /* best-effort — default applies */ }
     return undefined;
 }
+/** Best-effort read of the operator's micro-live notional cap
+ *  (`microLive.maxPositionUSDT`). Read at every adapter CONSTRUCTION — boot
+ *  AND runtime reconnects — so a mode flip or credential save can't silently
+ *  reset a raised OR lowered cap back to the $50 default (audit 2026-07-26
+ *  F8; same read-at-build-time pattern as loadBracketMode /
+ *  loadStopWatcherIntervalMs). Returns undefined when unset/garbage — the
+ *  adapters then apply their own MICRO_LIVE default. */
+export function loadMicroLiveConfig(path) {
+    try {
+        const ml = readPluginConfig(path).microLive;
+        if (!ml || typeof ml !== 'object')
+            return undefined;
+        if (ml.sizeCapPercent !== undefined) {
+            logger.warn('plugin-config', 'microLive.sizeCapPercent is set but has NEVER been enforced by any adapter — it has no effect. ' +
+                'Remove it; microLive.maxPositionUSDT is the enforced per-order notional cap.');
+        }
+        const cap = ml.maxPositionUSDT;
+        if (typeof cap === 'number' && Number.isFinite(cap) && cap > 0)
+            return { maxPositionUSDT: cap };
+    }
+    catch { /* best-effort — adapter default applies */ }
+    return undefined;
+}
 /** Read the config file. Returns `{}` if the file doesn't exist.
  *  Throws if the file exists but is unreadable or not valid JSON — callers
  *  should treat that as an abort signal, not silently overwrite. */