@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/canister-studio/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "canister-studio",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "tsc --noEmit && vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "gen": "meant gen did/icrc1.did did/icp_ledger.did did/ckbtc_minter.did -o src/canisters",
+    "gen:check": "meant gen did/icrc1.did did/icp_ledger.did did/ckbtc_minter.did -o src/canisters --check",
+    "smoke": "node scripts/smoke.ts"
+  },
+  "dependencies": {
+    "@meantjs/cli": "0.5.1",
+    "@meantjs/schema": "0.6.0",
+    "@ic-reactor/core": "^4.1.1",
+    "@ic-reactor/react": "^4.1.1",
+    "@icp-sdk/auth": "^10.0.1",
+    "@icp-sdk/core": "^6.1.0",
+    "@noble/curves": "^2.2.0",
+    "@tanstack/react-query": "^5.102.8",
+    "@tanstack/react-router": "^1.170.42",
+    "@tanstack/react-router-ssr-query": "^1.167.3",
+    "@tanstack/react-start": "^1.168.61",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "zod": "^4.6.6"
+  },
+  "devDependencies": {
+    "@ic-reactor/vite-plugin": "^4.1.1",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.3",
+    "@types/node": "^26.5.1",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.1",
+    "jsdom": "30.0.1",
+    "typescript": "^6.0.3",
+    "vite": "^8.3.4",
+    "vitest": "^5.0.0"
+  }
+}

package/examples/canister-studio/scripts/smoke.ts

