@oracle-agent/oracle 0.13.1 → 0.14.0

package/src/equities/normalize.mjs

@@ -0,0 +1,295 @@
+// Symbol normalization for Oracle Equities.
+//
+// Every venue names the same underlying differently. This module resolves all of
+// those forms to ONE canonical Oracle symbol so the ranking engine compares like
+// with like.
+//
+// The governing rule is FAIL CLOSED. A wrong symbol match does not produce a
+// missing row, it produces a FABRICATED one: two different assets get differenced
+// and printed as an arbitrage that does not exist. Concretely, in the captured
+// fixtures the ticker "LIT" appears on hyperliquid_hip3 (dex hyna, mark 3.37) and
+// on arcus perps (mark 2.0379). A naive canonicalization merges them and prints a
+// ~6536bp spread. Those are two different underlyings sharing three letters. The
+// same trap exists for SKHX (1169.2) versus SKHY (153.61), both live on dex xyz.
+//
+// So: we never guess. Unknown or contested input returns
+// { ambiguous: true, candidates: [...] } and the caller must either supply an
+// explicit assetClass assertion or drop the row.
+//
+// Zero runtime dependencies. Node builtins only, via src/fixtures.mjs.
+
+import { getUniverse, getVenues } from './fixtures.mjs';
+
+// ---------------------------------------------------------------------------
+// canonical universe, sourced from fixtures/universe.json (the authority)
+// ---------------------------------------------------------------------------
+
+let canonicalSet;
+function canonical() {
+  canonicalSet ??= new Set(Object.keys(getUniverse()));
+  return canonicalSet;
+}
+
+let dexSet;
+function knownDexs() {
+  dexSet ??= new Set(Object.keys(getVenues().venues.hyperliquid_hip3.dexs));
+  return dexSet;
+}
+
+/**
+ * Symbols that mean genuinely DIFFERENT underlyings on different venues.
+ * Listed explicitly. Each entry must be disambiguated by the caller with an
+ * assetClass assertion, and even then the result is never cross venue comparable.
+ */
+export const CONTESTED_SYMBOLS = Object.freeze({
+  LIT: Object.freeze([
+    Object.freeze({
+      assetClass: 'etf',
+      description: 'Global X Lithium and Battery Tech ETF, an equity basket',
+      venues: Object.freeze(['hyperliquid_hip3']),
+    }),
+    Object.freeze({
+      assetClass: 'crypto',
+      description: 'a crypto perp listed under the same three letters',
+      venues: Object.freeze(['arcus']),
+    }),
+  ]),
+});
+
+/**
+ * Venue unique names: pre IPO markets and synthetic baskets that exist on exactly
+ * ONE venue in the captured fixtures. They map to themselves. They can never be
+ * cross venue ranked because there is no second venue to compare against.
+ *
+ * Derived from fixtures/venues.json: symbols on dex vntl that appear nowhere else.
+ * NOTE: WHEAT is on vntl AND xyz, so it is deliberately excluded here.
+ */
+export const VENUE_UNIQUE_SYMBOLS = Object.freeze([
+  'SPACEX',
+  'OPENAI',
+  'ANTHROPIC',
+  'MAG7',
+  'SEMIS',
+  'ROBOT',
+  'INFOTECH',
+  'NUCLEAR',
+  'DEFENSE',
+  'ENERGY',
+  'BIOTECH',
+  'GOLDJM',
+  'SILVERJM',
+  'SOY',
+]);
+
+const VENUE_UNIQUE_SET = new Set(VENUE_UNIQUE_SYMBOLS);
+
+/**
+ * Allowlist for the lowercase x suffix (Solana xStocks style: NVDAx -> NVDA).
+ * The suffix is stripped ONLY for these bases, so a genuine ticker ending in a
+ * lowercase x is never mangled. No fixture currently exercises this with real
+ * data (no Solana or TON venue was captured), but the rule is cheap and correct
+ * and a future adapter needs it.
+ */
+export const XSTOCK_BASE_ALLOWLIST = Object.freeze([
+  'NVDA',
+  'TSLA',
+  'SPY',
+  'AAPL',
+  'COIN',
+  'AMZN',
+  'GOOGL',
+  'MSFT',
+]);
+
+const XSTOCK_BASE_SET = new Set(XSTOCK_BASE_ALLOWLIST);
+
+const QUOTE_SUFFIXES = Object.freeze(['-USD', '-USDC', '-USDT', '-PERP']);
+
+// ---------------------------------------------------------------------------
+// result shape
+// ---------------------------------------------------------------------------
+
+function resolved(symbolRaw, symbol, extra = {}) {
+  return Object.freeze({
+    ok: true,
+    ambiguous: false,
+    symbol,
+    symbolRaw,
+    dex: extra.dex ?? null,
+    applied: Object.freeze(extra.applied ?? []),
+    venueUnique: extra.venueUnique ?? false,
+    contested: extra.contested ?? false,
+    crossVenueComparable: extra.crossVenueComparable ?? true,
+    candidates: Object.freeze([]),
+    reason: null,
+  });
+}
+
+function unresolved(symbolRaw, reason, candidates = []) {
+  return Object.freeze({
+    ok: false,
+    ambiguous: true,
+    symbol: null,
+    symbolRaw: typeof symbolRaw === 'string' ? symbolRaw : null,
+    dex: null,
+    applied: Object.freeze([]),
+    venueUnique: false,
+    contested: false,
+    crossVenueComparable: false,
+    candidates: Object.freeze(candidates.map((c) => Object.freeze({ ...c }))),
+    reason,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// public helpers
+// ---------------------------------------------------------------------------
+
+export function listCanonicalSymbols() {
+  return [...canonical()];
+}
+
+export function isCanonical(symbol) {
+  return typeof symbol === 'string' && canonical().has(symbol);
+}
+
+/**
+ * Resolve a venue specific symbol form to its canonical Oracle symbol.
+ *
+ * @param {string} input        raw venue symbol, e.g. "xyz:NVDA", "NVDA-USD", "NVDAx"
+ * @param {object} [options]
+ * @param {string} [options.assetClass]  explicit assertion required to resolve a
+ *                                       contested ticker. Never inferred.
+ * @returns {object} frozen resolution record. Check `.ok` before using `.symbol`.
+ */
+export function normalizeSymbol(input, options = {}) {
+  if (typeof input !== 'string') {
+    return unresolved(input, 'input must be a string');
+  }
+
+  const trimmed = input.trim();
+  if (trimmed.length === 0) {
+    return unresolved(input, 'input must be a nonempty symbol');
+  }
+
+  const applied = [];
+  let working = trimmed;
+  let dex = null;
+
+  // 1. dex namespace strip, allowlisted against the real HIP-3 dex list.
+  const colon = working.indexOf(':');
+  if (colon !== -1) {
+    const prefix = working.slice(0, colon);
+    const rest = working.slice(colon + 1);
+    if (prefix.length === 0 || rest.length === 0) {
+      return unresolved(input, 'malformed dex namespace');
+    }
+    if (!knownDexs().has(prefix)) {
+      return unresolved(input, `unknown dex namespace "${prefix}"`, [
+        {
+          assetClass: 'unknown',
+          description: `no HIP-3 dex named "${prefix}" in the captured fixtures`,
+          venues: [],
+        },
+      ]);
+    }
+    dex = prefix;
+    working = rest;
+    applied.push('dex-namespace-strip');
+  }
+
+  // 2. quote suffix strip (-USD and friends), case insensitive on the suffix only.
+  for (const suffix of QUOTE_SUFFIXES) {
+    if (working.length > suffix.length && working.toUpperCase().endsWith(suffix)) {
+      working = working.slice(0, working.length - suffix.length);
+      applied.push('quote-suffix-strip');
+      break;
+    }
+  }
+
+  // 3. lowercase x suffix strip, allowlist gated so a real ticker ending in a
+  //    lowercase x is never mangled. Uppercase X is NOT a suffix (see SKHX).
+  if (working.endsWith('x')) {
+    const base = working.slice(0, -1);
+    if (XSTOCK_BASE_SET.has(base)) {
+      working = base;
+      applied.push('xstock-suffix-strip');
+    }
+    // Not allowlisted: leave it alone and let the canonical check decide.
+  }
+
+  if (working.length === 0) {
+    return unresolved(input, 'symbol empty after transforms');
+  }
+
+  // 4. venue unique names (pre IPO, baskets) map to themselves.
+  if (VENUE_UNIQUE_SET.has(working)) {
+    return resolved(trimmed, working, {
+      dex,
+      applied,
+      venueUnique: true,
+      crossVenueComparable: false,
+    });
+  }
+
+  // 5. contested tickers: never guessed, require an explicit assetClass.
+  if (Object.hasOwn(CONTESTED_SYMBOLS, working)) {
+    const candidates = CONTESTED_SYMBOLS[working];
+    const asserted = options.assetClass;
+    if (typeof asserted !== 'string' || asserted.length === 0) {
+      return unresolved(
+        input,
+        `"${working}" names different underlyings on different venues, ` +
+          'caller must assert assetClass',
+        candidates,
+      );
+    }
+    const match = candidates.find((c) => c.assetClass === asserted);
+    if (!match) {
+      return unresolved(
+        input,
+        `assetClass "${asserted}" matches no known underlying for "${working}"`,
+        candidates,
+      );
+    }
+    return resolved(trimmed, working, {
+      dex,
+      applied,
+      contested: true,
+      crossVenueComparable: false,
+    });
+  }
+
+  // 6. canonical universe check. This is the fail closed gate.
+  if (canonical().has(working)) {
+    return resolved(trimmed, working, { dex, applied });
+  }
+
+  return unresolved(
+    input,
+    `"${working}" is not in the canonical universe, refusing to guess`,
+    nearMissCandidates(working),
+  );
+}
+
+/**
+ * Suggest canonical symbols a caller might have meant, WITHOUT resolving to them.
+ * Suggestions are diagnostic only. They are deliberately not auto applied: that is
+ * exactly the fuzzy step that fabricates spreads.
+ */
+function nearMissCandidates(working) {
+  const upper = working.toUpperCase();
+  const out = [];
+  for (const symbol of canonical()) {
+    if (symbol === upper) continue;
+    if (symbol.startsWith(upper) || upper.startsWith(symbol)) {
+      out.push({
+        assetClass: 'unknown',
+        description: `canonical "${symbol}" shares a prefix, not auto applied`,
+        venues: [],
+      });
+    }
+    if (out.length >= 5) break;
+  }
+  return out;
+}

package/src/equities/num.mjs

@@ -0,0 +1,146 @@
+const MAX_SCALE = 1000;
+const TEN_THOUSAND = Object.freeze({ mantissa: 10000n, scale: 0 });
+
+function assertScale(scale) {
+  if (!Number.isSafeInteger(scale) || scale < 0 || scale > MAX_SCALE) {
+    throw new RangeError(`scale must be a safe integer from 0 through ${MAX_SCALE}`);
+  }
+}
+
+function fixed(mantissa, scale) {
+  if (typeof mantissa !== 'bigint') {
+    throw new TypeError('mantissa must be a bigint');
+  }
+  assertScale(scale);
+  return Object.freeze({ mantissa, scale });
+}
+
+function assertFixed(value, name = 'value') {
+  if (value === null || typeof value !== 'object') {
+    throw new TypeError(`${name} must be a fixed point value`);
+  }
+  if (typeof value.mantissa !== 'bigint') {
+    throw new TypeError(`${name}.mantissa must be a bigint`);
+  }
+  assertScale(value.scale);
+}
+
+function pow10(scale) {
+  assertScale(scale);
+  return 10n ** BigInt(scale);
+}
+
+export function parseDecimal(value) {
+  if (typeof value !== 'string' || !/^[+-]?\d+(?:\.\d+)?$/.test(value)) {
+    throw new TypeError('value must be a plain decimal string');
+  }
+
+  const negative = value.startsWith('-');
+  const unsigned = value[0] === '-' || value[0] === '+' ? value.slice(1) : value;
+  const [whole, fraction = ''] = unsigned.split('.');
+  const digits = `${whole}${fraction}`;
+  const mantissa = BigInt(digits) * (negative ? -1n : 1n);
+
+  return fixed(mantissa, fraction.length);
+}
+
+export function fromScaledInteger(value, scale) {
+  assertScale(scale);
+  if (typeof value === 'bigint') {
+    return fixed(value, scale);
+  }
+  if (typeof value !== 'string' || !/^[+-]?\d+$/.test(value)) {
+    throw new TypeError('value must be an integer string or bigint');
+  }
+  return fixed(BigInt(value), scale);
+}
+
+export function toString(value) {
+  assertFixed(value);
+  const negative = value.mantissa < 0n;
+  const digits = (negative ? -value.mantissa : value.mantissa).toString();
+
+  if (value.scale === 0) {
+    return `${negative ? '-' : ''}${digits}`;
+  }
+
+  const padded = digits.padStart(value.scale + 1, '0');
+  const splitAt = padded.length - value.scale;
+  return `${negative ? '-' : ''}${padded.slice(0, splitAt)}.${padded.slice(splitAt)}`;
+}
+
+export function rescale(value, targetScale) {
+  assertFixed(value);
+  assertScale(targetScale);
+
+  if (targetScale === value.scale) {
+    return fixed(value.mantissa, value.scale);
+  }
+  if (targetScale > value.scale) {
+    return fixed(value.mantissa * pow10(targetScale - value.scale), targetScale);
+  }
+  return fixed(value.mantissa / pow10(value.scale - targetScale), targetScale);
+}
+
+function align(left, right) {
+  assertFixed(left, 'left');
+  assertFixed(right, 'right');
+  const scale = Math.max(left.scale, right.scale);
+  return [rescale(left, scale), rescale(right, scale), scale];
+}
+
+export function add(left, right) {
+  const [a, b, scale] = align(left, right);
+  return fixed(a.mantissa + b.mantissa, scale);
+}
+
+export function sub(left, right) {
+  const [a, b, scale] = align(left, right);
+  return fixed(a.mantissa - b.mantissa, scale);
+}
+
+export function mul(left, right) {
+  assertFixed(left, 'left');
+  assertFixed(right, 'right');
+  const scale = left.scale + right.scale;
+  assertScale(scale);
+  return fixed(left.mantissa * right.mantissa, scale);
+}
+
+export function div(left, right, resultScale = Math.max(left?.scale ?? 0, right?.scale ?? 0)) {
+  assertFixed(left, 'left');
+  assertFixed(right, 'right');
+  assertScale(resultScale);
+  if (right.mantissa === 0n) {
+    throw new RangeError('division by zero');
+  }
+
+  const numerator = left.mantissa * pow10(right.scale + resultScale);
+  const denominator = right.mantissa * pow10(left.scale);
+  return fixed(numerator / denominator, resultScale);
+}
+
+export function cmp(left, right) {
+  const [a, b] = align(left, right);
+  if (a.mantissa < b.mantissa) return -1;
+  if (a.mantissa > b.mantissa) return 1;
+  return 0;
+}
+
+export function spreadBps(value, reference, resultScale = 8) {
+  const delta = sub(value, reference);
+  return div(mul(delta, TEN_THOUSAND), reference, resultScale);
+}
+
+export function applyBps(value, bps, resultScale = value?.scale ?? 0) {
+  assertFixed(value);
+  assertFixed(bps, 'bps');
+  assertScale(resultScale);
+
+  const factor = fixed(10000n * pow10(bps.scale) + bps.mantissa, bps.scale);
+  return div(mul(value, factor), TEN_THOUSAND, resultScale);
+}
+
+export function formatUsd(value) {
+  return `$${toString(rescale(value, 2))}`;
+}

package/src/equities/prepare.mjs

@@ -0,0 +1,95 @@
+// Prepare-only artifact builder for RH Uniswap routes.
+// Emits unsigned transaction descriptors. Contains zero signing code and zero
+// key handling by construction. Refuses quote-only routes and stale quotes.
+
+import { quote as rhQuote } from './venues/rh-uniswap.mjs';
+import { getRhPoolState } from './fixtures.mjs';
+
+export const FRESHNESS_MS = 120_000;
+
+// Uniswap V3 SwapRouter02 style exactInputSingle selector, placeholder encoding.
+// The real calldata builder lands when a full router address is pinned. For v1
+// we emit a structured intent the user wallet / higher layer can encode.
+const V3_ROUTER = '0x0000000000000000000000000000000000000000'; // not yet pinned
+const V4_POOL_MANAGER = '0x84b75b19A3cdf8E2F56d0507d22D442847B2053C';
+
+/**
+ * Prepare an unsigned swap artifact for a RH Uniswap equity pool.
+ *
+ * @param {object} opts
+ * @param {string} opts.symbol
+ * @param {'buy'|'sell'} [opts.side]
+ * @param {object} [opts.sizeUsd]   fixed point
+ * @param {number} [opts.nowMs]
+ * @param {string} opts.recipient   user wallet, required
+ */
+export function prepare(opts = {}) {
+  const { symbol, side = 'buy', sizeUsd = null, recipient, nowMs = Date.now() } = opts;
+
+  if (typeof symbol !== 'string' || !symbol) {
+    throw new TypeError('symbol is required');
+  }
+  if (typeof recipient !== 'string' || !/^0x[0-9a-fA-F]{40}$/.test(recipient)) {
+    throw new TypeError('recipient must be a 0x-prefixed 20 byte address');
+  }
+
+  const q = rhQuote({ symbol, side, sizeUsd });
+  if (q === null) {
+    throw new Error(`no RH Uniswap pool for ${symbol}`);
+  }
+  if (q.tier !== 'prepare') {
+    throw new Error(`route tier is ${q.tier}, only prepare tier can be prepared`);
+  }
+
+  const ageMs = nowMs - q.capturedAt;
+  if (ageMs > FRESHNESS_MS) {
+    throw new Error(
+      `quote is stale (${ageMs}ms old, bound ${FRESHNESS_MS}ms); re-quote before preparing`,
+    );
+  }
+
+  const state = getRhPoolState();
+  const pool = state.pools[symbol];
+  const to = pool.version === 'v4' ? V4_POOL_MANAGER : V3_ROUTER;
+
+  // Approval target is the router/pool manager, NEVER the destination of funds.
+  const spender = to;
+  const token = side === 'buy' ? pool.quoteAddr : pool.token;
+
+  return Object.freeze({
+    artifactKind: 'unsigned-tx',
+    chainId: 4663,
+    to,
+    data: '0x', // calldata encoding is a follow up; structure is the contract
+    value: '0',
+    requiresApproval: {
+      spender,
+      token,
+      amount: null, // exact amount filled by the caller from size
+    },
+    requiresWalletSignature: true,
+    backendSigner: false,
+    unsigned: true,
+    houseSigned: false,
+    quoteRef: {
+      venue: q.venue,
+      symbol: q.symbol,
+      symbolRaw: q.symbolRaw,
+      capturedAt: q.capturedAt,
+      blockOrSeq: q.blockOrSeq,
+      mid: q.mid,
+      version: pool.version,
+      pair: pool.pair,
+    },
+    quoteAgeMs: ageMs,
+    recipient,
+    side,
+    notes: [
+      'prepare-only: user wallet must sign',
+      'calldata encoding is deferred; this artifact is the bound intent',
+      pool.version === 'v4'
+        ? 'V4 route via PoolManager'
+        : 'V3 route via SwapRouter (address not yet pinned)',
+    ],
+  });
+}