@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/packages/core/tests/fixtures/skippable.ts

@@ -0,0 +1,33 @@
+// Generated by Meant from a Meant Contract. Do not edit.
+import * as $ from "@meantjs/schema";
+
+export type Empty = Record<string, never>;
+const $Empty: $.Schema<Empty> = $.c.rec(() => $.c.unit());
+export { $Empty as Empty };
+
+export type Options = { limit: bigint | null; prefix: string | null };
+const $Options: $.Schema<Options> = $.c.rec(() => $.c.record({ limit: $.c.opt($.c.nat), prefix: $.c.opt($.c.text) }));
+export { $Options as Options };
+
+/**
+ * One method per shape of variables `skipToken` might be assignable to: an
+ * empty record, a record of opts alone, an opt, reserved, null, and no
+ * arguments. Only a read whose variables cannot hold `skipToken` gives
+ * options without `SkipToken` in their `queryFn` type.
+ */
+const $actor: $.Schema<$.Principal> = $.c.rec(() => $.c.service({ no_args: $.c.func([], [$.c.nat], "query"), maybe_nat: $.c.func([$.c.opt($.c.nat)], [$.c.nat], "query"), nothing_at_all: $.c.func([$.c.null], [$.c.nat], "query"), only_opts: $.c.func([$Options], [$.c.nat], "query"), empty_record: $.c.func([$.c.unit()], [$.c.nat], "query"), anything: $.c.func([$.c.reserved], [$.c.nat], "query") }));
+/**
+ * One method per shape of variables `skipToken` might be assignable to: an
+ * empty record, a record of opts alone, an opt, reserved, null, and no
+ * arguments. Only a read whose variables cannot hold `skipToken` gives
+ * options without `SkipToken` in their `queryFn` type.
+ */
+export type Actor = {
+  no_args: (() => Promise<bigint>) & $.WithMode<"query">;
+  maybe_nat: ((arg0: bigint | null) => Promise<bigint>) & $.WithMode<"query">;
+  nothing_at_all: ((arg0: null) => Promise<bigint>) & $.WithMode<"query">;
+  only_opts: ((arg0: Options) => Promise<bigint>) & $.WithMode<"query">;
+  empty_record: ((arg0: Record<string, never>) => Promise<bigint>) & $.WithMode<"query">;
+  anything: ((arg0: unknown) => Promise<bigint>) & $.WithMode<"query">;
+};
+export { $actor as actor };

package/packages/core/tests/func.test.ts

