@ixo/oracle-runtime-workers 0.29.1 → 0.30.0

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

@@ -0,0 +1,287 @@
+/**
+ * `claim_intents` and `collection_membership`: x/claims state the index
+ * does not answer, read from the chain.
+ */
+import { z } from 'zod';
+import { defineKind, type KindResult } from '../types';
+import { displayCoins } from '../coins';
+import { clip } from '../../summaries';
+import {
+  COLLECTION_ID,
+  accountFor,
+  addressArg,
+  coinsOr,
+  coinsSchema,
+  durationText,
+  failed,
+  firstArg,
+  isPast,
+} from './shared';
+
+const pagination = z.object({ next_key: z.string().nullish() }).nullish();
+const cw20Schema = z.object({ address: z.string(), amount: z.string() });
+
+/** cw20 amounts as shown: the token contract and its base units. */
+const cw20Of = (payments: z.infer<typeof cw20Schema>[]) =>
+  payments.slice(0, 5).map((payment) => ({
+    contract: clip(payment.address, 80),
+    amountBaseUnits: clip(payment.amount, 40),
+  }));
+
+/** A store key for `pagination.key`: its bytes base64, escaped for a query string. */
+const keyParam = (key: string) => encodeURIComponent(btoa(key));
+
+/** cw20 amounts as shown, or `empty`. */
+const cw20Or = <Empty extends string>(
+  payments: z.infer<typeof cw20Schema>[],
+  empty: Empty,
+) => (payments.length ? cw20Of(payments) : empty);
+
+const collectionIdArg = z
+  .string()
+  .describe('Claim collection id, e.g. "8250".');
+
+/* ── claim intents ────────────────────────────────────────────────────── */
+
+/**
+ * Intents read per request. x/claims keys an intent
+ * `<agentAddress>/<collectionId>/<intentId>` (`IntentKeyCreate`) and lists
+ * the whole store in key order, so a page that starts at the key
+ * `<agent>/` (or `<agent>/<collection>/`) holds that agent's intents
+ * first; the first intent of another agent (or collection) ends them.
+ */
+const INTENT_SCAN = 200;
+
+const intentsResponse = z.object({
+  intents: z.array(
+    z.object({
+      id: z.string(),
+      agent_address: z.string(),
+      collection_id: z.string(),
+      claim_id: z.string().optional(),
+      created_at: z.string().nullish(),
+      expire_at: z.string().nullish(),
+      status: z.string(),
+      amount: coinsSchema.default([]),
+      cw20_payment: z.array(cw20Schema).default([]),
+      cw1155_payment: z.array(z.unknown()).default([]),
+      member_address: z.string().optional(),
+    }),
+  ),
+  pagination,
+});
+
+export const claimIntentsKind = defineKind({
+  name: 'claim_intents',
+  summary:
+    "An agent's claim intents: payments reserved in escrow before a claim is submitted.",
+  explain: [
+    'A claim intent (x/claims) is an agent\'s declared plan to submit a claim in a collection: the payment it asks for (`coins`, bank coins or "none"; `cw20` tokens) is moved into the collection\'s escrow when the intent is created. `status`: active (waiting for the claim; `expiresAt` is the deadline), fulfilled (the claim was submitted, `claimId`; the escrow is paid out on approval or returned on rejection), expired (no claim in time; the escrow went back).',
+    '`pastExpiry: true` = still active on chain but past its deadline: the chain expires it on its next pass. `forMember` = the team member the intent is on behalf of.',
+    "The kind reads up to 200 intents starting at this account's (and collection's) first one; `matched` counts them, `complete: false` = there were more than 200, so the list may be missing some.",
+  ].join('\n'),
+  source: 'chain',
+  list: true,
+  args: z.strictObject({
+    address: addressArg,
+    collectionId: collectionIdArg.optional(),
+    first: firstArg,
+  }),
+  example: {},
+  plan(input, ctx) {
+    const account = accountFor(ctx, input.address);
+    if ('invalid' in account) return account;
+    const { collectionId } = input;
+    if (collectionId !== undefined && !COLLECTION_ID.test(collectionId))
+      return { invalid: 'collectionId must be a number such as "8250".' };
+    return {
+      source: 'chain',
+      async run(): Promise<KindResult> {
+        const start = `${account.address}/${collectionId === undefined ? '' : `${collectionId}/`}`;
+        const read = await ctx.rest(
+          `/ixo/claims/intents?pagination.key=${keyParam(start)}&pagination.limit=${INTENT_SCAN}`,
+          intentsResponse,
+          { label: 'claim intents' },
+        );
+        if (!read.ok) return failed(read.failure);
+        const { intents: page, pagination: paging } = read.value;
+        const theirs = (intent: (typeof page)[number]) =>
+          intent.agent_address === account.address &&
+          (collectionId === undefined || intent.collection_id === collectionId);
+        const end = page.findIndex((intent) => !theirs(intent));
+        const mine = end < 0 ? page : page.slice(0, end);
+        const intents = await Promise.all(
+          mine.slice(0, ctx.first).map(async (intent) => {
+            const status = intent.status.toLowerCase();
+            return {
+              id: clip(intent.id, 40),
+              collectionId: clip(intent.collection_id, 20),
+              status: clip(status, 20),
+              coins: await coinsOr(ctx, intent.amount, 'none'),
+              ...(intent.cw20_payment.length
+                ? { cw20: cw20Of(intent.cw20_payment) }
+                : {}),
+              ...(intent.cw1155_payment.length
+                ? { cw1155Payments: intent.cw1155_payment.length }
+                : {}),
+              createdAt: intent.created_at ?? null,
+              expiresAt: intent.expire_at ?? null,
+              ...(status === 'active' &&
+              intent.expire_at &&
+              isPast(intent.expire_at)
+                ? { pastExpiry: true }
+                : {}),
+              ...(intent.claim_id
+                ? { claimId: clip(intent.claim_id, 120) }
+                : {}),
+              ...(intent.member_address
+                ? { forMember: clip(intent.member_address, 80) }
+                : {}),
+            };
+          }),
+        );
+        return {
+          ok: true,
+          subject: account.subject,
+          first: ctx.first,
+          data: {
+            address: account.address,
+            ...(collectionId !== undefined ? { collectionId } : {}),
+            intents,
+            matched: mine.length,
+            // Another agent's intent ended the account's, or the store did.
+            complete: end >= 0 || !paging?.next_key,
+          },
+        };
+      },
+    };
+  },
+});
+
+/* ── collection membership ────────────────────────────────────────────── */
+
+const memberBudget = z.object({
+  member_address: z.string(),
+  period: z.string(),
+  period_spend_limit: coinsSchema.default([]),
+  period_spent: coinsSchema.default([]),
+  period_cw20_spend_limit: z.array(cw20Schema).default([]),
+  period_cw20_spent: z.array(cw20Schema).default([]),
+  period_reset_at: z.string().nullish(),
+});
+const depositBalance = z.object({
+  agent_address: z.string(),
+  amount: coinsSchema.default([]),
+  withdrawable_at: z.string().nullish(),
+});
+const membersResponse = z.object({
+  member_budgets: z.array(memberBudget),
+  pagination,
+});
+const depositsResponse = z.object({
+  balances: z.array(depositBalance),
+  pagination,
+});
+
+/**
+ * The list page that starts at `address`. x/claims keys member budgets
+ * and deposits by `<collection>/<address>` and lists one collection's
+ * under the `<collection>/` prefix, so a page keyed at the address holds
+ * that account's record first if it exists. The point routes answer HTTP
+ * 500 for an absent record, which `ctx.rest` cannot tell from a fault.
+ */
+const fromAddress = (address: string) =>
+  `pagination.key=${encodeURIComponent(btoa(address))}&pagination.limit=1`;
+
+export const collectionMembershipKind = defineKind({
+  name: 'collection_membership',
+  summary:
+    "An account's team-member budget and performance deposit in one claim collection.",
+  explain: [
+    '`member: true` = the account is a team member of the collection with a spending budget (x/claims member budget): it may reserve up to `budget.spendLimit` per `budget.period` for claim intents (`budget.spent` so far this period, "none" = nothing yet; reset at `budget.resetAt`; `resetDue` = that time has passed and the budget refills on the next use). "none allowed" = the budget allows no spending of that kind (bank coins, or cw20 tokens: `cw20SpendLimit`, `cw20Spent`). `member: false` = no member budget here (an agent may still submit claims through an authz grant: see `authz_grants`).',
+    "`deposit` = the agent's performance deposit held in the collection's escrow (null = none), as `coin` (or `coins` when it holds several denoms): it can be slashed when a dispute against the agent is lost. `lockEnded: true` = its lock (`withdrawableAt`, null = none) is over, so it can be withdrawn unless a dispute against the agent is still open.",
+    'Amounts are display units (`amount` + `symbol`) with `amountBaseUnits`; cw20 amounts are base units of the token contract.',
+  ].join('\n'),
+  source: 'chain',
+  list: false,
+  args: z.strictObject({ collectionId: collectionIdArg, address: addressArg }),
+  example: { collectionId: '8250' },
+  plan(input, ctx) {
+    const account = accountFor(ctx, input.address);
+    if ('invalid' in account) return account;
+    const { collectionId } = input;
+    if (!COLLECTION_ID.test(collectionId))
+      return { invalid: 'collectionId must be a number such as "8250".' };
+    const base = `/ixo/claims/collection/${collectionId}`;
+    return {
+      source: 'chain',
+      async run(): Promise<KindResult> {
+        const [members, deposits] = await Promise.all([
+          ctx.rest(
+            `${base}/members?${fromAddress(account.address)}`,
+            membersResponse,
+            { label: 'collection member budget' },
+          ),
+          ctx.rest(
+            `${base}/deposits?${fromAddress(account.address)}`,
+            depositsResponse,
+            { label: 'collection deposit' },
+          ),
+        ]);
+        if (!members.ok) return failed(members.failure);
+        if (!deposits.ok) return failed(deposits.failure);
+        const budget = members.value.member_budgets.find(
+          (entry) => entry.member_address === account.address,
+        );
+        const deposit = deposits.value.balances.find(
+          (entry) => entry.agent_address === account.address,
+        );
+        const withdrawableAt = deposit?.withdrawable_at ?? null;
+        // A drained deposit is removed from the store: an empty one is none.
+        const held = deposit ? await displayCoins(ctx, deposit.amount) : [];
+        return {
+          ok: true,
+          subject: account.subject,
+          data: {
+            address: account.address,
+            collectionId,
+            member: !!budget,
+            ...(budget
+              ? {
+                  budget: {
+                    period: durationText(budget.period),
+                    // The intent handler lets a member spend only what the
+                    // limit lists: an empty limit allows nothing.
+                    spendLimit: await coinsOr(
+                      ctx,
+                      budget.period_spend_limit,
+                      'none allowed',
+                    ),
+                    spent: await coinsOr(ctx, budget.period_spent, 'none'),
+                    cw20SpendLimit: cw20Or(
+                      budget.period_cw20_spend_limit,
+                      'none allowed',
+                    ),
+                    cw20Spent: cw20Or(budget.period_cw20_spent, 'none'),
+                    resetAt: budget.period_reset_at ?? null,
+                    ...(budget.period_reset_at && isPast(budget.period_reset_at)
+                      ? { resetDue: true }
+                      : {}),
+                  },
+                }
+              : {}),
+            deposit: held.length
+              ? {
+                  ...(held.length === 1 && held[0]
+                    ? { coin: held[0] }
+                    : { coins: held }),
+                  withdrawableAt,
+                  lockEnded: withdrawableAt === null || isPast(withdrawableAt),
+                }
+              : null,
+          },
+        };
+      },
+    };
+  },
+});

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

