@hypelens/hypelens-agent-rail 0.1.20 → 0.1.22

package/src/mcp.js

@@ -4,7 +4,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { walls, cascade, pretradeCheck, whaleBook, quickstart } from './core.js';
-import { status, placeOrder, approvePayloads, newAgentWallet, getBalances, getPositions, cancelOrder, closePosition } from './exchange.js';
+import { status, placeOrder, approvePayloads, newAgentWallet, getBalances, getPositions, cancelOrder, closePosition, checkMaxBuilderFee } from './exchange.js';
 
 const j = (v) => ({ content: [{ type: 'text', text: JSON.stringify(v, null, 1) }] });
 const wrap = (fn) => async (args) => {
@@ -13,7 +13,7 @@ const wrap = (fn) => async (args) => {
 };
 
 const heatAfterPlace = (fn) => async (args) => {
-  if (!process.env.HYPELENS_AGENT_PK) {
+  if (!(process.env.HYPELENS_AGENT_PK || process.env.HYPERLIQUID_PRIVATE_KEY)) {
     return j({
       deferred: true,
       reason: 'setup_incomplete',
@@ -32,7 +32,7 @@ const heatAfterPlace = (fn) => async (args) => {
 };
 
 export async function main() {
-  const server = new McpServer({ name: 'hypelens-agent-rail', version: '0.1.20' });
+  const server = new McpServer({ name: 'hypelens-agent-rail', version: '0.1.22' });
 
   server.tool('hl_quickstart',
     'CALL FIRST: checklist wallet→approve→hl_balances(equity>0 / fundHow if 0)→hl_place_order sizeUsd mainnet when user asks to trade. No heat-first.',
@@ -48,10 +48,15 @@ export async function main() {
     {}, wrap(() => newAgentWallet()));
 
   server.tool('hl_approve_payloads',
-    'Setup: MASTER signs+POST approveAgent + ApproveBuilderFee once → next hl_balances → then hl_place_order sizeUsd:12.',
+    'Setup: OpenBroker — if HYPERLIQUID_PRIVATE_KEY/HYPELENS_MASTER_PK set, auto ApproveBuilderFee; else return clear MASTER payloads + maxBuilderFee. Next hl_balances → place.',
     { agentAddress: z.string().regex(/^0x[0-9a-fA-F]{40}$/) },
     wrap(({ agentAddress }) => approvePayloads(agentAddress)));
 
+  server.tool('hl_builder_fee_status',
+    'Check on-chain maxBuilderFee for builder 0x9548… (need >=10 tenths-bp). Place refuses until approved.',
+    { user: z.string().regex(/^0x[0-9a-fA-F]{40}$/).optional() },
+    wrap((a) => checkMaxBuilderFee(a)));
+
   server.tool('hl_balances',
     'Fund check before place. If equity=0 returns fundHow.depositAddress — ask user to deposit USDC, then recheck. If equity>0 nextTool=hl_place_order (only with user trading intent).',
     { user: z.string().regex(/^0x[0-9a-fA-F]{40}$/).optional() },
@@ -63,16 +68,18 @@ export async function main() {
     wrap((a) => getPositions(a)));
 
   server.tool('hl_place_order',
-    'PLACE mainnet perps (paying path). Prefer sizeUsd:12. Errors: approve missing / no margin / wrong net / retry place.',
+    'PLACE mainnet perps (paying path). ALWAYS attaches builder 1bp. Requires confirmTrade:true (or intent trade/place/execute). Refuses if maxBuilderFee not approved (no silent $0). Prefer sizeUsd:12 IOC.',
     {
       coin: z.string().describe('e.g. BTC'),
       isBuy: z.boolean(),
-      sizeUsd: z.number().positive().optional().describe('Preferred first-place notional USD — auto mark + size round (e.g. 12)'),
+      sizeUsd: z.number().positive().optional().describe('Preferred first-place notional USD — IOC @ mark±0.5% slip + size round (e.g. 12)'),
       size: z.number().positive().optional().describe('Coin units; optional if sizeUsd set'),
-      entryPx: z.number().positive().optional().describe('Limit px; omit with sizeUsd to use mark'),
+      entryPx: z.number().positive().optional().describe('GTC limit px; omit for IOC market (~0.5% slip from mark)'),
       slPx: z.number().positive().optional(), tpPx: z.number().positive().optional(),
       leverage: z.number().positive().optional().describe('Optional; enables advisory pre-trade risk check (first place: 2)'),
-      override: z.boolean().optional(), skipRiskCheck: z.boolean().optional()
+      override: z.boolean().optional(), skipRiskCheck: z.boolean().optional(),
+      confirmTrade: z.boolean().optional().describe('Required true after explicit user trade/place/execute intent'),
+      intent: z.enum(['trade', 'place', 'execute', 'buy', 'sell']).optional()
     },
     wrap((a) => placeOrder(a)));
 
@@ -82,8 +89,8 @@ export async function main() {
     wrap((a) => cancelOrder(a)));
 
   server.tool('hl_close_position',
-    'CLOSE a perp position (IOC reduce-only). Size defaults to full position. 1bp builder on fill.',
-    { coin: z.string(), size: z.number().positive().optional(), px: z.number().positive().optional(), user: z.string().regex(/^0x[0-9a-fA-F]{40}$/).optional() },
+    'CLOSE a perp position (IOC reduce-only). Size defaults to full position. 1bp builder on fill. Pass confirmTrade:true.',
+    { coin: z.string(), size: z.number().positive().optional(), px: z.number().positive().optional(), user: z.string().regex(/^0x[0-9a-fA-F]{40}$/).optional(), confirmTrade: z.boolean().optional(), intent: z.enum(['trade', 'place', 'execute', 'close']).optional() },
     wrap((a) => closePosition(a)));
 
   server.tool('hl_walls',

package/vendor/hl-actions.js

@@ -82,15 +82,17 @@
   }
 
   // ==== L1 (agent-signed) ORDER action with normalTpsl grouping + builder ====
-  // plan: { assetIndex, szDecimals, isBuy, entryPx, size, slPx?, tpPx? }
+  // plan: { assetIndex, szDecimals, isBuy, entryPx, size, slPx?, tpPx?, tif? }
   function buildOrderAction(plan) {
     if (plan.assetIndex == null || plan.assetIndex < 0) throw new Error('bad assetIndex');
     if (!(plan.size > 0)) throw new Error('bad size');
     const szDec = plan.szDecimals | 0;
     const s = sizeToWire(plan.size, szDec);
+    const rawTif = String(plan.tif || 'Gtc');
+    const tif = /^ioc$/i.test(rawTif) ? 'Ioc' : 'Gtc';
     const orders = [];
-    // 1) entry — GTC limit
-    orders.push({ a: plan.assetIndex, b: !!plan.isBuy, p: priceToWire(plan.entryPx, szDec), s, r: false, t: { limit: { tif: 'Gtc' } } });
+    // 1) entry — IOC when plan.tif=Ioc (market/sizeUsd), else GTC limit
+    orders.push({ a: plan.assetIndex, b: !!plan.isBuy, p: priceToWire(plan.entryPx, szDec), s, r: false, t: { limit: { tif: tif } } });
     // 2) SL — reduceOnly stop-market trigger (opposite side)
     if (plan.slPx != null) {
       orders.push({ a: plan.assetIndex, b: !plan.isBuy, p: priceToWire(plan.slPx, szDec), s, r: true,

package/vendor/hl-actions.js.bak

@@ -0,0 +1,116 @@
+// HypeLens Module 3 — Hyperliquid EXCHANGE action builders (PURE, no signing).
+// -----------------------------------------------------------------------------
+// Testnet-first. The BUILDER address is PINNED here and must NEVER be read from
+// the page. All numeric normalization (float_to_wire, szDecimals) lives here so
+// it can be unit-tested; the vendored SDK's actionSorter still owns msgpack key
+// order for the hash. Exposes window.HLX3.actions.
+(function (g) {
+  'use strict';
+  const X3 = g.HLX3 = g.HLX3 || {};
+
+  // --- HARD BLOCK: mainnet placement is DISABLED in code until testnet proof +
+  // an explicit, separate operator sign-off. While false, the mainnet network
+  // option is hidden, setNet('mainnet') is refused, and any mainnet /exchange
+  // POST is rejected (defense-in-depth in the background too). ---
+  const MAINNET_PLACEMENT_ENABLED = false;
+
+  // --- PINNED constants (never sourced from the page) ---
+  const BUILDER = '0x9548B8E9554a1968843B3C380431b10996247c88';   // HypeLens builder
+  const BUILDER_F = 20;                 // f=20 tenths-of-a-bp = 2bp = 0.02% (f ≤ 100 perps)
+  const MAX_BUILDER_FEE_RATE = '0.02%'; // approveBuilderFee maxFeeRate
+  const AGENT_NAME = 'hypelens';
+  const SIGNATURE_CHAIN_ID = '0x66eee'; // 421614 (Arbitrum Sepolia) for user-signed actions
+  const EIP712_DOMAIN = { name: 'HyperliquidSignTransaction', version: '1', chainId: 421614, verifyingContract: '0x0000000000000000000000000000000000000000' };
+
+  const NET = {
+    testnet: { chain: 'Testnet', source: 'b', exchange: 'https://api.hyperliquid-testnet.xyz/exchange', info: 'https://api.hyperliquid-testnet.xyz/info' },
+    mainnet: { chain: 'Mainnet', source: 'a', exchange: 'https://api.hyperliquid.xyz/exchange', info: 'https://api.hyperliquid.xyz/info' }
+  };
+
+  // strictly-increasing millisecond nonce
+  let _lastNonce = 0;
+  function nonce() { let n = Date.now(); if (n <= _lastNonce) n = _lastNonce + 1; _lastNonce = n; return n; }
+
+  // ---- float_to_wire: no trailing zeros, ≤5 significant figures, integer-safe ----
+  // HL rule: prices ≤5 sig figs; perp price decimals ≤ (6 - szDecimals); size to szDecimals.
+  function floatToWire(x) {
+    if (x == null || typeof x !== 'number' || !isFinite(x)) throw new Error('floatToWire: not a finite number: ' + x);
+    if (x === 0) return '0';
+    // 5 significant figures, then trim to 8 decimals max, strip trailing zeros.
+    const rounded = parseFloat(x.toPrecision(5));
+    let s = rounded.toFixed(8);
+    s = s.replace(/0+$/, '').replace(/\.$/, '');
+    if (s === '-0') s = '0';
+    return s;
+  }
+  function roundToDecimals(x, decimals) { const f = Math.pow(10, decimals); return Math.round(x * f) / f; }
+  // size wire: round to szDecimals then float_to_wire. A positive size that
+  // rounds to '0' would be silently rejected (or worse) — throw instead.
+  function sizeToWire(sz, szDecimals) {
+    const d = Math.max(0, szDecimals | 0);
+    const wire = floatToWire(roundToDecimals(Number(sz), d));
+    if (Number(sz) > 0 && wire === '0') throw new Error('size rounds to zero at ' + d + ' decimals — increase size');
+    return wire;
+  }
+  // price wire: ≤5 sig figs AND ≤ (6 - szDecimals) decimals (perps), then float_to_wire
+  function priceToWire(px, szDecimals) {
+    const maxDec = Math.max(0, 6 - (szDecimals | 0));
+    const five = parseFloat(Number(px).toPrecision(5));
+    return floatToWire(roundToDecimals(five, maxDec));
+  }
+
+  function isAddr(a) { return typeof a === 'string' && /^0x[0-9a-fA-F]{40}$/.test(a); }
+
+  // ==== USER-SIGNED actions (master wallet, EIP-712) ====
+  function buildApproveAgent(net, agentAddress) {
+    const N = NET[net]; if (!N) throw new Error('bad net'); if (!isAddr(agentAddress)) throw new Error('bad agentAddress');
+    const action = { type: 'approveAgent', hyperliquidChain: N.chain, signatureChainId: SIGNATURE_CHAIN_ID, agentAddress, agentName: AGENT_NAME, nonce: nonce() };
+    const types = { 'HyperliquidTransaction:ApproveAgent': [
+      { name: 'hyperliquidChain', type: 'string' }, { name: 'agentAddress', type: 'address' },
+      { name: 'agentName', type: 'string' }, { name: 'nonce', type: 'uint64' }
+    ] };
+    return { action, types, primaryType: 'HyperliquidTransaction:ApproveAgent', domain: EIP712_DOMAIN };
+  }
+  function buildApproveBuilderFee(net) {
+    const N = NET[net]; if (!N) throw new Error('bad net');
+    const action = { type: 'approveBuilderFee', hyperliquidChain: N.chain, signatureChainId: SIGNATURE_CHAIN_ID, maxFeeRate: MAX_BUILDER_FEE_RATE, builder: BUILDER, nonce: nonce() };
+    const types = { 'HyperliquidTransaction:ApproveBuilderFee': [
+      { name: 'hyperliquidChain', type: 'string' }, { name: 'maxFeeRate', type: 'string' },
+      { name: 'builder', type: 'address' }, { name: 'nonce', type: 'uint64' }
+    ] };
+    return { action, types, primaryType: 'HyperliquidTransaction:ApproveBuilderFee', domain: EIP712_DOMAIN };
+  }
+
+  // ==== L1 (agent-signed) ORDER action with normalTpsl grouping + builder ====
+  // plan: { assetIndex, szDecimals, isBuy, entryPx, size, slPx?, tpPx? }
+  function buildOrderAction(plan) {
+    if (plan.assetIndex == null || plan.assetIndex < 0) throw new Error('bad assetIndex');
+    if (!(plan.size > 0)) throw new Error('bad size');
+    const szDec = plan.szDecimals | 0;
+    const s = sizeToWire(plan.size, szDec);
+    const orders = [];
+    // 1) entry — GTC limit
+    orders.push({ a: plan.assetIndex, b: !!plan.isBuy, p: priceToWire(plan.entryPx, szDec), s, r: false, t: { limit: { tif: 'Gtc' } } });
+    // 2) SL — reduceOnly stop-market trigger (opposite side)
+    if (plan.slPx != null) {
+      orders.push({ a: plan.assetIndex, b: !plan.isBuy, p: priceToWire(plan.slPx, szDec), s, r: true,
+        t: { trigger: { isMarket: true, triggerPx: priceToWire(plan.slPx, szDec), tpsl: 'sl' } } });
+    }
+    // 3) TP — reduceOnly take-profit trigger (opposite side)
+    if (plan.tpPx != null) {
+      orders.push({ a: plan.assetIndex, b: !plan.isBuy, p: priceToWire(plan.tpPx, szDec), s, r: true,
+        t: { trigger: { isMarket: true, triggerPx: priceToWire(plan.tpPx, szDec), tpsl: 'tp' } } });
+    }
+    const grouping = (plan.slPx != null || plan.tpPx != null) ? 'normalTpsl' : 'na';
+    return { type: 'order', orders, grouping, builder: { b: BUILDER.toLowerCase(), f: BUILDER_F } };
+  }
+
+  X3.actions = {
+    MAINNET_PLACEMENT_ENABLED,
+    BUILDER, BUILDER_F, MAX_BUILDER_FEE_RATE, AGENT_NAME, SIGNATURE_CHAIN_ID, NET, EIP712_DOMAIN,
+    nonce, floatToWire, sizeToWire, priceToWire, roundToDecimals, isAddr,
+    buildApproveAgent, buildApproveBuilderFee, buildOrderAction
+  };
+  // CommonJS export so the wire math can be unit-tested under node.
+  try { if (typeof module !== 'undefined' && module.exports) module.exports = X3.actions; } catch (e) {}
+})(typeof window !== 'undefined' ? window : globalThis);

package/vendor/hl-sdk.js

@@ -9171,6 +9171,19 @@
             message
           };
         },
+        async signUserSigned(pk, action) {
+          const wallet = privateKeyToAccount(pk);
+          const typed = this.userSignedTypedData(action, action.signatureChainId);
+          const types = { ...typed.types };
+          delete types.EIP712Domain;
+          return await signTypedData2({
+            wallet,
+            domain: typed.domain,
+            types,
+            primaryType: typed.primaryType,
+            message: typed.message
+          });
+        },
         orderToWire(order, szDecimals) {
           const w = {
             a: order.a,

package/vendor/hl-signer.js

@@ -9,7 +9,7 @@
   'use strict';
   const X3 = g.HLX3 = g.HLX3 || {};
 
-  const SDK_METHODS = ['randomPrivateKey', 'addressFromPrivateKey', 'hashL1Action', 'signL1Action', 'userSignedTypedData', 'orderToWire'];
+  const SDK_METHODS = ['randomPrivateKey', 'addressFromPrivateKey', 'hashL1Action', 'signL1Action', 'userSignedTypedData', 'signUserSigned', 'orderToWire'];
   function sdk() { const s = g.HLSDK; if (!s) throw new Error('signing SDK not vendored — placement disabled'); return s; }
 
   // SELF-TEST (runs at load): all 6 adapter methods present + hashL1Action is
@@ -61,7 +61,16 @@
     return { domain: built.domain, types: built.types, primaryType: built.primaryType, message: built.action };
   }
 
-  X3.signer = { ready, lastError, selfTest, signL1, userTypedData, assertDeterministicHash, addressFromPrivateKey: (pk) => sdk().addressFromPrivateKey(pk) };
+  // MASTER-wallet EIP-712 sign for approveAgent / approveBuilderFee (OpenBroker).
+  async function signUserSigned(privateKey, action) {
+    const s = sdk();
+    if (typeof s.signUserSigned !== 'function') throw new Error('HLSDK.signUserSigned missing — rebuild vendor');
+    const signature = await s.signUserSigned(privateKey, action);
+    if (!signature || signature.r == null || signature.s == null || signature.v == null) throw new Error('SDK returned an invalid user signature');
+    return { signature, action, nonce: action.nonce };
+  }
+
+  X3.signer = { ready, lastError, selfTest, signL1, signUserSigned, userTypedData, assertDeterministicHash, addressFromPrivateKey: (pk) => sdk().addressFromPrivateKey(pk) };
   // Run the self-test once at load and surface the result in the console so a
   // broken/absent SDK is obvious. Placement stays fail-closed on failure.
   try { const r = selfTest(); if (r.ok) console.log('[HypeLens] signing SDK self-test PASSED (hash', r.hash.slice(0, 10) + '…)'); else console.warn('[HypeLens] signing SDK self-test FAILED —', r.error); } catch (e) {}