@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/next-ssr/src/format.ts

@@ -0,0 +1,46 @@
+// Display helpers shared by server and client components. Nothing here turns a
+// bigint into a number: amounts go through `formatUnits`.
+import { isPrincipal } from "@meantjs/schema"
+import { formatUnits } from "@ic-reactor/core"
+import type { Value } from "@/canisters/icrc1"
+
+export const toHex = (bytes: Uint8Array): string =>
+  Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("")
+
+/** `units` base units as tokens: `formatUnits` places the point, exactly. */
+export const tokens = (units: bigint, decimals: number, symbol: string) =>
+  `${formatUnits(units, decimals)} ${symbol}`
+
+/**
+ * What a value is at run time, as the page shows it next to the value: how a
+ * reader sees that hydration gave back a `bigint` or a `Uint8Array`, and not
+ * the string or the object of numbered keys JSON would have made of it.
+ */
+export function runtimeType(value: unknown): string {
+  if (value instanceof Uint8Array) return `Uint8Array(${value.length})`
+  if (value === null) return "null"
+  return typeof value
+}
+
+/**
+ * A Candid `principal` is principal text at run time (`@meantjs/schema`'s
+ * `Principal` is a branded string). After hydration it must still be
+ * canonical principal text, which `isPrincipal` checks.
+ */
+export const principalType = (text: string): string =>
+  isPrincipal(text) ? "principal text" : "not principal text"
+
+/** An `icrc1_metadata` value as text; a long one (a logo's data URL) is cut. */
+export function metadataText(value: Value): string {
+  switch (value.tag) {
+    case "Nat":
+    case "Int":
+      return value.value.toString()
+    case "Blob":
+      return `0x${toHex(value.value)}`
+    case "Text":
+      return value.value.length > 48
+        ? `${value.value.slice(0, 48)}… (${value.value.length} characters)`
+        : value.value
+  }
+}

package/examples/next-ssr/src/ledgers.ts

@@ -0,0 +1,38 @@
+// The canisters this app reads on mainnet, by canister id. A server render has
+// no `ic_env` cookie to resolve a `{ name }` from, so every canister the server
+// calls is an `{ id }` target. Plain data with no imports, so that
+// scripts/smoke.ts can load it under Node as it is.
+
+export interface LedgerRef {
+  /** The ledger's canister id on mainnet. */
+  readonly id: string
+  /** What the page calls it, and what the route handler accepts in its place. */
+  readonly label: string
+}
+
+/** The ICRC-1 ledgers every page reads. */
+export const LEDGERS: readonly LedgerRef[] = [
+  { id: "ryjl3-tyaaa-aaaaa-aaaba-cai", label: "ICP" },
+  { id: "mxzaz-hqaaa-aaaar-qaada-cai", label: "ckBTC" },
+  { id: "ss2fx-dyaaa-aaaar-qacoq-cai", label: "ckETH" },
+]
+
+/**
+ * NNS governance: a canister, but not a ledger. It has no `icrc1_*` methods,
+ * so the IC rejects every read of it (reject code 5). The home page renders it
+ * as a fourth ledger, to show one section failing alone.
+ */
+export const NOT_A_LEDGER: LedgerRef = {
+  id: "rrkah-fqaaa-aaaaa-aaaaq-cai",
+  label: "NNS governance (not a ledger)",
+}
+
+/** The cycles minting canister: it holds ICP, so a lookup has an answer. */
+export const SAMPLE_OWNER = "rkp4c-7iaaa-aaaaa-aaaca-cai"
+
+/**
+ * A well-formed canister id that names no canister on mainnet: a boundary
+ * node refuses every read of it with HTTP 400 `canister_not_found`, which the
+ * client reports as `code: "canister_not_found"`.
+ */
+export const NO_CANISTER = "2y4s5-zaaaa-aaad7-7777q-cai"

package/examples/next-ssr/src/server/balance-route.test.ts

