@ixo/oracle-runtime-workers 0.22.0 → 0.23.0

package/src/action-proposals/topic-budget.ts

@@ -0,0 +1,84 @@
+import { TopicReadUnavailable, typedTopicError } from './topic-errors';
+import type { TopicMatrixReader } from './topic-matrix';
+export const TOPIC_READ_BUDGET_MS = 10_000;
+export async function withTopicReadBudget<T>(
+  reader: TopicMatrixReader,
+  fetcher: typeof fetch,
+  run: (reader: TopicMatrixReader, fetcher: typeof fetch) => Promise<T>,
+  /** An outer budget (the alarm tick's): its abort ends this read too. */
+  outer?: AbortSignal,
+): Promise<T> {
+  const controller = new AbortController();
+  const deadlineAt = Date.now() + TOPIC_READ_BUDGET_MS;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let rejectDeadline: (error: unknown) => void = () => undefined;
+  const deadline = new Promise<never>((_resolve, reject) => {
+    rejectDeadline = reject;
+    timer = setTimeout(() => {
+      controller.abort();
+      reject(
+        new TopicReadUnavailable(
+          'Topic verification exceeded the ten second budget',
+        ),
+      );
+    }, TOPIC_READ_BUDGET_MS);
+  });
+  const onOuterAbort = () => {
+    controller.abort();
+    rejectDeadline(
+      new TopicReadUnavailable('Topic verification budget expired'),
+    );
+  };
+  if (outer?.aborted) onOuterAbort();
+  else outer?.addEventListener('abort', onOuterAbort, { once: true });
+  const active = () => {
+    if (controller.signal.aborted)
+      throw new TopicReadUnavailable('Topic verification budget expired');
+  };
+  const bounded: TopicMatrixReader = {
+    state: async (room) => {
+      active();
+      const value = await reader.state(room);
+      active();
+      return value;
+    },
+    event: async (room, id, opts) => {
+      active();
+      const value = await reader.event(room, id, {
+        ...opts,
+        deadlineAt: Math.min(opts?.deadlineAt ?? Infinity, deadlineAt),
+      });
+      active();
+      return value;
+    },
+    history: async (room, root, opts) => {
+      active();
+      const value = await reader.history(room, root, {
+        ...opts,
+        deadlineAt: Math.min(opts?.deadlineAt ?? Infinity, deadlineAt),
+      });
+      active();
+      return value;
+    },
+  };
+  const fetchBounded: typeof fetch = (input, init) => {
+    active();
+    return fetcher(input, { ...init, signal: controller.signal }).then(
+      (response) => {
+        active();
+        return response;
+      },
+    );
+  };
+  try {
+    return await Promise.race([run(bounded, fetchBounded), deadline]);
+  } catch (error) {
+    // The budget is where every authority read ends: whatever leaves it is
+    // a conflict, unavailable, or a bug.
+    throw typedTopicError(error);
+  } finally {
+    if (timer) clearTimeout(timer);
+    outer?.removeEventListener('abort', onOuterAbort);
+    controller.abort();
+  }
+}

package/src/action-proposals/topic-chain.ts

