@ixo/oracle-runtime-workers 0.29.1 → 0.31.0

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

@@ -0,0 +1,220 @@
+/**
+ * `staking`: an account's delegations, unbonding entries and pending
+ * rewards, with each validator's moniker. Three reads at once; monikers
+ * come from a per-isolate cache. A failed rewards read leaves the
+ * delegations standing, marked `rewardsUnavailable`.
+ */
+import { z } from 'zod';
+import { defineKind, type KindContext, type KindResult } from '../types';
+import { displayCoin, ixo, wholeUnits } from '../coins';
+import { clip } from '../../summaries';
+import {
+  ReadCache,
+  accountFor,
+  addressArg,
+  coinSchema,
+  coinsOr,
+  coinsSchema,
+  failed,
+} from './shared';
+
+/** A validator operator address. */
+const VALOPER = /^ixovaloper1[0-9a-z]{38,58}$/;
+/** Delegations and unbonding validators read per account (one page each). */
+const STAKING_PAGE = 50;
+/** Validators whose moniker is looked up per request; the others are shown by address. */
+const MONIKER_LOOKUPS = 20;
+/** A moniker (or a validator's absence) is reused for 10 min. */
+export const MONIKER_TTL_MS = 600_000;
+const MONIKER_CACHE_LIMIT = 256;
+
+const monikers = new ReadCache<string | null>(
+  MONIKER_TTL_MS,
+  MONIKER_CACHE_LIMIT,
+);
+
+const validatorResponse = z.object({
+  validator: z.object({ description: z.object({ moniker: z.string() }) }),
+});
+
+/** A validator's moniker; null when it has none or the chain has no such validator. */
+function monikerOf(ctx: KindContext, valoper: string) {
+  return monikers.get(ctx, valoper, async () => {
+    const read = await ctx.rest(
+      `/cosmos/staking/v1beta1/validators/${valoper}`,
+      validatorResponse,
+      { label: 'validator', notFoundOn404: true, maxBytes: 64 * 1024 },
+    );
+    if (read.ok)
+      return {
+        ok: true,
+        value: clip(read.value.validator.description.moniker, 60) || null,
+      };
+    return read.failure.reason === 'not_found'
+      ? { ok: true, value: null }
+      : read;
+  });
+}
+
+const pagination = z.object({ next_key: z.string().nullish() }).nullish();
+const delegationsResponse = z.object({
+  delegation_responses: z.array(
+    z.object({
+      delegation: z.object({ validator_address: z.string() }),
+      balance: coinSchema,
+    }),
+  ),
+  pagination,
+});
+const unbondingResponse = z.object({
+  unbonding_responses: z.array(
+    z.object({
+      validator_address: z.string(),
+      entries: z.array(
+        z.object({ completion_time: z.string(), balance: z.string() }),
+      ),
+    }),
+  ),
+  pagination,
+});
+const rewardsResponse = z.object({
+  rewards: z
+    .array(z.object({ validator_address: z.string(), reward: coinsSchema }))
+    .default([]),
+  total: coinsSchema.default([]),
+});
+
+/** The sum of whole base units. */
+const sum = (amounts: readonly string[]) =>
+  amounts.reduce((total, units) => total + BigInt(units), 0n).toString();
+
+const args = z.strictObject({ address: addressArg });
+
+export const stakingKind = defineKind({
+  name: 'staking',
+  summary:
+    "An account's staked IXO: delegations, unbonding, rewards waiting to be claimed.",
+  explain: [
+    'Staking = delegating IXO to validators, who secure the chain; delegated IXO earns rewards and is not in the bank balance. `delegations`: per validator (`moniker`, `validator` address) the IXO delegated now (`coin`). `unbonding`: IXO being undelegated (`coin`), returned to the bank balance at `completesAt` (it earns nothing meanwhile). `rewards`: earned and not yet withdrawn (claiming them is a transaction), in total and per validator (`coins`). `totals` adds them up. `rewardsUnavailable: true` = the rewards could not be read; the delegations still stand.',
+    'Liquid staking is staking too: IXO staked into a liquid staking pool (e.g. for PAY) is delegated by the pool, not by the account, so it is not listed here: see `liquid_staking`.',
+    '`staking: false` = no delegations and nothing unbonding (rewards may still be waiting). Amounts are display units (`amount` + `symbol`) with `amountBaseUnits`; reward fractions of a base unit are dropped. `moreDelegations` / `moreUnbonding` = more than 50 validators, the rest not read.',
+  ].join('\n'),
+  source: 'chain',
+  list: false,
+  args,
+  example: {},
+  plan(input, ctx) {
+    const account = accountFor(ctx, input.address);
+    if ('invalid' in account) return account;
+    return {
+      source: 'chain',
+      async run(): Promise<KindResult> {
+        const page = `pagination.limit=${STAKING_PAGE}`;
+        const [delegations, unbonding, rewards] = await Promise.all([
+          ctx.rest(
+            `/cosmos/staking/v1beta1/delegations/${account.address}?${page}`,
+            delegationsResponse,
+            { label: 'delegations' },
+          ),
+          ctx.rest(
+            `/cosmos/staking/v1beta1/delegators/${account.address}/unbonding_delegations?${page}`,
+            unbondingResponse,
+            { label: 'unbonding delegations' },
+          ),
+          ctx.rest(
+            `/cosmos/distribution/v1beta1/delegators/${account.address}/rewards`,
+            rewardsResponse,
+            { label: 'staking rewards' },
+          ),
+        ]);
+        if (!delegations.ok) return failed(delegations.failure);
+        if (!unbonding.ok) return failed(unbonding.failure);
+        const earned = rewards.ok ? rewards.value : null;
+        const validators = [
+          ...new Set([
+            ...delegations.value.delegation_responses.map(
+              (row) => row.delegation.validator_address,
+            ),
+            ...unbonding.value.unbonding_responses.map(
+              (row) => row.validator_address,
+            ),
+            ...(earned?.rewards ?? []).map((row) => row.validator_address),
+          ]),
+        ].filter((valoper) => VALOPER.test(valoper));
+        const names = new Map<string, string>();
+        await Promise.all(
+          validators.slice(0, MONIKER_LOOKUPS).map(async (valoper) => {
+            const moniker = await monikerOf(ctx, valoper);
+            if (moniker.ok && moniker.value) names.set(valoper, moniker.value);
+          }),
+        );
+        const who = (valoper: string) => {
+          const moniker = names.get(valoper);
+          return {
+            validator: clip(valoper, 80),
+            ...(moniker ? { moniker } : {}),
+          };
+        };
+        const delegated = await Promise.all(
+          delegations.value.delegation_responses.map(async (row) => ({
+            ...who(row.delegation.validator_address),
+            coin: await displayCoin(ctx, row.balance),
+          })),
+        );
+        // Unbonding balances are in the bond denom, uixo on every IXO network.
+        const entries = unbonding.value.unbonding_responses.flatMap((row) =>
+          row.entries.flatMap((entry) => {
+            const units = wholeUnits(entry.balance);
+            return units === null
+              ? []
+              : [
+                  {
+                    ...who(row.validator_address),
+                    coin: ixo(units),
+                    completesAt: entry.completion_time,
+                  },
+                ];
+          }),
+        );
+        const bonded = delegated.flatMap((row) =>
+          row.coin?.denom === 'uixo' ? [row.coin.amountBaseUnits] : [],
+        );
+        return {
+          ok: true,
+          subject: account.subject,
+          data: {
+            address: account.address,
+            staking: delegated.length > 0 || entries.length > 0,
+            delegations: delegated,
+            unbonding: entries,
+            ...(earned
+              ? {
+                  rewards: {
+                    total: await coinsOr(ctx, earned.total, 'none'),
+                    byValidator: await Promise.all(
+                      earned.rewards.map(async (row) => ({
+                        ...who(row.validator_address),
+                        coins: await coinsOr(ctx, row.reward, 'none'),
+                      })),
+                    ),
+                  },
+                }
+              : { rewardsUnavailable: true }),
+            totals: {
+              delegated: ixo(sum(bonded)),
+              unbonding: ixo(
+                sum(entries.map((row) => row.coin.amountBaseUnits)),
+              ),
+            },
+            ...(delegations.value.pagination?.next_key
+              ? { moreDelegations: true }
+              : {}),
+            ...(unbonding.value.pagination?.next_key
+              ? { moreUnbonding: true }
+              : {}),
+          },
+        };
+      },
+    };
+  },
+});

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

