@ixo/oracle-runtime-workers 0.41.2 → 0.42.0

package/src/plugins/pod-creator/chain-gateway.ts

@@ -9,24 +9,87 @@ import type { ServicePodBlueprint } from './blueprint-types';
  */
 export interface PreparedPodBatch {
   /**
-   * The messages, in execution order: `MsgCreateEntity` first, then the
-   * claim collection(s), entity accounts and grants (`POD_BATCH_TYPE_URLS`).
-   * Each is `{ typeUrl, value }` in proto-JSON (camelCase fields, integer
-   * amounts as strings, bytes as base64) with exactly its catalog fields.
+   * The messages, in execution order: `MsgCreateEntity` first, then only
+   * `POD_BATCH_TYPE_URLS` (the bundled gateway sends `MsgCreateEntity`
+   * alone). Each is `{ typeUrl, value }` in proto-JSON (camelCase fields,
+   * integer amounts as strings, bytes as base64, timestamps as RFC 3339
+   * strings) with exactly its catalog fields.
    */
   messages: ITrxMsg[];
   /** Human-readable summary of what the batch creates (at most 1000 characters). */
   summary: string;
   /** Estimated cost, when the gateway can compute it. */
   estimatedCost?: string;
+  /**
+   * Public documents the messages name (by URL and SHA-256 proof) that are
+   * not published yet: `publishDocuments` publishes them once the user
+   * approved, before the wallet is asked to sign. Empty when every document
+   * the messages name is already public.
+   */
+  documents: PendingDocument[];
+}
+
+/**
+ * A public document a batch names (the POD's profile, its domain card),
+ * reserved on the oracle's homeserver when the batch is prepared and
+ * uploaded only after the user approved it.
+ */
+export interface PendingDocument {
+  /** The reserved media it is uploaded as: `mxc://<server>/<media id>`. */
+  mxc: string;
+  /** Its media type, e.g. `application/ld+json`. */
+  contentType: string;
+  /** The file name the homeserver records. */
+  filename: string;
+  /** The exact text: the message carries the SHA-256 of these bytes as its proof. */
+  text: string;
+}
+
+/**
+ * An expected refusal (a missing identity, a homeserver that is down), which
+ * the tools report to the model as a result instead of throwing.
+ */
+export interface GatewayRefusal {
+  ok: false;
+  message: string;
+  /** Whether the same call can succeed later unchanged (something was down). */
+  retryable: boolean;
+}
+
+/** A gateway answer: the value, or why there is none. */
+export type GatewayResult<T extends object> =
+  | ({ ok: true } & T)
+  | GatewayRefusal;
+
+/**
+ * What a broadcast transaction says about the POD. `pending`: not on chain
+ * (or not indexed) within the lookup's time, ask again later with the same
+ * hash; `failed`: it failed, or it is not the POD this conversation sent, so
+ * asking again cannot help; `unavailable`: the chain could not be read.
+ */
+export type PodConfirmation =
+  | { status: 'created'; podDid: string; summary: string }
+  | {
+      status: 'pending' | 'failed' | 'unavailable';
+      message: string;
+      retryable: boolean;
+    };
+
+/** What the user's wallet was asked to sign, as the create session records it. */
+export interface SentPodBatch {
+  /** The messages exactly as sent (proto-JSON, catalog-validated). */
+  messages: ITrxMsg[];
+  /** The profile the POD was prepared with (for its domain card). */
+  profile: PodProfile;
 }
 
 /**
  * The message types a POD creation batch may carry. The chain runs the
  * messages of one transaction in order, all or nothing, so a later message
  * can name what an earlier one creates — the entity DID, its admin account,
- * the collection id — as long as the gateway predicts those values right
- * (otherwise the whole transaction fails and nothing is created).
+ * the collection id — only by predicting those values (otherwise the whole
+ * transaction fails and nothing is created). The bundled gateway does not
+ * predict: it sends `MsgCreateEntity` alone.
  */
 export const POD_BATCH_TYPE_URLS = [
   '/ixo.entity.v1beta1.MsgCreateEntity',
@@ -62,49 +125,78 @@ export function podBatchProblem(
   return null;
 }
 
-/** The created POD, resolved from the broadcast transaction. */
-export interface CreatedPod {
-  podDid: string;
-  summary: string;
+/** What the user agreed to call the POD, for its on-chain profile. */
+export interface PodProfile {
+  /** The POD's name: plain text, 1 to 100 characters. */
+  name: string;
+  /** What the POD does, in plain text (at most 600 characters). */
+  description?: string;
 }
 
 /**
- * The chain-facing seam for the create path. The planned concrete implementation
- * calls the IXO MCP server (hosted on Cloudflare) to compose the POD-creation
- * batch (`MsgCreateEntity` + the claim collection + authz grants) and to read a
- * broadcast transaction back. The oracle never signs creation — the user's
- * wallet does — so the gateway only ever returns proto-JSON messages, which
- * the plugin validates against the `@ixo/ixo-transaction` catalog before
- * storing them, and resolves results.
+ * The chain-facing seam for the create path. The oracle never signs
+ * creation — the user's wallet does — so a gateway only ever returns
+ * proto-JSON messages, which the plugin validates against the
+ * `@ixo/ixo-transaction` catalog before storing them, and resolves the
+ * broadcast transaction afterwards.
  *
- * Both methods receive the request `RuntimeContext` because reaching the IXO MCP
- * server follows the runtime's remote-MCP pattern (see the sandbox plugin):
- * resolve the server DID via did:web and mint a per-user `ixo:*` UCAN invocation
- * through `ctx.ucan` for the `Authorization` header, with the MCP URL read from
- * `ctx.config`. The seam is injected so the create path stays unit-testable
- * without a live server or chain.
+ * The bundled implementation is `createIxoChainGateway()`
+ * (`ixo-chain-gateway.ts`): one `MsgCreateEntity` owned by the user, its
+ * profile reserved on the oracle's homeserver and published after approval,
+ * read back from chain REST; then the POD's domain card. Every method
+ * receives the request `RuntimeContext` (the user, the config, the turn's
+ * abort signal, the oracle's Matrix device) and answers an expected refusal
+ * as a result; a throw is a programming error. The seam is injected so the
+ * create path stays unit-testable without a live homeserver or chain, and
+ * so a fork can compose a different batch.
  */
 export interface ChainGateway {
   preparePodBatch(
-    input: { blueprint: ServicePodBlueprint; network: Network },
+    input: {
+      blueprint: ServicePodBlueprint;
+      network: Network;
+      profile: PodProfile;
+    },
     ctx: RuntimeContext,
-  ): Promise<PreparedPodBatch>;
+  ): Promise<GatewayResult<PreparedPodBatch>>;
+  /** Publish a prepared batch's pending documents; publishing one twice is a success. */
+  publishDocuments(
+    input: { documents: readonly PendingDocument[] },
+    ctx: RuntimeContext,
+  ): Promise<GatewayResult<object>>;
+  /** Read the transaction back and check it is the POD `sent` describes. */
   confirmPodCreation(
-    input: { txHash: string; network: Network },
+    input: { txHash: string; network: Network; sent: SentPodBatch },
+    ctx: RuntimeContext,
+  ): Promise<PodConfirmation>;
+  /** The batch that adds a confirmed POD's public domain card (one message). */
+  prepareDomainCard(
+    input: { network: Network; podDid: string; profile: PodProfile },
+    ctx: RuntimeContext,
+  ): Promise<GatewayResult<PreparedPodBatch>>;
+  /** Ask the domain indexer to index the POD now; best effort, never throws. */
+  requestIndexing(
+    input: { network: Network; podDid: string },
     ctx: RuntimeContext,
-  ): Promise<CreatedPod>;
+  ): Promise<void>;
 }
 
 const notConfigured = (): never => {
   throw new Error(
-    'ChainGateway not configured: the POD create path needs a chain gateway ' +
-      'wired to the IXO MCP server before it can prepare or confirm ' +
-      'transactions.',
+    'ChainGateway not configured: this oracle was built without a chain ' +
+      'gateway, so it cannot prepare or confirm POD creation transactions.',
   );
 };
 
