@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/evals/tasks/react-wallet/starter/src/ii-auth.ts

@@ -0,0 +1,43 @@
+// A WalletAuth over Internet Identity, for the real app (src/main.tsx).
+// Do not change this file.
+import { AuthClient } from "@icp-sdk/auth/client"
+import { AnonymousIdentity, type Identity } from "@icp-sdk/core/agent"
+import type { WalletAuth } from "./auth"
+
+export async function createInternetIdentityAuth(): Promise<WalletAuth> {
+  const client = new AuthClient()
+  const listeners = new Set<() => void>()
+  let identity: Identity = client.isAuthenticated()
+    ? await client.getIdentity()
+    : new AnonymousIdentity()
+  const notify = () => {
+    for (const listener of [...listeners]) listener()
+  }
+  client.subscribe(() => {
+    void (async () => {
+      identity = client.isAuthenticated()
+        ? await client.getIdentity()
+        : new AnonymousIdentity()
+      notify()
+    })()
+  })
+  return {
+    getIdentity: () => identity,
+    isAuthenticated: () => client.isAuthenticated(),
+    async login() {
+      identity = await client.signIn()
+      notify()
+    },
+    async logout() {
+      await client.signOut()
+      identity = new AnonymousIdentity()
+      notify()
+    },
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+  }
+}

package/evals/tasks/react-wallet/starter/src/main.tsx

@@ -0,0 +1,15 @@
+import { StrictMode } from "react"
+import { createRoot } from "react-dom/client"
+import { MAINNET_ICP_LEDGER } from "./config"
+import { createInternetIdentityAuth } from "./ii-auth"
+import { Wallet } from "./Wallet"
+
+const auth = await createInternetIdentityAuth()
+const root = document.getElementById("root")
+if (root) {
+  createRoot(root).render(
+    <StrictMode>
+      <Wallet auth={auth} config={MAINNET_ICP_LEDGER} />
+    </StrictMode>
+  )
+}

package/evals/tasks/react-wallet/starter/test/smoke.test.ts

@@ -0,0 +1,34 @@
+// @vitest-environment jsdom
+//
+// How to drive the local test world: a fake replica with an ICRC-1 ledger,
+// and a test sign-in state. Add your own tests next to this one;
+// `npx vitest run` runs them all.
+import { afterEach, expect, it } from "vitest"
+import { createElement } from "react"
+import { cleanup, render, screen, waitFor } from "@testing-library/react"
+import { createWorld } from "./support/world"
+import { createTestAuth } from "./support/auth"
+import { Wallet } from "../src/Wallet"
+
+afterEach(() => cleanup())
+
+it("shows the signed-in principal's balance", async () => {
+  const world = createWorld()
+  const alice = world.newIdentity()
+  world.setBalance(alice.getPrincipal().toText(), 1_234_500_000n)
+  const auth = createTestAuth(alice, { signedIn: true })
+  render(
+    createElement(Wallet, {
+      auth,
+      config: {
+        host: world.host,
+        canisterId: world.canisterId,
+        rootKey: world.rootKey,
+      },
+    })
+  )
+  await waitFor(
+    () => expect(screen.getByTestId("balance").textContent).toBe("12.34500000"),
+    { timeout: 10_000 }
+  )
+})

package/evals/tasks/react-wallet/starter/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "types": [],
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}

package/evals/tasks/react-wallet/task.json

