@ixo/oracle-runtime-workers 0.29.1 → 0.31.0

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

@@ -0,0 +1,160 @@
+/**
+ * `liquid_stake_history`: an account's liquid staking events (x/liquidstake
+ * stake and unstake) as Blocksync indexed them.
+ *
+ * Index (ixo-blocksync main, `20260101000000000_v7-upgrade.sql`):
+ * `LiquidStakeTx_delegator_idx` ("delegator"); ordered by the primary key
+ * `id` (indexing order), newest first. `payload` is the event's attributes;
+ * since chain v7 its amounts are coins (`{ denom, amount }`), before it
+ * `"<amount><denom>"` strings: both are read.
+ */
+import { z } from 'zod';
+import {
+  COINS_NOTE,
+  displayCoin,
+  type ChainCoin,
+  type DisplayCoin,
+} from '../coins';
+import { defineKind, type KindContext, type KindResult } from '../types';
+import { accountArg, firstArg } from '../../queries';
+import { text } from '../../summaries';
+import {
+  PAGE,
+  accountFor,
+  chainCoin,
+  compact,
+  connection,
+  equalTo,
+  idText,
+  listResult,
+  num,
+  opt,
+  str,
+  unexpected,
+} from './shared';
+import { isRecord } from '../../summaries';
+
+const args = z.strictObject({
+  address: accountArg('Delegator'),
+  first: firstArg,
+});
+
+const FIELDS = 'kind poolId payload transactionHash height timestamp';
+
+const node = z.looseObject({
+  kind: str,
+  poolId: opt,
+  payload: z.unknown().optional(),
+  transactionHash: opt,
+  height: num,
+  timestamp: opt,
+});
+
+/** What each event kind means, in a few words. */
+const MEANING: Record<string, string> = {
+  stake: 'staked through the pool, receiving its liquid token',
+  unstake: "returned the pool's liquid token to unstake",
+  autocompound: 'the pool restaked its rewards',
+  rebalance: 'the pool moved stake between validators',
+  addValidator: 'a validator joined the pool',
+};
+
+/** The payload keys of each event's amounts and the names they get. */
+const AMOUNTS: Record<string, Record<string, string>> = {
+  stake: { liquid_amount: 'staked', stk_ixo_minted_amount: 'received' },
+  unstake: {
+    unstake_amount: 'returned',
+    unbonding_amount: 'unbonding',
+    unbonded_amount: 'unbonded',
+  },
+  autocompound: {
+    total_amount: 'total',
+    fee_amount: 'fee',
+    redelegate_amount: 'restaked',
+    weighted_rewards_amount: 'weightedRewards',
+  },
+};
+
+const LEGACY_COIN = /^(\d{1,80})([a-zA-Z][a-zA-Z0-9/:._-]{2,127})$/;
+
+/** A payload amount: a coin object, or the `"<amount><denom>"` string events carried before v7. */
+function payloadCoin(value: unknown): ChainCoin | undefined {
+  if (typeof value === 'string') {
+    const match = LEGACY_COIN.exec(value);
+    return match ? chainCoin({ denom: match[2], amount: match[1] }) : undefined;
+  }
+  return chainCoin(value);
+}
+
+/** The event's bank coins by what each is (`staked`, `received`…). */
+async function coinsOf(
+  ctx: KindContext,
+  kind: string,
+  payload: Record<string, unknown>,
+): Promise<Record<string, DisplayCoin> | undefined> {
+  const coins: Record<string, DisplayCoin> = {};
+  for (const [key, name] of Object.entries(AMOUNTS[kind] ?? {})) {
+    const coin = payloadCoin(payload[key]);
+    const shown = coin ? await displayCoin(ctx, coin) : null;
+    if (shown) coins[name] = shown;
+  }
+  return Object.keys(coins).length ? coins : undefined;
+}
+
+async function eventOf(ctx: KindContext, row: z.infer<typeof node>) {
+  const payload = isRecord(row.payload) ? row.payload : {};
+  return compact({
+    kind: text(row.kind, 40),
+    meaning: MEANING[row.kind],
+    poolId: idText(row.poolId),
+    coins: await coinsOf(ctx, row.kind, payload),
+    completionTime:
+      row.kind === 'unstake' ? idText(payload.completion_time) : undefined,
+    txHash: idText(row.transactionHash),
+    height:
+      row.height === null || row.height === undefined
+        ? undefined
+        : idText(String(row.height)),
+    time: idText(row.timestamp),
+  });
+}
+
+export const liquidStakeHistory = defineKind({
+  name: 'liquid_stake_history',
+  summary:
+    'Liquid staking history of an account (default: the user): stakes and unstakes per pool, newest first.',
+  explain: [
+    'Liquid staking stakes IXO through a pool that spreads it over validators and gives back the pool’s liquid token (e.g. PAY for the `pay` pool), which can be held or moved while the IXO stays staked.',
+    'Each row’s bank coins are in `coins`, by what each is. A `stake` row: `coins.staked` (IXO in) and `coins.received` (liquid token out). An `unstake` row: `coins.returned` (liquid token handed back), `coins.unbonding` (IXO now unbonding, paid out at `completionTime`) and `coins.unbonded` (IXO paid at once). An `autocompound` row: `coins.total`, `coins.fee`, `coins.restaked`, `coins.weightedRewards`.',
+    COINS_NOTE,
+    'Each row also has poolId, txHash, height and time. Ask `liquid_staking` for the pools and the account’s current liquid token balance.',
+  ].join(' '),
+  source: 'blocksync',
+  list: true,
+  args,
+  example: { first: 5 },
+  plan(input, ctx) {
+    const delegator = accountFor(input.address, ctx.identity, 'address');
+    if ('invalid' in delegator) return delegator;
+    const n = ctx.first;
+    return {
+      source: 'blocksync',
+      field: (alias) =>
+        `${alias}: liquidStakeTxes(filter: ${equalTo('delegator', delegator.address)}, first: ${n}, orderBy: ID_DESC) { ${PAGE} nodes { ${FIELDS} } }`,
+      async shape(raw): Promise<KindResult> {
+        const parsed = connection(node).safeParse(raw);
+        if (!parsed.success) return { ok: false, ...unexpected };
+        return listResult(
+          {
+            items: await Promise.all(
+              parsed.data.nodes.map((row) => eventOf(ctx, row)),
+            ),
+            more: parsed.data.pageInfo?.hasNextPage ? true : undefined,
+          },
+          n,
+          delegator.subject,
+        );
+      },
+    };
+  },
+});

