@ixo/oracle-runtime-workers 0.29.1 → 0.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.29.1",
+  "version": "0.30.0",
   "description": "QiForge oracle runtime for Cloudflare Workers — Durable Object per user (SQLite in WASM over DO storage), Matrix E2EE gateway Durable Object, Hono HTTP/SSE shell.",
   "private": false,
   "publishConfig": {
@@ -66,8 +66,8 @@
     "protobufjs": "^7.6.5",
     "@ixo/topic-protocol": "1.0.0-rc.8",
     "@ixo/common": "1.7.1",
-    "@ixo/ucan": "2.3.0",
-    "@ixo/ixo-transaction": "0.2.0"
+    "@ixo/ixo-transaction": "0.2.0",
+    "@ixo/ucan": "2.3.0"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.22.0",

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

@@ -0,0 +1,141 @@
+/**
+ * An account's bank balances as `get_account_balances` shows them: one
+ * REST read of one page, each denom through its display, `uixo` first,
+ * then verified tokens, then by amount. The tool reads them with its own
+ * readers; `get_account_overview` reads them as an unregistered kind
+ * inside its one `runRequests` call.
+ */
+import { z } from 'zod';
+import { formatUnits, type IbcTrace, type TokenDisplay } from './denoms';
+import type { Outcome } from './http';
+import { defineKind } from './kinds/types';
+import { accountOf } from './queries';
+
+/** Bank balances read per account (one page). */
+export const BALANCE_PAGE = 50;
+/** Tokens resolved at once; each runs its metadata, trace and channel reads in turn. */
+const METADATA_CONCURRENCY = 4;
+
+const balancesResponse = z.object({
+  balances: z.array(z.object({ denom: z.string(), amount: z.string() })),
+  pagination: z.object({ next_key: z.string().nullish() }).nullish(),
+});
+
+export type BalanceToken = {
+  denom: string;
+  symbol: string;
+  decimals: number;
+  verified: boolean;
+  amountBaseUnits: string;
+  amount: string;
+  origin?: string;
+  trace?: IbcTrace;
+  metadataUnavailable?: true;
+};
+
+export interface Balances {
+  tokens: BalanceToken[];
+  /** The account holds more denoms than one page. */
+  moreDenoms: boolean;
+}
+
+/** `items` mapped with at most `limit` running at once, in order. */
+async function mapLimit<T, R>(
+  items: readonly T[],
+  limit: number,
+  map: (item: T) => Promise<R>,
+): Promise<R[]> {
+  const out: R[] = [];
+  for (let index = 0; index < items.length; index += limit)
+    out.push(
+      ...(await Promise.all(items.slice(index, index + limit).map(map))),
+    );
+  return out;
+}
+
+/** How the balances are read: one REST GET and each denom's display. */
+export interface BalanceReaders {
+  rest<S extends z.ZodType>(
+    path: string,
+    schema: S,
+    opts: { label: string },
+  ): Promise<Outcome<z.infer<S>>>;
+  display(denom: string): Promise<TokenDisplay>;
+}
+
+/**
+ * The bank balances of `address` (an `ixo1` address of bech32 characters,
+ * safe as a path segment), each token shown through `readers.display`.
+ */
+export async function readBalances(
+  readers: BalanceReaders,
+  address: string,
+): Promise<Outcome<Balances>> {
+  const read = await readers.rest(
+    `/cosmos/bank/v1beta1/balances/${address}?pagination.limit=${BALANCE_PAGE}`,
+    balancesResponse,
+    { label: 'balances' },
+  );
+  if (!read.ok) return read;
+  const coins = read.value.balances.filter((coin) =>
+    /^(0|[1-9][0-9]{0,39})$/.test(coin.amount),
+  );
+  const tokens: BalanceToken[] = await mapLimit(
+    coins,
+    METADATA_CONCURRENCY,
+    async (coin) => {
+      const display = await readers.display(coin.denom);
+      return {
+        denom: coin.denom,
+        symbol: display.symbol,
+        decimals: display.decimals,
+        verified: display.verified,
+        amountBaseUnits: coin.amount,
+        amount: formatUnits(coin.amount, display.decimals),
+        ...(display.origin !== undefined ? { origin: display.origin } : {}),
+        ...(display.trace !== undefined ? { trace: display.trace } : {}),
+        ...(display.metadataUnavailable ? { metadataUnavailable: true } : {}),
+      };
+    },
+  );
+  const rank = (token: BalanceToken) =>
+    token.denom === 'uixo' ? 0 : token.verified ? 1 : 2;
+  tokens.sort(
+    (a, b) => rank(a) - rank(b) || Number(b.amount) - Number(a.amount),
+  );
+  return {
+    ok: true,
+    value: { tokens, moreDenoms: !!read.value.pagination?.next_key },
+  };
+}
+
+/**
+ * The balances as a kind, for `get_account_overview` only (it is not in
+ * the `chain_lookup` catalogue): `{ tokens, moreDenoms }` with the
+ * account's `subject`. Its denoms are looked up through the request's
+ * `display`, so at most `MAX_DISPLAY_DENOMS` of them.
+ */
+export const balancesKind = defineKind({
+  name: 'balances',
+  summary:
+    'The bank balances of an account, as get_account_balances reads them.',
+  explain:
+    'Each token: denom, symbol, decimals, verified, amountBaseUnits and `amount` in display units; uixo first, then verified tokens, then by amount.',
+  source: 'chain',
+  list: false,
+  args: z.strictObject({ address: z.string().optional() }),
+  example: {},
+  plan(input, ctx) {
+    const account = accountOf(input.address, ctx.identity, 'address');
+    if (!account.ok) return { invalid: account.detail };
+    return {
+      source: 'chain',
+      async run() {
+        const read = await readBalances(ctx, account.address);
+        return read.ok
+          ? { ok: true, subject: account.subject, data: read.value }
+          : { ok: false, ...read.failure };
+      },
+    };
+  },
+});

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

@@ -5,11 +5,11 @@
  *
  * PostGraphile answers field by field: one alias can be null with an error
  * naming it while the others are fine, so errors are returned beside the
- * data, never thrown. "current transaction is aborted" and "Connection
- * terminated unexpectedly" say nothing about the question: the aliases
- * they name are asked again once, in a document of only those aliases,
- * and the answers merged; a statement timeout is never asked again (it
- * would only time out again).
+ * data, never thrown. A transient database error ({@link TRANSIENT_ERROR}:
+ * an aborted transaction, a dropped connection, no free connection) says
+ * nothing about the question: the aliases it names are asked again once,
+ * in a document of only those aliases, and the answers merged; a
+ * statement timeout is never asked again (it would only time out again).
  */
 import { z } from 'zod';
 import {
@@ -28,8 +28,13 @@ export const BLOCKSYNC_MAX_BYTES = 1024 * 1024;
  */
 export const BLOCKSYNC_ATTEMPT_TIMEOUT_MS = 11_000;
 
+/**
+ * Database errors that say nothing about the question: an aborted
+ * transaction, a dropped connection, and the server's connection pool or
+ * PostgreSQL itself out of connections.
+ */
 export const TRANSIENT_ERROR =
-  /current transaction is aborted|Connection terminated unexpectedly/;
+  /current transaction is aborted|Connection terminated unexpectedly|timeout exceeded when trying to connect|too many clients|remaining connection slots are reserved/;
 export const STATEMENT_TIMEOUT = /statement timeout/i;
 
 export interface GraphqlError {

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

@@ -28,11 +28,17 @@
  *   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. Its trace is not read then.
+ * budget left to ask) or was not asked (a `chain_lookup` request past its
+ * denom lookups) is shown the same way with `metadataUnavailable`: it may
+ * still be verified. Its trace is not read then.
  */
 import { z } from 'zod';
-import { MIN_ATTEMPT_MS, throwIfAborted, type ChainCall } from './http';
+import {
+  hasBudget,
+  throwIfAborted,
+  untilAborted,
+  type ChainCall,
+} from './http';
 import { restJson } from './rest';
 
 export type DenomMetadataView = { symbol: string; decimals: number } | null;
@@ -229,16 +235,26 @@ export const METADATA_NOT_FOUND_TTL_MS = 60_000;
 export const METADATA_FAILED_TTL_MS = 10_000;
 /** A denom trace or a channel's chain id never changes: found ones are reused for 1 h (misses and failures as for metadata). */
 export const IBC_TRACE_TTL_MS = 3_600_000;
-const CACHE_LIMIT = 256;
+/** Answers kept per cache; past it the oldest written is dropped. */
+export const DENOM_CACHE_LIMIT = 256;
 
-/** One read's answer: the value (null for a miss), or why there is none. */
-type Lookup<T> = { value: T | null } | 'failed' | 'aborted';
+/**
+ * One read's answer: the value (null for a miss), or why there is none:
+ * `failed` (the upstream failed), `timeout` (it did not answer in time, or
+ * the launching call's budget ran out), `aborted` (the launching turn was
+ * aborted).
+ */
+type Lookup<T> = { value: T | null } | 'failed' | 'timeout' | 'aborted';
 
 /**
  * Answers per `${restUrl}|${key}`, kept per isolate: a found value for
- * `foundTtlMs`, a miss for 60 s, a failure for 10 s, an abort never. A
+ * `foundTtlMs`, a miss for 60 s, a failure for 10 s, a timeout or an abort
+ * never; at most {@link DENOM_CACHE_LIMIT}, the oldest dropped first. A
  * read in flight is shared by every call of the isolate that needs the
- * same key; none is started with less than 1 s of the budget left.
+ * same key; none is started with less than 1 s of the budget left. A call
+ * that joined a read which then timed out or was aborted by its launching
+ * turn reads again itself while its own budget allows; it waits on its own
+ * turn's abort, never another's.
  */
 class ReadCache<T> {
   private readonly answers = new Map<
@@ -249,18 +265,22 @@ class ReadCache<T> {
 
   constructor(private readonly foundTtlMs: number) {}
 
-  get(
+  async get(
     call: ChainCall,
     key: string,
     read: () => Promise<Lookup<T>>,
   ): Promise<Lookup<T>> {
     const id = `${call.restUrl}|${key}`;
     const hit = this.answers.get(id);
-    if (hit && hit.expiresAt > Date.now()) return Promise.resolve(hit.lookup);
+    if (hit && hit.expiresAt > Date.now()) return hit.lookup;
     const running = this.inflight.get(id);
-    if (running) return running;
-    if (call.deadline - Date.now() < MIN_ATTEMPT_MS)
-      return Promise.resolve('failed');
+    if (running) {
+      const lookup = await untilAborted(running, call.signal);
+      return (lookup === 'timeout' || lookup === 'aborted') && hasBudget(call)
+        ? this.get(call, key, read)
+        : lookup;
+    }
+    if (!hasBudget(call)) return 'timeout';
     const pending = read()
       .then((lookup) => {
         this.remember(id, lookup);
@@ -277,14 +297,18 @@ class ReadCache<T> {
   }
 
   private remember(id: string, lookup: Lookup<T>): void {
-    if (lookup === 'aborted') return;
+    if (lookup === 'aborted' || lookup === 'timeout') return;
     const ttl =
       lookup === 'failed'
         ? METADATA_FAILED_TTL_MS
         : lookup.value
           ? this.foundTtlMs
           : METADATA_NOT_FOUND_TTL_MS;
-    if (this.answers.size > CACHE_LIMIT) this.answers.clear();
+    this.answers.delete(id);
+    if (this.answers.size >= DENOM_CACHE_LIMIT) {
+      const oldest = this.answers.keys().next();
+      if (!oldest.done) this.answers.delete(oldest.value);
+    }
     this.answers.set(id, { lookup, expiresAt: Date.now() + ttl });
   }
 }
@@ -306,8 +330,9 @@ export function resetDenomMetadataCache(): void {
 
 /**
  * One bounded REST read of a resource that may be absent: a 404 is a
- * miss, any other failure `failed`, the launching turn's abort `aborted`
- * (so a call sharing the read is not failed by another turn's abort).
+ * miss, a timeout `timeout`, any other failure `failed`, the launching
+ * turn's abort `aborted` (so a call sharing the read is not failed by
+ * another turn's abort).
  */
 async function readRest<S extends z.ZodType, T>(
   call: ChainCall,
@@ -328,7 +353,11 @@ async function readRest<S extends z.ZodType, T>(
     throw error;
   }
   if (!read.ok)
-    return read.failure.reason === 'not_found' ? { value: null } : 'failed';
+    return read.failure.reason === 'not_found'
+      ? { value: null }
+      : read.failure.reason === 'timeout'
+        ? 'timeout'
+        : 'failed';
   return { value: pick(read.value) };
 }
 
@@ -441,8 +470,7 @@ async function tracedDisplay(
   const hash = denom.slice('ibc/'.length);
   const trace = await traceCache.get(call, hash, () => readTrace(call, hash));
   throwIfAborted(call.signal);
-  if (trace === 'failed' || trace === 'aborted' || !trace.value)
-    return fallback;
+  if (typeof trace !== 'object' || !trace.value) return fallback;
   const { baseDenom, path, channel } = trace.value;
   const chainId = await chainIdCache.get(call, channel, () =>
     readChainId(call, channel),
@@ -452,13 +480,43 @@ async function tracedDisplay(
     ...fallback,
     trace: {
       baseDenom,
-      claimedChain:
-        chainId === 'failed' || chainId === 'aborted' ? null : chainId.value,
+      claimedChain: typeof chainId === 'object' ? chainId.value : null,
       path,
     },
   };
 }
 
+/**
+ * The display of `denom` when it takes no lookup: `uixo`, a denom that is
+ * not a bank denom (never looked up) and an `ibc/…` denom in `ibcDenoms`.
+ * Null for any other denom: its display needs its DenomMetadata.
+ */
+export function knownDisplay(
+  denom: string,
+  ibcDenoms: IbcDenomTable,
+): TokenDisplay | null {
+  if (denom === 'uixo' || !DENOM.test(denom))
+    return trustedDenomDisplay(denom, null);
+  const known = IBC_DENOM.test(denom) ? ibcDenoms.get(denom) : undefined;
+  return known
+    ? {
+        symbol: known.symbol,
+        decimals: known.decimals,
+        verified: true,
+        ...(known.origin ? { origin: known.origin } : {}),
+      }
+    : null;
+}
+
+/**
+ * A denom shown without its metadata (the read failed, or was not made):
+ * unverified, in base units, under its full denom, `metadataUnavailable`
+ * because it may still be verified.
+ */
+export function unreadDisplay(denom: string): TokenDisplay {
+  return { ...trustedDenomDisplay(denom, null), metadataUnavailable: true };
+}
+
 /**
  * The display of `denom`: `uixo` and an `ibc/…` denom in `ibcDenoms`
  * without a lookup; any other denom through its DenomMetadata, then (an
@@ -469,25 +527,15 @@ export async function denomDisplay(
   denom: string,
   ibcDenoms: IbcDenomTable,
 ): Promise<TokenDisplay> {
-  if (denom === 'uixo' || !DENOM.test(denom))
-    return trustedDenomDisplay(denom, null);
-  const ibc = IBC_DENOM.test(denom);
-  const known = ibc ? ibcDenoms.get(denom) : undefined;
-  if (known)
-    return {
-      symbol: known.symbol,
-      decimals: known.decimals,
-      verified: true,
-      ...(known.origin ? { origin: known.origin } : {}),
-    };
+  const known = knownDisplay(denom, ibcDenoms);
+  if (known) return known;
   const lookup = await metadataCache.get(call, denom, () =>
     readMetadata(call, denom),
   );
   throwIfAborted(call.signal);
-  if (lookup === 'failed' || lookup === 'aborted')
-    return { ...trustedDenomDisplay(denom, null), metadataUnavailable: true };
+  if (typeof lookup !== 'object') return unreadDisplay(denom);
   const display = trustedDenomDisplay(denom, lookup.value);
-  return display.verified || !ibc
+  return display.verified || !IBC_DENOM.test(denom)
     ? display
     : tracedDisplay(call, denom, display);
 }