@reefclaw/openclaw-plugin 0.1.0

package/.gitignore

@@ -0,0 +1,8 @@
+# Assembled output — everything except the package sources is generated by
+# scripts/assemble.mjs from plugin/dist + skill/dist + the bootstrap skill.
+*
+!package.json
+!scripts/
+!scripts/**
+!README.md
+!.gitignore

package/audit/mode-transition-audit.d.ts

@@ -0,0 +1,11 @@
+import type { TradingMode } from '../types.js';
+export interface ModeTransitionAuditEntry {
+    ts: string;
+    previousMode: TradingMode;
+    targetMode: TradingMode;
+    acknowledged: boolean;
+    ok: boolean;
+    reason?: string;
+    testnet?: boolean;
+}
+export declare function recordModeTransition(entry: Omit<ModeTransitionAuditEntry, 'ts'>, pluginId?: string): void;

package/audit/mode-transition-audit.js

@@ -0,0 +1,29 @@
+// Mode-transition audit — append-only JSONL record of every set_trading_mode call.
+//
+// Written BEFORE the adapter swap (so even a crashed transition leaves a trail)
+// and updated with the outcome. Intended for post-incident review and regulatory
+// defence ("the operator acknowledged the LIVE transition at 2026-04-20T14:32:11Z").
+//
+// Path: ~/.openclaw/plugins/<pluginId>/mode-transitions.jsonl
+// Append-only; never truncated. One JSON object per line.
+import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { logger, formatError } from '../logger.js';
+import { resolvePluginsBaseDir } from '../util/plugin-paths.js';
+const TAG = 'mode-audit';
+function resolvePath(pluginId) {
+    const dir = join(resolvePluginsBaseDir(), pluginId ?? 'reefclaw-paper-trading');
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    return join(dir, 'mode-transitions.jsonl');
+}
+export function recordModeTransition(entry, pluginId) {
+    const full = { ts: new Date().toISOString(), ...entry };
+    try {
+        appendFileSync(resolvePath(pluginId), JSON.stringify(full) + '\n', 'utf8');
+        logger.info(TAG, `${full.previousMode} → ${full.targetMode} ok=${full.ok} ack=${full.acknowledged}`);
+    }
+    catch (err) {
+        logger.error(TAG, `Failed to write audit entry: ${formatError(err)}`);
+    }
+}

package/balance-utils.d.ts

@@ -0,0 +1,36 @@
+import type { CcxtBalance } from './types.js';
+/**
+ * Read the total quote-currency balance from a CCXT balance map.
+ *
+ * Uses the PRIMARY funded currency only — whichever of USDT/USDC has
+ * the larger balance. Summing both was incorrect because Binance
+ * cross-margin accounting reports position margin/value as a phantom
+ * balance in the settlement currency (e.g., opening an ATOM/USDT
+ * position with a USDC-funded account creates a USDT "balance" entry
+ * equal to the position's notional, inflating getQuoteBalance by the
+ * position value and causing the KPI to double-count).
+ *
+ * For wallet/equity/NAV reads on Binance Futures, prefer
+ * `getQuoteWalletBalance(balance)` — it handles BNFCR.
+ */
+export declare function getQuoteBalance(balanceMap: Record<string, number> | undefined): number;
+/**
+ * Read the effective wallet-equivalent quote balance from a Binance Futures
+ * fetchBalance response, including the BNFCR realized-PnL accumulator.
+ *
+ * Why this exists: Binance multi-asset accounts settle realized PnL into
+ * BNFCR (negative when net-loss, positive when net-gain). CCXT's `total`
+ * map carries `marginBalance` (= walletBalance + uPnl), so the BNFCR line
+ * mixes uPnl into the total, which double-counts when the caller adds
+ * position uPnl on top. This helper reads `info.assets[i].walletBalance`
+ * directly, which excludes uPnl by construction.
+ *
+ * Returns max(USDT_wallet, USDC_wallet) + BNFCR_wallet. BNFCR is added
+ * (not max'd) because it is independent of the funded stablecoin — a
+ * USDC-funded account with cumulative losses shows USDC unchanged plus
+ * BNFCR negative; the user's true wallet is the sum.
+ *
+ * Falls back to `getQuoteBalance(balance.total)` when `info.assets` is
+ * absent (mock balances in unit tests, non-Binance exchanges).
+ */
+export declare function getQuoteWalletBalance(balance: CcxtBalance | null | undefined): number;

package/balance-utils.js

