@ixo/oracle-runtime-workers 0.27.0 → 0.28.0

package/src/plugins/ixo-chain/denoms.ts

@@ -0,0 +1,189 @@
+/**
+ * How a bank denom is shown. DenomMetadata is trusted for any denom: on
+ * the IXO chain it is written only by chain code (liquidstake pools, which
+ * governance creates; the IBC transfer module; genesis and upgrades), never
+ * by a token's issuer (the chain has no tokenfactory module). This is
+ * broader than the Auth Hub's rule (ixo-auth-worker
+ * `src/lib/actions/denom-display.ts`), which reads metadata only for
+ * `ibc/…`, so the Hub may still show a native token such as `upay` as
+ * unverified.
+ *
+ * - `uixo`: always IXO with 6 decimals, verified, no lookup.
+ * - any other denom with metadata whose `display` unit is listed in
+ *   `denom_units` with an exponent of 0–18: verified, those decimals, the
+ *   metadata `symbol` (or, when that is empty, the display unit
+ *   upper-cased: `uatom` → `ATOM`) if it is plain ASCII.
+ * - anything else (no metadata, a display unit not listed — the shape IBC
+ *   transfers register — or a malformed denom, which is never looked up):
+ *   unverified, base units (0 decimals), the full denom as its symbol.
+ *
+ * A denom whose metadata could not be read (a transport failure, or no
+ * budget left to ask) is shown the same way with `metadataUnavailable`:
+ * it may still be verified.
+ */
+import { z } from 'zod';
+import { MIN_ATTEMPT_MS, throwIfAborted, type ChainCall } from './http';
+import { restJson } from './rest';
+
+export type DenomMetadataView = { symbol: string; decimals: number } | null;
+export type TokenDisplay = {
+  symbol: string;
+  decimals: number;
+  verified: boolean;
+  metadataUnavailable?: true;
+};
+
+/** Symbols an unverified denom may never use (compared case-insensitively). */
+const RESERVED_SYMBOLS = ['IXO', 'USDC', 'USDT', 'ATOM', 'OSMO'] as const;
+/** The Cosmos SDK bank denom pattern: only such a denom is looked up. */
+const DENOM = /^[a-zA-Z][a-zA-Z0-9/:._-]{2,127}$/;
+// Plain ASCII only: no spaces or look-alike Unicode letters ("UЅDC").
+const SAFE_SYMBOL = /^[A-Za-z0-9._-]{1,32}$/;
+
+export function trustedDenomDisplay(
+  denom: string,
+  metadata: DenomMetadataView,
+): TokenDisplay {
+  if (denom === 'uixo') return { symbol: 'IXO', decimals: 6, verified: true };
+  const symbol =
+    metadata && SAFE_SYMBOL.test(metadata.symbol) ? metadata.symbol : null;
+  if (
+    metadata &&
+    symbol &&
+    DENOM.test(denom) &&
+    Number.isInteger(metadata.decimals) &&
+    metadata.decimals >= 0 &&
+    metadata.decimals <= 18
+  )
+    return { symbol, decimals: metadata.decimals, verified: true };
+  const reserved =
+    symbol !== null &&
+    (RESERVED_SYMBOLS as readonly string[]).includes(symbol.toUpperCase());
+  return {
+    symbol: symbol && !reserved ? symbol : denom,
+    decimals: 0,
+    verified: false,
+  };
+}
+
+/** Base units as a decimal string: `("9000000", 6)` → `"9"`, `("1234567", 6)` → `"1.234567"`. */
+export function formatUnits(amount: string, decimals: number): string {
+  if (decimals === 0) return amount;
+  const padded = amount.padStart(decimals + 1, '0');
+  const whole = padded.slice(0, -decimals);
+  const fraction = padded.slice(-decimals).replace(/0+$/, '');
+  return fraction ? `${whole}.${fraction}` : whole;
+}
+
+/**
+ * Per isolate: found metadata is reused for 10 min, a definite miss (404,
+ * or no display unit) for 60 s, a failed read for 10 s — a failure is
+ * never kept as a miss, so it cannot leave a real token unverified.
+ */
+export const METADATA_TTL_MS = 600_000;
+export const METADATA_NOT_FOUND_TTL_MS = 60_000;
+export const METADATA_FAILED_TTL_MS = 10_000;
+const CACHE_LIMIT = 256;
+
+/** A metadata read: its view (null for a miss), or why there is none. */
+type Lookup = { metadata: DenomMetadataView } | 'failed' | 'aborted';
+
+const metadataCache = new Map<string, { lookup: Lookup; expiresAt: number }>();
+/** Reads in flight, shared by every call of the isolate that needs the same denom. */
+const inflight = new Map<string, Promise<Lookup>>();
+
+/** Tests only: forget every cached metadata answer. */
+export function resetDenomMetadataCache(): void {
+  metadataCache.clear();
+  inflight.clear();
+}
+
+const metadataResponse = z.object({
+  metadata: z.object({
+    denom_units: z.array(
+      z.object({ denom: z.string(), exponent: z.number().int() }),
+    ),
+    display: z.string(),
+    symbol: z.string(),
+  }),
+});
+
+/**
+ * One DenomMetadata read. The by-query-string route is used because the
+ * path route cannot carry the slash in `ibc/…` (the gateway answers 501).
+ * A 404 is a miss; any other failure is `failed`; the launching turn's
+ * abort is `aborted` (never cached), so a call sharing the read is not
+ * failed by another turn's abort.
+ */
+async function readMetadata(call: ChainCall, denom: string): Promise<Lookup> {
+  let read;
+  try {
+    read = await restJson(
+      call,
+      `/cosmos/bank/v1beta1/denoms_metadata_by_query_string?denom=${encodeURIComponent(denom)}`,
+      metadataResponse,
+      { label: 'denom metadata', maxBytes: 64 * 1024, notFoundOn404: true },
+    );
+  } catch (error) {
+    if (call.signal.aborted) return 'aborted';
+    throw error;
+  }
+  if (!read.ok)
+    return read.failure.reason === 'not_found' ? { metadata: null } : 'failed';
+  const { metadata } = read.value;
+  const unit = metadata.denom_units.find((u) => u.denom === metadata.display);
+  return {
+    metadata:
+      unit && unit.exponent >= 0 && unit.exponent <= 18
+        ? {
+            symbol: metadata.symbol || metadata.display.toUpperCase(),
+            decimals: unit.exponent,
+          }
+        : null,
+  };
+}
+
+function remember(key: string, lookup: Lookup): void {
+  if (lookup === 'aborted') return;
+  const ttl =
+    lookup === 'failed'
+      ? METADATA_FAILED_TTL_MS
+      : lookup.metadata
+        ? METADATA_TTL_MS
+        : METADATA_NOT_FOUND_TTL_MS;
+  if (metadataCache.size > CACHE_LIMIT) metadataCache.clear();
+  metadataCache.set(key, { lookup, expiresAt: Date.now() + ttl });
+}
+
+/** The cached lookup, the read in flight, or a new read; `failed` without a read once the budget is spent. */
+function lookupOf(call: ChainCall, denom: string): Promise<Lookup> {
+  const key = `${call.restUrl}|${denom}`;
+  const hit = metadataCache.get(key);
+  if (hit && hit.expiresAt > Date.now()) return Promise.resolve(hit.lookup);
+  const running = inflight.get(key);
+  if (running) return running;
+  if (call.deadline - Date.now() < MIN_ATTEMPT_MS)
+    return Promise.resolve('failed');
+  const read = readMetadata(call, denom)
+    .then((lookup) => {
+      remember(key, lookup);
+      return lookup;
+    })
+    .finally(() => inflight.delete(key));
+  inflight.set(key, read);
+  return read;
+}
+
+/** The display of `denom`, reading its DenomMetadata for every denom but `uixo`. */
+export async function denomDisplay(
+  call: ChainCall,
+  denom: string,
+): Promise<TokenDisplay> {
+  if (denom === 'uixo' || !DENOM.test(denom))
+    return trustedDenomDisplay(denom, null);
+  const lookup = await lookupOf(call, denom);
+  throwIfAborted(call.signal);
+  return lookup === 'failed' || lookup === 'aborted'
+    ? { ...trustedDenomDisplay(denom, null), metadataUnavailable: true }
+    : trustedDenomDisplay(denom, lookup.metadata);
+}