@@ -0,0 +1,237 @@
+/**
+ * `network_economics`: how new IXO is minted. The x/mint parameters, the
+ * provisions the chain mints this epoch and the epoch clock, each from a
+ * 10 min per-isolate cache.
+ */
+import { z } from 'zod';
+import { defineKind, type KindContext, type KindResult } from '../types';
+import { displayCoin } from '../coins';
+import { clip } from '../../summaries';
+import {
+  DEC_ONE,
+  ReadCache,
+  decMul,
+  decPercent,
+  durationText,
+  failed,
+  parseDec,
+  sharePercent,
+} from './shared';
+
+/** Mint parameters, provisions and epochs are reused for 10 min. */
+export const ECONOMICS_TTL_MS = 600_000;
+/** Reductions replayed at most when checking the schedule (one per period; mainnet has had one). */
+const MAX_REDUCTIONS = 1_000n;
+
+const paramsResponse = z.object({
+  params: z.object({
+    mint_denom: z.string(),
+    genesis_epoch_provisions: z.string(),
+    epoch_identifier: z.string(),
+    reduction_period_in_epochs: z.string(),
+    reduction_factor: z.string(),
+    distribution_proportions: z.object({
+      staking: z.string(),
+      impact_rewards: z.string(),
+      community_pool: z.string(),
+    }),
+    minting_rewards_distribution_start_epoch: z.string(),
+  }),
+});
+const provisionsResponse = z.object({ epoch_provisions: z.string() });
+const epochsResponse = z.object({
+  epochs: z.array(
+    z.object({
+      identifier: z.string(),
+      duration: z.string(),
+      current_epoch: z.string(),
+      current_epoch_start_time: z.string(),
+      epoch_counting_started: z.boolean(),
+    }),
+  ),
+});
+
+type Params = z.infer<typeof paramsResponse>['params'];
+type Epoch = z.infer<typeof epochsResponse>['epochs'][number];
+
+const params = new ReadCache<z.infer<typeof paramsResponse>>(
+  ECONOMICS_TTL_MS,
+  8,
+);
+const provisions = new ReadCache<z.infer<typeof provisionsResponse>>(
+  ECONOMICS_TTL_MS,
+  8,
+);
+const epochs = new ReadCache<z.infer<typeof epochsResponse>>(
+  ECONOMICS_TTL_MS,
+  8,
+);
+
+const cached = <S extends z.ZodType>(
+  cache: ReadCache<z.infer<S>>,
+  ctx: KindContext,
+  path: string,
+  schema: S,
+  label: string,
+) => cache.get(ctx, path, () => ctx.rest(path, schema, { label }));
+
+const COUNT = /^\d{1,12}$/;
+
+/**
+ * The next provisions reduction. x/mint cuts the provisions by
+ * `reduction_factor` at the end of the epoch `start + n × period`
+ * (`start` = the distribution start epoch); the chain does not expose
+ * the epoch of the last cut, so the schedule is replayed from the
+ * genesis provisions with the chain's own decimal rounding and used only
+ * when it reproduces exactly the provisions the chain reports now (a
+ * parameter changed by governance on the way would not). Null otherwise,
+ * or before minting started.
+ */
+function nextReduction(
+  values: Params,
+  current: bigint,
+  epoch: Epoch,
+): { epoch: string; around: string | null; provisionsAfter: bigint } | null {
+  const genesis = parseDec(values.genesis_epoch_provisions);
+  const factor = parseDec(values.reduction_factor);
+  const count = (value: string) => (COUNT.test(value) ? BigInt(value) : null);
+  const start = count(values.minting_rewards_distribution_start_epoch);
+  const period = count(values.reduction_period_in_epochs);
+  const now = count(epoch.current_epoch);
+  if (
+    genesis === null ||
+    factor === null ||
+    start === null ||
+    period === null ||
+    now === null
+  )
+    return null;
+  // The epoch in progress has not ended: the last one ended is now − 1.
+  const lastEnded = now - 1n;
+  if (period <= 0n || !epoch.epoch_counting_started || lastEnded < start)
+    return null;
+  const cuts = (lastEnded - start) / period;
+  if (cuts > MAX_REDUCTIONS) return null;
+  let expected = genesis;
+  for (let n = 0n; n < cuts; n += 1n) expected = decMul(expected, factor);
+  if (expected !== current) return null;
+  const target = start + (cuts + 1n) * period;
+  const seconds = /^(\d{1,12})s$/.exec(epoch.duration)?.[1];
+  const startedAt = Date.parse(epoch.current_epoch_start_time);
+  // The reduction runs when the target epoch ends.
+  const around =
+    seconds && Number.isFinite(startedAt)
+      ? new Date(
+          startedAt + Number((target - now + 1n) * BigInt(seconds)) * 1000,
+        ).toISOString()
+      : null;
+  return {
+    epoch: target.toString(),
+    around,
+    provisionsAfter: decMul(current, factor),
+  };
+}
+
+export const networkEconomicsKind = defineKind({
+  name: 'network_economics',
+  summary:
+    'How new IXO is minted: provisions per epoch, the next reduction, where it goes.',
+  explain: [
+    'IXO inflation (x/mint): at the end of every epoch (`epoch.identifier`, e.g. "day", each `epoch.length`) the chain mints `provisionsPerEpoch` new IXO and splits it by `distribution` (staking rewards to delegators, impact rewards, the community pool).',
+    'Every `reduction.everyEpochs` epochs the provisions are multiplied by `reduction.factor` (a cut of `reduction.cutPercent`). `reduction.next` gives the epoch of the next cut, roughly when (`around`, the end of that epoch) and the provisions after it; it is left out when the current parameters do not reproduce the provisions the chain reports (e.g. after a governance change), so it is never a guess.',
+    'Amounts are display units (`amount` + `symbol`) with `amountBaseUnits` (fractions of a base unit dropped).',
+  ].join('\n'),
+  source: 'chain',
+  list: false,
+  args: z.strictObject({}),
+  example: {},
+  plan(_input, ctx) {
+    return {
+      source: 'chain',
+      async run(): Promise<KindResult> {
+        const [paramsRead, provisionsRead, epochsRead] = await Promise.all([
+          cached(
+            params,
+            ctx,
+            '/ixo/mint/v1beta1/params',
+            paramsResponse,
+            'mint params',
+          ),
+          cached(
+            provisions,
+            ctx,
+            '/ixo/mint/v1beta1/epoch_provisions',
+            provisionsResponse,
+            'epoch provisions',
+          ),
+          cached(
+            epochs,
+            ctx,
+            '/ixo/epochs/v1beta1/epochs',
+            epochsResponse,
+            'epochs',
+          ),
+        ]);
+        if (!paramsRead.ok) return failed(paramsRead.failure);
+        if (!provisionsRead.ok) return failed(provisionsRead.failure);
+        if (!epochsRead.ok) return failed(epochsRead.failure);
+        const values = paramsRead.value.params;
+        const denom = values.mint_denom;
+        const current = parseDec(provisionsRead.value.epoch_provisions);
+        const epoch = epochsRead.value.epochs.find(
+          (entry) => entry.identifier === values.epoch_identifier,
+        );
+        const coin = (scaled: bigint) =>
+          displayCoin(ctx, { denom, amount: (scaled / DEC_ONE).toString() });
+        const next =
+          current !== null && epoch
+            ? nextReduction(values, current, epoch)
+            : null;
+        const factor = parseDec(values.reduction_factor);
+        const split = values.distribution_proportions;
+        return {
+          ok: true,
+          data: {
+            mintDenom: clip(denom, 60),
+            ...(epoch
+              ? {
+                  epoch: {
+                    identifier: clip(epoch.identifier, 40),
+                    length: durationText(epoch.duration),
+                    current: epoch.current_epoch,
+                    startedAt: epoch.current_epoch_start_time,
+                  },
+                }
+              : {}),
+            ...(current !== null
+              ? { provisionsPerEpoch: await coin(current) }
+              : {}),
+            reduction: {
+              factor: clip(values.reduction_factor, 30),
+              ...(factor !== null && factor <= DEC_ONE
+                ? { cutPercent: sharePercent(DEC_ONE - factor, DEC_ONE) }
+                : {}),
+              everyEpochs: values.reduction_period_in_epochs,
+              ...(next
+                ? {
+                    next: {
+                      epoch: next.epoch,
+                      around: next.around,
+                      provisionsAfter: await coin(next.provisionsAfter),
+                    },
+                  }
+                : {}),
+            },
+            distribution: {
+              staking: decPercent(split.staking),
+              impactRewards: decPercent(split.impact_rewards),
+              communityPool: decPercent(split.community_pool),
+            },
+            distributionStartEpoch:
+              values.minting_rewards_distribution_start_epoch,
+          },
+        };
+      },
+    };
+  },
+});