@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/canister-studio/src/components/provenance.ts

@@ -0,0 +1,38 @@
+import type { InterfaceSource } from "../interface/types.ts"
+
+const MODULE_LABEL: Readonly<
+  Record<Extract<InterfaceSource, { kind: "typed" }>["module"], string>
+> = {
+  icrc1: "icrc1.ts",
+  icp_ledger: "icp_ledger.ts",
+  ckbtc_minter: "ckbtc_minter.ts",
+}
+
+/** What a source can be trusted for, in one line. */
+export function provenanceText(source: InterfaceSource): string {
+  switch (source.kind) {
+    case "typed":
+      return `A committed .did, generated at build time into src/canisters/${MODULE_LABEL[source.module]}: its methods have TypeScript types.`
+    case "metadata":
+      return "The canister's candid:service metadata, read with a certified read_state: the subnet signed it."
+    case "tmp_hack":
+      // A private canister has metadata, readable by its controllers only.
+      return `${source.reason === "private" ? "Its candid:service metadata is readable by its controllers only, so this interface was read" : "No public candid:service metadata: read"} from the __get_candid_interface_tmp_hack query, one replica's answer that nobody certified. The canister could be lying about its interface.`
+    case "pasted":
+      return "A .did pasted here: nothing ties it to any canister."
+  }
+}
+
+/** Where an interface came from, in a few words (the facts table). */
+export function provenanceShort(source: InterfaceSource): string {
+  switch (source.kind) {
+    case "typed":
+      return `Committed .did, typed by src/canisters/${MODULE_LABEL[source.module]}`
+    case "metadata":
+      return "candid:service metadata, certified read_state"
+    case "tmp_hack":
+      return "__get_candid_interface_tmp_hack query, not certified"
+    case "pasted":
+      return "Pasted .did"
+  }
+}

package/examples/canister-studio/src/components/route-render.test.tsx

@@ -0,0 +1,71 @@
+// @vitest-environment node
+// Pages rendered as the server renders them: the app's own router and routes
+// over a test client, so what is checked is the HTML a reader (or curl) gets.
+import { createTestClient } from "@ic-reactor/core/testing"
+import { createMemoryHistory, RouterProvider } from "@tanstack/react-router"
+import { renderToString } from "react-dom/server"
+import { afterEach, describe, expect, it } from "vitest"
+import {
+  actor as icrc1Actor,
+  type Actor as Ledger,
+} from "../canisters/icrc1.ts"
+import { getRouter } from "../router.tsx"
+import { WALLET_LEDGERS } from "./wallet/ledgers.ts"
+
+let test: ReturnType<typeof createTestClient> | undefined
+afterEach(() => {
+  test?.client.dispose()
+  test = undefined
+})
+
+async function renderPage(url: string): Promise<string> {
+  test = createTestClient({ network: "ic", signedIn: false })
+  for (const entry of Object.values(WALLET_LEDGERS)) {
+    test.mock<Ledger>(icrc1Actor, entry.id, {
+      icrc1_name: () => entry.name,
+      icrc1_symbol: () => "TOK",
+      icrc1_decimals: () => 8,
+      icrc1_fee: () => 10n,
+    })
+  }
+  const router = getRouter(test.client)
+  router.update({
+    ...router.options,
+    history: createMemoryHistory({ initialEntries: [url] }),
+  })
+  await router.load()
+  return renderToString(<RouterProvider router={router} />)
+}
+
+/** The labels of the links in `html`'s `nav` of class `navClass` marked current. */
+function currentIn(html: string, navClass: string): string[] {
+  const nav = new RegExp(
+    `<nav[^>]*class="[^"]*${navClass}[^"]*"[^>]*>([\\s\\S]*?)</nav>`
+  ).exec(html)
+  if (nav === null) throw new Error(`no nav .${navClass}`)
+  return [...(nav[1] ?? "").matchAll(/<a([^>]*)>([^<]*)<\/a>/g)]
+    .filter(([, attrs]) => attrs?.includes('aria-current="page"'))
+    .map(([, , label]) => label ?? "")
+}
+
+describe("the wallet's ledger picker", () => {
+  it.each([
+    ["/wallet", "ICP"],
+    ["/wallet?ledger=ckbtc", "ckBTC"],
+    ["/wallet?ledger=cketh", "ckETH"],
+  ])("marks one ledger current on %s", async (url, label) => {
+    expect(currentIn(await renderPage(url), "wallet-ledgers")).toEqual([label])
+  })
+})
+
+describe("the interface tool tabs", () => {
+  const page = "/canister/ryjl3-tyaaa-aaaaa-aaaba-cai/interface"
+  it.each([
+    [page, "Candid"],
+    [`${page}?tab=typescript`, "TypeScript"],
+    [`${page}?tab=project`, "Project"],
+    [`${page}?tab=compatibility`, "Compatibility"],
+  ])("marks one tab current on %s", async (url, label) => {
+    expect(currentIn(await renderPage(url), "iface-tabs")).toEqual([label])
+  })
+})