@@ -0,0 +1,151 @@
+// Scenario 7: the balance route's handler, called as Next calls it, over a
+// test client per request.
+import { afterEach, describe, expect, it, vi } from "vitest"
+import { LEDGERS, NOT_A_LEDGER, NO_CANISTER, SAMPLE_OWNER } from "@/ledgers"
+import {
+  mockLedgers,
+  requestsFor,
+  type MockLedgers,
+} from "@/testing/mock-ledgers"
+import { balanceRoute } from "./balance-route"
+
+const tests: MockLedgers[] = []
+afterEach(() => {
+  for (const test of tests.splice(0)) test.client.dispose()
+})
+
+/** The handler over a new test client per request, and those clients. */
+function handler(prepare?: (test: MockLedgers) => void) {
+  const newClient = vi.fn(() => {
+    const test = mockLedgers()
+    prepare?.(test)
+    tests.push(test)
+    return test.client
+  })
+  return { GET: balanceRoute(newClient), newClient }
+}
+
+const get = async (
+  GET: ReturnType<typeof balanceRoute>,
+  ledger: string,
+  principal: string
+) => {
+  const response = await GET(
+    new Request(`http://localhost/api/balance/${ledger}/${principal}`),
+    { params: Promise.resolve({ ledger, principal }) }
+  )
+  return { status: response.status, body: (await response.json()) as unknown }
+}
+
+describe("GET /api/balance/[ledger]/[principal]", () => {
+  it("answers the balance as decimal text and exact base units, with a client of its own", async () => {
+    const { GET, newClient } = handler()
+
+    const { status, body } = await get(GET, "ICP", SAMPLE_OWNER)
+
+    expect(status).toBe(200)
+    expect(body).toEqual({
+      ledger: LEDGERS[0]!.id,
+      owner: SAMPLE_OWNER,
+      symbol: "ICP",
+      decimals: 8,
+      balance: "123456789012345.67890123",
+      baseUnits: "12345678901234567890123",
+    })
+    await get(GET, "ckBTC", SAMPLE_OWNER)
+    expect(newClient).toHaveBeenCalledTimes(2)
+  })
+
+  it("takes a label in any case, or a canister id", async () => {
+    const { GET } = handler()
+
+    expect((await get(GET, "cketh", SAMPLE_OWNER)).body).toMatchObject({
+      ledger: LEDGERS[2]!.id,
+      decimals: 18,
+      balance: "12345.678901234567890123",
+    })
+    expect((await get(GET, LEDGERS[1]!.id, SAMPLE_OWNER)).body).toMatchObject({
+      symbol: "ckBTC",
+    })
+  })
+
+  it("answers 400 for a principal or a ledger it cannot read, before building a client", async () => {
+    const { GET, newClient } = handler()
+
+    const badOwner = await get(GET, "ICP", "not-a-principal")
+    const badLedger = await get(GET, "DOGE", SAMPLE_OWNER)
+
+    expect(badOwner.status).toBe(400)
+    expect(badOwner.body).toMatchObject({ error: { kind: "invalid_args" } })
+    expect(badLedger.status).toBe(400)
+    expect(badLedger.body).toMatchObject({ error: { kind: "invalid_args" } })
+    expect(newClient).not.toHaveBeenCalled()
+  })
+
+  it("maps a rejected read to 502, with the kind and reject code", async () => {
+    const { GET } = handler()
+
+    const { status, body } = await get(GET, NOT_A_LEDGER.id, SAMPLE_OWNER)
+
+    expect(status).toBe(502)
+    expect(body).toMatchObject({ error: { kind: "rejected", rejectCode: 5 } })
+  })
+
+  it.each([429, 503])(
+    "maps a read turned away with HTTP %i, which passes, to 503",
+    async (refusal) => {
+      // A boundary node turns the balance read away every time it is sent:
+      // the client re-sends a read at most twice, then gives up with
+      // `not_delivered`. A fourth send would be answered, and the route would
+      // answer 200.
+      const { GET } = handler((test) =>
+        test.refuseNext(refusal, { method: "icrc1_balance_of", times: 3 })
+      )
+
+      const { status, body } = await get(GET, "ICP", SAMPLE_OWNER)
+
+      expect(status).toBe(503)
+      expect(body).toMatchObject({
+        error: { kind: "not_delivered", httpStatus: refusal },
+      })
+      expect(tests[0] && requestsFor(tests[0], "icrc1_balance_of").length).toBe(
+        3
+      )
+    }
+  )
+
+  it("maps a read refused with an HTTP 4xx that stands to 502, since asking again cannot help", async () => {
+    // A boundary node answers HTTP 400 for a canister id that names no
+    // canister, or a request it cannot accept, however often it is asked: here
+    // it turns the balance read away each of the three times a read could be
+    // sent. The client does not re-send a 4xx, and neither should the route's
+    // caller.
+    const { GET } = handler((test) =>
+      test.refuseNext(400, { method: "icrc1_balance_of", times: 3 })
+    )
+
+    const { status, body } = await get(GET, "ICP", SAMPLE_OWNER)
+
+    expect(status).toBe(502)
+    expect(body).toMatchObject({
+      error: { kind: "not_delivered", httpStatus: 400 },
+    })
+    expect(tests[0] && requestsFor(tests[0], "icrc1_balance_of").length).toBe(1)
+  })
+
+  it("maps a canister that does not exist to 502, with code canister_not_found", async () => {
+    // For this id, outside every subnet's range, mainnet answers HTTP 400
+    // `canister_not_found` (`kind: "not_delivered"`); the fake replica rejects
+    // with code 3 and IC0301 (`kind: "rejected"`), as a mainnet replica does
+    // for an id inside its range that holds no canister. All say
+    // `code: "canister_not_found"`, and all are a 502.
+    const { GET } = handler()
+
+    const { status, body } = await get(GET, NO_CANISTER, SAMPLE_OWNER)
+
+    expect(status).toBe(502)
+    expect(body).toMatchObject({
+      error: { kind: "rejected", rejectCode: 3, code: "canister_not_found" },
+    })
+  })
+})

