@oracle-agent/oracle 0.10.0 → 0.12.0

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

@@ -1,353 +0,0 @@
-// Hyperliquid HyperCore staking lane: HYPE stake / unstake / delegate.
-//
-// Reads are public info endpoints. Writes are PREPARE-ONLY: this module returns
-// EIP-712 typed data plus the exact action payload for the user's own wallet to
-// sign. It never signs, never posts to /exchange, never holds a key.
-//
-// Flow the user actually performs:
-//   spot -> staking balance      : cDeposit
-//   staking balance -> validator : tokenDelegate (isUndelegate=false)
-//   validator -> staking balance : tokenDelegate (isUndelegate=true)   [1 day validator lockup]
-//   staking balance -> spot      : cWithdraw                            [7 day unstaking queue]
-
-import { stampPrepared } from "../../prepare-envelope.mjs";
-import { httpJson } from "../http.mjs";
-import { hlInfo } from "./hl-info.mjs";
-export const HYPE_STAKING_DECIMALS = 8;
-export const HYPE_WEI_PER_TOKEN = 10n ** BigInt(HYPE_STAKING_DECIMALS);
-export const HL_SIGNATURE_CHAIN_ID = "0xa4b1"; // Arbitrum One, per Hyperliquid user-signed action spec
-export const HL_UNSTAKING_QUEUE_DAYS = 7;
-export const HL_VALIDATOR_LOCKUP_DAYS = 1;
-// The signed action encodes wei as uint64.
-export const MAX_UINT64 = 2n ** 64n - 1n;
-
-function exchangeUrl(opts = {}) {
-  if (opts.exchangeUrl) return opts.exchangeUrl;
-  if (process.env.HL_EXCHANGE_URL) return process.env.HL_EXCHANGE_URL;
-  const testnet = opts.testnet || process.env.HL_TESTNET === "1";
-  return testnet ? "https://api.hyperliquid-testnet.xyz/exchange" : "https://api.hyperliquid.xyz/exchange";
-}
-
-function hyperliquidChain(opts = {}) {
-  return opts.testnet || process.env.HL_TESTNET === "1" ? "Testnet" : "Mainnet";
-}
-
-function evmAddress(value, label) {
-  const addr = String(value || "").trim();
-  if (!/^0x[0-9a-fA-F]{40}$/.test(addr)) throw new Error(`hl-staking: ${label} must be a 0x EVM address`);
-  return addr.toLowerCase();
-}
-
-/** HYPE amount (decimal string or number) -> integer wei string at 8 decimals. */
-export function hypeToWei(amount, label = "amount") {
-  const text = String(amount ?? "").trim();
-  if (!/^\d+(\.\d+)?$/.test(text)) throw new Error(`hl-staking: ${label} must be a positive decimal HYPE amount`);
-  const [whole, frac = ""] = text.split(".");
-  if (frac.length > HYPE_STAKING_DECIMALS) {
-    throw new Error(`hl-staking: ${label} has more than ${HYPE_STAKING_DECIMALS} decimals`);
-  }
-  const wei = BigInt(whole) * HYPE_WEI_PER_TOKEN + BigInt((frac + "0".repeat(HYPE_STAKING_DECIMALS)).slice(0, HYPE_STAKING_DECIMALS) || "0");
-  if (wei <= 0n) throw new Error(`hl-staking: ${label} must be greater than zero`);
-  if (wei > MAX_UINT64) throw new Error(`hl-staking: ${label} exceeds the uint64 range the signed action encodes`);
-  return wei.toString();
-}
-
-/**
- * The EIP-712 field is uint64. JavaScript's Number loses integer precision
- * above 2^53, so passing Number(wei) can hand the wallet a DIFFERENT amount
- * than the one Oracle prepared and displayed. Keep wei exact: emit a JS number
- * only while it is provably lossless, otherwise emit the decimal string, which
- * every EIP-712 encoder accepts for uintN.
- */
-function exactWei(weiString) {
-  const n = BigInt(weiString);
-  return n <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(n) : weiString;
-}
-
-export function weiToHype(wei) {
-  const n = BigInt(String(wei || "0"));
-  const whole = n / HYPE_WEI_PER_TOKEN;
-  const frac = (n % HYPE_WEI_PER_TOKEN).toString().padStart(HYPE_STAKING_DECIMALS, "0").replace(/0+$/, "");
-  return frac ? `${whole}.${frac}` : String(whole);
-}
-
-// ---------------------------------------------------------------- reads
-
-export async function hlStakingHealth(opts = {}) {
-  try {
-    const validators = await hlValidatorSummaries(opts);
-    return {
-      ok: validators.count > 0,
-      provider: "hl-staking",
-      chain: hyperliquidChain(opts),
-      validators: validators.count,
-      exec: false,
-    };
-  } catch (error) {
-    return { ok: false, provider: "hl-staking", error: String(error?.message || error).slice(0, 160), exec: false };
-  }
-}
-
-export async function hlValidatorSummaries(opts = {}) {
-  const raw = await hlInfo({ type: "validatorSummaries" }, opts);
-  const list = Array.isArray(raw) ? raw : [];
-  const validators = list.map((v) => ({
-    validator: v.validator ?? null,
-    name: v.name ?? null,
-    isActive: v.isActive ?? null,
-    isJailed: v.isJailed ?? null,
-    commission: v.commission ?? null,
-    stake: v.stake ?? null,
-    nRecentBlocks: v.nRecentBlocks ?? null,
-  }));
-  return { provider: "hl-staking", count: validators.length, validators, exec: false, raw };
-}
-
-export async function hlDelegatorSummary(args = {}, opts = {}) {
-  const user = evmAddress(args.user || args.address, "user");
-  const raw = await hlInfo({ type: "delegatorSummary", user }, opts);
-  return {
-    provider: "hl-staking",
-    user,
-    delegatedWei: raw?.delegated ?? null,
-    undelegatedWei: raw?.undelegated ?? null,
-    totalPendingWithdrawalWei: raw?.totalPendingWithdrawal ?? null,
-    nPendingWithdrawals: raw?.nPendingWithdrawals ?? null,
-    delegatedHype: raw?.delegated != null ? String(raw.delegated) : null,
-    undelegatedHype: raw?.undelegated != null ? String(raw.undelegated) : null,
-    exec: false,
-    raw,
-  };
-}
-
-export async function hlDelegations(args = {}, opts = {}) {
-  const user = evmAddress(args.user || args.address, "user");
-  const raw = await hlInfo({ type: "delegations", user }, opts);
-  const list = Array.isArray(raw) ? raw : [];
-  return {
-    provider: "hl-staking",
-    user,
-    count: list.length,
-    delegations: list.map((d) => ({
-      validator: d.validator ?? null,
-      amount: d.amount ?? null,
-      lockedUntilTimestamp: d.lockedUntilTimestamp ?? null,
-    })),
-    exec: false,
-    raw,
-  };
-}
-
-export async function hlDelegatorRewards(args = {}, opts = {}) {
-  const user = evmAddress(args.user || args.address, "user");
-  const raw = await hlInfo({ type: "delegatorRewards", user }, opts);
-  return { provider: "hl-staking", user, rewards: Array.isArray(raw) ? raw : [], exec: false };
-}
-
-export async function hlDelegatorHistory(args = {}, opts = {}) {
-  const user = evmAddress(args.user || args.address, "user");
-  const raw = await hlInfo({ type: "delegatorHistory", user }, opts);
-  return { provider: "hl-staking", user, history: Array.isArray(raw) ? raw : [], exec: false };
-}
-
-// ------------------------------------------------------------- prepares
-
-function nonceNow(args = {}) {
-  const n = args.nonce == null ? Date.now() : Number(args.nonce);
-  if (!Number.isInteger(n) || n <= 0) throw new Error("hl-staking: nonce must be a positive integer ms timestamp");
-  return n;
-}
-
-function signatureChainId(opts = {}) {
-  return String(opts.signatureChainId || process.env.HL_SIGNATURE_CHAIN_ID || HL_SIGNATURE_CHAIN_ID);
-}
-
-function eip712Domain(opts = {}) {
-  return {
-    name: "HyperliquidSignTransaction",
-    version: "1",
-    chainId: Number(BigInt(signatureChainId(opts))),
-    verifyingContract: "0x0000000000000000000000000000000000000000",
-  };
-}
-
-function preparedAction({ kind, action, types, primaryType, message, opts, notes, caps }) {
-  return stampPrepared({
-    provider: "hl-staking",
-    venue: "hypercore",
-    chain: hyperliquidChain(opts),
-    kind,
-    prepareReady: true,
-    executionReady: false,
-    signingReady: false,
-    broadcastReady: false,
-    requiresUserSignature: true,
-    signWith: "user wallet (EIP-712 typed data)",
-    submitTo: exchangeUrl(opts),
-    submitShape: { action, nonce: action.nonce, signature: "<user 65-byte signature>" },
-    action,
-    typedData: {
-      domain: eip712Domain(opts),
-      types,
-      primaryType,
-      message,
-    },
-    caps: caps || null,
-    notes,
-    exec: false,
-  }, { provider: "hl-staking", kind });
-}
-
-/** spot HYPE -> staking balance. Instant. */
-export function hlPrepareStakeDeposit(args = {}, opts = {}) {
-  const wei = hypeToWei(args.amountHype ?? args.amount, "amountHype");
-  const maxHype = args.maxHype == null ? null : hypeToWei(args.maxHype, "maxHype");
-  if (maxHype && BigInt(wei) > BigInt(maxHype)) {
-    throw new Error(`hl-staking: amount ${weiToHype(wei)} HYPE exceeds maxHype cap ${weiToHype(maxHype)} HYPE`);
-  }
-  const nonce = nonceNow(args);
-  const chain = hyperliquidChain(opts);
-  const action = {
-    type: "cDeposit",
-    hyperliquidChain: chain,
-    signatureChainId: signatureChainId(opts),
-    wei: exactWei(wei),
-    nonce,
-  };
-  return preparedAction({
-    kind: "hype-stake-deposit",
-    action,
-    primaryType: "HyperliquidTransaction:CDeposit",
-    types: {
-      "HyperliquidTransaction:CDeposit": [
-        { name: "hyperliquidChain", type: "string" },
-        { name: "wei", type: "uint64" },
-        { name: "nonce", type: "uint64" },
-      ],
-    },
-    message: { hyperliquidChain: chain, wei: exactWei(wei), nonce },
-    opts,
-    caps: { amountHype: weiToHype(wei), maxHype: maxHype ? weiToHype(maxHype) : null },
-    notes: [
-      "Moves HYPE from your Hyperliquid spot balance into your staking balance.",
-      "Staking balance still earns nothing until it is delegated to a validator.",
-      "Oracle prepared this. Your wallet signs it. Nothing was submitted.",
-    ],
-  });
-}
-
-/** staking balance -> spot HYPE. Enters the 7 day unstaking queue. */
-export function hlPrepareStakeWithdraw(args = {}, opts = {}) {
-  const wei = hypeToWei(args.amountHype ?? args.amount, "amountHype");
-  const nonce = nonceNow(args);
-  const chain = hyperliquidChain(opts);
-  const action = {
-    type: "cWithdraw",
-    hyperliquidChain: chain,
-    signatureChainId: signatureChainId(opts),
-    wei: exactWei(wei),
-    nonce,
-  };
-  return preparedAction({
-    kind: "hype-stake-withdraw",
-    action,
-    primaryType: "HyperliquidTransaction:CWithdraw",
-    types: {
-      "HyperliquidTransaction:CWithdraw": [
-        { name: "hyperliquidChain", type: "string" },
-        { name: "wei", type: "uint64" },
-        { name: "nonce", type: "uint64" },
-      ],
-    },
-    message: { hyperliquidChain: chain, wei: exactWei(wei), nonce },
-    opts,
-    caps: { amountHype: weiToHype(wei) },
-    notes: [
-      `Starts the ${HL_UNSTAKING_QUEUE_DAYS} day unstaking queue back to spot. The HYPE is not liquid during the queue.`,
-      "Undelegate from the validator first: only undelegated staking balance can be withdrawn.",
-      "Oracle prepared this. Your wallet signs it. Nothing was submitted.",
-    ],
-  });
-}
-
-/** staking balance <-> validator. isUndelegate=false stakes, true unstakes. */
-export function hlPrepareDelegate(args = {}, opts = {}) {
-  const validator = evmAddress(args.validator, "validator");
-  const wei = hypeToWei(args.amountHype ?? args.amount, "amountHype");
-  const isUndelegate = Boolean(args.isUndelegate ?? args.undelegate ?? false);
-  const maxHype = args.maxHype == null ? null : hypeToWei(args.maxHype, "maxHype");
-  if (!isUndelegate && maxHype && BigInt(wei) > BigInt(maxHype)) {
-    throw new Error(`hl-staking: delegate amount ${weiToHype(wei)} HYPE exceeds maxHype cap ${weiToHype(maxHype)} HYPE`);
-  }
-  const nonce = nonceNow(args);
-  const chain = hyperliquidChain(opts);
-  const action = {
-    type: "tokenDelegate",
-    hyperliquidChain: chain,
-    signatureChainId: signatureChainId(opts),
-    validator,
-    wei: exactWei(wei),
-    isUndelegate,
-    nonce,
-  };
-  return preparedAction({
-    kind: isUndelegate ? "hype-undelegate" : "hype-delegate",
-    action,
-    primaryType: "HyperliquidTransaction:TokenDelegate",
-    types: {
-      "HyperliquidTransaction:TokenDelegate": [
-        { name: "hyperliquidChain", type: "string" },
-        { name: "validator", type: "address" },
-        { name: "wei", type: "uint64" },
-        { name: "isUndelegate", type: "bool" },
-        { name: "nonce", type: "uint64" },
-      ],
-    },
-    message: { hyperliquidChain: chain, validator, wei: exactWei(wei), isUndelegate, nonce },
-    opts,
-    caps: { amountHype: weiToHype(wei), maxHype: maxHype ? weiToHype(maxHype) : null, validator },
-    notes: isUndelegate
-      ? [
-          "Returns stake from the validator to your staking balance.",
-          `Delegations carry a ${HL_VALIDATOR_LOCKUP_DAYS} day validator lockup before they can be undelegated.`,
-          "Oracle prepared this. Your wallet signs it. Nothing was submitted.",
-        ]
-      : [
-          "Delegates staking balance to the chosen validator so it starts earning.",
-          `Once delegated, the stake is locked with that validator for ${HL_VALIDATOR_LOCKUP_DAYS} day.`,
-          "Check the validator's commission and jail status before delegating.",
-          "Oracle prepared this. Your wallet signs it. Nothing was submitted.",
-        ],
-  });
-}
-
-/**
- * Read-only preflight: does the user actually hold enough in the right bucket
- * for the requested stake/unstake move? Never mutates anything.
- */
-export async function hlStakingPreflight(args = {}, opts = {}) {
-  const user = evmAddress(args.user || args.address, "user");
-  const summary = await hlDelegatorSummary({ user }, opts);
-  const delegations = await hlDelegations({ user }, opts);
-  return {
-    provider: "hl-staking",
-    user,
-    stakingBalanceUndelegated: summary.undelegatedWei,
-    stakingBalanceDelegated: summary.delegatedWei,
-    pendingWithdrawals: summary.nPendingWithdrawals,
-    delegations: delegations.delegations,
-    unstakingQueueDays: HL_UNSTAKING_QUEUE_DAYS,
-    validatorLockupDays: HL_VALIDATOR_LOCKUP_DAYS,
-    exec: false,
-  };
-}
-
-/** Never used by Oracle itself. Exposed so a self-hoster can see the exact submit shape. */
-export function hlStakingSubmitShape(opts = {}) {
-  return {
-    method: "POST",
-    url: exchangeUrl(opts),
-    body: { action: "<prepared action>", nonce: "<action.nonce>", signature: "<user signature r/s/v>" },
-    note: "Oracle does not submit this. The signing wallet or its owner posts it. There is deliberately no submit function in this module.",
-  };
-}

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

