@oracle-agent/oracle 0.1.0 → 0.2.1

package/src/data/providers/hl-assets.mjs

@@ -0,0 +1,165 @@
+// Hyperliquid asset ID resolution — main perps, HIP-3 builder dexs, HIP-4 outcomes.
+// Docs: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/asset-ids
+//
+// Main perps:      asset = index in meta.universe
+// HIP-3 builder:   asset = 100000 + perp_dex_index * 10000 + index_in_meta
+// HIP-4 outcomes:  encoding = 10 * outcome + side; asset = 100_000_000 + encoding
+//                  coin form: #<encoding>
+
+import { hlInfo, hlMetaAndAssetCtxs } from "./hl-info.mjs";
+
+const OUTCOME_ASSET_BASE = 100_000_000;
+const BUILDER_PERP_BASE = 100_000;
+
+let _dexCache = { at: 0, dexs: null };
+let _metaCache = new Map(); // dex -> { at, universe, ctxs }
+
+async function perpDexs(opts = {}) {
+  const now = Date.now();
+  if (_dexCache.dexs && now - _dexCache.at < 60_000 && !opts.fetchImpl) return _dexCache.dexs;
+  const dexs = await hlInfo({ type: "perpDexs" }, opts);
+  _dexCache = { at: now, dexs: Array.isArray(dexs) ? dexs : [] };
+  return _dexCache.dexs;
+}
+
+async function metaForDex(dex = "", opts = {}) {
+  const key = dex || "";
+  const now = Date.now();
+  const hit = _metaCache.get(key);
+  // skip cache when caller injects fetchImpl (unit tests / custom transport)
+  if (hit && now - hit.at < 30_000 && !opts.fetchImpl) return hit;
+  const raw = dex
+    ? await hlInfo({ type: "metaAndAssetCtxs", dex }, opts)
+    : await hlMetaAndAssetCtxs(opts);
+  const universe = raw?.[0]?.universe ?? raw?.universe ?? [];
+  const ctxs = Array.isArray(raw?.[1]) ? raw[1] : [];
+  const entry = { at: now, universe, ctxs };
+  _metaCache.set(key, entry);
+  return entry;
+}
+
+/** Parse HIP-4 coin "#1100" or encoding number → { encoding, outcome, side }. */
+export function parseOutcomeCoin(coin) {
+  const text = String(coin || "").trim();
+  let encoding;
+  if (text.startsWith("#")) encoding = Number(text.slice(1));
+  else if (/^\d+$/.test(text)) encoding = Number(text);
+  else return null;
+  if (!Number.isInteger(encoding) || encoding < 0) return null;
+  const side = encoding % 10;
+  if (side !== 0 && side !== 1) return null;
+  const outcome = Math.floor(encoding / 10);
+  return { encoding, outcome, side, coin: `#${encoding}`, assetId: OUTCOME_ASSET_BASE + encoding };
+}
+
+export function outcomeAssetId(outcome, side) {
+  const o = Number(outcome);
+  const s = Number(side);
+  if (!Number.isInteger(o) || o < 0) throw new Error("hl-assets: outcome id must be a non-negative integer");
+  if (s !== 0 && s !== 1) throw new Error("hl-assets: outcome side must be 0 or 1");
+  const encoding = 10 * o + s;
+  return { encoding, outcome: o, side: s, coin: `#${encoding}`, assetId: OUTCOME_ASSET_BASE + encoding };
+}
+
+/**
+ * Resolve any tradeable HL coin name to asset id + precision.
+ * Accepts: "BTC", "xyz:TSLA", "#1100", { outcome, side }, { dex, coin }.
+ */
+export async function resolveHlAsset(args = {}, opts = {}) {
+  // HIP-4 explicit
+  if (args.outcome != null || (args.coin && String(args.coin).startsWith("#"))) {
+    const parsed =
+      args.outcome != null
+        ? outcomeAssetId(args.outcome, args.side ?? args.outcomeSide ?? 0)
+        : parseOutcomeCoin(args.coin);
+    if (!parsed) throw new Error(`hl-assets: invalid outcome coin ${args.coin}`);
+    // szDecimals for outcomes: typically 2-4; use 2 default (binary contracts)
+    const szDecimals = args.szDecimals != null ? Number(args.szDecimals) : 2;
+    return {
+      kind: "outcome",
+      coin: parsed.coin,
+      assetId: parsed.assetId,
+      encoding: parsed.encoding,
+      outcome: parsed.outcome,
+      side: parsed.side,
+      szDecimals,
+      maxLeverage: 1,
+      dex: null,
+      markPx: null,
+    };
+  }
+
+  const rawName = String(args.coin || args.symbol || args.name || "").trim();
+  if (!rawName) throw new Error("hl-assets: coin required");
+
+  // HIP-3 builder dex coin: dex:COIN
+  if (rawName.includes(":")) {
+    const [dex, ...rest] = rawName.split(":");
+    const leaf = rest.join(":");
+    if (!dex || !leaf) throw new Error(`hl-assets: bad builder coin ${rawName}`);
+    const dexs = await perpDexs(opts);
+    const dexIndex = dexs.findIndex((d) => d && d.name === dex);
+    if (dexIndex < 1) throw new Error(`hl-assets: unknown builder dex "${dex}"`);
+    const { universe, ctxs } = await metaForDex(dex, opts);
+    const index = universe.findIndex((a) => a.name === rawName || a.name === `${dex}:${leaf}` || a.name.endsWith(`:${leaf}`));
+    if (index < 0) throw new Error(`hl-assets: ${rawName} not in dex ${dex} meta`);
+    const asset = universe[index];
+    if (asset.isDelisted) throw new Error(`hl-assets: ${rawName} is delisted`);
+    const assetId = BUILDER_PERP_BASE + dexIndex * 10_000 + index;
+    const ctx = ctxs[index] || {};
+    return {
+      kind: "hip3",
+      coin: asset.name || rawName,
+      assetId,
+      szDecimals: asset.szDecimals ?? 0,
+      maxLeverage: asset.maxLeverage ?? null,
+      dex,
+      dexIndex,
+      indexInMeta: index,
+      markPx: ctx.markPx ?? null,
+    };
+  }
+
+  // Main dex perps
+  const { universe, ctxs } = await metaForDex("", opts);
+  const coin = rawName.toUpperCase();
+  const index = universe.findIndex((a) => a.name === coin);
+  if (index < 0) {
+    // optional: bare leaf match on builder dexs (TSLA -> xyz:TSLA)
+    if (opts.allowBareBuilderLeaf === true) {  // opt-in only; explicit dex:COIN preferred
+      try {
+        const dexs = await perpDexs(opts);
+        for (let di = 1; di < dexs.length; di++) {
+          const d = dexs[di];
+          if (!d?.name) continue;
+          const tryName = `${d.name}:${coin}`;
+          try {
+            return await resolveHlAsset({ coin: tryName }, opts);
+          } catch {
+            /* next dex */
+          }
+        }
+      } catch {
+        /* offline / mock without perpDexs */
+      }
+    }
+    throw new Error(`hl-perps: ${coin} is not a listed perp`);
+  }
+  const asset = universe[index];
+  if (asset.isDelisted) throw new Error(`hl-assets: ${coin} is delisted`);
+  const ctx = ctxs[index] || {};
+  return {
+    kind: "main",
+    coin: asset.name,
+    assetId: index,
+    szDecimals: asset.szDecimals ?? 0,
+    maxLeverage: asset.maxLeverage ?? null,
+    dex: "",
+    markPx: ctx.markPx ?? null,
+  };
+}
+
+export function clearHlAssetCache() {
+  _dexCache = { at: 0, dexs: null };
+  _metaCache.clear();
+}