@@ -0,0 +1,188 @@
+// Mainnet smoke check, never part of `pnpm test`: runs the server's live
+// interface loader against real canisters, calls one through the interface
+// it compiled, checks each committed .did against the interface its canister
+// publishes today, and reads the typed canisters through the generated
+// modules. Node strips the types itself (22.18 or newer): no bundler, no
+// loader.
+import assert from "node:assert/strict"
+import { readFile } from "node:fs/promises"
+import { principal, serviceMethods } from "@meantjs/schema"
+import { schemaFromContract } from "@meantjs/schema/contract"
+import { createClient, formatUnits, isReactorError } from "@ic-reactor/core"
+import {
+  actor as minterActor,
+  type Actor as MinterActor,
+} from "../src/canisters/ckbtc_minter.ts"
+import {
+  actor as icrc1Actor,
+  type Actor as Icrc1Actor,
+} from "../src/canisters/icrc1.ts"
+import {
+  compatibilityForDids,
+  loadLiveInterface,
+  moduleForDid,
+  projectionForDid,
+} from "../src/interface/live-candid.server.ts"
+import type { InterfacePayload } from "../src/interface/types.ts"
+import type { DynActor } from "../src/lib/reactor.ts"
+
+// The registry's canisters (src/lib/registry.ts, which imports .did files
+// with Vite's `?raw` and so cannot load in plain Node).
+const TYPED = [
+  { id: "ryjl3-tyaaa-aaaaa-aaaba-cai", did: "did/icp_ledger.did" },
+  { id: "mxzaz-hqaaa-aaaar-qaada-cai", did: "did/icrc1.did" },
+  { id: "ss2fx-dyaaa-aaaar-qacoq-cai", did: "did/icrc1.did" },
+  { id: "mqygn-kiaaa-aaaar-qaadq-cai", did: "did/ckbtc_minter.did" },
+] as const
+const ICP_LEDGER = TYPED[0].id
+const LEDGERS = TYPED.slice(0, 3)
+const CKBTC_LEDGER = TYPED[1].id
+const CKBTC_MINTER = TYPED[3].id
+// No candid:service metadata: its interface comes from the uncertified query.
+const CAP_ROUTER = "lj532-6iaaa-aaaah-qcc7a-cai"
+// candid:service readable by its controllers only.
+const NNS_LIFELINE = "rno2w-sqaaa-aaaaa-aaacq-cai"
+
+type OkPayload = Extract<InterfacePayload, { ok: true }>
+
+function expectOk(p: InterfacePayload): OkPayload {
+  assert.ok(p.ok, p.ok ? "" : `${p.canisterId}: ${p.code}: ${p.message}`)
+  return p
+}
+
+async function timed<T>(work: () => Promise<T>): Promise<[T, number]> {
+  const start = performance.now()
+  const result = await work()
+  return [result, Math.round(performance.now() - start)]
+}
+
+function methodCounts(p: OkPayload): string {
+  const built = schemaFromContract(
+    JSON.parse(p.envelopeJson ?? "null") as unknown
+  )
+  assert.ok(built.ok && built.actor !== undefined, "the envelope does not load")
+  const counts = new Map<string, number>()
+  for (const m of serviceMethods(built.actor).values()) {
+    counts.set(m.mode, (counts.get(m.mode) ?? 0) + 1)
+  }
+  return [...counts].map(([mode, n]) => `${n} ${mode}`).join(", ")
+}
+
+// 1. The ICP ledger through the server loader: cold, then from the cache.
+const [cold, coldMs] = await timed(() => loadLiveInterface(ICP_LEDGER))
+const icp = expectOk(cold)
+assert.deepEqual(icp.source.kind, "metadata")
+assert.equal(icp.cache, "miss")
+const [warm, warmMs] = await timed(() => loadLiveInterface(ICP_LEDGER))
+assert.equal(expectOk(warm).cache, "hit")
+console.log(
+  `ICP ledger     certified metadata, ${icp.did.length} B .did, ${icp.envelopeJson?.length} B envelope; ${methodCounts(icp)}`
+)
+console.log(
+  `               cold ${coldMs} ms, warm ${warmMs} ms (cache ${warm.ok ? warm.cache : "-"})`
+)
+
+// 2. The server's other compile steps over the .did it read.
+const module = await moduleForDid(icp.did)
+assert.ok(module.ok, module.ok ? "" : module.message)
+const projection = await projectionForDid(icp.did, [
+  "icrc1_symbol",
+  "icrc1_balance_of",
+])
+assert.ok(projection.ok, projection.ok ? "" : projection.message)
+console.log(
+  `               module ${module.module.length} B; projection of ${projection.methods.join(", ")}: ${projection.did.length} B`
+)
+
+// 3. A read through the compiled interface, built as the method runner
+// builds it: the query options of a `Canister<DynActor>`, no arguments
+// (`vars` undefined).
+const client = createClient({ network: "ic", identity: "anonymous" })
+const live = schemaFromContract(
+  JSON.parse(icp.envelopeJson ?? "null") as unknown
+)
+assert.ok(live.ok && live.actor !== undefined)
+const ledger = client.canister<DynActor>(live.actor, { id: ICP_LEDGER })
+const symbol = await client.queryClient.fetchQuery(
+  client.queryOptions(ledger, "icrc1_symbol", undefined)
+)
+assert.equal(symbol, "ICP")
+console.log(
+  `               icrc1_symbol() through the live interface: ${String(symbol)}`
+)
+
+// 4. The fallbacks and refusals.
+const cap = expectOk(await loadLiveInterface(CAP_ROUTER))
+assert.deepEqual(cap.source.kind, "tmp_hack")
+assert.equal(cap.source.kind === "tmp_hack" && cap.source.certified, false)
+console.log(
+  `CAP router     tmp_hack, UNCERTIFIED, ${cap.did.length} B; ${methodCounts(cap)}`
+)
+for (const [id, code] of [
+  [NNS_LIFELINE, "private_interface"],
+  ["aaaaa-aa", "management_canister"],
+  ["2vxsx-fae", "not_a_canister"],
+  ["ryjl3-tyaaa-aaaaa-aaaba-caj", "invalid_canister_id"],
+] as const) {
+  const p = await loadLiveInterface(id)
+  assert.ok(
+    !p.ok && p.code === code,
+    `${id}: expected ${code}, got ${p.ok ? "ok" : p.code}`
+  )
+  console.log(`${id.padEnd(28)} ${p.code}`)
+}
+
+// 5. Each committed .did against the live, certified candid:service.
+for (const { id, did } of TYPED) {
+  const payload = expectOk(await loadLiveInterface(id))
+  const written = await readFile(new URL(`../${did}`, import.meta.url), "utf8")
+  const report = await compatibilityForDids(written, payload.did)
+  assert.ok(report.ok, report.ok ? "" : `${did} vs ${id}: ${report.message}`)
+  console.log(
+    `${did.padEnd(20)} vs ${id}: ${report.compatible ? "compatible" : "INCOMPATIBLE"} (cache ${payload.cache})`
+  )
+  assert.ok(report.compatible, JSON.stringify(report.diagnostics))
+}
+
+// 6. The ledgers' metadata through the generated icrc1 module.
+for (const { id } of LEDGERS) {
+  const typed = client.canister<Icrc1Actor>(icrc1Actor, { id })
+  const [sym, decimals, fee, supply] = await Promise.all([
+    typed.icrc1_symbol(),
+    typed.icrc1_decimals(),
+    typed.icrc1_fee(),
+    typed.icrc1_total_supply(),
+  ])
+  console.log(
+    `${sym.padEnd(6)} decimals ${decimals}, fee ${formatUnits(fee, decimals)}, supply ${formatUnits(supply, decimals)}`
+  )
+  assert.equal(typeof supply, "bigint")
+}
+
+// 7. The minter's info, a query of the full ckbtc_minter module.
+const minter = client.canister<MinterActor>(minterActor, { id: CKBTC_MINTER })
+const info = await minter.get_minter_info()
+console.log(`ckBTC minter   min retrieval ${info.retrieve_btc_min_amount} sat`)
+assert.equal(typeof info.retrieve_btc_min_amount, "bigint")
+
+// 8. The client is anonymous: it refuses a transfer before sending anything.
+try {
+  await client
+    .canister<Icrc1Actor>(icrc1Actor, { id: CKBTC_LEDGER })
+    .icrc1_transfer({
+      to: { owner: principal("rrkah-fqaaa-aaaaa-aaaaq-cai"), subaccount: null },
+      amount: 1n,
+      fee: null,
+      memo: null,
+      from_subaccount: null,
+      created_at_time: null,
+    })
+  assert.fail("an anonymous client sent a transfer")
+} catch (error) {
+  assert.ok(isReactorError(error))
+  assert.equal(error.kind, "unauthenticated")
+  console.log("transfer       refused:", error.kind, error.code)
+}
+
+client.dispose()
+console.log("ok")

