@ixo/oracle-runtime-workers 0.29.0 → 0.30.0

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

@@ -0,0 +1,23 @@
+import type { KindDef } from '../types';
+import { accountKind, smartAccountKind, spendableKind } from './account';
+import { claimIntentsKind, collectionMembershipKind } from './claims';
+import { networkEconomicsKind } from './economics';
+import { govProposalsKind } from './governance';
+import { authzGrantsKind, feeGrantsKind } from './grants';
+import { liquidStakingKind } from './liquid-staking';
+import { stakingKind } from './staking';
+
+/** Kinds answered by chain REST reads, in catalogue order. */
+export const CHAIN_KINDS: readonly KindDef[] = [
+  feeGrantsKind,
+  authzGrantsKind,
+  smartAccountKind,
+  accountKind,
+  stakingKind,
+  spendableKind,
+  liquidStakingKind,
+  networkEconomicsKind,
+  govProposalsKind,
+  claimIntentsKind,
+  collectionMembershipKind,
+];

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

@@ -0,0 +1,279 @@
+/**
+ * `liquid_staking`: the x/liquidstake pools (each mints its own liquid
+ * staking token, e.g. PAY), what one token is worth in IXO, and what the
+ * account holds of each pool's token. Pools, pool states and the module's
+ * parameters come from a 60 s per-isolate cache; the account's balance of
+ * each token is read every time.
+ *
+ * The chain's own `unstake_rate` is `TruncateDec`'d to a whole number
+ * (x/liquidstake `GetNetAmountStateForPool`, `StkIXOToNativeToken(1, …)`),
+ * so it reads 1 while a PAY is worth more. The value here is the keeper's
+ * unstake arithmetic on the account's whole holding (`LiquidUnstake`
+ * before the fee): `held × net_amount ÷ stkixo_total_supply` in
+ * `LegacyDec`, truncated to a whole base unit.
+ */
+import { z } from 'zod';
+import { defineKind, type KindContext, type KindResult } from '../types';
+import { displayCoin, ixo, wholeUnits } from '../coins';
+import { clip } from '../../summaries';
+import {
+  DEC_ONE,
+  ReadCache,
+  accountFor,
+  addressArg,
+  coinSchema,
+  decPercent,
+  decQuo,
+  failed,
+  parseDec,
+} from './shared';
+
+/** Pools, their states and the module parameters are reused for 60 s. */
+export const LIQUIDSTAKE_TTL_MS = 60_000;
+/** Pools read (one page); governance creates them, mainnet has two. */
+const POOL_PAGE = 10;
+/** x/liquidstake pool ids: lower-case letters, digits and inner dashes. */
+const POOL_ID = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
+/** The Cosmos SDK bank denom pattern. */
+const DENOM = /^[a-zA-Z][a-zA-Z0-9/:._-]{2,127}$/;
+
+const poolsResponse = z.object({
+  pools: z.array(
+    z.object({
+      pool_id: z.string(),
+      liquid_bond_denom: z.string(),
+      paused: z.boolean().default(false),
+      unstake_fee_rate: z.string().optional(),
+    }),
+  ),
+  pagination: z.object({ next_key: z.string().nullish() }).nullish(),
+});
+const statesResponse = z.object({
+  net_amount_state: z.object({
+    stake_rate: z.string(),
+    unstake_rate: z.string(),
+    stkixo_total_supply: z.string(),
+    net_amount: z.string(),
+    total_liquid_tokens: z.string(),
+  }),
+});
+const paramsResponse = z.object({
+  module_params: z.object({
+    min_liquid_stake_amount: z.string(),
+    module_paused: z.boolean(),
+  }),
+});
+const balanceResponse = z.object({ balance: coinSchema.nullish() });
+
+const pools = new ReadCache<z.infer<typeof poolsResponse>>(
+  LIQUIDSTAKE_TTL_MS,
+  8,
+);
+const states = new ReadCache<z.infer<typeof statesResponse>>(
+  LIQUIDSTAKE_TTL_MS,
+  64,
+);
+const params = new ReadCache<z.infer<typeof paramsResponse>>(
+  LIQUIDSTAKE_TTL_MS,
+  8,
+);
+
+const readPools = (ctx: KindContext) =>
+  pools.get(ctx, 'pools', () =>
+    ctx.rest(
+      `/ixo/liquidstake/v1beta1/pools?pagination.limit=${POOL_PAGE}`,
+      poolsResponse,
+      { label: 'liquidstake pools' },
+    ),
+  );
+const readParams = (ctx: KindContext) =>
+  params.get(ctx, 'module_params', () =>
+    ctx.rest('/ixo/liquidstake/v1beta1/module_params', paramsResponse, {
+      label: 'liquidstake params',
+    }),
+  );
+const readState = (ctx: KindContext, poolId: string) =>
+  states.get(ctx, poolId, () =>
+    ctx.rest(
+      `/ixo/liquidstake/v1beta1/pools/${poolId}/states`,
+      statesResponse,
+      {
+        label: 'liquidstake pool state',
+      },
+    ),
+  );
+
+/** A LegacyDec without its trailing zeros: `"1.000000000000000000"` → `"1"`. */
+const rateText = (rate: string) =>
+  clip(rate.includes('.') ? rate.replace(/\.?0+$/, '') : rate, 30);
+
+/** Decimal places of `rate`. */
+const RATE_PLACES = 6;
+
+/**
+ * The IXO behind one token: `net ÷ supply` (net in 10⁻¹⁸ units) rounded
+ * down to {@link RATE_PLACES} places, e.g. `"1.031359"`.
+ */
+function rateOf(net: bigint, supply: bigint): string {
+  const scale = 10n ** BigInt(RATE_PLACES);
+  const scaled = (net * scale) / (supply * DEC_ONE);
+  return `${scaled / scale}.${(scaled % scale).toString().padStart(RATE_PLACES, '0')}`;
+}
+
+/**
+ * `StkIXOToNativeToken(held, supply, net)` as the keeper computes it:
+ * `held` as a decimal `MulTruncate` `net`, `Quo` `supply`, `TruncateDec`.
+ * Whole base units.
+ */
+function nativeOf(held: bigint, net: bigint, supply: bigint): string {
+  return (decQuo(held * net, supply * DEC_ONE) / DEC_ONE).toString();
+}
+
+/**
+ * `DeductFeeRate(native, feeRate)` as the keeper computes it on unstake:
+ * `native MulTruncate (1 − feeRate)`, `TruncateDec`, then `TruncateInt`.
+ * Whole base units; null when the rate is not a decimal in [0, 1].
+ */
+function afterUnstakeFee(native: string, feeRate: string): string | null {
+  const fee = parseDec(feeRate);
+  if (fee === null || fee > DEC_ONE) return null;
+  return ((BigInt(native) * (DEC_ONE - fee)) / DEC_ONE).toString();
+}
+
+/**
+ * The pool's state as shown: what a token is worth, and the account's
+ * holding in IXO before and after the pool's unstake fee.
+ */
+function stateView(
+  net: z.infer<typeof statesResponse>['net_amount_state'],
+  held: string,
+  feeRate: string | undefined,
+): Record<string, unknown> {
+  const amount = parseDec(net.net_amount);
+  const supply = wholeUnits(net.stkixo_total_supply);
+  const totalStaked = wholeUnits(net.total_liquid_tokens);
+  const backed = amount !== null && supply !== null && supply !== '0';
+  const native = backed ? nativeOf(BigInt(held), amount, BigInt(supply)) : null;
+  const received =
+    native !== null && feeRate !== undefined
+      ? afterUnstakeFee(native, feeRate)
+      : native;
+  return {
+    rate: backed ? rateOf(amount, BigInt(supply)) : null,
+    chainStakeRate: rateText(net.stake_rate),
+    chainUnstakeRate: rateText(net.unstake_rate),
+    ...(totalStaked ? { totalStaked: ixo(totalStaked) } : {}),
+    ...(native !== null ? { valueInIxo: ixo(native) } : {}),
+    ...(received !== null ? { unstakeReceivesIxo: ixo(received) } : {}),
+  };
+}
+
+/**
+ * One pool as shown, with the account's holding of its token; a pool
+ * whose state could not be read is shown with `stateUnavailable` (its
+ * rate, totals and value unknown). The account's balance failing fails
+ * the pool.
+ */
+async function poolView(
+  ctx: KindContext,
+  address: string,
+  pool: z.infer<typeof poolsResponse>['pools'][number],
+): Promise<KindResult> {
+  const denom = pool.liquid_bond_denom;
+  const [state, balance] = await Promise.all([
+    readState(ctx, pool.pool_id),
+    ctx.rest(
+      `/cosmos/bank/v1beta1/balances/${address}/by_denom?denom=${encodeURIComponent(denom)}`,
+      balanceResponse,
+      { label: 'liquid staking token balance' },
+    ),
+  ]);
+  if (!balance.ok) return failed(balance.failure);
+  const held = wholeUnits(balance.value.balance?.amount ?? '0') ?? '0';
+  const [yourBalance, lstSupply] = await Promise.all([
+    displayCoin(ctx, { denom, amount: held }),
+    state.ok
+      ? displayCoin(ctx, {
+          denom,
+          amount: state.value.net_amount_state.stkixo_total_supply,
+        })
+      : null,
+  ]);
+  const fee = pool.unstake_fee_rate ? decPercent(pool.unstake_fee_rate) : null;
+  return {
+    ok: true,
+    data: {
+      id: pool.pool_id,
+      lst: { symbol: yourBalance?.symbol ?? denom, denom },
+      paused: pool.paused,
+      ...(fee ? { unstakeFee: fee } : {}),
+      ...(state.ok
+        ? stateView(state.value.net_amount_state, held, pool.unstake_fee_rate)
+        : { stateUnavailable: true }),
+      ...(lstSupply ? { lstSupply } : {}),
+      yourBalance,
+    },
+  };
+}
+
+const args = z.strictObject({ address: addressArg });
+
+export const liquidStakingKind = defineKind({
+  name: 'liquid_staking',
+  summary:
+    'Liquid staking pools (e.g. PAY): rates, totals and how much of each token an account holds.',
+  explain: [
+    'Liquid staking (x/liquidstake) is staking too: IXO staked into a pool is delegated to its validators and earns rewards, and the pool mints its own liquid staking token (LST, e.g. PAY from the "pay" pool) one for one. The LST can be held or sent while the IXO stays staked; unstaking burns LST and returns its IXO, minus `unstakeFee`, after the unbonding period.',
+    "Per pool: `id`, `lst` (symbol and denom), `paused` (no staking or unstaking now), `rate` = IXO behind one LST now (pool IXO ÷ LST supply, 6 decimals; it grows as rewards accrue; null when the pool has no LST), `totalStaked` (IXO delegated by the pool), `lstSupply`, and for the account `yourBalance` (its LST) and `valueInIxo` (the IXO behind that LST now) and `unstakeReceivesIxo` (what unstaking it now would return after `unstakeFee`, as the chain computes it). `chainStakeRate` / `chainUnstakeRate` are the chain's own figures, truncated by the chain to whole numbers: use `rate`, never them, for what a token is worth. `stateUnavailable` = that pool's state could not be read (no rate or value).",
+    '`module.minStake` is the smallest stake accepted, `module.paused` pauses every pool. Amounts are display units with `amountBaseUnits`.',
+  ].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 [poolList, moduleParams] = await Promise.all([
+          readPools(ctx),
+          readParams(ctx),
+        ]);
+        if (!poolList.ok) return failed(poolList.failure);
+        if (!moduleParams.ok) return failed(moduleParams.failure);
+        const readable = poolList.value.pools.filter(
+          (pool) =>
+            POOL_ID.test(pool.pool_id) && DENOM.test(pool.liquid_bond_denom),
+        );
+        const answers = await Promise.all(
+          readable.map((pool) => poolView(ctx, account.address, pool)),
+        );
+        const views = [];
+        for (const answer of answers) {
+          if (!answer.ok) return answer;
+          views.push(answer.data);
+        }
+        const { min_liquid_stake_amount: min, module_paused: paused } =
+          moduleParams.value.module_params;
+        const minStake = wholeUnits(min);
+        const skipped = poolList.value.pools.length - readable.length;
+        return {
+          ok: true,
+          subject: account.subject,
+          data: {
+            address: account.address,
+            module: {
+              ...(minStake ? { minStake: ixo(minStake) } : {}),
+              paused,
+            },
+            pools: views,
+            ...(skipped ? { unreadablePools: skipped } : {}),
+            ...(poolList.value.pagination?.next_key ? { morePools: true } : {}),
+          },
+        };
+      },
+    };
+  },
+});

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