package/examples/next-ssr/src/server/balance-route.ts

@@ -0,0 +1,157 @@
+// Scenario 7 (with src/app/api/balance/[ledger]/[principal]/route.ts): a Route
+// Handler with a client of its own, answering JSON.
+//
+// Rules:
+// - One client per request: the handler builds a client for each request it
+//   serves, through `newClient`.
+// - A route handler has no cache to fill and no page to hydrate, so it calls
+//   the ledger directly (`ledger.icrc1_balance_of(account)`): a direct call
+//   never touches a cache.
+// - Amounts are base units: the JSON gives the balance as decimal text from
+//   `formatUnits` and the exact base units as a string, never as a JSON
+//   number, which would lose digits past 2^53.
+// - Typed principals are validated with `isPrincipal` and made with
+//   `principal()`; anything else is a 400 before any call is made.
+// - A failure is a `ReactorError`: its `kind` decides the HTTP status, with
+//   `httpStatus` telling a refusal that passes from one that stands
+//   (`statusOf`).
+import { isPrincipal, principal } from "@meantjs/schema"
+import {
+  formatUnits,
+  isReactorError,
+  type Client,
+  type ReactorError,
+  type ReactorErrorKind,
+} from "@ic-reactor/core"
+import { actor, type Actor } from "@/canisters/icrc1"
+import { LEDGERS } from "@/ledgers"
+
+/** The route's dynamic segments, as Next hands them to the handler. */
+export interface BalanceParams {
+  /** A ledger's label from src/ledgers.ts (`ICP`, `ckBTC`, `ckETH`, any case) or a canister id. */
+  readonly ledger: string
+  readonly principal: string
+}
+
+/** What the handler answers for each kind of failure; see `statusOf`. */
+export const STATUS_BY_KIND = {
+  // The request itself is wrong.
+  invalid_args: 400,
+  unauthenticated: 401,
+  // The IC or the canister said no, or answered with something unusable: the
+  // upstream failed, not this request, and it gives the same answer again.
+  rejected: 502,
+  invalid_reply: 502,
+  canister_err: 502,
+  // Nothing came back in time.
+  outcome_unknown: 504,
+  // The read was turned away for now (a rate limit, a 5xx, reject code 2) or
+  // got no answer: worth asking again later. `statusOf` sends the refusals
+  // that stand to 502 instead.
+  not_delivered: 503,
+  cancelled: 503,
+} as const satisfies Record<ReactorErrorKind, number>
+
+/**
+ * The HTTP status the handler answers for `error`.
+ *
+ * `kind` decides it, except where `kind` is not enough: `not_delivered`
+ * covers a refusal that passes and one that stands. HTTP 429, 408 and every
+ * 5xx pass, and so do reject code 2 and a dropped connection (no
+ * `httpStatus`): the client itself re-sends those. Any other 4xx stands: a
+ * boundary node answers 400 for a canister id that names no canister
+ * (`code: "canister_not_found"`), however often it is asked, and refuses a bad
+ * signature the same way each time. Telling a caller to come back later (503)
+ * for that would be a lie, so it is a 502, like a rejection.
+ */
+export function statusOf(error: ReactorError<unknown>): number {
+  const { kind, httpStatus } = error
+  const refusedForGood =
+    kind === "not_delivered" &&
+    httpStatus !== undefined &&
+    httpStatus >= 400 &&
+    httpStatus < 500 &&
+    httpStatus !== 408 &&
+    httpStatus !== 429
+  return refusedForGood ? 502 : STATUS_BY_KIND[kind]
+}
+
+const json = (status: number, body: unknown): Response =>
+  Response.json(body, {
+    status,
+    headers: { "cache-control": "no-store" },
+  })
+
+/** The canister id `text` names: a ledger's label, or a canister id itself. */
+function ledgerIdOf(text: string): string | undefined {
+  const known = LEDGERS.find(
+    ({ label }) => label.toLowerCase() === text.toLowerCase()
+  )
+  if (known !== undefined) return known.id
+  return isPrincipal(text) ? text : undefined
+}
+
+/**
+ * The `GET` handler of the balance route. `newClient` builds the client for
+ * one request; the route passes `() => createClient({ network: "ic",
+ * identity: "anonymous" })`, and the tests a test client.
+ */
+export function balanceRoute(newClient: () => Client) {
+  return async (
+    _request: Request,
+    context: { params: Promise<BalanceParams> }
+  ): Promise<Response> => {
+    const params = await context.params
+    const ledgerId = ledgerIdOf(params.ledger)
+    if (ledgerId === undefined) {
+      return json(400, {
+        error: {
+          kind: "invalid_args",
+          message: `${params.ledger} is neither ${LEDGERS.map(({ label }) => label).join(", ")} nor a canister id.`,
+        },
+      })
+    }
+    if (!isPrincipal(params.principal)) {
+      return json(400, {
+        error: {
+          kind: "invalid_args",
+          message: `${params.principal} is not principal text.`,
+        },
+      })
+    }
+    const owner = principal(params.principal)
+
+    const client = newClient()
+    const ledger = client.canister<Actor>(actor, { id: ledgerId })
+    try {
+      const [baseUnits, decimals, symbol] = await Promise.all([
+        ledger.icrc1_balance_of({ owner, subaccount: null }),
+        ledger.icrc1_decimals(),
+        ledger.icrc1_symbol(),
+      ])
+      return json(200, {
+        ledger: ledgerId,
+        owner,
+        symbol,
+        decimals,
+        balance: formatUnits(baseUnits, decimals),
+        baseUnits: baseUnits.toString(),
+      })
+    } catch (error) {
+      if (!isReactorError(error)) throw error
+      return json(statusOf(error), {
+        error: {
+          kind: error.kind,
+          ...(error.code !== undefined && { code: error.code }),
+          ...(error.rejectCode !== undefined && {
+            rejectCode: error.rejectCode,
+          }),
+          ...(error.httpStatus !== undefined && {
+            httpStatus: error.httpStatus,
+          }),
+          message: error.message,
+        },
+      })
+    }
+  }
+}

