@ixo/oracle-runtime-workers 0.29.1 → 0.31.0

package/src/plugins/ixo-chain/kinds/indexed/token-history.ts

@@ -0,0 +1,205 @@
+/**
+ * `token_history`: the IXO 1155 token transfers, retirements and
+ * cancellations of an account, as one alias holding one sub-field per
+ * direction (Blocksync's `query` field nests the root query type).
+ *
+ * Index (ixo-blocksync main): `TokenTransaction_from_to_idx` ("from",
+ * "to") serves `from`; `to` and `TokenRetired`/`TokenCancelled` `owner`
+ * lead no index (`TokenRetired_name_owner_id_idx` and
+ * `TokenCancelled_name_idx` lead with `name`). All four answered in under
+ * 1 s on mainnet on Oct 29 2026 (`to` 0.9 s, the slowest), so they are
+ * read without `totalCount`, newest indexed row first (`aid`, the primary
+ * key). The index stores no time or height for these rows.
+ */
+import { z } from 'zod';
+import { TOKEN_DECIMALS_NOTE } from '../../summaries';
+import { defineKind, type KindResult } from '../types';
+import { accountArg, firstArg } from '../../queries';
+import { text } from '../../summaries';
+import {
+  PAGE,
+  accountFor,
+  amountText,
+  compact,
+  connection,
+  equalTo,
+  idText,
+  listResult,
+  longText,
+  opt,
+  str,
+  unexpected,
+} from './shared';
+
+const DIRECTIONS = ['in', 'out', 'retired', 'cancelled'] as const;
+type Direction = (typeof DIRECTIONS)[number];
+
+const args = z.strictObject({
+  address: accountArg('Token holder'),
+  direction: z
+    .enum(DIRECTIONS)
+    .optional()
+    .describe(
+      'in (received), out (sent), retired or cancelled. Default: in and out.',
+    ),
+  first: firstArg,
+});
+
+const TRANSFER_FIELDS = 'aid from to amount tokenId token { name collection }';
+
+/** The sub-fields (name, root and fields) a direction reads. */
+const SUBFIELDS: Record<
+  Direction,
+  { name: string; root: string; column: string; fields: string }
+> = {
+  out: {
+    name: 'sent',
+    root: 'tokenTransactions',
+    column: 'from',
+    fields: TRANSFER_FIELDS,
+  },
+  in: {
+    name: 'received',
+    root: 'tokenTransactions',
+    column: 'to',
+    fields: TRANSFER_FIELDS,
+  },
+  retired: {
+    name: 'retired',
+    root: 'tokenRetireds',
+    column: 'owner',
+    fields: 'aid id name amount reason jurisdiction',
+  },
+  cancelled: {
+    name: 'cancelled',
+    root: 'tokenCancelleds',
+    column: 'owner',
+    fields: 'aid id name amount reason',
+  },
+};
+
+const transferNode = z.looseObject({
+  aid: z.number(),
+  from: str,
+  to: str,
+  amount: z.union([z.string(), z.number()]),
+  tokenId: str,
+  token: z.looseObject({ name: opt, collection: opt }).nullish(),
+});
+const burnNode = z.looseObject({
+  aid: z.number(),
+  id: str,
+  name: opt,
+  amount: z.union([z.string(), z.number()]),
+  reason: opt,
+  jurisdiction: opt,
+});
+const answer = z.looseObject({
+  sent: connection(transferNode).optional(),
+  received: connection(transferNode).optional(),
+  retired: connection(burnNode).optional(),
+  cancelled: connection(burnNode).optional(),
+});
+
+type Row = { aid: number; item: Record<string, unknown> };
+
+function transferRows(
+  nodes: z.infer<typeof transferNode>[],
+  direction: 'sent' | 'received',
+): Row[] {
+  return nodes.map((node) => {
+    // An empty sender is a mint, an empty recipient a burn.
+    const counterparty = direction === 'sent' ? node.to : node.from;
+    return {
+      aid: node.aid,
+      item: compact({
+        direction,
+        tokenId: idText(node.tokenId),
+        name: text(node.token?.name),
+        collection: idText(node.token?.collection),
+        amount: amountText(node.amount),
+        counterparty: idText(counterparty),
+        minted: direction === 'received' && !node.from ? true : undefined,
+        burned: direction === 'sent' && !node.to ? true : undefined,
+      }),
+    };
+  });
+}
+
+function burnRows(
+  nodes: z.infer<typeof burnNode>[],
+  direction: 'retired' | 'cancelled',
+): Row[] {
+  return nodes.map((node) => ({
+    aid: node.aid,
+    item: compact({
+      direction,
+      tokenId: idText(node.id),
+      name: text(node.name),
+      amount: amountText(node.amount),
+      reason: longText(node.reason),
+      jurisdiction: text(node.jurisdiction, 80),
+    }),
+  }));
+}
+
+export const tokenHistory = defineKind({
+  name: 'token_history',
+  summary:
+    'IXO 1155 token movements of an account (default: the user): received, sent, retired or cancelled.',
+  explain: [
+    'IXO 1155 tokens (impact tokens, carbon credits, SUPA…) move between accounts; retiring one takes it out of circulation for good, with a reason and a jurisdiction (an offset claim), and cancelling one voids it.',
+    'Each row: direction (received, sent, retired, cancelled), tokenId, name (the token class), collection, amount and, for transfers, the counterparty.',
+    '`minted: true` marks a received row with no sender (newly minted to the account); `burned: true` a sent row with no recipient.',
+    'IXO 1155 tokens have no decimals on chain: amounts are whole units.',
+    'Rows are newest indexed first; the index keeps no time or block height for them, so ask `transactions` for when.',
+    'With no direction, received and sent are merged; `more: true` when the index holds older rows.',
+  ].join(' '),
+  source: 'blocksync',
+  list: true,
+  args,
+  example: { direction: 'retired', first: 5 },
+  plan(input, ctx) {
+    const holder = accountFor(input.address, ctx.identity, 'address');
+    if ('invalid' in holder) return holder;
+    const directions: Direction[] = input.direction
+      ? [input.direction]
+      : ['in', 'out'];
+    const n = ctx.first;
+    const subfields = directions
+      .map((direction) => {
+        const { name, root, column, fields } = SUBFIELDS[direction];
+        return `${name}: ${root}(filter: ${equalTo(column, holder.address)}, first: ${n}, orderBy: PRIMARY_KEY_DESC) { ${PAGE} nodes { ${fields} } }`;
+      })
+      .join(' ');
+    return {
+      source: 'blocksync',
+      field: (alias) => `${alias}: query { ${subfields} }`,
+      shape(raw): KindResult {
+        const parsed = answer.safeParse(raw);
+        if (!parsed.success) return { ok: false, ...unexpected };
+        const { sent, received, retired, cancelled } = parsed.data;
+        const parts = [sent, received, retired, cancelled];
+        // A transfer to oneself is not indexed, so no row is in both lists.
+        const rows = [
+          ...transferRows(sent?.nodes ?? [], 'sent'),
+          ...transferRows(received?.nodes ?? [], 'received'),
+          ...burnRows(retired?.nodes ?? [], 'retired'),
+          ...burnRows(cancelled?.nodes ?? [], 'cancelled'),
+        ].sort((a, b) => b.aid - a.aid);
+        const more =
+          rows.length > n ||
+          parts.some((part) => part?.pageInfo?.hasNextPage === true);
+        return listResult(
+          {
+            note: TOKEN_DECIMALS_NOTE,
+            items: rows.slice(0, n).map((row) => row.item),
+            more: more ? true : undefined,
+          },
+          n,
+          holder.subject,
+        );
+      },
+    };
+  },
+});