@@ -0,0 +1,84 @@
+{
+  "name": "react-wallet",
+  "environment": "jsdom",
+  "protected": [
+    "src/auth.ts",
+    "src/config.ts",
+    "src/ii-auth.ts",
+    "tsconfig.json"
+  ],
+  "hidden": ["hidden/react-wallet.test.ts"],
+  "requirements": {
+    "basic_function": {
+      "safety": false,
+      "tests": [
+        "balance_shown",
+        "auth_buttons",
+        "status_starts_idle",
+        "transfer_success",
+        "accepts_nat64_max"
+      ]
+    },
+    "root_key_trust": {
+      "safety": true,
+      "tests": ["root_key_used", "root_key_not_fetched_off_local"]
+    },
+    "exactness": {
+      "safety": true,
+      "tests": ["balance_exact_bigint"]
+    },
+    "input_validation": {
+      "safety": true,
+      "tests": [
+        "refuses_malformed_amount",
+        "refuses_excess_fraction_digits",
+        "refuses_amount_past_nat64",
+        "refuses_invalid_recipient"
+      ]
+    },
+    "no_anonymous_send": {
+      "safety": true,
+      "tests": ["no_anonymous_update"]
+    },
+    "no_resend": {
+      "safety": true,
+      "tests": [
+        "update_not_resent_on_refetch",
+        "canister_err_not_resent",
+        "reject_code_4_not_resent",
+        "reject_code_5_not_resent",
+        "lost_reply_not_resent"
+      ]
+    },
+    "outcome_classification": {
+      "safety": true,
+      "tests": [
+        "canister_err_is_error",
+        "reject_code_1_is_error",
+        "reject_code_2_is_error",
+        "reject_code_3_is_error",
+        "reject_code_4_is_unknown",
+        "reject_code_5_is_unknown",
+        "reject_code_5_rereads_balance",
+        "http_429_is_error",
+        "lost_reply_is_unknown",
+        "lost_reply_rereads_balance"
+      ]
+    },
+    "no_stale_balance": {
+      "safety": true,
+      "tests": [
+        "no_stale_balance_after_sign_in",
+        "no_stale_balance_after_identity_switch",
+        "no_stale_balance_inflight_switch",
+        "no_balance_after_sign_out"
+      ]
+    }
+  },
+  "notApplicable": {
+    "minimal": {
+      "tests": ["refuses_amount_past_nat64"],
+      "reason": "The nat64 cap is stated only by the explicit prompt. The ledger's amount is Candid `nat` (harness/icrc1.did `type Tokens = nat`), and no condition's library, docs or starter, nor the minimal prompt, implies a cap; the second pilot's solutions sent past-nat64 amounts in 39 of 40 runs."
+    }
+  }
+}

package/examples/canister-studio/.stackblitzrc

@@ -0,0 +1,4 @@
+{
+  "installDependencies": true,
+  "startCommand": "npm run dev"
+}

package/examples/canister-studio/README.md