@@ -0,0 +1,112 @@
+/**
+ * Bank coins as every kind shows them: `{ denom, symbol, amount,
+ * amountBaseUnits, verified, origin?, trace?, metadataUnavailable? }`, the
+ * `amount` converted to display units through the call's denom displays
+ * (`KindContext.display`). IXO 1155 tokens are not bank coins: their
+ * amounts stay whole units.
+ */
+import { formatUnits, type IbcTrace, type TokenDisplay } from '../denoms';
+import type { KindContext } from './types';
+
+/** A bank coin as shown: display amount and symbol, with the base units it came from. */
+export type DisplayCoin = {
+  denom: string;
+  symbol: string;
+  /** Display units (`amountBaseUnits` ÷ 10^decimals); base units when unverified. */
+  amount: string;
+  amountBaseUnits: string;
+  verified: boolean;
+  /** The chain a verified IBC token came from: tells apart two tokens of one symbol. */
+  origin?: string;
+  /** What an unverified IBC token's trace claims: self-reported, never what the token is. */
+  trace?: IbcTrace;
+  /** Its metadata was not read: it may still be verified. */
+  metadataUnavailable?: true;
+};
+
+/** A chain coin: a denom and an amount as the chain's JSON gives it. */
+export type ChainCoin = { denom: string; amount: string };
+
+/** Coins shown per list; the rest are left out. */
+export const COIN_CAP = 10;
+
+/** The rule every kind's `explain` states for its bank coins. */
+export const COINS_NOTE =
+  'Bank coins: `amount` in display units beside `symbol` (uixo → IXO, upay → PAY, both 6 decimals), with `amountBaseUnits`; an unverified token (`verified: false`) is in base units under its full denom.';
+
+/**
+ * Whole base units of a Coin or DecCoin amount (a DecCoin's fraction, a
+ * share of one base unit, is dropped); null when it is not a non-negative
+ * decimal of at most 40 digits.
+ */
+export function wholeUnits(amount: string): string | null {
+  return /^(0|[1-9][0-9]{0,39})(?:\.[0-9]{1,18})?$/.exec(amount)?.[1] ?? null;
+}
+
+/** `baseUnits` of `denom` as shown with `display`. */
+export function coinView(
+  denom: string,
+  baseUnits: string,
+  display: TokenDisplay,
+): DisplayCoin {
+  return {
+    denom,
+    symbol: display.symbol,
+    amount: formatUnits(baseUnits, display.decimals),
+    amountBaseUnits: baseUnits,
+    verified: display.verified,
+    ...(display.origin !== undefined ? { origin: display.origin } : {}),
+    ...(display.trace !== undefined ? { trace: display.trace } : {}),
+    ...(display.metadataUnavailable ? { metadataUnavailable: true } : {}),
+  };
+}
+
+/** Each denom's display, looked up at once (the call's REST limit bounds them). */
+export async function displaysOf(
+  ctx: Pick<KindContext, 'display'>,
+  denoms: readonly string[],
+): Promise<Map<string, TokenDisplay>> {
+  const out = new Map<string, TokenDisplay>();
+  await Promise.all(
+    [...new Set(denoms)].map(async (denom) => {
+      out.set(denom, await ctx.display(denom));
+    }),
+  );
+  return out;
+}
+
+/** Coins as shown, at most `max`; an amount that is not a decimal is left out. */
+export async function displayCoins(
+  ctx: Pick<KindContext, 'display'>,
+  coins: readonly ChainCoin[],
+  max = COIN_CAP,
+): Promise<DisplayCoin[]> {
+  const shown = coins
+    .flatMap((coin) => {
+      const units = wholeUnits(coin.amount);
+      return units === null ? [] : [{ denom: coin.denom, units }];
+    })
+    .slice(0, max);
+  return Promise.all(
+    shown.map(async ({ denom, units }) =>
+      coinView(denom, units, await ctx.display(denom)),
+    ),
+  );
+}
+
+/** One coin as shown; null when its amount is not a decimal. */
+export async function displayCoin(
+  ctx: Pick<KindContext, 'display'>,
+  coin: ChainCoin,
+): Promise<DisplayCoin | null> {
+  return (await displayCoins(ctx, [coin], 1))[0] ?? null;
+}
+
+/** IXO as shown, from base units (uixo). */
+export function ixo(baseUnits: string): DisplayCoin {
+  return coinView('uixo', baseUnits, {
+    symbol: 'IXO',
+    decimals: 6,
+    verified: true,
+  });
+}

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