package/src/plugins/ixo-chain/kinds/registry.ts

@@ -0,0 +1,43 @@
+/**
+ * Every `chain_lookup` kind, in catalogue order: the core kinds, then the
+ * chain REST kinds, then the Blocksync-indexed kinds. Names are unique:
+ * a name registered twice fails the module at load.
+ */
+import { CHAIN_KINDS } from './chain';
+import { CORE_KINDS } from './core';
+import { INDEXED_KINDS } from './indexed';
+import type { KindDef } from './types';
+
+/** `kinds` by name; throws when two share a name. */
+export function indexKinds(
+  kinds: readonly KindDef[],
+): ReadonlyMap<string, KindDef> {
+  const byName = new Map<string, KindDef>();
+  for (const kind of kinds) {
+    if (byName.has(kind.name))
+      throw new Error(`ixo-chain: kind "${kind.name}" is registered twice`);
+    byName.set(kind.name, kind);
+  }
+  return byName;
+}
+
+export const KINDS: readonly KindDef[] = [
+  ...CORE_KINDS,
+  ...CHAIN_KINDS,
+  ...INDEXED_KINDS,
+];
+
+const BY_NAME = indexKinds(KINDS);
+
+function namesOf(kinds: readonly KindDef[]): [string, ...string[]] {
+  const [first, ...rest] = kinds.map((kind) => kind.name);
+  if (first === undefined) throw new Error('ixo-chain: no kinds registered');
+  return [first, ...rest];
+}
+
+/** Every kind's name in catalogue order: the `kind` enum of `chain_lookup`. */
+export const kindNames = namesOf(KINDS);
+
+export function kindByName(name: string): KindDef | undefined {
+  return BY_NAME.get(name);
+}

package/src/plugins/ixo-chain/kinds/types.ts