@@ -0,0 +1,98 @@
+// Utility for reading quote-currency balance from CCXT balance objects.
+// Binance USDⓈ-M Futures settles in USDT or USDC — accounts may hold either or both.
+// On multi-asset accounts a third asset, BNFCR, accumulates realized PnL as a
+// signed wallet line (negative = cumulative loss, positive = cumulative gain).
+/**
+ * Read the total quote-currency balance from a CCXT balance map.
+ *
+ * Uses the PRIMARY funded currency only — whichever of USDT/USDC has
+ * the larger balance. Summing both was incorrect because Binance
+ * cross-margin accounting reports position margin/value as a phantom
+ * balance in the settlement currency (e.g., opening an ATOM/USDT
+ * position with a USDC-funded account creates a USDT "balance" entry
+ * equal to the position's notional, inflating getQuoteBalance by the
+ * position value and causing the KPI to double-count).
+ *
+ * For wallet/equity/NAV reads on Binance Futures, prefer
+ * `getQuoteWalletBalance(balance)` — it handles BNFCR.
+ */
+export function getQuoteBalance(balanceMap) {
+    if (!balanceMap)
+        return 0;
+    const usdt = balanceMap.USDT ?? 0;
+    const usdc = balanceMap.USDC ?? 0;
+    // Use whichever currency has the larger wallet balance (the funded one).
+    // If both are zero, return 0. If both are funded, use the larger.
+    return Math.max(usdt, usdc);
+}
+/**
+ * Read the effective wallet-equivalent quote balance from a Binance Futures
+ * fetchBalance response, including the BNFCR realized-PnL accumulator.
+ *
+ * Why this exists: Binance multi-asset accounts settle realized PnL into
+ * BNFCR (negative when net-loss, positive when net-gain). CCXT's `total`
+ * map carries `marginBalance` (= walletBalance + uPnl), so the BNFCR line
+ * mixes uPnl into the total, which double-counts when the caller adds
+ * position uPnl on top. This helper reads `info.assets[i].walletBalance`
+ * directly, which excludes uPnl by construction.
+ *
+ * Returns max(USDT_wallet, USDC_wallet) + BNFCR_wallet. BNFCR is added
+ * (not max'd) because it is independent of the funded stablecoin — a
+ * USDC-funded account with cumulative losses shows USDC unchanged plus
+ * BNFCR negative; the user's true wallet is the sum.
+ *
+ * Falls back to `getQuoteBalance(balance.total)` when `info.assets` is
+ * absent (mock balances in unit tests, non-Binance exchanges).
+ */
+export function getQuoteWalletBalance(balance) {
+    if (!balance)
+        return 0;
+    // Prefer Binance's own account-level wallet aggregate when present.
+    // `/fapi/v3/account` (CCXT passes it through verbatim at `info`) returns
+    // `totalWalletBalance` — in Multi-Assets Mode this is the USD-denominated
+    // sum across all margin assets, with each non-USD collateral valued at
+    // Binance's live index price (verified against developers.binance.com →
+    // Account Information V3, 2026-05-16). It also excludes uPnL by
+    // construction (marginBalance = walletBalance + uPnL), matching this
+    // function's "wallet, uPnL added by caller" contract.
+    //
+    // Why this beats the per-asset reconstruction below: summing
+    // `max(USDT,USDC) + BNFCR` values USDC at FACE 1.0000, but Binance values
+    // USDC collateral at the live USDC/USD index (~0.9998). That made the
+    // dashboard wallet permanently ~$0.2 high vs the Binance app on this
+    // account (always-on, same-sign, slowly varying with the USDC peg —
+    // 2026-05-16 "figures slightly off always"). totalWalletBalance is the
+    // exact number the app's Futures "Wallet Balance" shows. The read path is
+    // already REST (`LiveAdapter.getBalance` → `fetchBalance()` every poll),
+    // so this is zero freshness regression — same cadence, correct value.
+    const info = balance?.info;
+    if (info && info.totalWalletBalance != null) {
+        const twb = parseFloat(String(info.totalWalletBalance));
+        if (Number.isFinite(twb))
+            return twb;
+    }
+    // Fallback (no Binance aggregate — non-Binance exchange, mock balances in
+    // unit tests, or a WS-store-derived balance object): the legacy
+    // face-value per-asset reconstruction. Carries the documented ~USDC-index
+    // drift but is the best available when the aggregate is absent.
+    const assets = balance?.info?.assets;
+    if (!Array.isArray(assets))
+        return getQuoteBalance(balance.total);
+    let usdt = 0;
+    let usdc = 0;
+    let bnfcr = 0;
+    for (const a of assets) {
+        if (!a || typeof a.asset !== 'string')
+            continue;
+        const wb = parseFloat(String(a.walletBalance ?? 0));
+        if (!Number.isFinite(wb))
+            continue;
+        if (a.asset === 'USDT')
+            usdt = wb;
+        else if (a.asset === 'USDC')
+            usdc = wb;
+        else if (a.asset === 'BNFCR')
+            bnfcr = wb;
+    }
+    return Math.max(usdt, usdc) + bnfcr;
+}

package/bridge/bridge.d.ts