@@ -0,0 +1,246 @@
+/**
+ * The core kinds: claims, collections, entities, DID documents, 1155
+ * tokens and transactions, each one aliased root field of the call's
+ * Blocksync document. Their arguments, patterns and fields are in
+ * `queries.ts`; their answers are shaped by `summaries.ts`.
+ */
+import type { UserIdentity } from '../../../core/user-identity';
+import {
+  CORE_ARGS,
+  requestField,
+  type ChainRequest,
+  type Subject,
+} from '../queries';
+import { shapeResult } from '../summaries';
+import {
+  defineKind,
+  type KindContext,
+  type KindDef,
+  type KindInvalid,
+  type KindPlan,
+} from './types';
+
+/** Whose a by-id record is, from the accounts the answer names as its owners. */
+function ownerOf(
+  ownedBy: string[] | undefined,
+  identity: UserIdentity,
+): Subject | undefined {
+  if (!ownedBy) return undefined;
+  return identity.address && ownedBy.includes(identity.address)
+    ? 'user'
+    : 'other';
+}
+
+/** A core request as its aliased field and the shaping of that alias's answer. */
+function blocksyncPlan(
+  request: ChainRequest,
+  ctx: KindContext,
+): KindPlan | KindInvalid {
+  const plan = requestField(request, ctx.identity, ctx.first);
+  if (!plan.ok) return { invalid: plan.detail };
+  return {
+    source: 'blocksync',
+    field: (alias) => `${alias}: ${plan.field}`,
+    shape(raw) {
+      const shaped = shapeResult(request, raw);
+      if (!shaped.ok) return { ok: false, ...shaped.failure };
+      const subject = plan.subject ?? ownerOf(shaped.ownedBy, ctx.identity);
+      return {
+        ok: true,
+        data: shaped.data,
+        ...(subject ? { subject } : {}),
+        ...(plan.first !== undefined ? { first: plan.first } : {}),
+      };
+    },
+  };
+}
+
+const COINS =
+  'Bank coins are `{ denom, amountBaseUnits }` in base units (uixo ÷ 1,000,000 = IXO).';
+const STATUSES =
+  'Evaluation status is pending, approved, rejected, disputed, invalidated or flagged.';
+
+const claimsKind = defineKind({
+  name: 'claims',
+  summary:
+    'Claims an agent submitted (default: the user), newest first, with evaluation and payment status.',
+  explain: [
+    'Each claim: claimId, collectionId, agent, submissionDate, `evaluation` (status, date) and `paymentsStatus` per payment leg (e.g. `approval: PAID`).',
+    STATUSES,
+    COINS,
+    '`totalCount` counts every matching claim; when `hasNextPage`, pass `endCursor` as `after` for the next page.',
+  ].join(' '),
+  source: 'blocksync',
+  list: true,
+  args: CORE_ARGS.claims,
+  example: { collectionId: '8250', first: 5 },
+  plan: (args, ctx) => blocksyncPlan({ kind: 'claims', ...args }, ctx),
+});
+
+const COUNTED = ' { totalCount pageInfo { ';
+
+/**
+ * `claims` without its `totalCount`, which PostgreSQL computes by counting
+ * every matching claim: the page and `hasNextPage` only. What
+ * `get_account_overview` reads for its claims part. Not a `chain_lookup`
+ * kind.
+ */
+export const claimsPage: KindDef = {
+  ...claimsKind,
+  plan(rawArgs, ctx) {
+    const plan = claimsKind.plan(rawArgs, ctx);
+    if ('invalid' in plan || plan.source !== 'blocksync') return plan;
+    return {
+      ...plan,
+      field: (alias) => plan.field(alias).replace(COUNTED, ' { pageInfo { '),
+    };
+  },
+};
+
+/** The core kinds, in catalogue order. */
+export const CORE_KINDS: readonly KindDef[] = [
+  claimsKind,
+  defineKind({
+    name: 'claim',
+    summary:
+      'One claim by id, with its current evaluation (status, oracle, reason, amount paid).',
+    explain: [
+      '`not_found` when the index has no claim with that id.',
+      STATUSES,
+      COINS,
+      "`subject` is `user` when the claim's agent is the user's address.",
+    ].join(' '),
+    source: 'blocksync',
+    list: false,
+    args: CORE_ARGS.claim,
+    example: {
+      claimId: 'bafkreido4unh2l34n5zy5sy3nhyc3nhih65eysmal5dlq6j56m3eecntfm',
+    },
+    plan: (args, ctx) => blocksyncPlan({ kind: 'claim', ...args }, ctx),
+  }),
+  defineKind({
+    name: 'claim_collection',
+    summary: 'One claim collection: claim counts, state and payment terms.',
+    explain: [
+      '`state` is open, paused or closed; quota, count, evaluated, approved, rejected and disputed count claims.',
+      '`payments` per leg (submission, evaluation, approval, rejection): the paying `account`, bank coins, cw20 amounts (`amountBaseUnits`, base units), cw1155 amounts (whole units, with token ids) and `oraclePayment` when an oracle is paid.',
+      COINS,
+      "`subject` is `user` when the collection's admin is the user.",
+    ].join(' '),
+    source: 'blocksync',
+    list: false,
+    args: CORE_ARGS.claim_collection,
+    example: { id: '8250' },
+    plan: (args, ctx) =>
+      blocksyncPlan({ kind: 'claim_collection', ...args }, ctx),
+  }),
+  defineKind({
+    name: 'claim_collections',
+    summary:
+      'Claim collections by admin (default: the user) or by entity, newest start date first.',
+    explain: [
+      'Each: id, entity, admin, protocol, start/end date, claim counts and state (open, paused, closed).',
+      'A collection without a start date sorts first.',
+      'With only `entity`, every collection of that entity whatever its admin, and no `subject`.',
+    ].join(' '),
+    source: 'blocksync',
+    list: true,
+    args: CORE_ARGS.claim_collections,
+    example: { first: 5 },
+    plan: (args, ctx) =>
+      blocksyncPlan({ kind: 'claim_collections', ...args }, ctx),
+  }),
+  defineKind({
+    name: 'entities',
+    summary:
+      'Entities (DAOs, projects, protocols, assets…) an account owns (default: the user).',
+    explain: [
+      'Each: id (did:ixo:entity:…), type, status, owner, created.',
+      'Ordered by id as text: ids are hashes, so the order says nothing about age.',
+      "`status` is a number the entity's creator defines; the chain gives it no fixed meaning.",
+    ].join(' '),
+    source: 'blocksync',
+    list: true,
+    args: CORE_ARGS.entities,
+    example: { type: 'dao' },
+    plan: (args, ctx) => blocksyncPlan({ kind: 'entities', ...args }, ctx),
+  }),
+  defineKind({
+    name: 'entity',
+    summary:
+      'One entity by DID: type, owner, controllers, accounts, linked entities and resources, services, settings.',
+    explain: [
+      'Resources, services and settings show what and where (id, type, description, serviceEndpoint, mediaType), never their content.',
+      "`status` is a number the entity's creator defines.",
+      'Ask it beside `did_document` for "what is did:ixo:entity:…".',
+      "`subject` is `user` when the entity's owner is the user.",
+    ].join(' '),
+    source: 'blocksync',
+    list: false,
+    args: CORE_ARGS.entity,
+    example: { id: 'did:ixo:entity:0123456789abcdef0123456789abcdef' },
+    plan: (args, ctx) => blocksyncPlan({ kind: 'entity', ...args }, ctx),
+  }),
+  defineKind({
+    name: 'did_document',
+    summary:
+      "A DID document (default: the user's DID): controllers, verification methods, linked resources.",
+    explain: [
+      'Any did:ixo:… DID, an entity or an account.',
+      'Verification methods show id, type, controller and the public key or blockchain account they hold.',
+    ].join(' '),
+    source: 'blocksync',
+    list: false,
+    args: CORE_ARGS.did_document,
+    example: {},
+    plan: (args, ctx) => blocksyncPlan({ kind: 'did_document', ...args }, ctx),
+  }),
+  defineKind({
+    name: 'token_balances',
+    summary:
+      'IXO 1155 tokens (impact tokens, carbon credits…) an account holds (default: the user), largest first.',
+    explain: [
+      'Each: tokenId, name, class, collection, amount, retired, contractAddress.',
+      'IXO 1155 tokens have no decimals on chain: `amount` and `retired` are whole units.',
+    ].join(' '),
+    source: 'blocksync',
+    list: true,
+    args: CORE_ARGS.token_balances,
+    example: {},
+    plan: (args, ctx) =>
+      blocksyncPlan({ kind: 'token_balances', ...args }, ctx),
+  }),
+  defineKind({
+    name: 'transactions',
+    summary:
+      'Transactions an account signed (default) or received, newest first, with each message summarised.',
+    explain: [
+      'Each: hash, height, time, code, succeeded (code 0), memo and its first 5 messages (`messageCount` when there are more).',
+      'Messages: MsgSend `{ from, to, amount }`, MsgTransferToken `{ from, to, tokens }` (whole units), claim messages `{ claimId, collectionId, status }`, an authz MsgExec as its first 5 inner messages, anything else as a short excerpt.',
+      '`received` matches the recipient of a message (or of the first message inside a MsgExec); MsgMultiSend outputs are not seen.',
+      COINS,
+    ].join(' '),
+    source: 'blocksync',
+    list: true,
+    args: CORE_ARGS.transactions,
+    example: { direction: 'received', first: 5 },
+    plan: (args, ctx) => blocksyncPlan({ kind: 'transactions', ...args }, ctx),
+  }),
+  defineKind({
+    name: 'transaction',
+    summary:
+      'One transaction by hash, with up to 50 messages, its signers and fee.',
+    explain: [
+      'As a row of `transactions`, plus up to 10 `signers` and the `fee`.',
+      COINS,
+      '`subject` is `user` when the user signed it.',
+    ].join(' '),
+    source: 'blocksync',
+    list: false,
+    args: CORE_ARGS.transaction,
+    example: {
+      hash: '9C1D5E4A7B3F20864D2E6A1C8B5F3D7E0A4C6B2D8F1E3A5C7B9D0F2E4A6C8B1D',
+    },
+    plan: (args, ctx) => blocksyncPlan({ kind: 'transaction', ...args }, ctx),
+  }),
+];