package/src/plugins/ixo-chain/kinds/indexed/member-budgets.ts

@@ -0,0 +1,175 @@
+/**
+ * `member_budgets`: an account's per-period spending budgets in team
+ * claim collections (x/claims `MemberBudget`).
+ *
+ * Index (ixo-blocksync main): `MemberBudget_memberAddress_idx`
+ * ("memberAddress") serves the account; the primary key ("collectionId",
+ * "memberAddress") serves a collection with it and gives the order
+ * (collection id as text).
+ */
+import { z } from 'zod';
+import { literal } from '../../queries';
+import { COINS_NOTE, displayCoins, type ChainCoin } from '../coins';
+import { defineKind, type KindContext, type KindResult } from '../types';
+import { accountArg, firstArg } from '../../queries';
+import {
+  PAGE,
+  accountFor,
+  chainCoins,
+  collectionIdArg,
+  compact,
+  connection,
+  cw20Amounts,
+  idText,
+  listResult,
+  num,
+  opt,
+  reached,
+  str,
+  unexpected,
+} from './shared';
+
+const args = z.strictObject({
+  address: accountArg('Team member'),
+  collectionId: collectionIdArg('Only this collection, e.g. "8250".'),
+  first: firstArg,
+});
+
+const FIELDS =
+  'collectionId memberAddress periodNs periodSpendLimit periodSpent periodCw20SpendLimit periodCw20Spent periodResetAt updatedAt';
+
+const node = z.looseObject({
+  collectionId: str,
+  memberAddress: str,
+  periodNs: num,
+  periodSpendLimit: z.unknown().optional(),
+  periodSpent: z.unknown().optional(),
+  periodCw20SpendLimit: z.unknown().optional(),
+  periodCw20Spent: z.unknown().optional(),
+  periodResetAt: opt,
+  updatedAt: opt,
+});
+
+const DIGITS = /^\d+$/;
+const NS_PER_SECOND = 1_000_000_000n;
+
+/** A period in nanoseconds as days, hours or seconds (the largest unit it divides into). */
+function periodLabel(
+  value: string | number | null | undefined,
+): string | undefined {
+  if (value === null || value === undefined) return undefined;
+  const ns = String(value);
+  if (!DIGITS.test(ns)) return undefined;
+  const seconds = BigInt(ns) / NS_PER_SECOND;
+  if (seconds > 0n && seconds % 86_400n === 0n)
+    return `${seconds / 86_400n} days`;
+  if (seconds > 0n && seconds % 3_600n === 0n)
+    return `${seconds / 3_600n} hours`;
+  return `${seconds} seconds`;
+}
+
+/**
+ * Per limit denom, what is left this period: the limit less what counts
+ * as spent in it (never below zero).
+ */
+function remainingOf(limit: ChainCoin[], spent: ChainCoin[]): ChainCoin[] {
+  return limit.map((coin) => {
+    const used = spent.find((entry) => entry.denom === coin.denom);
+    const left = BigInt(coin.amount) - (used ? BigInt(used.amount) : 0n);
+    return { denom: coin.denom, amount: String(left > 0n ? left : 0n) };
+  });
+}
+
+/**
+ * An empty limit lets the member commit none of that kind (x/claims
+ * checks an intent's coins against the limit less what was spent, and a
+ * denom or cw20 contract it does not list has nothing left); the chain
+ * refuses a budget with neither a native nor a cw20 limit.
+ */
+const NONE_ALLOWED = 'none allowed';
+/** What was spent this period, or `"none"`. */
+const spentOrNone = <T>(list: T[]): T[] | 'none' =>
+  list.length ? list : 'none';
+
+async function budgetOf(
+  ctx: KindContext,
+  row: z.infer<typeof node>,
+  now: number,
+) {
+  const limit = chainCoins(row.periodSpendLimit);
+  const cw20Limit = cw20Amounts(row.periodCw20SpendLimit);
+  // After the reset time nothing spent counts: the chain zeroes it at the
+  // member's next intent.
+  const resetDue = reached(row.periodResetAt, now) === true;
+  const spent = resetDue ? [] : chainCoins(row.periodSpent);
+  const cw20Spent = resetDue ? [] : cw20Amounts(row.periodCw20Spent);
+  const [spendLimit, spentShown, remaining] = await Promise.all([
+    displayCoins(ctx, limit),
+    displayCoins(ctx, spent),
+    displayCoins(ctx, remainingOf(limit, spent)),
+  ]);
+  const native = spendLimit.length > 0;
+  return compact({
+    collectionId: idText(row.collectionId),
+    member: idText(row.memberAddress),
+    period: periodLabel(row.periodNs),
+    spendLimit: native ? spendLimit : NONE_ALLOWED,
+    spent: spentOrNone(spentShown),
+    remaining: native ? remaining : undefined,
+    cw20SpendLimit: cw20Limit.length ? cw20Limit : NONE_ALLOWED,
+    cw20Spent: spentOrNone(cw20Spent),
+    resetAt: idText(row.periodResetAt),
+    resetDue: resetDue ? true : undefined,
+    updatedAt: idText(row.updatedAt),
+  });
+}
+
+export const memberBudgets = defineKind({
+  name: 'member_budgets',
+  summary:
+    'Spending budgets an account (default: the user) has as a team member of claim collections.',
+  explain: [
+    'A collection with member budgets is a team collection: every claim intent on it is made on behalf of a member, and each member may commit at most `spendLimit` of the collection’s payments per `period` (at least 24 hours).',
+    '`spendLimit` is bank coins (a denom it does not list may not be committed), or `"none allowed"`: no bank coin, only the cw20 tokens of `cw20SpendLimit` (likewise `"none allowed"` when no cw20 token may be committed).',
+    'Committing an intent adds its amount to `spent` (`"none"` when nothing counts this period); a rejected, disputed or invalidated claim, or an intent that expires unused, gives it back within the same period.',
+    '`remaining` is the limit less what was spent this period. The period rolls over at `resetAt`, lazily: `resetDue: true` means that time has passed, so nothing spent counts any more and the chain zeroes it at the member’s next intent.',
+    COINS_NOTE,
+    '`cw20SpendLimit`/`cw20Spent` are base units per cw20 token contract. cw1155 payments are not budgeted.',
+    'Ordered by collection id as text. Empty when the account is not a member of any team collection.',
+  ].join(' '),
+  source: 'blocksync',
+  list: true,
+  args,
+  example: { collectionId: '8250' },
+  plan(input, ctx) {
+    const member = accountFor(input.address, ctx.identity, 'address');
+    if ('invalid' in member) return member;
+    const n = ctx.first;
+    const filter = literal({
+      memberAddress: { equalTo: member.address },
+      ...(input.collectionId !== undefined
+        ? { collectionId: { equalTo: input.collectionId } }
+        : {}),
+    });
+    return {
+      source: 'blocksync',
+      field: (alias) =>
+        `${alias}: memberBudgets(filter: ${filter}, first: ${n}, orderBy: PRIMARY_KEY_ASC) { ${PAGE} nodes { ${FIELDS} } }`,
+      async shape(raw): Promise<KindResult> {
+        const parsed = connection(node).safeParse(raw);
+        if (!parsed.success) return { ok: false, ...unexpected };
+        const now = Date.now();
+        return listResult(
+          {
+            items: await Promise.all(
+              parsed.data.nodes.map((row) => budgetOf(ctx, row, now)),
+            ),
+            more: parsed.data.pageInfo?.hasNextPage ? true : undefined,
+          },
+          n,
+          member.subject,
+        );
+      },
+    };
+  },
+});

