@ixo/oracle-runtime-workers 0.31.0 → 0.32.0

package/src/hub-actions/client.ts

@@ -86,8 +86,13 @@ export interface HubActionTransport {
 
 /**
  * The protocol version this runtime declares on every operation call
- * (capabilities, POST operations, GET status, options). Version 5 is the
- * 0.7.0 contract: version 4 plus the application card (`ixo.bid.submit.v1`)
+ * (capabilities, POST operations, GET status, options). Version 6 is the
+ * 0.8.0 contract: version 5 plus 29 more `ixo.chain.tx.v1` message types
+ * (staking, voting, retiring impact tokens, claim collections, entities and
+ * identity-record links), which a 0.7.0 parser cannot read in capabilities,
+ * review steps or receipts, so the Hub lists and accepts them only at level
+ * 6 (`chainTxMessageTypesForLevel`); options answer as at version 3.
+ * Version 5 is the 0.7.0 contract: version 4 plus the application card (`ixo.bid.submit.v1`)
  * and the claim card (`ixo.claim.submit.v1`) with their receipts
  * (`ixo.bid.submission.v1`, `ixo.claim.submission.v1`,
  * `ixo.submission.failed.v1`), which a 0.6.0 parser cannot read, so the Hub
@@ -101,22 +106,32 @@ export interface HubActionTransport {
  * the 0.4.1 shapes. The envelopes stay tagged `ixo.auth-outcome/2` and
  * `ixo.auth-capabilities/2`, which `@ixo/action-protocol` parses.
  *
- * An Auth Hub older than version 5 checks `?version=` against its closed
- * list (1 to 4) and answers every call that declares 5 with 400
- * `invalid_request`, before anything else: see `HUB_UPDATE_REQUIRED`.
+ * An Auth Hub older than version 6 checks `?version=` against its closed
+ * list (1 to 5) and answers every call that declares 6 with 400
+ * `invalid_request`, before anything else. This runtime then speaks
+ * version 5 to it (every Hub action but the level-6 chain types keeps
+ * working while Auth Hub is rolled out) and asks for 6 again after
+ * `HUB_PROTOCOL_RECHECK_MS`; a Hub that refuses 5 too is told apart with
+ * `HUB_UPDATE_REQUIRED`.
  */
-const HUB_PROTOCOL_VERSION = '5';
-const HUB_PROTOCOL_QUERY = `version=${HUB_PROTOCOL_VERSION}`;
+const HUB_PROTOCOL_VERSION = '6';
+/** The lowest version this runtime works at: 6 without the level-6 chain types. */
+const HUB_PROTOCOL_FALLBACK_VERSION = '5';
+type HubProtocolVersion =
+  | typeof HUB_PROTOCOL_VERSION
+  | typeof HUB_PROTOCOL_FALLBACK_VERSION;
+/** How long a Hub that refused version 6 is spoken to at version 5 before 6 is tried again. */
+export const HUB_PROTOCOL_RECHECK_MS = 10 * 60_000;
 
 /**
  * What the model is told when Auth Hub refuses a read (capabilities,
  * options, status) with 400 `invalid_request`. A read carries nothing but
  * the protocol version (and, for options, the binding the runtime itself
- * checked), so that answer comes from a Hub that does not know version 5.
+ * checked), so that answer comes from a Hub that does not know version 6.
  * The owner object keeps every action it holds: polls and callbacks pick
  * the outcomes up once the Hub is updated.
  */
-export const HUB_UPDATE_REQUIRED = `Auth Hub must be updated before this oracle can use Hub actions: it does not accept protocol version ${HUB_PROTOCOL_VERSION}, which this runtime needs (invalid_request). Tell the person this is not available right now; retrying or changing the fields will not help.`;
+export const HUB_UPDATE_REQUIRED = `Auth Hub must be updated before this oracle can use Hub actions: it does not accept protocol version ${HUB_PROTOCOL_FALLBACK_VERSION}, the lowest this runtime works with (invalid_request). Tell the person this is not available right now; retrying or changing the fields will not help.`;
 /** Every Hub call but a chain-transaction prepare. */
 const HUB_TIMEOUT_MS = 10_000;
 /**
@@ -131,8 +146,17 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
+/** A read Auth Hub refused because it does not know the declared version. */
+function isUpdateRequired(error: unknown): boolean {
+  return (
+    error instanceof HubActionRefused && error.message === HUB_UPDATE_REQUIRED
+  );
+}
+
 export class HubActionClient {
   private readonly origin: string;
+  /** Until when this Hub is spoken to at version 5 (it refused 6). */
+  private fallbackUntil = 0;
 
   constructor(private readonly transport: HubActionTransport) {
     const url = new URL(transport.origin);
@@ -152,6 +176,34 @@ export class HubActionClient {
     this.origin = url.origin;
   }
 
+  /** The protocol version the next call declares. */
+  get protocolVersion(): HubProtocolVersion {
+    return Date.now() < this.fallbackUntil
+      ? HUB_PROTOCOL_FALLBACK_VERSION
+      : HUB_PROTOCOL_VERSION;
+  }
+
+  /**
+   * A read at the current version; when Auth Hub refuses version 6 as
+   * unknown, the same read at version 5, remembered for
+   * `HUB_PROTOCOL_RECHECK_MS`. Only reads do this: a refused read changed
+   * nothing, while a prepare's 400 can be a real refusal of its operation.
+   */
+  private async negotiated<T>(
+    read: (version: HubProtocolVersion) => Promise<T>,
+  ): Promise<T> {
+    const version = this.protocolVersion;
+    try {
+      return await read(version);
+    } catch (error) {
+      if (version !== HUB_PROTOCOL_VERSION || !isUpdateRequired(error))
+        throw error;
+      const answer = await read(HUB_PROTOCOL_FALLBACK_VERSION);
+      this.fallbackUntil = Date.now() + HUB_PROTOCOL_RECHECK_MS;
+      return answer;
+    }
+  }
+
   /** `subject`: what a refused prepare is called in the model's words. */
   private async send(
     path: string,
@@ -221,8 +273,9 @@ export class HubActionClient {
     // amounts) without it, and stores the version per action for the
     // outcomes it pushes.
     const operation = parseOperation(input.operation);
+    // The version the capabilities read before every prepare settled on.
     const response = await this.send(
-      `/api/internal/actions/operations?${HUB_PROTOCOL_QUERY}`,
+      `/api/internal/actions/operations?version=${this.protocolVersion}`,
       { ...input, operation },
       operation.kind === 'ixo.chain.tx.v1'
         ? HUB_CHAIN_TX_PREPARE_TIMEOUT_MS
@@ -234,10 +287,17 @@ export class HubActionClient {
     return assertHubReferenceUrl(response.reference, this.origin);
   }
 
-  async capabilities(): Promise<ActionCapabilitiesV1> {
-    return parseCapabilities(
-      await this.send(
-        `/api/internal/actions/operations/capabilities?${HUB_PROTOCOL_QUERY}`,
+  /** `timeoutMs`: a turn's tool list passes a short one (a slow Hub must not hold a turn). */
+  async capabilities(
+    timeoutMs = HUB_TIMEOUT_MS,
+  ): Promise<ActionCapabilitiesV1> {
+    return this.negotiated(async (version) =>
+      parseCapabilities(
+        await this.send(
+          `/api/internal/actions/operations/capabilities?version=${version}`,
+          undefined,
+          timeoutMs,
+        ),
       ),
     );
   }
@@ -249,16 +309,18 @@ export class HubActionClient {
     // Options version 3 (asked at the protocol version; version 4 answers
     // the same): version 2 plus the owner's bank tokens
     // (`transfer.tokens`), which any-token transfers are chosen from.
-    const query = new URLSearchParams({
-      bindingId: input.bindingId,
-      bindingRevision: String(input.bindingRevision),
-      version: HUB_PROTOCOL_VERSION,
+    const options = await this.negotiated(async (version) => {
+      const query = new URLSearchParams({
+        bindingId: input.bindingId,
+        bindingRevision: String(input.bindingRevision),
+        version,
+      });
+      return parseActionOptions(
+        await this.send(
+          `/api/internal/actions/operations/options?${query.toString()}`,
+        ),
+      );
     });
-    const options = parseActionOptions(
-      await this.send(
-        `/api/internal/actions/operations/options?${query.toString()}`,
-      ),
-    );
     if (options.version !== 'ixo.auth-options/3')
       throw new Error('Hub action options require version 3');
     return options;
@@ -295,10 +357,12 @@ export class HubActionClient {
   ): Promise<HubActionStatus> {
     if (!/^[A-Za-z0-9_-]{32}$/.test(id))
       throw new Error('Invalid Hub action id');
-    const raw = await this.send(
-      `/api/internal/actions/operations/${id}?${HUB_PROTOCOL_QUERY}`,
-      undefined,
-      timeoutMs,
+    const raw = await this.negotiated((version) =>
+      this.send(
+        `/api/internal/actions/operations/${id}?version=${version}`,
+        undefined,
+        timeoutMs,
+      ),
     );
     if (!isRecord(raw)) throw new Error('Invalid Hub action status');
     const value = raw;

package/src/hub-actions/request.ts

@@ -7,32 +7,28 @@ import {
   type ChainTxMessage,
   type ChainTxOperation,
 } from '@ixo/action-protocol';
+import type { ChainTxOwnerField, DistributiveOmit } from '../plugin-api/types';
 import type { HubActionClient } from './client';
 import { HubActionRefused, type HubActionOrigin } from './store';
 
 /**
- * A chain-transaction message as the owner object completes it: bank
- * amounts already in base units (`bankStepsInBaseUnits`), the owner's
- * identity in claims messages still to add (`chainTxOperation`).
+ * A chain-transaction message as the owner object completes it: bank and
+ * stake amounts already in base units (`chainTxAmountsInBaseUnits`), the
+ * owner's identity (`ChainTxOwnerField`) still to add (`chainTxOperation`).
  */
-export type ChainTxHostMessage =
-  | Extract<
-      ChainTxMessage,
-      { type: 'cosmos.bank.send' } | { type: 'ixo.token.transfer' }
-    >
-  | Omit<Extract<ChainTxMessage, { type: 'ixo.claims.submit' }>, 'agentDid'>
-  | Omit<
-      Extract<ChainTxMessage, { type: 'ixo.claims.evaluate' }>,
-      'agentDid' | 'agentAddress'
-    >;
+export type ChainTxHostMessage = DistributiveOmit<
+  ChainTxMessage,
+  ChainTxOwnerField
+>;
 
 /**
  * The chain transaction (`ixo.chain.tx.v1`) of the model's messages: the
  * signer is the owner's account (their DID is `did:ixo:<address>`), and
- * the owner's identity in claims messages is the signer's: `agentDid` is
- * `did:ixo:<signer>` (the DID the runtime authenticates to the Hub as) and
- * an evaluation's `agentAddress` is the signer (the chain records the
- * evaluator, and pays it, by that address; Auth Hub requires both). The
+ * the owner's identity in the messages is the signer's: `agentDid`,
+ * `creatorDid`, `controllerDid` and `ownerDid` are `did:ixo:<signer>` (the
+ * DID the runtime authenticates to the Hub as) and an evaluation's
+ * `agentAddress` is the signer (the chain records the evaluator, and pays
+ * it, by that address; Auth Hub requires each to be the owner's). The
  * protocol parses the result; a field the runtime sets (signer, network,
  * chain id) is refused in fixed words, a field from the model's messages
  * in the protocol's (`Invalid messages[0].tokens[0].id`).
@@ -49,15 +45,26 @@ export function chainTxOperation(input: {
   const signer = input.ownerDid.startsWith('did:ixo:')
     ? input.ownerDid.slice('did:ixo:'.length)
     : '';
-  const agentDid = `did:ixo:${signer}`;
+  const ownDid = `did:ixo:${signer}`;
   // Identity last: a stray identity field cannot survive.
-  const messages: ChainTxMessage[] = input.messages.map((message) =>
-    message.type === 'ixo.claims.submit'
-      ? { ...message, agentDid }
-      : message.type === 'ixo.claims.evaluate'
-        ? { ...message, agentDid, agentAddress: signer }
-        : message,
-  );
+  const messages = input.messages.map((message): ChainTxMessage => {
+    switch (message.type) {
+      case 'ixo.claims.submit':
+      case 'ixo.claims.claim-intent':
+      case 'ixo.claims.dispute':
+        return { ...message, agentDid: ownDid };
+      case 'ixo.claims.evaluate':
+        return { ...message, agentDid: ownDid, agentAddress: signer };
+      case 'ixo.claims.create-claim-authorization':
+        return { ...message, creatorDid: ownDid };
+      case 'ixo.entity.update':
+        return { ...message, controllerDid: ownDid };
+      case 'ixo.entity.create':
+        return { ...message, ownerDid: ownDid };
+      default:
+        return message;
+    }
+  });
   try {
     return parseOperation({
       kind: 'ixo.chain.tx.v1',

package/src/hub-actions/transfer.ts

@@ -1,8 +1,10 @@
-import type {
-  ActionOperationV1,
-  ActionReceiptV1,
-  OptionsToken,
+import {
+  parseChainTxRefusal,
+  type ActionOperationV1,
+  type ActionReceiptV1,
+  type OptionsToken,
 } from '@ixo/action-protocol';
+import { chainTxRefusalWords, wordableRefusal } from './chain-tx-refusals';
 import type { ChainTxMessageInput } from '../plugin-api/types';
 import { quoteHubText } from './hub-text';
 import type { ChainTxHostMessage } from './request';
@@ -91,24 +93,67 @@ const IXO_TOKEN: TransferToken = {
 };
 
 /**
- * A chain transaction's bank steps in base units; the other messages pass
+ * A chain transaction's amounts in base units; messages without one pass
  * unchanged. Each bank step names a display `amount` of a token from the
  * owner's list (`denom`, absent = uixo): the token must be listed, the
  * amount converts with its listed decimals (`toBaseUnits`: a plain decimal,
  * no more digits after the point than the decimals, above zero; an
  * unverified token lists 0: base units), and the bank steps of one token
- * together stay within its listed balance. `tokens` is the owner's list
- * (hub_action_options `transfer.tokens`), null when the Hub listed none;
- * the caller reads it only when there is a bank step.
+ * together stay within its listed balance. Each stake step (stake, unstake,
+ * move stake) names a display `amount` of IXO, converted with IXO's 6
+ * decimals; what a stake takes from the wallet counts against the listed
+ * IXO balance together with the IXO bank steps, when the list has IXO
+ * (Auth Hub checks every balance again before the card is made). `tokens`
+ * is the owner's list (hub_action_options `transfer.tokens`), null when the
+ * Hub listed none; the caller reads it only when there is a bank or stake
+ * step.
  */
-export function bankStepsInBaseUnits(
+export function chainTxAmountsInBaseUnits(
   messages: readonly ChainTxMessageInput[],
   tokens: readonly OptionsToken[] | null,
 ): ChainTxHostMessage[] {
   const spent = new Map<string, bigint>();
-  return messages.map((message, index) => {
-    if (message.type !== 'cosmos.bank.send') return message;
+  /** The bank and stake steps of one listed token together, within its listed balance. */
+  const spend = (
+    at: string,
+    token: OptionsToken,
+    amount: bigint,
+    what: string,
+  ) => {
+    const total = (spent.get(token.denom) ?? 0n) + amount;
+    spent.set(token.denom, total);
+    if (total > BigInt(token.balanceBaseUnits))
+      throw new HubActionRefused(
+        'refused',
+        `${at}.amount: the owner holds ${describeAmount(token.balanceBaseUnits, token)}, less than ${total === amount ? what : 'what the steps of this transaction take of it together'}.`,
+      );
+  };
+  const converted = (at: string, amount: string, decimals: number) => {
+    try {
+      return toBaseUnits(amount, decimals);
+    } catch (error) {
+      if (error instanceof HubActionRefused)
+        throw new HubActionRefused('refused', `${at}.amount: ${error.message}`);
+      throw error;
+    }
+  };
+  return messages.map((message, index): ChainTxHostMessage => {
     const at = `messages[${index}]`;
+    if (
+      message.type === 'cosmos.staking.delegate' ||
+      message.type === 'cosmos.staking.undelegate' ||
+      message.type === 'cosmos.staking.redelegate'
+    ) {
+      const { amount: display, ...rest } = message;
+      const amount = converted(at, display, IXO_TOKEN.decimals);
+      // Only a stake takes IXO from the wallet: unstaking and moving stake
+      // work on what is already staked.
+      const ixo = tokens?.find((item) => item.denom === IXO_TOKEN.denom);
+      if (message.type === 'cosmos.staking.delegate' && ixo)
+        spend(at, ixo, amount, 'this stake');
+      return { ...rest, amountBaseUnits: amount.toString() };
+    }
+    if (message.type !== 'cosmos.bank.send') return message;
     if (!tokens?.length)
       throw new HubActionRefused(
         'refused',
@@ -124,21 +169,8 @@ export function bankStepsInBaseUnits(
           .slice(0, 10)
           .join(', ')}).`,
       );
-    let amount: bigint;
-    try {
-      amount = toBaseUnits(message.amount, token.decimals);
-    } catch (error) {
-      if (error instanceof HubActionRefused)
-        throw new HubActionRefused('refused', `${at}.amount: ${error.message}`);
-      throw error;
-    }
-    const total = (spent.get(token.denom) ?? 0n) + amount;
-    spent.set(token.denom, total);
-    if (total > BigInt(token.balanceBaseUnits))
-      throw new HubActionRefused(
-        'refused',
-        `${at}.amount: the owner holds ${describeAmount(token.balanceBaseUnits, token)}, less than ${total === amount ? 'this send' : 'the bank steps of this token in this transaction'}.`,
-      );
+    const amount = converted(at, message.amount, token.decimals);
+    spend(at, token, amount, 'this send');
     return {
       type: 'cosmos.bank.send',
       toAddress: message.toAddress,
@@ -316,6 +348,24 @@ export function hubPrepareRefusal(
   if (unfixable)
     return new HubActionRefused('refused', unfixable, undefined, status);
   if (!parsed) return null;
+  // A chain transaction Auth Hub would not make from what it read on chain,
+  // or whose simulation named one message: a fixed code, in the runtime's
+  // own words (the reason text is not passed on). Without a code, the
+  // reason is passed on quoted, as below.
+  const coded =
+    status === 400 &&
+    subject === 'transaction' &&
+    (parsed.error === 'operation_not_registered' ||
+      parsed.error === 'simulation_failed')
+      ? wordableRefusal(parseChainTxRefusal(parsed.reason))
+      : null;
+  if (coded)
+    return new HubActionRefused(
+      'refused',
+      chainTxRefusalWords(coded),
+      undefined,
+      status,
+    );
   const reason = parsed.reason
     ? quoteHubText('reason', parsed.reason, HUB_REASON_MAX)
     : '';

package/src/plugin-api/types.ts

@@ -32,13 +32,40 @@ import type {
   ChainTxMessage,
 } from '@ixo/action-protocol';
 
+/** `Omit` applied to each member of a union (plain `Omit` merges them). */
+export type DistributiveOmit<T, K extends PropertyKey> = T extends unknown
+  ? Omit<T, K>
+  : never;
+
+/**
+ * The owner's own identity in chain-transaction messages, which the host
+ * fills and the model never names: the filer's or disputer's `agentDid`
+ * (claims, reservations, disputes), an evaluation's `agentDid` and
+ * `agentAddress`, a claim permission's `creatorDid`, an entity update's
+ * `controllerDid` and a new entity's `ownerDid`: always `did:ixo:<signer>`,
+ * or the signer for an address.
+ */
+export type ChainTxOwnerField =
+  | 'agentDid'
+  | 'agentAddress'
+  | 'creatorDid'
+  | 'controllerDid'
+  | 'ownerDid';
+
+/** The stake steps: their amount is IXO, written in display units. */
+export type ChainTxStakeType =
+  | 'cosmos.staking.delegate'
+  | 'cosmos.staking.undelegate'
+  | 'cosmos.staking.redelegate';
+
 /**
  * A chain-transaction message as the model writes it: the protocol's
- * message without the owner's identity, which the host fills (a claim's
- * `agentDid`, an evaluation's `agentDid` and `agentAddress`: the signer's).
- * A bank step names a display `amount` of a token from the owner's list
- * (`denom`, absent = uixo); the host converts it to the protocol's
- * `amountBaseUnits` from the listed decimals.
+ * message without the owner's identity (`ChainTxOwnerField`), which the
+ * host fills. A bank step names a display `amount` of a token from the
+ * owner's list (`denom`, absent = uixo); a stake step a display `amount` of
+ * IXO. The host converts both to the protocol's `amountBaseUnits` (the
+ * listed decimals; 6 for IXO). Every other amount (impact tokens, a
+ * collection's payments) is already in the protocol's units.
  */
 export type ChainTxMessageInput =
   | {
@@ -48,11 +75,16 @@ export type ChainTxMessageInput =
       amount: string;
       denom?: string;
     }
-  | Extract<ChainTxMessage, { type: 'ixo.token.transfer' }>
-  | Omit<Extract<ChainTxMessage, { type: 'ixo.claims.submit' }>, 'agentDid'>
-  | Omit<
-      Extract<ChainTxMessage, { type: 'ixo.claims.evaluate' }>,
-      'agentDid' | 'agentAddress'
+  | (DistributiveOmit<
+      Extract<ChainTxMessage, { type: ChainTxStakeType }>,
+      'amountBaseUnits'
+    > & {
+      /** A plain decimal in IXO ("100" or "0.5"). */
+      amount: string;
+    })
+  | DistributiveOmit<
+      Exclude<ChainTxMessage, { type: 'cosmos.bank.send' | ChainTxStakeType }>,
+      ChainTxOwnerField
     >;
 
 /**
@@ -812,7 +844,13 @@ export interface RuntimeContext<TConfig = MergedConfig> {
 
   /** Host-owned action coordinator. It accepts only runtime-derived channel context. */
   hubActions?: {
-    capabilities(): Promise<ActionCapabilitiesV1>;
+    /**
+     * The Hub's capabilities for this oracle account (cached 60 s).
+     * `turn`: a read on a turn's critical path (a tool list): a short
+     * timeout, no new read within 30 s of a failed one, and the last
+     * capabilities read while reads fail.
+     */
+    capabilities(opts?: { turn?: boolean }): Promise<ActionCapabilitiesV1>;
     options(input: {
       ownerDid: string;
       provider: string;
@@ -822,13 +860,16 @@ export interface RuntimeContext<TConfig = MergedConfig> {
     /**
      * One chain transaction (`ixo.chain.tx.v1`) of 1–8 messages: the host
      * adds the chain id and network (the account's), the signer (the
-     * owner's address) and the owner's identity in claims messages
-     * (`agentDid` = `did:ixo:<signer>`, an evaluation's `agentAddress` = the
-     * signer) and prepares it like any operation (no fee: the Hub simulates
-     * gas and sets it). A bank step's display `amount` is converted to base
-     * units from the owner's token list (one options read per call, only
-     * when there is a bank step), refused for a token not listed, more
-     * digits than its decimals, zero or more than the listed balance.
+     * owner's address) and the owner's identity (`ChainTxOwnerField`:
+     * `did:ixo:<signer>`, an evaluation's `agentAddress` = the signer) and
+     * prepares it like any operation (no fee: the Hub simulates gas and
+     * sets it). A bank step's display `amount` is converted to base units
+     * from the owner's token list (one options read per call, only when
+     * there is a bank or stake step), refused for a token not listed, more
+     * digits than its decimals, zero or more than the listed balance. A
+     * stake step's IXO `amount` is converted with 6 decimals; what a stake
+     * takes from the wallet counts against the listed IXO balance with the
+     * IXO bank steps, when the list has IXO.
      */
     chainTransaction(input: {
       ownerDid: string;