package/examples/canister-studio/src/components/use-task.ts

@@ -0,0 +1,56 @@
+import { useCallback, useEffect, useRef, useState } from "react"
+
+/** The state of one async task the user started (or a tab started). */
+export type TaskState<T> =
+  | { readonly status: "idle" }
+  | { readonly status: "running" }
+  | { readonly status: "done"; readonly value: T }
+  | { readonly status: "failed"; readonly message: string }
+
+/**
+ * Runs an async task and keeps only the latest run's outcome: a run that
+ * finishes after a newer one started (or after unmount) is dropped. For
+ * one-off server-function calls and lazily loaded tools, not for canister
+ * reads (those go through ic-reactor's query options).
+ */
+export function useTask<T>(): {
+  state: TaskState<T>
+  run(task: () => Promise<T>): void
+  reset(): void
+} {
+  const [state, setState] = useState<TaskState<T>>({ status: "idle" })
+  const latest = useRef(0)
+
+  useEffect(
+    () => () => {
+      // Unmounted: no later setState from a run in flight.
+      latest.current += 1
+    },
+    []
+  )
+
+  const run = useCallback((task: () => Promise<T>) => {
+    const runId = ++latest.current
+    setState({ status: "running" })
+    task().then(
+      (value) => {
+        if (runId === latest.current) setState({ status: "done", value })
+      },
+      (error: unknown) => {
+        if (runId === latest.current) {
+          setState({
+            status: "failed",
+            message: error instanceof Error ? error.message : String(error),
+          })
+        }
+      }
+    )
+  }, [])
+
+  const reset = useCallback(() => {
+    latest.current += 1
+    setState({ status: "idle" })
+  }, [])
+
+  return { state, run, reset }
+}

package/examples/canister-studio/src/components/wallet/BalancePanel.tsx

@@ -0,0 +1,110 @@
+import { isPrincipal } from "@meantjs/schema"
+import { useAuth, useClient } from "@ic-reactor/react"
+import { skipToken, useQuery } from "@tanstack/react-query"
+import { useId, useState, type ReactElement } from "react"
+import { CacheKeyPanel } from "../../calls/CacheKeyPanel.tsx"
+import { formatTokens } from "../../lib/format.ts"
+import type { RegistryEntry } from "../../lib/registry.ts"
+import { ActionButton } from "../ActionButton.tsx"
+import { Notice } from "../Notice.tsx"
+import { Skeleton, Spinner } from "../Spinner.tsx"
+import { ledgerCanister } from "./ledgers.ts"
+import type { LedgerToken } from "./LedgerSummary.tsx"
+
+/**
+ * The signed-in caller's balance on one ledger. Rendered only after
+ * hydration (the page wraps it in `ClientOnly`): a server has no caller.
+ *
+ * The Certified switch reads through the certified twin (a replicated call
+ * with a verified certificate), under a key of its own. The key itself is
+ * shown, with the caller's segment highlighted.
+ */
+export function BalancePanel({
+  entry,
+  token,
+}: {
+  entry: RegistryEntry
+  token: LedgerToken
+}): ReactElement {
+  const auth = useAuth()
+  const client = useClient()
+  const ids = useId()
+  const [certified, setCertified] = useState(false)
+
+  const signedIn = auth.status === "signed-in"
+  const owner =
+    signedIn && isPrincipal(auth.principal) ? auth.principal : undefined
+  const account = owner === undefined ? undefined : { owner, subaccount: null }
+  const ledger = ledgerCanister(client, entry.id, certified)
+  const balance = useQuery(
+    client.queryOptions(ledger, "icrc1_balance_of", account ?? skipToken)
+  )
+
+  if (account === undefined) {
+    return (
+      <Notice tone="info" title="Sign in to see your balance" role="none">
+        <p>
+          A balance belongs to a caller, and a server has none: the page renders
+          without it, and your balance loads in your browser once you sign in.
+          Reads are keyed by caller, so one principal’s balance is never shown
+          to another.
+        </p>
+      </Notice>
+    )
+  }
+
+  const key = client.queryKey(ledger, "icrc1_balance_of", account)
+  return (
+    <div className="stack wallet-balance">
+      <div className="row row-between">
+        <div className="stack-xs">
+          <span className="text-xs muted">Your balance</span>
+          <span className="wallet-balance-value tabular" aria-live="polite">
+            {balance.data !== undefined ? (
+              formatTokens(balance.data, token.decimals, token.symbol)
+            ) : balance.isError ? (
+              <span className="muted">Not read</span>
+            ) : (
+              <Skeleton width="10rem" height="1.4em" />
+            )}
+          </span>
+        </div>
+        <div className="row">
+          <label className="switch-label" htmlFor={`${ids}-certified`}>
+            <input
+              id={`${ids}-certified`}
+              type="checkbox"
+              className="switch"
+              checked={certified}
+              onChange={(event) => setCertified(event.target.checked)}
+            />
+            Certified
+          </label>
+          <ActionButton
+            className="btn btn-sm"
+            onClick={() => void balance.refetch()}
+            unavailable={balance.isFetching}
+          >
+            {balance.isFetching ? <Spinner size="sm" label="Reading" /> : null}
+            Refetch
+          </ActionButton>
+        </div>
+      </div>
+      {balance.isError && (
+        <Notice tone="danger" title="The balance read failed">
+          <p className="break-all">{balance.error.message}</p>
+        </Notice>
+      )}
+      <p className="text-xs muted">
+        {certified
+          ? "Certified: a replicated call whose answer the subnet signed, under its own key."
+          : "A query: one replica’s answer, fast, not certified."}
+      </p>
+      <CacheKeyPanel
+        queryKey={key}
+        status={balance.status}
+        fetching={balance.isFetching}
+      />
+    </div>
+  )
+}