@@ -1,119 +0,0 @@
-// Short-lived Hyperliquid WebSocket snapshots (subscribe → first payload → close).
-// No long-running daemon; safe for desk HTTP handlers.
-
-const HL_WS = process.env.HL_WS_URL || "wss://api.hyperliquid.xyz/ws";
-
-/**
- * @param {object} subscription e.g. { type: 'allMids' } | { type: 'l2Book', coin: 'BTC' }
- * @param {object} [opts]
- * @param {number} [opts.timeoutMs]
- * @param {number} [opts.maxMessages] stop after N data messages (default 1)
- */
-export async function hlWsSnapshot(subscription, opts = {}) {
-  if (!subscription?.type) throw new Error("hlWsSnapshot requires subscription.type");
-  const timeoutMs = opts.timeoutMs ?? 8_000;
-  const maxMessages = opts.maxMessages ?? 1;
-  const WebSocketImpl = opts.WebSocket || globalThis.WebSocket;
-  if (!WebSocketImpl) throw new Error("WebSocket not available in this runtime");
-
-  const url = opts.url || HL_WS;
-  const started = Date.now();
-
-  return new Promise((resolve, reject) => {
-    let settled = false;
-    const messages = [];
-    let dataCount = 0;
-    const ws = new WebSocketImpl(url);
-    const timer = setTimeout(() => {
-      cleanup();
-      if (!settled) {
-        settled = true;
-        if (messages.length) {
-          resolve({ ok: true, partial: true, ms: Date.now() - started, messages });
-        } else {
-          reject(new Error(`hl ws timeout after ${timeoutMs}ms`));
-        }
-      }
-    }, timeoutMs);
-
-    function cleanup() {
-      clearTimeout(timer);
-      try {
-        ws.close();
-      } catch {
-        /* ignore */
-      }
-    }
-
-    ws.addEventListener("open", () => {
-      ws.send(JSON.stringify({ method: "subscribe", subscription }));
-    });
-
-    ws.addEventListener("message", (ev) => {
-      let data;
-      try {
-        data = JSON.parse(typeof ev.data === "string" ? ev.data : String(ev.data));
-      } catch {
-        data = { raw: String(ev.data).slice(0, 200) };
-      }
-      messages.push(data);
-      // skip pure subscriptionResponse for counting "data"
-      if (data.channel && data.channel !== "subscriptionResponse") {
-        dataCount += 1;
-      } else if (data.data && data.channel === "subscriptionResponse") {
-        // ignore ack
-      } else if (!data.channel) {
-        dataCount += 1;
-      }
-      if (dataCount >= maxMessages) {
-        cleanup();
-        if (!settled) {
-          settled = true;
-          resolve({
-            ok: true,
-            ms: Date.now() - started,
-            subscription,
-            messages,
-            last: messages[messages.length - 1],
-          });
-        }
-      }
-    });
-
-    ws.addEventListener("error", () => {
-      cleanup();
-      if (!settled) {
-        settled = true;
-        reject(new Error("hl ws error"));
-      }
-    });
-  });
-}
-
-export async function hlWsHealth(opts = {}) {
-  try {
-    const snap = await hlWsSnapshot({ type: "allMids" }, { ...opts, maxMessages: 1 });
-    const last = snap.last || {};
-    const mids = last.data?.mids || last.data || {};
-    const n = typeof mids === "object" ? Object.keys(mids).length : 0;
-    return { ok: true, ms: snap.ms, midCount: n, channel: last.channel || null };
-  } catch (e) {
-    return { ok: false, error: String(e.message || e).slice(0, 160) };
-  }
-}
-
-export async function hlWsAllMids(opts = {}) {
-  const snap = await hlWsSnapshot({ type: "allMids" }, opts);
-  const last = snap.last || {};
-  return {
-    ms: snap.ms,
-    mids: last.data?.mids || last.data || {},
-    channel: last.channel,
-  };
-}
-
-export async function hlWsL2Book(coin, opts = {}) {
-  if (!coin) throw new Error("coin required");
-  const snap = await hlWsSnapshot({ type: "l2Book", coin: String(coin) }, opts);
-  return { ms: snap.ms, book: snap.last?.data || snap.last, channel: snap.last?.channel };
-}

