@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/vite-wallet/src/transfer.test.ts

@@ -0,0 +1,178 @@
+// Scenario 5, without React: what typed text becomes, or why it is refused,
+// and what the ledger takes for a duplicate of what it becomes.
+import { isReactorError } from "@ic-reactor/core"
+import { afterEach, describe, expect, it } from "vitest"
+import {
+  actor as ledgerActor,
+  type Actor as Ledger,
+  type TransferArg,
+  type Icrc1TransferError,
+} from "./canisters/ledger.ts"
+import {
+  BOB,
+  clearEnvCookie,
+  createTestWallet,
+  FEE,
+  ICP,
+  SEED_1,
+  type TestWallet,
+} from "./test/test-wallet.tsx"
+import { describeTransferError, readTransferForm } from "./transfer.ts"
+import { ICP_LEDGER } from "./use-canisters.ts"
+
+const token = { symbol: "ICP", decimals: 8, fee: FEE }
+
+let wallet: TestWallet | undefined
+afterEach(() => {
+  wallet?.client.dispose()
+  wallet = undefined
+  clearEnvCookie()
+})
+
+describe("reading the transfer form", () => {
+  it("makes an argument with the fee shown, a memo and a created_at_time for deduplication", () => {
+    const memo = new Uint8Array(16).fill(7)
+    const read = readTransferForm(
+      { to: ` ${BOB} `, amount: "1.5" },
+      token,
+      1_700_000_000_000,
+      memo
+    )
+    expect(read).toEqual({
+      ok: true,
+      arg: {
+        to: { owner: BOB, subaccount: null },
+        amount: 150_000_000n,
+        fee: FEE,
+        memo,
+        from_subaccount: null,
+        created_at_time: 1_700_000_000_000_000_000n,
+      },
+    })
+  })
+
+  it("gives each transfer its own 16-byte memo, even in the same millisecond", () => {
+    const form = { to: BOB, amount: "1" }
+    const first = readTransferForm(form, token, 1_700_000_000_000)
+    const second = readTransferForm(form, token, 1_700_000_000_000)
+    if (!first.ok || !second.ok) throw new Error("refused")
+    expect(first.arg.memo).toHaveLength(16)
+    expect(second.arg.memo).toHaveLength(16)
+    expect(second.arg.memo).not.toEqual(first.arg.memo)
+  })
+
+  it.each([
+    ["not-a-principal", "1", "to", "Not a principal."],
+    [
+      BOB,
+      "1e3",
+      "amount",
+      'Write plain digits with at most one "." (no exponent, grouping or sign).',
+    ],
+    [
+      BOB,
+      "1,5",
+      "amount",
+      'Write plain digits with at most one "." (no exponent, grouping or sign).',
+    ],
+    [BOB, "-1", "amount", "An amount cannot be negative."],
+    [BOB, "0.000000001", "amount", "At most 8 decimals."],
+    [BOB, "0", "amount", "Send more than zero."],
+    [
+      BOB,
+      "",
+      "amount",
+      'Write plain digits with at most one "." (no exponent, grouping or sign).',
+    ],
+  ])("refuses to %s, amount %j", (to, amount, field, reason) => {
+    expect(readTransferForm({ to, amount }, token)).toEqual({
+      ok: false,
+      field,
+      reason,
+    })
+  })
+
+  it("takes amounts past what a JavaScript number holds exactly", () => {
+    const read = readTransferForm(
+      { to: BOB, amount: "92233720368.54775807" },
+      token
+    )
+    expect(read.ok && read.arg.amount).toBe(9_223_372_036_854_775_807n)
+  })
+})
+
+describe("the ledger's refusals, worded", () => {
+  const cases: [string, Icrc1TransferError, string][] = [
+    [
+      "InsufficientFunds",
+      { tag: "InsufficientFunds", value: { balance: 50_000_000n } },
+      "Insufficient funds: the balance is 0.5 ICP, less than the amount plus the fee.",
+    ],
+    [
+      "BadFee",
+      { tag: "BadFee", value: { expected_fee: 20_000n } },
+      "Bad fee: the ledger now charges 0.0002 ICP. Nothing moved; send again to pay that fee.",
+    ],
+    [
+      "Duplicate",
+      { tag: "Duplicate", value: { duplicate_of: 7n } },
+      "Duplicate of block 7: this exact transfer went through already, and was not made twice.",
+    ],
+    [
+      "TooOld",
+      { tag: "TooOld" },
+      "Too old: created_at_time is outside the ledger's deduplication window.",
+    ],
+    [
+      "GenericError",
+      { tag: "GenericError", value: { error_code: 3n, message: "paused" } },
+      "Error 3: paused",
+    ],
+  ]
+  it.each(cases)("%s", (_tag, err, sentence) => {
+    expect(describeTransferError(err, token)).toBe(sentence)
+  })
+})
+
+describe("deduplication on the ledger", () => {
+  const arg = (read: ReturnType<typeof readTransferForm>): TransferArg => {
+    if (!read.ok) throw new Error(`refused: ${read.reason}`)
+    return read.arg
+  }
+
+  it("executes two transfers of the same amount made in the same millisecond, and answers a re-send Duplicate of its own block", async () => {
+    const made = createTestWallet()
+    wallet = made
+    made.setBalance(SEED_1, 7n * ICP)
+    const ledger = made.client.canister<Ledger>(ledgerActor, { id: ICP_LEDGER })
+    const nowMs = Date.now()
+    const form = { to: BOB, amount: "1" }
+    const first = arg(readTransferForm(form, token, nowMs))
+    const second = arg(readTransferForm(form, token, nowMs))
+
+    // The first one runs (block 0), but its reply is lost.
+    made.dropNextReply()
+    const lost = await ledger.icrc1_transfer(first).then(
+      () => undefined,
+      (error: unknown) => error
+    )
+    expect(isReactorError(lost) && lost.mayHaveExecuted).toBe(true)
+
+    // The second transfer and the first one's re-send, at once.
+    const [paid, resent] = await Promise.allSettled([
+      ledger.icrc1_transfer(second),
+      ledger.icrc1_transfer(first),
+    ])
+    // The second is a transfer of its own, not the first one's duplicate.
+    expect(paid).toEqual({ status: "fulfilled", value: 1n })
+    // The re-send of the first is answered Duplicate, with the first's block.
+    expect(resent.status).toBe("rejected")
+    const err = resent.status === "rejected" ? resent.reason : undefined
+    expect(
+      isReactorError(err) && err.kind === "canister_err" && err.err
+    ).toEqual({ tag: "Duplicate", value: { duplicate_of: 0n } })
+    // Two transfers paid, each once.
+    expect(made.balanceOf(BOB)).toBe(2n * ICP)
+    expect(made.balanceOf(SEED_1)).toBe(5n * ICP - 2n * FEE)
+  })
+})

