@reefclaw/openclaw-plugin 0.1.20 → 0.1.22

package/types.d.ts

@@ -111,24 +111,29 @@ export declare const DEFAULT_CONFIG: PluginConfig;
  *  `exchange` block (openclaw.json legacy fallback). Which fields matter
  *  depends on `venue` (docs/HYPERLIQUID_INTEGRATION_PLAN.md §5.2):
  *
- *    binance (default, and the only live-supported venue until Phase 3) —
- *      apiKey + secret (HMAC pair) are required; walletAddress/agentPrivateKey
- *      are ignored.
+ *    binance (default) — apiKey + secret (HMAC pair) are required;
+ *      walletAddress/agentPrivateKey are ignored.
  *    hyperliquid — walletAddress (MASTER wallet address, 0x…, used for
  *      queries; never its private key) + agentPrivateKey (an approved
  *      agent/API wallet's key — signs orders, cannot withdraw). apiKey/secret
- *      are meaningless. Boot falls back to PAPER for this venue until the
- *      Phase 3 adapter ships.
+ *      are absent — an HL block never carries a Binance HMAC pair.
  *
- *  apiKey/secret stay required at the type level because every constructed
- *  instance today feeds BinancePrivateApi; the on-disk JSON is parsed, not
- *  type-constructed, so an HL block without them is readable. Phase 3
- *  restructures this into a per-venue discriminated union. */
+ *  apiKey/secret are optional at the type level because the on-disk shape is
+ *  per-venue: every Binance consumer (index.ts boot, set_trading_mode,
+ *  set_exchange_credentials) truthiness-guards the pair before constructing a
+ *  BinancePrivateApi, so an HL block without them is both readable AND
+ *  writable. */
 export interface ExchangeConfig {
     venue?: 'binance' | 'hyperliquid';
-    apiKey: string;
-    secret: string;
+    apiKey?: string;
+    secret?: string;
     testnet?: boolean;
     walletAddress?: string;
     agentPrivateKey?: string;
+    /** Per-venue testnet memo. `testnet` above is the ACTIVE venue's flag (what
+     *  boot reads); this remembers the OTHER venue's setting so switching back
+     *  restores it instead of inheriting the flag from whichever venue was
+     *  configured last. Traders run both venues and switch between them — a
+     *  switch must never lose a configured setting. */
+    testnetByVenue?: Partial<Record<'binance' | 'hyperliquid', boolean>>;
 }

package/venues/hyperliquid/hl-agent-wallet.d.ts

@@ -0,0 +1,29 @@
+/** Generate a fresh secp256k1 private key (0x-prefixed, 64 hex chars) from
+ *  CSPRNG bytes, rejection-sampled into the valid scalar range. This is how
+ *  the box mints its own HL agent wallet — the key is BORN here and never
+ *  leaves the machine (the caller persists it to plugin-config and surfaces
+ *  only the derived PUBLIC address). */
+export declare function generateAgentPrivateKey(): string;
+/** Master/agent wallet address: 0x + 40 hex chars. */
+export declare function isHexAddress(value: unknown): value is string;
+/** Agent private key: 32 bytes of hex, 0x prefix optional (the HL app shows it
+ *  with the prefix; some wallets export without). */
+export declare function isHexPrivateKey(value: unknown): value is string;
+/** Canonical stored form: trimmed, 0x-prefixed, original casing preserved. */
+export declare function normalizeHexPrivateKey(value: string): string;
+export type DeriveAddressResult = {
+    ok: true;
+    address: string;
+} | {
+    ok: false;
+    reason: 'invalid_key' | 'unavailable';
+};
+/** Test seam: reset the memoized keccak loader (unit tests only). */
+export declare function __resetKeccakCacheForTests(): void;
+/** Derive the Ethereum address a private key controls (lowercase 0x…40 hex).
+ *  'invalid_key' = the key is malformed or outside the secp256k1 range;
+ *  'unavailable' = the keccak dependency could not be loaded (callers must
+ *  fail OPEN — skip the check, never block credential entry on infra). */
+export declare function deriveAddressFromPrivateKey(privateKey: string): Promise<DeriveAddressResult>;
+/** Case-insensitive address equality (addresses may arrive checksummed). */
+export declare function sameAddress(a: string, b: string): boolean;

package/venues/hyperliquid/hl-agent-wallet.js

@@ -0,0 +1,118 @@
+// Hyperliquid agent-wallet helpers — format validation + address derivation.
+//
+// Why derivation exists at all: the single most catastrophic mistake a
+// non-technical trader can make in the HL onboarding form is pasting their
+// MASTER wallet's private key where the AGENT key belongs (the master key can
+// withdraw everything; the agent key can only trade). The form cannot tell the
+// two apart — both are 32-byte hex — but the box can: derive the address from
+// the pasted key and refuse when it equals the master walletAddress. The same
+// derived address also lets test_exchange_credentials verify the agent is
+// actually APPROVED for the master account (POST /info extraAgents) before the
+// user goes live.
+//
+// Derivation = secp256k1 pubkey (node:crypto createECDH — stable Node API) +
+// keccak-256 of the 64-byte public key, last 20 bytes (the Ethereum address
+// rule). Node has no keccak (its sha3-256 is NIST-padded, a different hash),
+// so keccak_256 comes from ccxt's vendored noble-hashes — ccxt is pinned at
+// 4.5.37 and the deep path is guarded by a known-vector unit test
+// (hl-agent-wallet.test.ts), so a ccxt bump that moves the file fails loudly.
+// If the import ever breaks at runtime we degrade gracefully: derivation
+// reports 'unavailable' and callers skip the address checks rather than
+// blocking credential entry.
+//
+// SECURITY: this module handles the raw agent private key in memory only —
+// it never logs it, never persists it, and never puts it in a return value.
+import { createECDH, randomBytes } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import path from 'node:path';
+/** secp256k1 group order n — a private key must be in [1, n-1]. */
+const SECP256K1_ORDER = BigInt('0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141');
+/** Generate a fresh secp256k1 private key (0x-prefixed, 64 hex chars) from
+ *  CSPRNG bytes, rejection-sampled into the valid scalar range. This is how
+ *  the box mints its own HL agent wallet — the key is BORN here and never
+ *  leaves the machine (the caller persists it to plugin-config and surfaces
+ *  only the derived PUBLIC address). */
+export function generateAgentPrivateKey() {
+    // Rejection probability per draw is ~2^-128 (order ≈ 2^256) — the loop is
+    // for correctness, not because retries are expected.
+    for (;;) {
+        const candidate = randomBytes(32);
+        const scalar = BigInt(`0x${candidate.toString('hex')}`);
+        if (scalar > 0n && scalar < SECP256K1_ORDER) {
+            return `0x${candidate.toString('hex')}`;
+        }
+    }
+}
+/** Master/agent wallet address: 0x + 40 hex chars. */
+export function isHexAddress(value) {
+    return typeof value === 'string' && /^0x[0-9a-fA-F]{40}$/.test(value.trim());
+}
+/** Agent private key: 32 bytes of hex, 0x prefix optional (the HL app shows it
+ *  with the prefix; some wallets export without). */
+export function isHexPrivateKey(value) {
+    return typeof value === 'string' && /^(0x)?[0-9a-fA-F]{64}$/.test(value.trim());
+}
+/** Canonical stored form: trimmed, 0x-prefixed, original casing preserved. */
+export function normalizeHexPrivateKey(value) {
+    const trimmed = value.trim();
+    return trimmed.startsWith('0x') || trimmed.startsWith('0X') ? `0x${trimmed.slice(2)}` : `0x${trimmed}`;
+}
+let keccakPromise = null;
+/** Load keccak_256 from ccxt's vendored noble-hashes. The package's `exports`
+ *  map only exposes ".", so we resolve the package root from the main entry and
+ *  import the file by path (file URLs bypass the exports map). Returns null on
+ *  any failure — derivation then reports 'unavailable'. */
+function loadKeccak() {
+    if (!keccakPromise) {
+        keccakPromise = (async () => {
+            try {
+                const req = createRequire(import.meta.url);
+                const entry = req.resolve('ccxt');
+                const marker = `${path.sep}ccxt${path.sep}`;
+                const idx = entry.lastIndexOf(marker);
+                if (idx === -1)
+                    return null;
+                const root = entry.slice(0, idx + marker.length - 1);
+                const sha3 = path.join(root, 'js', 'src', 'static_dependencies', 'noble-hashes', 'sha3.js');
+                const mod = (await import(pathToFileURL(sha3).href));
+                return typeof mod.keccak_256 === 'function' ? mod.keccak_256 : null;
+            }
+            catch {
+                return null;
+            }
+        })();
+    }
+    return keccakPromise;
+}
+/** Test seam: reset the memoized keccak loader (unit tests only). */
+export function __resetKeccakCacheForTests() {
+    keccakPromise = null;
+}
+/** Derive the Ethereum address a private key controls (lowercase 0x…40 hex).
+ *  'invalid_key' = the key is malformed or outside the secp256k1 range;
+ *  'unavailable' = the keccak dependency could not be loaded (callers must
+ *  fail OPEN — skip the check, never block credential entry on infra). */
+export async function deriveAddressFromPrivateKey(privateKey) {
+    if (!isHexPrivateKey(privateKey))
+        return { ok: false, reason: 'invalid_key' };
+    const keccak = await loadKeccak();
+    if (!keccak)
+        return { ok: false, reason: 'unavailable' };
+    try {
+        const ecdh = createECDH('secp256k1');
+        ecdh.setPrivateKey(Buffer.from(normalizeHexPrivateKey(privateKey).slice(2), 'hex'));
+        const uncompressed = ecdh.getPublicKey(null, 'uncompressed'); // 0x04 || X || Y (65 bytes)
+        const digest = keccak(Uint8Array.from(uncompressed.subarray(1)));
+        const address = `0x${Buffer.from(digest.subarray(digest.length - 20)).toString('hex')}`;
+        return { ok: true, address };
+    }
+    catch {
+        // createECDH throws on out-of-range keys — malformed input, not infra.
+        return { ok: false, reason: 'invalid_key' };
+    }
+}
+/** Case-insensitive address equality (addresses may arrive checksummed). */
+export function sameAddress(a, b) {
+    return a.trim().toLowerCase() === b.trim().toLowerCase();
+}

package/venues/hyperliquid/hl-preflight.d.ts

@@ -0,0 +1,28 @@
+/** Approvals expiring inside this window get a renewal warning — long enough
+ *  to act on, short enough not to nag for months. */
+export declare const HL_EXPIRY_WARN_MS: number;
+export interface HlPreflightInput {
+    walletAddress: string;
+    /** Derived agent address to check approval for; null = skip the check
+     *  (derivation unavailable). */
+    agentAddress: string | null;
+    testnet: boolean;
+    /** Injectable for tests; production uses global fetch. */
+    fetchImpl?: typeof fetch;
+}
+export interface HlPreflightOutcome {
+    /** clearinghouseState answered and parsed — the master account is queryable. */
+    reachable: boolean;
+    /** Set when !reachable — the raw error string for the caller's message. */
+    unreachableError?: string;
+    /** Perp equity + spot USDC; null when unreachable. */
+    balanceUSDC: number | null;
+    /** true/false = extraAgents answered definitively; null = could not check. */
+    agentApproved: boolean | null;
+    /** Approval expiry (epoch ms) when the exchange reports one. */
+    agentValidUntil: number | null;
+    warnings: string[];
+}
+export declare function hlApiBase(testnet: boolean): string;
+export declare function hlInfo(fetchImpl: typeof fetch, testnet: boolean, body: Record<string, unknown>): Promise<unknown>;
+export declare function hlPreflight(input: HlPreflightInput): Promise<HlPreflightOutcome>;

package/venues/hyperliquid/hl-preflight.js

@@ -0,0 +1,116 @@
+// Hyperliquid credential preflight — the UNSIGNED verification core shared by
+// test_exchange_credentials (candidate creds) and hl_agent_wallet_status
+// (stored creds). Deliberately takes ADDRESSES ONLY — this module never sees a
+// private key, so it stays outside the credential-holder set.
+//
+// Checks (all keyless POST /info reads — the master address is the query key):
+//   1. clearinghouseState(master) → perp equity. Failure here = "unreachable";
+//      callers hard-fail with the error string.
+//   2. spotClearinghouseState(master) → spot USDC (the unified account
+//      collateralizes perps from spot — verified live on testnet 2026-07-12).
+//      Cosmetic: failure is silently skipped, perp equity alone still answers.
+//   3. extraAgents(master) → is `agentAddress` in the approved list, and when
+//      does the approval expire? Shape [{name,address,validUntil(ms)}] —
+//      verified vs Chainstack/QuickNode HL API references 2026-08-01 (the
+//      official gitbook omits this info type). A definitive miss is the
+//      caller's hard fail; an endpoint error degrades to a warning
+//      (fail-open on infra, closed on an explicit "not approved").
+import { sameAddress } from './hl-agent-wallet.js';
+/** Approvals expiring inside this window get a renewal warning — long enough
+ *  to act on, short enough not to nag for months. */
+export const HL_EXPIRY_WARN_MS = 14 * 24 * 60 * 60 * 1000;
+export function hlApiBase(testnet) {
+    return testnet ? 'https://api.hyperliquid-testnet.xyz' : 'https://api.hyperliquid.xyz';
+}
+export async function hlInfo(fetchImpl, testnet, body) {
+    const res = await fetchImpl(`${hlApiBase(testnet)}/info`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(15_000),
+    });
+    if (!res.ok)
+        throw new Error(`POST /info ${String(body.type)} → ${res.status}`);
+    return res.json();
+}
+function msg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+export async function hlPreflight(input) {
+    const fetchImpl = input.fetchImpl ?? fetch;
+    const { walletAddress, testnet } = input;
+    const warnings = [];
+    // 1+2. Master account state.
+    let balanceUSDC = null;
+    try {
+        const state = (await hlInfo(fetchImpl, testnet, {
+            type: 'clearinghouseState',
+            user: walletAddress,
+        }));
+        const perpEquity = Number(state?.marginSummary?.accountValue);
+        let total = Number.isFinite(perpEquity) ? perpEquity : 0;
+        try {
+            const spot = (await hlInfo(fetchImpl, testnet, {
+                type: 'spotClearinghouseState',
+                user: walletAddress,
+            }));
+            for (const b of spot?.balances ?? []) {
+                if (String(b?.coin) === 'USDC') {
+                    const t = Number(b?.total);
+                    if (Number.isFinite(t))
+                        total += t;
+                }
+            }
+        }
+        catch {
+            // Spot read is cosmetic — perp equity alone is still a real answer.
+        }
+        balanceUSDC = total;
+        if (total <= 0) {
+            warnings.push('The master account holds no USDC yet — deposit/bridge USDC to Hyperliquid before going live.');
+        }
+    }
+    catch (e) {
+        return {
+            reachable: false,
+            unreachableError: msg(e),
+            balanceUSDC: null,
+            agentApproved: null,
+            agentValidUntil: null,
+            warnings,
+        };
+    }
+    // 3. Agent approval.
+    let agentApproved = null;
+    let agentValidUntil = null;
+    if (input.agentAddress) {
+        try {
+            const agents = (await hlInfo(fetchImpl, testnet, {
+                type: 'extraAgents',
+                user: walletAddress,
+            }));
+            if (Array.isArray(agents)) {
+                const match = agents.find((a) => typeof a?.address === 'string' && sameAddress(a.address, input.agentAddress));
+                agentApproved = match != null;
+                if (match && Number.isFinite(Number(match.validUntil))) {
+                    agentValidUntil = Number(match.validUntil);
+                    const remaining = agentValidUntil - Date.now();
+                    if (remaining <= 0) {
+                        agentApproved = false;
+                        warnings.push('The agent wallet approval has EXPIRED — re-approve it in the Hyperliquid API page.');
+                    }
+                    else if (remaining < HL_EXPIRY_WARN_MS) {
+                        warnings.push(`The agent wallet approval expires in ${Math.ceil(remaining / (24 * 60 * 60 * 1000))} day(s) — renew it soon (approvals last at most 180 days).`);
+                    }
+                }
+            }
+            else {
+                warnings.push('Could not read the approved-agents list — approval not verified.');
+            }
+        }
+        catch {
+            warnings.push('Could not read the approved-agents list — approval not verified.');
+        }
+    }
+    return { reachable: true, balanceUSDC, agentApproved, agentValidUntil, warnings };
+}