package/examples/next-ssr/src/server/error-summary.test.ts

@@ -0,0 +1,34 @@
+// Scenario 8: what a section shows of a failure is read from the
+// `ReactorError` on the server; anything else is this app's bug, and thrown.
+import { afterEach, describe, expect, it } from "vitest"
+import { actor, type Actor } from "@/canisters/icrc1"
+import { NOT_A_LEDGER } from "@/ledgers"
+import { mockLedgers, type MockLedgers } from "@/testing/mock-ledgers"
+import { summarizeError } from "./error-summary"
+
+let test: MockLedgers
+afterEach(() => test.client.dispose())
+
+describe("summarizeError", () => {
+  it("reads the kind and reject code of a ReactorError", async () => {
+    test = mockLedgers()
+    const notALedger = test.client.canister<Actor>(actor, {
+      id: NOT_A_LEDGER.id,
+    })
+
+    const error = await notALedger.icrc1_name().catch((e: unknown) => e)
+
+    expect(summarizeError(error)).toEqual({
+      kind: "rejected",
+      rejectCode: 5,
+      message: expect.stringContaining("icrc1_name"),
+    })
+  })
+
+  it("throws anything that is not a ReactorError", () => {
+    test = mockLedgers()
+    const bug = new TypeError("a bug of the app")
+
+    expect(() => summarizeError(bug)).toThrow(bug)
+  })
+})

