@reefclaw/connect 0.1.7 → 0.1.8

package/assets/shared/readiness.js

@@ -13,6 +13,15 @@ export const READINESS_CHECK_COPY = {
         phase: 'connect',
         fixHint: 'Your agent host is geo-blocked by Binance (HTTP 451). Run OpenClaw from a Binance-permitted region — most EU / several Asia VPS regions work.',
     },
+    // Dormant until the Hyperliquid venue ships (docs/HYPERLIQUID_INTEGRATION_PLAN.md
+    // Phase 1): the reporter probes only the CONFIGURED venue, so this id is never
+    // emitted while venue='binance'. Landed early so older webapps render it via the
+    // string-widened ReadinessCheck.id the moment a newer plugin starts sending it.
+    hyperliquid_reachable: {
+        label: 'Hyperliquid reachable',
+        phase: 'connect',
+        fixHint: 'Your agent host cannot reach the Hyperliquid API (api.hyperliquid.xyz). Check outbound HTTPS/DNS/firewall; if the host region is restricted, run OpenClaw from a permitted region.',
+    },
     clock_in_sync: {
         label: 'Host clock in sync',
         phase: 'connect',

package/assets/shared/venues/symbols.d.ts

@@ -0,0 +1,43 @@
+export type VenueId = 'binance' | 'hyperliquid';
+export declare const VENUE_IDS: readonly VenueId[];
+export declare function isVenueId(value: unknown): value is VenueId;
+/** Parse a raw config value into a venue.
+ *  Absent/empty → 'binance' (every pre-venue config file keeps today's
+ *  behavior byte-identically). An unrecognized string is surfaced to the
+ *  caller instead of being silently coerced — mis-spelling a venue must be
+ *  loud, never quietly become "trade on Binance". */
+export declare function parseVenue(raw: unknown): {
+    venue: VenueId;
+    unrecognized?: string;
+};
+/** `FillEvent.exchange` / webapp `trades.exchange` value — half of the
+ *  audit-trail idempotency key `(exchange, exchange_trade_id)` (migration
+ *  0042). 'binance_futures' is the historical literal on every existing row;
+ *  NEVER change these strings once a venue has written rows. */
+export declare const FILL_EXCHANGE_ID: Record<VenueId, string>;
+export declare function fillExchangeId(venue: VenueId): string;
+/** Quote/settle asset of the venue's linear perps. */
+export declare const VENUE_QUOTE_ASSET: Record<VenueId, string>;
+/** Prefix that namespaces Hyperliquid rows inside the intel symbol column. */
+export declare const HL_INTEL_PREFIX = "HL_";
+/** Canonical symbol → the venue's CCXT unified symbol.
+ *  'BTC/USDT' (binance) → 'BTC/USDT:USDT'; 'BTC/USDC' (hyperliquid) →
+ *  'BTC/USDC:USDC'. Accepts an already-suffixed input (idempotent). */
+export declare function toCcxtSymbol(venue: VenueId, canonical: string): string;
+/** Canonical symbol → intel DB symbol.
+ *  binance: 'BTC/USDT' → 'BTCUSDT' (the historical concatenated form intel has
+ *  always stored); hyperliquid: 'BTC/USDC' → 'HL_BTC' (namespaced coin, case
+ *  preserved). */
+export declare function toIntelSymbol(venue: VenueId, canonical: string): string;
+/** Inverse of toIntelSymbol. 'HL_'-prefixed → hyperliquid; everything else is
+ *  the historical Binance namespace. Binance symbols that are not
+ *  USDT-concatenated (none exist in INTEL_SYMBOLS today) come back verbatim as
+ *  canonical — honest passthrough, not a guess. */
+export declare function fromIntelSymbol(intelSymbol: string): {
+    venue: VenueId;
+    canonical: string;
+};
+/** The Hyperliquid venue-native coin name for a canonical symbol
+ *  ('BTC/USDC' → 'BTC'). Orders address assets by integer index resolved from
+ *  `meta.universe` at runtime — the coin name is the stable half. */
+export declare function toHyperliquidCoin(canonical: string): string;

package/assets/shared/venues/symbols.js

@@ -0,0 +1,123 @@
+// Venue identity + symbol-coordinate mapping for multi-venue support.
+//
+// Phase 0 of docs/HYPERLIQUID_INTEGRATION_PLAN.md (§5.3): the single source of
+// truth for how one market is named across the four coordinate systems —
+//
+//   layer                      binance              hyperliquid
+//   canonical (agent/webapp)   'BTC/USDT'           'BTC/USDC'
+//   CCXT unified               'BTC/USDT:USDT'      'BTC/USDC:USDC'
+//   venue-native               'BTCUSDT'            coin 'BTC' (asset index via meta)
+//   intel DB symbol            'BTCUSDT'            'HL_BTC'
+//
+// The intel namespace ('HL_' prefix) is deliberate: a distinct symbol string IS
+// venue isolation to the entire symbol-keyed intel read stack (context, cache
+// keys, conditions, facts, regime, API routes) with zero schema migration —
+// see the plan §5.3 for the trade-off vs an `exchange` column.
+//
+// Scattered `.replace('USDT', …)` conversions are the anti-pattern this module
+// replaces at NEW call sites (existing Binance sites migrate opportunistically,
+// never in the Phase 0 no-behavior-change window).
+//
+// Case rule: Hyperliquid coin names are case-sensitive ('kPEPE' = 1000 PEPE);
+// the intel symbol preserves the venue's exact casing after the 'HL_' prefix
+// ('HL_kPEPE') so round-trips are lossless. Never uppercase an HL coin.
+export const VENUE_IDS = ['binance', 'hyperliquid'];
+export function isVenueId(value) {
+    return value === 'binance' || value === 'hyperliquid';
+}
+/** Parse a raw config value into a venue.
+ *  Absent/empty → 'binance' (every pre-venue config file keeps today's
+ *  behavior byte-identically). An unrecognized string is surfaced to the
+ *  caller instead of being silently coerced — mis-spelling a venue must be
+ *  loud, never quietly become "trade on Binance". */
+export function parseVenue(raw) {
+    if (raw === undefined || raw === null || raw === '')
+        return { venue: 'binance' };
+    if (isVenueId(raw))
+        return { venue: raw };
+    return { venue: 'binance', unrecognized: String(raw) };
+}
+/** `FillEvent.exchange` / webapp `trades.exchange` value — half of the
+ *  audit-trail idempotency key `(exchange, exchange_trade_id)` (migration
+ *  0042). 'binance_futures' is the historical literal on every existing row;
+ *  NEVER change these strings once a venue has written rows. */
+export const FILL_EXCHANGE_ID = {
+    binance: 'binance_futures',
+    hyperliquid: 'hyperliquid',
+};
+export function fillExchangeId(venue) {
+    return FILL_EXCHANGE_ID[venue];
+}
+/** Quote/settle asset of the venue's linear perps. */
+export const VENUE_QUOTE_ASSET = {
+    binance: 'USDT',
+    hyperliquid: 'USDC',
+};
+/** Prefix that namespaces Hyperliquid rows inside the intel symbol column. */
+export const HL_INTEL_PREFIX = 'HL_';
+/** Strip a CCXT settle suffix ('BTC/USDT:USDT' → 'BTC/USDT'). Same regex as
+ *  webapp/src/lib/symbols.ts normalizeSymbol — kept inline so this module has
+ *  zero imports and survives the sync-copy deploy boundary. */
+function stripSettleSuffix(symbol) {
+    return symbol.replace(/:[A-Z]+$/, '');
+}
+function splitCanonical(canonical) {
+    const stripped = stripSettleSuffix(canonical.trim());
+    const parts = stripped.split('/');
+    if (parts.length !== 2 || parts[0].length === 0 || parts[1].length === 0) {
+        throw new Error(`Not a canonical BASE/QUOTE symbol: '${canonical}'`);
+    }
+    return { base: parts[0], quote: parts[1] };
+}
+/** Canonical symbol → the venue's CCXT unified symbol.
+ *  'BTC/USDT' (binance) → 'BTC/USDT:USDT'; 'BTC/USDC' (hyperliquid) →
+ *  'BTC/USDC:USDC'. Accepts an already-suffixed input (idempotent). */
+export function toCcxtSymbol(venue, canonical) {
+    const { base, quote } = splitCanonical(canonical);
+    if (quote !== VENUE_QUOTE_ASSET[venue]) {
+        throw new Error(`Symbol '${canonical}' is not ${VENUE_QUOTE_ASSET[venue]}-quoted — not a ${venue} linear perp`);
+    }
+    return `${base}/${quote}:${quote}`;
+}
+/** Canonical symbol → intel DB symbol.
+ *  binance: 'BTC/USDT' → 'BTCUSDT' (the historical concatenated form intel has
+ *  always stored); hyperliquid: 'BTC/USDC' → 'HL_BTC' (namespaced coin, case
+ *  preserved). */
+export function toIntelSymbol(venue, canonical) {
+    const { base, quote } = splitCanonical(canonical);
+    if (venue === 'hyperliquid') {
+        if (quote !== VENUE_QUOTE_ASSET.hyperliquid) {
+            throw new Error(`Symbol '${canonical}' is not USDC-quoted — not a Hyperliquid perp`);
+        }
+        return `${HL_INTEL_PREFIX}${base}`;
+    }
+    return `${base}${quote}`;
+}
+/** Inverse of toIntelSymbol. 'HL_'-prefixed → hyperliquid; everything else is
+ *  the historical Binance namespace. Binance symbols that are not
+ *  USDT-concatenated (none exist in INTEL_SYMBOLS today) come back verbatim as
+ *  canonical — honest passthrough, not a guess. */
+export function fromIntelSymbol(intelSymbol) {
+    if (intelSymbol.startsWith(HL_INTEL_PREFIX)) {
+        const coin = intelSymbol.slice(HL_INTEL_PREFIX.length);
+        if (coin.length === 0) {
+            throw new Error(`Malformed intel symbol '${intelSymbol}' — empty coin after HL_ prefix`);
+        }
+        return { venue: 'hyperliquid', canonical: `${coin}/${VENUE_QUOTE_ASSET.hyperliquid}` };
+    }
+    if (intelSymbol.endsWith(VENUE_QUOTE_ASSET.binance) && intelSymbol.length > 4) {
+        const base = intelSymbol.slice(0, -VENUE_QUOTE_ASSET.binance.length);
+        return { venue: 'binance', canonical: `${base}/${VENUE_QUOTE_ASSET.binance}` };
+    }
+    return { venue: 'binance', canonical: intelSymbol };
+}
+/** The Hyperliquid venue-native coin name for a canonical symbol
+ *  ('BTC/USDC' → 'BTC'). Orders address assets by integer index resolved from
+ *  `meta.universe` at runtime — the coin name is the stable half. */
+export function toHyperliquidCoin(canonical) {
+    const { base, quote } = splitCanonical(canonical);
+    if (quote !== VENUE_QUOTE_ASSET.hyperliquid) {
+        throw new Error(`Symbol '${canonical}' is not USDC-quoted — not a Hyperliquid perp`);
+    }
+    return base;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reefclaw/connect",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "One-command installer that connects your OpenClaw agent to ReefClaw (paper trading, no exchange keys).",
   "type": "module",
   "bin": {