package/src/plugins/ixo-chain/http.ts

@@ -0,0 +1,388 @@
+/**
+ * The network edge shared by the chain REST and Blocksync reads: one bounded
+ * HTTP exchange per attempt and the retry policy around it. Upstream
+ * failures become a {@link Failure} the tools hand to the model; nothing
+ * here throws for them. Only the turn's own abort is rethrown.
+ */
+import {
+  boundedBytes,
+  fetchWithoutRedirects,
+} from '../../core/domain-context/transport';
+
+export type Source = 'chain' | 'blocksync';
+
+export type FailureReason =
+  | 'rate_limited'
+  | 'timeout'
+  | 'index_timeout'
+  | 'unavailable'
+  | 'not_found'
+  | 'too_large'
+  | 'invalid_input';
+
+/** Why a read failed: a code, the plain sentence the model relays, and whether asking again can help. */
+export interface Failure {
+  reason: FailureReason;
+  detail: string;
+  retryable: boolean;
+}
+
+/**
+ * The one retry waits a uniform 1–3 s when the upstream names no
+ * `Retry-After`, so isolates that failed together do not retry together.
+ */
+export const RETRY_DELAY_MIN_MS = 1_000;
+export const RETRY_DELAY_MAX_MS = 3_000;
+/** Longest `Retry-After` honoured. */
+export const MAX_RETRY_DELAY_MS = 5_000;
+/** Whole-tool budget: every attempt and wait of one tool call fits inside it. */
+export const TOOL_BUDGET_MS = 20_000;
+/** A read, or its retry, is not started with less time than this left in the budget. */
+export const MIN_ATTEMPT_MS = 1_000;
+/** How long a 429 or 503 answers the isolate's other reads of that upstream without asking it. */
+export const UNHEALTHY_MS = 10_000;
+
+const SOURCE_NAME: Record<Source, string> = {
+  chain: 'The chain node',
+  blocksync: 'Blocksync',
+};
+
+function rateLimited(source: Source): Failure {
+  return {
+    reason: 'rate_limited',
+    detail: `${SOURCE_NAME[source]} is rate-limiting requests; try again in a few seconds.`,
+    retryable: true,
+  };
+}
+
+function timedOut(source: Source): Failure {
+  return {
+    reason: 'timeout',
+    detail:
+      source === 'blocksync'
+        ? 'Blocksync did not answer in time; narrow the question (fewer rows or requests).'
+        : 'The chain node did not answer in time; try again shortly.',
+    retryable: true,
+  };
+}
+
+export const tooLarge = (detail: string): Failure => ({
+  reason: 'too_large',
+  detail,
+  retryable: false,
+});
+
+export function unavailable(
+  source: Source,
+  why: string,
+  retryable: boolean,
+): Failure {
+  return {
+    reason: 'unavailable',
+    detail: `${SOURCE_NAME[source]} is unavailable right now (${why}).`,
+    retryable,
+  };
+}
+
+/** What one tool call's reads share: where they go, the budget and the turn's abort. */
+export interface ChainCall {
+  network: 'mainnet' | 'testnet' | 'devnet';
+  restUrl: string;
+  blocksyncUrl: string;
+  /** Epoch ms by which every read of the call has finished. */
+  deadline: number;
+  signal: AbortSignal;
+  fetch: typeof fetch;
+}
+
+/**
+ * One attempt's outcome. `retry` asks for the policy's one retry: on a
+ * failure it is the failure's, on a value it means the answer was
+ * transient (a GraphQL "transaction aborted") and is kept if the retry
+ * cannot run or fails.
+ */
+export type Attempt<T> =
+  | { ok: true; value: T; retry?: false }
+  | { ok: true; value: T; retry: true; note: string }
+  | {
+      ok: false;
+      failure: Failure;
+      retry: boolean;
+      retryAfterMs?: number;
+      /** A 429 or 503: the upstream is marked unhealthy for {@link UNHEALTHY_MS}. */
+      unhealthy?: true;
+      /** An expected answer rather than a fault (a 404 the caller asked for): not logged. */
+      quiet?: true;
+      /** Log text: status or error class, never a request body or an address. */
+      note: string;
+    };
+
+export type Outcome<T> =
+  | { ok: true; value: T }
+  | { ok: false; failure: Failure };
+
+/** The turn's abort reason as an error (a non-error reason becomes an `AbortError`). */
+function abortReason(signal: AbortSignal): Error {
+  return signal.reason instanceof Error
+    ? signal.reason
+    : new DOMException('Aborted', 'AbortError');
+}
+
+/** Throws the turn's abort reason once the turn is aborted. */
+export function throwIfAborted(signal: AbortSignal): void {
+  if (signal.aborted) throw abortReason(signal);
+}
+
+/** Resolves after `ms`; rejects with the turn's abort reason if it ends first. */
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(abortReason(signal));
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(abortReason(signal));
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    signal.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+/** The wait before the one retry when the upstream named none: uniform in 1–3 s. */
+export function retryDelayMs(): number {
+  return Math.round(
+    RETRY_DELAY_MIN_MS +
+      Math.random() * (RETRY_DELAY_MAX_MS - RETRY_DELAY_MIN_MS),
+  );
+}
+
+/**
+ * Upstreams that answered 429 or 503 within the last {@link UNHEALTHY_MS},
+ * keyed by base URL, with the failure that marked them. Per isolate: every
+ * call of the isolate answers with it instead of asking the upstream again.
+ */
+const unhealthy = new Map<string, { until: number; failure: Failure }>();
+
+/** Tests only: forget every unhealthy mark. */
+export function resetUpstreamHealth(): void {
+  unhealthy.clear();
+}
+
+function heldBack(upstream: string): Failure | null {
+  const mark = unhealthy.get(upstream);
+  if (!mark) return null;
+  if (mark.until > Date.now()) return mark.failure;
+  unhealthy.delete(upstream);
+  return null;
+}
+
+/** An answer clears the upstream's mark; a 429 or 503 sets it. */
+function recordHealth(upstream: string, attempt: Attempt<unknown>): void {
+  if (attempt.ok) unhealthy.delete(upstream);
+  else if (attempt.unhealthy)
+    unhealthy.set(upstream, {
+      until: Date.now() + UNHEALTHY_MS,
+      failure: attempt.failure,
+    });
+}
+
+/** One logical read: its log label and the base URL its health is kept under. */
+export interface Read {
+  label: string;
+  upstream: string;
+}
+
+/**
+ * Runs `attempt`, and once more when it asks for a retry and the budget
+ * leaves room: after `Retry-After` (capped at 5 s) when the upstream sent
+ * one, else after a uniform 1–3 s. An upstream marked unhealthy is not
+ * asked at all; the call's own retry is. A transient answer is kept when
+ * its retry fails. Each failed attempt logs one line, except an expected
+ * (`quiet`) answer.
+ */
+export async function withRetry<T>(
+  call: ChainCall,
+  read: Read,
+  attempt: () => Promise<Attempt<T>>,
+): Promise<Outcome<T>> {
+  const held = heldBack(read.upstream);
+  if (held) {
+    console.warn(
+      `[ixo-chain] ${read.label} not attempted: the upstream answered ${held.reason === 'rate_limited' ? '429' : '503'} moments ago`,
+    );
+    return { ok: false, failure: held };
+  }
+  const first = await attempt();
+  recordHealth(read.upstream, first);
+  if (first.ok && !first.retry) return { ok: true, value: first.value };
+  if (first.ok || !first.quiet)
+    console.warn(`[ixo-chain] ${read.label} attempt 1 failed: ${first.note}`);
+  const wait =
+    !first.ok && first.retryAfterMs !== undefined
+      ? Math.min(first.retryAfterMs, MAX_RETRY_DELAY_MS)
+      : retryDelayMs();
+  const giveUp = (): Outcome<T> =>
+    first.ok
+      ? { ok: true, value: first.value }
+      : { ok: false, failure: first.failure };
+  if (!first.retry || Date.now() + wait + MIN_ATTEMPT_MS > call.deadline)
+    return giveUp();
+  await sleep(wait, call.signal);
+  const second = await attempt();
+  recordHealth(read.upstream, second);
+  if (second.ok) {
+    if (second.retry)
+      console.warn(
+        `[ixo-chain] ${read.label} attempt 2 failed: ${second.note}`,
+      );
+    return { ok: true, value: second.value };
+  }
+  console.warn(`[ixo-chain] ${read.label} attempt 2 failed: ${second.note}`);
+  return first.ok
+    ? { ok: true, value: first.value }
+    : { ok: false, failure: second.failure };
+}
+
+/**
+ * `Retry-After` in ms: delta seconds or an HTTP date. Undefined when absent,
+ * unreadable, zero or in the past, so the default wait applies.
+ */
+export function retryAfterMs(header: string | null): number | undefined {
+  if (!header) return undefined;
+  const value = header.trim();
+  const ms = /^\d+$/.test(value)
+    ? Number(value) * 1000
+    : Date.parse(value) - Date.now();
+  return Number.isFinite(ms) && ms > 0 ? ms : undefined;
+}
+
+const REDIRECTED = 'ixo-chain-redirect';
+
+/**
+ * One bounded HTTP exchange: at most `timeoutMs` (and never past the call's
+ * deadline) including the body read, no redirects followed, the body cut
+ * off at `maxBytes`; the answer is the body text. Only a 2xx body is read.
+ * 429/502/503/504 and network errors ask for a retry; anything else is a
+ * failure the retry cannot fix. A 404 is `unavailable` (a wrong route or
+ * gateway) unless the caller reads a resource that may be absent
+ * (`notFoundOn404`): then it is a quiet `not_found`.
+ */
+export async function exchange(
+  call: ChainCall,
+  source: Source,
+  url: string,
+  init: RequestInit,
+  opts: { timeoutMs: number; maxBytes: number; notFoundOn404?: boolean },
+): Promise<Attempt<string>> {
+  throwIfAborted(call.signal);
+  const budget = Math.min(opts.timeoutMs, call.deadline - Date.now());
+  if (budget <= 0)
+    return {
+      ok: false,
+      failure: timedOut(source),
+      retry: false,
+      note: 'no budget left',
+    };
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), budget);
+  const onAbort = () => controller.abort();
+  call.signal.addEventListener('abort', onAbort, { once: true });
+  try {
+    const response = await fetchWithoutRedirects(
+      call.fetch,
+      url,
+      { ...init, signal: controller.signal },
+      REDIRECTED,
+    );
+    const { status } = response;
+    if (!response.ok) {
+      await response.body?.cancel().catch(() => undefined);
+      if (status === 429)
+        return {
+          ok: false,
+          failure: rateLimited(source),
+          retry: true,
+          unhealthy: true,
+          note: 'HTTP 429',
+          ...optionalRetryAfter(response.headers.get('retry-after')),
+        };
+      if (status === 502 || status === 503 || status === 504)
+        return {
+          ok: false,
+          failure: unavailable(source, `HTTP ${status}`, true),
+          retry: true,
+          ...(status === 503 ? { unhealthy: true } : {}),
+          note: `HTTP ${status}`,
+          ...optionalRetryAfter(response.headers.get('retry-after')),
+        };
+      if (status === 404 && opts.notFoundOn404)
+        return {
+          ok: false,
+          failure: {
+            reason: 'not_found',
+            detail: 'Nothing was found for that request.',
+            retryable: false,
+          },
+          retry: false,
+          quiet: true,
+          note: 'HTTP 404',
+        };
+      // 501 says the route is not implemented: asking again cannot help.
+      return {
+        ok: false,
+        failure: unavailable(
+          source,
+          `HTTP ${status}`,
+          status >= 500 && status !== 501,
+        ),
+        retry: false,
+        note: `HTTP ${status}`,
+      };
+    }
+    const bytes = await boundedBytes(response, opts.maxBytes);
+    return { ok: true, value: new TextDecoder().decode(bytes) };
+  } catch (error) {
+    throwIfAborted(call.signal);
+    if (controller.signal.aborted)
+      return {
+        ok: false,
+        failure: timedOut(source),
+        retry: false,
+        note: `timeout after ${budget} ms`,
+      };
+    if (error instanceof Error && error.message === REDIRECTED)
+      return {
+        ok: false,
+        failure: unavailable(source, 'it redirected the request', false),
+        retry: false,
+        note: 'redirect refused',
+      };
+    if (error instanceof Error && error.message === 'document-too-large')
+      return {
+        ok: false,
+        failure: tooLarge(
+          'The answer was too large to read; ask for fewer rows or a narrower filter.',
+        ),
+        retry: false,
+        note: `body over ${opts.maxBytes} bytes`,
+      };
+    return {
+      ok: false,
+      failure: unavailable(source, 'network error', true),
+      retry: true,
+      note: `network error (${error instanceof Error ? error.name : 'unknown'})`,
+    };
+  } finally {
+    clearTimeout(timer);
+    call.signal.removeEventListener('abort', onAbort);
+  }
+}
+
+function optionalRetryAfter(header: string | null): { retryAfterMs?: number } {
+  const ms = retryAfterMs(header);
+  return ms === undefined ? {} : { retryAfterMs: ms };
+}

package/src/plugins/ixo-chain/index.ts

@@ -0,0 +1 @@
+export { IxoChainPlugin } from './ixo-chain.plugin';