package/examples/canister-studio/src/calls/CacheKeyPanel.tsx

@@ -0,0 +1,104 @@
+import type { QueryKey } from "@tanstack/react-query"
+import type { JSX } from "react"
+
+export interface CacheKeyPanelProps {
+  /** The read's key, as `client.queryKey()` / `readQueryOptions()` build it. */
+  queryKey: QueryKey
+  /** TanStack Query's view of that key, when the panel shows a live read. */
+  status?: "pending" | "success" | "error"
+  fetching?: boolean
+}
+
+// `["ic-reactor", network, caller, canisterId, method, args…]`, plus
+// "certified" for the certified twin. The positions are ic-reactor's; the
+// panel only names them.
+
+interface Segment {
+  readonly name: string
+  readonly value: string
+  readonly note?: string
+}
+
+function segmentsOf(key: QueryKey): Segment[] {
+  const parts = key.map((part) =>
+    typeof part === "string" ? part : JSON.stringify(part)
+  )
+  const [root, network, caller, canister, method, ...rest] = parts
+  const segments: Segment[] = []
+  const push = (name: string, value: string | undefined, note?: string) => {
+    if (value !== undefined) segments.push({ name, value, note })
+  }
+  push("root", root)
+  push("network", network)
+  push(
+    "caller",
+    caller,
+    "Each principal has its own entries: one caller's answer is never served to another."
+  )
+  push("canister", canister)
+  push("method", method)
+  const certified = rest[rest.length - 1] === "certified"
+  const args = certified ? rest.slice(0, -1) : rest
+  if (args[0] === "$skip") {
+    push("args", "$skip", "Nothing submitted yet: the read is skipped.")
+  } else if (args[0] === "$invalid") {
+    push("args", args.slice(1).join(" "), "These arguments do not encode.")
+  } else {
+    push("args", args[0], "The hex of the Candid encoding of the arguments.")
+  }
+  if (certified) {
+    push(
+      "certified",
+      "certified",
+      "The certified twin keeps entries of its own."
+    )
+  }
+  return segments
+}
+
+/**
+ * A read's live query key, segment by segment, with the caller segment
+ * highlighted: the key is how ic-reactor keeps principals apart in one
+ * cache, and why nothing writes it by hand.
+ */
+export function CacheKeyPanel(props: CacheKeyPanelProps): JSX.Element {
+  const segments = segmentsOf(props.queryKey)
+  return (
+    <details className="disclosure call-cache" open>
+      <summary>
+        Query key
+        {props.status !== undefined && (
+          <span className="badge">
+            {props.fetching === true ? "fetching" : props.status}
+          </span>
+        )}
+      </summary>
+      <div className="disclosure-body">
+        <ol className="list-plain call-key" aria-label="Query key segments">
+          {segments.map((segment) => (
+            <li
+              key={segment.name}
+              className={
+                segment.name === "caller"
+                  ? "call-key-segment call-key-caller"
+                  : "call-key-segment"
+              }
+            >
+              <span className="call-key-name">{segment.name}</span>
+              <code className="call-key-value mono break-all">
+                {segment.value}
+              </code>
+              {segment.note !== undefined && (
+                <span className="call-key-note subtle">{segment.note}</span>
+              )}
+            </li>
+          ))}
+        </ol>
+        <p className="text-xs muted">
+          Built by <code className="code-inline">client.queryKey()</code>, never
+          by hand: a key written by hand leaves the caller out.
+        </p>
+      </div>
+    </details>
+  )
+}

