@ixo/oracle-runtime-workers 0.13.0 → 0.15.0

package/src/plugins/flows/translator.ts

@@ -21,6 +21,7 @@ import type {
 } from '@ixo/editor/core';
 import { canToType, getActionByCan, typeToCan } from '@ixo/editor/core';
 import { FlowError } from './errors';
+import { rewriteRefTokens, wholeRef } from './ref-syntax';
 import type { Condition, FlowSpecInput, FlowStep } from './types';
 
 /** The compiler's block-id convention (verified: `generateBlockId`). */
@@ -49,8 +50,6 @@ const EVALUATOR_TO_OP: Record<string, Condition['is']> = Object.fromEntries(
   ]),
 );
 
-const REF_PATTERN = /^\{\{\s*(.+?)\s*\}\}$/;
-
 /**
  * Data refs cross an id boundary. The agent works in STEP ids
  * ("fill-form.output.answers.did"), but the flow engine resolves a `$ref` by
@@ -84,17 +83,14 @@ function blockRefToStepRef(ref: string): string {
  * are filled downstream against the same block-id-keyed runtime state; they must
  * therefore carry the block id, or every "{{...}}" resolves to an empty string.
  * Non-output tokens (handlebars helpers like `{{#if}}`, `trigger.payload.*`)
- * contain no ".output." and pass through untouched.
+ * contain no ".output." and pass through untouched. The scan is linear in the
+ * string length (ref-syntax.ts), because it runs on document content.
  */
 function rewriteEmbeddedRefs(
   text: string,
   mapRef: (ref: string) => string,
 ): string {
-  return text.replace(
-    /(\{\{\s*)([^{}]+?)(\s*\}\})/g,
-    (_full, open: string, ref: string, close: string) =>
-      `${open}${mapRef(ref)}${close}`,
-  );
+  return rewriteRefTokens(text, mapRef);
 }
 
 /** Resolve a friendly action name (registry `type`) to its `can` ability string. */
