@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/docs/src/content/docs/build/ssr-per-user.mdx

@@ -0,0 +1,552 @@
+---
+title: "Render a server page for one user"
+description: "A Next.js App Router page for the account a URL names: its ICP balance read on the server and handed to the browser exact, a certified balance streamed in, and the owner told apart once they sign in"
+---
+
+import { Aside, FileTree } from "@astrojs/starlight/components"
+
+This guide builds one page of a Next.js App Router app:
+`/accounts/<principal>`, the ICP balance of the account the URL names. The
+server reads the balance and sends it with the page. The browser takes over
+the server's cache and sends nothing on load. A certified balance, read
+through consensus, streams in after it.
+
+The user is the account in the URL, not the visitor. A server holds no
+session: it reads as the anonymous principal, and any account's balance can be
+read that way. Once the visitor signs in, the browser knows who they are, and
+the page says whether the account is theirs.
+
+The page takes care of five things:
+
+- **One client per request.** Two visitors never share a cache.
+- **The same keys on both sides.** One function builds the page's reads for
+  the server and for the browser, so the browser finds what the server read.
+- **Exact amounts.** A balance crosses from the server to the browser as a
+  `bigint`, never as a rounded number.
+- **A bad URL.** Text that is not a principal gets the not-found page, and
+  nothing is sent to the ledger.
+- **Failures.** A ledger that does not answer is shown with the error's kind,
+  rendered on the server.
+
+When it is done, the project holds these files beside the ones
+`create-next-app` wrote:
+
+<FileTree>
+
+- icrc1.did the ledger's interface
+- vitest.config.ts
+- src/
+  - generated/
+    - icrc1.ts written by `meant gen`
+  - account.ts the page's reads, for the server and the browser
+  - account.test.ts
+  - server/
+    - request-client.ts
+  - app/
+    - layout.tsx
+    - providers.tsx
+    - accounts/
+      - \[owner\]/
+        - page.tsx
+  - components/
+    - Balance.tsx
+    - YourAccount.tsx
+    - CertifiedBalance.tsx
+
+</FileTree>
+
+## Before you start
+
+Create the app. These flags give it a `src/` directory and the `@/*` alias
+this guide imports with:
+
+```sh
+npx create-next-app@latest my-app --ts --app --src-dir --import-alias "@/*" --yes
+cd my-app
+```
+
+`create-next-app` turns on Cache Components (`cacheComponents: true` in
+`next.config.ts`). This guide is written for them.
+
+1. Install the packages of
+   [Getting started, step 1](/v4/guides/getting-started/#1-install): the
+   core, React and Internet Identity packages, and the generator.
+2. Install Vitest for the test in step 8. `create-next-app` pins
+   `@types/node` to version 20, which Vitest 5 does not accept, so update it
+   in the same command:
+
+   ```sh
+   npm install --save-dev vitest @types/node@22
+   ```
+
+3. In `tsconfig.json`, set `"target"` to `"ES2022"`. `create-next-app` writes
+   `"ES2017"`, and TypeScript refuses a bigint literal such as `1n` below
+   ES2020.
+4. Copy `icrc1.did` from the repository's
+   [`examples/icrc-ledger`](https://github.com/B3Pay/ic-reactor/tree/main/examples/icrc-ledger)
+   directory to the project's root, and generate its module:
+
+   ```sh
+   npx @meantjs/cli gen icrc1.did -o src/generated
+   ```
+
+## 1. One client per request
+
+```ts
+// src/server/request-client.ts
+import { createClient, type Client } from "@ic-reactor/core"
+import { cache } from "react"
+
+/** This request's client: every Server Component of one request gets it. */
+export const requestClient = cache((): Client =>
+  createClient({ network: "ic", identity: "anonymous" })
+)
+```
+
+React's `cache()` keeps a value for the length of one server request. Every
+Server Component of a request gets the same client, and the next request gets
+a new one. Never build a client at module scope on a server: every request
+would share it, and its cache with it.
+
+The client is anonymous, because a server holds no session, and an anonymous
+client refuses every update before sending it. There is nothing to dispose:
+it built no sign-in, and a server's `QueryClient` sets no timers. See
+[SSR and hydration](/v4/guides/ssr/#one-client-per-request).
+
+## 2. The provider
+
+```tsx
+// src/app/providers.tsx
+"use client"
+
+import { createClient } from "@ic-reactor/core"
+import { ReactorProvider } from "@ic-reactor/react"
+import { AuthClient } from "@icp-sdk/auth/client"
+import type { ReactNode } from "react"
+
+export function Providers({ children }: { children: ReactNode }) {
+  return (
+    <ReactorProvider
+      client={() =>
+        createClient({
+          network: "ic",
+          auth: (network) => new AuthClient(network),
+        })
+      }
+    >
+      {children}
+    </ReactorProvider>
+  )
+}
+```
+
+Replace the `src/app/layout.tsx` that `create-next-app` wrote:
+
+```tsx
+// src/app/layout.tsx
+import type { ReactNode } from "react"
+import { Providers } from "@/app/providers"
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  )
+}
+```
+
+The layout is a Server Component, and a function cannot cross from a Server
+Component into a client one, so the `client` factory lives in a module marked
+`"use client"`. The provider calls the factory once for each request's server
+render, and once in the browser tab. The `auth` factory runs only in the
+browser.
+
+## 3. The page's reads
+
+```ts
+// src/account.ts
+import type { Principal } from "@meantjs/schema"
+import type { Client } from "@ic-reactor/core"
+import { actor, type Actor } from "@/generated/icrc1"
+
+/** The ICP ledger on mainnet. */
+export const LEDGER_ID = "ryjl3-tyaaa-aaaaa-aaaba-cai"
+
+/**
+ * The reads of an account page. The server and the browser both build them
+ * here, so the browser asks for the very keys the server filled.
+ */
+export function accountReads(client: Client, owner: Principal) {
+  const ledger = client.canister<Actor>(actor, { id: LEDGER_ID })
+  return {
+    symbol: client.queryOptions(ledger, "icrc1_symbol"),
+    decimals: client.queryOptions(ledger, "icrc1_decimals"),
+    balance: client.queryOptions(ledger, "icrc1_balance_of", {
+      owner,
+      subaccount: null,
+    }),
+  }
+}
+
+/**
+ * Reads an account into the client's cache. prefetchQuery never throws: a
+ * read that fails stays in the cache with its error.
+ */
+export async function prefetchAccount(client: Client, owner: Principal) {
+  const reads = accountReads(client, owner)
+  await Promise.all([
+    client.queryClient.prefetchQuery(reads.symbol),
+    client.queryClient.prefetchQuery(reads.decimals),
+    client.queryClient.prefetchQuery(reads.balance),
+  ])
+  return reads
+}
+```
+
+- The server builds the page's reads with `accountReads`, and so does the
+  component that shows them in the browser. The keys come from the client,
+  never from a string you wrote, so both sides ask for the same keys.
+- Those keys hold the caller. The server reads as the anonymous principal, and
+  the browser's hydrating render is anonymous too, whoever is signed in, so the
+  browser finds the server's data.
+- `prefetchAccount` reads the three into the client's cache.
+  `prefetchQuery` never throws, so a failed read stays in the cache with its
+  error, to be read back with `getQueryState`.
+
+## 4. The page
+
+```tsx
+// src/app/accounts/[owner]/page.tsx
+import { isPrincipal, principal } from "@meantjs/schema"
+import { isReactorError } from "@ic-reactor/core"
+import { dehydrate, HydrationBoundary } from "@tanstack/react-query"
+import { notFound } from "next/navigation"
+import { connection } from "next/server"
+import { Suspense } from "react"
+import { prefetchAccount } from "@/account"
+import { Balance } from "@/components/Balance"
+import { CertifiedBalance } from "@/components/CertifiedBalance"
+import { YourAccount } from "@/components/YourAccount"
+import { requestClient } from "@/server/request-client"
+
+type Params = Promise<{ owner: string }>
+
+export default function AccountPage({ params }: { params: Params }) {
+  return (
+    <main>
+      <h1>Account</h1>
+      <Suspense fallback={<p>Reading the account…</p>}>
+        <Account params={params} />
+      </Suspense>
+    </main>
+  )
+}
+
+async function Account({ params }: { params: Params }) {
+  // Read the ledger for each request: never once, kept for every visitor.
+  await connection()
+  // Anything can arrive in a URL: only principal text names an account.
+  const { owner: text } = await params
+  if (!isPrincipal(text)) notFound()
+  const owner = principal(text)
+
+  const client = requestClient()
+  const reads = await prefetchAccount(client, owner)
+  const failed = client.queryClient.getQueryState(reads.balance.queryKey)?.error
+
+  return (
+    <>
+      <p>
+        <code>{owner}</code>
+      </p>
+      <YourAccount owner={owner} />
+      {failed == null ? (
+        <HydrationBoundary state={dehydrate(client.queryClient)}>
+          <Balance owner={owner} />
+        </HydrationBoundary>
+      ) : (
+        <p role="alert">
+          The ledger did not answer (
+          {isReactorError(failed) ? failed.kind : "failed"}).
+        </p>
+      )}
+      <Suspense fallback={<p>Certified balance: reading through consensus…</p>}>
+        <CertifiedBalance owner={owner} />
+      </Suspense>
+    </>
+  )
+}
+```
+
+- **A shell, then the account.** Cache Components prerender the heading and
+  the fallback once, at build time. The account section renders for each
+  request and streams into the same response. Reading `params` outside a
+  `<Suspense>` fails the build ("prevents the route from being
+  prerendered").
+- **`connection()`** says the section is rendered when a request comes in.
+  Without it, Next tries to prerender the section, and logs an error when the
+  agent reads the clock ("encountered the unstable value `Date.now()`").
+- **A bad URL.** `isPrincipal` turns away anything that is not principal text,
+  before a call is made. The response is under way by then, so its status
+  stays 200. Next marks the not-found page `noindex`.
+- **The hand-over.** `dehydrate(client.queryClient)` is plain JSON. The
+  client's `QueryClient` writes a `bigint` into it as tagged text and reads it
+  back exact in the browser.
+- **A failure** stays on the server. TanStack Query dehydrates successful
+  reads only, so the page renders the error's kind itself, where
+  `isReactorError` can read it.
+
+<Aside>
+  The account section is in the first response, but React's inline script is
+  what puts it on the screen. Without JavaScript, the fallback stays. For a page
+  that shows its data without JavaScript, or answers a bad principal with a 404,
+  turn Cache Components off and await the account in the page itself, as
+  [SSR and hydration](/v4/guides/ssr/#prefetch-and-hand-over) does.
+</Aside>
+
+## 5. The balance in the browser
+
+```tsx
+// src/components/Balance.tsx
+"use client"
+
+import type { Principal } from "@meantjs/schema"
+import { formatUnits } from "@ic-reactor/core"
+import { useClient } from "@ic-reactor/react"
+import { useQuery } from "@tanstack/react-query"
+import { accountReads } from "@/account"
+
+export function Balance({ owner }: { owner: Principal }) {
+  const client = useClient()
+  const reads = accountReads(client, owner)
+  // The server has just read these: no read again on mount. A token's symbol
+  // and decimals never change; the balance is read again after a minute.
+  const symbol = useQuery({ ...reads.symbol, staleTime: Infinity })
+  const decimals = useQuery({ ...reads.decimals, staleTime: Infinity })
+  const balance = useQuery({ ...reads.balance, staleTime: 60_000 })
+
+  if (balance.isError) return <p role="alert">{balance.error.message}</p>
+  if (
+    symbol.data === undefined ||
+    decimals.data === undefined ||
+    balance.data === undefined
+  ) {
+    return <p>Balance: …</p>
+  }
+  return (
+    <p>
+      Balance: {formatUnits(balance.data, decimals.data)} {symbol.data}
+    </p>
+  )
+}
+```
+
+- TanStack Query's default `staleTime` is 0. Without one, each read the server
+  handed over would be stale on arrival, and read again as soon as the
+  component mounts. With these, the browser sends nothing on load. A minute
+  after the server's read, a remount or a refocused window reads the balance
+  again.
+- After the visitor signs in, `useClient()` renders the component again for
+  the new caller, whose keys are empty. The balance shows `…` until it is read
+  as them. Nothing read anonymously is reused for a signed-in visitor.
+- `formatUnits` shows base units as decimal text, never through `Number`. See
+  [Values and units](/v4/guides/values/#token-amounts).
+
+## 6. Whose account it is
+
+```tsx
+// src/components/YourAccount.tsx
+"use client"
+
+import type { Principal } from "@meantjs/schema"
+import { useAuth } from "@ic-reactor/react"
+
+export function YourAccount({ owner }: { owner: Principal }) {
+  const { status, principal, signIn } = useAuth()
+  if (status === "signed-in") {
+    return principal === owner ? (
+      <p>This is your account.</p>
+    ) : (
+      <p>
+        You are signed in as <code>{principal}</code>, another account.
+      </p>
+    )
+  }
+  return (
+    <button onClick={() => signIn().catch(console.error)}>
+      Sign in to see if this is you
+    </button>
+  )
+}
+```
+
+`useAuth()` is `"anonymous"` on the server and in the browser's hydrating
+render, whatever session the browser holds, so the HTML matches. Right after
+hydration, the component renders again with the session, and the page says
+whether the account is the visitor's. See
+[The hydrating render](/v4/guides/ssr/#the-hydrating-render).
+
+## 7. A certified balance, streamed
+
+```tsx
+// src/components/CertifiedBalance.tsx
+import type { Principal } from "@meantjs/schema"
+import { formatUnits, isReactorError } from "@ic-reactor/core"
+import { LEDGER_ID } from "@/account"
+import { actor, type Actor } from "@/generated/icrc1"
+import { requestClient } from "@/server/request-client"
+
+/** The balance read through consensus: a second or two on mainnet. */
+export async function CertifiedBalance({ owner }: { owner: Principal }) {
+  const client = requestClient()
+  const { queryClient } = client
+  const ledger = client.canister<Actor>(actor, {
+    id: LEDGER_ID,
+    certified: true,
+  })
+  try {
+    const [balance, decimals, symbol] = await Promise.all([
+      queryClient.fetchQuery(
+        client.queryOptions(ledger, "icrc1_balance_of", {
+          owner,
+          subaccount: null,
+        })
+      ),
+      queryClient.fetchQuery(client.queryOptions(ledger, "icrc1_decimals")),
+      queryClient.fetchQuery(client.queryOptions(ledger, "icrc1_symbol")),
+    ])
+    return (
+      <p>
+        Certified balance: {formatUnits(balance, decimals)} {symbol}
+      </p>
+    )
+  } catch (error) {
+    return (
+      <p role="alert">
+        Certified balance: not read (
+        {isReactorError(error) ? error.kind : "failed"}).
+      </p>
+    )
+  }
+}
+```
+
+- `certified: true` makes each read a replicated call, which goes through
+  consensus: a second or two on mainnet. Its keys are its own, ending in
+  `"certified"`, so an uncertified answer is never served for it.
+- The page renders it inside its own `<Suspense>`, so the rest of the account
+  does not wait for it.
+- `requestClient()` returns the client the page used, because it is the same
+  request.
+- It is an awaited Server Component, so a failure is rendered with its kind
+  here, on the server.
+
+## 8. Test the hand-over
+
+Vitest needs the `@/` alias that Next.js resolves:
+
+```ts
+// vitest.config.ts
+import { fileURLToPath } from "node:url"
+import { defineConfig } from "vitest/config"
+
+export default defineConfig({
+  // The same `@/` that Next.js resolves to src/.
+  resolve: { alias: { "@": fileURLToPath(new URL("./src", import.meta.url)) } },
+})
+```
+
+```ts
+// src/account.test.ts
+import { principal } from "@meantjs/schema"
+import { createTestClient } from "@ic-reactor/core/testing"
+import { dehydrate, hydrate } from "@tanstack/react-query"
+import { afterEach, expect, it } from "vitest"
+import { accountReads, LEDGER_ID, prefetchAccount } from "@/account"
+import { actor, type Actor } from "@/generated/icrc1"
+
+const owner = principal("rkp4c-7iaaa-aaaaa-aaaca-cai")
+const balance = 2n ** 70n // more than a Number holds exactly
+
+// A client over an in-memory replica, with the ledger mocked: one for the
+// server's request and one for the browser tab, as the app has.
+const clients: ReturnType<typeof createTestClient>[] = []
+function side(signedIn: boolean) {
+  const test = createTestClient({ signedIn })
+  test.mock<Actor>(actor, LEDGER_ID, {
+    icrc1_symbol: () => "ICP",
+    icrc1_decimals: () => 8,
+    icrc1_balance_of: () => balance,
+  })
+  clients.push(test)
+  return test
+}
+afterEach(() => {
+  for (const test of clients.splice(0)) test.client.dispose()
+})
+
+/** What the page sends the browser: the server's cache, as JSON. */
+async function serverRender() {
+  const server = side(false)
+  await prefetchAccount(server.client, owner)
+  return JSON.parse(JSON.stringify(dehydrate(server.client.queryClient)))
+}
+
+it("hands the balance to the browser exactly, and the browser reads nothing", async () => {
+  const state = await serverRender()
+  const browser = side(false)
+  hydrate(browser.client.queryClient, state)
+
+  const reads = accountReads(browser.client, owner)
+  expect(browser.client.queryClient.getQueryData(reads.balance.queryKey)).toBe(
+    balance
+  )
+  expect(browser.requests).toHaveLength(0)
+})
+
+it("reads again as a signed-in visitor: nothing read anonymously is reused", async () => {
+  const state = await serverRender()
+  const browser = side(true)
+  hydrate(browser.client.queryClient, state)
+
+  const reads = accountReads(browser.client, owner)
+  const { queryClient } = browser.client
+  expect(queryClient.getQueryData(reads.balance.queryKey)).toBeUndefined()
+  expect(await queryClient.fetchQuery(reads.balance)).toBe(balance)
+})
+```
+
+```sh
+npx vitest run
+```
+
+- Each side is a real client over an in-memory replica, with the ledger
+  mocked. The server's state goes through `JSON.stringify` and `JSON.parse`,
+  as it does on its way to the browser.
+- `2n ** 70n` is more than a `Number` holds exactly, and it arrives exact.
+- An anonymous browser sends nothing. A signed-in one finds no data under its
+  own keys, and reads the balance again.
+
+## 9. Run it
+
+```sh
+npm run dev
+```
+
+Open `http://localhost:3000/accounts/rkp4c-7iaaa-aaaaa-aaaca-cai`, the
+account of the cycles minting canister. The balance shows first, and the
+certified balance a second or two later. In the network panel, the browser
+sends no request to the IC for the page. Then try
+`http://localhost:3000/accounts/not-a-principal`.
+
+## Next
+
+- [Next.js SSR example](/v4/examples/next-ssr/): three ledgers, a lookup
+  form, a Route Handler, and tests of the hydration itself.
+- [SSR and hydration](/v4/guides/ssr/): every rule this page follows, and what
+  a signed-in reload costs.
+- [Build an ICRC-1 wallet](/v4/build/icrc1-wallet/): sign in and send a
+  transfer that is never paid twice.

package/docs/src/content/docs/examples/canister-studio.mdx

@@ -0,0 +1,95 @@
+---
+title: "Canister Studio"
+description: Automatic forms and safe calls for any mainnet canister, server-rendered with TanStack Start, on ic-reactor 4 and Meant
+editUrl: false
+---
+
+import { CardGrid, LinkCard } from "@astrojs/starlight/components"
+
+A TanStack Start app, rendered on the server, built on `@ic-reactor/core`,
+`@ic-reactor/react` and `@ic-reactor/vite-plugin` with TanStack Query's own
+hooks. It gives every method of any canister on mainnet a form built from its
+Candid, and calls it with every rule of ic-reactor 4 in view:
+
+- **Typed canisters.** The ICP ledger, the ckBTC and ckETH ledgers and the ckBTC
+  minter come from three modules that the Vite plugin generates from committed
+  `.did` files with `meant gen`. The wallet page calls them through the
+  generated types, with no cast.
+- **Any canister, read live.** Open any mainnet canister id: a server function
+  reads its `candid:service` metadata and module hash in one certified
+  `read_state`, compiles the interface with `@meantjs/cli` in a worker
+  thread with a deadline, and caches it by module hash. The browser rebuilds
+  the actor from the compiled envelope with `schemaFromContract`. An
+  interface read from the uncertified `__get_candid_interface_tmp_hack` query
+  is labelled so, and a certificate that fails to verify, or leaves the
+  metadata unproven, is never followed by a fallback.
+- **Automatic forms.** A field per Candid type: amounts in token units read
+  with `parseUnits`, principals checked as you type, blobs as hex, text or
+  base64, and variants, options, vectors and records, with `created_at_time`
+  set to now for ICRC deduplication. The submit button names what is wrong,
+  and the issues of an `invalid_args` refusal land on their fields.
+- **Server rendering.** One client per request on the server and one per tab,
+  made by the router. Loaders prefetch mainnet reads and never throw, the
+  browser hydrates them without reading again, and a failed read is never
+  sent to the browser, which reads it itself and gets the full
+  `ReactorError`. A shared query link, a method and its arguments as hex
+  Candid, renders its result in the server's HTML.
+- **Safe writes.** Signed out, a write is disabled and says why. Signed in, a
+  confirm step shows the sender, the target, the method, the Candid text and
+  the sha256 of the exact argument bytes. A write is sent once and never
+  retried. A failure shows its `kind`, its code and whether it may have
+  executed, and after an unknown outcome `client.resendOf` offers the same
+  call again, deduplicated by `created_at_time`.
+- **Reads.** Certified reads under keys of their own, the live query key with
+  its caller segment, and the ckBTC minter's `get_btc_address`, an update,
+  read once per caller through `{ update: "idempotent" }`.
+- **The Safety lab.** Ten scenarios that `createTestClient()` runs in the
+  browser against a mocked ICRC-1 ledger: an anonymous write refused before
+  sending, arguments that do not encode, a lost reply and its deduplicated
+  re-send, an HTTP 429 the client sends again by itself, canister rejects, a
+  typed `Err`, a caller that changes, cache isolation and certified reads.
+  Each shows its request log and the error's fields.
+- **The playground and the interface tools.** Paste a `.did` and compile it
+  in the browser with the compiler's lazily loaded WASM; for any canister, get
+  its Candid, its TypeScript module, a projection to the methods you choose,
+  and a check of a written `.did` against the live one.
+
+The guides it shows at work: [The client](/v4/guides/client/) and
+[SSR and hydration](/v4/guides/ssr/) (a client per request, prefetch and
+hydration), [Reads](/v4/guides/reads/), [Writes](/v4/guides/writes/) and
+[Errors and mayHaveExecuted](/v4/guides/errors/) (every call),
+[Values and units](/v4/guides/values/) (the forms and the replies),
+[Auth](/v4/guides/auth/) (Internet Identity), [Testing](/v4/guides/testing/)
+(the Safety lab and the tests) and [The Vite plugin](/v4/guides/vite-plugin/)
+(the typed modules).
+
+The tests run the real client on `createTestClient()` from
+`@ic-reactor/core/testing`, with each canister mocked at its mainnet id and
+the interface loader given a fetcher of the test's own, and never reach
+mainnet. The app itself calls mainnet: sign-in is mainnet's Internet
+Identity, and a transfer you confirm moves real tokens.
+
+StackBlitz installs the example from npm and starts its dev server
+(`npm run dev`). The home page renders there on the server with its mainnet
+reads, because its loader calls no server function. TanStack Start's server
+functions do not run there: they keep each request in Node's
+`AsyncLocalStorage`, which StackBlitz does not implement. The typed canisters
+need none to load and to call. Any other canister opened from inside the app
+is read and compiled in the browser instead, with the compiler's lazily
+loaded WASM, and so is the live side of a pasted `.did` check. A projection,
+the TypeScript module of a canister read live and the check of a typed
+canister's committed `.did` run on the studio's server only, and say so
+there. Clone the repository to run the server path.
+
+<CardGrid>
+  <LinkCard
+    title="Open in StackBlitz"
+    description="Edit and run in your browser"
+    href="https://stackblitz.com/github/b3pay/ic-reactor/tree/main/examples/canister-studio?file=src/routes/index.tsx"
+  />
+  <LinkCard
+    title="View on GitHub"
+    description="Browse the source code"
+    href="https://github.com/b3pay/ic-reactor/tree/main/examples/canister-studio"
+  />
+</CardGrid>

package/docs/src/content/docs/examples/icrc-ledger.mdx

@@ -0,0 +1,45 @@
+---
+title: "ICRC-1 ledger"
+description: Mainnet ICP ledger reads and a fault-injection transfer sandbox on ic-reactor 4
+editUrl: false
+---
+
+import { CardGrid, LinkCard } from "@astrojs/starlight/components"
+
+An explorer for an ICRC-1 ledger, built on `@ic-reactor/core`,
+`@ic-reactor/react` and `@ic-reactor/vite-plugin` with TanStack Query's own
+hooks.
+
+- **Mainnet:** a client built with `createClient({ network: "ic", identity: "anonymous" })`
+  reads the ICP ledger: name, symbol, decimals, fee, total supply, metadata,
+  the minting account and the balance of a principal you type. It also reads
+  the block log, following the archive callbacks the ledger's reply carries
+  with `client.func`. Certified reads can be switched on.
+- **Sandbox:** `createTestClient()` from `@ic-reactor/core/testing` runs a real
+  client against an in-memory replica with a mocked ledger. Sign in, switch
+  accounts, and send transfers with a fault armed (a canister reject, a lost
+  reply, HTTP 429) to see what the client reports: whether the transfer may
+  have executed, the re-read of the balance, and the single re-send after a
+  failure that proves the transfer never arrived.
+
+The generated modules come from the ledger's `.did` files through the Vite
+plugin, which runs `meant gen`.
+
+The guides this example shows at work: [Reads](/v4/guides/reads/) (the
+balance, certified reads), [The client](/v4/guides/client/) (`client.func` for
+archive callbacks), [Writes](/v4/guides/writes/) and
+[Errors and mayHaveExecuted](/v4/guides/errors/) (the transfer and its
+faults), and [Testing](/v4/guides/testing/) (the sandbox).
+
+<CardGrid>
+  <LinkCard
+    title="Open in StackBlitz"
+    description="Edit and run in your browser"
+    href="https://stackblitz.com/github/b3pay/ic-reactor/tree/main/examples/icrc-ledger?file=src/App.tsx"
+  />
+  <LinkCard
+    title="View on GitHub"
+    description="Browse the source code"
+    href="https://github.com/b3pay/ic-reactor/tree/main/examples/icrc-ledger"
+  />
+</CardGrid>