@@ -0,0 +1,272 @@
+import protobuf from 'protobufjs/minimal.js';
+import { z } from 'zod';
+import {
+  QueryEntityRequest,
+  QueryEntityResponse,
+  QueryParamsRequest,
+  QueryParamsResponse,
+} from '@ixo/impactxclient-sdk/module/codegen/ixo/entity/v1beta1/query.js';
+import {
+  QueryCollectionRequest,
+  QueryCollectionResponse,
+} from '@ixo/impactxclient-sdk/module/codegen/ixo/claims/v1beta1/query.js';
+import {
+  QueryGrantsRequest,
+  QueryGrantsResponse,
+} from '@ixo/impactxclient-sdk/module/codegen/cosmos/authz/v1beta1/query.js';
+import {
+  QuerySmartContractStateRequest,
+  QuerySmartContractStateResponse,
+} from '@ixo/impactxclient-sdk/module/codegen/cosmwasm/wasm/v1/query.js';
+import { IxoAddressSchema } from '@ixo/ixo-transaction/action-proposals';
+import { boundedBytes } from '../core/domain-context/transport';
+import { digestTopicProposalEffect } from './topic-store';
+import { ActionProposalConflict } from './store';
+import { TopicReadUnavailable } from './topic-errors';
+import { chainNetwork } from './verify';
+const encode64 = (v: Uint8Array) =>
+  btoa(Array.from(v, (c) => String.fromCharCode(c)).join(''));
+const decode64 = (v: string) =>
+  Uint8Array.from(atob(v), (c) => c.charCodeAt(0));
+const hex = (v: Uint8Array) =>
+  Array.from(v, (c) => c.toString(16).padStart(2, '0')).join('');
+export class TopicChainReader {
+  constructor(
+    private readonly rpc: string,
+    private readonly chainId: string,
+    private readonly fetcher: typeof fetch = fetch,
+  ) {}
+  private async request(path: string) {
+    const base = new URL(this.rpc);
+    if (
+      base.protocol !== 'https:' ||
+      base.username ||
+      base.password ||
+      base.search ||
+      base.hash
+    )
+      throw new TopicReadUnavailable('Invalid trusted RPC');
+    const res = await this.fetcher(
+      new URL(path, `${base.href.replace(/\/$/, '')}/`),
+      { redirect: 'error', signal: AbortSignal.timeout(10000) },
+    );
+    if (!res.ok) throw new TopicReadUnavailable('Chain authority unavailable');
+    return JSON.parse(
+      new TextDecoder().decode(await boundedBytes(res, 524288)),
+    ) as unknown;
+  }
+  // The node's envelopes are transport: an answer this reader does not
+  // understand is the node failing, not a fact about the chain.
+  // The network an origin serves comes from the per-isolate `/status`
+  // cache the transfer verifier uses (5 minutes), not a read per call.
+  async checkChain() {
+    let network: string;
+    try {
+      network = await chainNetwork(new URL(this.rpc).href, () =>
+        this.request('status'),
+      );
+    } catch (error) {
+      if (error instanceof TopicReadUnavailable) throw error;
+      throw new TopicReadUnavailable('Chain authority unavailable');
+    }
+    if (network !== this.chainId)
+      throw new TopicReadUnavailable('Chain authority mismatch');
+  }
+  private async query(path: string, data: Uint8Array) {
+    const r = z
+      .object({
+        result: z.object({
+          response: z.object({
+            code: z.number().optional(),
+            value: z.string(),
+            height: z.string(),
+          }),
+        }),
+      })
+      .safeParse(
+        await this.request(
+          `abci_query?path=${encodeURIComponent(JSON.stringify(path))}&data=0x${hex(data)}&prove=false`,
+        ),
+      );
+    if (!r.success)
+      throw new TopicReadUnavailable('Chain authority unavailable');
+    const response = r.data.result.response;
+    if (response.code)
+      throw new TopicReadUnavailable('Authoritative chain query failed');
+    return decode64(response.value);
+  }
+  async collection(
+    entityDid: string,
+    collectionId: string,
+    signerAddress: string,
+  ) {
+    await this.checkChain();
+    const entity = QueryEntityResponse.decode(
+      await this.query(
+        '/ixo.entity.v1beta1.Query/Entity',
+        QueryEntityRequest.encode(
+          { id: entityDid },
+          new protobuf.Writer(),
+        ).finish(),
+      ),
+    ).entity;
+    const collection = QueryCollectionResponse.decode(
+      await this.query(
+        '/ixo.claims.v1beta1.Query/Collection',
+        QueryCollectionRequest.encode(
+          { id: collectionId },
+          new protobuf.Writer(),
+        ).finish(),
+      ),
+    ).collection;
+    const params = QueryParamsResponse.decode(
+      await this.query(
+        '/ixo.entity.v1beta1.Query/Params',
+        QueryParamsRequest.encode({}, new protobuf.Writer()).finish(),
+      ),
+    ).params;
+    const admin = entity?.accounts.find((a) => a.name === 'admin');
+    if (
+      !entity ||
+      entity.id !== entityDid ||
+      !collection ||
+      collection.id !== collectionId ||
+      collection.entity !== entityDid ||
+      !admin ||
+      collection.admin !== admin.address ||
+      !params?.nftContractAddress
+    )
+      throw new ActionProposalConflict(
+        'Entity collection and admin binding mismatch',
+      );
+    IxoAddressSchema.parse(admin.address);
+    const smart = QuerySmartContractStateRequest.fromPartial({
+      address: params.nftContractAddress,
+      queryData: new TextEncoder().encode(
+        JSON.stringify({
+          owner_of: { token_id: entityDid, include_expired: false },
+        }),
+      ),
+    });
+    const owner = QuerySmartContractStateResponse.decode(
+      await this.query(
+        '/cosmwasm.wasm.v1.Query/SmartContractState',
+        QuerySmartContractStateRequest.encode(
+          smart,
+          new protobuf.Writer(),
+        ).finish(),
+      ),
+    );
+    const nft = z
+      .object({ owner: IxoAddressSchema })
+      .parse(JSON.parse(new TextDecoder().decode(owner.data)));
+    if (nft.owner !== signerAddress)
+      throw new ActionProposalConflict(
+        'Signing account is not the entity NFT owner',
+      );
+    return {
+      adminAddress: admin.address,
+      dependencies: [
+        {
+          kind: 'entity' as const,
+          key: entityDid,
+          digest: await digestTopicProposalEffect({
+            id: entity.id,
+            accounts: entity.accounts,
+          }),
+        },
+        {
+          kind: 'collection' as const,
+          key: collectionId,
+          digest: await digestTopicProposalEffect({
+            id: collection.id,
+            entity: collection.entity,
+            admin: collection.admin,
+          }),
+        },
+        {
+          kind: 'nft-owner' as const,
+          key: params.nftContractAddress,
+          digest: await digestTopicProposalEffect({
+            entityDid,
+            owner: nft.owner,
+          }),
+        },
+      ],
+    };
+  }
+  async authorization(
+    admin: string,
+    grantee: string,
+    role: 'submit' | 'evaluate',
+  ) {
+    const typeUrl =
+      role === 'submit'
+        ? ('/ixo.claims.v1beta1.SubmitClaimAuthorization' as const)
+        : ('/ixo.claims.v1beta1.EvaluateClaimAuthorization' as const);
+    const messageType =
+      role === 'submit'
+        ? '/ixo.claims.v1beta1.MsgSubmitClaim'
+        : '/ixo.claims.v1beta1.MsgEvaluateClaim';
+    const request = QueryGrantsRequest.fromPartial({
+      granter: admin,
+      grantee,
+      msgTypeUrl: messageType,
+    });
+    const response = QueryGrantsResponse.decode(
+      await this.query(
+        '/cosmos.authz.v1beta1.Query/Grants',
+        QueryGrantsRequest.encode(request, new protobuf.Writer()).finish(),
+      ),
+    );
+    if (response.pagination?.nextKey.length || response.grants.length > 1)
+      throw new ActionProposalConflict(
+        'Authorization query exceeds exact single-grant bound',
+      );
+    const grant = response.grants[0];
+    if (grant?.authorization && grant.authorization.typeUrl !== typeUrl)
+      throw new ActionProposalConflict('Authorization role mismatch');
+    // The grant's expiry on chain covers every constraint in it; the grant
+    // builder refuses to merge into it under another expiry.
+    const expiresAt = (() => {
+      if (!grant?.expiration) return null;
+      const seconds = Number(grant.expiration.seconds.toString());
+      if (!Number.isSafeInteger(seconds))
+        throw new TopicReadUnavailable('Invalid grant expiration');
+      return new Date(
+        seconds * 1000 + grant.expiration.nanos / 1e6,
+      ).toISOString();
+    })();
+    return {
+      existing: grant?.authorization
+        ? {
+            typeUrl,
+            valueBase64: encode64(grant.authorization.value),
+            expiresAt,
+          }
+        : undefined,
+      dependency: {
+        kind: 'authorization' as const,
+        key: `${admin}\0${grantee}\0${role}`,
+        digest: await digestTopicProposalEffect(
+          grant
+            ? {
+                authorization: grant.authorization
+                  ? {
+                      typeUrl: grant.authorization.typeUrl,
+                      valueBase64: encode64(grant.authorization.value),
+                    }
+                  : null,
+                expiration: grant.expiration
+                  ? {
+                      seconds: grant.expiration.seconds.toString(),
+                      nanos: grant.expiration.nanos,
+                    }
+                  : null,
+              }
+            : null,
+        ),
+      },
+    };
+  }
+}

