@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/canister-studio/src/interface/live-loader.ts

@@ -0,0 +1,364 @@
+// Canister id in, interface payload out: the read, the fallbacks, the caches.
+// Isomorphic: the server wires it to an agent and its own compiler
+// (live-candid.server.ts), the browser to an agent and the lazily loaded
+// WASM (browser.ts), and tests to a fake source.
+import { checkCanisterId } from "../lib/ids.ts"
+import { sha256Hex, toHex } from "../lib/hex.ts"
+import { Lru } from "./cache.ts"
+import {
+  tooLarge,
+  type CompiledInterface,
+  type CompileFailure,
+} from "./compile.ts"
+import { classifyReadError, type CandidSource } from "./read-candid.ts"
+import type { InterfaceErrorCode, InterfacePayload } from "./types.ts"
+
+type OkPayload = Extract<InterfacePayload, { ok: true }>
+type FailedPayload = Extract<InterfacePayload, { ok: false }>
+
+export interface LiveLoaderOptions {
+  source: CandidSource
+  /** Compiles a .did (already within the size cap). */
+  compile(did: string): Promise<CompiledInterface | CompileFailure>
+  /** Recorded on each payload. */
+  compiledIn: "server" | "browser"
+  /** The clock, for tests. */
+  now?: () => number
+  /**
+   * The bound on one load, as a timer: it covers the reads, and the compile
+   * when that runs off the thread (the server's worker, with a deadline of
+   * its own). A compile on this thread (the browser's) holds the timer
+   * back until it returns.
+   */
+  timeoutMs?: number
+}
+
+export interface LiveLoader {
+  /**
+   * The live interface of a canister: its certified `candid:service`, or
+   * the uncertified tmp hack query when it publishes none, compiled. Never
+   * throws, and never reads a canister id `checkCanisterId` refuses.
+   */
+  load(
+    canisterId: string,
+    options?: { retry?: boolean }
+  ): Promise<InterfacePayload>
+}
+
+/** How long a canister's (module hash, did) answer is used before re-checking. */
+export const CANISTER_TTL_MS = 60_000
+/** How long a definitive failure (no interface, not found, …) is remembered. */
+export const FAILURE_TTL_MS = 5 * 60_000
+/**
+ * How long a failure that may pass by itself (network, timeout, a
+ * certificate that did not verify) is remembered: long enough to absorb a
+ * burst of reloads, short enough not to lock a canister out.
+ */
+export const TRANSIENT_FAILURE_TTL_MS = 15_000
+/**
+ * How old a remembered transient failure must be before an explicit retry
+ * ("Try again") reads the canister again: a retry is real, but a burst of
+ * clicks cannot turn into a burst of reads and compiles.
+ */
+export const RETRY_MIN_MS = 1_000
+/** The bound on one load (see `LiveLoaderOptions.timeoutMs`). */
+export const LOAD_TIMEOUT_MS = 15_000
+
+const MAX_CANISTERS = 1_000
+const MAX_FAILURES = 1_000
+/** Compiled interfaces by did hash: ckBTC and ckETH ledgers share one. */
+const MAX_DIDS = 200
+/** And at most this much text (UTF-16, 2 bytes a unit) across them. */
+const MAX_DID_CACHE_BYTES = 64 * 1024 * 1024
+
+const TRANSIENT: ReadonlySet<InterfaceErrorCode> = new Set([
+  "network",
+  "timeout",
+  "trust_error",
+  "server_error",
+])
+
+type CanisterEntry = {
+  /** When the module hash was last confirmed against the canister. */
+  checkedAt: number
+  /** Hex; a canister with no module never gets an entry. */
+  moduleHash: string
+  didSha256: string
+  source: "metadata" | "tmp_hack"
+  /** For the tmp hack: why the metadata was not used. */
+  reason?: "absent" | "private"
+}
+
+type DidEntry = { did: string; compiled: CompiledInterface }
+
+type FailureEntry = { at: number; until: number; payload: FailedPayload }
+
+const encoder = new TextEncoder()
+
+export function createLiveInterfaceLoader(
+  options: LiveLoaderOptions
+): LiveLoader {
+  const { source, compile, compiledIn } = options
+  const now = options.now ?? Date.now
+  const timeoutMs = options.timeoutMs ?? LOAD_TIMEOUT_MS
+
+  const byCanister = new Lru<string, CanisterEntry>({
+    maxEntries: MAX_CANISTERS,
+  })
+  const byDid = new Lru<string, DidEntry>({
+    maxEntries: MAX_DIDS,
+    maxWeight: MAX_DID_CACHE_BYTES,
+    weigh: (entry) =>
+      2 * (entry.did.length + entry.compiled.envelopeJson.length),
+  })
+  const failures = new Lru<string, FailureEntry>({ maxEntries: MAX_FAILURES })
+  const inflight = new Map<string, Promise<InterfacePayload>>()
+
+  const failed = (
+    canisterId: string,
+    code: InterfaceErrorCode,
+    message: string,
+    diagnostics?: FailedPayload["diagnostics"]
+  ): FailedPayload =>
+    diagnostics === undefined
+      ? { ok: false, canisterId, code, message }
+      : { ok: false, canisterId, code, message, diagnostics }
+
+  const payloadOf = (
+    canisterId: string,
+    entry: CanisterEntry,
+    { did, compiled }: DidEntry,
+    cache: OkPayload["cache"]
+  ): OkPayload => ({
+    ok: true,
+    canisterId,
+    source:
+      entry.source === "metadata"
+        ? { kind: "metadata", certified: true, moduleHash: entry.moduleHash }
+        : {
+            kind: "tmp_hack",
+            certified: false,
+            moduleHash: entry.moduleHash,
+            reason: entry.reason ?? "absent",
+          },
+    did,
+    didSha256: entry.didSha256,
+    envelopeJson: compiled.envelopeJson,
+    docs: compiled.docs,
+    fetchedAt: entry.checkedAt,
+    cache,
+    interfaceId: compiled.interfaceId,
+    compiledIn,
+  })
+
+  const remember = (canisterId: string, entry: CanisterEntry): void => {
+    byCanister.set(canisterId, entry)
+    // A load that outlived its timeout still lands here: drop the timeout
+    // it left behind, so the next request gets the answer.
+    failures.delete(canisterId)
+  }
+
+  // The cached answer while it is fresh, or after its module hash is
+  // re-checked unchanged; `undefined` when the interface must be read again.
+  async function fromCache(
+    canisterId: string
+  ): Promise<InterfacePayload | undefined> {
+    const hit = byCanister.get(canisterId)
+    const didEntry = hit === undefined ? undefined : byDid.get(hit.didSha256)
+    if (hit === undefined || didEntry === undefined) return undefined
+    if (now() - hit.checkedAt < CANISTER_TTL_MS) {
+      return payloadOf(canisterId, hit, didEntry, "hit")
+    }
+    // An uncertified tmp-hack answer is a query's reply, which may change
+    // with the canister's state, not only on an upgrade: past its TTL it is
+    // read again rather than renewed by an unchanged module hash.
+    if (hit.source === "tmp_hack") return undefined
+    let moduleHash: Uint8Array | null
+    try {
+      moduleHash = await source.readModuleHash(canisterId)
+    } catch (error) {
+      const sorted = classifyReadError(error, "module_hash")
+      if (sorted.kind !== "failed") return undefined
+      // The last certified answer beats none while the network is down;
+      // `fetchedAt` says how old it is. A certificate that does not verify,
+      // or a canister that is gone, is never answered from the cache.
+      if (sorted.code === "network" || sorted.code === "timeout") {
+        return payloadOf(canisterId, hit, didEntry, "hit")
+      }
+      return failed(canisterId, sorted.code, sorted.message)
+    }
+    // Metadata are custom sections of the module: the same module hash is
+    // the same interface, so nothing is read or compiled again.
+    if (moduleHash === null || toHex(moduleHash) !== hit.moduleHash) {
+      return undefined
+    }
+    const fresh = { ...hit, checkedAt: now() }
+    remember(canisterId, fresh)
+    return payloadOf(canisterId, fresh, didEntry, "hit")
+  }
+
+  async function readFresh(canisterId: string): Promise<InterfacePayload> {
+    let did: string | null = null
+    let moduleHash: Uint8Array | null = null
+    let isPrivate = false
+    try {
+      ;({ did, moduleHash } = await source.readCandidAndHash(canisterId))
+    } catch (error) {
+      const sorted = classifyReadError(error, "metadata")
+      if (sorted.kind === "failed") {
+        return failed(canisterId, sorted.code, sorted.message)
+      }
+      // A private candid:service refuses the whole request, module hash
+      // included: read the hash alone.
+      isPrivate = true
+      try {
+        moduleHash = await source.readModuleHash(canisterId)
+      } catch (hashError) {
+        const hashSorted = classifyReadError(hashError, "module_hash")
+        return hashSorted.kind === "failed"
+          ? failed(canisterId, hashSorted.code, hashSorted.message)
+          : failed(canisterId, "network", "Reading the module hash failed.")
+      }
+    }
+    if (moduleHash === null) {
+      return failed(
+        canisterId,
+        "no_interface",
+        "This canister has no module installed, so it has no interface."
+      )
+    }
+
+    let kind: CanisterEntry["source"] = "metadata"
+    if (did === null) {
+      try {
+        did = await source.readTmpHack(canisterId)
+        kind = "tmp_hack"
+      } catch (error) {
+        const sorted = classifyReadError(error, "tmp_hack")
+        if (sorted.kind === "failed") {
+          return failed(canisterId, sorted.code, sorted.message)
+        }
+        return isPrivate
+          ? failed(
+              canisterId,
+              "private_interface",
+              "This canister's candid:service metadata is readable by its controllers only, and it has no __get_candid_interface_tmp_hack query."
+            )
+          : failed(
+              canisterId,
+              "no_interface",
+              "This canister publishes no candid:service metadata and has no __get_candid_interface_tmp_hack query."
+            )
+      }
+    }
+
+    const large = tooLarge(did)
+    if (large !== undefined) {
+      return failed(canisterId, large.code, large.message)
+    }
+    const didSha256 = await sha256Hex(encoder.encode(did))
+    let didEntry = byDid.get(didSha256)
+    if (didEntry === undefined) {
+      const compiled = await compile(did)
+      if (!compiled.ok) {
+        return failed(
+          canisterId,
+          compiled.code,
+          compiled.message,
+          compiled.diagnostics
+        )
+      }
+      didEntry = { did, compiled }
+      byDid.set(didSha256, didEntry)
+    }
+    const entry: CanisterEntry = {
+      checkedAt: now(),
+      moduleHash: toHex(moduleHash),
+      didSha256,
+      source: kind,
+      ...(kind === "tmp_hack"
+        ? { reason: isPrivate ? ("private" as const) : ("absent" as const) }
+        : {}),
+    }
+    remember(canisterId, entry)
+    return payloadOf(canisterId, entry, didEntry, "miss")
+  }
+
+  async function resolve(canisterId: string): Promise<InterfacePayload> {
+    try {
+      return (await fromCache(canisterId)) ?? (await readFresh(canisterId))
+    } catch (error) {
+      // The reads never throw past classifyReadError, so this is the
+      // compiler that could not run (its WASM missing, or not downloaded)
+      // or a bug.
+      console.error(`Loading the interface of ${canisterId} failed:`, error)
+      if (compiledIn === "server") {
+        // Its text can carry the server's file paths: it stays in the log.
+        return failed(
+          canisterId,
+          "server_error",
+          "The studio's server failed while loading this interface; its log has the details."
+        )
+      }
+      // In a browser, most likely the compiler's download.
+      const message = error instanceof Error ? error.message : String(error)
+      return failed(
+        canisterId,
+        "network",
+        `Loading the interface failed in this browser: ${message.slice(0, 300)}`
+      )
+    }
+  }
+
+  function load(
+    canisterId: string,
+    options: { retry?: boolean } = {}
+  ): Promise<InterfacePayload> {
+    const id = checkCanisterId(canisterId)
+    if (!id.ok) return Promise.resolve(failed(canisterId, id.code, id.message))
+    const known = failures.get(canisterId)
+    const retried =
+      options.retry === true &&
+      known !== undefined &&
+      TRANSIENT.has(known.payload.code) &&
+      now() - known.at >= RETRY_MIN_MS
+    if (known !== undefined && known.until > now() && !retried)
+      return Promise.resolve(known.payload)
+    const running = inflight.get(canisterId)
+    if (running !== undefined) return running
+
+    const promise = withTimeout(resolve(canisterId), timeoutMs, () =>
+      failed(
+        canisterId,
+        "timeout",
+        `Loading the interface took longer than ${timeoutMs / 1000} s.`
+      )
+    )
+      .then((payload) => {
+        if (!payload.ok) {
+          const ttl = TRANSIENT.has(payload.code)
+            ? TRANSIENT_FAILURE_TTL_MS
+            : FAILURE_TTL_MS
+          failures.set(canisterId, { at: now(), until: now() + ttl, payload })
+        }
+        return payload
+      })
+      .finally(() => inflight.delete(canisterId))
+    inflight.set(canisterId, promise)
+    return promise
+  }
+
+  return { load }
+}
+
+function withTimeout<T>(
+  work: Promise<T>,
+  ms: number,
+  onTimeout: () => T
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const timeout = new Promise<T>((resolve) => {
+    timer = setTimeout(() => resolve(onTimeout()), ms)
+  })
+  return Promise.race([work, timeout]).finally(() => clearTimeout(timer))
+}