-/** Default gateway that errors until a real one is wired. */
+/**
+ * A gateway that refuses every call, for a fork that wants the design
+ * pipeline without on-chain creation: the create tools report creation as
+ * unavailable without calling it.
+ */
 export const notConfiguredChainGateway: ChainGateway = {
   preparePodBatch: async () => notConfigured(),
+  publishDocuments: async () => notConfigured(),
   confirmPodCreation: async () => notConfigured(),
+  prepareDomainCard: async () => notConfigured(),
+  requestIndexing: async () => notConfigured(),
 };

package/src/plugins/pod-creator/config.ts

@@ -5,6 +5,7 @@ import {
 } from '@ixo/ixo-transaction';
 import { z } from 'zod';
 import type { RuntimeContext } from '../../plugin-api/types';
+import { DOMAIN_INDEXER_URLS } from '../domain-indexer/domain-indexer.plugin';
 import {
   chainIdConfigSchema,
   chainIdsFromConfig,
@@ -18,6 +19,9 @@ import {
  */
 export const DEFAULT_NETWORK: Network = 'testnet';
 
+/** An IXO entity DID as the chain derives it. */
+const ENTITY_DID = /^did:ixo:entity:[0-9a-f]{32}$/;
+
 /**
  * Plugin-owned env vars. The capsules registry URL and `NETWORK` are read as
  * siblings from the merged config (owned by the skills plugin / base schema),
@@ -42,14 +46,49 @@ export const podCreatorConfigSchema = z.object({
     .default(false),
   /** The chain id each network's signing request names. */
   ...chainIdConfigSchema.shape,
+  /**
+   * The relayer node a created POD names, instead of the network's default
+   * ({@link POD_RELAYER_NODE_DIDS}).
+   */
+  POD_CREATOR_RELAYER_NODE_DID: z
+    .string()
+    .regex(ENTITY_DID, 'expected an entity DID: did:ixo:entity:<32 hex>')
+    .optional(),
+  /**
+   * The Portal a created POD is linked to, instead of the network's default
+   * ({@link PORTAL_URLS}).
+   */
+  POD_CREATOR_PORTAL_URL: z.url().optional(),
 });
 