@@ -130,8 +126,8 @@ function isRuntimeRef(value: unknown): value is { $ref: string } {
  */
 function friendlyValueToNb(value: unknown): unknown {
   if (typeof value === 'string') {
-    const match = REF_PATTERN.exec(value);
-    if (match?.[1]) return { $ref: stepRefToBlockRef(match[1]) };
+    const ref = wholeRef(value);
+    if (ref) return { $ref: stepRefToBlockRef(ref) };
     return value.includes('{{')
       ? rewriteEmbeddedRefs(value, stepRefToBlockRef)
       : value;
@@ -204,6 +200,7 @@ export function buildConditionsProp(conditions: Condition[]): string {
       name: `Condition from ${c.fromStep}`,
       sourceBlockId: stepIdToBlockId(c.fromStep),
       sourceBlockType: 'action',
+      source: c.source,
       rule: {
         type: 'property_value',
         property: c.field,
@@ -243,6 +240,12 @@ export function parseConditionsProp(
     const friendlyOp = EVALUATOR_TO_OP[String(rule.operator)];
     if (!friendlyOp) continue;
     out.push({
+      // An untagged stored condition is evaluated against runtime output, so
+      // it reads as one and round-trips through update_step unchanged in meaning.
+      source:
+        entry.source === 'configured_input'
+          ? 'configured_input'
+          : 'runtime_output',
       fromStep: resolveStep(sourceBlockId),
       field: String(rule.property),
       is: friendlyOp,

package/src/plugins/flows/types.ts

@@ -9,6 +9,22 @@
  * same shape augmented with a read-only `status`.
  */
 import { z } from 'zod';
+import {
+  MAX_CONDITIONS_PER_STEP,
+  MAX_DESCRIPTION_CHARS,
+  MAX_DID_CHARS,
+  MAX_FLOW_SPEC_BYTES,
+  MAX_FLOW_STEPS,
+  MAX_NAME_CHARS,
+  MAX_SKILLS_PER_STEP,
+  MAX_STEP_ID_CHARS,
+  MAX_STEP_INPUTS,
+  MAX_STEP_INPUTS_BYTES,
+  MAX_STEP_SPEC_BYTES,
+  jsonByteLength,
+  secretLiteralMessage,
+  secretLiteralPaths,
+} from './input-policy';
 
 /**
  * Condition operators, aligned 1:1 with the FE condition evaluator's
@@ -26,11 +42,69 @@ export const CONDITION_OPERATORS = [
   'isNotEmpty',
 ] as const;
 
+const nameSchema = z
+  .string()
+  .max(MAX_NAME_CHARS, `At most ${MAX_NAME_CHARS} characters.`);
+const descriptionSchema = z
+  .string()
+  .max(MAX_DESCRIPTION_CHARS, `At most ${MAX_DESCRIPTION_CHARS} characters.`);
+
+/**
+ * A step id. It is embedded in `{{<id>.output.<field>}}` references and in
+ * block ids, so it may not contain whitespace or braces.
+ */
+export const stepIdSchema = z
+  .string()
+  .min(1)
+  .max(
+    MAX_STEP_ID_CHARS,
+    `A step id is at most ${MAX_STEP_ID_CHARS} characters.`,
+  )
+  .regex(/^[^\s{}]+$/, 'A step id may not contain spaces or braces.');
+
+/** A DID (`did:<method>:<id>`). */
+export const didSchema = z
+  .string()
+  .max(MAX_DID_CHARS, `A DID is at most ${MAX_DID_CHARS} characters.`)
+  .regex(/^did:[a-z0-9]+:\S+$/, 'Must be a DID, e.g. "did:ixo:ixo1…".');
+
+/**
+ * A step's inputs: at most {@link MAX_STEP_INPUTS} names and
+ * {@link MAX_STEP_INPUTS_BYTES} UTF-8 bytes of JSON, and no secret (PIN,
+ * mnemonic, password, token, API key) other than a step-output reference.
+ * Whether that step exists is checked where the flow is known.
+ */
+export const stepInputsSchema = z
+  .record(z.string().max(MAX_NAME_CHARS), z.unknown())
+  .superRefine((inputs, issue) => {
+    if (Object.keys(inputs).length > MAX_STEP_INPUTS)
+      issue.addIssue({
+        code: 'custom',
+        message: `A step may have at most ${MAX_STEP_INPUTS} inputs.`,
+      });
+    if (jsonByteLength(inputs) > MAX_STEP_INPUTS_BYTES)
+      issue.addIssue({
+        code: 'custom',
+        message: `A step's inputs may be at most ${MAX_STEP_INPUTS_BYTES} bytes of JSON.`,
+      });
+    const secrets = secretLiteralPaths(inputs);
+    if (secrets.length > 0)
+      issue.addIssue({
+        code: 'custom',
+        message: secretLiteralMessage(secrets),
+      });
+  });
+
 export const conditionSchema = z.object({
-  fromStep: z
-    .string()
-    .describe('Id of the upstream step whose value is checked.'),
-  field: z.string().describe('Field on the upstream step to inspect.'),
+  source: z
+    .enum(['configured_input', 'runtime_output'])
+    .describe(
+      'Read authored inputs or successful runtime output. Required for newly authored conditions.',
+    ),
+  fromStep: stepIdSchema.describe(
+    'Id of the upstream step whose value is checked.',
+  ),
+  field: nameSchema.describe('Field on the upstream step to inspect.'),
   is: z.enum(CONDITION_OPERATORS).describe('Comparison operator.'),
   value: z
     .unknown()
@@ -38,28 +112,36 @@ export const conditionSchema = z.object({
     .describe('Value to compare against (omit for isEmpty/isNotEmpty).'),
 });
 
+export const semanticGateSchema = z
+  .object({
+    version: z.literal(1),
+    decision: z.literal('flow.gate.semantic'),
+    criterion: z.string().min(1).max(4000),
+    rubric: z.string().min(1).max(4000),
+    inputFields: z.array(z.string().min(1).max(512)).min(1).max(50),
+  })
+  .strict();
+
 export const hookSchema = z.object({
   type: z.enum(['sendEmail', 'addLinkedEntity', 'sendMatrixDM']),
-  config: z.record(z.string(), z.unknown()),
+  config: z.record(z.string().max(MAX_NAME_CHARS), z.unknown()),
 });
 
 export const dueSchema = z.object({
-  at: z.string().optional().describe('Absolute due date (ISO 8601).'),
-  within: z
-    .string()
+  at: nameSchema.optional().describe('Absolute due date (ISO 8601).'),
+  within: nameSchema
     .optional()
     .describe(
       'Duration from when the step becomes active (ISO 8601 duration).',
     ),
-  afterCommitment: z
-    .string()
+  afterCommitment: nameSchema
     .optional()
     .describe('Duration from commitment (ISO 8601 duration).'),
 });
 
 export const onEventSchema = z.object({
-  fromStep: z.string().describe('Upstream step that emits the event.'),
-  event: z.string().describe('Event name the upstream step emits.'),
+  fromStep: stepIdSchema.describe('Upstream step that emits the event.'),
+  event: nameSchema.describe('Event name the upstream step emits.'),
 });
 
 /**
@@ -68,18 +150,15 @@ export const onEventSchema = z.object({
  * is only attached on read (see FlowStepRead).
  */
 export const flowStepSchema = z.object({
-  id: z
-    .string()
-    .min(1)
-    .describe('Stable, human-readable step id, e.g. "load-batches".'),
-  action: z
-    .string()
+  id: stepIdSchema.describe(
+    'Stable, human-readable step id, e.g. "load-batches".',
+  ),
+  action: nameSchema
     .min(1)
     .describe('Action name from list_actions (e.g. "qi/email.send").'),
-  title: z.string().optional(),
-  description: z.string().optional(),
-  phase: z
-    .string()
+  title: nameSchema.optional(),
+  description: descriptionSchema.optional(),
+  phase: nameSchema
     .min(1)
     .optional()
     .describe(
@@ -92,11 +171,11 @@ export const flowStepSchema = z.object({
       'Whether only a person may run this step or a suitably skilled, authorised Flow Agent may run it.',
     ),
 
-  inputs: z
-    .record(z.string(), z.unknown())
+  inputs: stepInputsSchema
     .optional()
     .describe(
-      'Inputs for the action. A value may be a reference to an upstream output, written as "{{step-id.output.field}}".',
+      'Inputs for the action. A value may be a reference to an upstream output, written as "{{step-id.output.field}}". ' +
+        'Never put a PIN, mnemonic, password, token or API key here: the portal collects those when the user runs the step.',
     ),
   form: z
     .record(z.string(), z.unknown())
@@ -106,7 +185,8 @@ export const flowStepSchema = z.object({
     ),
 
   after: z
-    .array(z.string())
+    .array(stepIdSchema)
+    .max(MAX_FLOW_STEPS)
     .optional()
     .describe(
       'Order this step after the named steps. Pair with an input reference for a real data dependency. This is ordering only, not an auto-trigger.',
@@ -114,12 +194,21 @@ export const flowStepSchema = z.object({
   runWhen: conditionSchema
     .optional()
     .describe(
-      'Gate this step on an upstream value (static configuration only).',
+      'Gate this step on an upstream configured input or runtime output.',
     ),
   conditions: z
     .array(conditionSchema)
+    .max(
+      MAX_CONDITIONS_PER_STEP,
+      `A step may have at most ${MAX_CONDITIONS_PER_STEP} conditions.`,
+    )
     .optional()
     .describe('Multiple activation gates (all must pass).'),
+  semanticGate: semanticGateSchema
+    .optional()
+    .describe(
+      'Additional versioned semantic gate; cannot override deterministic conditions or authority.',
+    ),
   onEvent: onEventSchema
     .optional()
     .describe(
@@ -132,12 +221,13 @@ export const flowStepSchema = z.object({
     .describe('When the step runs. Default "manual".'),
   due: dueSchema.optional(),
 
-  assignTo: z
-    .string()
+  assignTo: didSchema
     .optional()
-    .describe('Assignee (a DID or known alias) — metadata only.'),
-  commitTo: z
-    .string()
+    .describe(
+      'The DID assigned to this step. Assigning AUTHORISES that DID to run the step (it is written to the ' +
+        "step's authorised actors) — only assign a DID the user named and confirmed.",
+    ),
+  commitTo: nameSchema
     .optional()
     .describe('Commitment window (ISO 8601 duration).'),
 
@@ -146,7 +236,11 @@ export const flowStepSchema = z.object({
     .optional()
     .describe('Lifecycle hooks: event name -> hooks.'),
   skills: z
-    .array(z.string())
+    .array(nameSchema)
+    .max(
+      MAX_SKILLS_PER_STEP,
+      `A step may require at most ${MAX_SKILLS_PER_STEP} skills.`,
+    )
     .optional()
     .describe(
       'Governed skill ids required for agent-capable execution. The first is used for Flow Agent matching.',
@@ -157,19 +251,50 @@ export const flowStepSchema = z.object({
     .describe('Hint the portal to force a confirmation before this step runs.'),
 });
 
+/**
+ * {@link flowStepSchema} plus the whole-step size cap. A separate schema so
+ * `flowStepSchema` stays a plain object that `.partial()` can derive from.
+ */
+export const sizedFlowStepSchema = flowStepSchema.refine(
+  (step) => jsonByteLength(step) <= MAX_STEP_SPEC_BYTES,
+  `A step may be at most ${MAX_STEP_SPEC_BYTES} bytes of JSON.`,
+);
+
 /**
  * A whole flow as the agent authors it. `ref` is the opaque flow handle; it is
  * omitted on create and assigned by the plugin.
  */
-export const flowSpecSchema = z.object({
-  ref: z
-    .string()
-    .optional()
-    .describe('Opaque flow handle. Omit when creating; the plugin assigns it.'),
-  title: z.string().min(1),
-  goal: z.string().optional(),
-  steps: z.array(flowStepSchema),
-});
+export const flowSpecSchema = z
+  .object({
+    ref: z
+      .string()
+      .optional()
+      .describe(
+        'Opaque flow handle. Omit when creating; the plugin assigns it.',
+      ),
+    title: nameSchema.min(1),
+    goal: descriptionSchema.optional(),
+    steps: z
+      .array(sizedFlowStepSchema)
+      .max(MAX_FLOW_STEPS, `A flow may have at most ${MAX_FLOW_STEPS} steps.`),
+  })
+  .refine(
+    (flow) => jsonByteLength(flow) <= MAX_FLOW_SPEC_BYTES,
+    `A flow may be at most ${MAX_FLOW_SPEC_BYTES} bytes of JSON; build a larger flow step by step with add_step.`,
+  )
+  .superRefine((flow, issue) => {
+    // A secret reference must point at a step of this flow.
+    const stepIds = new Set(flow.steps.map((step) => step.id));
+    flow.steps.forEach((step, index) => {
+      const secrets = secretLiteralPaths(step.inputs ?? {}, stepIds);
+      if (secrets.length > 0)
+        issue.addIssue({
+          code: 'custom',
+          path: ['steps', index, 'inputs'],
+          message: secretLiteralMessage(secrets),
+        });
+    });
+  });
 
 export type Condition = z.infer<typeof conditionSchema>;
 export type FlowStep = z.infer<typeof flowStepSchema>;

package/src/plugins/index.ts

@@ -2,11 +2,16 @@
  * Bundled Workers-runtime plugins — ports of the Node runtime's MCP / fetch
  * plugins. Each is gated the same way as on Node: `autoDetect` on its env
  * key where one exists (memory / sandbox / firecrawl / composio), always-on
- * otherwise (domain-indexer; vfs self-gates on `ctx.ucan.hasSigningKey()`).
+ * otherwise (domain-indexer; vfs self-gates on `ctx.ucan.hasSigningKey()`;
+ * pod-creator is on-demand and stays hidden until `load_capability`).
  *
  * A host opts in by spreading `BUNDLED_WORKERS_PLUGINS` into
  * `createOracleWorker({ plugins })` — plugins whose env keys are absent are
  * skipped by their `autoDetect`.
+ *
+ * Shipped but opt-in (not in the bundle): `IxoTransactionPlugin`, which asks
+ * the user's Portal wallet to sign chain transactions; an oracle adds
+ * `new IxoTransactionPlugin()` itself.
  */
 import type { OraclePlugin } from '../plugin-api/oracle-plugin';
 import { ComposioPlugin } from './composio';
@@ -22,6 +27,7 @@ import { PortalPlugin } from './portal';
 import { AGUIPlugin } from './agui';
 import { AttachmentsPlugin } from './attachments';
 import { MatrixGroupChatsPlugin } from './matrix-group-chats';
+import { PodCreatorPlugin } from './pod-creator';
 
 export * from './composio';
 export * from './editor';
@@ -35,6 +41,8 @@ export * from './vfs';
 export * from './user-preferences';
 export * from './portal';
 export * from './agui';
+export * from './ixo-transaction';
+export * from './pod-creator';
 
 export const memoryPlugin = new MemoryPlugin();
 export const sandboxPlugin = new SandboxPlugin();
@@ -48,6 +56,7 @@ export const portalPlugin = new PortalPlugin();
 export const aguiPlugin = new AGUIPlugin();
 export const attachmentsPlugin = new AttachmentsPlugin();
 export const matrixGroupChatsPlugin = new MatrixGroupChatsPlugin();
+export const podCreatorPlugin = new PodCreatorPlugin();
 /** TasksPlugin is already an object (defineOraclePlugin), not a class. */
 export const tasksPlugin = TasksPlugin;
 
@@ -70,4 +79,5 @@ export const BUNDLED_WORKERS_PLUGINS = [
   aguiPlugin,
   attachmentsPlugin,
   matrixGroupChatsPlugin,
+  podCreatorPlugin,
 ] as const satisfies readonly OraclePlugin[];

package/src/plugins/ixo-transaction/chain-ids.ts

@@ -0,0 +1,43 @@
+/**
+ * The chain id each network's signing requests name, as plugin config. Every
+ * plugin that asks the Portal wallet to sign (`IxoTransactionPlugin`, the POD
+ * creator) declares this same schema object, so one set of variables
+ * configures them all and the env composition does not report the shared
+ * keys as a collision.
+ */
+import {
+  ChainIdSchema,
+  DEFAULT_CHAIN_IDS,
+  type Network,
+} from '@ixo/ixo-transaction';
+import { z } from 'zod';
+
+/**
+ * The defaults are what each network's RPC reports (`DEFAULT_CHAIN_IDS`);
+ * override an entry after a chain upgrade changes the id. The Portal refuses
+ * a request for another chain than its wallet's.
+ */
+export const chainIdConfigSchema = z.object({
+  IXO_TRANSACTION_CHAIN_ID_DEVNET: ChainIdSchema.default(
+    DEFAULT_CHAIN_IDS.devnet,
+  ),
+  IXO_TRANSACTION_CHAIN_ID_TESTNET: ChainIdSchema.default(
+    DEFAULT_CHAIN_IDS.testnet,
+  ),
+  IXO_TRANSACTION_CHAIN_ID_MAINNET: ChainIdSchema.default(
+    DEFAULT_CHAIN_IDS.mainnet,
+  ),
+});
+
+export type ChainIdConfig = z.output<typeof chainIdConfigSchema>;
+
+/** The chain id per network, from the parsed config. */
+export function chainIdsFromConfig(
+  config: ChainIdConfig,
+): Readonly<Record<Network, string>> {
+  return {
+    devnet: config.IXO_TRANSACTION_CHAIN_ID_DEVNET,
+    testnet: config.IXO_TRANSACTION_CHAIN_ID_TESTNET,
+    mainnet: config.IXO_TRANSACTION_CHAIN_ID_MAINNET,
+  };
+}

package/src/plugins/ixo-transaction/index.ts

@@ -0,0 +1,2 @@
+export { IxoTransactionPlugin } from './ixo-transaction.plugin';
+export type { SignIxoTransactionResult } from './tools';

package/src/plugins/ixo-transaction/ixo-transaction.plugin.ts

@@ -0,0 +1,119 @@
+/**
+ * IXO transaction plugin: turns a conversation into a validated IXO chain
+ * transaction and asks the user's Portal wallet to sign it. On demand, and
+ * opt-in — not part of `BUNDLED_WORKERS_PLUGINS`; an oracle adds
+ * `new IxoTransactionPlugin()` to its plugins.
+ *
+ * The catalog, intent routing and validation come from the runtime-neutral
+ * `@ixo/ixo-transaction` package, whose Portal half
+ * (`@ixo/ixo-transaction/react`) answers the `sign_transaction` action.
+ */
+import { z } from 'zod';
+import { OraclePlugin } from '../../plugin-api/oracle-plugin';
+import type {
+  PluginContext,
+  PluginManifest,
+  PluginTool,
+} from '../../plugin-api/types';
+import { chainIdConfigSchema, chainIdsFromConfig } from './chain-ids';
+import { createIxoTransactionTools } from './tools';
+
+/** Default time the user has to sign in their wallet. */
+export const DEFAULT_SIGN_TIMEOUT_MS = 120_000;
+/** Upper bound: well inside the turn's own deadline (`TURN_TIMEOUT_MS`, 10 min by default). */
+export const MAX_SIGN_TIMEOUT_MS = 300_000;
+
+const configSchema = z.object({
+  /**
+   * `'true'` lets mainnet drafts through validation, each still needing a
+   * successful testnet receipt or a recorded override. Off by default: the
+   * oracle prepares testnet (and devnet) transactions only.
+   */
+  IXO_TRANSACTION_ALLOW_MAINNET: z.enum(['true', 'false']).default('false'),
+  /** The chain id each network's requests name (shared with the POD creator). */
+  ...chainIdConfigSchema.shape,
+  /** How long `sign_ixo_transaction` waits for the wallet, in ms. */
+  IXO_TRANSACTION_SIGN_TIMEOUT_MS: z.coerce
+    .number()
+    .int()
+    .positive()
+    .max(MAX_SIGN_TIMEOUT_MS)
+    .default(DEFAULT_SIGN_TIMEOUT_MS),
+});
+
+const manifest: PluginManifest = {
+  title: 'IXO Transaction',
+  summary:
+    'Prepares and validates IXO chain transactions; the user signs them in their Portal wallet.',
+  whenToUse: [
+    'The user wants to create, update, transfer, submit, evaluate, mint or retire on the IXO chain.',
+    'The user types a slash command such as /ixo entity create or /ixo token retire.',
+    'Classify, collect fields, validate, disclose risks, then sign only after explicit consent.',
+  ],
+  whenNotToUse: [
+    'Reading chain state or balances: this plugin only prepares writes.',
+    'Asking the oracle to sign itself: only the user signs, in their wallet.',
+    'Bonds, liquid staking or names: not supported yet.',
+  ],
+  examples: [
+    {
+      user: 'I want to create a new domain',
+      thought:
+        'Resolve the request to a Msg first, then collect its required fields.',
+      tool: 'classify_ixo_transaction_intent',
+      args: { input: 'I want to create a new domain' },
+    },
+    {
+      user: '/ixo token retire',
+      thought:
+        'List the route to see its fields and risks before asking for values.',
+      tool: 'list_ixo_transaction_routes',
+      args: { messageType: 'token' },
+    },
+    {
+      user: 'Yes, I accept that retiring is permanent. Sign it.',
+      thought:
+        "Risks disclosed and accepted in the user's words: send the testnet draft to the wallet.",
+      tool: 'sign_ixo_transaction',
+      args: {
+        command: '/ixo token retire',
+        network: 'testnet',
+        value: {
+          owner: 'ixo1qwertyuiopasdfghjklzxcvbnmqwerty12345',
+          tokens: [{ id: 'CARBON-1', amount: '10' }],
+          jurisdiction: 'ZA',
+          reason: 'Offsetting 2026 travel',
+        },
+        riskConfirmation: {
+          confirmed: true,
+          acceptedRisks: [
+            'Permanently retires (burns) impact credits. Irreversible.',
+          ],
+        },
+      },
+    },
+  ],
+  tags: ['ixo', 'transaction', 'wallet', 'portal', 'cosmos'],
+  category: 'integration',
+  visibility: 'on-demand',
+  stability: 'experimental',
+};
+
+export class IxoTransactionPlugin extends OraclePlugin {
+  readonly name = 'ixo-transaction';
+
+  readonly version = '1.0.0';
+
+  readonly manifest = manifest;
+
+  override readonly configSchema = configSchema;
+
+  override getTools(ctx: PluginContext): PluginTool[] {
+    const config = configSchema.parse(ctx.config);
+    return createIxoTransactionTools({
+      allowMainnet: config.IXO_TRANSACTION_ALLOW_MAINNET === 'true',
+      signTimeoutMs: config.IXO_TRANSACTION_SIGN_TIMEOUT_MS,
+      chainIds: chainIdsFromConfig(config),
+    });
+  }
+}

package/src/plugins/ixo-transaction/receipts.ts

@@ -0,0 +1,99 @@
+/**
+ * Testnet receipts: the oracle's own record that a user signed a transaction
+ * on testnet, which a mainnet draft of the same message must cite.
+ *
+ * Kept in the user's blob store (`ctx.blobStore`, Durable Object storage of
+ * the user's object, scoped to the user's DID). The store hands out its own
+ * random ids and keeps an entry at most 24 hours, so a receipt is cited by
+ * that id plus the transaction hash, and expires a day after the testnet
+ * signing. The model can only cite an id it was given: it cannot make one up,
+ * read another user's, or pass off another plugin's blob (the name is
+ * checked). Any store failure refuses the mainnet draft.
+ */
+import type { ITrxMsg, TestnetReceipt } from '@ixo/ixo-transaction';
+import { z } from 'zod';
+import { operationKey } from '../../core/middlewares/tool-execution';
+import type { RuntimeContext } from '../../plugin-api/types';
+
+export const RECEIPT_NAME_PREFIX = 'ixo-transaction/receipt:';
+/** The blob store's maximum lifetime. */
+export const RECEIPT_TTL_SECONDS = 24 * 60 * 60;
+
+const ReceiptRecordSchema = z
+  .object({
+    transactionHash: z.string(),
+    digest: z.string(),
+    chainId: z.string(),
+  })
+  .strict();
+
+type ReceiptStoreContext = Pick<RuntimeContext, 'blobStore' | 'user'>;
+
+/** SHA-256 of the message's canonical form (typeUrl + canonical value). */
+export function messageDigest(message: ITrxMsg): Promise<string> {
+  return operationKey(message.typeUrl, message.value);
+}
+
+/** Record a signed testnet transaction; returns the receipt to cite. */
+export async function recordTestnetReceipt(
+  ctx: ReceiptStoreContext,
+  signed: { transactionHash: string; message: ITrxMsg; chainId: string },
+): Promise<TestnetReceipt> {
+  const receiptId = await ctx.blobStore.put({
+    userDid: ctx.user.did,
+    name: `${RECEIPT_NAME_PREFIX}${signed.transactionHash}`,
+    value: JSON.stringify({
+      transactionHash: signed.transactionHash,
+      digest: await messageDigest(signed.message),
+      chainId: signed.chainId,
+    }),
+    ttlSeconds: RECEIPT_TTL_SECONDS,
+  });
+  return { transactionHash: signed.transactionHash, receiptId };
+}
+
+/**
+ * Why `receipt` does not prove a testnet signing of `message` by this user
+ * on `testnetChainId`, or null when it does.
+ */
+export async function testnetReceiptProblem(
+  ctx: ReceiptStoreContext,
+  receipt: TestnetReceipt,
+  message: ITrxMsg,
+  testnetChainId: string,
+): Promise<string | null> {
+  const unknown = `Testnet receipt ${receipt.receiptId} is not one this oracle recorded for this user (or it is older than 24 hours): sign the same transaction on testnet and use the testnetReceipt that returns`;
+  if (!ctx.blobStore.isValidBlobId(receipt.receiptId)) return unknown;
+  let entry: { name: string; value: string } | null;
+  try {
+    entry = await ctx.blobStore.get({
+      userDid: ctx.user.did,
+      blobId: receipt.receiptId,
+    });
+  } catch (error) {
+    return `Testnet receipts cannot be checked right now (${error instanceof Error ? error.message : String(error)}), so the mainnet transaction was refused`;
+  }
+  if (!entry) return unknown;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(entry.value);
+  } catch {
+    return unknown;
+  }
+  const record = ReceiptRecordSchema.safeParse(parsed);
+  if (!record.success) return unknown;
+  if (
+    entry.name !== `${RECEIPT_NAME_PREFIX}${receipt.transactionHash}` ||
+    record.data.transactionHash !== receipt.transactionHash
+  ) {
+    return `Testnet receipt ${receipt.receiptId} is not for transaction ${receipt.transactionHash}`;
+  }
+  if (record.data.chainId !== testnetChainId) {
+    return `Testnet receipt ${receipt.receiptId} was signed on ${record.data.chainId}, not on the testnet chain ${testnetChainId}`;
+  }
+  if (record.data.digest !== (await messageDigest(message))) {
+    return `Testnet receipt ${receipt.receiptId} is for a different transaction: the mainnet draft must be the same message that was signed on testnet`;
+  }
+  return null;
+}