package/src/action-proposals/topic-effects.ts

@@ -0,0 +1,44 @@
+import {
+  materializeCreateStep,
+  TopicCreatePlanSchema,
+} from '@ixo/ixo-transaction/topic-create-plan';
+import {
+  ExpectedTopicEffectSchema,
+  type TopicActionProposal,
+  type TopicStepId,
+  type ExpectedTopicEffect,
+} from '@ixo/ixo-transaction/topic-proposals';
+export const topicIdFromPlan = (plan: unknown): string =>
+  TopicCreatePlanSchema.parse(plan).identity.topicId;
+export async function topicExpectedEffect(
+  proposal: TopicActionProposal,
+  step: TopicStepId,
+): Promise<ExpectedTopicEffect> {
+  const action = proposal.action;
+  if (action.name === 'grant_topic_access') {
+    if (step !== 'grant') throw new Error('Invalid grant step');
+    return {
+      kind: 'chain',
+      chainId: action.chainId,
+      signerAddress: action.signerAddress,
+      memo: action.memo,
+      messages: action.grants.map((g) => g.message),
+    };
+  }
+  if (step === 'grant') throw new Error('Invalid creation step');
+  const verified = (name: TopicStepId) => {
+    const s = proposal.lifecycle.steps.find((s) => s.step === name);
+    return s?.status === 'verified' && s.receipt.kind === 'matrix'
+      ? s.receipt.eventId
+      : undefined;
+  };
+  const effect = await materializeCreateStep(action.plan, step, {
+    rootEventId: verified('anchor'),
+    bodyEventId: verified('body'),
+  });
+  const { step: _step, ...wire } = effect;
+  return ExpectedTopicEffectSchema.parse({
+    ...wire,
+    transactionId: wire.transactionId ?? `${proposal.id}:${step}`,
+  });
+}

