@ixo/oracle-runtime-workers 0.32.0 → 0.33.1

package/src/plugins/hub-actions/hub-actions.plugin.ts

@@ -1,4 +1,5 @@
 import {
+  CHAIN_TX_GROUP_MESSAGE_TYPES,
   CHAIN_TX_MAX_MESSAGES,
   CHAIN_TX_MESSAGE_TYPES,
   operationJsonSchema,
@@ -30,6 +31,8 @@ import { toolNotRunMessage } from '../../core/tool-not-run';
 import {
   CHAIN_TX_CATALOG,
   CHAIN_TX_GENERAL_RULES,
+  GROUP_ACTION_SCHEMA,
+  GROUP_ACTION_TYPES,
   chainTxMessageInput,
   hasUnsafeText,
 } from './chain-tx-catalog';
@@ -100,22 +103,38 @@ const memoSchema = z
 /**
  * A catalogue field reduced to its basic type: no descriptions, patterns or
  * limits (those stay in describe_chain_messages and the handler's check).
+ * A union of message types (a new group proposal's `actions`) is given as
+ * `typeUnion` gives the messages themselves: fields only for the types in
+ * `described`.
  */
-export function fieldsOnly(schema: z.core.$ZodType): z.ZodType {
+export function fieldsOnly(
+  schema: z.core.$ZodType,
+  described?: ReadonlySet<string>,
+): z.ZodType {
   if (schema instanceof z.ZodObject)
     return z.strictObject(
       Object.fromEntries(
         Object.entries(schema.shape).map(([key, field]) => [
           key,
-          fieldsOnly(field),
+          fieldsOnly(field, described),
         ]),
       ),
     );
   if (schema instanceof z.ZodOptional)
-    return fieldsOnly(schema.unwrap()).optional();
+    return fieldsOnly(schema.unwrap(), described).optional();
   if (schema instanceof z.ZodNullable)
-    return fieldsOnly(schema.unwrap()).nullable();
-  if (schema instanceof z.ZodArray) return z.array(fieldsOnly(schema.element));
+    return fieldsOnly(schema.unwrap(), described).nullable();
+  if (schema instanceof z.ZodArray)
+    return z.array(fieldsOnly(schema.element, described));
+  if (schema instanceof z.ZodDiscriminatedUnion)
+    return typeUnion(
+      schema.options.map((option) => {
+        if (!(option instanceof z.ZodObject))
+          throw new Error('A message union holds a non-object branch');
+        return [messageTypeOf(option), option] as const;
+      }),
+      described,
+    );
   if (schema instanceof z.ZodString) return z.string();
   if (schema instanceof z.ZodNumber) return z.number();
   if (schema instanceof z.ZodBoolean) return z.boolean();
@@ -125,42 +144,51 @@ export function fieldsOnly(schema: z.core.$ZodType): z.ZodType {
   );
 }
 
+/** The `type` a catalogue message schema is for (its `type` literal). */
+function messageTypeOf(schema: z.ZodObject): string {
+  const type = schema.shape.type;
+  const [value] = type instanceof z.ZodLiteral ? [...type.values] : [];
+  if (typeof value !== 'string')
+    throw new Error('A catalogue message schema has no `type` literal');
+  return value;
+}
+
 /**
  * One message type as the model is given it: its field names and basic
  * types, so a provider that holds a tool call to its schema sends every
  * field. Loose, so a field the type does not have reaches the handler,
  * which names it.
  */
-function messageFieldsOnly(schema: z.ZodObject) {
+function messageFieldsOnly(
+  schema: z.ZodObject,
+  described?: ReadonlySet<string>,
+) {
   return z.looseObject(
     Object.fromEntries(
       Object.entries(schema.shape).map(([key, field]) => [
         key,
-        fieldsOnly(field),
+        fieldsOnly(field, described),
       ]),
     ),
   );
 }
 
 /**
- * The schema the model is given: per type its fields (messageFieldsOnly)
- * when the type was described in this session (`described`; absent: every
- * type), and one open branch naming every other type (`type` one of them,
- * any other field allowed). A type the model has not read about costs its
- * name only; the request handler refuses it until it is described, and
- * the next model call is given its fields (`chainTxFieldsMiddleware`).
- * Each message is checked by the handler against its full catalogue
- * schema.
+ * Messages as the model is given them: per type its fields
+ * (messageFieldsOnly) when the type was described in this session
+ * (`described`; absent: every type), and one open branch naming every
+ * other type (`type` one of them, any other field allowed). A union inside
+ * a message (a new group proposal's `actions`) takes `nested` instead.
  */
-export function chainTransactionSchemaFor(
-  catalog: Readonly<Record<string, { schema: z.ZodObject }>>,
+function typeUnion(
+  schemas: readonly (readonly [string, z.ZodObject])[],
   described?: ReadonlySet<string>,
+  nested: ReadonlySet<string> | undefined = described,
 ) {
-  const entries = Object.entries(catalog);
-  const withFields = entries
+  const withFields = schemas
     .filter(([type]) => !described || described.has(type))
-    .map(([, entry]) => messageFieldsOnly(entry.schema));
-  const [firstUnread, ...unread] = entries
+    .map(([, schema]) => messageFieldsOnly(schema, nested));
+  const [firstUnread, ...unread] = schemas
     .filter(([type]) => described && !described.has(type))
     .map(([type]) => type);
   const branches =
@@ -172,9 +200,36 @@ export function chainTransactionSchemaFor(
         ];
   const [first, ...rest] = branches;
   if (!first) throw new Error('The chain transaction catalogue is empty');
+  return z.discriminatedUnion('type', [first, ...rest]);
+}
+
+/**
+ * The schema the model is given: the messages as `typeUnion` gives them,
+ * a new group proposal's actions the same way. A type the model has not
+ * read about costs its name only; the request handler refuses it until it
+ * is described, and the next model call is given its fields
+ * (`chainTxFieldsMiddleware`). Without a session store (`described`
+ * absent) every message type carries its fields, but a new proposal's
+ * actions are named only: the 14 action types' fields would repeat their
+ * top-level branches (26 228 characters instead of 20 950); the
+ * handler names any field it misses. Each message is checked by the
+ * handler against its full catalogue schema.
+ */
+export function chainTransactionSchemaFor(
+  catalog: Readonly<Record<string, { schema: z.ZodObject }>>,
+  described?: ReadonlySet<string>,
+) {
   return z.strictObject({
     messages: z
-      .array(z.discriminatedUnion('type', [first, ...rest]))
+      .array(
+        typeUnion(
+          Object.entries(catalog).map(
+            ([type, entry]) => [type, entry.schema] as const,
+          ),
+          described,
+          described ?? new Set<string>(),
+        ),
+      )
       .min(1)
       .max(CHAIN_TX_MAX_MESSAGES),
     memo: memoSchema,
@@ -649,7 +704,10 @@ async function requestChainTransaction(
     const unread = [
       ...new Set(
         parsed.data.messages
-          .map(chainTxTypeOf)
+          .flatMap((message) => [
+            chainTxTypeOf(message),
+            ...groupActionTypesOf(message),
+          ])
           .filter(
             (type): type is ChainTxMessageType =>
               type !== null && !described.includes(type),
@@ -719,6 +777,19 @@ function strictChainTxMessages(
 ): { messages: ChainTxMessageInput[] } | { issues: string[] } {
   const checked: ChainTxMessageInput[] = [];
   const issues: string[] = [];
+  // A group step is a chain of reads in Auth Hub and names a new
+  // proposal's number on its receipt: it goes alone on its card (the
+  // protocol refuses `messages` otherwise).
+  if (
+    messages.length > 1 &&
+    messages.some((message) => {
+      const type = chainTxTypeOf(message);
+      return type !== null && GROUP_STEP_TYPES.includes(type);
+    })
+  )
+    issues.push(
+      'messages: a group step (a group vote, carrying out or closing a group proposal, a new group proposal) goes alone on its card; prepare the other messages on another card',
+    );
   messages.forEach((message, index) => {
     const type = chainTxTypeOf(message);
     if (!type) {
@@ -739,6 +810,31 @@ function chainTxTypeOf(message: unknown): ChainTxMessageType | null {
   return CHAIN_TX_MESSAGE_TYPES.find((known) => known === type) ?? null;
 }
 
+const GROUP_STEP_TYPES: readonly ChainTxMessageType[] =
+  CHAIN_TX_GROUP_MESSAGE_TYPES;
+
+/**
+ * The action types a new group proposal holds (each a type a group may
+ * do): their rules are read like a top-level message's before the card.
+ * Anything else is left to the message's own check.
+ */
+function groupActionTypesOf(message: unknown): ChainTxMessageType[] {
+  if (
+    chainTxTypeOf(message) !== 'daodao.proposal.create' ||
+    typeof message !== 'object' ||
+    message === null ||
+    !('actions' in message) ||
+    !Array.isArray(message.actions)
+  )
+    return [];
+  return message.actions
+    .map(chainTxTypeOf)
+    .filter(
+      (type): type is ChainTxMessageType =>
+        type !== null && GROUP_ACTION_TYPES.some((allowed) => allowed === type),
+    );
+}
+
 function chainTxShapeRefusal(
   issues: readonly string[],
 ): HubActionRequestResult {
@@ -784,10 +880,11 @@ function issuesOf(
 
 /**
  * The catalogue types this account may use: the Hub capabilities'
- * `chainTx.messageTypes`. None when chain transactions cannot be used
+ * `chainTx.messageTypes`, which follow the protocol level the Hub speaks
+ * with this runtime (level 5: the four 0.6.0 types; 6: 33; 7: all 37, the
+ * four group steps included). None when chain transactions cannot be used
  * here: not a channel turn, Hub actions off, chain transactions off for the
- * account, a Hub at protocol level 5 (the 0.6.0 types only, as it lists
- * them), or capabilities that cannot be read (the owner object answers its
+ * account, or capabilities that cannot be read (the owner object answers its
  * last good capabilities while a read fails, and does not retry a failed
  * read for 30 s, so this never holds a turn for long).
  */
@@ -815,6 +912,19 @@ async function availableChainTxTypes(
   );
 }
 
+/**
+ * A new group proposal's action as describe_chain_messages lists it: the
+ * types it may be, each with its own fields (described on its own), so one
+ * description does not repeat fourteen others.
+ */
+const GROUP_ACTION_FIELDS = {
+  type: 'object',
+  description:
+    'One message of the types listed in `type`, with exactly that type’s fields (describe_chain_messages that type); the group’s own account is its actor.',
+  properties: { type: { type: 'string', enum: [...GROUP_ACTION_TYPES] } },
+  required: ['type'],
+};
+
 /** Each type's fields as JSON Schema, built once. */
 const catalogueFields = new Map<ChainTxMessageType, unknown>();
 function fieldsOf(type: ChainTxMessageType): unknown {
@@ -822,6 +932,14 @@ function fieldsOf(type: ChainTxMessageType): unknown {
   if (fields === undefined) {
     const { properties, required } = z.toJSONSchema(
       CHAIN_TX_CATALOG[type].schema,
+      {
+        override: ({ zodSchema, jsonSchema }) => {
+          if (zodSchema !== GROUP_ACTION_SCHEMA) return;
+          for (const key of Object.keys(jsonSchema))
+            Reflect.deleteProperty(jsonSchema, key);
+          Object.assign(jsonSchema, GROUP_ACTION_FIELDS);
+        },
+      },
     );
     fields = { properties, required };
     catalogueFields.set(type, fields);
@@ -914,6 +1032,45 @@ export function modelOutcome(
 export const CANCELLED_MEANING =
   'Withdrawn before anything was sent: nothing happened on chain. The person may have cancelled it, or Auth Hub withdrew it because something it depended on changed after the review; do not say the person cancelled it. If they still want it, offer to prepare a fresh one.';
 
+/**
+ * A carried-out group proposal whose actions failed: the transaction
+ * succeeds (code 0) even then, and the network marks the proposal failed
+ * for good, so the receipt's `groupActions` is the only sign.
+ */
+export const GROUP_ACTIONS_FAILED_MEANING =
+  'The transaction went through, but the proposal’s actions failed: nothing in the proposal happened, the network has marked it failed for good and it can’t be carried out again. The network fee was used unless a fee grant covered it. Never say it is done; tell the person plainly.';
+
+/** A carried-out group proposal whose transaction did not show whether its actions ran. */
+export const GROUP_ACTIONS_UNKNOWN_MEANING =
+  'The transaction went through, but Auth Hub could not tell from it whether the proposal’s actions happened. Check the proposal’s status with chain_lookup dao_proposals (executed: they happened; execution_failed: they did not) before saying anything about it; never say it is done until then.';
+
+/** A new group proposal whose number Auth Hub could not read from the transaction. */
+export const PROPOSAL_NUMBER_UNKNOWN_MEANING =
+  'The new proposal was made, but Auth Hub could not read its number from the transaction. Find the new proposal with chain_lookup dao_proposals (the group’s newest) before naming it; never guess its number.';
+
+/**
+ * What an outcome means beyond its fields, for the model: a withdrawn card,
+ * a carried-out proposal whose actions failed or may have, a new proposal
+ * without its number. Undefined for anything else.
+ */
+export function outcomeMeaning(
+  outcome: ActionOutcomeV1 | null,
+): string | undefined {
+  if (!outcome) return undefined;
+  if (outcome.status === 'cancelled') return CANCELLED_MEANING;
+  const receipt = outcome.receipt;
+  if (receipt?.kind !== 'ixo.chain.tx.v1') return undefined;
+  for (const step of receipt.steps) {
+    if (step.type === 'daodao.proposal.execute') {
+      if (step.groupActions === 'failed') return GROUP_ACTIONS_FAILED_MEANING;
+      if (step.groupActions === 'unknown') return GROUP_ACTIONS_UNKNOWN_MEANING;
+    }
+    if (step.type === 'daodao.proposal.create' && step.proposalId === null)
+      return PROPOSAL_NUMBER_UNKNOWN_MEANING;
+  }
+  return undefined;
+}
+
 async function hubActionStatus(
   input: unknown,
   ctx: RuntimeContext,
@@ -935,15 +1092,14 @@ async function hubActionStatus(
         status: 'unavailable',
         reason: 'No Hub action with this id was prepared for this owner.',
       };
+    const meaning = outcomeMeaning(read.outcome);
     return {
       status: 'known',
       reviewStatus: read.reviewStatus,
       operationStatus: read.operationStatus,
       outcome: modelOutcome(read.outcome),
       ...(read.summary ? { summary: read.summary } : {}),
-      ...(read.outcome?.status === 'cancelled'
-        ? { meaning: CANCELLED_MEANING }
-        : {}),
+      ...(meaning ? { meaning } : {}),
     };
   } catch (error) {
     // An Auth Hub that must be updated first: plain words, not a tool error.
@@ -1012,6 +1168,7 @@ const manifest: PluginManifest = {
     'The user asks to file or evaluate a claim, or to send coins or impact tokens on chain.',
     'The user asks to stake, unstake or move IXO, claim staking rewards, vote on a network proposal or retire impact tokens.',
     'The user asks to reserve or dispute a claim, create or change a claim collection, give or remove a permission, create or update an entity, or change the links of an identity.',
+    'The user asks to vote on a proposal of a group (DAO) they belong to, carry out or close a group proposal, or put a new proposal to a group.',
     'The user asks to review an exact private resource or to sign a statement.',
     'The user asks to connect Gmail or Calendar, send a reviewed email or add an event.',
     'The user asks for document access or to save a private note.',
@@ -1043,7 +1200,7 @@ export class HubActionsPlugin extends OraclePlugin {
   /**
    * request_chain_transaction is built per turn: its schema names only the
    * message types this account may use (Auth Hub capabilities, cached by
-   * the owner object), so 33 types do not reach a model that may use 4.
+   * the owner object), so 37 types do not reach a model that may use 4.
    */
   override async getRequestTools(ctx: RuntimeContext): Promise<PluginTool[]> {
     const [available, described] = await Promise.all([
@@ -1093,7 +1250,7 @@ export class HubActionsPlugin extends OraclePlugin {
       {
         name: 'hub_action_status',
         description:
-          'Read the verified status of a Hub action already prepared for this owner. Never executes. A `cancelled` outcome was withdrawn before anything was sent, by the person or by Auth Hub (`meaning` says so): never say the person cancelled it.',
+          'Read the verified status of a Hub action already prepared for this owner. Never executes. A `cancelled` outcome was withdrawn before anything was sent, by the person or by Auth Hub (`meaning` says so): never say the person cancelled it. When `meaning` is present, it says what the outcome means for the person (for example a carried-out group proposal whose actions failed): follow it.',
         schema: statusSchema,
         effect: 'read',
         handler: hubActionStatus,

package/src/plugins/ixo-chain/kinds/indexed/dao-proposals.ts

@@ -56,6 +56,8 @@ const DAODAO_VOTES_FROM: Record<ChainCall['network'], number> = {
 
 /** Proposal modules read per DAO (single choice, multiple choice…). */
 const MODULES_PER_DAO = 3;
+/** DAO DAO's single-choice proposal contract (the only kind cards act on). */
+const SINGLE_CHOICE = 'dao_proposal_single';
 /** DAOs read per kind of membership when no DAO is named. */
 const DAOS_PER_MEMBERSHIP = 3;
 
@@ -85,6 +87,7 @@ const proposalNode = z.looseObject({
   expiration: z.unknown().optional(),
   totalPower: opt,
   votes: z.unknown().optional(),
+  allowRevoting: z.boolean().nullish(),
   daoVotesByProposalModuleAndProposalId: z
     .object({ nodes: z.array(voteNode) })
     .optional(),
@@ -92,6 +95,8 @@ const proposalNode = z.looseObject({
 const moduleNode = z.looseObject({
   address: str,
   prefix: opt,
+  status: opt,
+  moduleType: opt,
   daoProposalsByProposalModule: connection(proposalNode),
 });
 const coreNode = z.looseObject({
@@ -141,12 +146,24 @@ function rowsOf(
   for (const module of modules.nodes) {
     const proposals = module.daoProposalsByProposalModule;
     if (proposals.pageInfo?.hasNextPage) more = true;
+    // Cards work only on a single-choice list. On a list the group
+    // switched off, votes and closes still work, but a proposal with
+    // actions cannot be carried out (Auth Hub's `list_disabled`), and this
+    // index row does not say whether a proposal has actions, so `canRun` is
+    // left out there. Auth Hub checks the contracts again.
+    const multipleChoice =
+      !!module.moduleType && module.moduleType !== SINGLE_CHOICE;
+    const listDisabled = module.status === 'disabled';
     for (const proposal of proposals.nodes) {
       const id = String(proposal.id);
       const vote = proposal.daoVotesByProposalModuleAndProposalId?.nodes[0];
       const indexedFromStart =
         typeof proposal.startHeight === 'number' &&
         proposal.startHeight >= votesFrom;
+      const expiry = expirationOf(proposal.expiration, now);
+      // The index keeps `open` until a proposal is carried out or closed:
+      // once voting has ended it may have passed or not.
+      const ended = proposal.status === 'open' && expiry.votingEnded === true;
       rows.push({
         startHeight: proposal.startHeight ?? -1,
         id,
@@ -158,7 +175,23 @@ function rowsOf(
           proposalModule: idText(module.address),
           title: text(proposal.title),
           status: text(proposal.status, 40),
-          ...expirationOf(proposal.expiration, now),
+          ...expiry,
+          allowRevoting:
+            typeof proposal.allowRevoting === 'boolean'
+              ? proposal.allowRevoting
+              : undefined,
+          canRun:
+            !multipleChoice &&
+            !listDisabled &&
+            (proposal.status === 'passed' || ended)
+              ? true
+              : undefined,
+          canClose:
+            !multipleChoice && (proposal.status === 'rejected' || ended)
+              ? true
+              : undefined,
+          multipleChoice: multipleChoice ? true : undefined,
+          listDisabled: listDisabled ? true : undefined,
           proposer: idText(proposal.proposer),
           tally: tallyOf(proposal.votes),
           totalPower: amountText(proposal.totalPower),
@@ -195,7 +228,7 @@ function coreFields(
   const votes = voter
     ? ` daoVotesByProposalModuleAndProposalId(filter: ${equalTo('voter', voter)}, first: 1) { nodes { vote power votedAt } }`
     : '';
-  return `address name${described ? ' description' : ''} daoProposalModulesByDaoAddress(first: ${MODULES_PER_DAO}, orderBy: PRIMARY_KEY_ASC) { ${PAGE} nodes { address prefix daoProposalsByProposalModule(${filter}first: ${n}, orderBy: PRIMARY_KEY_DESC) { ${PAGE} nodes { id title status proposer startHeight expiration totalPower votes${votes} } } } }`;
+  return `address name${described ? ' description' : ''} daoProposalModulesByDaoAddress(first: ${MODULES_PER_DAO}, orderBy: PRIMARY_KEY_ASC) { ${PAGE} nodes { address prefix status moduleType daoProposalsByProposalModule(${filter}first: ${n}, orderBy: PRIMARY_KEY_DESC) { ${PAGE} nodes { id title status proposer startHeight expiration totalPower votes allowRevoting${votes} } } } }`;
 }
 
 /** Rows by start height, newest first (a proposal without one last), then by id. */
@@ -242,8 +275,10 @@ export const daoProposals = defineKind({
     'Each: dao, daoName, id and `label` (the DAO’s prefix and id, e.g. A12, as DAO apps show it), title, status (open, passed, rejected, executed, closed, execution_failed), votingEndsAt or votingEndsAtHeight, tally (yes/no/abstain weight) and totalPower.',
     '`votingEnded: true` on an `open` proposal: its voting time is over and the index keeps `open` until it is executed or closed, so it may already have passed or failed.',
     '`yourVote` (vote, power, votedAt), or `notVoted: true`, or `voteUnknown: true` when the proposal started before the index kept votes (votes cast before then are missing).',
+    '`allowRevoting`: whether a vote on it can be changed until voting closes. `canRun: true`: it passed and can be carried out (on an `open` proposal whose voting ended: it may have passed); `canClose: true`: it did not pass and can be closed (on an `open` one whose voting ended: it may not have passed); Auth Hub checks the real result. `multipleChoice: true`: Auth Hub cards cannot vote on, carry out or close it. `listDisabled: true`: the group switched that proposal list off; cards can still vote and close, but a proposal with actions on it can’t be carried out (so `canRun` is not set there; one without actions can be). Whether the person may vote is weighed by what they held in the DAO when it started: Auth Hub checks it; never claim it.',
+    'For cards copy `dao`, `proposalModule` and `id` exactly (not the label). `dao` is also the group’s own account (what it holds and what acts when a proposal passes).',
     'Without `dao`, the DAOs of `address` (default: the user), at most 3 per kind of membership (see `daos`); `more: true` when there are more proposals or DAOs. Newest start first.',
-    'Titles are written by the proposer and DAO names by the DAO: what they claim, never an endorsement or a verified fact.',
+    'Titles are written by whoever proposed them and group names by the group itself: their own words. Say so only when it matters, in one short, calm note.',
   ].join(' '),
   source: 'blocksync',
   list: true,