package/examples/canister-studio/src/components/wallet/LedgerSummary.tsx

@@ -0,0 +1,63 @@
+import { useClient } from "@ic-reactor/react"
+import { useSuspenseQuery } from "@tanstack/react-query"
+import type { ReactElement } from "react"
+import { formatTokens } from "../../lib/format.ts"
+import type { RegistryEntry } from "../../lib/registry.ts"
+import { ledgerMetaReads } from "./ledgers.ts"
+
+/** A ledger's token, as its own replies give it (never the registry hint). */
+export interface LedgerToken {
+  name: string
+  symbol: string
+  decimals: number
+  fee: bigint
+}
+
+/**
+ * Reads the ledger's token metadata (suspends; server-rendered through the
+ * loader's prefetch) and hands it to `children`: the units every amount on
+ * the page is parsed and shown with.
+ */
+export function WithLedgerToken({
+  entry,
+  children,
+}: {
+  entry: RegistryEntry
+  children(token: LedgerToken): ReactElement
+}): ReactElement {
+  const client = useClient()
+  const reads = ledgerMetaReads(client, entry.id)
+  const token: LedgerToken = {
+    name: useSuspenseQuery(reads.name).data,
+    symbol: useSuspenseQuery(reads.symbol).data,
+    decimals: useSuspenseQuery(reads.decimals).data,
+    fee: useSuspenseQuery(reads.fee).data,
+  }
+  return children(token)
+}
+
+/** The ledger's token at a glance. */
+export function LedgerSummary({
+  entry,
+  token,
+}: {
+  entry: RegistryEntry
+  token: LedgerToken
+}): ReactElement {
+  return (
+    <dl className="kv kv-compact wallet-summary">
+      <dt>Token</dt>
+      <dd>
+        {token.name} <span className="muted">({token.symbol})</span>
+      </dd>
+      <dt>Decimals</dt>
+      <dd className="tabular">{token.decimals}</dd>
+      <dt>Transfer fee</dt>
+      <dd className="tabular">
+        {formatTokens(token.fee, token.decimals, token.symbol)}
+      </dd>
+      <dt>Ledger</dt>
+      <dd className="mono break-all">{entry.id}</dd>
+    </dl>
+  )
+}

package/examples/canister-studio/src/components/wallet/MinterPanel.tsx