package/examples/next-ssr/src/server/error-summary.ts

@@ -0,0 +1,37 @@
+// Scenario 8 (with src/components/LedgerError.tsx): errors on the server.
+//
+// Rule: every rejection a client call produces is a `ReactorError`; test it
+// with `isReactorError(error)`, then read `kind`. Anything else is a bug in
+// this app, and is thrown on.
+//
+// A server section shows its own failure: the page renders the kind here, on
+// the server, so it is in the HTML. An `error.tsx` boundary would not do: in a
+// production build Next replaces a Server Component's error with a generic one
+// before the browser sees it, and the kind would be gone.
+import { isReactorError, type ReactorErrorKind } from "@ic-reactor/core"
+
+/** What a section shows of a failed call: plain data, safe to pass to any component. */
+export interface ErrorSummary {
+  readonly kind: ReactorErrorKind
+  /** The IC reject code, when the IC or the canister rejected the call. */
+  readonly rejectCode?: number
+  /** The HTTP status a replica or boundary node answered with, when there was one. */
+  readonly httpStatus?: number
+  readonly message: string
+}
+
+/**
+ * The summary of a failed call.
+ *
+ * @throws `error` itself when it is not a `ReactorError`: not a failure of
+ * the call, but of this app.
+ */
+export function summarizeError(error: unknown): ErrorSummary {
+  if (!isReactorError(error)) throw error
+  return {
+    kind: error.kind,
+    ...(error.rejectCode !== undefined && { rejectCode: error.rejectCode }),
+    ...(error.httpStatus !== undefined && { httpStatus: error.httpStatus }),
+    message: error.message,
+  }
+}

package/examples/next-ssr/src/server/parse-owner.test.ts

@@ -0,0 +1,39 @@
+// Scenario 6: the owner search parameter is user input, validated on the
+// server. Principal text becomes a principal; anything else is a message.
+import { describe, expect, it } from "vitest"
+import { SAMPLE_OWNER } from "@/ledgers"
+import { parseOwner } from "./parse-owner"
+
+describe("parseOwner", () => {
+  it("makes a principal of principal text, without the spaces around it", () => {
+    expect(parseOwner(`  ${SAMPLE_OWNER} `)).toEqual({
+      kind: "valid",
+      text: SAMPLE_OWNER,
+      owner: SAMPLE_OWNER,
+    })
+  })
+
+  it("refuses text that is not a principal, with a message that names it", () => {
+    for (const text of [
+      "not-a-principal",
+      SAMPLE_OWNER.toUpperCase(),
+      SAMPLE_OWNER.slice(0, -1),
+    ]) {
+      const input = parseOwner(text)
+      expect(input.kind).toBe("invalid")
+      expect(input.kind === "invalid" && input.reason).toContain(`"${text}"`)
+    }
+  })
+
+  it("reads no parameter, or a blank one, as nothing asked", () => {
+    expect(parseOwner(undefined)).toEqual({ kind: "empty" })
+    expect(parseOwner("   ")).toEqual({ kind: "empty" })
+  })
+
+  it("uses the first of a repeated parameter", () => {
+    expect(parseOwner([SAMPLE_OWNER, "aaaaa-aa"])).toMatchObject({
+      kind: "valid",
+      owner: SAMPLE_OWNER,
+    })
+  })
+})

