@oracle-agent/oracle 0.4.0 → 0.4.2

package/src/portfolio-risk.mjs

@@ -0,0 +1,170 @@
+// Pure portfolio exposure and coverage summary. This module performs no I/O.
+
+export const DEFAULT_RISK_THRESHOLDS = Object.freeze({
+  assetHighPct: 50,
+  assetMediumPct: 25,
+  chainHighPct: 75,
+  venueHighPct: 60,
+  stablecoinHighPct: 70,
+});
+
+const STABLECOINS = new Set(["USDC", "USDT", "USDT0", "DAI", "FRAX", "LUSD", "TUSD", "USDP", "GUSD", "PYUSD", "USDE"]);
+
+function finite(value) {
+  if (value === null || value === "" || value === undefined) return null;
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? number : null;
+}
+
+function rounded(value) {
+  return Math.round((value + Number.EPSILON) * 1e8) / 1e8;
+}
+
+function pct(value, total) {
+  return total > 0 ? rounded((value / total) * 100) : null;
+}
+
+function addressOf(snapshot) {
+  return snapshot.address || snapshot.owner || snapshot.walletAddress || snapshot.wallet?.address || null;
+}
+
+function labelIndex(labels) {
+  const entries = Array.isArray(labels) ? labels : Array.isArray(labels?.entries) ? labels.entries : [];
+  const index = new Map();
+  for (const entry of entries) {
+    if (!entry?.address) continue;
+    const key = String(entry.address).toLowerCase();
+    if (!index.has(key)) index.set(key, entry);
+  }
+  return index;
+}
+
+function addAsset(output, raw, context = {}) {
+  if (!raw || typeof raw !== "object") return;
+  const symbol = String(raw.symbol ?? raw.coin ?? raw.name ?? raw.collection ?? raw.tokenId ?? "unknown");
+  const value = finite(raw.usdValue ?? raw.valueUsd ?? raw.knownUsd ?? raw.estimatedValueUsd ?? raw.floorValueUsd);
+  const kind = raw.kind === "nft" || raw.type === "nft" || raw.collection || raw.tokenId != null ? "nft" : "fungible";
+  output.push({
+    symbol,
+    usdValue: value,
+    chain: String(raw.chain ?? raw.chainName ?? context.chain ?? "unknown"),
+    venue: String(raw.venue ?? raw.protocol ?? raw.platform ?? context.venue ?? "wallet"),
+    address: raw.address ?? context.address ?? null,
+    kind,
+    stablecoin: raw.stablecoin === true || STABLECOINS.has(symbol.toUpperCase()),
+  });
+}
+
+function assetsFromSnapshot(snapshot) {
+  const output = [];
+  const rootAddress = addressOf(snapshot);
+  for (const asset of snapshot.assets || snapshot.holdings || []) addAsset(output, asset, { address: rootAddress, chain: snapshot.chain, venue: snapshot.venue });
+  for (const chain of snapshot.chains || []) {
+    const chainName = chain.chain ?? chain.name ?? chain.slug ?? (chain.chainId != null ? String(chain.chainId) : chain.family) ?? "unknown";
+    const context = { address: chain.address ?? rootAddress, chain: chainName, venue: chain.venue };
+    if (chain.native && (chain.native.amount == null || Number(chain.native.amount) !== 0)) {
+      addAsset(output, { ...chain.native, symbol: chain.native.symbol ?? chain.symbol ?? chainName }, context);
+    }
+    for (const asset of chain.assets || chain.fungibleTokens?.assets || []) addAsset(output, asset, context);
+    for (const asset of chain.collectibles?.assets || chain.nfts || []) addAsset(output, { ...asset, kind: "nft" }, context);
+    for (const asset of chain.spot?.balances || []) addAsset(output, asset, { ...context, venue: "Hyperliquid spot" });
+    const accountValue = finite(chain.perps?.accountValueUsd);
+    if (accountValue != null) addAsset(output, { symbol: "perps account", usdValue: accountValue }, { ...context, venue: "Hyperliquid perps" });
+  }
+  for (const item of snapshot.inventory?.items || snapshot.nfts?.items || []) addAsset(output, { ...item, kind: "nft" }, { address: rootAddress, chain: item.chain ?? snapshot.chain, venue: item.marketplace ?? snapshot.venue });
+  return output;
+}
+
+function snapshotKey(snapshot, index) {
+  const address = addressOf(snapshot);
+  const chain = snapshot.chain ?? snapshot.chainId ?? snapshot.family ?? "*";
+  return address ? `${String(address).toLowerCase()}|${String(chain).toLowerCase()}` : `snapshot:${index}`;
+}
+
+function buckets(assets, property, total) {
+  const map = new Map();
+  for (const asset of assets) {
+    if (asset.usdValue == null) continue;
+    const name = asset[property];
+    map.set(name, (map.get(name) || 0) + asset.usdValue);
+  }
+  return [...map].map(([name, knownUsd]) => ({ name, knownUsd: rounded(knownUsd), percentOfKnown: pct(knownUsd, total) }))
+    .sort((a, b) => b.knownUsd - a.knownUsd || a.name.localeCompare(b.name));
+}
+
+/**
+ * Summarize already-fetched portfolio snapshots. Accepts either
+ * `{ snapshots, labels, thresholds }` or an array plus an options object.
+ */
+export function summarizePortfolioRisk(input = {}, options = {}) {
+  const snapshots = Array.isArray(input) ? input : Array.isArray(input.snapshots) ? input.snapshots : input.snapshot ? [input.snapshot] : [];
+  const labels = labelIndex(options.labels ?? options.addressBook ?? input.labels ?? input.addressBook);
+  const thresholds = { ...DEFAULT_RISK_THRESHOLDS, ...(input.thresholds || {}), ...(options.thresholds || {}) };
+  const unique = [];
+  const seen = new Set();
+  let duplicatesIgnored = 0;
+  snapshots.forEach((snapshot, index) => {
+    if (!snapshot || typeof snapshot !== "object") return;
+    const key = snapshotKey(snapshot, index);
+    if (seen.has(key)) duplicatesIgnored += 1;
+    else { seen.add(key); unique.push(snapshot); }
+  });
+
+  const assets = unique.flatMap(assetsFromSnapshot);
+  const priced = assets.filter((asset) => asset.usdValue != null);
+  const unknown = assets.filter((asset) => asset.usdValue == null);
+  const explicitUnknown = unique.reduce((sum, snapshot) => sum + Number(snapshot.valuation?.unpricedNonzeroItems || snapshot.unpricedNonzeroItems || 0), 0);
+  const totalKnownUsd = rounded(priced.reduce((sum, asset) => sum + asset.usdValue, 0));
+  const unknownItemCount = unknown.length + explicitUnknown;
+  const chainExposures = buckets(priced, "chain", totalKnownUsd);
+  const venueExposures = buckets(priced, "venue", totalKnownUsd);
+  const groupedAssets = buckets(priced, "symbol", totalKnownUsd);
+  for (const row of chainExposures) row.chain = row.name;
+  for (const row of venueExposures) row.venue = row.name;
+  for (const row of groupedAssets) {
+    row.asset = row.name;
+    row.symbol = row.name;
+  }
+  const stablecoinKnownUsd = rounded(priced.filter((asset) => asset.stablecoin).reduce((sum, asset) => sum + asset.usdValue, 0));
+  const nftAssets = assets.filter((asset) => asset.kind === "nft");
+  const snapshotNftUnvalued = unique.reduce((sum, snapshot) => sum + Number(snapshot.valuation?.nftUnvaluedItems || 0), 0);
+  const nftUnvaluedItems = nftAssets.filter((asset) => asset.usdValue == null).length + snapshotNftUnvalued;
+  const nftValuedItems = nftAssets.filter((asset) => asset.usdValue != null).length;
+  const top = groupedAssets[0] || null;
+  const concentrationLevel = !top ? "unknown" : top.percentOfKnown >= thresholds.assetHighPct ? "high" : top.percentOfKnown >= thresholds.assetMediumPct ? "medium" : "low";
+  const warnings = [];
+  if (unknownItemCount) warnings.push(`${unknownItemCount} nonzero holding(s) have unknown USD value; they are excluded from totals and percentages.`);
+  if (nftUnvaluedItems) warnings.push("NFT valuation coverage is partial; estimates are not executable bids and unvalued NFTs are not treated as zero.");
+  if (duplicatesIgnored) warnings.push(`${duplicatesIgnored} duplicate address/chain snapshot(s) were ignored.`);
+  if (top && concentrationLevel !== "low") warnings.push(`Asset concentration is ${concentrationLevel}: ${top.name} is ${top.percentOfKnown}% of known value.`);
+  if (chainExposures[0]?.percentOfKnown >= thresholds.chainHighPct) warnings.push(`Chain concentration is high: ${chainExposures[0].name} is ${chainExposures[0].percentOfKnown}% of known value.`);
+  if (venueExposures[0]?.percentOfKnown >= thresholds.venueHighPct) warnings.push(`Venue concentration is high: ${venueExposures[0].name} is ${venueExposures[0].percentOfKnown}% of known value.`);
+
+  const addresses = unique.map(addressOf).filter(Boolean).map((address) => {
+    const entry = labels.get(String(address).toLowerCase());
+    return { address, label: entry?.label ?? null, who: entry?.who ?? null, role: entry?.role ?? null };
+  });
+  return {
+    totalKnownUsd,
+    coverage: {
+      complete: unique.length > 0 && unknownItemCount === 0 && unique.every((snapshot) => snapshot.valuation?.complete !== false && snapshot.coverage?.complete !== false),
+      label: unknownItemCount === 0 && unique.length && unique.every((snapshot) => snapshot.valuation?.complete !== false && snapshot.coverage?.complete !== false)
+        ? "complete for the supplied snapshots" : "known priced value only; portfolio coverage is partial or unverified",
+      unknownUsd: unknownItemCount ? null : 0,
+      pricedItemCount: priced.length,
+      unknownItemCount,
+      snapshotCount: unique.length,
+      duplicatesIgnored,
+    },
+    chainExposures,
+    venueExposures,
+    topAssets: groupedAssets.slice(0, Math.max(1, Number(options.topAssets ?? input.topAssets ?? 10))),
+    concentrationRisk: { level: concentrationLevel, topAsset: top?.name ?? null, topAssetPercent: top?.percentOfKnown ?? null, thresholds: { mediumPct: thresholds.assetMediumPct, highPct: thresholds.assetHighPct } },
+    stablecoinExposure: { knownUsd: stablecoinKnownUsd, percentOfKnown: pct(stablecoinKnownUsd, totalKnownUsd), high: totalKnownUsd > 0 && pct(stablecoinKnownUsd, totalKnownUsd) >= thresholds.stablecoinHighPct },
+    nftCoverage: { status: nftAssets.length || snapshotNftUnvalued ? (nftUnvaluedItems ? "partial" : "valued") : "not-observed", valuedItems: nftValuedItems, unvaluedItems: nftUnvaluedItems, knownUsd: rounded(nftAssets.filter((asset) => asset.usdValue != null).reduce((sum, asset) => sum + asset.usdValue, 0)) },
+    addresses,
+    warnings: [...new Set(warnings)],
+  };
+}
+
+export const portfolioRiskSummary = summarizePortfolioRisk;

