@ixo/oracle-runtime-workers 0.31.0 → 0.33.0

package/src/hub-actions/client.ts

@@ -9,6 +9,7 @@ import {
   type ActionOutcomeV1,
   type ActionReferenceV1,
   type ActionReviewView,
+  type ChainTxMessageType,
   type HubActionOptionsV2,
   type HubActionOptionsV3,
 } from '@ixo/action-protocol';
@@ -86,8 +87,18 @@ 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 7 is the
+ * 0.9.0 contract: version 6 plus the four group steps on `ixo.chain.tx.v1`
+ * (a vote on a group proposal, carrying out a passed one, closing a failed
+ * one, a new proposal), which a 0.8.0 parser cannot read in capabilities,
+ * review steps or receipts, so the Hub lists and accepts them only at
+ * level 7; options answer as at version 3. 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 +112,38 @@ 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 this runtime's version checks `?version=` against
+ * its closed list (1 to 6 on 0.8.0, 1 to 5 on 0.7.0) and answers every call
+ * that declares a version it does not know with 400 `invalid_request`,
+ * before anything else. This runtime then steps down
+ * (`HUB_PROTOCOL_VERSIONS`: 7, then 6, then 5) to the highest version that
+ * Hub answers (every Hub action the lower level has keeps working while
+ * Auth Hub is rolled out: the group steps at 6, the level-6 chain types too
+ * at 5) and asks for 7 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 = '7';
+/** The lowest version this runtime works at: 7 without the group steps and the level-6 chain types. */
+const HUB_PROTOCOL_LOWEST_VERSION = '5';
+/** Every version this runtime speaks, highest first. */
+const HUB_PROTOCOL_VERSIONS = [
+  HUB_PROTOCOL_VERSION,
+  '6',
+  HUB_PROTOCOL_LOWEST_VERSION,
+] as const;
+type HubProtocolVersion = (typeof HUB_PROTOCOL_VERSIONS)[number];
+/** How long a Hub that refused a version is spoken to at a lower one before the highest 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.
- * The owner object keeps every action it holds: polls and callbacks pick
- * the outcomes up once the Hub is updated.
+ * checked), so that answer comes from a Hub that does not know the version
+ * declared. 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_LOWEST_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 +158,19 @@ 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;
+  /** The lower version this Hub answered after refusing a higher one. */
+  private fallbackVersion: HubProtocolVersion = HUB_PROTOCOL_VERSION;
+  /** Until when this Hub is spoken to at `fallbackVersion`. */
+  private fallbackUntil = 0;
 
   constructor(private readonly transport: HubActionTransport) {
     const url = new URL(transport.origin);
@@ -152,12 +190,56 @@ export class HubActionClient {
     this.origin = url.origin;
   }
 
-  /** `subject`: what a refused prepare is called in the model's words. */
+  /** The protocol version the next call declares. */
+  get protocolVersion(): HubProtocolVersion {
+    return Date.now() < this.fallbackUntil
+      ? this.fallbackVersion
+      : HUB_PROTOCOL_VERSION;
+  }
+
+  /**
+   * A read at the current version; when Auth Hub refuses it as unknown,
+   * the same read at each lower version in turn (`HUB_PROTOCOL_VERSIONS`),
+   * and the version it answered is 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.
+   * A Hub that refuses the lowest version too answers `HUB_UPDATE_REQUIRED`.
+   */
+  private async negotiated<T>(
+    read: (version: HubProtocolVersion) => Promise<T>,
+  ): Promise<T> {
+    const current = this.protocolVersion;
+    const versions = HUB_PROTOCOL_VERSIONS.slice(
+      HUB_PROTOCOL_VERSIONS.indexOf(current),
+    );
+    for (const [step, version] of versions.entries()) {
+      try {
+        const answer = await read(version);
+        if (step > 0) {
+          this.fallbackVersion = version;
+          this.fallbackUntil = Date.now() + HUB_PROTOCOL_RECHECK_MS;
+        }
+        return answer;
+      } catch (error) {
+        if (step === versions.length - 1 || !isUpdateRequired(error))
+          throw error;
+      }
+    }
+    // Unreachable: the loop returns or throws at its last version.
+    throw new Error('No Hub protocol version to read at');
+  }
+
+  /**
+   * `subject`: what a refused prepare is called in the model's words;
+   * `steps`: a chain transaction's message types, for the words of a refusal
+   * that depends on them.
+   */
   private async send(
     path: string,
     body?: unknown,
     timeoutMs = HUB_TIMEOUT_MS,
     subject?: HubPrepareSubject,
+    steps?: readonly ChainTxMessageType[],
   ): Promise<unknown> {
     const request = new Request(new URL(path, this.origin), {
       method: body === undefined ? 'GET' : 'POST',
@@ -191,6 +273,7 @@ export class HubActionClient {
         response.status,
         await response.json().catch(() => null),
         subject,
+        steps,
       );
       if (refusal) throw refusal;
     }
@@ -221,23 +304,34 @@ 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
         : HUB_TIMEOUT_MS,
       prepareSubjectOf(operation.kind),
+      operation.kind === 'ixo.chain.tx.v1'
+        ? operation.messages.map((message) => message.type)
+        : [],
     );
     if (!response || typeof response !== 'object' || !('reference' in response))
       throw new Error('Hub action response has no reference');
     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 +343,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 +391,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,9 +1,18 @@
-import type {
-  ActionOperationV1,
-  ActionReceiptV1,
-  OptionsToken,
+import {
+  CHAIN_TX_GROUP_MESSAGE_TYPES,
+  parseChainTxRefusal,
+  type ActionOperationV1,
+  type ActionReceiptV1,
+  type ChainTxGroupAction,
+  type ChainTxMessageType,
+  type OptionsToken,
 } from '@ixo/action-protocol';
-import type { ChainTxMessageInput } from '../plugin-api/types';
+import { chainTxRefusalWords, wordableRefusal } from './chain-tx-refusals';
+import type {
+  ChainTxGroupActionInput,
+  ChainTxMessageInput,
+  ChainTxStakeInput,
+} from '../plugin-api/types';
 import { quoteHubText } from './hub-text';
 import type { ChainTxHostMessage } from './request';
 import { HubActionRefused } from './store';
@@ -90,25 +99,147 @@ const IXO_TOKEN: TransferToken = {
   verified: true,
 };
 
+/** `toBaseUnits`, its refusal naming the message's amount (`messages[0].amount`). */
+function converted(at: string, amount: string, decimals: number): bigint {
+  try {
+    return toBaseUnits(amount, decimals);
+  } catch (error) {
+    if (error instanceof HubActionRefused)
+      throw new HubActionRefused('refused', `${at}.amount: ${error.message}`);
+    throw error;
+  }
+}
+
+const isStakeInput = (
+  message: ChainTxMessageInput | ChainTxGroupActionInput,
+): message is ChainTxStakeInput =>
+  message.type === 'cosmos.staking.delegate' ||
+  message.type === 'cosmos.staking.undelegate' ||
+  message.type === 'cosmos.staking.redelegate';
+
 /**
- * A chain transaction's bank steps in base units; the other messages pass
+ * Whether converting `messages` needs the owner's token list: a bank or
+ * stake step (its amount and the owner's balance), or a new group
+ * proposal's coin send of another token than IXO (its decimals).
+ */
+export function chainTxNeedsTokenList(
+  messages: readonly ChainTxMessageInput[],
+): boolean {
+  return messages.some(
+    (message) =>
+      message.type === 'cosmos.bank.send' ||
+      message.type === 'cosmos.staking.delegate' ||
+      (message.type === 'daodao.proposal.create' &&
+        message.actions.some(
+          (action) =>
+            action.type === 'cosmos.bank.send' &&
+            (action.denom ?? IXO_TOKEN.denom) !== IXO_TOKEN.denom,
+        )),
+  );
+}
+
+/**
+ * One action of a new group proposal with its amount in base units: a
+ * stake's IXO with 6 decimals, a coin send's with the decimals of its token
+ * (IXO without a list; another token from the owner's list, which is the
+ * only place the runtime learns a token's decimals). No balance is
+ * checked: the group's own account pays when it carries the proposal out,
+ * and the network checks it then.
+ */
+function groupActionInBaseUnits(
+  action: ChainTxGroupActionInput,
+  at: string,
+  tokens: readonly OptionsToken[] | null,
+): ChainTxGroupAction {
+  if (isStakeInput(action)) {
+    const { amount, ...rest } = action;
+    return {
+      ...rest,
+      amountBaseUnits: converted(at, amount, IXO_TOKEN.decimals).toString(),
+    };
+  }
+  if (action.type !== 'cosmos.bank.send') return action;
+  const denom = action.denom ?? IXO_TOKEN.denom;
+  const token =
+    denom === IXO_TOKEN.denom
+      ? IXO_TOKEN
+      : tokens?.find((item) => item.denom === denom);
+  if (!token)
+    throw new HubActionRefused(
+      'refused',
+      `${at}.denom: ${denom} is not in the owner's token list, so its decimals are unknown here; a group proposal can send IXO, or a token exactly as hub_action_options lists it.`,
+    );
+  return {
+    type: 'cosmos.bank.send',
+    toAddress: action.toAddress,
+    amountBaseUnits: converted(at, action.amount, token.decimals).toString(),
+    denom: token.denom,
+  };
+}
+
+/**
+ * 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). A new
+ * group proposal's bank and stake actions convert the same way
+ * (`groupActionInBaseUnits`) and are never checked against the owner's
+ * balance: the group's own account pays them when the group carries the
+ * proposal out. `tokens` is the owner's list (hub_action_options
+ * `transfer.tokens`), null when the Hub listed none; the caller reads it
+ * only when `chainTxNeedsTokenList`.
  */
-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'}.`,
+      );
+  };
+  return messages.map((message, index): ChainTxHostMessage => {
     const at = `messages[${index}]`;
+    if (message.type === 'daodao.proposal.create')
+      return {
+        ...message,
+        actions: message.actions.map((action, j) =>
+          groupActionInBaseUnits(action, `${at}.actions[${j}]`, tokens),
+        ),
+      };
+    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 +255,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,
@@ -199,10 +317,26 @@ export function prepareSubjectOf(
       : 'operation';
 }
 
+/**
+ * Why the chain's authorization check refused a chain transaction, by its
+ * steps: a group step (the group may let only members carry proposals out
+ * or propose), a claim step (the collection admin's authorization), or
+ * neither.
+ */
+function notAuthorizedWhy(steps: readonly ChainTxMessageType[]): string {
+  if (steps.some((type) => GROUP_STEP_TYPES.includes(type)))
+    return ' (for a group step, the group may let only its members do this)';
+  if (steps.some((type) => type.startsWith('ixo.claims.')))
+    return ' (for claims, the collection admin has not granted the authorization)';
+  return '';
+}
+const GROUP_STEP_TYPES: readonly ChainTxMessageType[] =
+  CHAIN_TX_GROUP_MESSAGE_TYPES;
+
 /** What the model is told when Auth Hub refuses a prepare (400). */
 const HUB_PREPARE_REFUSALS: Record<
   string,
-  (subject: HubPrepareSubject) => string
+  (subject: HubPrepareSubject, steps: readonly ChainTxMessageType[]) => string
 > = {
   simulation_failed: (subject) =>
     `Auth Hub simulated this ${subject} and it would fail on chain`,
@@ -215,10 +349,11 @@ const HUB_PREPARE_REFUSALS: Record<
   // it or tell the owner what was wrong.
   operation_not_registered: (subject) =>
     `Auth Hub did not accept this ${subject} as written`,
-  // The chain's authorization module refused the simulation: for claims,
-  // the collection admin has not authorized this account.
-  not_authorized: (subject) =>
-    `The account is not authorized on chain for this ${subject} (for claims, the collection admin has not granted the authorization)`,
+  // The chain's authorization check refused the simulation: for claims,
+  // the collection admin has not authorized this account; for a group step,
+  // the group lets only its members do it.
+  not_authorized: (subject, steps) =>
+    `The account is not authorized on chain for this ${subject}${notAuthorizedWhy(steps)}`,
 };
 /** Appended to every refusal no retry or change of arguments can lift. */
 const NOT_FIXABLE = 'retrying or changing the fields will not help';
@@ -310,12 +445,31 @@ export function hubPrepareRefusal(
   status: number,
   body: unknown,
   subject: HubPrepareSubject = 'transfer',
+  steps: readonly ChainTxMessageType[] = [],
 ): HubActionRefused | null {
   const parsed = hubErrorBody(body);
   const unfixable = unfixableRefusal(status, parsed, subject);
   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)
     : '';
@@ -326,7 +480,7 @@ export function hubPrepareRefusal(
   if (words)
     return new HubActionRefused(
       'refused',
-      `${words(subject)}.${reason ? ` ${reason}.` : ''}`,
+      `${words(subject, steps)}.${reason ? ` ${reason}.` : ''}`,
       undefined,
       status,
     );