package/examples/next-ssr/src/server/parse-owner.ts

@@ -0,0 +1,34 @@
+// Scenario 6 (with src/app/account/page.tsx): validating typed principal
+// text on the server.
+//
+// Rule: make a principal from user input with `principal(text)`, never a cast;
+// test the text with `isPrincipal(text)` first, and refuse what it rejects. A
+// search parameter is user input: anyone can type any URL. Refusing it here
+// shows a message in the page; nothing is sent to a canister, and nothing
+// throws during the render.
+import { isPrincipal, principal, type Principal } from "@meantjs/schema"
+
+/** What the `owner` search parameter holds. */
+export type OwnerInput =
+  | { readonly kind: "empty" }
+  | { readonly kind: "invalid"; readonly text: string; readonly reason: string }
+  | { readonly kind: "valid"; readonly text: string; readonly owner: Principal }
+
+/**
+ * Reads a search parameter as an owner principal. `?owner=a&owner=b` uses the
+ * first; surrounding spaces are dropped.
+ */
+export function parseOwner(value: string | string[] | undefined): OwnerInput {
+  const text = (Array.isArray(value) ? value[0] : value)?.trim() ?? ""
+  if (text === "") return { kind: "empty" }
+  if (!isPrincipal(text)) {
+    return {
+      kind: "invalid",
+      text,
+      reason:
+        `"${text}" is not a principal. Principal text is lowercase groups of five ` +
+        "characters joined by dashes, with a checksum in front: rkp4c-7iaaa-aaaaa-aaaca-cai is one.",
+    }
+  }
+  return { kind: "valid", text, owner: principal(text) }
+}

package/examples/next-ssr/src/server/prefetch-ledgers.test.ts