@@ -0,0 +1,109 @@
+import type { OpenClawProvider } from './provider.js';
+import type { ConnectorConfig } from './types.js';
+export declare class Bridge {
+    private readonly provider;
+    private connector;
+    private readonly seqs;
+    private throttleBuffer;
+    private throttleTimer;
+    /**
+     * Bounded ring buffer of every frame this bridge has emitted to the relay.
+     * On a `reconcile` request the bridge populates `snapshot.gapFill` with
+     * everything the browser hasn't seen yet (per-channel `seq > lastSeq`).
+     * Defaults: 500 events × 4 channels × 5 min age cap. See
+     * event-replay-buffer.ts for the rationale.
+     */
+    private readonly replayBuffer;
+    /** Current local SKILL.md version (from frontmatter) */
+    private currentSkillVersion;
+    /** Last trading mode observed from either a tradingMode event or a
+     *  successful set_trading_mode outcome. Used by the skill-side ladder
+     *  check so the dashboard can be rejected quickly without a plugin
+     *  round-trip. `null` means "unknown yet" — the plugin is the authority. */
+    private lastKnownTradingMode;
+    private readonly listeners;
+    /** rc_ connection token — also authenticates the webapp skill-content pull */
+    private readonly connectionToken;
+    constructor(provider: OpenClawProvider, connectorConfig: ConnectorConfig);
+    /** Start the bridge: connect to relay + start provider */
+    start(): void;
+    /** Stop the bridge: disconnect + stop provider */
+    stop(): void;
+    private wireProviderEvents;
+    private addListener;
+    private unwireProviderEvents;
+    private emit;
+    /** Send a frame to the relay AND record it in the replay buffer.
+     *
+     *  Both writes happen unconditionally:
+     *    - replayBuffer.record() is the canonical wire-history; gapFill draws
+     *      from it on the next reconcile, even if this frame's wire send was
+     *      a no-op because the connector was disconnected.
+     *    - connector.sendEvent() internally checks readyState and silently
+     *      no-ops when the socket is closed (connector.ts:164), so calling it
+     *      during a disconnect is safe and we don't have to mirror the gate
+     *      here. */
+    private sendFrame;
+    /** Flush all buffered low-priority events (latest value per type).
+     *
+     *  Drains through sendFrame regardless of connector state — the replay
+     *  buffer is the authoritative record and must capture coalesced events
+     *  even when the link is down. The wire send inside sendFrame is a no-op
+     *  until the connector reconnects, at which point new events flow live and
+     *  the offline coalesced ones are available via gapFill on reconcile. */
+    private flushThrottleBuffer;
+    private startThrottleTimer;
+    private stopThrottleTimer;
+    private handleRequest;
+    private handleStateChange;
+    /** Today every authenticated session carries operator.write via the
+     *  relay-level Clerk token. This method exists as the enforcement seam —
+     *  a future PR can drop per-session roles in here without restructuring
+     *  the dispatcher. Returning true keeps current behavior identical. */
+    private hasOperatorWriteScope;
+    /** Handle a set_trading_mode request. Returns 'responded' if the handler
+     *  already wrote the response frame (e.g. on validation failure), otherwise
+     *  returns the structured outcome for the caller to wrap in a success
+     *  frame. Ladder validation runs here for fast dashboard feedback and
+     *  again in the plugin (defense in depth). */
+    private handleSetTradingMode;
+    /** Handle a set_exchange_credentials request. The secret value passes
+     *  through once and is never cached or logged; only a redacted fingerprint
+     *  appears in the audit trail. */
+    private handleSetExchangeCredentials;
+    /** Handle a test_exchange_credentials request — transient read-only
+     *  verification, nothing persisted. Same input validation + secret
+     *  redaction rules as set_exchange_credentials. */
+    private handleTestExchangeCredentials;
+    /** Handle a clear_exchange_credentials request. No input — the method
+     *  itself is the "yes I want this" signal; the webapp is expected to
+     *  gate this behind a confirmation dialog before calling. */
+    private handleClearExchangeCredentials;
+    /** Apply a SKILL.md update: verify signature (C1), write to workspace +
+     *  installed skill dir, clear session cache, notify agent. */
+    private applySkillUpdate;
+    /**
+     * Fetch the stored SKILL.md envelope from the relay's Durable-Object store
+     * and apply it. The DO store is writable exclusively through the
+     * ADMIN_SECRET-gated HTTP push (party.ts handleSkillPush) — pulling makes
+     * the STORE, not any WS frame, the trust anchor for OTA content. Refuses to
+     * downgrade below the local version (a stale relay copy must never clobber
+     * a newer local SKILL.md — prod incident 2026-05-13); an equal version
+     * re-applies (idempotent repair for a re-push). Returns null when the relay
+     * has nothing stored; throws on transport error.
+     */
+    private pullAndApplySkillUpdate;
+    /**
+     * Pull the full SKILL.md from the webapp's authenticated endpoint and apply
+     * it when newer than local. This is how a FRESH install upgrades from the
+     * bundled bootstrap (v0.0.x) to the real trading instructions — the relay's
+     * per-room Durable-Object store is empty for a new user, so the relay push
+     * channel alone can never deliver the first full copy. Token-gated: no valid
+     * rc_ token → 401 → no content (the full SKILL.md never ships unauthenticated).
+     * Same downgrade guard + applySkillUpdate pipeline (incl. the C1 signature
+     * gate when enforced) as the relay pull path.
+     */
+    private pullSkillContentFromWebapp;
+    /** Check relay's latest SKILL.md version against local and auto-update if stale */
+    private handleConnectAck;
+}