@@ -0,0 +1,154 @@
+/**
+ * `client.func()`: a func reference from a reply, such as a ledger's archive
+ * callback, called through the same path as a canister's methods.
+ */
+import { afterEach, describe, expect, it, vi } from "vitest"
+import { c, principal, type Principal } from "@meantjs/schema"
+import { Ed25519KeyIdentity } from "@icp-sdk/core/identity"
+import {
+  ARCHIVE,
+  LEDGER,
+  canisterRequests,
+  clientAs,
+  replicaWith,
+  serve,
+} from "./canister-helpers.js"
+import * as archive from "./fixtures/archive.js"
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+const reader = Ed25519KeyIdentity.generate()
+
+/** The blocks of a range, as the archive holds them. */
+const blocksOf = (start: bigint, length: bigint): archive.BlockRange => ({
+  blocks: Array.from({ length: Number(length) }, (_, i) => ({
+    index: start + BigInt(i),
+    memo: new Uint8Array([i]),
+  })),
+})
+
+/**
+ * The archive canister's interface, as the ledger's func types describe it:
+ * a service's methods are func schemas, so the generated ones serve as is.
+ */
+const archiveService = c.service({
+  read_range: archive.QueryArchiveFn,
+  notify: archive.NotifyFn,
+})
+type ArchiveActor = {
+  read_range: (arg: archive.GetBlocksArgs) => Promise<archive.BlockRange>
+  notify: (text: string) => Promise<bigint>
+}
+
+/** A ledger whose blocks 0 to 9 are archived, and the archive that holds them. */
+function setup(identity: Parameters<typeof clientAs>[1] = reader) {
+  const callback = (method: string) => ({
+    principal: principal(ARCHIVE),
+    method,
+  })
+  const replica = replicaWith({
+    [LEDGER]: serve<archive.Actor>(archive.actor, {
+      get_blocks: () => ({
+        first_index: 10n,
+        blocks: [],
+        archived_blocks: [
+          { start: 0n, length: 10n, callback: callback("read_range") },
+        ],
+      }),
+      notify_hook: () => callback("notify"),
+    }),
+    [ARCHIVE]: serve<ArchiveActor>(archiveService, {
+      read_range: ([{ start, length }]) => blocksOf(start, length),
+      notify: ([text]) => BigInt(text.length),
+    }),
+  })
+  const client = clientAs(replica, identity)
+  return {
+    replica,
+    client,
+    ledger: client.canister<archive.Actor>(archive.actor, { id: LEDGER }),
+  }
+}
+
+const last = <T>(items: readonly T[]): T | undefined => items[items.length - 1]
+
+describe("a func reference", () => {
+  it("calls the canister and method it names, with the func type's arguments, results and mode", async () => {
+    const { replica, client, ledger } = setup()
+    const reply = await ledger.get_blocks({ start: 0n, length: 10n })
+    const [range] = reply.archived_blocks
+    const read = client.func<
+      (arg: archive.GetBlocksArgs) => Promise<archive.BlockRange>
+    >(archive.QueryArchiveFn, range.callback)
+
+    await expect(read({ start: range.start, length: 2n })).resolves.toEqual(
+      blocksOf(0n, 2n)
+    )
+    // A query func goes to the query endpoint, as the caller.
+    expect(last(canisterRequests(replica))).toMatchObject({
+      endpoint: "query",
+      canisterId: ARCHIVE,
+      methodName: "read_range",
+      caller: reader.getPrincipal().toText(),
+    })
+  })
+
+  it("sends an update func as a call, and refuses it for a caller who is not signed in", async () => {
+    const { replica, client, ledger } = setup()
+    const hook = await ledger.notify_hook()
+    const notify = client.func<(text: string) => Promise<bigint>>(
+      archive.NotifyFn,
+      hook
+    )
+    await expect(notify("hello")).resolves.toBe(5n)
+    expect(last(canisterRequests(replica))).toMatchObject({
+      endpoint: "call",
+      canisterId: ARCHIVE,
+      methodName: "notify",
+    })
+
+    const anonymous = setup("anonymous")
+    const refused = anonymous.client.func<(text: string) => Promise<bigint>>(
+      archive.NotifyFn,
+      hook
+    )
+    await expect(refused("hello")).rejects.toMatchObject({
+      kind: "unauthenticated",
+      canisterId: ARCHIVE,
+      method: "notify",
+    })
+    expect(canisterRequests(anonymous.replica)).toEqual([])
+  })
+
+  it("rejects arguments that do not match the func type, sending nothing", async () => {
+    const { replica, client } = setup()
+    const read = client.func<(arg: unknown) => Promise<unknown>>(
+      archive.QueryArchiveFn,
+      { principal: principal(ARCHIVE), method: "read_range" }
+    )
+    await expect(read({ start: 1 })).rejects.toMatchObject({
+      kind: "invalid_args",
+      mayHaveExecuted: false,
+    })
+    expect(canisterRequests(replica)).toEqual([])
+  })
+
+  it("throws a TypeError for a schema that is not a func, or a reference that is not one", () => {
+    const { client } = setup()
+    const ref = { principal: principal(ARCHIVE), method: "read_range" }
+    expect(() => client.func(archive.Block as never, ref)).toThrow(
+      /func schema/
+    )
+    expect(() =>
+      client.func(archive.QueryArchiveFn, {
+        ...ref,
+        principal: "AAAAA-AA" as Principal,
+      })
+    ).toThrow(/"AAAAA-AA" is not a canister's principal text/)
+    expect(() =>
+      client.func(archive.QueryArchiveFn, { ...ref, method: "" })
+    ).toThrow(TypeError)
+  })
+})

package/packages/core/tests/identity-attributes.test.ts

@@ -0,0 +1,214 @@
+/**
+ * Identity attributes the way the auth guide sends them (#914), on the fake
+ * replica: the nonce through a client built with an explicit
+ * `AnonymousIdentity`, since `identity: "anonymous"` refuses an update, and the
+ * finish call through a client built with an `AttributesIdentity`, which
+ * carries the attributes as the call's `sender_info`. The guide also reads the
+ * `AuthClient` its factory built right after `client.signIn()`, which needs the
+ * client to build its auth and ask it to sign in before the call returns.
+ *
+ * Internet Identity itself is not in the loop: the attributes are fixed bytes,
+ * and the fake canister checks only who called. What a canister checks of
+ * them is DFINITY's `identity-attributes` library's to test.
+ */
+import { AnonymousIdentity, Cbor } from "@icp-sdk/core/agent"
+import { AttributesIdentity, Ed25519KeyIdentity } from "@icp-sdk/core/identity"
+import { Principal } from "@icp-sdk/core/principal"
+import { afterEach, describe, expect, it, vi } from "vitest"
+import { createClient } from "../src/client.js"
+import { createFakeReplica } from "../src/testing/fake-replica.js"
+import { createTestAuth } from "../src/testing/test-auth.js"
+import { ANONYMOUS, clientAs, onPage, serve } from "./canister-helpers.js"
+import * as accounts from "./fixtures/accounts.js"
+
+const ACCOUNTS = "bkyz2-fmaaa-aaaaa-qaaaq-cai"
+const INTERNET_IDENTITY = "rdmx6-jaaaa-aaaaa-aaadq-cai"
+const NONCE = Uint8Array.from({ length: 32 }, (_, i) => i)
+const BUNDLE = {
+  data: Uint8Array.from([0x44, 0x49, 0x44, 0x4c]),
+  signature: Uint8Array.from([1, 2, 3, 4, 5]),
+}
+
+/** An accounts canister that issues {@link NONCE} and records its callers. */
+const accountsReplica = (
+  finish: accounts.Actor["_internet_identity_sign_in_finish"] extends () => Promise<
+    infer R
+  >
+    ? () => R
+    : never = () => ({ tag: "ok" })
+) => {
+  const callers: Array<{ method: string; caller: string }> = []
+  const replica = createFakeReplica({
+    canisters: {
+      [ACCOUNTS]: serve<accounts.Actor>(accounts.actor, {
+        _internet_identity_sign_in_start: (_, { caller }) => {
+          callers.push({ method: "start", caller })
+          return NONCE
+        },
+        _internet_identity_sign_in_finish: (_, { caller }) => {
+          callers.push({ method: "finish", caller })
+          return finish()
+        },
+      }),
+    },
+  })
+  return { replica, callers }
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+describe("identity attributes, as the auth guide sends them", () => {
+  it("mints the nonce through a client built with an explicit AnonymousIdentity, which identity: anonymous refuses", async () => {
+    const { replica, callers } = accountsReplica()
+    const readOnly = clientAs(replica, "anonymous")
+    await expect(
+      readOnly
+        .canister<accounts.Actor>(accounts.actor, { id: ACCOUNTS })
+        ._internet_identity_sign_in_start()
+    ).rejects.toMatchObject({
+      kind: "unauthenticated",
+      code: "anonymous_write",
+    })
+    expect(callers).toEqual([])
+    readOnly.dispose()
+
+    const anonymous = clientAs(replica, new AnonymousIdentity())
+    const nonce = await anonymous
+      .canister<accounts.Actor>(accounts.actor, { id: ACCOUNTS })
+      ._internet_identity_sign_in_start()
+    // `requestAttributes` takes `() => Promise<Uint8Array>`: the blob comes
+    // back as one, not as an array of numbers.
+    expect(nonce).toBeInstanceOf(Uint8Array)
+    expect([...nonce]).toEqual([...NONCE])
+    expect(callers).toEqual([{ method: "start", caller: ANONYMOUS }])
+    anonymous.dispose()
+  })
+
+  it("sends an AttributesIdentity's attributes as the call's sender_info, signed by the identity it wraps", async () => {
+    const { replica, callers } = accountsReplica()
+    const inner = Ed25519KeyIdentity.generate()
+    const sent: Array<Record<string, unknown>> = []
+    const client = createClient({
+      network: { host: replica.host, rootKey: replica.rootKey },
+      fetch: async (input, init) => {
+        if (String(input).endsWith("/call")) {
+          const body = new Uint8Array(
+            await new Response(init?.body as BodyInit).arrayBuffer()
+          )
+          const envelope = Cbor.decode(body) as {
+            content: Record<string, unknown>
+          }
+          sent.push(envelope.content)
+        }
+        return replica.fetch(input, init)
+      },
+      identity: new AttributesIdentity({
+        inner,
+        attributes: BUNDLE,
+        signer: { canisterId: Principal.fromText(INTERNET_IDENTITY) },
+      }),
+    })
+    expect(client.authState()).toMatchObject({
+      status: "signed-in",
+      principal: inner.getPrincipal().toText(),
+    })
+
+    const viaClient = client.canister<accounts.Actor>(accounts.actor, {
+      id: ACCOUNTS,
+    })
+    await viaClient._internet_identity_sign_in_finish()
+
+    // The replica checked the signature over the content, sender_info
+    // included, and saw the wrapped identity as the caller.
+    expect(callers).toEqual([
+      { method: "finish", caller: inner.getPrincipal().toText() },
+    ])
+    expect(replica.requests.filter((r) => r.refused)).toEqual([])
+    expect(sent).toHaveLength(1)
+    const info = sent[0]?.sender_info as Record<string, Uint8Array> | undefined
+    expect(info).toBeDefined()
+    expect([...(info?.signer ?? [])]).toEqual([
+      ...Principal.fromText(INTERNET_IDENTITY).toUint8Array(),
+    ])
+    expect([...(info?.info ?? [])]).toEqual([...BUNDLE.data])
+    expect([...(info?.sig ?? [])]).toEqual([...BUNDLE.signature])
+    client.dispose()
+  })
+
+  it("resolves accepted attributes, rejects refused ones as a canister_err that names the library's error, and a trap as rejected", async () => {
+    const answers: Array<
+      | { tag: "ok" }
+      | { tag: "err"; value: accounts.IdentityAttributesError }
+      | "trap"
+    > = [
+      { tag: "ok" },
+      {
+        tag: "err",
+        value: { tag: "Stale", value: { ageNs: 400_000_000_000n } },
+      },
+      "trap",
+    ]
+    const { replica } = accountsReplica(() => {
+      const answer = answers.shift() ?? { tag: "ok" }
+      // The library traps on a signer it does not trust.
+      if (answer === "trap") throw new Error("untrusted attribute signer")
+      return answer
+    })
+    const client = clientAs(
+      replica,
+      new AttributesIdentity({
+        inner: Ed25519KeyIdentity.generate(),
+        attributes: BUNDLE,
+        signer: { canisterId: Principal.fromText(INTERNET_IDENTITY) },
+      })
+    )
+    const viaClient = client.canister<accounts.Actor>(accounts.actor, {
+      id: ACCOUNTS,
+    })
+    // `variant { ok; err }`, as a Motoko `Result` is spelled: ok resolves.
+    await expect(viaClient._internet_identity_sign_in_finish()).resolves.toBe(
+      null
+    )
+    await expect(
+      viaClient._internet_identity_sign_in_finish()
+    ).rejects.toMatchObject({
+      kind: "canister_err",
+      err: { tag: "Stale", value: { ageNs: 400_000_000_000n } },
+    })
+    await expect(
+      viaClient._internet_identity_sign_in_finish()
+    ).rejects.toMatchObject({ kind: "rejected", rejectCode: 5 })
+    client.dispose()
+  })
+
+  it("builds its auth and asks it to sign in before signIn() returns, so the guide reads the AuthClient right after", async () => {
+    onPage()
+    const { replica } = accountsReplica()
+    const auth = createTestAuth({ seed: 1 })
+    void auth.signOut()
+    const events: string[] = []
+    const client = createClient({
+      network: { host: replica.host, rootKey: replica.rootKey },
+      fetch: replica.fetch,
+      auth: () => {
+        events.push("factory")
+        return {
+          ...auth,
+          signIn: (options?: unknown) => {
+            events.push("signIn")
+            return auth.signIn(options as number | undefined)
+          },
+        }
+      },
+    })
+    expect(events).toEqual([])
+
+    const signedIn = client.signIn()
+    expect(events).toEqual(["factory", "signIn"])
+    await signedIn
+    expect(client.authState().status).toBe("signed-in")
+    client.dispose()
+  })
+})

package/packages/core/tests/keys.test.ts

@@ -0,0 +1,289 @@
+/**
+ * Query keys (DECISIONS Q5): who the read is made as, which canister, which
+ * method, and the Candid encoding of the arguments, with the tags that stand
+ * in for arguments that are skipped or do not encode and for a canister name
+ * that does not resolve.
+ */
+import { readFileSync } from "node:fs"
+import { afterEach, describe, expect, it, vi } from "vitest"
+import { principal, serviceMethods } from "@meantjs/schema"
+import { encodeArgs } from "@meantjs/schema/codec"
+import { schemaFromContract } from "@meantjs/schema/contract"
+import { Ed25519KeyIdentity } from "@icp-sdk/core/identity"
+import {
+  QueryClient,
+  dehydrate,
+  hydrate,
+  skipToken,
+} from "@tanstack/query-core"
+import { toHex } from "../src/keys.js"
+import { createTestAuth } from "../src/testing/test-auth.js"
+import {
+  ANONYMOUS,
+  FEE,
+  LEDGER,
+  SHAPES,
+  clientAs,
+  clientWithAuth,
+  ledgerCanister,
+  replicaWith,
+  serve,
+} from "./canister-helpers.js"
+import * as icrc1 from "./fixtures/icrc1.js"
+import * as shapes from "./fixtures/shapes.js"
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+const alice = Ed25519KeyIdentity.generate()
+const ALICE = principal(alice.getPrincipal().toText())
+const account = { owner: ALICE, subaccount: null }
+
+const hexOf = (
+  schemas: Parameters<typeof encodeArgs>[0],
+  values: unknown[]
+): string => {
+  const encoded = encodeArgs(schemas, values)
+  if (!encoded.ok) throw new Error("the fixture does not encode")
+  return toHex(encoded.bytes)
+}
+
+function setup() {
+  const replica = replicaWith({})
+  const client = clientAs(replica, alice)
+  return {
+    replica,
+    client,
+    ledger: client.canister<icrc1.Actor>(icrc1.actor, { id: LEDGER }),
+    canister: client.canister<shapes.Actor>(shapes.actor, { id: SHAPES }),
+  }
+}
+
+describe("a read's key", () => {
+  it("is ic-reactor, the network, the caller, the canister, the method and the hex of the encoded arguments", () => {
+    const { client, ledger } = setup()
+    const key = client.queryOptions(
+      ledger,
+      "icrc1_balance_of",
+      account
+    ).queryKey
+    expect(key).toEqual([
+      "ic-reactor",
+      client.network,
+      ALICE,
+      LEDGER,
+      "icrc1_balance_of",
+      hexOf([icrc1.Account], [account]),
+    ])
+    expect(client.queryKey(ledger, "icrc1_balance_of", account)).toEqual(key)
+  })
+
+  it("is the same whatever the order of a record's keys", () => {
+    const { client, ledger } = setup()
+    expect(
+      client.queryKey(ledger, "icrc1_balance_of", {
+        subaccount: null,
+        owner: ALICE,
+      })
+    ).toEqual(client.queryKey(ledger, "icrc1_balance_of", account))
+  })
+
+  it("is the same for the generated schema and for the one schemaFromContract loads", () => {
+    const envelope: unknown = JSON.parse(
+      readFileSync(
+        new URL("./fixtures/icrc1.envelope.json", import.meta.url),
+        "utf8"
+      )
+    )
+    const loaded = schemaFromContract(envelope)
+    if (!loaded.ok || loaded.actor === undefined) {
+      throw new Error("the envelope does not load")
+    }
+    const { client, ledger } = setup()
+    const fromContract = client.canister<icrc1.Actor>(loaded.actor, {
+      id: LEDGER,
+    })
+    expect(fromContract).not.toBe(ledger)
+    for (const [method, vars] of [
+      ["icrc1_balance_of", account],
+      ["icrc1_fee", undefined],
+      [
+        "icrc1_transfer",
+        {
+          to: account,
+          amount: 5n,
+          fee: null,
+          memo: new Uint8Array([1]),
+          from_subaccount: null,
+          created_at_time: 1n,
+        },
+      ],
+    ] as const) {
+      expect(client.queryKey(fromContract, method, vars as never)).toEqual(
+        client.queryKey(ledger, method, vars as never)
+      )
+    }
+  })
+
+  it("holds whoever is signed in when it is built", async () => {
+    const replica = replicaWith({})
+    const auth = createTestAuth({ seed: 1, signedIn: false })
+    const client = clientWithAuth(replica, auth)
+    const ledger = client.canister<icrc1.Actor>(icrc1.actor, { id: LEDGER })
+    // queryOptions and queryKey build the same key, with the caller of now.
+    const caller = () => {
+      const key = client.queryOptions(
+        ledger,
+        "icrc1_balance_of",
+        account
+      ).queryKey
+      expect(client.queryKey(ledger, "icrc1_balance_of", account)).toEqual(key)
+      expect(client.queryKey(ledger)[2]).toBe(key[2])
+      return key[2]
+    }
+    expect(caller()).toBe(ANONYMOUS)
+    await auth.signIn()
+    const first = client.caller()
+    expect(caller()).toBe(first)
+    auth.switchTo(2)
+    expect(caller()).toBe(client.caller())
+    expect(caller()).not.toBe(first)
+    await auth.signOut()
+    expect(caller()).toBe(ANONYMOUS)
+  })
+
+  it("ends in certified for a certified canister, and its prefixes match both", () => {
+    const { client, canister } = setup()
+    const certified = client.canister<shapes.Actor>(shapes.actor, {
+      id: SHAPES,
+      certified: true,
+    })
+    const plain = client.queryKey(canister, "one", 1n)
+    const sure = client.queryKey(certified, "one", 1n)
+    expect(sure).toEqual([...plain, "certified"])
+    expect(client.queryOptions(certified, "one", 1n).queryKey).toEqual(sure)
+    expect(client.queryKey(certified, "one")).toEqual(
+      client.queryKey(canister, "one")
+    )
+  })
+
+  it("is cut short to a prefix when the arguments or the method are left out", () => {
+    const { client, canister } = setup()
+    const full = client.queryKey(canister, "pair", [1n, "x"])
+    expect(client.queryKey(canister, "pair")).toEqual(full.slice(0, 5))
+    expect(client.queryKey(canister)).toEqual(full.slice(0, 4))
+    expect(client.queryKey(canister, "nothing", undefined)).toEqual([
+      ...full.slice(0, 4),
+      "nothing",
+      hexOf([], []),
+    ])
+  })
+
+  it("is the read's whole key for a method without arguments, with or without the vars", async () => {
+    const replica = replicaWith({ [LEDGER]: ledgerCanister(new Map()) })
+    const client = clientAs(replica, alice)
+    const ledger = client.canister<icrc1.Actor>(icrc1.actor, { id: LEDGER })
+    const fee = client.queryOptions(ledger, "icrc1_fee")
+    expect(client.queryKey(ledger, "icrc1_fee")).toEqual(fee.queryKey)
+    expect(client.queryKey(ledger, "icrc1_fee", undefined)).toEqual(
+      fee.queryKey
+    )
+    // What a cache read and write are handed: the key must be whole, as
+    // getQueryData and setQueryData match it exactly.
+    await client.queryClient.fetchQuery(fee)
+    expect(
+      client.queryClient.getQueryData(client.queryKey(ledger, "icrc1_fee"))
+    ).toBe(FEE)
+    client.queryClient.setQueryData(client.queryKey(ledger, "icrc1_fee"), 1n)
+    expect(client.queryClient.getQueryData(fee.queryKey)).toBe(1n)
+    expect(
+      client.queryClient.getQueryCache().findAll({ queryKey: fee.queryKey })
+    ).toHaveLength(1)
+  })
+
+  it("takes a two-argument method's variables as the tuple", () => {
+    const { client, canister } = setup()
+    const pair = serviceMethods(shapes.actor).get("pair")
+    if (pair === undefined) throw new Error("the fixture has no pair method")
+    const key = client.queryKey(canister, "pair", [1n, "x"])
+    expect(key[key.length - 1]).toBe(hexOf(pair.args, [1n, "x"]))
+  })
+
+  it("tags skipped arguments with $skip", () => {
+    const { client, ledger } = setup()
+    const options = client.queryOptions(ledger, "icrc1_balance_of", skipToken)
+    expect(options.queryKey.slice(4)).toEqual(["icrc1_balance_of", "$skip"])
+    expect(options.queryFn).toBe(skipToken)
+    expect(
+      client.queryKey(ledger, "icrc1_balance_of", skipToken as never)
+    ).toEqual(options.queryKey)
+  })
+
+  it("tags arguments that do not encode with $invalid and a stable text of them, without throwing", () => {
+    const { client, canister } = setup()
+    const cyclic: Record<string, unknown> = {
+      n: 1n,
+      bytes: new Uint8Array([255]),
+    }
+    cyclic.self = cyclic
+    const odd = [1, cyclic, undefined, Symbol("s"), () => 0, -0, NaN]
+    const keyOf = (vars: unknown) =>
+      client.queryOptions(canister, "one", vars as bigint).queryKey
+    const key = keyOf(odd)
+    expect(key.slice(4, 6)).toEqual(["one", "$invalid"])
+    expect(key).toHaveLength(7)
+    expect(keyOf(odd)).toEqual(key)
+    expect(keyOf(2)).not.toEqual(keyOf(3))
+    expect(keyOf({ b: 1, a: 2 })).toEqual(keyOf({ a: 2, b: 1 }))
+    // A key is JSON, so TanStack can hash it.
+    expect(() => JSON.stringify(key)).not.toThrow()
+  })
+
+  it("holds $unresolved:<name> for a { name } the cookie does not resolve", () => {
+    const { client } = setup()
+    const byName = client.canister<shapes.Actor>(shapes.actor, {
+      name: "backend",
+    })
+    expect(client.queryKey(byName, "one", 1n)[3]).toBe("$unresolved:backend")
+    expect(client.queryOptions(byName, "one", 1n).queryKey[3]).toBe(
+      "$unresolved:backend"
+    )
+  })
+
+  it("throws a TypeError for a method the service does not have, or a canister of another client", () => {
+    const { client, canister } = setup()
+    const other = setup().canister
+    expect(() => client.queryKey(canister, "nope" as "one")).toThrow(
+      /has no method "nope"/
+    )
+    expect(() => client.queryKey(other, "one", 1n)).toThrow(/another client/)
+    expect(() => client.queryKey({} as typeof canister)).toThrow(
+      /made by client.canister/
+    )
+  })
+})
+
+describe("a read's data", () => {
+  it("survives dehydration as JSON, nat8 as a number and nat as a bigint", async () => {
+    const replica = replicaWith({
+      [SHAPES]: serve<shapes.Actor>(shapes.actor, {
+        small: ([n]) => n + 1,
+        one: ([n]) => n + 1n,
+      }),
+    })
+    const server = clientAs(replica, "anonymous")
+    const canister = server.canister<shapes.Actor>(shapes.actor, { id: SHAPES })
+    const small = server.queryOptions(canister, "small", 7)
+    const one = server.queryOptions(canister, "one", 7n)
+    await server.queryClient.fetchQuery(small)
+    await server.queryClient.fetchQuery(one)
+    const wire = JSON.stringify(dehydrate(server.queryClient))
+
+    const browser = clientAs(replica, "anonymous")
+    hydrate(browser.queryClient, JSON.parse(wire))
+    expect(browser.queryClient.getQueryData(small.queryKey)).toBe(8)
+    expect(browser.queryClient.getQueryData(one.queryKey)).toBe(8n)
+    expect(new QueryClient().getQueryData(small.queryKey)).toBeUndefined()
+  })
+})