package/examples/canister-studio/src/interface/load.test.ts

@@ -0,0 +1,328 @@
+// What route loaders and pages call. The server function and the browser
+// fallback are mocked: this file never reaches a network or a compiler (the
+// runtime payloads below carry the committed icrc1 envelope).
+import { serviceMethods } from "@meantjs/schema"
+import { renderHook } from "@testing-library/react"
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import icrc1Did from "../../did/icrc1.did?raw"
+import { actor as icpLedgerActor } from "../canisters/icp_ledger.ts"
+import icrc1EnvelopeText from "../canisters/icrc1.envelope.json?raw"
+import { actor as icrc1Actor } from "../canisters/icrc1.ts"
+import { sha256Hex } from "../lib/hex.ts"
+import { registryEntry } from "../lib/registry.ts"
+import { readInterfaceInBrowser } from "./browser.ts"
+import { fetchInterface } from "./functions.ts"
+import {
+  interfaceFromPayload,
+  loadInterfacePayload,
+  retryInterface,
+  loadLivePayload,
+  useCanisterInterface,
+} from "./load.ts"
+import type { CanisterInterface, InterfacePayload } from "./types.ts"
+
+vi.mock("./functions.ts", () => ({ fetchInterface: vi.fn() }))
+vi.mock("./browser.ts", () => ({ readInterfaceInBrowser: vi.fn() }))
+
+const fetchMock = vi.mocked(fetchInterface)
+const browserMock = vi.mocked(readInterfaceInBrowser)
+
+const ICP_LEDGER = "ryjl3-tyaaa-aaaaa-aaaba-cai"
+const CKBTC_LEDGER = "mxzaz-hqaaa-aaaar-qaada-cai"
+const CKETH_LEDGER = "ss2fx-dyaaa-aaaar-qacoq-cai"
+const CKBTC_MINTER = "mqygn-kiaaa-aaaar-qaadq-cai"
+const CYCLES_LEDGER = "um5iw-rqaaa-aaaaq-qaaba-cai"
+// The NNS dapp: neither in the registry nor curated.
+const SOME_CANISTER = "qoctq-giaaa-aaaaa-aaaea-cai"
+
+type OkPayload = Extract<InterfacePayload, { ok: true }>
+
+async function runtimePayload(
+  canisterId: string,
+  overrides: Partial<OkPayload> = {}
+): Promise<OkPayload> {
+  return {
+    ok: true,
+    canisterId,
+    source: { kind: "metadata", certified: true, moduleHash: "a1".repeat(32) },
+    did: icrc1Did,
+    didSha256: await sha256Hex(new TextEncoder().encode(icrc1Did)),
+    envelopeJson: JSON.stringify(JSON.parse(icrc1EnvelopeText)),
+    docs: { icrc1_fee: "The fee of one transfer." },
+    fetchedAt: 1_000,
+    cache: "miss",
+    compiledIn: "server",
+    ...overrides,
+  }
+}
+
+function ok(p: InterfacePayload): OkPayload {
+  if (!p.ok) {
+    throw new Error(`expected an interface, got ${p.code}: ${p.message}`)
+  }
+  return p
+}
+
+beforeEach(() => {
+  fetchMock.mockReset()
+  browserMock.mockReset()
+})
+
+afterEach(() => {
+  vi.unstubAllEnvs()
+})
+
+describe("loadInterfacePayload", () => {
+  it("gives a registry canister's typed payload without a server call", async () => {
+    const p = ok(await loadInterfacePayload(ICP_LEDGER))
+    expect(p).toMatchObject({
+      canisterId: ICP_LEDGER,
+      source: { kind: "typed", module: "icp_ledger" },
+      did: registryEntry(ICP_LEDGER)?.did,
+      fetchedAt: 0,
+      cache: "typed",
+    })
+    expect(p.didSha256).toBe(await sha256Hex(new TextEncoder().encode(p.did)))
+    expect(p.envelopeJson).toBeUndefined()
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
+  it("reads a typed canister's docs from its committed module", async () => {
+    const p = ok(await loadInterfacePayload(CKBTC_MINTER))
+    expect(p.docs.get_minter_info).toMatch(/Returns internal minter parameters/)
+  })
+
+  it("refuses an invalid id without a server call", async () => {
+    expect(
+      await loadInterfacePayload(" mxzaz-hqaaa-aaaar-qaada-cai")
+    ).toMatchObject({
+      ok: false,
+      code: "invalid_canister_id",
+    })
+    expect(await loadInterfacePayload("aaaaa-aa")).toMatchObject({
+      ok: false,
+      code: "management_canister",
+    })
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
+  it("asks the server function for any other canister", async () => {
+    const payload = await runtimePayload(SOME_CANISTER)
+    fetchMock.mockResolvedValue(payload)
+    expect(await loadInterfacePayload(SOME_CANISTER)).toBe(payload)
+    expect(fetchMock).toHaveBeenCalledWith({
+      data: { canisterId: SOME_CANISTER, retry: false },
+    })
+  })
+
+  it("passes an explicit retry to the server once, for that load only", async () => {
+    const payload = {
+      ok: false as const,
+      canisterId: SOME_CANISTER,
+      code: "network" as const,
+      message: "down",
+    }
+    fetchMock.mockResolvedValue(payload)
+    retryInterface(SOME_CANISTER)
+    await loadInterfacePayload(SOME_CANISTER)
+    await loadInterfacePayload(SOME_CANISTER)
+    expect(fetchMock.mock.calls.map((c) => c[0])).toEqual([
+      { data: { canisterId: SOME_CANISTER, retry: true } },
+      { data: { canisterId: SOME_CANISTER, retry: false } },
+    ])
+  })
+
+  it("passes a failure the server returns through, without a browser read", async () => {
+    const failure: InterfacePayload = {
+      ok: false,
+      canisterId: SOME_CANISTER,
+      code: "no_interface",
+      message: "none",
+    }
+    fetchMock.mockResolvedValue(failure)
+    expect(await loadInterfacePayload(SOME_CANISTER)).toBe(failure)
+    expect(browserMock).not.toHaveBeenCalled()
+  })
+
+  it("reads from the browser when the server function cannot be called", async () => {
+    vi.stubEnv("SSR", false)
+    const fromBrowser = await runtimePayload(SOME_CANISTER, {
+      compiledIn: "browser",
+    })
+    fetchMock.mockRejectedValue(new TypeError("Failed to fetch"))
+    browserMock.mockResolvedValue(fromBrowser)
+    expect(await loadInterfacePayload(SOME_CANISTER)).toBe(fromBrowser)
+    expect(browserMock).toHaveBeenCalledWith(SOME_CANISTER, { retry: false })
+  })
+
+  it("reports a failed call during SSR instead of reading from the server's 'browser'", async () => {
+    vi.stubEnv("SSR", true)
+    fetchMock.mockRejectedValue(new Error("AsyncLocalStorage is gone"))
+    expect(await loadInterfacePayload(SOME_CANISTER)).toMatchObject({
+      ok: false,
+      code: "network",
+    })
+    expect(browserMock).not.toHaveBeenCalled()
+  })
+
+  // StackBlitz: the server answers a plain 500, and TanStack Start's client
+  // resolves the call with undefined instead of rejecting.
+  it("reads from the browser when the server function resolves with no result", async () => {
+    vi.stubEnv("SSR", false)
+    const fromBrowser = await runtimePayload(SOME_CANISTER, {
+      compiledIn: "browser",
+    })
+    fetchMock.mockResolvedValue(undefined as unknown as InterfacePayload)
+    browserMock.mockResolvedValue(fromBrowser)
+    expect(await loadInterfacePayload(SOME_CANISTER)).toBe(fromBrowser)
+    expect(browserMock).toHaveBeenCalledWith(SOME_CANISTER, { retry: false })
+  })
+
+  it("reports a call with no result during SSR as a failed payload", async () => {
+    vi.stubEnv("SSR", true)
+    fetchMock.mockResolvedValue(undefined as unknown as InterfacePayload)
+    expect(await loadInterfacePayload(SOME_CANISTER)).toMatchObject({
+      ok: false,
+      canisterId: SOME_CANISTER,
+      code: "network",
+      message: expect.stringMatching(/studio's server/),
+    })
+    expect(browserMock).not.toHaveBeenCalled()
+  })
+})
+
+describe("loadLivePayload", () => {
+  it("reads a registry canister live too, for a check against its committed .did", async () => {
+    const payload = await runtimePayload(ICP_LEDGER)
+    fetchMock.mockResolvedValue(payload)
+    expect(await loadLivePayload(ICP_LEDGER)).toBe(payload)
+    expect(fetchMock).toHaveBeenCalledWith({
+      data: { canisterId: ICP_LEDGER, retry: false },
+    })
+  })
+
+  it("falls back to the browser when the server gives no result", async () => {
+    vi.stubEnv("SSR", false)
+    const fromBrowser = await runtimePayload(ICP_LEDGER, {
+      compiledIn: "browser",
+    })
+    fetchMock.mockResolvedValue({} as InterfacePayload)
+    browserMock.mockResolvedValue(fromBrowser)
+    expect(await loadLivePayload(ICP_LEDGER)).toBe(fromBrowser)
+  })
+})
+
+describe("interfaceFromPayload", () => {
+  it("uses the registry's generated actor for a typed payload", async () => {
+    const p = ok(await loadInterfacePayload(ICP_LEDGER))
+    const iface = interfaceFromPayload(p)
+    expect(iface.actor).toBe(icpLedgerActor)
+    expect(iface).toMatchObject({
+      canisterId: ICP_LEDGER,
+      name: "ICP ledger",
+      source: p.source,
+    })
+    expect(iface.registry?.id).toBe(ICP_LEDGER)
+    expect(iface.methods).toHaveLength(serviceMethods(icpLedgerActor).size)
+    expect(iface.method("icrc1_transfer")?.mode).toBe("update")
+    expect(iface.method("icrc1_balance_of")?.mode).toBe("query")
+    expect(interfaceFromPayload(p)).toBe(iface)
+  })
+
+  it("sorts methods by code point and looks names up in a Map", async () => {
+    const iface = interfaceFromPayload(
+      ok(await loadInterfacePayload(ICP_LEDGER))
+    )
+    const names = iface.methods.map((m) => m.name)
+    expect(names).toEqual([...names].sort())
+    expect(iface.method("toString")).toBeUndefined()
+    expect(iface.method("__proto__")).toBeUndefined()
+  })
+
+  it("gives ckBTC and ckETH ledgers their own interfaces over one actor", async () => {
+    const ckbtc = interfaceFromPayload(
+      ok(await loadInterfacePayload(CKBTC_LEDGER))
+    )
+    const cketh = interfaceFromPayload(
+      ok(await loadInterfacePayload(CKETH_LEDGER))
+    )
+    expect(ckbtc).not.toBe(cketh)
+    expect(ckbtc.actor).toBe(icrc1Actor)
+    expect(cketh.actor).toBe(icrc1Actor)
+    expect(cketh.name).toBe("ckETH ledger")
+  })
+
+  it("rebuilds a runtime interface from its envelope, with docs", async () => {
+    const iface = interfaceFromPayload(await runtimePayload(SOME_CANISTER))
+    expect(iface.name).toBe(SOME_CANISTER)
+    expect(iface.registry).toBeUndefined()
+    expect(iface.omitted).toEqual([])
+    expect(iface.methods.map((m) => m.name)).toContain("icrc1_transfer")
+    expect(iface.method("icrc1_fee")?.doc).toBe("The fee of one transfer.")
+    expect(iface.method("icrc1_symbol")?.doc).toBeUndefined()
+  })
+
+  it("keeps objects stable by content: a payload rebuilt after hydration gives the same interface", async () => {
+    const first = interfaceFromPayload(await runtimePayload(CYCLES_LEDGER))
+    const again = interfaceFromPayload(await runtimePayload(CYCLES_LEDGER))
+    expect(again).toBe(first)
+    expect(first.name).toBe("Cycles ledger")
+    // Another canister with the same .did: its own interface, the same schemas.
+    const other = interfaceFromPayload(await runtimePayload(SOME_CANISTER))
+    expect(other).not.toBe(first)
+    expect(other.actor).toBe(first.actor)
+  })
+
+  it("labels a tmp_hack interface from the payload's source", async () => {
+    const iface = interfaceFromPayload(
+      await runtimePayload(SOME_CANISTER, {
+        source: { kind: "tmp_hack", certified: false, moduleHash: null },
+      })
+    )
+    expect(iface.source).toEqual({
+      kind: "tmp_hack",
+      certified: false,
+      moduleHash: null,
+    })
+  })
+
+  it("names a pasted interface", async () => {
+    const iface = interfaceFromPayload(
+      await runtimePayload("", { source: { kind: "pasted", certified: false } })
+    )
+    expect(iface.name).toBe("Pasted interface")
+  })
+
+  it("throws for an envelope the schema loader refuses", async () => {
+    const tampered = await runtimePayload(SOME_CANISTER, {
+      didSha256: "f".repeat(64),
+      envelopeJson: JSON.stringify({
+        ...JSON.parse(icrc1EnvelopeText),
+        extra: 1,
+      }),
+    })
+    expect(() => interfaceFromPayload(tampered)).toThrow(/unknown_key/)
+  })
+})
+
+describe("useCanisterInterface", () => {
+  it("gives undefined for a failure, and a stable interface for a payload", async () => {
+    const failure: InterfacePayload = {
+      ok: false,
+      canisterId: SOME_CANISTER,
+      code: "no_interface",
+      message: "none",
+    }
+    const payload = await runtimePayload(SOME_CANISTER)
+    const { result, rerender } = renderHook<
+      CanisterInterface | undefined,
+      InterfacePayload
+    >((p) => useCanisterInterface(p), { initialProps: failure })
+    expect(result.current).toBeUndefined()
+    rerender(payload)
+    const iface = result.current
+    expect(iface?.canisterId).toBe(SOME_CANISTER)
+    rerender({ ...payload })
+    expect(result.current).toBe(iface)
+  })
+})