@@ -0,0 +1,286 @@
+/**
+ * What the chain REST kinds share: argument schemas, the account a request
+ * is about, the chain's coin JSON, exact decimal arithmetic on the chain's
+ * number strings, short labels, and a bounded per-isolate cache of
+ * slow-changing reads. Coins are shown through `../coins.ts`.
+ */
+import { z } from 'zod';
+import {
+  BUDGET_SPENT,
+  hasBudget,
+  throwIfAborted,
+  untilAborted,
+  type Failure,
+  type Outcome,
+} from '../../http';
+import { accountOf, type Subject } from '../../queries';
+import { clip } from '../../summaries';
+import { displayCoins, type DisplayCoin } from '../coins';
+import type { KindContext, KindInvalid, KindResult } from '../types';
+
+/* ── arguments ────────────────────────────────────────────────────────── */
+
+// Account arguments are bounded by `accountOf`'s patterns before any read.
+export const addressArg = z
+  .string()
+  .optional()
+  .describe("An ixo1… address or did:ixo:ixo1… DID; default: the user's.");
+
+export const firstArg = z
+  .number()
+  .int()
+  .min(1)
+  .max(20)
+  .optional()
+  .describe('Rows (1–20, default 10).');
+
+export const directionArg = z
+  .enum(['received', 'given'])
+  .optional()
+  .describe(
+    'received (default): granted to this account; given: granted by it.',
+  );
+
+/** A claim collection id as x/claims numbers them. */
+export const COLLECTION_ID = /^\d{1,12}$/;
+
+/** The account a request names (the user's by default), or why it is refused. */
+export function accountFor(
+  ctx: KindContext,
+  input: string | undefined,
+): { address: string; subject: Subject } | KindInvalid {
+  const account = accountOf(input, ctx.identity, 'address');
+  return account.ok
+    ? { address: account.address, subject: account.subject }
+    : { invalid: account.detail };
+}
+
+/* ── results ──────────────────────────────────────────────────────────── */
+
+export const failed = (failure: Failure): KindResult => ({
+  ok: false,
+  ...failure,
+});
+
+/** The last segment of a type URL: `/cosmos.bank.v1beta1.MsgSend` → `MsgSend`. */
+export function shortType(typeUrl: string): string {
+  return clip(typeUrl.slice(typeUrl.lastIndexOf('.') + 1) || typeUrl, 80);
+}
+
+/** Whether an RFC 3339 time is before now; false when it does not parse. */
+export function isPast(time: string): boolean {
+  const ms = Date.parse(time);
+  return Number.isFinite(ms) && ms < Date.now();
+}
+
+/** A grant's expiry: the time (null = never) and whether it has passed. */
+export function expiryOf(time: string | null | undefined): {
+  expiration: string | null;
+  expired: boolean;
+} {
+  return time
+    ? { expiration: time, expired: isPast(time) }
+    : { expiration: null, expired: false };
+}
+
+const UNITS = [
+  [86_400n, 'day'],
+  [3_600n, 'hour'],
+  [60n, 'minute'],
+] as const;
+
+/**
+ * A protobuf Duration as JSON gives it (`"2592000s"`, `"1.5s"`) in words:
+ * `30 days`, `1 hour`, `90 minutes`; the largest unit that divides it
+ * exactly. The input itself when it is not a duration.
+ */
+export function durationText(duration: string): string {
+  const match = /^(\d{1,15})(?:\.\d{1,9})?s$/.exec(duration);
+  if (!match?.[1]) return clip(duration, 40);
+  const seconds = BigInt(match[1]);
+  const unit = UNITS.find(([size]) => seconds >= size && seconds % size === 0n);
+  const [count, name] = unit
+    ? [seconds / unit[0], unit[1]]
+    : [seconds, 'second'];
+  return `${count} ${name}${count === 1n ? '' : 's'}`;
+}
+
+/** A duration in words, or null when it is absent or zero (no duration set). */
+export function setDuration(
+  duration: string | null | undefined,
+): string | null {
+  return !duration || /^0+(?:\.0+)?s$/.test(duration)
+    ? null
+    : durationText(duration);
+}
+
+/** The text of `items` with at most `max` named and the rest counted. */
+export function listText(items: readonly string[], max = 5): string {
+  const named = items.slice(0, max).join(', ');
+  return items.length > max ? `${named} and ${items.length - max} more` : named;
+}
+
+/* ── coins ────────────────────────────────────────────────────────────── */
+
+export const coinSchema = z.object({ denom: z.string(), amount: z.string() });
+export const coinsSchema = z.array(coinSchema);
+
+/**
+ * Bank coins as shown, or `empty` when there are none: the word for what
+ * that field's empty list means on chain ("none", "unlimited", "any",
+ * "none allowed"), never an empty list.
+ */
+export async function coinsOr<Empty extends string>(
+  ctx: Pick<KindContext, 'display'>,
+  coins: z.infer<typeof coinsSchema>,
+  empty: Empty,
+): Promise<DisplayCoin[] | Empty> {
+  const shown = await displayCoins(ctx, coins);
+  return shown.length ? shown : empty;
+}
+
+/* ── decimals ─────────────────────────────────────────────────────────── */
+
+/** The chain's `LegacyDec`: 18 decimal places. */
+const DEC_PLACES = 18;
+export const DEC_ONE = 10n ** BigInt(DEC_PLACES);
+const DECIMAL = /^(0|[1-9][0-9]{0,59})(?:\.([0-9]{1,18}))?$/;
+
+/** A non-negative decimal string as an integer of 10⁻¹⁸ units; null when it is not one. */
+export function parseDec(value: string): bigint | null {
+  const match = DECIMAL.exec(value);
+  if (!match?.[1]) return null;
+  return (
+    BigInt(match[1]) * DEC_ONE +
+    BigInt((match[2] ?? '').padEnd(DEC_PLACES, '0'))
+  );
+}
+
+/** 10⁻³⁶ units as 10⁻¹⁸ units, rounded half-to-even (`LegacyDec`'s `chopPrecisionAndRound`). */
+function chopHalfEven(value: bigint): bigint {
+  const quotient = value / DEC_ONE;
+  const remainder = value % DEC_ONE;
+  const half = DEC_ONE / 2n;
+  if (remainder < half) return quotient;
+  if (remainder > half) return quotient + 1n;
+  return quotient % 2n === 0n ? quotient : quotient + 1n;
+}
+
+/** `LegacyDec.Mul`: the product rounded half-to-even at 18 decimals. */
+export function decMul(a: bigint, b: bigint): bigint {
+  return chopHalfEven(a * b);
+}
+
+/**
+ * `LegacyDec.Quo` of two non-negative decimals (10⁻¹⁸ units, `b` > 0): the
+ * quotient truncated at 36 places, then rounded half-to-even at 18.
+ */
+export function decQuo(a: bigint, b: bigint): bigint {
+  return chopHalfEven((a * DEC_ONE * DEC_ONE) / b);
+}
+
+/** Hundredths of a percent as text: `3333n` → `33.33%`. */
+function hundredthsText(hundredths: bigint): string {
+  const whole = hundredths / 100n;
+  const fraction = (hundredths % 100n).toString().padStart(2, '0');
+  const trimmed = fraction.replace(/0+$/, '');
+  return trimmed ? `${whole}.${trimmed}%` : `${whole}%`;
+}
+
+/** A decimal fraction as a percentage rounded down to hundredths: `"0.05"` → `5%`; null when it does not parse. */
+export function decPercent(value: string): string | null {
+  const scaled = parseDec(value);
+  return scaled === null ? null : hundredthsText((scaled * 10_000n) / DEC_ONE);
+}
+
+/** `part / whole` as a percentage rounded down to hundredths; `0%` of nothing. */
+export function sharePercent(part: bigint, whole: bigint): string {
+  return hundredthsText(whole > 0n ? (part * 10_000n) / whole : 0n);
+}
+
+/* ── cache ────────────────────────────────────────────────────────────── */
+
+const caches = new Set<{ clear(): void }>();
+
+/** Tests only: forget every cached chain-kind read. */
+export function resetChainKindCaches(): void {
+  for (const cache of caches) cache.clear();
+}
+
+/**
+ * Successful reads kept per isolate for `ttlMs`, keyed by REST base and
+ * `key`, at most `limit` (the oldest written is dropped first). A failure
+ * is never kept. A read in flight is shared by every call that needs the
+ * same key. A call that joined a read which then timed out (the upstream,
+ * or the launching call's budget) or was aborted by its launching turn
+ * reads again itself while its own budget allows; it waits on its own
+ * turn's abort and throws only that, never another turn's.
+ */
+export class ReadCache<T> {
+  private readonly answers = new Map<string, { value: T; expiresAt: number }>();
+  private readonly inflight = new Map<string, Promise<Outcome<T>>>();
+
+  constructor(
+    private readonly ttlMs: number,
+    private readonly limit: number,
+  ) {
+    caches.add(this);
+  }
+
+  async get(
+    ctx: KindContext,
+    key: string,
+    read: () => Promise<Outcome<T>>,
+  ): Promise<Outcome<T>> {
+    const id = `${ctx.call.restUrl}|${key}`;
+    const hit = this.answers.get(id);
+    if (hit && hit.expiresAt > Date.now())
+      return { ok: true, value: hit.value };
+    if (hit) this.answers.delete(id);
+    const running = this.inflight.get(id);
+    if (running) {
+      const shared = await this.join(running, ctx);
+      if (shared && (shared.ok || shared.failure.reason !== 'timeout'))
+        return shared;
+      // The shared read timed out, or its launching turn was aborted.
+      if (hasBudget(ctx.call)) return this.get(ctx, key, read);
+      return shared ?? { ok: false, failure: BUDGET_SPENT };
+    }
+    const pending = read().finally(() => this.inflight.delete(id));
+    this.inflight.set(id, pending);
+    const outcome = await pending;
+    if (outcome.ok) this.remember(id, outcome.value);
+    return outcome;
+  }
+
+  /**
+   * A read another call started, as this call waits for it: its outcome,
+   * or null when it threw (its launching turn was aborted). This turn's
+   * own abort is thrown as soon as it happens.
+   */
+  private async join(
+    running: Promise<Outcome<T>>,
+    ctx: KindContext,
+  ): Promise<Outcome<T> | null> {
+    try {
+      return await untilAborted(running, ctx.call.signal);
+    } catch {
+      throwIfAborted(ctx.call.signal);
+      return null;
+    }
+  }
+
+  clear(): void {
+    this.answers.clear();
+    this.inflight.clear();
+  }
+
+  private remember(id: string, value: T): void {
+    this.answers.delete(id);
+    if (this.answers.size >= this.limit) {
+      const oldest = this.answers.keys().next();
+      if (!oldest.done) this.answers.delete(oldest.value);
+    }
+    this.answers.set(id, { value, expiresAt: Date.now() + this.ttlMs });
+  }
+}