package/examples/vite-wallet/src/transfer.ts

@@ -0,0 +1,110 @@
+// Scenario 5, the part without React: typed text to an `icrc1_transfer`
+// argument or the reason it is refused before anything is sent, and what each
+// `Err` of the ledger means.
+import { isPrincipal, principal } from "@meantjs/schema"
+import { parseUnits } from "@ic-reactor/core"
+import type { TransferArg, Icrc1TransferError } from "./canisters/ledger.ts"
+import { showAmount, type Token } from "./token.ts"
+
+export interface TransferForm {
+  /** The recipient's principal, as typed. */
+  readonly to: string
+  /** The amount in tokens, as typed: "1.5". */
+  readonly amount: string
+}
+
+export type ReadTransfer =
+  | { readonly ok: true; readonly arg: TransferArg }
+  | {
+      readonly ok: false
+      readonly field: keyof TransferForm
+      readonly reason: string
+    }
+
+/**
+ * The transfer `form` asks for, or the first field that is refused.
+ *
+ * - The amount goes through `parseUnits`, which takes only plain decimal text
+ *   with at most `token.decimals` fraction digits: "1e3", "1,5" and "-1" are
+ *   refused here, and nothing reaches the ledger.
+ * - `fee` is the fee the person was shown. Had the ledger's fee changed since,
+ *   it answers `BadFee` instead of charging the new one silently.
+ * - `created_at_time` (`nowMs`, in nanoseconds) makes the transfer
+ *   deduplicated: the same argument sent again by the same account is
+ *   answered `Duplicate`, and pays nothing twice.
+ * - `memo` is this transfer's own, 16 random bytes: the ledger takes two
+ *   arguments for one only when every field matches, so two different
+ *   transfers of the same amount made in the same millisecond are not taken
+ *   for each other's `Duplicate`. Read the form once per transfer, and re-send
+ *   the argument it gave, memo included.
+ */
+export function readTransferForm(
+  form: TransferForm,
+  token: Pick<Token, "decimals" | "fee">,
+  nowMs: number = Date.now(),
+  memo: Uint8Array = newMemo()
+): ReadTransfer {
+  const to = form.to.trim()
+  if (!isPrincipal(to)) {
+    return { ok: false, field: "to", reason: "Not a principal." }
+  }
+  let amount: bigint
+  try {
+    amount = parseUnits(form.amount, token.decimals)
+  } catch (error) {
+    return {
+      ok: false,
+      field: "amount",
+      reason:
+        error instanceof RangeError
+          ? form.amount.trim().startsWith("-")
+            ? "An amount cannot be negative."
+            : `At most ${token.decimals} decimals.`
+          : 'Write plain digits with at most one "." (no exponent, grouping or sign).',
+    }
+  }
+  if (amount === 0n) {
+    return { ok: false, field: "amount", reason: "Send more than zero." }
+  }
+  return {
+    ok: true,
+    arg: {
+      to: { owner: principal(to), subaccount: null },
+      amount,
+      fee: token.fee,
+      memo,
+      from_subaccount: null,
+      created_at_time: BigInt(nowMs) * 1_000_000n,
+    },
+  }
+}
+
+/** A memo of its own for one transfer: 16 bytes from `crypto.getRandomValues`. */
+export function newMemo(): Uint8Array {
+  return crypto.getRandomValues(new Uint8Array(16))
+}
+
+/** What the ledger's `Err` means, in a sentence. */
+export function describeTransferError(
+  err: Icrc1TransferError,
+  token: Token
+): string {
+  switch (err.tag) {
+    case "InsufficientFunds":
+      return `Insufficient funds: the balance is ${showAmount(err.value.balance, token)}, less than the amount plus the fee.`
+    case "BadFee":
+      return `Bad fee: the ledger now charges ${showAmount(err.value.expected_fee, token)}. Nothing moved; send again to pay that fee.`
+    case "Duplicate":
+      return `Duplicate of block ${err.value.duplicate_of}: this exact transfer went through already, and was not made twice.`
+    case "TooOld":
+      return "Too old: created_at_time is outside the ledger's deduplication window."
+    case "CreatedInFuture":
+      return "Created in the future: the ledger's clock is behind created_at_time."
+    case "BadBurn":
+      return `Bad burn: burn at least ${showAmount(err.value.min_burn_amount, token)}.`
+    case "TemporarilyUnavailable":
+      return "The ledger is temporarily unavailable."
+    case "GenericError":
+      return `Error ${err.value.error_code}: ${err.value.message}`
+  }
+}

