@ixo/oracle-runtime-workers 0.41.2 → 0.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.41.2",
+  "version": "0.42.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": {
@@ -67,8 +67,8 @@
     "protobufjs": "^7.6.5",
     "@ixo/topic-protocol": "1.0.0-rc.8",
     "survey-core": "2.3.11",
-    "@ixo/ixo-transaction": "0.2.0",
     "@ixo/common": "1.8.0",
+    "@ixo/ixo-transaction": "0.2.0",
     "@ixo/ucan": "2.3.0",
     "@ixo/action-interactions": "0.1.1"
   },

package/src/attachments/download.ts

@@ -168,7 +168,7 @@ export class HomeserverUnauthorizedError extends Error {
 }
 
 /** `mxc://<server>/<media id>`, the parts checked before they go into a URL. */
-const MXC_PATTERN = /^mxc:\/\/([A-Za-z0-9.:[\]-]+)\/([A-Za-z0-9_-]+)$/;
+export const MXC_PATTERN = /^mxc:\/\/([A-Za-z0-9.:[\]-]+)\/([A-Za-z0-9_-]+)$/;
 
 /**
  * Open the media behind `mxc` on the homeserver as the account behind

package/src/core/middlewares/dangling-tool-calls.ts

@@ -1,17 +1,32 @@
 /**
- * A turn that dies between the model's tool call and the tool's result — the
- * user aborted it, or the runtime was reset while the tool ran — leaves the
- * checkpoint with an assistant message whose `tool_calls` have no
- * `ToolMessage`. OpenRouter chat completions tolerate that history; the
- * ChatGPT-subscription lane (Responses API) rejects every later turn on the
- * session with `400 No tool output found for function call …`. This
- * middleware answers each unanswered call, for the model request only, with
- * a tool result that says the call was interrupted. The checkpoint is left as
- * it is: nothing is rewritten in place, and the model is free to call the
- * tool again.
+ * Every provider's request converter needs each assistant message's
+ * `tool_calls` answered by the tool messages that directly follow it. Two
+ * histories break that, and this middleware mends both for the model request
+ * only (the checkpoint is left as it is: nothing is rewritten in place):
+ *
+ * - Messages a sub-agent forwarded into the chat (`forwardTools`, marked with
+ *   `forwardedFrom`) are left out: they are for the UI, and the parent call's
+ *   own result is what the model reads.
+ * - A result that arrived later. A sub-agent that forwards its own tool calls
+ *   (`forwardTools`, `subagent-as-tool.ts`) hands back a `Command` whose
+ *   forwarded assistant and tool messages come before the parent call's own
+ *   result, so that result lands after them; with parallel calls, after
+ *   another call's forwarded messages too. The result is moved up to its
+ *   call. Before this, such a call read as interrupted and the model was told
+ *   "nothing from it was recorded, call it again" for every sub-agent call
+ *   that forwarded anything.
+ * - A result that never came. A turn that dies between the model's tool call
+ *   and the tool's result (the user aborted it, or the runtime was reset
+ *   while the tool ran) leaves the call unanswered. OpenRouter chat
+ *   completions tolerate that history; the ChatGPT-subscription lane
+ *   (Responses API) rejects every later turn on the session with
+ *   `400 No tool output found for function call …`. Such a call is answered
+ *   with a tool result that says it was interrupted, and the model is free to
+ *   call the tool again.
  */
 import {
   type BaseMessage,
+  HumanMessage,
   isAIMessage,
   isToolMessage,
   ToolMessage,
@@ -30,26 +45,73 @@ export function interruptedToolResult(toolName: string): string {
   return `The call to ${toolName} was interrupted before it returned a result (the turn was aborted or the runtime restarted while it ran), so nothing from it was recorded. Call it again if its result is still needed.`;
 }
 
+/**
+ * `additional_kwargs` key a forwarded sub-agent message carries
+ * (`FORWARDED_FROM_KEY` in `subagent-as-tool.ts`, repeated here so the
+ * middleware does not import the sub-agent wrapper).
+ */
+const FORWARDED_FROM = 'forwardedFrom';
+
+/** The messages without those a sub-agent forwarded into the chat: they are for the UI, not the model. */
+export function withoutForwarded(messages: BaseMessage[]): BaseMessage[] {
+  const kept = messages.filter(
+    (message) =>
+      typeof message.additional_kwargs?.[FORWARDED_FROM] !== 'string',
+  );
+  return kept.length === messages.length ? messages : kept;
+}
+
 export interface DanglingToolCallRepair {
-  /** The original array when nothing was missing, otherwise a repaired copy. */
+  /** The original array when nothing was changed, otherwise a repaired copy. */
   messages: BaseMessage[];
-  /** How many tool calls were answered. */
+  /** How many tool calls were answered as interrupted (no result anywhere). */
   repaired: number;
+  /** How many results were moved up to their call from later in the turn. */
+  regrouped: number;
 }
 
 /**
- * Insert a synthetic `ToolMessage` for every `tool_calls` entry of an
- * assistant message that has no `ToolMessage` among the tool messages that
- * directly follow it. The synthetic results go right after the real ones,
- * before the next non-tool message, which is the position every provider's
- * request converter requires.
+ * The index of the tool message answering `callId` after `from`, before the
+ * next human message (a result never answers a call of an earlier turn), and
+ * not already taken; -1 when there is none.
+ */
+function laterResult(
+  messages: readonly BaseMessage[],
+  from: number,
+  callId: string,
+  taken: ReadonlySet<number>,
+): number {
+  for (let j = from; j < messages.length; j += 1) {
+    const candidate = messages[j]!;
+    if (HumanMessage.isInstance(candidate)) return -1;
+    if (
+      !taken.has(j) &&
+      isToolMessage(candidate) &&
+      candidate.tool_call_id === callId
+    )
+      return j;
+  }
+  return -1;
+}
+
+/**
+ * Answer every `tool_calls` entry of an assistant message right after it:
+ * first with the tool messages that directly follow it, then with its result
+ * from later in the turn (moved up, see the file comment), else with a
+ * synthetic result that says the call was interrupted. Results go before the
+ * next non-tool message, the position every provider's request converter
+ * requires.
  */
 export function repairDanglingToolCalls(
   messages: BaseMessage[],
 ): DanglingToolCallRepair {
   const out: BaseMessage[] = [];
+  /** Indexes of results moved up to their call; skipped where they were. */
+  const taken = new Set<number>();
   let repaired = 0;
+  let regrouped = 0;
   for (let i = 0; i < messages.length; i += 1) {
+    if (taken.has(i)) continue;
     const message = messages[i]!;
     out.push(message);
     if (!isAIMessage(message)) continue;
@@ -59,13 +121,23 @@ export function repairDanglingToolCalls(
     const answered = new Set<string>();
     let next = i + 1;
     while (next < messages.length && isToolMessage(messages[next]!)) {
-      const toolMessage = messages[next] as ToolMessage;
-      answered.add(toolMessage.tool_call_id);
-      out.push(toolMessage);
+      if (!taken.has(next)) {
+        const toolMessage = messages[next] as ToolMessage;
+        answered.add(toolMessage.tool_call_id);
+        out.push(toolMessage);
+      }
       next += 1;
     }
     for (const call of toolCalls) {
       if (!call.id || answered.has(call.id)) continue;
+      const later = laterResult(messages, next, call.id, taken);
+      if (later !== -1) {
+        taken.add(later);
+        answered.add(call.id);
+        out.push(messages[later]!);
+        regrouped += 1;
+        continue;
+      }
       out.push(
         new ToolMessage({
           tool_call_id: call.id,
@@ -78,7 +150,11 @@ export function repairDanglingToolCalls(
     }
     i = next - 1;
   }
-  return { messages: repaired === 0 ? messages : out, repaired };
+  return {
+    messages: repaired === 0 && regrouped === 0 ? messages : out,
+    repaired,
+    regrouped,
+  };
 }
 
 export const createDanglingToolCallRepairMiddleware = (
@@ -88,11 +164,21 @@ export const createDanglingToolCallRepairMiddleware = (
   return createMiddleware({
     name: 'DanglingToolCallRepairMiddleware',
     wrapModelCall: async (request, handler) => {
-      const { messages, repaired } = repairDanglingToolCalls(request.messages);
-      if (repaired === 0) return handler(request);
-      logger.warn(
-        `[DanglingToolCallRepair] ${repaired} tool call(s) had no result in the thread history; answered as interrupted for this model call`,
-      );
+      const visible = withoutForwarded(request.messages);
+      const { messages, repaired, regrouped } =
+        repairDanglingToolCalls(visible);
+      if (repaired === 0 && regrouped === 0)
+        return visible === request.messages
+          ? handler(request)
+          : handler({ ...request, messages });
+      if (repaired > 0)
+        logger.warn(
+          `[DanglingToolCallRepair] ${repaired} tool call(s) had no result in the thread history; answered as interrupted for this model call`,
+        );
+      if (regrouped > 0)
+        logger.debug?.(
+          `[DanglingToolCallRepair] ${regrouped} tool result(s) moved up to their call (forwarded sub-agent messages came between)`,
+        );
       return handler({ ...request, messages });
     },
   });

package/src/core/middlewares/result-cap.ts

@@ -102,7 +102,7 @@ export function capFooter(
   tail: number,
 ): string {
   const where = meta.id
-    ? `The full result is saved as ${meta.id}: call read_result({ id: "${meta.id}", offset: 0 }) and follow \`next\` to read it in chunks.`
+    ? `The full result is saved as ${meta.id}; if your task needs a part that is not shown, read_result({ id: "${meta.id}", offset }) reads it. Do not read it all to check that the call worked.`
     : 'The full result could not be saved.';
   return `\n\n[Result truncated: showing the first ${head} and last ${tail} of ${meta.size} characters. ${where}]`;
 }

package/src/core/read-result-tool.ts

@@ -7,12 +7,17 @@
  * ranges, of a trimmed one character ranges; `next` is the offset of the
  * following chunk or `null` at the end.
  */
-import { ToolMessage, type BaseMessage } from '@langchain/core/messages';
+import {
+  AIMessage,
+  ToolMessage,
+  type BaseMessage,
+} from '@langchain/core/messages';
 import { z } from 'zod';
 import { tool } from '../plugin-api/tool-helper';
 import type { PluginTool } from '../plugin-api/types';
 import type { ReadResultOutcome } from '../do/result-store';
 import { contentToText } from './middlewares/result-cap';
+import { turnStart } from './middlewares/turn-boundary';
 
 export interface ReadResultToolOptions {
   read: (
@@ -26,6 +31,58 @@ export interface ReadResultToolOptions {
 
 export const READ_RESULT_TOOL_NAME = 'read_result';
 
+/**
+ * Reads one turn may make. Paging is for the part of a result a task needs,
+ * not for checking that a call worked: a model that read every chunk of a
+ * saved result (hundreds of characters at a time) spent a turn and two
+ * million tokens on it. Six of the largest chunks cover a result of about
+ * 96,000 characters.
+ */
+export const READ_RESULT_CALLS_PER_TURN = 6;
+
+/** The smallest chunk read: a request for less reads this much, so a turn's reads are never spent on slivers. */
+export const READ_RESULT_MIN_CHARS = 2_000;
+
+/** The result of a read past {@link READ_RESULT_CALLS_PER_TURN}: not run. */
+export function readBudgetSpent(reads: number): string {
+  return `Not read: this turn already read ${reads} chunks, the most one turn may read. Continue with what you have (the head and tail of the result, and each call's own reply, say whether it worked), or tell the person what is still unread.`;
+}
+
+/**
+ * Reads this turn asked for before the call `toolCallId`, counted on the
+ * model's own tool calls so a batch of parallel reads counts each one (their
+ * results are not in the thread yet when they run). Without the call's id
+ * in the thread, the reads that already returned.
+ */
+function readsBefore(
+  messages: readonly BaseMessage[],
+  toolCallId: string | undefined,
+): number {
+  const start = turnStart(messages);
+  if (toolCallId) {
+    let asked = 0;
+    for (let i = start; i < messages.length; i += 1) {
+      const message = messages[i];
+      if (!AIMessage.isInstance(message)) continue;
+      for (const call of message.tool_calls ?? []) {
+        if (call.name !== READ_RESULT_TOOL_NAME) continue;
+        if (call.id === toolCallId) return asked;
+        asked += 1;
+      }
+    }
+  }
+  let returned = 0;
+  for (let i = start; i < messages.length; i += 1) {
+    const message = messages[i];
+    if (
+      ToolMessage.isInstance(message) &&
+      message.name === READ_RESULT_TOOL_NAME
+    )
+      returned += 1;
+  }
+  return returned;
+}
+
 /** The longest chunk `read_result` hands back under a result cap: well under the cap, so a page is never capped itself. */
 export function readResultMaxChars(resultCapChars: number): number {
   return Math.min(16_000, Math.max(512, Math.floor(resultCapChars / 2)));
@@ -51,7 +108,7 @@ export function buildReadResultTool(
   options: ReadResultToolOptions,
 ): PluginTool {
   const maxChars = Math.max(512, Math.min(options.maxChars, 64 * 1024));
-  const defaultChars = Math.min(4_000, maxChars);
+  const minChars = Math.min(READ_RESULT_MIN_CHARS, maxChars);
   const schema = z.object({
     id: z
       .string()
@@ -64,12 +121,19 @@ export function buildReadResultTool(
       .int()
       .min(256)
       .max(maxChars)
-      .default(defaultChars)
-      .describe(`Length to read (max ${maxChars}).`),
+      .default(maxChars)
+      .describe(
+        `Length to read (default and max ${maxChars}; at least ${minChars} is read).`,
+      ),
   });
   return tool(
     async (rawArgs, ctx) => {
-      const { id, offset, length } = schema.parse(rawArgs);
+      const parsed = schema.parse(rawArgs);
+      const reads = readsBefore(ctx.history.messages, ctx.toolCallId);
+      if (reads >= READ_RESULT_CALLS_PER_TURN)
+        return { error: readBudgetSpent(reads) };
+      const { id, offset } = parsed;
+      const length = Math.max(parsed.length, minChars);
       const text = threadResult(ctx.history.messages, id);
       if (text !== undefined) {
         const end = offset + length;
@@ -103,8 +167,7 @@ export function buildReadResultTool(
       name: READ_RESULT_TOOL_NAME,
       effect: 'read',
       visibility: 'always',
-      description:
-        'Read a tool result you no longer have in full, in chunks. Use the id from a "[Result truncated …]" footer or a stub that says the result was removed; start at offset 0 and pass the returned `next` as the offset of the following call until `next` is null.',
+      description: `Read part of a tool result you no longer have in full: the id from a "[Result truncated …]" footer or a stub that says the result was removed. Read only the part your task needs, in large chunks (pass a returned \`next\` as the offset to continue). Never read a result back to check that a call worked: its visible head and tail and the call's own reply say that. At most ${READ_RESULT_CALLS_PER_TURN} reads per turn.`,
       schema,
     },
   );

package/src/core/runtime-context.ts

@@ -95,7 +95,7 @@ export interface MatrixAdapter {
   getRoomState(roomId: string): Promise<RoomStateSnapshot>;
   getEventById(roomId: string, eventId: string): Promise<MatrixEvent>;
   /** See `MatrixGatewayObject.botCredentials`. */
-  botCredentials(): Promise<BotCredentials>;
+  botCredentials(opts?: { rejected?: string }): Promise<BotCredentials>;
   /** Group rooms: room kind and channel memory (see `plugin-api/types.ts`). Hosts without a gateway omit them. */
   roomInfo?: RuntimeContext['matrix']['roomInfo'];
   channelMemory?: RuntimeContext['matrix']['channelMemory'];
@@ -497,7 +497,7 @@ export function buildRuntimeContext<TConfig = MergedConfig>(
     matrix: {
       postToRoom: (roomId, content, opts) =>
         ambient.matrix.postToRoom(roomId, content, opts),
-      botCredentials: () => ambient.matrix.botCredentials(),
+      botCredentials: (opts) => ambient.matrix.botCredentials(opts),
       postEvent: (roomId, eventType, content, opts) =>
         ambient.matrix.postEvent(roomId, eventType, content, opts),
       getRoomState: (roomId) => ambient.matrix.getRoomState(roomId),

package/src/core/subagent-as-tool.ts

@@ -97,6 +97,34 @@ const taskSchema = z.object({
     ),
 });
 
+/** Characters of a sub-agent's last tool result handed back when it ended without a reply. */
+export const SUBAGENT_FALLBACK_RESULT_CHARS = 2_000;
+
+/**
+ * What the parent reads as a sub-agent's result: its final reply, or, when
+ * the sub-agent ended on an empty one (a model that stops right after its
+ * last tool call, such as a POD specialist after `submit_section`), its last
+ * tool result, labelled as such and cut to
+ * {@link SUBAGENT_FALLBACK_RESULT_CHARS}. An empty result leaves the parent
+ * nothing to tell whether the work was done.
+ */
+export function subAgentResultText(
+  messages: BaseMessage[],
+  name: string,
+): string {
+  const text = lastMessageContent(messages).toString();
+  if (text.trim()) return text;
+  const lastTool = messages.findLast((message) =>
+    ToolMessage.isInstance(message),
+  );
+  if (!lastTool) return `${name} finished without a reply.`;
+  const result =
+    typeof lastTool.content === 'string'
+      ? lastTool.content
+      : JSON.stringify(lastTool.content);
+  return `${name} finished without a reply. Its last tool call${lastTool.name ? ` (${lastTool.name})` : ''} returned: ${result.slice(0, SUBAGENT_FALLBACK_RESULT_CHARS)}`;
+}
+
 function lastMessageContent(messages: BaseMessage[]): string {
   const last = messages.at(-1);
   if (!last?.content) return '';
@@ -120,6 +148,18 @@ function lastMessageContent(messages: BaseMessage[]): string {
  * LangChain-generated ids starting at 0, and two invocations in one chat
  * collide — the frontend uses these ids as React keys.
  */
+/**
+ * `additional_kwargs` key on every forwarded message: the parent call it came
+ * from. Forwarded messages are for the chat (the UI renders the sub-agent's
+ * calls); the parent model reads the call's own result instead, so the
+ * dangling-call middleware leaves them out of its requests
+ * (`withoutForwarded`). Without that, the parent model took a forwarded call
+ * for one of its own (it called a specialist's `submit_section` itself) and
+ * read each forwarded call's arguments, a whole POD section, on every model
+ * call of the thread.
+ */
+export const FORWARDED_FROM_KEY = 'forwardedFrom';
+
 export function filterForwardedMessages(
   messages: BaseMessage[],
   forwardTools: Set<string>,
@@ -140,7 +180,13 @@ export function filterForwardedMessages(
         oldToNewId.set(tc.id, newId);
         return { ...tc, id: newId };
       });
-      acc.push(new AIMessage({ content: '', tool_calls: rewritten }));
+      acc.push(
+        new AIMessage({
+          content: '',
+          tool_calls: rewritten,
+          additional_kwargs: { [FORWARDED_FROM_KEY]: idPrefix },
+        }),
+      );
     }
 
     if (msg.type === 'tool') {
@@ -152,6 +198,7 @@ export function filterForwardedMessages(
           content: toolMsg.content,
           tool_call_id: newId,
           ...(toolMsg.name ? { name: toolMsg.name } : {}),
+          additional_kwargs: { [FORWARDED_FROM_KEY]: idPrefix },
         }),
       );
     }
@@ -273,7 +320,7 @@ export function createSubagentAsTool(
     messages: BaseMessage[],
     toolCallId: string,
   ): string | Command => {
-    const text = lastMessageContent(messages).toString();
+    const text = subAgentResultText(messages, spec.name);
     if (forwardSet.size === 0) return text;
 
     const idPrefix = toolCallId || `run_${crypto.randomUUID().slice(0, 8)}`;

package/src/do/ambient.ts

@@ -183,7 +183,8 @@ export function createMatrixAdapter(
       ),
     postEvent: (roomId, eventType, content, opts) =>
       gateway.sendEvent(roomId, eventType, JSON.stringify(content), opts ?? {}),
-    botCredentials: () => gateway.botCredentials(),
+    botCredentials: (opts?: { rejected?: string }) =>
+      gateway.botCredentials(opts?.rejected ? { rejected: opts.rejected } : {}),
     roomInfo: (roomId) => gateway.groupChatRoomInfo(roomId),
     channelMemory: {
       recall: async (roomId, limit) =>

package/src/plugin-api/types.ts

@@ -818,8 +818,11 @@ export interface RuntimeContext<TConfig = MergedConfig> {
     /**
      * Credentials of the oracle's own crypto-less device for plugins that run
      * their own Matrix client (editor, flows). Minted and kept by the gateway.
+     * A caller whose request the homeserver answered 401 passes the token it
+     * used as `rejected`: the host then re-validates the device (or logs it
+     * in again) and answers with fresh credentials, so one retry can succeed.
      */
-    botCredentials: () => Promise<{
+    botCredentials: (opts?: { rejected?: string }) => Promise<{
       baseUrl: string;
       userId: string;
       accessToken: string;
@@ -1317,6 +1320,13 @@ export interface PluginSubAgent {
    *
    * Runtime-injected passthrough tools (e.g. memory CRUD) are never
    * forwarded — they're already on the main agent.
+   *
+   * Forwarded messages are for the chat: they stay in the thread (the UI
+   * and the transcript show them) but are left out of the parent's model
+   * requests. The parent model reads the sub-agent's final reply as the
+   * call's result (its last tool result when that reply is empty), so the
+   * sub-agent's reply must say what it did. Forward the calls the user
+   * should see (a write, its receipt), not large reads.
    */
   forwardTools?: boolean | string[];
   /** Called after sub-agent completes; can emit follow-up events. */

package/src/plugins/domain-indexer/domain-indexer.plugin.ts

@@ -14,7 +14,7 @@ import { createDomainIndexerTools } from './domain-indexer-tools';
  * the core `NETWORK` env var. Operators can override with the optional
  * `DOMAIN_INDEXER_URL` env var (useful for local/staging deployments).
  */
-const DOMAIN_INDEXER_URLS = {
+export const DOMAIN_INDEXER_URLS = {
   mainnet: 'https://domain-indexer.ixo.earth',
   testnet: 'https://domain-indexer.testnet.ixo.earth',
   devnet: 'https://domain-indexer.devnet.ixo.earth',

package/src/plugins/ixo-chain/http.ts

@@ -151,6 +151,8 @@ export interface ChainCall {
   deadline: number;
   signal: AbortSignal;
   fetch: typeof fetch;
+  /** How the call waits before a retry; {@link sleep} unless a test injects its own clock. */
+  sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
 }
 
 /**
@@ -192,7 +194,7 @@ export type Outcome<T> =
   | { ok: false; failure: Failure };
 
 /** The turn's abort reason as an error (a non-error reason becomes an `AbortError`). */
-function abortReason(signal: AbortSignal): Error {
+export function abortReason(signal: AbortSignal): Error {
   return signal.reason instanceof Error
     ? signal.reason
     : new DOMException('Aborted', 'AbortError');
@@ -288,7 +290,7 @@ export class ReadsInFlight<T> {
 }
 
 /** Resolves after `ms`; rejects with the turn's abort reason if it ends first. */
-function sleep(ms: number, signal: AbortSignal): Promise<void> {
+export function sleep(ms: number, signal: AbortSignal): Promise<void> {
   return new Promise((resolve, reject) => {
     if (signal.aborted) {
       reject(abortReason(signal));
@@ -394,7 +396,7 @@ export async function withRetry<T>(
       : { ok: false, failure: first.failure };
   if (!first.retry || Date.now() + wait + MIN_ATTEMPT_MS > call.deadline)
     return giveUp();
-  await sleep(wait, call.signal);
+  await (call.sleep ?? sleep)(wait, call.signal);
   const second = await attempt();
   recordHealth(read.upstream, second);
   if (second.ok) {
@@ -518,7 +520,9 @@ const outOfBudget = (note: string): Attempt<never> => ({
  * The body of an error answer as text, or undefined when it is longer than
  * {@link ERROR_BODY_MAX_BYTES} (the rest is not read).
  */
-async function errorBodyOf(response: Response): Promise<string | undefined> {
+export async function errorBodyOf(
+  response: Response,
+): Promise<string | undefined> {
   const reader = response.body?.getReader();
   if (!reader) return '';
   const decoder = new TextDecoder();

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

@@ -79,12 +79,25 @@ function networkOf(config: MergedConfig): Network {
 
 /** The REST base URL: `CHAIN_REST_URL` when set, else the network's default. */
 export function chainRestUrl(config: MergedConfig): string {
+  return chainRestUrlFor(networkOf(config), config);
+}
+
+/**
+ * The REST base URL for `network`: `CHAIN_REST_URL` when set (the
+ * operator's node for the oracle's network), else that network's default.
+ * For a caller that already knows its network rather than reading
+ * `NETWORK` itself.
+ */
+export function chainRestUrlFor(
+  network: Network,
+  config: MergedConfig,
+): string {
   const override = configSchema.shape.CHAIN_REST_URL.safeParse(
     config.CHAIN_REST_URL,
   );
   return override.success && override.data
     ? override.data
-    : CHAIN_REST_URLS[networkOf(config)];
+    : CHAIN_REST_URLS[network];
 }
 
 /** The names worker's origin: `IXO_NAMES_URL` when set, else the network's default. */

package/src/plugins/ixo-chain/queries.ts

@@ -221,6 +221,32 @@ export function isBech32(address: string, prefix: string): boolean {
   return padding < 5 && (last & ((1 << padding) - 1)) === 0;
 }
 
+/**
+ * The bytes a valid bech32 `address` with the prefix `prefix` carries (for
+ * an account, the 20-byte hash of its public key); null when
+ * {@link isBech32} refuses it.
+ */
+export function bech32Bytes(
+  address: string,
+  prefix: string,
+): Uint8Array | null {
+  if (!isBech32(address, prefix)) return null;
+  const data = address.slice(prefix.length + 1, -BECH32_CHECKSUM);
+  const bytes: number[] = [];
+  let buffer = 0;
+  let bits = 0;
+  for (const char of data) {
+    buffer = (buffer << 5) | BECH32_CHARSET.indexOf(char);
+    bits += 5;
+    if (bits >= 8) {
+      bits -= 8;
+      bytes.push((buffer >>> bits) & 0xff);
+    }
+  }
+  // The leftover bits are the zero padding isBech32 checked.
+  return Uint8Array.from(bytes);
+}
+
 /**
  * The account an account field names: the user's own address when the
  * field is omitted, else an `ixo1…` address or the address a