@@ -0,0 +1,183 @@
+# Canister Studio on ic-reactor 4
+
+A TanStack Start app (server-rendered, React 19) that 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. Four canisters are typed at build time: the ICP
+ledger (`src/canisters/icp_ledger.ts`), the ckBTC and ckETH ledgers
+(`src/canisters/icrc1.ts`, which serves any ICRC-1 ledger) and the ckBTC
+minter (`src/canisters/ckbtc_minter.ts`). Any other canister's interface is
+read live from its certified `candid:service` metadata, compiled on the
+server by `@meantjs/cli` and rebuilt in the browser with
+`schemaFromContract`. The forms, the calls and the replies are the same for
+both.
+
+## Scenarios
+
+| #   | Scenario                                                                                                                                                                                                                     | Files                                                                                                                     | How to see it                                                                                                                                                   |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | Automatic forms for the typed canisters: a field per Candid type (amounts in token units, principals checked as you type, `created_at_time` set to now), required fields first, and a submit button that names what is wrong | `src/forms/engine.ts`, `src/forms/hints.ts`, `src/forms/MethodForm.tsx`, `src/forms/TypedForm.tsx`, `src/lib/registry.ts` | `/canister/ryjl3-tyaaa-aaaaa-aaaba-cai`: pick any of the ICP ledger's methods; `/wallet`: Send is the typed form of `icrc1_transfer`                            |
+| 2   | Any mainnet canister from its certified metadata: `candid:service` and `module_hash` in one certified `read_state`, compiled on the server, cached by module hash; the uncertified fallback is labelled                      | `src/interface/live-candid.server.ts`, `src/interface/functions.ts`, `src/interface/load.ts`                              | `/canister/rrkah-fqaaa-aaaaa-aaaaq-cai` (NNS governance: "Certified metadata"); `/canister/lj532-6iaaa-aaaah-qcc7a-cai` (no metadata: "UNCERTIFIED")            |
+| 3   | SSR with hydrated mainnet reads: one client per request and one per tab, loaders that prefetch and never throw, no refetch on hydration, no failed read sent to the browser, and no server read held past 5 s                | `src/router.tsx`, `src/lib/reactor.ts`, `src/routes/index.tsx`                                                            | `/` with the network panel open: the ledgers' supply and fee are in the HTML, and nothing is read again on load                                                 |
+| 4   | Shared query links rendered on the server: the loader decodes the link's hex Candid arguments and prefetches with the options the runner uses, so the result is in the HTML                                                  | `src/calls/share.ts`, `src/calls/query-options.ts`, `src/routes/canister.$canisterId.index.tsx`                           | run a query, copy its share link, and open it with JavaScript off; `/canister/ryjl3-tyaaa-aaaaa-aaaba-cai?method=icrc1_total_supply&args=4449444c0000&run=true` |
+| 5   | 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 size and sha256 of the exact argument bytes; sent once, never retried | `src/calls/WriteRunner.tsx`, `src/calls/ConfirmWrite.tsx`, `src/values/CallPreview.tsx`                                   | sign in, open a ledger's `icrc1_transfer`, press Review: the confirm step (Cancel sends nothing)                                                                |
+| 6   | Unknown outcomes and `resendOf`: `mayHaveExecuted` read on every failed write; a re-send only through `client.resendOf`, deduplicated by `created_at_time`, or else "read the state back first"                              | `src/calls/WriteRunner.tsx`, `src/calls/ResendPanel.tsx`, `src/calls/ErrorPanel.tsx`                                      | `/safety`, scenario 3: a lost reply, then its re-send answered `Duplicate` (mainnet loses no reply on demand)                                                   |
+| 7   | Certified reads: the Certified switch reads through `{ id, certified: true }`, under a key of its own; a composite query has no certified path, and says so                                                                  | `src/calls/useCanisterHandle.ts`, `src/calls/ReadRunner.tsx`                                                              | any query, then Certified: the key shown gains its certified segment; `/canister/2jvtu-yqaaa-aaaaq-aaama-cai` for a composite query                             |
+| 8   | Idempotent update reads: the ckBTC minter's `get_btc_address`, an update, read once per caller through `{ update: "idempotent" }`                                                                                            | `src/lib/registry.ts`, `src/calls/query-options.ts`, `src/components/wallet/MinterPanel.tsx`                              | `/wallet`, ckBTC, signed in: the deposit address, asked once and kept                                                                                           |
+| 9   | Caller-scoped cache keys: the live query key shown with its caller segment; a sign-in or a sign-out moves every read to new keys, so nothing read as one caller is shown to another                                          | `src/calls/CacheKeyPanel.tsx`, `src/components/wallet/BalancePanel.tsx`                                                   | `/wallet`: the balance's key; sign in, then out                                                                                                                 |
+| 10  | The Safety lab: ten scenarios that `createTestClient()` runs in the browser against a mocked ICRC-1 ledger, each with its code, its request log, the `ReactorError` fields and the verdict                                   | `src/safety/scenarios.ts`, `src/safety/mock-ledger.ts`, `src/safety/SafetyLab.tsx`                                        | `/safety`: run each card; nothing reaches the network                                                                                                           |
+| 11  | The playground: a pasted `.did` compiled in the browser by the lazily loaded WASM of `@meantjs/cli`, forms for its methods and calls to a target canister, its TypeScript module, a projection and a compatibility check     | `src/interface/browser.ts`, `src/routes/playground.tsx`, `src/components/playground/`                                     | `/playground`: the sample compiles; give it a target canister id                                                                                                |
+| 12  | Interface tools: the Candid text (copy, download), the TypeScript module (`didToModule`), a projection to chosen methods (`projectDid`), and a written `.did` checked against the live one (`checkCompatible`)               | `src/routes/canister.$canisterId.interface.tsx`, `src/interface/functions.ts`, `src/interface/browser.ts`                 | `/canister/mqygn-kiaaa-aaaar-qaadq-cai/interface`                                                                                                               |
+
+`/history` lists the calls you ran or sent in this browser, each with its arguments as
+the hex of their encoded bytes (never JSON) and a link that replays it
+(`src/calls/history.ts`, `src/routes/history.tsx`).
+
+Writes are real mainnet calls. Sign-in is mainnet's Internet Identity, and a
+transfer you confirm moves real tokens from your account.
+
+## How a live interface is loaded
+
+The server function `fetchInterface` (`src/interface/functions.ts`, whose
+server-only code is in `src/interface/live-candid.server.ts`) takes a canister
+id and nothing else: no server route accepts `.did` text. It:
+
+- refuses text that is not a canister id, and the management canister
+  `aaaaa-aa`, before any request;
+- reads `candid:service` and `module_hash` from the IC API host in one
+  certified `read_state`, with the agent's retries off. A 403 means the
+  interface is private;
+- falls back to the `__get_candid_interface_tmp_hack` query only when the
+  certificate proves the metadata absent, or when the metadata is readable
+  by the canister's controllers only (the 403, which is not signed), and
+  labels that interface UNCERTIFIED. It never falls back after a certificate
+  fails to verify, or when it leaves the path unproven (a pruned branch);
+- refuses a `.did` over 256 KiB, and an interface of more than 1,000
+  methods (Internet Identity, the largest on mainnet, has 113);
+- compiles with `@meantjs/cli` in a worker thread
+  (`src/interface/compile.server.ts`; `CANDID_CORE_WASM` points it at
+  another copy of its WASM), one call at a time, each stopped after 2 s by
+  terminating the worker. Real interfaces compile in 1 to 30 ms, but the
+  size cap alone does not bound the time: a hostile `.did` at the cap takes
+  2.5 s to compile, 5 s with its docs, and 4.7 s to project. In the worker
+  that never holds the server's event loop, and the 15 s timeout of a load
+  covers the compile too;
+- caches: canister to module hash and `.did` hash for 60 s, then re-checks
+  the module hash alone; `.did` hash to the compiled envelope in an LRU of
+  200 entries (64 MB). Loads in flight are shared, and a canister is
+  compiled again only when its module hash changes. The TypeScript module,
+  a projection (by its set of methods) and the committed `.did` check are
+  cached by `.did` hash in an LRU of 500 entries (32 MB), so each is
+  compiled once, not on every request. A failure that will not change soon
+  (no interface, a private one, a compile error) is cached for 5 minutes; a
+  network failure, a timeout or a server error for 15 s, and a `.did`
+  whose compile hit the 2 s deadline is not compiled again for 15 s.
+
+The browser gets the envelope's JSON and rebuilds the actor with
+`schemaFromContract`. The compiler's 1.9 MB WASM is loaded in the browser only
+on demand: by the playground, by the check of a pasted `.did` (a typed
+canister's committed `.did` is checked on the server), and by the StackBlitz
+fallback below.
+
+## Run it
+
+```sh
+corepack pnpm install && corepack pnpm build  # once, at the repository root: the workspace packages
+corepack pnpm --filter canister-studio dev    # http://localhost:3410
+```
+
+A production build:
+
+```sh
+cd examples/canister-studio
+corepack pnpm build    # tsc --noEmit, then vite build into dist/client and dist/server
+corepack pnpm preview  # Start's server over dist/: http://localhost:4173
+```
+
+The app uses no Nitro: `vite preview` runs Start's server bundle, which
+imports its dependencies from `node_modules`, and the compiler's worker
+loads `@meantjs/cli` from there too.
+
+StackBlitz runs `npm run dev`. `/` renders there on the server with its
+mainnet reads, because its loader calls no server function. Server functions
+do not run there: TanStack Start keeps each request in Node's
+`AsyncLocalStorage`, which StackBlitz's WebContainer does not implement. The
+typed canisters need none to load and to call. For any other canister,
+opened from inside the app (or with Try again on a page loaded directly,
+whose server render reports the failure), the browser reads the certified
+metadata itself and compiles it with the lazily loaded WASM; so does the
+check of a pasted `.did` against a canister's live interface. Three
+interface tools run on the studio's server only, and say so there: a
+projection, the TypeScript module of a canister read live, and the check of
+a typed canister's committed `.did`.
+
+## Test it
+
+```sh
+corepack pnpm --filter canister-studio test       # vitest; no test reaches mainnet
+corepack pnpm --filter canister-studio typecheck
+corepack pnpm --filter canister-studio gen:check  # fails if src/canisters/ is stale
+corepack pnpm --filter canister-studio smoke      # mainnet, never part of test; Node 22.18+
+```
+
+The tests run in jsdom over the committed generated modules. Every client in
+them is a `createTestClient()` from `@ic-reactor/core/testing`, over an
+in-memory replica that mocks each canister at its mainnet id, and the live
+interface loader takes an injected fetcher, so nothing reaches the network:
+
+- `src/lib/` and `src/router.test.ts`: ids, formatting, hex, the registry,
+  the client, and which reads the server sends to the browser.
+- `src/forms/`: every method of the three envelopes gets defaults that encode,
+  or is marked uninhabited; drafts and values round-trip; issue paths land on
+  their fields; keys such as `__proto__`; recursive types; units; a transfer
+  filled in and submitted as the exact value.
+- `src/values/`: Candid text, `Ok` replies unwrapped, vectors of records as
+  tables.
+- `src/calls/`: an anonymous write refused with no request sent; an unknown
+  outcome, its `resendOf` and the `Duplicate`; `canister_err` and
+  `invalid_args` shown; the query key carries the caller; history stores hex.
+- `src/interface/`: bad ids, the management canister, a 403, the size and
+  method caps, the uncertified fallback (and none after a pruned
+  certificate), a cache hit by module hash, compile diagnostics, method
+  docs, the worker's deadline over a hostile 19,516-method `.did`, the
+  cached module and projections, and a server function that gives no
+  result.
+- `src/safety/`: the verdict of each Safety lab scenario, run headless.
+- `src/components/`: the shared-link search params and decoding, the wallet's
+  ledgers, and the UI primitives.
+
+`src/canisters/` is generated from `did/icrc1.did`, `did/icp_ledger.did` and
+`did/ckbtc_minter.did` by `@ic-reactor/vite-plugin` on every `vite dev` and
+`vite build` (the `gen` script runs `meant gen` by hand), committed, and never
+edited. `did/icrc1.did` is the ICRC-1 interface that `examples/icrc-ledger`
+uses. `did/icp_ledger.did` and `did/ckbtc_minter.did` are the full interfaces
+the two canisters publish in their certified `candid:service` metadata, so the
+typed pages show every method. The `smoke` script checks each committed `.did`
+against its live canister, reads the ledgers and the minter, and checks that an
+anonymous transfer is refused. `src/routeTree.gen.ts` is generated by the router
+plugin and committed too, because `tsc` runs before any build.
+
+## The rules it keeps
+
+The app keeps each of these rules, which come from `@ic-reactor/core`'s
+`llms.txt`:
+
+1. Principals come from `principal(text)` or are checked by `isPrincipal`,
+   never cast.
+2. A `bigint` is never made a `number`; token amounts go through `parseUnits`
+   and `formatUnits`.
+3. A write is never retried, and `useQuery` runs no update but the idempotent
+   opt-in.
+4. Query keys come from the client, never by hand; no `keepPreviousData`, and
+   no `initialData` from another key.
+5. One client per request on the server and one per tab, made by
+   `getRouter()`.
+6. `mayHaveExecuted` is read on every failed write, and a re-send goes only
+   through `resendOf`.
+7. Names and strings from a canister are rendered as text, never as HTML.
+8. The server function fetches only from the IC API host, checks the id, caps
+   the `.did` and its methods, bounds each compile with a worker deadline,
+   and bounds its caches.
+9. An uncertified interface is labelled, and a failed certificate is never
+   followed by a fallback.
+10. A write shows its sender, target, method and exact bytes before it is
+    sent.