package/src/signals/engine.mjs

@@ -0,0 +1,146 @@
+const SIGNAL_TYPES = Object.freeze([
+  "wallet",
+  "pool",
+  "nft_floor",
+  "hl_flow",
+  "prediction_market",
+]);
+
+const TYPE_ALIASES = Object.freeze({
+  wallets: "wallet",
+  smart_wallet: "wallet",
+  pools: "pool",
+  new_pool: "pool",
+  nft: "nft_floor",
+  nft_floors: "nft_floor",
+  hyperliquid: "hl_flow",
+  prediction: "prediction_market",
+  prediction_markets: "prediction_market",
+});
+
+const clamp = (value, min = 0, max = 1) => Math.min(max, Math.max(min, value));
+const finite = (value) => (Number.isFinite(Number(value)) ? Number(value) : null);
+const round = (value) => Math.round(value * 10_000) / 10_000;
+
+function typeOf(event) {
+  const raw = String(event?.type ?? event?.surface ?? event?.kind ?? "").toLowerCase();
+  return TYPE_ALIASES[raw] ?? raw;
+}
+
+function idOf(event, index) {
+  return String(event?.id ?? event?.signalId ?? event?.asset ?? event?.market ?? event?.pool ?? event?.collection ?? `${typeOf(event)}:${index}`);
+}
+
+function add(contributions, feature, value, observed = true) {
+  if (!observed || value === null || !Number.isFinite(value)) return;
+  contributions.push({ feature, value: round(value) });
+}
+
+function walletFeatures(event, out) {
+  const buys = finite(event.repeatBuys ?? event.repeat_buys ?? event.buyCount);
+  const winRate = finite(event.walletWinRate ?? event.winRate);
+  add(out, "repeat_buys", buys === null ? null : clamp((buys - 1) / 4) * 0.38);
+  add(out, "wallet_win_rate", winRate === null ? null : (clamp(winRate) - 0.5) * 0.5);
+}
+
+function poolFeatures(event, out) {
+  const age = finite(event.ageHours ?? event.poolAgeHours);
+  const liquidity = finite(event.liquidityUsd ?? event.liquidity);
+  const locked = event.liquidityLocked ?? event.locked;
+  add(out, "pool_age", age === null ? null : age < 24 ? -0.42 : clamp(age / 720) * 0.12);
+  add(out, "liquidity", liquidity === null ? null : (clamp(Math.log10(Math.max(1, liquidity)) / 7) - 0.5) * 0.28);
+  add(out, "liquidity_lock", locked == null ? null : locked ? 0.12 : -0.28);
+}
+
+function nftFeatures(event, out) {
+  const change = finite(event.floorChange ?? event.floorChangePct);
+  const sales = finite(event.sales ?? event.saleCount);
+  add(out, "floor_change", change === null ? null : clamp(change, -1, 1) * 0.35);
+  add(out, "sales_depth", sales === null ? null : clamp(sales / 50) * 0.18);
+}
+
+function hlFeatures(event, out) {
+  const imbalance = finite(event.flowImbalance ?? event.imbalance);
+  const funding = finite(event.fundingRate ?? event.funding);
+  add(out, "flow_imbalance", imbalance === null ? null : clamp(imbalance, -1, 1) * 0.42);
+  add(out, "funding", funding === null ? null : -clamp(funding * 100, -1, 1) * 0.12);
+}
+
+function predictionFeatures(event, out) {
+  const market = finite(event.marketProbability ?? event.marketPrice ?? event.probability);
+  const fair = finite(event.fairProbability ?? event.referenceProbability ?? event.fairValue);
+  add(out, "probability_mispricing", market === null || fair === null ? null : clamp(fair - market, -1, 1) * 0.65);
+  const liquidity = finite(event.liquidityUsd ?? event.liquidity);
+  add(out, "market_liquidity", liquidity === null ? null : clamp(Math.log10(Math.max(1, liquidity)) / 6) * 0.12);
+}
+
+const FEATURE_BUILDERS = Object.freeze({
+  wallet: walletFeatures,
+  pool: poolFeatures,
+  nft_floor: nftFeatures,
+  hl_flow: hlFeatures,
+  prediction_market: predictionFeatures,
+});
+
+function markoutFor(event, id, markouts) {
+  const rows = markouts.filter((row) => {
+    const target = row?.signalId ?? row?.eventId ?? row?.id ?? row?.asset ?? row?.market;
+    return target != null && String(target) === id;
+  });
+  if (rows.length === 0) return null;
+  const values = rows.map((row) => finite(row.return ?? row.markout ?? row.pnl ?? row.value)).filter((value) => value !== null);
+  if (values.length === 0) return null;
+  return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+
+/** Pure, deterministic scoring of observed onchain events. It never fetches data or executes. */
+export function scoreSignals(events = [], markouts = [], options = {}) {
+  if (!Array.isArray(events) || !Array.isArray(markouts)) throw new TypeError("events and markouts must be arrays");
+  const minimumCoverage = clamp(finite(options.minimumCoverage) ?? 0.5);
+
+  return events.map((event, index) => {
+    const type = typeOf(event);
+    const id = idOf(event, index);
+    const builder = FEATURE_BUILDERS[type];
+    const contributions = [];
+    if (builder) builder(event, contributions);
+
+    const expected = type === "wallet" ? 2 : type === "pool" ? 3 : 2;
+    const coverage = round(clamp(contributions.length / expected));
+    const rawFeatureScore = contributions.reduce((sum, item) => sum + item.value, 0);
+    const markout = markoutFor(event, id, markouts);
+    const markoutContribution = markout === null ? 0 : clamp(markout, -1, 1) * 0.35;
+    if (markout !== null) add(contributions, "shadow_markout", markoutContribution);
+    const score = round(clamp(0.5 + rawFeatureScore + markoutContribution));
+    const markoutFactor = markout === null ? 0.8 : clamp(0.85 + markout * 0.3, 0.35, 1);
+    const confidence = round(clamp(coverage * markoutFactor));
+    const flags = ["COLD_INTELLIGENCE_ONLY", "NO_HOT_EXECUTION"];
+    if (!builder) flags.push("UNSUPPORTED_SIGNAL_TYPE");
+    if (coverage < minimumCoverage) flags.push("LOW_COVERAGE", "NO_TRADE");
+    if (confidence < 0.5) flags.push("LOW_CONFIDENCE", "NO_TRADE");
+    if (type === "pool" && (finite(event.ageHours ?? event.poolAgeHours) ?? Infinity) < 24) flags.push("NEW_POOL_RISK", "NO_TRADE");
+    if (markout !== null && markout < 0) flags.push("NEGATIVE_MARKOUT");
+
+    return {
+      id,
+      type,
+      score,
+      confidence,
+      coverage,
+      contributions,
+      flags: [...new Set(flags)],
+      noTrade: flags.includes("NO_TRADE"),
+      executionAllowed: false,
+    };
+  }).sort((a, b) => b.score - a.score || b.confidence - a.confidence || a.id.localeCompare(b.id));
+}
+
+export function createSignalsEngine(defaults = {}) {
+  return Object.freeze({
+    score(events, markouts = [], options = {}) {
+      return scoreSignals(events, markouts, { ...defaults, ...options });
+    },
+  });
+}
+
+export { SIGNAL_TYPES };

package/src/signals/index.mjs

@@ -0,0 +1 @@
+export { SIGNAL_TYPES, createSignalsEngine, scoreSignals } from "./engine.mjs";

package/src/watch-preferences.mjs

@@ -0,0 +1,85 @@
+/** Notification classes supported by Oracle watches. */
+export const WATCH_CATEGORIES = Object.freeze([
+  'price',
+  'wallet',
+  'risk',
+  'execution',
+  'security',
+  'nft',
+  'governance',
+  'system',
+]);
+
+const CATEGORY_SET = new Set(WATCH_CATEGORIES);
+
+function assertCategory(category) {
+  if (!CATEGORY_SET.has(category)) {
+    throw new TypeError(`Unknown watch category: ${String(category)}`);
+  }
+  return category;
+}
+
+function subscribedCategories(preferences = {}) {
+  const categories = preferences.subscribedCategories ?? [];
+  if (!Array.isArray(categories)) {
+    throw new TypeError('subscribedCategories must be an array');
+  }
+  return categories;
+}
+
+/** New users receive no category notifications until they explicitly opt in. */
+export function defaultPreferences() {
+  return { subscribedCategories: [] };
+}
+
+/** Return a new preference value with exactly one notification class enabled. */
+export function subscribe(preferences, category) {
+  assertCategory(category);
+  const current = subscribedCategories(preferences);
+  if (current.includes(category)) return { ...preferences, subscribedCategories: [...current] };
+  return { ...preferences, subscribedCategories: [...current, category] };
+}
+
+/** Return a new preference value with the requested notification class disabled. */
+export function unsubscribe(preferences, category) {
+  assertCategory(category);
+  const current = subscribedCategories(preferences);
+  return {
+    ...preferences,
+    subscribedCategories: current.filter((candidate) => candidate !== category),
+  };
+}
+
+/** Create a direct watch. Notifications are opt-in independently for every watch. */
+export function createWatch({ category, notify = false, ...watch } = {}) {
+  assertCategory(category);
+  if (typeof notify !== 'boolean') throw new TypeError('watch notify must be a boolean');
+  return { ...watch, category, notify };
+}
+
+function isMatchingNotifyingWatch(alert, watch) {
+  if (!watch || watch.notify !== true || watch.category !== alert.category) return false;
+  if (alert.watchId !== undefined && watch.id !== alert.watchId) return false;
+  return true;
+}
+
+/**
+ * Decide whether an alert may be delivered. This function only describes policy;
+ * it performs no scheduling or delivery.
+ */
+export function evaluateAlert(alert, preferences = defaultPreferences(), watch) {
+  if (!alert || typeof alert !== 'object') throw new TypeError('alert must be an object');
+  assertCategory(alert.category);
+
+  if (subscribedCategories(preferences).includes(alert.category)) {
+    return { deliver: true, reason: 'category-subscribed' };
+  }
+  if (isMatchingNotifyingWatch(alert, watch)) {
+    return { deliver: true, reason: 'watch-opt-in' };
+  }
+  return { deliver: false, reason: 'not-subscribed' };
+}
+
+export function shouldDeliverAlert(alert, preferences, watch) {
+  return evaluateAlert(alert, preferences, watch).deliver;
+}