package/examples/vite-wallet/src/use-canisters.ts

@@ -0,0 +1,49 @@
+// Scenario 1: the two canisters, by name and by id.
+//
+// `client.canister()` returns the same object for the same service and
+// target, so components call this in render.
+import type { Canister } from "@ic-reactor/core"
+import { useClient } from "@ic-reactor/react"
+import {
+  actor as backendActor,
+  type Actor as Backend,
+} from "./canisters/backend.ts"
+import {
+  actor as ledgerActor,
+  type Actor as Ledger,
+} from "./canisters/ledger.ts"
+
+/** The ICP ledger: the NNS installs it at its mainnet id on a local network too. */
+export const ICP_LEDGER = "ryjl3-tyaaa-aaaaa-aaaba-cai"
+
+export interface WalletCanisters {
+  readonly backend: Canister<Backend>
+  /**
+   * The same backend, with its query replies certified: the address book is
+   * read through it, because a contact decides where a payment goes.
+   */
+  readonly certifiedBackend: Canister<Backend>
+  readonly ledger: Canister<Ledger>
+}
+
+export function useCanisters(): WalletCanisters {
+  const client = useClient()
+  return {
+    // `icp deploy` picks the backend's id, and a fresh network picks another
+    // one: the ic_env cookie carries it as PUBLIC_CANISTER_ID:backend, read
+    // each time a call or a key is built.
+    backend: client.canister<Backend>(backendActor, { name: "backend" }),
+    // A plain query is answered and signed by one replica. A read that
+    // decides where value goes, or what a person approves, is certified
+    // instead: it is sent as a replicated call, and the subnet's certificate
+    // is checked. That costs what an update costs (as long, and the canister
+    // pays cycles), so only those reads use it.
+    certifiedBackend: client.canister<Backend>(backendActor, {
+      name: "backend",
+      certified: true,
+    }),
+    // An id that never changes is written down: it needs no cookie, and
+    // works where there is none (a server, a script).
+    ledger: client.canister<Ledger>(ledgerActor, { id: ICP_LEDGER }),
+  }
+}