+/**
+ * The relayer node each network's Portal names on the domains (and PODs) it
+ * creates: its `NEXT_PUBLIC_DAO_DID` (ixo-portal `lib/entity/createEntity.ts`),
+ * as read from the Portal's recent "Create domain:" transactions. The
+ * mainnet Portal lists only entities of this relayer that are verified.
+ * Not the oracles' relayer (`lib/oracle/networkConfig.ts`), which only
+ * oracle entities name.
+ */
+export const POD_RELAYER_NODE_DIDS: Readonly<Record<Network, string>> = {
+  mainnet: 'did:ixo:entity:47d9c64891e77cb8e588d33b83ab3042',
+  testnet: 'did:ixo:entity:3d079ebc0b332aad3305bb4a51c72edb',
+  devnet: 'did:ixo:entity:ac12c6f8f299071eb24f2a10591d7ab7',
+};
+
+/** The Portal each network's PODs are opened in. */
+export const PORTAL_URLS: Readonly<Record<Network, string>> = {
+  mainnet: 'https://portal.qi.space',
+  testnet: 'https://test.portal.qi.space',
+  devnet: 'https://dev.portal.qi.space',
+};
+
 /** Sibling env + plugin flags the tools read at request time. */
 const configReadSchema = z.object({
   NETWORK: NetworkSchema.optional(),
   POD_CREATOR_ALLOW_MAINNET:
     podCreatorConfigSchema.shape.POD_CREATOR_ALLOW_MAINNET.optional(),
   ...chainIdConfigSchema.shape,
+  POD_CREATOR_PORTAL_URL: podCreatorConfigSchema.shape.POD_CREATOR_PORTAL_URL,
 });
 
 export interface PodCreatorConfig {
@@ -57,8 +96,12 @@ export interface PodCreatorConfig {
   mainnetAllowed: boolean;
   /** The chain id each network's signing request names. */
   chainIds: Readonly<Record<Network, string>>;
+  /** The Portal of `network`, without a trailing slash. */
+  portalUrl: string;
 }
 
+const withoutSlash = (url: string): string => url.replace(/\/+$/, '');
+
 /**
  * Network routing + the mainnet opt-in, read from the merged config. Falls
  * back to testnet with mainnet disabled when the config is unreadable — and
@@ -75,11 +118,48 @@ export function readPodCreatorConfig(ctx: RuntimeContext): PodCreatorConfig {
       network: DEFAULT_NETWORK,
       mainnetAllowed: false,
       chainIds: DEFAULT_CHAIN_IDS,
+      portalUrl: PORTAL_URLS[DEFAULT_NETWORK],
     };
   }
+  const network = parsed.data.NETWORK ?? DEFAULT_NETWORK;
   return {
-    network: parsed.data.NETWORK ?? DEFAULT_NETWORK,
+    network,
     mainnetAllowed: parsed.data.POD_CREATOR_ALLOW_MAINNET ?? false,
     chainIds: chainIdsFromConfig(parsed.data),
+    portalUrl: withoutSlash(
+      parsed.data.POD_CREATOR_PORTAL_URL ?? PORTAL_URLS[network],
+    ),
   };
 }
+
+const relayerReadSchema = z.object({
+  POD_CREATOR_RELAYER_NODE_DID:
+    podCreatorConfigSchema.shape.POD_CREATOR_RELAYER_NODE_DID,
+});
+
+/** The relayer node a POD created on `network` names: the operator's, else the network's Portal's. */
+export function relayerNodeDidFor(
+  ctx: RuntimeContext,
+  network: Network,
+): string {
+  const parsed = relayerReadSchema.safeParse(ctx.config);
+  return (
+    (parsed.success ? parsed.data.POD_CREATOR_RELAYER_NODE_DID : undefined) ??
+    POD_RELAYER_NODE_DIDS[network]
+  );
+}
+
+/** `DOMAIN_INDEXER_URL` is the domain-indexer plugin's; read here as a sibling. */
+const indexerReadSchema = z.object({ DOMAIN_INDEXER_URL: z.url().optional() });
+
+/** The domain indexer of `network`, without a trailing slash. */
+export function domainIndexerUrlFor(
+  ctx: RuntimeContext,
+  network: Network,
+): string {
+  const parsed = indexerReadSchema.safeParse(ctx.config);
+  return withoutSlash(
+    (parsed.success ? parsed.data.DOMAIN_INDEXER_URL : undefined) ??
+      DOMAIN_INDEXER_URLS[network],
+  );
+}

package/src/plugins/pod-creator/create-session-store.ts

@@ -1,5 +1,7 @@
+import { ITrxMsgSchema } from '@ixo/ixo-transaction';
 import { z } from 'zod';
 import type { RuntimeContext, UserKvSurface } from '../../plugin-api/types';
+import type { SentPodBatch } from './chain-gateway';
 
 /**
  * Per-(user, thread) state machine for the create path's propose → approve →
@@ -16,9 +18,13 @@ import type { RuntimeContext, UserKvSurface } from '../../plugin-api/types';
  * message after seeing the batch before it can be approved, so a single model
  * turn — steered, say, by injected text in the brief or a section — cannot run
  * prepare → approve → sign on its own.
+ *
+ * After the commit it keeps what was sent for signing (confirmation checks
+ * the transaction against it), the POD confirmed from it, and the one domain
+ * card step that may follow.
  */
 export interface CreateSessionStore {
-  /** Record a freshly prepared batch; any prior approval is superseded. */
+  /** Record a freshly prepared batch; anything before it in the thread is superseded. */
   prepared(
     userDid: string,
     threadId: string,
@@ -37,15 +43,57 @@ export interface CreateSessionStore {
     requestId: string,
   ): Promise<ApproveOutcome>;
   /**
-   * Spend the approval for a sign dispatch. Returns true only when `blobId`
-   * is the approved pending batch; the approval is cleared when it matches, so
-   * a second dispatch needs a fresh approve.
+   * Spend the approval for a sign dispatch of `sent`. Returns true only when
+   * `blobId` is the approved pending batch; the approval is cleared when it
+   * matches (a second dispatch needs a fresh approve) and `sent` is recorded
+   * as what the wallet was asked to sign.
    */
-  consume(userDid: string, threadId: string, blobId: string): Promise<boolean>;
-  /** Drop the session (after on-chain confirmation). */
+  consume(
+    userDid: string,
+    threadId: string,
+    blobId: string,
+    sent?: SentPodBatch,
+  ): Promise<boolean>;
+  /** The thread's approval, what its last sign request carried, and the POD confirmed from it. */
+  read(
+    userDid: string,
+    threadId: string,
+  ): Promise<CreateSessionView | undefined>;
+  /** Record the POD confirmed from the sent batch (no-op when nothing was sent). */
+  confirmed(
+    userDid: string,
+    threadId: string,
+    pod: { podDid: string; txHash: string },
+  ): Promise<void>;
+  /**
+   * Claim the confirmed POD's one domain card step. `no-pod` when no POD
+   * was confirmed in the thread, `claimed` when the card is being added or
+   * was added already.
+   */
+  claimCard(userDid: string, threadId: string): Promise<CardClaim>;
+  /** End a claimed card step: `added` keeps it closed, `released` lets it run again. */
+  settleCard(
+    userDid: string,
+    threadId: string,
+    outcome: 'added' | 'released',
+  ): Promise<void>;
+  /** Drop the session (the design was restarted). */
   clear(userDid: string, threadId: string): Promise<void>;
 }
 
+/** The session as the create tools read it. */
+export interface CreateSessionView {
+  /** The prepared batch while it holds an approval not spent yet. */
+  approvedBlobId?: string;
+  sent?: SentPodBatch;
+  confirmed?: { podDid: string; txHash: string };
+}
+
+export type CardClaim =
+  | { status: 'ok'; podDid: string; sent: SentPodBatch }
+  | { status: 'no-pod' }
+  | { status: 'claimed'; state: 'sending' | 'added' };
+
 /** Resolves the create-session store for one request (it lives in the user's database). */
 export type CreateSessionStoreFor = (ctx: RuntimeContext) => CreateSessionStore;
 
@@ -54,11 +102,25 @@ export type ApproveOutcome = 'approved' | 'not-prepared' | 'same-request';
 /** `ctx.kv` namespace holding one create session per (user, thread). */
 export const CREATE_SESSION_NAMESPACE = 'pod-creator/create-sessions';
 
+const sentSchema = z.object({
+  messages: z.array(ITrxMsgSchema),
+  profile: z.object({
+    name: z.string(),
+    description: z.string().optional(),
+  }),
+});
+
 const createSessionSchema = z.object({
   preparedBlobId: z.string(),
   /** The request (turn) that prepared the batch. */
   preparedRequestId: z.string(),
   approved: z.boolean(),
+  /** What the last sign request of the prepared batch carried. */
+  sent: sentSchema.optional(),
+  /** The POD confirmed from `sent`. */
+  confirmed: z.object({ podDid: z.string(), txHash: z.string() }).optional(),
+  /** The confirmed POD's domain card: being added (claimed), or added. */
+  card: z.enum(['sending', 'added']).optional(),
 });
 
 type CreateSession = z.infer<typeof createSessionSchema>;
@@ -156,6 +218,7 @@ export class KvCreateSessionStore implements CreateSessionStore {
     userDid: string,
     threadId: string,
     blobId: string,
+    sent?: SentPodBatch,
   ): Promise<boolean> {
     let spent = false;
     await this.kv.update(
@@ -167,13 +230,102 @@ export class KvCreateSessionStore implements CreateSessionStore {
           session !== undefined &&
           session.preparedBlobId === blobId &&
           session.approved;
-        return session && spent ? { ...session, approved: false } : session;
+        if (!session || !spent) return session;
+        return {
+          ...session,
+          approved: false,
+          ...(sent !== undefined ? { sent } : {}),
+        };
       },
       this.writeOptions,
     );
     return spent;
   }
 
+  async read(
+    userDid: string,
+    threadId: string,
+  ): Promise<CreateSessionView | undefined> {
+    const session = parseSession(
+      await this.kv.get(CREATE_SESSION_NAMESPACE, key(userDid, threadId)),
+    );
+    if (!session) return undefined;
+    return {
+      ...(session.approved ? { approvedBlobId: session.preparedBlobId } : {}),
+      ...(session.sent ? { sent: session.sent } : {}),
+      ...(session.confirmed ? { confirmed: session.confirmed } : {}),
+    };
+  }
+
+  async confirmed(
+    userDid: string,
+    threadId: string,
+    pod: { podDid: string; txHash: string },
+  ): Promise<void> {
+    await this.kv.update(
+      CREATE_SESSION_NAMESPACE,
+      key(userDid, threadId),
+      (current) => {
+        const session = parseSession(current);
+        if (!session?.sent) return session;
+        // The card belongs to the POD: another confirmed POD starts afresh.
+        const samePod = session.confirmed?.podDid === pod.podDid;
+        const { card: _card, ...rest } = session;
+        return {
+          ...(samePod ? session : rest),
+          confirmed: { podDid: pod.podDid, txHash: pod.txHash },
+        };
+      },
+      this.writeOptions,
+    );
+  }
+
+  async claimCard(userDid: string, threadId: string): Promise<CardClaim> {
+    let claim: CardClaim = { status: 'no-pod' };
+    await this.kv.update(
+      CREATE_SESSION_NAMESPACE,
+      key(userDid, threadId),
+      (current) => {
+        const session = parseSession(current);
+        if (!session?.confirmed || !session.sent) {
+          claim = { status: 'no-pod' };
+          return session;
+        }
+        if (session.card) {
+          claim = { status: 'claimed', state: session.card };
+          return session;
+        }
+        claim = {
+          status: 'ok',
+          podDid: session.confirmed.podDid,
+          sent: session.sent,
+        };
+        return { ...session, card: 'sending' };
+      },
+      this.writeOptions,
+    );
+    return claim;
+  }
+
+  async settleCard(
+    userDid: string,
+    threadId: string,
+    outcome: 'added' | 'released',
+  ): Promise<void> {
+    await this.kv.update(
+      CREATE_SESSION_NAMESPACE,
+      key(userDid, threadId),
+      (current) => {
+        const session = parseSession(current);
+        if (!session || session.card !== 'sending') return session;
+        if (outcome === 'added') return { ...session, card: 'added' };
+        const { card: _card, ...rest } = session;
+        return rest;
+      },
+      this.writeOptions,
+    );
+  }
+
   async clear(userDid: string, threadId: string): Promise<void> {
     await this.kv.delete(CREATE_SESSION_NAMESPACE, key(userDid, threadId));
   }