@jinn-network/client 0.1.0 → 0.1.1-canary.4a6ed8b2

package/dist/restorer/impls/claude-mcp-hyperliquid/mcp-tools.d.ts

@@ -0,0 +1,137 @@
+/**
+ * MCP tool definitions for claude-mcp-hyperliquid — §8.2.
+ *
+ * 5 read tools (public HL data, no auth):
+ *   hl_clearinghouse_state, hl_user_fills, hl_meta, hl_all_mids, hl_portfolio
+ *
+ * 4 write tools (require API wallet; safety rails enforced here):
+ *   hl_open_position, hl_close_position, hl_modify_position, hl_cancel_orders
+ *
+ * This module exports a factory function that takes dependencies and returns a
+ * list of McpToolDefinition objects. The session orchestrator registers these
+ * into the MCP server for each session.
+ *
+ * It also exports `startMcpServer(config)` — the entry point used by the
+ * generated hl-server.mjs wrapper. This is THE live code path for write tools.
+ *
+ * Safety rails (§8.3) are enforced at the tool boundary before any network call.
+ * Claude cannot bypass them through reasoning.
+ */
+import { z } from 'zod';
+import { HyperliquidClient } from '../../../venues/hyperliquid/client.js';
+import type { SafetyConfig, RateLimitState } from './safety-rails.js';
+/**
+ * Config passed into startMcpServer() — matches what _writeHlMcpServerScript
+ * serialises as JSON and what the generated wrapper passes as process.argv[2].
+ */
+export interface McpServerConfig {
+    hlBaseUrl: string;
+    apiWalletPrivateKey: string;
+    apiWalletAddress: string;
+    masterAddress: string;
+    safetyConfig?: Partial<SafetyConfig>;
+}
+export interface McpToolContent {
+    type: 'text';
+    text: string;
+}
+export interface McpToolResult {
+    content: McpToolContent[];
+}
+export type McpToolHandler<TArgs> = (args: TArgs) => Promise<McpToolResult>;
+export interface ToolDeps {
+    hlClient: HyperliquidClient;
+    /** HL exchange base URL (for write calls: POST /exchange) */
+    hlBaseUrl: string;
+    /** API wallet private key (0x-prefixed) for signing write operations */
+    apiWalletPrivateKey: string;
+    /** API wallet address */
+    apiWalletAddress: string;
+    /** Master account address (used as default for read tools) */
+    masterAddress: string;
+    /** Safety config (defaults to DEFAULT_SAFETY_CONFIG) */
+    safetyConfig?: SafetyConfig;
+    /** Rate-limit state (shared across all tools in a session) */
+    rateLimitState: RateLimitState;
+    /** Callback when a write op completes (for fill tracking) */
+    onWriteOp?: (op: WriteOpRecord) => void;
+}
+export interface WriteOpRecord {
+    /** Tool name */
+    tool: string;
+    /** Epoch ms when the op was submitted */
+    submittedAt: number;
+    /** Params sent to HL */
+    params: Record<string, unknown>;
+    /** HL response */
+    response: unknown;
+}
+/**
+ * Params for signing a Hyperliquid L1 action.
+ */
+export interface SignHlActionParams {
+    /** 0x-prefixed private key */
+    privateKey: string;
+    /** The action object (will be msgpack-encoded) */
+    action: Record<string, unknown>;
+    /** Nonce (typically epoch ms) */
+    nonce: number;
+    /** Optional vault address (20 bytes hex, 0x-prefixed) */
+    vaultAddress?: string | null;
+    /** Optional expiry timestamp (epoch ms) */
+    expiresAfter?: number | null;
+    /** true = mainnet (source "a"), false = testnet (source "b") */
+    isMainnet: boolean;
+}
+/**
+ * Sign a Hyperliquid L1 action using the canonical algorithm from hyperliquid-python-sdk.
+ *
+ * Algorithm (mirrors sign_l1_action in hyperliquid/utils/signing.py):
+ *
+ * 1. action_hash = keccak256(
+ *      msgpack(action)
+ *      || uint64_be(nonce)
+ *      || vault_flag_byte           // 0x01 if vaultAddress present, 0x00 otherwise
+ *      || vault_address_20_bytes    // only if vaultAddress present
+ *      || (0x01 || uint64_be(expiresAfter))  // only if expiresAfter present
+ *    )
+ *
+ * 2. EIP-712 typed-data:
+ *      domain: { name: "Exchange", version: "1", chainId: 1337, verifyingContract: 0x0...0 }
+ *      primaryType: "Agent"
+ *      types: Agent: [{name:"source",type:"string"},{name:"connectionId",type:"bytes32"}]
+ *      message: { source: isMainnet ? "a" : "b", connectionId: action_hash }
+ *
+ * 3. Sign with viem signTypedData.
+ *
+ * 4. Decode 65-byte sig into { r, s, v }.
+ */
+export declare function signHlAction(params: SignHlActionParams): Promise<{
+    r: string;
+    s: string;
+    v: number;
+}>;
+/**
+ * Build tool handlers for registration with a McpServer.
+ *
+ * Returns an array of { name, description, schema, handler } objects.
+ * The session orchestrator calls server.tool(name, description, schema, handler)
+ * for each.
+ */
+export declare function buildHlTools(deps: ToolDeps): HlToolDefinition[];
+export interface HlToolDefinition<TSchema extends z.ZodTypeAny = z.ZodTypeAny> {
+    name: string;
+    description: string;
+    schema: TSchema;
+    handler: McpToolHandler<z.infer<TSchema>>;
+}
+/**
+ * Start the HL MCP server on stdio using the provided config.
+ *
+ * This is THE live code path for write tools in production. The generated
+ * hl-server.mjs wrapper imports and calls this function — no stub signing,
+ * no duplication, no split-brain.
+ *
+ * Stays alive until stdin closes (child process lifecycle).
+ */
+export declare function startMcpServer(config: McpServerConfig): Promise<void>;