package/src/data/providers/hyperevm-dex.mjs

@@ -1,49 +0,0 @@
-// HyperEVM (chain 999) discovery via DexScreener + optional RPC health.
-// No dedicated public Uniswap QuoterV2 on HyperEVM assumed.
-
-import { dexscreenerSearch, dexscreenerToken } from "./dexscreener.mjs";
-import { rpcHealth } from "./evm-rpc.mjs";
-
-export const HYPEREVM_CHAIN_ID = 999;
-
-export async function hyperevmHealth(opts = {}) {
-  const out = { chainId: HYPEREVM_CHAIN_ID, rpc: null, dex: null };
-  try {
-    out.rpc = await rpcHealth(HYPEREVM_CHAIN_ID, opts);
-  } catch (e) {
-    out.rpc = { ok: false, error: String(e.message || e).slice(0, 120) };
-  }
-  try {
-    const s = await dexscreenerSearch("HYPE", opts);
-    const pairs = (s.pairs || []).filter((p) =>
-      /hyper|hl|hyperevm/i.test(String(p.chainId || p.chain || ""))
-    );
-    out.dex = {
-      ok: true,
-      hypePairs: pairs.length || (s.pairs || []).length,
-      sample: (pairs[0] || s.pairs?.[0])?.pairAddress || null,
-    };
-  } catch (e) {
-    out.dex = { ok: false, error: String(e.message || e).slice(0, 120) };
-  }
-  return {
-    ok: Boolean(out.rpc?.ok || out.dex?.ok),
-    ...out,
-  };
-}
-
-export async function hyperevmSearch(q = "HYPE", opts = {}) {
-  const s = await dexscreenerSearch(q, opts);
-  const pairs = s.pairs || [];
-  const hl = pairs.filter((p) => /hyper|hl|hyperevm/i.test(String(p.chainId || "")));
-  return {
-    query: q,
-    hyperPairs: hl,
-    allPairs: pairs.slice(0, 20),
-    count: hl.length || pairs.length,
-  };
-}
-
-export async function hyperevmToken(address, opts = {}) {
-  return dexscreenerToken(address, opts);
-}