package/src/data/providers/hl-info.mjs

@@ -65,7 +65,13 @@ export async function hlMeta(opts = {}) {
 }
 
 export async function hlMetaAndAssetCtxs(opts = {}) {
-  return hlInfo({ type: "metaAndAssetCtxs" }, opts);
+  const body = { type: "metaAndAssetCtxs" };
+  if (opts.dex) body.dex = opts.dex;
+  return hlInfo(body, opts);
+}
+
+export async function hlPerpDexs(opts = {}) {
+  return hlInfo({ type: "perpDexs" }, opts);
 }
 
 export async function hlCandleSnapshot({ coin, interval = "1h", startTime, endTime }, opts = {}) {

package/src/data/providers/hl-outcome.mjs

@@ -0,0 +1,61 @@
+// HIP-4 outcome market prepare helpers (local, no VPS).
+import { stampPrepared } from "../../prepare-envelope.mjs";
+import { hlOutcomeMeta } from "./hl-info.mjs";
+import { outcomeAssetId, parseOutcomeCoin } from "./hl-assets.mjs";
+import { hlPreparePerpOrder, hlPrepareCancelOrder } from "./hl-perps.mjs";
+
+export async function hlOutcomeList(opts = {}) {
+  const meta = await hlOutcomeMeta(opts);
+  return {
+    provider: "hl-outcome",
+    kind: "outcome-meta",
+    outcomes: meta?.outcomes || [],
+    questions: meta?.questions || [],
+  };
+}
+
+/**
+ * Prepare a HIP-4 outcome order.
+ * args: { outcome, side: 0|1|'yes'|'no', sideName?, coin?, ...hlPreparePerpOrder fields }
+ */
+export async function hlPrepareOutcomeOrder(args = {}, opts = {}) {
+  let coin = args.coin;
+  let outcome = args.outcome;
+  let side = args.side;
+  if (typeof side === "string") {
+    const s = side.toLowerCase();
+    if (s === "yes" || s === "0") side = 0;
+    else if (s === "no" || s === "1") side = 1;
+  }
+  if (args.sideName && outcome != null) {
+    const meta = await hlOutcomeMeta(opts);
+    const o = (meta?.outcomes || []).find((x) => Number(x.outcome) === Number(outcome));
+    if (o?.sideSpecs) {
+      const idx = o.sideSpecs.findIndex(
+        (sp) => String(sp.name).toLowerCase() === String(args.sideName).toLowerCase()
+      );
+      if (idx >= 0) side = idx;
+    }
+  }
+  if (!coin) {
+    if (outcome == null || side == null) {
+      throw new Error("hl-outcome: provide coin (#N) or outcome + side (0/1 or yes/no)");
+    }
+    coin = outcomeAssetId(outcome, side).coin;
+  }
+  const prepared = await hlPreparePerpOrder({ ...args, coin }, opts);
+  // ensure stamped kind
+  return stampPrepared(
+    { ...prepared, kind: "hip4-order", provider: "hl-perps" },
+    { provider: "hl-perps", kind: "hip4-order" }
+  );
+}
+
+export async function hlPrepareOutcomeCancel(args = {}, opts = {}) {
+  let coin = args.coin;
+  if (!coin && args.outcome != null) {
+    const side = args.side ?? 0;
+    coin = outcomeAssetId(args.outcome, side).coin;
+  }
+  return hlPrepareCancelOrder({ ...args, coin }, opts);
+}

package/src/data/providers/hl-perps.mjs

@@ -12,8 +12,10 @@
 // rounded to szDecimals. Integers are always allowed regardless of sig figs.
 // We do that rounding here, once, in decimal — never through a float.
 
-import { hlMetaAndAssetCtxs } from "./hl-info.mjs";
+import { hlMetaAndAssetCtxs, hlAllMids } from "./hl-info.mjs";
+import { resolveHlAsset } from "./hl-assets.mjs";
 import { toScaledInteger } from "../../exact-integer.mjs";
+import { stampPrepared } from "../../prepare-envelope.mjs";
 
 export const HL_PERP_MAX_SIG_FIGS = 5;
 export const HL_PERP_PRICE_DECIMALS = 6; // 6 - szDecimals for perps
@@ -102,23 +104,18 @@ export function formatPerpSize(size, szDecimals) {
 
 /** Resolve a coin to its asset index and precision. Required before ordering. */
 export async function hlPerpAssetInfo(args = {}, opts = {}) {
-  const coin = String(args.coin || args.symbol || "").trim().toUpperCase();
-  if (!coin) throw new Error("hl-perps: coin required");
-  const meta = await hlMetaAndAssetCtxs(opts);
-  const universe = meta?.[0]?.universe ?? meta?.universe ?? [];
-  const ctxs = Array.isArray(meta?.[1]) ? meta[1] : [];
-  const index = universe.findIndex((a) => a.name === coin);
-  if (index < 0) throw new Error(`hl-perps: ${coin} is not a listed perp`);
-  const asset = universe[index];
-  if (asset.isDelisted) throw new Error(`hl-perps: ${coin} is delisted`);
-  const ctx = ctxs[index] || {};
+  // Resolves main perps, HIP-3 builder dexs (dex:COIN), and HIP-4 outcomes (#N / outcome+side).
+  const info = await resolveHlAsset(args, opts);
   return {
-    coin,
-    assetId: index,
-    szDecimals: asset.szDecimals ?? 0,
-    maxLeverage: asset.maxLeverage ?? null,
-    markPx: ctx.markPx ?? null,
-    oraclePx: ctx.oraclePx ?? null,
+    coin: info.coin,
+    assetId: info.assetId,
+    szDecimals: info.szDecimals,
+    maxLeverage: info.maxLeverage,
+    markPx: info.markPx,
+    kind: info.kind,
+    dex: info.dex ?? null,
+    outcome: info.outcome ?? null,
+    side: info.side ?? null,
   };
 }
 
@@ -157,16 +154,16 @@ function envelope(action, nonce) {
     action,
     nonce,
     signatureChainId: HL_SIGNATURE_CHAIN_ID,
-    // The wallet signs this; Oracle never does.
-    requiresUserSignature: true,
-    signingReady: false,
-    broadcastReady: false,
-    executionReady: false,
     submitTo: "https://api.hyperliquid.xyz/exchange",
-    note: "Sign this action with the user's wallet and POST it. Oracle does not submit.",
+    note: "Sign locally via @oracle-agent/operator or a wallet. Oracle does not submit.",
   };
 }
 
+/** Stamp a full HL prepare result (provider/kind + action envelope). */
+function stamped(result) {
+  return stampPrepared(result, { provider: result.provider || "hl-perps", kind: result.kind });
+}
+
 /**
  * Prepare a perp order.
  *
@@ -185,7 +182,11 @@ export async function hlPreparePerpOrder(args = {}, opts = {}) {
 
   let price;
   if (kind === ORDER_TYPES.MARKET) {
-    const mark = Number(info.markPx);
+    let mark = Number(info.markPx);
+    if (!Number.isFinite(mark)) {
+      const mids = await hlAllMids(opts);
+      mark = Number(mids?.[info.coin] ?? mids?.[String(info.assetId)] ?? NaN);
+    }
     if (!Number.isFinite(mark)) throw new Error("hl-perps: no mark price available for a market order");
     const bps = Number(args.maxSlippageBps ?? 50);
     if (!Number.isInteger(bps) || bps < 0) throw new Error("hl-perps: maxSlippageBps must be a non-negative integer");
@@ -234,12 +235,16 @@ export async function hlPreparePerpOrder(args = {}, opts = {}) {
   const nonce = Number(args.nonce ?? Date.now());
   const notional = Number(price) * Number(size);
 
-  return {
+  return stamped({
     provider: "hl-perps",
     venue: "hyperliquid",
-    kind: "perp-order",
+    kind: info.kind === "outcome" ? "hip4-order" : info.kind === "hip3" ? "hip3-order" : "perp-order",
     coin: info.coin,
     assetId: info.assetId,
+    assetKind: info.kind,
+    outcome: info.outcome ?? null,
+    outcomeSide: info.side ?? null,
+    dex: info.dex ?? null,
     side: isBuy ? "buy" : "sell",
     orderType: kind,
     price,
@@ -249,7 +254,7 @@ export async function hlPreparePerpOrder(args = {}, opts = {}) {
     maxLeverage: info.maxLeverage,
     markPx: info.markPx,
     ...envelope(action, nonce),
-  };
+  });
 }
 
 /** Prepare a cancel by order id. */
@@ -258,14 +263,14 @@ export async function hlPrepareCancelOrder(args = {}, opts = {}) {
   const oid = args.orderId ?? args.oid;
   if (oid == null) throw new Error("hl-perps: orderId required");
   const action = { type: "cancel", cancels: [{ a: info.assetId, o: Number(oid) }] };
-  return {
+  return stamped({
     provider: "hl-perps",
     venue: "hyperliquid",
     kind: "perp-cancel",
     coin: info.coin,
     orderId: Number(oid),
     ...envelope(action, Number(args.nonce ?? Date.now())),
-  };
+  });
 }
 
 /**
@@ -292,7 +297,7 @@ export async function hlPrepareUpdateLeverage(args = {}, opts = {}) {
     isCross: mode === MARGIN_MODE.CROSS,
     leverage,
   };
-  return {
+  return stamped({
     provider: "hl-perps",
     venue: "hyperliquid",
     kind: "perp-leverage",
@@ -305,7 +310,7 @@ export async function hlPrepareUpdateLeverage(args = {}, opts = {}) {
         ? `${leverage}x liquidates on roughly a ${(100 / leverage).toFixed(2)}% adverse move before fees`
         : null,
     ...envelope(action, Number(args.nonce ?? Date.now())),
-  };
+  });
 }
 
 /** Prepare an isolated-margin adjustment for an existing position. */
@@ -325,14 +330,14 @@ export async function hlPrepareUpdateIsolatedMargin(args = {}, opts = {}) {
     isBuy: true,
     ntli: micro <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(micro) : micro.toString(),
   };
-  return {
+  return stamped({
     provider: "hl-perps",
     venue: "hyperliquid",
     kind: "perp-isolated-margin",
     coin: info.coin,
     usd: text,
     ...envelope(action, Number(args.nonce ?? Date.now())),
-  };
+  });
 }
 
 /**
@@ -368,7 +373,7 @@ export async function hlPrepareBracketOrder(args = {}, opts = {}) {
   if (orders.length === 1) throw new Error("hl-perps: a bracket needs takeProfitPx and/or stopLossPx");
 
   const action = { type: "order", orders, grouping: "normalTpsl" };
-  return {
+  return stamped({
     provider: "hl-perps",
     venue: "hyperliquid",
     kind: "perp-bracket",
@@ -378,5 +383,5 @@ export async function hlPrepareBracketOrder(args = {}, opts = {}) {
     takeProfitPx: args.takeProfitPx == null ? null : formatPerpPrice(args.takeProfitPx, info.szDecimals),
     stopLossPx: args.stopLossPx == null ? null : formatPerpPrice(args.stopLossPx, info.szDecimals),
     ...envelope(action, Number(args.nonce ?? Date.now())),
-  };
+  });
 }

package/src/data/providers/magiceden-sol.mjs

@@ -8,6 +8,7 @@
 import { httpJson } from "../http.mjs";
 import { solanaPubkey } from "./solana-rpc.mjs";
 import { resolveProviderEndpoint, credentialedHeaders } from "../provider-endpoint.mjs";
+import { stampPrepared } from "../../prepare-envelope.mjs";
 
 export const MAGICEDEN_SOL_API = "https://api-mainnet.magiceden.dev/v2";
 export const LAMPORTS_PER_SOL = 1_000_000_000;
@@ -223,7 +224,7 @@ export async function magicEdenSolPrepareBuy(args = {}, opts = {}) {
     throw new Error("magiceden: buy_now returned no unsigned transaction payload");
   }
   const transaction = Buffer.from(data).toString("base64");
-  return {
+  return stampPrepared({
     provider: "magiceden-sol",
     chain: "solana-mainnet-beta",
     kind: "nft-buy",
@@ -241,7 +242,7 @@ export async function magicEdenSolPrepareBuy(args = {}, opts = {}) {
     transaction,
     transactionEncoding: "base64",
     raw,
-  };
+  });
 }
 
 /**
@@ -269,7 +270,7 @@ export async function magicEdenSolPrepareList(args = {}, opts = {}) {
   const data = raw?.v0?.tx?.data ?? raw?.tx?.data ?? null;
   const transaction = Array.isArray(data) ? Buffer.from(data).toString("base64") : null;
   if (!transaction) throw new Error("magiceden: sell returned no transaction payload");
-  return {
+  return stampPrepared({
     provider: "magiceden-sol",
     chain: "solana-mainnet-beta",
     kind: "nft-list",
@@ -284,7 +285,7 @@ export async function magicEdenSolPrepareList(args = {}, opts = {}) {
     transaction,
     transactionEncoding: "base64",
     raw,
-  };
+  });
 }
 
 /**
@@ -333,7 +334,7 @@ export async function magicEdenSolPrepareMint(args = {}, opts = {}) {
     throw new Error("magiceden: mint returned no unsigned transaction payload");
   }
   const transaction = Buffer.from(data).toString("base64");
-  return {
+  return stampPrepared({
     provider: "magiceden-sol",
     chain: "solana-mainnet-beta",
     kind: "nft-mint",
@@ -351,5 +352,5 @@ export async function magicEdenSolPrepareMint(args = {}, opts = {}) {
     transaction,
     transactionEncoding: "base64",
     raw,
-  };
+  });
 }