package/examples/vite-wallet/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "erasableSyntaxOnly": true,
+    "allowImportingTsExtensions": true,
+    "types": ["vite/client", "node"]
+  },
+  "include": ["src", "scripts", "vite.config.ts", "vitest.config.ts"]
+}

package/examples/vite-wallet/vite.config.ts

@@ -0,0 +1,47 @@
+import { icReactor } from "@ic-reactor/vite-plugin"
+import react from "@vitejs/plugin-react"
+import { defineConfig } from "vite"
+
+export default defineConfig({
+  plugins: [
+    react(),
+    icReactor({
+      // Each canister by its name in icp.yaml, which is also its name in the
+      // ic_env cookie. The plugin writes src/canisters/<did name>.ts (and its
+      // envelope) from each .did when `vite dev` or `vite build` starts, and
+      // again when a .did changes. The files are committed too, so
+      // `pnpm gen:check` fails a stale copy.
+      canisters: {
+        // A project canister: under `vite dev` and `vite preview` the plugin
+        // asks `icp` for its id and puts it in the cookie.
+        backend: { didFile: "backend/backend.did" },
+        // Not a project canister, so its id is given: `icp` has none to report.
+        // ledger.did is the projection of the mainnet ledger's interface
+        // (`network` defaults to "ic") to the methods the wallet calls, and
+        // every type they reach. It is committed, so the plugin reads it and
+        // fetches nothing: builds work offline. Were it missing, the plugin
+        // would fetch and project it again, and `IC_REACTOR_FETCH=ledger` does
+        // that on purpose. `IC_REACTOR_VERIFY=ledger` checks it against the
+        // live ledger.
+        ledger: {
+          didFile: "ledger.did",
+          canisterId: "ryjl3-tyaaa-aaaaa-aaaba-cai",
+          methods: [
+            "icrc1_balance_of",
+            "icrc1_decimals",
+            "icrc1_fee",
+            "icrc1_symbol",
+            "icrc1_transfer",
+          ],
+        },
+      },
+      // On by default, written out: set the ic_env cookie on every page load
+      // and proxy /api to the network `icp network status` reports.
+      injectEnvironment: true,
+    }),
+  ],
+  server: { port: 5175, strictPort: true },
+  preview: { port: 5185, strictPort: true },
+  // The IC agent, with its BLS certificate check, is most of the main chunk.
+  build: { chunkSizeWarningLimit: 700 },
+})

package/examples/vite-wallet/vitest.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from "vitest/config"
+
+// The tests run over the committed generated modules (`pnpm gen:check` keeps
+// them current), so they need neither the React plugin nor the generator, and
+// never a replica: every canister is a mock on the in-memory replica of
+// `createTestClient()`. jsdom gives them a page (http://localhost:3000), with
+// the cookie jar `{ name }` canisters are resolved from and sessionStorage.
+//
+// package.json pins jsdom to 30.0.1: jsdom 30.1 subclasses the global
+// `Iterator`, which StackBlitz's WebContainer does not define, so there every
+// test file fails to start with "ReferenceError: Iterator is not defined".
+export default defineConfig({
+  test: {
+    environment: "jsdom",
+    include: ["src/**/*.test.{ts,tsx}", "scripts/**/*.test.ts"],
+  },
+})