@@ -0,0 +1,156 @@
+/**
+ * The contract every `chain_lookup` kind implements. A kind is one named
+ * read the model can ask for: its arguments, a one-line summary for the
+ * catalogue `describe_chain_kinds` returns, a longer explanation shown
+ * only on request, and a plan that answers it either as one aliased field
+ * of the call's single Blocksync document or as chain REST reads.
+ *
+ * Arguments are validated by the kind's own schema inside
+ * {@link defineKind}: `chain_lookup`'s tool schema only names the kind, so
+ * the catalogue does not cost context on every turn.
+ */
+import type { z } from 'zod';
+import type { UserIdentity } from '../../../core/user-identity';
+import type { TokenDisplay } from '../denoms';
+import type { ChainCall, Failure, Outcome, Source } from '../http';
+import type { Subject } from '../queries';
+import type { Absent } from '../rest';
+
+/** How a kind bounds one REST read, and which answers mean "none". */
+export interface KindRestOptions {
+  label: string;
+  notFoundOn404?: boolean;
+  maxBytes?: number;
+  /**
+   * HTTP statuses that mean "there is none" (e.g. `[400, 404]` for a vote
+   * never cast): such an answer is `{ ok: true, absent: true }`, not a
+   * failure, and is not logged.
+   */
+  noneOn?: readonly number[];
+}
+
+/** What a kind's plan may use: the call, the user and the call's shared readers. */
+export interface KindContext {
+  call: ChainCall;
+  identity: UserIdentity;
+  /**
+   * Rows a list kind returns: the request's `first`, already clamped to
+   * 1–20 and scaled down for a batch of several requests.
+   */
+  first: number;
+  /**
+   * A chain REST GET through the call's shared concurrency limit and the
+   * plugin's retry policy. `path` is appended to the REST base and must
+   * only carry values the kind validated.
+   */
+  rest<S extends z.ZodType>(
+    path: string,
+    schema: S,
+    opts: KindRestOptions & { noneOn?: undefined },
+  ): Promise<Outcome<z.infer<S>>>;
+  rest<S extends z.ZodType>(
+    path: string,
+    schema: S,
+    opts: KindRestOptions & { noneOn: readonly number[] },
+  ): Promise<Outcome<z.infer<S>> | Absent>;
+  /**
+   * How a bank denom is shown (`denoms.ts`, with the oracle's IBC table:
+   * the network's built-in entries and `IXO_CHAIN_IBC_DENOMS`). Lookups are
+   * cached per isolate and run through the call's REST limit; one request
+   * looks up at most a fixed number of distinct denoms, and any further one
+   * is shown unread (base units, `metadataUnavailable`).
+   */
+  display(denom: string): Promise<TokenDisplay>;
+}
+
+/** One kind's answer. `subject` says whether it is about the user. */
+export type KindResult =
+  | {
+      ok: true;
+      data: unknown;
+      subject?: Subject;
+      /** The rows a list kind asked for. */
+      first?: number;
+    }
+  | ({ ok: false } & Failure);
+
+/** How a validated request is answered. */
+export type KindPlan =
+  | {
+      source: 'blocksync';
+      /** The aliased root field (`${alias}: …`) for the call's one document. */
+      field(alias: string): string;
+      /** The answer from that alias's data (null when the index has none). */
+      shape(raw: unknown): KindResult | Promise<KindResult>;
+    }
+  | {
+      source: 'chain';
+      run(): Promise<KindResult>;
+    };
+
+/** A request the kind refuses before any read: the detail the model sees. */
+export type KindInvalid = { invalid: string };
+
+/** A registered kind, its argument types erased. */
+export interface KindDef {
+  name: string;
+  /** One line for the catalogue: what question it answers. */
+  summary: string;
+  /** What the result means (types, units, how to read it); shown only on request. */
+  explain: string;
+  source: Source;
+  /** Whether the kind returns a list honouring `first`. */
+  list: boolean;
+  /** The argument schema (for `describe_chain_kinds`). */
+  args: z.ZodType;
+  /** A valid `args` object. */
+  example: Record<string, unknown>;
+  /** Validates `rawArgs` and returns the plan, or why the request is refused. */
+  plan(rawArgs: unknown, ctx: KindContext): KindPlan | KindInvalid;
+}
+
+/** The argument problems as one sentence naming what the kind expects. */
+function invalidArgs(name: string, error: z.ZodError): KindInvalid {
+  const issues = error.issues
+    .slice(0, 3)
+    .map((issue) =>
+      issue.path.length
+        ? `${issue.path.join('.')}: ${issue.message}`
+        : issue.message,
+    )
+    .join('; ');
+  return {
+    invalid: `Invalid args for kind "${name}" (${issues}). Call describe_chain_kinds with ["${name}"] for its arguments.`,
+  };
+}
+
+/**
+ * A kind from its typed spec: `plan` receives the arguments already parsed
+ * by `args`, so a kind never reads unvalidated input.
+ */
+export function defineKind<S extends z.ZodType>(spec: {
+  name: string;
+  summary: string;
+  explain: string;
+  source: Source;
+  list: boolean;
+  args: S;
+  example: z.input<S> & Record<string, unknown>;
+  plan(args: z.output<S>, ctx: KindContext): KindPlan | KindInvalid;
+}): KindDef {
+  return {
+    name: spec.name,
+    summary: spec.summary,
+    explain: spec.explain,
+    source: spec.source,
+    list: spec.list,
+    args: spec.args,
+    example: spec.example,
+    plan(rawArgs, ctx) {
+      const parsed = spec.args.safeParse(rawArgs ?? {});
+      return parsed.success
+        ? spec.plan(parsed.data, ctx)
+        : invalidArgs(spec.name, parsed.error);
+    },
+  };
+}