package/src/plugins/ixo-chain/kinds/indexed/shared.ts

@@ -0,0 +1,211 @@
+/**
+ * What the Blocksync-indexed kinds share: argument schemas and patterns,
+ * the clipping every indexed string gets, bank coins and cw20 amounts, and
+ * the parsing of the index's timestamps.
+ *
+ * Every string from the index is chain data written by anyone and is
+ * clipped (ids, addresses and dates 120 characters, names and labels 200,
+ * long text 240). Amounts stay strings: base units never pass through
+ * `Number`. Bank coins are shown through `../coins.ts`.
+ */
+import { z } from 'zod';
+import type { UserIdentity } from '../../../../core/user-identity';
+import type { Failure } from '../../http';
+import { accountOf, literal, type Subject } from '../../queries';
+import { EXCERPT_CHARS, ID_CHARS, clip, isRecord, text } from '../../summaries';
+import {
+  COIN_CAP,
+  displayCoins,
+  wholeUnits,
+  type ChainCoin,
+  type DisplayCoin,
+} from '../coins';
+import type { KindContext, KindInvalid, KindResult } from '../types';
+
+const COLLECTION_ID = /^\d{1,12}$/;
+/** A claim id as the core `claim` kind takes it (a CID such as `bafkrei…`). */
+const CLAIM_ID = /^[a-z0-9]{20,100}$/i;
+/** A CosmWasm contract address: `ixo1` and 58 bech32 characters (32 bytes). */
+export const CONTRACT_ADDRESS = /^ixo1[02-9ac-hj-np-z]{58}$/;
+
+const LIST_CAP = 10;
+
+export const collectionIdArg = (role: string) =>
+  z
+    .string()
+    .regex(COLLECTION_ID, 'a collection number such as "8250"')
+    .optional()
+    .describe(role);
+
+export const claimIdArg = (role: string) =>
+  z
+    .string()
+    .regex(CLAIM_ID, 'a claim id (a CID such as "bafkrei…")')
+    .optional()
+    .describe(role);
+
+/** The account an account argument names (the user's by default), or why it cannot be asked. */
+export function accountFor(
+  input: string | undefined,
+  identity: UserIdentity,
+  role: string,
+): { address: string; subject: Subject } | KindInvalid {
+  const account = accountOf(input, identity, role);
+  return account.ok
+    ? { address: account.address, subject: account.subject }
+    : { invalid: account.detail };
+}
+
+/** `{ column: { equalTo: value } }` as a GraphQL filter literal. */
+export const equalTo = (column: string, value: string): string =>
+  literal({ [column]: { equalTo: value } });
+
+/** An id, address or date, clipped to {@link ID_CHARS}. */
+export const idText = (value: unknown) => text(value, ID_CHARS);
+
+/** Long free text (a reason, a description), clipped to {@link EXCERPT_CHARS}. */
+export const longText = (value: unknown) => text(value, EXCERPT_CHARS);
+
+/** An amount (string or number) as clipped text; undefined otherwise. */
+export function amountText(value: unknown): string | undefined {
+  return typeof value === 'string' || typeof value === 'number'
+    ? clip(String(value), 80)
+    : undefined;
+}
+
+/** Drops undefined entries so absent fields cost nothing in the answer. */
+export function compact<T extends Record<string, unknown>>(value: T): T {
+  for (const key of Object.keys(value))
+    if (value[key] === undefined) delete value[key];
+  return value;
+}
+
+export const nonEmpty = <T>(list: T[]): T[] | undefined =>
+  list.length ? list : undefined;
+
+/**
+ * One `{ denom, amount }` bank coin from the index, its amount in whole
+ * base units; undefined for anything else (an amount that is not a
+ * non-negative decimal included).
+ */
+export function chainCoin(value: unknown): ChainCoin | undefined {
+  if (!isRecord(value)) return undefined;
+  const denom = idText(value.denom);
+  const amount = amountText(value.amount);
+  const units = amount === undefined ? null : wholeUnits(amount);
+  return denom && units !== null ? { denom, amount: units } : undefined;
+}
+
+/** The bank coins of a JSON coin array, at most {@link COIN_CAP}; anything else is left out. */
+export function chainCoins(value: unknown): ChainCoin[] {
+  if (!Array.isArray(value)) return [];
+  const out: ChainCoin[] = [];
+  for (const entry of value) {
+    if (out.length >= COIN_CAP) break;
+    const coin = chainCoin(entry);
+    if (coin) out.push(coin);
+  }
+  return out;
+}
+
+/** The bank coins of a JSON coin array as shown; undefined when there are none. */
+export async function bankCoins(
+  ctx: Pick<KindContext, 'display'>,
+  value: unknown,
+): Promise<DisplayCoin[] | undefined> {
+  return nonEmpty(await displayCoins(ctx, chainCoins(value)));
+}
+
+/** cw20 amounts (`[{ address, amount }]`, base units of each token contract), at most ten. */
+export function cw20Amounts(
+  value: unknown,
+): { address: string; amountBaseUnits: string }[] {
+  if (!Array.isArray(value)) return [];
+  const out: { address: string; amountBaseUnits: string }[] = [];
+  for (const entry of value) {
+    if (out.length >= LIST_CAP) break;
+    if (!isRecord(entry)) continue;
+    const address = idText(entry.address);
+    const amountBaseUnits = amountText(entry.amount);
+    if (address && amountBaseUnits) out.push({ address, amountBaseUnits });
+  }
+  return out;
+}
+
+/**
+ * cw1155 amounts (x/claims `CW1155Payment`: `[{ address, token_id, amount }]`,
+ * whole units of the listed token ids of each contract), at most ten.
+ */
+export function cw1155Amounts(
+  value: unknown,
+): { address: string; tokenIds?: string[]; amount: string }[] {
+  if (!Array.isArray(value)) return [];
+  const out: { address: string; tokenIds?: string[]; amount: string }[] = [];
+  for (const entry of value) {
+    if (out.length >= LIST_CAP) break;
+    if (!isRecord(entry)) continue;
+    const address = idText(entry.address);
+    const amount = amountText(entry.amount);
+    const ids = entry.token_id ?? entry.tokenId;
+    const tokenIds = Array.isArray(ids)
+      ? ids.slice(0, LIST_CAP).flatMap((id) => {
+          const shown = idText(id);
+          return shown ? [shown] : [];
+        })
+      : [];
+    if (address && amount)
+      out.push(compact({ address, tokenIds: nonEmpty(tokenIds), amount }));
+  }
+  return out;
+}
+
+const OFFSET = /(Z|[+-]\d{2}:?\d{2})$/;
+
+/**
+ * Epoch ms of an index timestamp. Blocksync's `TIMESTAMP(3)` columns hold
+ * UTC without an offset (`2026-10-29T14:55:29.676`), so one without an
+ * offset is read as UTC; NaN when it is not a date.
+ */
+function timeOf(value: string): number {
+  return Date.parse(OFFSET.test(value) ? value : `${value}Z`);
+}
+
+/** Whether `value` is an index timestamp at or before `now`; undefined when it is not one. */
+export function reached(value: unknown, now: number): boolean | undefined {
+  if (typeof value !== 'string') return undefined;
+  const at = timeOf(value);
+  return Number.isNaN(at) ? undefined : at <= now;
+}
+
+export const unexpected: Failure = {
+  reason: 'unavailable',
+  detail: 'Blocksync answered this request in an unexpected shape.',
+  retryable: false,
+};
+
+/** A list answer: the rows, and `more` when the index holds rows past them. */
+export const connection = <T extends z.ZodType>(node: T) =>
+  z.looseObject({
+    pageInfo: z.object({ hasNextPage: z.boolean() }).optional(),
+    nodes: z.array(node),
+  });
+
+export const PAGE = 'pageInfo { hasNextPage }';
+
+/** A list kind's answer by account or filter. */
+export function listResult(
+  data: Record<string, unknown>,
+  first: number,
+  subject?: Subject,
+): KindResult {
+  return {
+    ok: true,
+    data: compact(data),
+    first,
+    ...(subject ? { subject } : {}),
+  };
+}
+
+export const str = z.string();
+export const opt = z.string().nullish();
+export const num = z.union([z.string(), z.number()]).nullish();