package/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@ic-reactor/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.0",
+  "description": "A placeholder that reserves the name. Install a 4.x version.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/B3Pay/ic-reactor.git",
+    "directory": "packages/mcp"
+  }
+}

package/packages/core/.size-limit.js

@@ -0,0 +1,47 @@
+// Core's own code, gzipped: `dist/index.js` with every peer left out, since
+// size-limit adds each `peerDependencies` entry of this package to the check's
+// `ignore` (and an `ignore: []` here does not stop it).
+//
+// The limit is tight on purpose, as react's is: measured 15,164 B with the
+// builders refusing another copy's skipToken (#873; 14,957 B before that,
+// +207 B; 14,750 B before resendOf held a re-send to the bytes and canister
+// ids it went out with; 14,449 B before resendOf; 14,347 B on
+// 4.0.0-beta.3), so it leaves 36 B. A change that
+// grows core fails here, and its pull request states the size delta and
+// raises this limit deliberately.
+//
+// What an app pays for core with its peers included is measured by
+// `scripts/size-app/`, which declares no peers. Both run in `pnpm size`.
+export default [
+  {
+    name: "Core Library",
+    path: "dist/index.js",
+    // With client.time() (#885) on top of v4: measured 15,487 B, so the limit moved from 15,200 B to 15.54 kB.
+    // With expiresAt (#888) on top of v4: measured 15,646 B, so the limit moved from 15,540 B to 15.7 kB.
+    // With client.encode() (#887) on top of v4: measured 15,774 B, so the limit moved from 15,700 B to 15.83 kB.
+    // With client.canisterId() (#890) on top of v4: measured 15,809 B, so the limit moved from 15,830 B to 15.86 kB.
+    // With maxElements (#932) on top of v4: measured 15,888 B, so the limit moved from 15,860 B to 15.94 kB.
+    // With timeoutMs (#875) on top of v4: measured 16,269 B, so the limit moved from 15,940 B to 16.32 kB.
+    // With strict createClient options (#938) on top of v4: measured 16,608 B, so the limit moved from 16,320 B to 16.66 kB.
+    // With TanStack retries kept for app queries (#937) on top of v4: measured 16,669 B, so the limit moved from 16,660 B to 16.72 kB.
+    // With a held-back write sent as its caller (#936) on top of v4: measured 17,194 B, so the limit moved from 16,720 B to 17.25 kB.
+    // With a view per useClient() caller (#935) on top of v4: measured 17,347 B, so the limit moved from 17,250 B to 17.4 kB.
+    // With #939 on top of v4: measured 17,645 B, so the limit moved from 17,400 B to 17.7 kB.
+    // With #940 on top of v4: measured 17,818 B, so the limit moved from 17,700 B to 17.87 kB.
+    // With #941 on top of v4: measured 17,980 B, so the limit moved from 17,870 B to 18.03 kB.
+    // With #942 on top of v4: measured 18,118 B, so the limit moved from 18,030 B to 18.17 kB.
+    // With #960 on top of v4: measured 18,281 B, so the limit moved from 18,170 B to 18.33 kB.
+    // With #963 on top of v4: measured 18,489 B, so the limit moved from 18,330 B to 18.54 kB.
+    // With #961 on top of v4: measured 18,505 B, so the limit moved from 18,540 B to 18.56 kB.
+    // With #962 on top of v4: measured 18,577 B, so the limit moved from 18,560 B to 18.64 kB.
+    // With #975 on top of v4: measured 18,622 B, so the limit moved from 18,640 B to 18.69 kB.
+    // With #973 on top of v4: measured 18,721 B, so the limit moved from 18,690 B to 18.79 kB.
+    // With #974 on top of v4: measured 18,825 B, so the limit moved from 18,790 B to 18.9 kB.
+    // With #976 on top of v4: measured 18,833 B, so the limit moved from 18,900 B to 18.91 kB.
+    // With #977 on top of v4: measured 18,834 B, so the limit moved from 18,910 B to 18.92 kB.
+    // With #949 on top of v4: measured 18,841 B, so the limit moved from 18,920 B to 18.93 kB.
+    // With #913 on top of v4: measured 18,975 B, so the limit moved from 18,930 B to 19.1 kB.
+    limit: "19.1 kB",
+    gzip: true,
+  },
+]

