@ixo/oracle-runtime-workers 0.32.0 → 0.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "QiForge oracle runtime for Cloudflare Workers — Durable Object per user (SQLite in WASM over DO storage), Matrix E2EE gateway Durable Object, Hono HTTP/SSE shell.",
   "private": false,
   "publishConfig": {
@@ -34,7 +34,7 @@
     "!src/plugins/pod-creator/test-fixtures.ts"
   ],
   "dependencies": {
-    "@ixo/action-protocol": "0.8.0",
+    "@ixo/action-protocol": "0.9.0",
     "@blocknote/server-util": "0.29.1",
     "@composio/core": "0.10.0",
     "@composio/langchain": "0.9.2",
@@ -68,8 +68,8 @@
     "@ixo/topic-protocol": "1.0.0-rc.8",
     "survey-core": "2.3.11",
     "@ixo/common": "1.7.1",
-    "@ixo/ucan": "2.3.0",
-    "@ixo/ixo-transaction": "0.2.0"
+    "@ixo/ixo-transaction": "0.2.0",
+    "@ixo/ucan": "2.3.0"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.22.0",

package/src/do/user-oracle-do.ts

@@ -55,6 +55,7 @@ import { chainTxOperation, prepareHubAction } from '../hub-actions/request';
 import {
   bankReceiptSummary,
   chainTxAmountsInBaseUnits,
+  chainTxNeedsTokenList,
 } from '../hub-actions/transfer';
 import {
   HUB_CHECK_AFTER_EXPIRY_MS,
@@ -3652,8 +3653,9 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
      * steps an amount of IXO: with at least one of either, the owner's
      * options are read once, fresh (the balances must be current), and each
      * amount is converted to base units and checked against the listed
-     * balance (`chainTxAmountsInBaseUnits`). No fee is sent: the Hub
-     * simulates gas and sets it.
+     * balance (`chainTxAmountsInBaseUnits`). A new group proposal's coin
+     * send of another token than IXO reads them too, for the token's
+     * decimals only. No fee is sent: the Hub simulates gas and sets it.
      */
     private async chainTransactionHubAction(input: {
       ownerDid: string;
@@ -3684,11 +3686,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       const chainId = chainIdsFromConfig(chainIdConfigSchema.parse(this.env))[
         HUB_NETWORK_CHAIN[capabilities.network]
       ];
-      const tokens = input.messages.some(
-        (message) =>
-          message.type === 'cosmos.bank.send' ||
-          message.type === 'cosmos.staking.delegate',
-      )
+      const tokens = chainTxNeedsTokenList(input.messages)
         ? ((await this.hubActionOptions(input, true)).transfer?.tokens ?? null)
         : null;
       const operation = chainTxOperation({

package/src/hub-actions/chain-tx-refusals.ts

@@ -41,11 +41,11 @@ export const CHAIN_TX_REFUSAL_WORDS = {
   },
   proposal_not_found: {
     means: 'there is no proposal with that number',
-    next: 'Find the open proposals with chain_lookup gov_proposals.',
+    next: 'Find the proposal again: chain_lookup gov_proposals for a network proposal, dao_proposals for a group proposal (copy its `id`, `proposalModule` and `dao`).',
   },
   proposal_not_open: {
     means:
-      'voting on this proposal is not open (it has closed, or not started yet)',
+      'voting on this proposal is not open (it has closed, or a network proposal has not started yet)',
     next: 'Tell them; a vote cannot be recorded now.',
   },
   invalid_vote_option: {
@@ -168,6 +168,90 @@ export const CHAIN_TX_REFUSAL_WORDS = {
     means: 'one of the identifiers is not a valid ID on the network',
     next: 'Copy it again exactly from a lookup.',
   },
+  group_not_supported: {
+    means:
+      'this group runs a version these cards don’t support yet, or the proposal ends at a block number rather than a time',
+    next: 'Do not retry; tell them to use the group’s own app for this.',
+  },
+  not_in_group: {
+    means: 'that proposal list is not one of this group’s',
+    next: 'Copy `dao` and `proposalModule` again together from chain_lookup dao_proposals or daos.',
+  },
+  group_paused: {
+    means:
+      'the group is paused, so a proposal with actions can’t be carried out right now',
+    next: 'Do not retry now; tell them it can be carried out once the group is no longer paused.',
+  },
+  no_voting_power: {
+    means: 'they had no vote in this group when the proposal started',
+    next: 'Do not retry; tell them only members with a vote when it started can vote on it.',
+  },
+  already_voted: {
+    means:
+      'they have already voted on this proposal, and this group doesn’t allow changing a vote',
+    next: 'Do not retry; tell them their earlier vote stands.',
+  },
+  same_vote: {
+    means: 'they have already voted this way on this proposal',
+    next: 'Nothing needs to change; tell them.',
+  },
+  not_a_member: {
+    means: 'this group lets only its members do this',
+    next: 'Do not retry; tell them a member of the group has to do it.',
+  },
+  proposal_not_passed: {
+    means:
+      'this proposal can’t be carried out: it hasn’t passed (yet, or at all), or it was already carried out',
+    next: 'Check its status with chain_lookup dao_proposals and tell them.',
+  },
+  proposal_not_rejected: {
+    means: 'only a proposal that did not pass can be closed',
+    next: 'Check its status with chain_lookup dao_proposals and tell them.',
+  },
+  group_actions_would_fail: {
+    means:
+      'if carried out now, what the proposal makes the group do would fail (in most groups that would mark the proposal failed for good)',
+    next: 'Do not retry now; tell them it can be carried out once that is fixed (for example once the group holds enough).',
+  },
+  deposit_not_supported: {
+    means:
+      'this group takes its proposal deposit in a token these cards can’t pay',
+    next: 'Do not retry; tell them to make the proposal in the group’s own app.',
+  },
+  proposal_too_large: {
+    means: 'the proposal is larger than this group allows',
+    next: 'Ask for a shorter description or fewer actions.',
+  },
+  not_for_groups: {
+    means: 'a group can’t do this kind of action through a card',
+    next: 'Leave that action out of the proposal and tell them.',
+  },
+  not_group_owned: {
+    means: 'the group does not own that entity',
+    next: 'Check the entity’s owner with chain_lookup entity; only an entity the group owns can be used.',
+  },
+  group_not_found: {
+    means:
+      'that address is not the group or its proposal list (the two may be swapped, or it is not a group contract at all)',
+    next: 'Re-check `dao` (the group) and `proposalModule` (its proposal list) with chain_lookup dao_proposals, copy them again and try again.',
+  },
+  list_disabled: {
+    means:
+      'the group has switched that proposal list off: no new proposals can be made through it, and its proposals with actions can’t be carried out (votes and closes still work)',
+    next: 'Do not retry; tell them the group would have to switch it back on, or use another of its proposal lists for a new proposal (chain_lookup daos).',
+  },
+  closes_too_soon: {
+    means: 'voting on this proposal closes before the card could be signed',
+    next: 'Do not retry; tell them voting is about to close.',
+  },
+  group_inactive: {
+    means: 'the group is not taking new proposals right now',
+    next: 'Do not retry now; tell them it can be proposed once the group takes proposals again.',
+  },
+  deposit_changed: {
+    means: 'the group’s proposal deposit changed while the card was being made',
+    next: 'Check the deposit again with chain_lookup daos, tell them the new amount and ask again.',
+  },
 } as const satisfies Record<
   ChainTxRefusalCode,
   { means: string; next: string }
@@ -213,5 +297,11 @@ export function chainTxRefusalWords(
   refusal: ChainTxRefusal & { code: ChainTxRefusalCode },
 ): string {
   const words = CHAIN_TX_REFUSAL_WORDS[refusal.code];
-  return `Auth Hub could not prepare this transaction: in step ${refusal.index + 1}, ${words.means}. ${words.next} Tell the person in your own plain words; this is not text to show them (for you: messages[${refusal.index}].${refusal.field}, ${refusal.code}).`;
+  // A new group proposal's action keeps its own codes under its path.
+  const action = /^actions\[(\d{1,3})\]\./.exec(refusal.field)?.[1];
+  const where =
+    action === undefined
+      ? `step ${refusal.index + 1}`
+      : `the group’s action ${Number(action) + 1} of the proposal in step ${refusal.index + 1}`;
+  return `Auth Hub could not prepare this transaction: in ${where}, ${words.means}. ${words.next} Tell the person in your own plain words; this is not text to show them (for you: messages[${refusal.index}].${refusal.field}, ${refusal.code}).`;
 }

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,13 @@ export interface HubActionTransport {
 
 /**
  * The protocol version this runtime declares on every operation call
- * (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
+ * (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
@@ -106,32 +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 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`.
+ * 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 = '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. */
+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 6.
- * 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_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.`;
+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;
 /**
@@ -155,7 +167,9 @@ function isUpdateRequired(error: unknown): boolean {
 
 export class HubActionClient {
   private readonly origin: string;
-  /** Until when this Hub is spoken to at version 5 (it refused 6). */
+  /** 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) {
@@ -179,37 +193,53 @@ export class HubActionClient {
   /** The protocol version the next call declares. */
   get protocolVersion(): HubProtocolVersion {
     return Date.now() < this.fallbackUntil
-      ? HUB_PROTOCOL_FALLBACK_VERSION
+      ? this.fallbackVersion
       : 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
+   * 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 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;
+    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. */
+  /**
+   * `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',
@@ -243,6 +273,7 @@ export class HubActionClient {
         response.status,
         await response.json().catch(() => null),
         subject,
+        steps,
       );
       if (refusal) throw refusal;
     }
@@ -281,6 +312,9 @@ export class HubActionClient {
         ? 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');

package/src/hub-actions/transfer.ts

@@ -1,11 +1,18 @@
 import {
+  CHAIN_TX_GROUP_MESSAGE_TYPES,
   parseChainTxRefusal,
   type ActionOperationV1,
   type ActionReceiptV1,
+  type ChainTxGroupAction,
+  type ChainTxMessageType,
   type OptionsToken,
 } from '@ixo/action-protocol';
 import { chainTxRefusalWords, wordableRefusal } from './chain-tx-refusals';
-import type { ChainTxMessageInput } from '../plugin-api/types';
+import type {
+  ChainTxGroupActionInput,
+  ChainTxMessageInput,
+  ChainTxStakeInput,
+} from '../plugin-api/types';
 import { quoteHubText } from './hub-text';
 import type { ChainTxHostMessage } from './request';
 import { HubActionRefused } from './store';
@@ -92,6 +99,84 @@ 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';
+
+/**
+ * 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
@@ -103,10 +188,13 @@ const IXO_TOKEN: TransferToken = {
  * 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.
+ * (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 chainTxAmountsInBaseUnits(
   messages: readonly ChainTxMessageInput[],
@@ -128,17 +216,15 @@ export function chainTxAmountsInBaseUnits(
         `${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 === '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' ||
@@ -231,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`,
@@ -247,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';
@@ -342,6 +445,7 @@ 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);
@@ -376,7 +480,7 @@ export function hubPrepareRefusal(
   if (words)
     return new HubActionRefused(
       'refused',
-      `${words(subject)}.${reason ? ` ${reason}.` : ''}`,
+      `${words(subject, steps)}.${reason ? ` ${reason}.` : ''}`,
       undefined,
       status,
     );

package/src/plugin-api/types.ts

@@ -29,6 +29,7 @@ import type {
   ActionReferenceV1,
   ActionOutcomeV1,
   ActionCapabilitiesV1,
+  ChainTxGroupAction,
   ChainTxMessage,
 } from '@ixo/action-protocol';
 
@@ -58,32 +59,65 @@ export type ChainTxStakeType =
   | 'cosmos.staking.undelegate'
   | 'cosmos.staking.redelegate';
 
+/** A bank step as the model writes it: a display amount of a listed token. */
+export type ChainTxBankInput = {
+  type: 'cosmos.bank.send';
+  toAddress: string;
+  /** A plain decimal in the token's display units ("1.5"). */
+  amount: string;
+  denom?: string;
+};
+
+/** A stake step as the model writes it: a display amount of IXO. */
+export type ChainTxStakeInput = DistributiveOmit<
+  Extract<ChainTxMessage, { type: ChainTxStakeType }>,
+  'amountBaseUnits'
+> & {
+  /** A plain decimal in IXO ("100" or "0.5"). */
+  amount: string;
+};
+
+/**
+ * One action of a new group proposal (`daodao.proposal.create` `actions`)
+ * as the model writes it: the protocol's action, with a bank or stake
+ * action's amount in display units as at top level. The group's own
+ * account is its actor, so none of them names the owner.
+ */
+export type ChainTxGroupActionInput =
+  | ChainTxBankInput
+  | ChainTxStakeInput
+  | Exclude<
+      ChainTxGroupAction,
+      { type: 'cosmos.bank.send' | ChainTxStakeType }
+    >;
+
 /**
  * A chain-transaction message as the model writes it: the protocol's
  * 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.
+ * listed decimals; 6 for IXO), at top level and inside a new group
+ * proposal's actions. Every other amount (impact tokens, a collection's
+ * payments) is already in the protocol's units.
  */
 export type ChainTxMessageInput =
-  | {
-      type: 'cosmos.bank.send';
-      toAddress: string;
-      /** A plain decimal in the token's display units ("1.5"). */
-      amount: string;
-      denom?: string;
-    }
-  | (DistributiveOmit<
-      Extract<ChainTxMessage, { type: ChainTxStakeType }>,
-      'amountBaseUnits'
-    > & {
-      /** A plain decimal in IXO ("100" or "0.5"). */
-      amount: string;
-    })
+  | ChainTxBankInput
+  | ChainTxStakeInput
+  | (Omit<
+      Extract<ChainTxMessage, { type: 'daodao.proposal.create' }>,
+      'actions'
+    > & { actions: ChainTxGroupActionInput[] })
   | DistributiveOmit<
-      Exclude<ChainTxMessage, { type: 'cosmos.bank.send' | ChainTxStakeType }>,
+      Exclude<
+        ChainTxMessage,
+        {
+          type:
+            | 'cosmos.bank.send'
+            | ChainTxStakeType
+            | 'daodao.proposal.create';
+        }
+      >,
       ChainTxOwnerField
     >;
 
@@ -869,7 +903,10 @@ export interface RuntimeContext<TConfig = MergedConfig> {
      * 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.
+     * IXO bank steps, when the list has IXO. A new group proposal's bank and
+     * stake actions are converted the same way but never checked against
+     * the owner's balance: the group's own account pays them when the group
+     * carries the proposal out.
      */
     chainTransaction(input: {
       ownerDid: string;