package/src/action-proposals/topic-errors.ts

@@ -0,0 +1,79 @@
+import { TopicProtocolError } from '@ixo/topic-protocol';
+import { ZodError } from 'zod';
+import { ActionProposalConflict } from './store';
+
+/**
+ * A room, DID or chain read that failed, timed out or came back oversized.
+ * Nothing about the card or its authority is known to have changed; the
+ * caller retries later. The shell answers it with 503 and a generic message,
+ * the reason stays in the log. Everything the reads DID establish about a
+ * card having changed is an `ActionProposalConflict` (409) instead, and any
+ * other error is a bug that surfaces as one.
+ */
+export class TopicReadUnavailable extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'TopicReadUnavailable';
+  }
+}
+
+/** The failures `boundedBytes` (`core/domain-context/transport`) reports. */
+const TRANSPORT_FAILURES = new Set([
+  'document-unavailable',
+  'document-too-large',
+]);
+
+/**
+ * Every failure leaving an authority read, typed. The readers throw their
+ * own conclusions typed already; what is left is the transport (a fetch
+ * that failed or timed out, a body too large or not JSON) and content an
+ * authority answered with that this contract does not accept (a Zod
+ * refusal of room state, a DID document or a chain query). The first is
+ * unavailable, the second a conflict reported without the schema's issue
+ * dump. Anything else is a bug and is rethrown as it was.
+ */
+export function typedTopicError(
+  error: unknown,
+): ActionProposalConflict | TopicReadUnavailable {
+  if (
+    error instanceof ActionProposalConflict ||
+    error instanceof TopicReadUnavailable
+  )
+    return error;
+  if (
+    error instanceof TopicProtocolError ||
+    (error instanceof Error && error.name === 'TopicProtocolError')
+  ) {
+    // A contract body or operation in the room that the topic protocol
+    // itself rejects: a fact about the authority, reported by its code. The
+    // name check covers a second copy of the package in the bundle.
+    const code =
+      error instanceof TopicProtocolError
+        ? error.code
+        : 'code' in error
+          ? String(error.code)
+          : 'unknown';
+    console.warn(
+      `[topic-actions] authority content rejected by the topic protocol: ${code}`,
+    );
+    return new ActionProposalConflict('Topic authority content is malformed');
+  }
+  if (error instanceof ZodError) {
+    console.warn(
+      `[topic-actions] authority content rejected: ${error.issues
+        .slice(0, 3)
+        .map((i) => `${i.path.join('.')}: ${i.message}`)
+        .join('; ')}`,
+    );
+    return new ActionProposalConflict('Topic authority content is malformed');
+  }
+  if (error instanceof SyntaxError)
+    return new TopicReadUnavailable('Topic authority answer is not JSON');
+  if (
+    error instanceof TypeError ||
+    error instanceof DOMException ||
+    (error instanceof Error && TRANSPORT_FAILURES.has(error.message))
+  )
+    return new TopicReadUnavailable(error.message);
+  throw error;
+}