package/packages/core/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-2026 Behrad Deylami
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/packages/core/README.md

@@ -0,0 +1,84 @@
+# @ic-reactor/core
+
+> **This is ic-reactor 4.** It replaces the 3.x runtime with a thin layer over
+> a module Meant generates. 3.x is documented at
+> https://ic-reactor.b3pay.net/v3/packages/core and takes security fixes until
+> 90 days after the 4.0 release.
+
+[![npm version](https://img.shields.io/npm/v/@ic-reactor/core.svg)](https://www.npmjs.com/package/@ic-reactor/core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-blue.svg)](https://www.typescriptlang.org/)
+
+ic-reactor 4 is a thin layer over a `meant gen` module: a client with
+caller-scoped query keys, one error union that says whether a call may have
+executed, network resolution, strict token-unit helpers and a test client.
+
+**The guide is [`llms.txt`](./llms.txt)**, shipped in this package
+(`node_modules/@ic-reactor/core/llms.txt`): setup, values, reads, writes,
+errors and a complete React example, for people and coding agents alike. The
+docs site covers the same ground in pages, starting with
+[Getting started](https://ic-reactor.b3pay.net/v4/guides/getting-started/),
+and [this package's page](https://ic-reactor.b3pay.net/v4/packages/core/)
+lists its exports and peers.
+
+## Install
+
+```bash
+npm install @ic-reactor/core @icp-sdk/core @tanstack/query-core
+npm install --save-exact @meantjs/schema@0.6.0
+npm install --save-dev --save-exact @meantjs/cli@0.5.1
+```
+
+`@meantjs/schema` is a peer at exactly that version: the module `meant gen`
+writes imports it, so the generator (`@meantjs/cli@0.5.1`) has to pair with it
+too. Install the CLI at that version: without a version, npm installs the
+newest CLI, and when that one pairs with another schema, npm stops with
+`ERESOLVE`.
+
+With React, install `@tanstack/query-core` at the exact version your
+`@tanstack/react-query` depends on (`npm view @tanstack/react-query@<version>
+dependencies`), and check that `npm ls @tanstack/query-core` shows one copy.
+With two copies, core and the hooks each have their own `skipToken`:
+`client.queryOptions()` throws a `TypeError` for the hooks' one, and in
+development `ReactorProvider` throws when it is handed such a client.
+
+## A first read
+
+Generate a module from the canister's `.did` file, here the ICRC-1 ledger's
+`icrc1.did`:
+
+```bash
+npx @meantjs/cli gen icrc1.did -o src/generated
+```
+
+Then call the canister. A client with `identity: "anonymous"` only reads, and
+amounts are `bigint` in base units:
+
+```ts
+// src/read.ts
+import { createClient, formatUnits } from "@ic-reactor/core"
+import { actor, type Actor } from "./generated/icrc1"
+
+const client = createClient({ network: "ic", identity: "anonymous" })
+const ledger = client.canister<Actor>(actor, {
+  id: "ryjl3-tyaaa-aaaaa-aaaba-cai", // the ICP ledger
+})
+
+const fee = await ledger.icrc1_fee() // 10000n
+console.log(formatUnits(fee, await ledger.icrc1_decimals())) // "0.0001"
+```
+
+Run it with `npx tsx src/read.ts`, in a package with `"type": "module"`: the
+package is an ES module only, and the script uses top-level `await`.
+
+Reads and writes through TanStack Query, sign-in, errors and the test client
+are in the guide and on the docs site.
+[`@ic-reactor/react`](https://www.npmjs.com/package/@ic-reactor/react) is the
+React bindings, and
+[`@ic-reactor/vite-plugin`](https://www.npmjs.com/package/@ic-reactor/vite-plugin)
+generates the module in a Vite app.
+
+## 3.x
+
+The released 3.x package is documented at https://ic-reactor.b3pay.net/v3/packages/core. Its source and
+security fixes live on the `v3` branch.