@@ -0,0 +1,137 @@
+// Scenarios 1, 3 and 8 on the server: the prefetch reads into the client it is
+// given and only that one, as the anonymous caller, by `{ id }`; its
+// dehydrated cache survives JSON exactly; a ledger that fails is reported and
+// left out, and the rest are not.
+import { isPrincipal } from "@meantjs/schema"
+import { dehydrate, hydrate, type QueryKey } from "@tanstack/react-query"
+import { afterEach, describe, expect, it } from "vitest"
+import { actor, type Actor } from "@/canisters/icrc1"
+import { LEDGERS, NOT_A_LEDGER } from "@/ledgers"
+import {
+  ANONYMOUS,
+  mockLedgers,
+  tokenOf,
+  type MockLedgers,
+} from "@/testing/mock-ledgers"
+import { prefetchLedgers, TOKEN_READS } from "./prefetch-ledgers"
+
+const clients: MockLedgers[] = []
+const newRequest = () => {
+  const test = mockLedgers()
+  clients.push(test)
+  return test
+}
+afterEach(() => {
+  for (const test of clients.splice(0)) test.client.dispose()
+})
+
+describe("prefetchLedgers", () => {
+  it("reads every token read of every ledger, by id, as the anonymous caller", async () => {
+    const server = newRequest()
+
+    const { state, failures } = await prefetchLedgers(server.client, LEDGERS)
+
+    expect(failures).toEqual({})
+    const reads = server.requests.filter(({ endpoint }) => endpoint === "query")
+    expect(reads).toHaveLength(LEDGERS.length * TOKEN_READS.length)
+    expect(new Set(reads.map(({ caller }) => caller))).toEqual(
+      new Set([ANONYMOUS])
+    )
+    expect(new Set(reads.map(({ canisterId }) => canisterId))).toEqual(
+      new Set(LEDGERS.map(({ id }) => id))
+    )
+    // Every query was dehydrated, keyed by network and caller.
+    expect(state.queries).toHaveLength(reads.length)
+    for (const query of state.queries) {
+      expect(query.state.status).toBe("success")
+      expect(query.queryKey.slice(0, 3)).toEqual([
+        "ic-reactor",
+        "ic",
+        ANONYMOUS,
+      ])
+    }
+  })
+
+  it("fills only the client it is given: each request's client starts empty", async () => {
+    const first = newRequest()
+    const second = newRequest()
+
+    await prefetchLedgers(first.client, LEDGERS)
+
+    expect(second.client.queryClient.getQueryCache().getAll()).toHaveLength(0)
+    expect(second.requests).toHaveLength(0)
+    const { state } = await prefetchLedgers(second.client, LEDGERS)
+    expect(state.queries).toHaveLength(LEDGERS.length * TOKEN_READS.length)
+    expect(second.requests.length).toBe(first.requests.length)
+  })
+
+  it("dehydrates to JSON that hydrates into another client exactly, with nothing fetched", async () => {
+    const server = newRequest()
+    const { state } = await prefetchLedgers(server.client, LEDGERS)
+
+    // What the page hands the browser is JSON: through React's payload, or
+    // any other channel.
+    const json = JSON.stringify(state)
+    const browser = newRequest()
+    hydrate(browser.client.queryClient, JSON.parse(json))
+
+    for (const ref of LEDGERS) {
+      const token = tokenOf(ref)
+      const ledger = browser.client.canister<Actor>(actor, { id: ref.id })
+      // The browser finds each value under the key its own options build.
+      const { queryClient } = browser.client
+      const cached = <K extends QueryKey>(options: { queryKey: K }) =>
+        queryClient.getQueryData(options.queryKey)
+      const read = browser.client.queryOptions
+
+      const supply = cached(read(ledger, "icrc1_total_supply"))
+      expect(typeof supply).toBe("bigint")
+      expect(supply).toBe(token.supply) // 2^70 + i: past 2^53
+      expect(cached(read(ledger, "icrc1_fee"))).toBe(token.fee)
+      expect(cached(read(ledger, "icrc1_decimals"))).toBe(token.decimals)
+
+      const minter = cached(read(ledger, "icrc1_minting_account"))
+      expect(minter?.owner).toBe(token.minter.owner)
+      expect(isPrincipal(minter?.owner)).toBe(true)
+      expect(minter?.subaccount).toBeInstanceOf(Uint8Array)
+      expect(minter?.subaccount).toStrictEqual(token.minter.subaccount)
+
+      expect(cached(read(ledger, "icrc1_metadata"))).toStrictEqual([
+        ["icrc1:fee", { tag: "Nat", value: token.fee }],
+        ["test:int", { tag: "Int", value: -(2n ** 64n) }],
+        ["test:blob", { tag: "Blob", value: token.blob }],
+      ])
+    }
+    expect(browser.requests).toHaveLength(0)
+  })
+
+  it("needs the client's serializer: the raw cache is not JSON", async () => {
+    const server = newRequest()
+    await prefetchLedgers(server.client, LEDGERS)
+
+    // Without the client's dehydrate defaults, the bigints stay bigints.
+    const raw = dehydrate(server.client.queryClient, {
+      serializeData: (data: unknown) => data,
+    })
+    expect(() => JSON.stringify(raw)).toThrow(TypeError)
+  })
+
+  it("reports a canister that is not a ledger, leaves it out, and keeps the others", async () => {
+    const server = newRequest()
+
+    const { state, failures } = await prefetchLedgers(server.client, [
+      ...LEDGERS,
+      NOT_A_LEDGER,
+    ])
+
+    expect(Object.keys(failures)).toEqual([NOT_A_LEDGER.id])
+    expect(failures[NOT_A_LEDGER.id]).toMatchObject({
+      kind: "rejected",
+      rejectCode: 5,
+    })
+    const dehydratedIds = new Set(
+      state.queries.map(({ queryKey }) => queryKey[3])
+    )
+    expect(dehydratedIds).toEqual(new Set(LEDGERS.map(({ id }) => id)))
+  })
+})