package/examples/canister-studio/src/calls/ConfirmWrite.tsx

@@ -0,0 +1,265 @@
+import { useEffect, useId, useRef, type JSX, type KeyboardEvent } from "react"
+import { ModeBadge } from "../components/Badge.tsx"
+import { MODE_LABEL } from "../components/modes.ts"
+import type { CanisterInterface, MethodInfo } from "../interface/types.ts"
+import { formatByteSize, formatNanos } from "../lib/format.ts"
+import { toHex } from "../lib/hex.ts"
+import { candidArgsText } from "../values/candid-text.ts"
+import { useSha256 } from "../values/use-sha256.ts"
+import {
+  createdAtNanos,
+  createdAtTimeOf,
+  dedupeShapeOf,
+  duplicateTagOf,
+  knownDeduplicating,
+} from "./dedupe.ts"
+import { sameBytes } from "./prepare.ts"
+
+/** A send whose outcome is unknown: its exact argument bytes and its sender. */
+export interface EarlierSend {
+  readonly bytes: Uint8Array
+  readonly caller: string
+}
+
+export interface ConfirmWriteProps {
+  iface: CanisterInterface
+  method: MethodInfo
+  values: readonly unknown[]
+  /** The exact encoded argument bytes that will be sent. */
+  bytes: Uint8Array
+  /** The sender's principal text. */
+  caller: string
+  /**
+   * Earlier sends of this method whose outcome is still unknown, with the
+   * sender each went out as: the step says how this write relates to them.
+   */
+  earlierUnknown?: readonly EarlierSend[]
+  /** A write is in flight: the step cannot send another until it settles. */
+  busy?: boolean
+  onConfirm(): void
+  onCancel(): void
+}
+
+function argsText(
+  method: MethodInfo,
+  values: readonly unknown[]
+): string | undefined {
+  try {
+    return candidArgsText(method.args, values, { width: 80 })
+  } catch {
+    // The hex below is the exact message either way.
+    return undefined
+  }
+}
+
+function DedupeLine(props: {
+  iface: CanisterInterface
+  method: MethodInfo
+  values: readonly unknown[]
+}) {
+  const shape = dedupeShapeOf(props.method)
+  if (shape === undefined) {
+    return (
+      <>
+        None: this method has no{" "}
+        <code className="code-inline">created_at_time</code>. If the reply is
+        lost, nothing can safely send it again.
+      </>
+    )
+  }
+  const nanos = createdAtNanos(createdAtTimeOf(props.values[0]))
+  if (nanos === undefined) {
+    return (
+      <>
+        Off: <code className="code-inline">created_at_time</code> is empty, so a
+        re-send would be a second write.
+      </>
+    )
+  }
+  const tag = <code className="code-inline">{duplicateTagOf(shape)}</code>
+  return (
+    <>
+      <code className="code-inline">created_at_time</code> ={" "}
+      {formatNanos(nanos)} (<span className="mono">{nanos.toString()}</span>{" "}
+      ns).{" "}
+      {knownDeduplicating(props.iface, props.method) ? (
+        <>The same bytes sent again by the same sender answer {tag}.</>
+      ) : (
+        <>
+          If this canister deduplicates on it, as ICRC-1 ledgers do, the same
+          bytes sent again by the same sender answer {tag}; otherwise sending
+          them again runs the call again.
+        </>
+      )}
+    </>
+  )
+}
+
+/**
+ * The warning of a write sent while earlier sends of the method may have
+ * executed. Only the same bytes, carrying a created_at_time, from the same
+ * sender can be told apart from a new write: anything else runs as well if
+ * one of them ran.
+ */
+function EarlierUnknown(props: {
+  iface: CanisterInterface
+  method: MethodInfo
+  values: readonly unknown[]
+  bytes: Uint8Array
+  caller: string
+  earlier: readonly EarlierSend[]
+}) {
+  const { iface, method, values, bytes, caller, earlier } = props
+  const shape = dedupeShapeOf(method)
+  const stamped = shape !== undefined && createdAtTimeOf(values[0]) !== null
+  const sameArgs = earlier.filter((sent) => sameBytes(sent.bytes, bytes))
+  const one = earlier.length === 1
+  const ranToo = `If ${one ? "that one" : "one of them"} ran, this runs as well. Read the state back first when unsure.`
+  let text: string
+  if (sameArgs.length === 0) {
+    text = `This is a new write, with other bytes${stamped ? " and its own created_at_time" : ""}: the canister does not take it for a re-send of ${one ? "the earlier one" : "those"}. ${ranToo}`
+  } else if (!stamped) {
+    text = `These are the exact bytes of an earlier send whose outcome is unknown, but ${shape === undefined ? "this method has no created_at_time" : "they carry no created_at_time"}: the canister has nothing to deduplicate on, so sending them again runs the write again. ${ranToo}`
+  } else if (!sameArgs.some((sent) => sent.caller === caller)) {
+    text = `These are the exact bytes of an earlier send whose outcome is unknown, but that one went out as ${sameArgs[0]!.caller} and this goes out as ${caller}: a canister that deduplicates tells senders apart, so it does not take this for a re-send. ${ranToo}`
+  } else {
+    const tag = duplicateTagOf(shape)
+    text = knownDeduplicating(iface, method)
+      ? `These are the exact bytes of an earlier send whose outcome is unknown, from the same sender: the canister answers ${tag} if that one ran, and runs this one only if it did not.`
+      : `These are the exact bytes of an earlier send whose outcome is unknown, from the same sender. If this canister deduplicates them, as ICRC-1 ledgers do, it answers ${tag} if that one ran; otherwise it runs the call again.`
+  }
+  return (
+    <div
+      className="notice notice-danger call-confirm-earlier"
+      role="note"
+      aria-label="Earlier send unknown"
+    >
+      <p className="notice-title">
+        {one
+          ? "An earlier send of this method may have executed"
+          : `${earlier.length} earlier sends of this method may have executed`}
+      </p>
+      <p>{text}</p>
+    </div>
+  )
+}
+
+/**
+ * The confirm step before a write: sender, target, method, Candid text, byte
+ * size and sha256 of the exact bytes, and "may execute once".
+ */
+export function ConfirmWrite(props: ConfirmWriteProps): JSX.Element {
+  const { iface, method, values, bytes, caller, onConfirm, onCancel } = props
+  const earlier = props.earlierUnknown ?? []
+  const busy = props.busy === true
+  const titleId = useId()
+  const titleRef = useRef<HTMLHeadingElement>(null)
+  const sha = useSha256(bytes)
+  const candid = argsText(method, values)
+  const oneway = method.mode === "oneway"
+
+  // Keyboard and screen reader users land on the step that just opened.
+  useEffect(() => {
+    titleRef.current?.focus()
+  }, [])
+
+  const onKeyDown = (event: KeyboardEvent<HTMLElement>) => {
+    if (event.key === "Escape") {
+      event.stopPropagation()
+      onCancel()
+    }
+  }
+
+  return (
+    <section
+      className="card call-confirm"
+      aria-labelledby={titleId}
+      onKeyDown={onKeyDown}
+    >
+      <div className="card-header">
+        <h3 id={titleId} ref={titleRef} tabIndex={-1} className="card-title">
+          Confirm this {MODE_LABEL[method.mode]}
+        </h3>
+        <ModeBadge mode={method.mode} />
+      </div>
+      <div className="card-body stack">
+        {earlier.length > 0 && (
+          <EarlierUnknown
+            iface={iface}
+            method={method}
+            values={values}
+            bytes={bytes}
+            caller={caller}
+            earlier={earlier}
+          />
+        )}
+        <dl className="kv">
+          <dt>Sender</dt>
+          <dd className="mono break-all" data-testid="confirm-sender">
+            {caller}
+          </dd>
+          <dt>Target</dt>
+          <dd>
+            {iface.name}{" "}
+            <span className="mono break-all">{iface.canisterId}</span>
+          </dd>
+          <dt>Method</dt>
+          <dd className="mono break-all">{method.name}</dd>
+          <dt>Arguments</dt>
+          <dd>
+            {candid === undefined ? (
+              <span className="muted">See the exact bytes below.</span>
+            ) : (
+              <pre className="code call-confirm-candid">{candid}</pre>
+            )}
+          </dd>
+          <dt>Size</dt>
+          <dd>
+            {bytes.length < 1024
+              ? `${bytes.length} bytes`
+              : `${formatByteSize(bytes.length)} (${bytes.length} bytes)`}
+          </dd>
+          <dt>SHA-256</dt>
+          <dd className="mono break-all" data-testid="confirm-sha256">
+            {sha ?? "computing…"}
+          </dd>
+          <dt>Deduplication</dt>
+          <dd>
+            <DedupeLine iface={iface} method={method} values={values} />
+          </dd>
+        </dl>
+        <details className="disclosure">
+          <summary>Exact bytes (hex)</summary>
+          <div className="disclosure-body">
+            <pre className="code break-all call-confirm-hex">
+              {toHex(bytes)}
+            </pre>
+          </div>
+        </details>
+        <div className="notice notice-warn" role="note">
+          <p className="notice-title">
+            This may execute once, and only once per send
+          </p>
+          <p>
+            {oneway
+              ? "A oneway call returns no reply and no outcome: once sent, nothing tells you whether it ran."
+              : "The client never re-sends it after a failure that may have run it. If the reply is lost, the outcome is unknown: read the state back before sending it again."}
+          </p>
+        </div>
+      </div>
+      <div className="card-footer row row-end">
+        <button type="button" className="btn" onClick={onCancel}>
+          Cancel
+        </button>
+        <button
+          type="button"
+          className="btn btn-primary"
+          disabled={busy}
+          onClick={onConfirm}
+        >
+          {oneway ? "Send oneway call" : "Send update"}
+        </button>
+      </div>
+    </section>
+  )
+}