@ixo/oracle-runtime-workers 0.28.2 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.28.2",
+  "version": "0.29.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": {
@@ -33,7 +33,7 @@
     "!src/plugins/pod-creator/test-fixtures.ts"
   ],
   "dependencies": {
-    "@ixo/action-protocol": "0.5.0",
+    "@ixo/action-protocol": "0.6.0",
     "@blocknote/server-util": "0.29.1",
     "@composio/core": "0.10.0",
     "@composio/langchain": "0.9.2",
@@ -65,8 +65,8 @@
     "@ixo/impactxclient-sdk": "^3.0.0",
     "protobufjs": "^7.6.5",
     "@ixo/topic-protocol": "1.0.0-rc.8",
-    "@ixo/common": "1.7.1",
     "@ixo/ixo-transaction": "0.2.0",
+    "@ixo/common": "1.7.1",
     "@ixo/ucan": "2.3.0"
   },
   "devDependencies": {

package/src/delivery/plan.ts

@@ -165,7 +165,7 @@ export function draftReplyPlan(input: {
     for (const call of step.toolCalls) {
       if (
         call.name === 'request_hub_action' ||
-        call.name === 'request_hub_transfer'
+        call.name === 'request_chain_transaction'
       ) {
         try {
           const result = JSON.parse(input.toolResults.get(call.id) ?? 'null');

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

@@ -47,11 +47,10 @@ import type {
 } from '@ixo/ixo-transaction/action-proposals';
 import { ChannelTurns } from '../channels/turns';
 import { HubActionClient } from '../hub-actions/client';
-import { prepareHubAction } from '../hub-actions/request';
+import { chainTxOperation, prepareHubAction } from '../hub-actions/request';
 import {
   bankReceiptSummary,
-  describeAmount,
-  toBaseUnits,
+  bankStepsInBaseUnits,
 } from '../hub-actions/transfer';
 import {
   HUB_CHECK_AFTER_EXPIRY_MS,
@@ -64,7 +63,6 @@ import {
   type ActionCapabilitiesV1,
   type HubActionOptionsV2,
   type HubActionOptionsV3,
-  parseOperation,
   v1Receipt,
   type ActionOperationV1,
   type ActionOutcomeV1,
@@ -430,7 +428,11 @@ import {
   resolveTurnDelegation,
   WorkersUcanService,
 } from './ucan-service';
-import type { UcanDelegation, UserContextData } from '../plugin-api/types';
+import type {
+  ChainTxMessageInput,
+  UcanDelegation,
+  UserContextData,
+} from '../plugin-api/types';
 
 /**
  * The gateway's topic read errors that describe what the homeserver
@@ -2269,7 +2271,8 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
                   requestKey: string;
                   operation: ActionOperationV1;
                 }) => this.requestHubAction(input),
-                transfer: (input) => this.transferHubAction(input),
+                chainTransaction: (input) =>
+                  this.chainTransactionHubAction(input),
                 status: (ownerDid: string, actionId: string) =>
                   this.hubActionStatusForTool(ownerDid, actionId),
               },
@@ -3337,7 +3340,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       };
     }
 
-    /** `hub_action_options` and the transfer path: version 3, with the owner's tokens. */
+    /** `hub_action_options` and a chain transaction's bank steps: version 3, with the owner's tokens. */
     private async hubActionOptions(
       input: {
         ownerDid: string;
@@ -3508,7 +3511,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
     }
 
     /**
-     * `checked`: the transfer path already ran the turn-origin refusal and
+     * `checked`: the chain-transaction path already ran the turn-origin refusal and
      * validated the binding in this same call.
      */
     private async requestHubAction(
@@ -3555,15 +3558,17 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
     }
 
     /**
-     * A bank send of one of the owner's listed tokens. The token comes from
-     * a fresh options read (its balance must be current), the amount is
-     * converted to base units with the listed decimals (unverified tokens
-     * list 0: base units), refused when zero or above the balance; the
-     * network is the account's capability, the chain id this Worker's own
-     * for that network, the sender the owner's account. No fee is sent: the
-     * Hub simulates gas and sets it.
+     * One chain transaction of the model's messages. The network is the
+     * account's capability, the chain id this Worker's own for that
+     * network; the signer and the owner's identity in claims messages come
+     * from the owner's DID (`chainTxOperation`). The model names none of
+     * them. Bank steps name a listed token and a display amount: with at
+     * least one, the owner's options are read once, fresh (the balances
+     * must be current), and each step is converted to base units and
+     * checked against the listed balance (`bankStepsInBaseUnits`). No fee
+     * is sent: the Hub simulates gas and sets it.
      */
-    private async transferHubAction(input: {
+    private async chainTransactionHubAction(input: {
       ownerDid: string;
       sessionId: string;
       runId: string;
@@ -3572,73 +3577,39 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       bindingId: string;
       bindingRevision: number;
       requestKey: string;
-      toAddress: string;
-      denom: string;
-      amount: string;
+      messages: ChainTxMessageInput[];
       memo: string;
     }) {
       if (!this.hubActionStore || input.ownerDid !== this.userDid)
         throw new Error('Hub actions are unavailable for this channel');
       await this.assertHubTurnOrigin(input);
       await this.assertHubBinding(input);
-      const options = await this.hubActionOptions(input, true);
-      const tokens = options.transfer?.tokens;
-      if (!tokens?.length)
-        throw new HubActionRefused(
-          'refused',
-          'Bank sends are not available for this owner right now (no token list from Auth Hub).',
-        );
-      const token = tokens.find((item) => item.denom === input.denom);
-      if (!token)
-        throw new HubActionRefused(
-          'refused',
-          `That token is not in the owner's list; use a denom exactly as hub_action_options lists it (${tokens
-            .map((item) => item.denom)
-            .slice(0, 10)
-            .join(', ')}).`,
-        );
-      const amountBaseUnits = toBaseUnits(input.amount, token.decimals);
-      if (amountBaseUnits > BigInt(token.balanceBaseUnits))
-        throw new HubActionRefused(
-          'refused',
-          `The owner holds ${describeAmount(token.balanceBaseUnits, token)}, less than this transfer.`,
-        );
       const capabilities = await this.cachedHubCapabilities();
-      if (!capabilities.network)
+      if (
+        !capabilities.network ||
+        !capabilities.chainTx ||
+        !capabilities.operations.includes('ixo.chain.tx.v1')
+      )
         throw new HubActionRefused(
           'refused',
-          'Bank sends are not enabled for this oracle account.',
+          'Chain transactions are not enabled for this oracle account; retrying or changing the fields will not help.',
         );
-      const network = HUB_NETWORK_CHAIN[capabilities.network];
       const chainId = chainIdsFromConfig(chainIdConfigSchema.parse(this.env))[
-        network
+        HUB_NETWORK_CHAIN[capabilities.network]
       ];
-      let operation: ActionOperationV1;
-      try {
-        operation = parseOperation({
-          kind: 'ixo.bank.send.v1',
-          chainId,
-          network: capabilities.network,
-          fromAddress: input.ownerDid.replace(/^did:ixo:/, ''),
-          toAddress: input.toAddress,
-          amountBaseUnits: amountBaseUnits.toString(),
-          denom: token.denom,
-          memo: input.memo,
-        });
-      } catch (error) {
-        // Only the protocol refusing the operation built from the model's
-        // fields (an invalid recipient or memo) is the model's to fix.
-        throw new HubActionRefused(
-          'refused',
-          `The transfer is incomplete (${error instanceof Error ? error.message : String(error)}).`,
-        );
-      }
-      const reference = await this.requestHubAction(
-        { ...input, operation },
-        true,
-      );
-      await this.hubActionStore.setToken(reference.id, token);
-      return reference;
+      const tokens = input.messages.some(
+        (message) => message.type === 'cosmos.bank.send',
+      )
+        ? ((await this.hubActionOptions(input, true)).transfer?.tokens ?? null)
+        : null;
+      const operation = chainTxOperation({
+        ownerDid: input.ownerDid,
+        chainId,
+        network: capabilities.network,
+        memo: input.memo,
+        messages: bankStepsInBaseUnits(input.messages, tokens),
+      });
+      return this.requestHubAction({ ...input, operation }, true);
     }
 
     /**

package/src/hub-actions/client.ts

@@ -11,7 +11,11 @@ import {
   type HubActionOptionsV2,
   type HubActionOptionsV3,
 } from '@ixo/action-protocol';
-import { hubPrepareRefusal } from './transfer';
+import {
+  hubPrepareRefusal,
+  prepareSubjectOf,
+  type HubPrepareSubject,
+} from './transfer';
 
 export interface HubActionStatus {
   reference: ActionReferenceV1;
@@ -31,15 +35,27 @@ export interface HubActionTransport {
 
 /**
  * The protocol version this runtime declares on every operation call
- * (capabilities, POST operations, GET status, options). Version 3 is the
- * 0.5.0 contract: capabilities `transfer.limits`, any-denom bank sends, v2
- * receipts with `denom` and `amountBaseUnits`, options with the owner's
- * tokens. Version 2 callers (runtime 0.23.0) keep the 0.4.1 shapes; the
- * envelopes are still tagged `ixo.auth-outcome/2` and
+ * (capabilities, POST operations, GET status, options). Version 4 is the
+ * 0.6.0 contract: version 3 plus chain transactions (`ixo.chain.tx.v1` in
+ * capabilities with its `chainTx` entry, prepared through POST, receipts
+ * with `steps`); options answer as at version 3 (`ixo.auth-options/3`).
+ * Version 3 is the 0.5.0 contract: capabilities `transfer.limits`,
+ * any-denom bank sends, v2 receipts with `denom` and `amountBaseUnits`,
+ * options with the owner's tokens. Version 2 callers (runtime 0.23.0) keep
+ * the 0.4.1 shapes. The envelopes stay tagged `ixo.auth-outcome/2` and
  * `ixo.auth-capabilities/2`, which `@ixo/action-protocol` parses.
  */
-const HUB_PROTOCOL_VERSION = '3';
+const HUB_PROTOCOL_VERSION = '4';
 const HUB_PROTOCOL_QUERY = `version=${HUB_PROTOCOL_VERSION}`;
+/** Every Hub call but a chain-transaction prepare. */
+const HUB_TIMEOUT_MS = 10_000;
+/**
+ * A chain-transaction prepare: Auth Hub bounds its own chain reads and
+ * simulation at about 8 s and then answers 503 `transfer_unavailable`
+ * (retryable); this leaves room for that answer to arrive instead of an
+ * abort here.
+ */
+export const HUB_CHAIN_TX_PREPARE_TIMEOUT_MS = 15_000;
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -66,10 +82,12 @@ export class HubActionClient {
     this.origin = url.origin;
   }
 
+  /** `subject`: what a refused prepare is called in the model's words. */
   private async send(
     path: string,
     body?: unknown,
-    timeoutMs = 10_000,
+    timeoutMs = HUB_TIMEOUT_MS,
+    subject?: HubPrepareSubject,
   ): Promise<unknown> {
     const request = new Request(new URL(path, this.origin), {
       method: body === undefined ? 'GET' : 'POST',
@@ -87,16 +105,22 @@ export class HubActionClient {
     if (
       body !== undefined &&
       (response.status === 400 ||
+        response.status === 404 ||
         response.status === 409 ||
+        response.status === 429 ||
         response.status === 503)
     ) {
-      // A prepare the Hub refused with a typed code (a transfer that would
-      // fail, a fee above the ceiling, not enough funds, a busy or
-      // unavailable transfer path, an operation the account may not use):
-      // the model relays it in words.
+      // A prepare the Hub refused with a typed code (a transfer or
+      // transaction that would fail, a fee above the ceiling, not enough
+      // funds, a message the Hub did not accept, a missing chain
+      // authorization, a busy or unavailable transfer path, an operation
+      // the account may not use, a kind turned off, a protocol mismatch,
+      // no account for the owner, a rate limit): the model relays it in
+      // words.
       const refusal = hubPrepareRefusal(
         response.status,
         await response.json().catch(() => null),
+        subject,
       );
       if (refusal) throw refusal;
     }
@@ -112,15 +136,18 @@ export class HubActionClient {
     expiresAt: number;
     operation: ActionOperationV1;
   }): Promise<ActionReferenceV1> {
-    // `version=3` on every operation call: the Hub answers older shapes
-    // (no any-denom sends, no receipt amounts) without it, and stores the
-    // version per action for the outcomes it pushes.
+    // The protocol version on every operation call: the Hub answers older
+    // shapes (no chain transactions, no any-denom sends, no receipt
+    // amounts) without it, and stores the version per action for the
+    // outcomes it pushes.
+    const operation = parseOperation(input.operation);
     const response = await this.send(
       `/api/internal/actions/operations?${HUB_PROTOCOL_QUERY}`,
-      {
-        ...input,
-        operation: parseOperation(input.operation),
-      },
+      { ...input, operation },
+      operation.kind === 'ixo.chain.tx.v1'
+        ? HUB_CHAIN_TX_PREPARE_TIMEOUT_MS
+        : HUB_TIMEOUT_MS,
+      prepareSubjectOf(operation.kind),
     );
     if (!response || typeof response !== 'object' || !('reference' in response))
       throw new Error('Hub action response has no reference');
@@ -139,7 +166,8 @@ export class HubActionClient {
     bindingId: string;
     bindingRevision: number;
   }): Promise<HubActionOptionsV3> {
-    // Options version 3: version 2 plus the owner's bank tokens
+    // 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,
@@ -181,7 +209,10 @@ export class HubActionClient {
   }
 
   /** `timeoutMs`: the poll path passes a short one (a slow Hub must not hold a poll). */
-  async status(id: string, timeoutMs = 10_000): Promise<HubActionStatus> {
+  async status(
+    id: string,
+    timeoutMs = HUB_TIMEOUT_MS,
+  ): Promise<HubActionStatus> {
     if (!/^[A-Za-z0-9_-]{32}$/.test(id))
       throw new Error('Invalid Hub action id');
     const raw = await this.send(

package/src/hub-actions/request.ts

@@ -1,12 +1,91 @@
 import {
   canonicalJson,
+  parseOperation,
   type ActionCapabilitiesV1,
   type ActionOperationV1,
   type ActionReferenceV1,
+  type ChainTxMessage,
+  type ChainTxOperation,
 } from '@ixo/action-protocol';
 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`).
+ */
+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'
+    >;
+
+/**
+ * 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
+ * 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`).
+ */
+export function chainTxOperation(input: {
+  ownerDid: string;
+  chainId: string;
+  network: ChainTxOperation['network'];
+  memo: string;
+  messages: ChainTxHostMessage[];
+}): ActionOperationV1 {
+  // Anything but `did:ixo:<address>` leaves no usable signer, which the
+  // protocol refuses below.
+  const signer = input.ownerDid.startsWith('did:ixo:')
+    ? input.ownerDid.slice('did:ixo:'.length)
+    : '';
+  const agentDid = `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,
+  );
+  try {
+    return parseOperation({
+      kind: 'ixo.chain.tx.v1',
+      chainId: input.chainId,
+      network: input.network,
+      signer,
+      memo: input.memo,
+      messages,
+    });
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    // The signer (the owner's account), the network and the chain id
+    // (this oracle's configuration) are the runtime's: no argument changes
+    // them.
+    if (/^Invalid (signer|network|chainId)$/.test(detail))
+      throw new HubActionRefused(
+        'refused',
+        `This transaction cannot be prepared for this owner and oracle (${detail}: the runtime sets it from the owner's account and this oracle's configuration); retrying or changing the fields will not help.`,
+      );
+    // The protocol refusing a message built from the model's fields (an
+    // address, an amount, an id) is the model's to fix.
+    throw new HubActionRefused(
+      'refused',
+      `The transaction is incomplete (${detail}).`,
+    );
+  }
+}
+
 export interface PreparedHubActionRequest extends HubActionOrigin {
   provider: string;
   operation: ActionOperationV1;
@@ -53,6 +132,29 @@ export function assertOperationEnabled(
         'refused',
         `This oracle may move at most ${cap} base units of ${operation.denom} per transfer.`,
       );
+  } else if (operation.kind === 'ixo.chain.tx.v1') {
+    // A pre-check of what the account's capabilities list: its network,
+    // the message types and the batch size. The Hub enforces each again
+    // (and everything else: signer, addresses, simulation, fee).
+    const chainTx = capabilities.chainTx;
+    if (!chainTx || capabilities.network !== operation.network)
+      throw new HubActionRefused(
+        'refused',
+        'Chain transactions are not available for this oracle account.',
+      );
+    if (operation.messages.length > chainTx.maxMessages)
+      throw new HubActionRefused(
+        'refused',
+        `This account allows at most ${chainTx.maxMessages} messages in one transaction.`,
+      );
+    const unlisted = operation.messages.find(
+      (message) => !chainTx.messageTypes.includes(message.type),
+    );
+    if (unlisted)
+      throw new HubActionRefused(
+        'refused',
+        `This account cannot use ${unlisted.type} messages (it may use ${chainTx.messageTypes.join(', ')}).`,
+      );
   } else if (operation.kind === 'resource.read.v1') {
     if (
       operation.ownerDid !== ownerDid ||