@@ -0,0 +1,255 @@
+import { parseUnits } from "@ic-reactor/core"
+import { useAuth, useClient } from "@ic-reactor/react"
+import { skipToken, useQuery } from "@tanstack/react-query"
+import { useId, useState, type ReactElement } from "react"
+import { CacheKeyPanel } from "../../calls/CacheKeyPanel.tsx"
+import { addHistoryEntry, newHistoryId } from "../../calls/history.ts"
+import { prepareCall } from "../../calls/prepare.ts"
+import { historyEntryOf, type CallResult } from "../../calls/record.ts"
+import { formatTokens } from "../../lib/format.ts"
+import { ActionButton } from "../ActionButton.tsx"
+import { Card } from "../Card.tsx"
+import { CopyButton } from "../CopyButton.tsx"
+import { Notice } from "../Notice.tsx"
+import { Skeleton, Spinner } from "../Spinner.tsx"
+import { CKBTC_MINTER, minterCanister, minterInterface } from "./ledgers.ts"
+
+// Bitcoin amounts on the minter are satoshis.
+const BTC_DECIMALS = 8
+const NAT64_MAX = 2n ** 64n - 1n
+
+const btc = (sats: bigint): string => formatTokens(sats, BTC_DECIMALS, "BTC")
+
+/**
+ * The ckBTC minter, typed: the caller's bitcoin deposit address through the
+ * idempotent-update opt-in, and two public reads (the minter's limits and a
+ * withdrawal fee estimate).
+ */
+export function MinterPanel(): ReactElement {
+  return (
+    <Card
+      title="ckBTC minter"
+      subtitle={`Bitcoin in and out of ckBTC (${CKBTC_MINTER.id})`}
+      headingLevel={2}
+      id="wallet-minter"
+    >
+      <div className="grid wallet-minter-grid">
+        <DepositAddress />
+        <MinterLimits />
+        <WithdrawalFee />
+      </div>
+    </Card>
+  )
+}
+
+function DepositAddress(): ReactElement {
+  const auth = useAuth()
+  const client = useClient()
+  const [asked, setAsked] = useState(false)
+  const minter = minterCanister(client)
+  const signedIn = auth.status === "signed-in"
+  // `owner: null` is the caller. An update, read through the explicit
+  // idempotent opt-in: the same caller always gets the same address, so the
+  // answer is cached (stale time Infinity) and never read again by itself.
+  const arg = { owner: null, subaccount: null }
+  const address = useQuery(
+    client.queryOptions(
+      minter,
+      "get_btc_address",
+      asked && signedIn ? arg : skipToken,
+      { update: "idempotent" }
+    )
+  )
+
+  // Each ask is an update through consensus, so it goes into the history.
+  // `fetchQuery` shares the fetch the observer starts for the same key, and
+  // the idempotent options (stale time Infinity) never refetch an answer by
+  // themselves, so an error stays until the reader tries again.
+  const ask = (): void => {
+    setAsked(true)
+    const caller = client.caller()
+    const iface = minterInterface()
+    const method = iface.method("get_btc_address")
+    const call = method === undefined ? undefined : prepareCall(method, [arg])
+    const record = (result: CallResult): void => {
+      if (method === undefined || call === undefined) return
+      addHistoryEntry(
+        historyEntryOf(
+          { iface, method, caller, bytes: call.bytes, result },
+          Date.now(),
+          newHistoryId()
+        )
+      )
+    }
+    void client.queryClient
+      .fetchQuery(
+        client.queryOptions(minter, "get_btc_address", arg, {
+          update: "idempotent",
+        })
+      )
+      .then(
+        (reply) => record({ ok: true, reply }),
+        (error: unknown) => record({ ok: false, error })
+      )
+  }
+
+  return (
+    <section className="stack-sm" aria-labelledby="deposit-title">
+      <h3 id="deposit-title" className="text-sm wallet-minter-title">
+        Your deposit address
+      </h3>
+      <p className="text-xs muted">
+        <code className="code-inline">get_btc_address</code> is an update the
+        registry marks idempotent, so the page reads it with{" "}
+        <code className="code-inline">{'{ update: "idempotent" }'}</code>. It
+        still needs you signed in: the address belongs to your principal.
+      </p>
+      {!signedIn ? (
+        <p className="text-sm muted">Sign in to get your address.</p>
+      ) : address.data !== undefined ? (
+        <div className="stack-xs">
+          <div className="row-sm">
+            <code className="mono break-all wallet-address">
+              {address.data}
+            </code>
+            <CopyButton text={address.data} label="Copy address" iconOnly />
+          </div>
+          <CacheKeyPanel
+            queryKey={client.queryKey(minter, "get_btc_address", arg)}
+          />
+        </div>
+      ) : address.isError ? (
+        <Notice tone="danger" title="No address">
+          <p className="break-all">{address.error.message}</p>
+          <div className="row">
+            <ActionButton
+              className="btn btn-sm"
+              onClick={ask}
+              unavailable={address.isFetching}
+            >
+              {address.isFetching ? "Asking the minter…" : "Try again"}
+            </ActionButton>
+          </div>
+        </Notice>
+      ) : (
+        <ActionButton
+          className="btn btn-sm"
+          onClick={ask}
+          unavailable={address.isFetching}
+        >
+          {address.isFetching && (
+            <Spinner size="sm" label="Asking the minter" />
+          )}
+          {address.isFetching
+            ? "Asking the minter…"
+            : "Show my deposit address"}
+        </ActionButton>
+      )}
+    </section>
+  )
+}
+
+function MinterLimits(): ReactElement {
+  const client = useClient()
+  const info = useQuery(
+    client.queryOptions(minterCanister(client), "get_minter_info")
+  )
+  return (
+    <section className="stack-sm" aria-labelledby="limits-title">
+      <h3 id="limits-title" className="text-sm wallet-minter-title">
+        Limits
+      </h3>
+      {info.data !== undefined ? (
+        <dl className="kv kv-compact">
+          <dt>Min. withdrawal</dt>
+          <dd className="tabular">{btc(info.data.retrieve_btc_min_amount)}</dd>
+          <dt>Min. deposit</dt>
+          <dd className="tabular">
+            {info.data.deposit_btc_min_amount === null
+              ? "Not set"
+              : btc(info.data.deposit_btc_min_amount)}
+          </dd>
+          <dt>Check fee</dt>
+          <dd className="tabular">{btc(info.data.kyt_fee)}</dd>
+          <dt>Confirmations</dt>
+          <dd className="tabular">{info.data.min_confirmations}</dd>
+        </dl>
+      ) : info.isError ? (
+        <p className="text-sm muted break-all">{info.error.message}</p>
+      ) : (
+        <Skeleton height="4.5rem" />
+      )}
+    </section>
+  )
+}
+
+/** The amount text as satoshis, or why it is not one. */
+function satoshis(text: string): { sats?: bigint; problem?: string } {
+  if (text.trim() === "") return {}
+  try {
+    const sats = parseUnits(text.trim(), BTC_DECIMALS)
+    if (sats > NAT64_MAX) return { problem: "Larger than a nat64 can hold." }
+    return { sats }
+  } catch {
+    return { problem: "A plain decimal amount, at most 8 decimals: 0.001" }
+  }
+}
+
+function WithdrawalFee(): ReactElement {
+  const client = useClient()
+  const ids = useId()
+  const [text, setText] = useState("0.001")
+  const parsed = satoshis(text)
+  const fee = useQuery(
+    client.queryOptions(
+      minterCanister(client),
+      "estimate_withdrawal_fee",
+      parsed.sats === undefined ? skipToken : { amount: parsed.sats }
+    )
+  )
+  return (
+    <section className="stack-sm" aria-labelledby="fee-title">
+      <h3 id="fee-title" className="text-sm wallet-minter-title">
+        Withdrawal fee estimate
+      </h3>
+      <div className="field">
+        <label htmlFor={`${ids}-amount`} className="field-label">
+          Amount
+        </label>
+        <div className="input-group">
+          <input
+            id={`${ids}-amount`}
+            className="input mono"
+            inputMode="decimal"
+            autoComplete="off"
+            value={text}
+            onChange={(event) => setText(event.target.value)}
+            aria-invalid={parsed.problem !== undefined}
+            aria-describedby={`${ids}-amount-hint`}
+          />
+          <span className="input-addon">BTC</span>
+        </div>
+        <p
+          id={`${ids}-amount-hint`}
+          className={
+            parsed.problem === undefined ? "field-hint" : "field-error"
+          }
+        >
+          {parsed.problem ?? "Parsed with parseUnits: exact, never a float."}
+        </p>
+      </div>
+      {fee.data !== undefined && parsed.sats !== undefined ? (
+        <dl className="kv kv-compact" aria-live="polite">
+          <dt>Minter fee</dt>
+          <dd className="tabular">{btc(fee.data.minter_fee)}</dd>
+          <dt>Bitcoin fee</dt>
+          <dd className="tabular">{btc(fee.data.bitcoin_fee)}</dd>
+        </dl>
+      ) : fee.isError ? (
+        <p className="text-sm muted break-all">{fee.error.message}</p>
+      ) : fee.isFetching ? (
+        <Skeleton height="2.5rem" />
+      ) : null}
+    </section>
+  )
+}