# @ic-reactor/core > How to call Internet Computer canisters with a module `meant gen` > generated from a `.did`, a client from `@ic-reactor/core`, and TanStack > Query. The client applies the rules a hand-written integration must get > right; this guide names the call for each. Applies to `@ic-reactor/core` 4.3.0. ## Imports ```ts import { createClient, formatUnits, isReactorError, parseUnits } from "@ic-reactor/core" import { ReactorProvider, useAuth, useClient } from "@ic-reactor/react" import { isPrincipal, principal, type Principal } from "@meantjs/schema" import { skipToken, useMutation, useQuery } from "@tanstack/react-query" import { actor, type Actor } from "./generated/icrc1" ``` One import path per name: Candid values only from `@meantjs/schema`, `skipToken` and the hooks only from TanStack Query. `@ic-reactor/core` and `@ic-reactor/react` are ES modules only. A Node project needs `"type": "module"` in its `package.json` (`npm pkg set type=module`), or a bundler; `npx tsx` with top-level `await` fails in a CommonJS package. Under TypeScript's `moduleResolution: "nodenext"`, import local files with their `.js` extension (`./generated/icrc1.js`). The generated module (from `meant gen` or `@ic-reactor/vite-plugin`; do not edit it) exports a type and schema per Candid type, the service schema `actor`, and `type Actor`. ## Setup ```ts // src/ledger.ts import { createClient } from "@ic-reactor/core" import { actor, type Actor } from "./generated/icrc1" export const client = createClient({ network: "ic", identity: "anonymous" }) export const ledger = client.canister(actor, { id: "ryjl3-tyaaa-aaaaa-aaaba-cai" }) ``` `client.canister()` returns the same object each time: safe in render. With React, install `@tanstack/query-core` at the exact version your `@tanstack/react-query` depends on (`npm view @tanstack/react-query@ 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. `network` and the root key: - `"ic"`: mainnet (`https://icp-api.io`) and its built-in root key. - `"local"`: icp-cli's local network, `http://127.0.0.1:8000`; its root key is fetched. A dfx replica is `{ host: "http://127.0.0.1:4943" }`. - `{ host, rootKey }`: any other replica. A given `rootKey` is used, never fetched; without one, it is fetched only from a local `host` (`localhost`, `127.0.0.1`, `[::1]`). Never fetch one from any other host. - `"env"`: the page's network. Canisters can be named, `{ name: "backend" }`, from the `ic_env` cookie, believed only on a local replica or with `allowEnvConfig: true`. A server has no cookie: use `{ id }` there. `"env"` is for `localhost` pages: a LAN or Tailscale address, a LAN name with no dot, `*.local`, `*.test`, `*.internal`, `*.ts.net`, a tunnel or a dev container routes to its own origin (never mainnet) but does not believe the cookie or take a root key. `allowEnvConfig: true` throws on `ic0.app`, `*.app.github.dev`, `*.gitpod.io`, `*.loca.lt` and `*.devtunnels.ms` pages (not public suffixes: any sibling site can set the cookie), and never takes the cookie's root key for a mainnet host. `client.canisterId({ name })` says, without a call, what a name resolves to: `{ ok: true, id }`, or `{ ok: false, reason, message }` with `reason` `"no_browser"`, `"untrusted_host"` or `"absent"`, and the resolver's reason text, which a call's error includes after the method and target. - Without the Vite plugin (Next.js, webpack, esbuild) there is no cookie and no `/api` proxy, so `"env"` and `{ name }` do not work on a local network. Use `network: "local"` with `{ id }` from a build-time variable (`NEXT_PUBLIC_BACKEND_ID`, written from `icp canister status -e local -i backend` into `.env.development.local`, which only `next dev` reads). Deploying to mainnet (`icp deploy -e ic`) or to a cloud engine: with `"env"`, a canister's own `.icp0.io` (or `.raw.icp0.io`) page, and a cloud engine app's `.icp.net` page, believes its cookie's canister ids (a public suffix: no sibling can set it) and nothing else: never its root key or its `INTERNET_IDENTITY_PROVIDER` (sign-in stays mainnet's). Off a local page, when the page receives more than one `ic_env` cookie and they differ, none is believed (`{ name }` gets `untrusted_host`). On `.ic0.app` and custom domains `{ name }` does not resolve. For a mainnet app, which should not depend on the cookie, and a page that works everywhere, name canisters `{ id: import.meta.env.VITE_BACKEND_ID }`, with the local id in `.env.development` and the mainnet id (`icp canister status backend -e ic -i`) in `.env.production`. Never set `allowEnvConfig: true` on `ic0.app`; on a custom domain only when every subdomain is yours. Serve the frontend canister with security headers. For DFINITY's asset canister, put `.ic-assets.json5` in Vite's `public/` (icp-cli's static-site recipe reads the same headers from a `_headers` file): ```json5 [ { match: "**/*", security_policy: "hardened", headers: { "Content-Security-Policy": "default-src 'none'; script-src 'self'; connect-src 'self' https://icp-api.io; img-src 'self' data:; style-src 'self'; font-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'", "Cross-Origin-Opener-Policy": "same-origin-allow-popups", }, allow_raw_access: false, }, ] ``` A `Cross-Origin-Opener-Policy` of `same-origin` cuts off the Internet Identity window, so sign-in never completes. The HTTP gateway checks a page against the canister's certified state on `.icp0.io`, not on `.raw.icp0.io`: never link to the raw domain. `createClient` throws a `TypeError` for an option it does not have (`host` goes inside `network`), an `allowEnvConfig` or `fetchRootKey` that is not a boolean (environment text: `=== "true"`), a `rootKey` that is not 133 bytes in a `Uint8Array` (decode hex first), and a `host` the agent cannot call over `http:` or `https:`, including one `"env"` takes from the page or from `ICP_HOST` (`localhost:4943` reads as the scheme `localhost:`; write `http://localhost:4943`). Who calls (exactly one): - `identity`: a fixed `Identity` (scripts, servers, tests), or `"anonymous"`, read-only: every update is refused before sending. A `new AnonymousIdentity()` signs writes, so map one you are handed: `identity: id && !id.getPrincipal().isAnonymous() ? id : "anonymous"`. - `auth: (network) => new AuthClient(network)` (`@icp-sdk/auth/client`, from `@icp-sdk/auth` 11): users sign in and out. The factory runs once, in a browser only; if it throws (blocked `localStorage`) or returns no auth (a Promise, from an `async` factory), the client stays anonymous, public reads still work, and `signIn()` rejects with the error. `network` is `{ agentOptions, identityProvider? }`: the client's host and root key (and its `fetch`, when you gave one), and the Internet Identity to sign in with (that of an `ic_env` cookie believed in full, on a local page or with `allowEnvConfig: true`, never a canister's `icp0.io` page's; or icp-cli's built-in one for a local host). Absent on a mainnet client, it means mainnet's. Absent on any other network (a project that deploys its own `internet_identity`, `"env"` on a local page with no `INTERNET_IDENTITY_PROVIDER` in the cookie, a replica with its own root key), sign-in cannot work, and a factory that reads `network.identityProvider`, as `new AuthClient(network)` does, gets a warning once in development. Name the provider there, which never warns: `(network) => new AuthClient({ ...network, identityProvider: { authorizeUrl, canisterId } })`. A spread that adds other options, `{ ...network, derivationOrigin }`, reads no provider and gets no warning, so name one there too. `() => new AuthClient()` ignores `network`, so it suits mainnet only. On a dfx replica (`{ host: "http://127.0.0.1:4943" }`) the factory is handed icp-cli's built-in Internet Identity on port 4943, which dfx does not serve: name the one the dfx project deploys. Two `signIn()` calls with the same options in one synchronous run, as `StrictMode`'s double effect makes them, are one sign-in. With `new AuthClient({ ...network, transport: "redirect" })` (Internet Identity's ICRC-167 redirect), sign in only on a route of its own that calls `signIn()` on every load, from an effect that starts it on a timer its cleanup clears (a hydrating render shows `"anonymous"` whatever the session). Enter that route with a full page load (``, not a router link): `AuthClient` takes its callback from the page it is built on. List that URL in the origin's `/.well-known/ii-auth-callbacks`. Internet Identity's sign-in features, 2.0's among them, are `AuthClient` options. Pass them in the factory beside `...network` (`openIdProvider`, `ssoDomain`, `derivationOrigin`, `stateStorage: new CookieStateStorage({ domain })`, `namespace`, `disableBrowserActivity`, `transport: "redirect"`, which needs `signIn()` called on the page's load, not from a click), or to `signIn()` (`maxTimeToLive`, `maxTimeToIdle`, `returnTo`). `signIn()` rejects with the auth's own errors (its window closed or blocked, a `SupersededError`), never a `ReactorError`: always catch it. `signOut()` rejects when Internet Identity could not end the session, after the device is signed out and the user's reads are removed: tell the user the session lasts until it expires, not that the sign-out failed. Identity attributes reach a canister as a call's `sender_info`, never as arguments. With DFINITY's `identity-attributes` library on the canister: keep the `AuthClient` the factory builds, and the `identityProvider` canister it is handed (mainnet: `rdmx6-jaaaa-aaaaa-aaadq-cai`), per client; mint the nonce (`_internet_identity_sign_in_start`, an update) through a second client on the same network built with `identity: new AnonymousIdentity()`, since `identity: "anonymous"` and a signed-out client refuse updates; start `client.signIn()` and `requestAttributes({ keys, nonce })` together, from a click; then call `_internet_identity_sign_in_finish` through a client built with `identity: new AttributesIdentity({ inner: await authClient.getIdentity(), attributes, signer: { canisterId } })`, dispose both, and invalidate the app client's reads of that canister. Its `err` rejects as a `canister_err`; an untrusted signer traps (`rejected`, code 5). Trust `verified_email`, never `email` (for an organization's SSO, the canister reads `sso::email` for its `trusted_sso_domains`), and let the canister check the attributes. Who is calling, and may they write: | Question | Answer | | ---------------------- | ------------------------------------------------------------------------- | | the caller's principal | `useAuth().principal`, `client.caller()` (`"2vxsx-fae"` unless signed in) | | may a write be sent | `useAuth().status === "signed-in"`; the client refuses the rest itself | | when did it change | `useAuth()` re-renders; `client.subscribe(fn)` | `"signed-in"` may be a read-only session (Internet Identity can scope one to queries, and the network refuses its updates); nothing tells the two apart yet. A session ends by the clock: `useAuth()` re-renders with `"expired"` at `expiresAt` (ms since the epoch, present while signed in), with no user activity. It can end earlier: a sign-out in another tab reads `"anonymous"` at once, and one on a sibling subdomain that shares the sign-in when the page is next shown or focused; Internet Identity ending it (after `maxTimeToIdle` unused, or the user signing the device out) reads `"expired"` once the auth next asks for a delegation, and a call that needed one rejects `not_delivered` (an update already sent whose answer needed one: `outcome_unknown`). A copy of a delegation already issued stops working within 5 minutes of the end. By default a session lasts up to 30 days and ends after 7 idle days; `maxTimeToLive` and `maxTimeToIdle` shorten it. The client keeps one agent per principal: a call goes out as the principal current when it was made, or not at all. One client per browser tab, or per request on a server. In React, ` createClient(...)}>` builds it once per mounted tree and disposes it on unmount; a module-scope client passed as `client={() => client}` is borrowed, never disposed. A client made outside a provider, or kept across its unmount, is the app's to release with `client.dispose()` (calling it again does nothing; later calls reject `cancelled`, code `client_disposed`, and send nothing); one that lives as long as the page needs none. Inside, `useClient()` returns a view of it for the caller the render shows (anonymous while hydrating): a new object after each sign-in, switch or sign-out, the same one while the caller stays, whose `mutationOptions` send only as that caller (a write pressed before a switch reaches the render is refused `cancelled`, `caller_changed`, and sends nothing). `useAuth()` returns `{ status, principal, expiresAt?, signIn, signOut }`, `"anonymous"` on a server and in a hydrating page's first render. An app that already uses TanStack Query keeps one `QueryClient` per tree, the client's: run its own queries (REST too) under `ReactorProvider`, on `client.queryClient`. An error that is not a `ReactorError` is retried there as TanStack Query retries it (up to 3 times in a browser), and `client.dispose()` clears those queries too. A nested `QueryClientProvider` of the app's still has its reads invalidated by a write that ran on it, but a server render dehydrates `client.queryClient`. Any other sign-in that hands over an `Identity` (a delegation, or a key) becomes an `AuthLike`. A wallet that signs each call itself (ICRC-25 and ICRC-49: OISY, Plug, NFID accounts) is not one: keep the client anonymous for reads, send the wallet's writes with `SignerAgent` from `@icp-sdk/signer`, and then invalidate the reads yourself with `client.queryClient.invalidateQueries({ queryKey: client.queryKey(canister) })`. Such a write gets no `ReactorError` and no `mayHaveExecuted`. ```ts // src/auth-like.ts import type { AuthLike } from "@ic-reactor/core" import type { Identity } from "@icp-sdk/core/agent" export interface SignInSource { getIdentity(): Identity // anonymous while signed out isAuthenticated(): boolean login(): Promise logout(): Promise subscribe(listener: () => void): () => void } export function toAuthLike(source: SignInSource): AuthLike { const signedIn = () => source.isAuthenticated() && !source.getIdentity().getPrincipal().isAnonymous() return { getPrincipal: () => (signedIn() ? source.getIdentity().getPrincipal() : undefined), getStatus: () => ({ state: signedIn() ? "signed-in" : "signed-out" }), getIdentity: async () => source.getIdentity(), subscribe: (listener) => source.subscribe(listener), signIn: () => source.login(), signOut: () => source.logout(), } } ``` ## Values Methods use the generated types: | Candid | Value | | ---------------------------------------- | ---------------------------------------------- | | `nat`, `int`, `nat64`, `int64` | `bigint` (never `number`) | | `nat8`..`nat32`, `int8`..`int32`, floats | `number` | | `text`, `bool` | `string`, `boolean` | | `principal` | `Principal`: branded principal text | | `blob` / `vec nat8` | `Uint8Array` | | `opt T` | `T \| null` (the property is always present) | | `opt opt T`, `opt null` | `{ some: T \| null } \| null`, `{ some: null } \| null` | | `vec T` | `T[]` | | `record { a : T }` | `{ a: T }`, every field present | | `variant { A : T; B }` | `{ tag: "A"; value: T } \| { tag: "B" }` | Make principals from user input with `principal(text)`, which throws a `TypeError` for invalid text: catch it and refuse the input. In render, test with `isPrincipal(text)` first. Direct calls take the parameters `type Actor` lists; the builders below take them as one value: nothing for none, the value for one, a tuple `[a, b]` for more. Token amounts are base units: ```ts /// import { formatUnits, parseUnits } from "@ic-reactor/core" const units = parseUnits("1.5", 8) // 150000000n const text = formatUnits(units, 8, { minFractionDigits: 8 }) // "1.50000000" const local = new Intl.NumberFormat(undefined, { maximumFractionDigits: 8 }).format( text as Intl.StringNumericLiteral // the cast needs lib ES2023 ) ``` `parseUnits` throws for text that is not a plain decimal (`"1e3"`, `"1,5"`), a negative, or more significant fraction digits than `decimals`: refuse that input. Trailing zeros, `"5."`, `".5"` and whitespace around the number are accepted (`"1.500"` at 2 decimals is `150n`), so validate the field with `parseUnits` itself, not another parser. A cap is the Candid type's: a `nat64` field refuses 2^64 at encoding (`invalid_args`); an ICRC-1 `amount` is a `nat`, with none. ### Results A method whose result is `variant { Ok : T; Err : E }` resolves with the `Ok` value; `Err` rejects as kind `"canister_err"`, with the `Err` value in `err` (typed on a query's or mutation's `error`). ## Reads ```tsx import type { Principal } from "@meantjs/schema" import { formatUnits } from "@ic-reactor/core" import { useClient } from "@ic-reactor/react" import { skipToken, useQuery } from "@tanstack/react-query" import { actor, type Actor } from "./generated/icrc1" export function Balance({ owner }: { owner: Principal | undefined }) { const client = useClient() const ledger = client.canister(actor, { id: "ryjl3-tyaaa-aaaaa-aaaba-cai" }) const balance = useQuery( client.queryOptions(ledger, "icrc1_balance_of", owner ? { owner, subaccount: null } : skipToken) ) return

{balance.data === undefined ? "…" : formatUnits(balance.data, 8)}

} ``` `skipToken` stands in for arguments not known yet; arguments that do not encode make the read reject `invalid_args`. Keys are `["ic-reactor", network, caller, canisterId, method, args]`, so one principal's cached answer is never served to another: after a sign-in, sign-out or switch, the new caller's key is empty (`data` is `undefined`) until it loads, and a read made for the previous caller never lands in it. A sign-out, an expired session or a switch also removes the previous caller's reads from the cache; the anonymous reads stay. Keep it so: build the options in render from that render's `useClient()`, listing it in the dependencies of any `useMemo` or effect built from it (React Compiler does), and add nothing that carries data across keys (`placeholderData: keepPreviousData`, cross-key `initialData`). `client.queryKey(ledger, method?, args?)` gives keys for the cache. Reads retry transient failures (never on a server). Spread to add options: `{ ...client.queryOptions(...), staleTime }`. `queryOptions` with an update or oneway method of a generated `Actor` does not compile (an `Actor` written by hand says no mode: it throws at run time). An update that answers the same however often it runs (ckBTC's `get_btc_address`) opts in with a fourth argument, `{ update: "idempotent" }`, after the arguments (`undefined` when it takes none); a oneway never compiles. Such a read is still an update, so a signed-out or `"anonymous"` client refuses it (`unauthenticated`) and sends nothing. Read an ICRC-21 consent message as the caller who will send the write: the message can depend on the caller (the DFINITY ICRC-1 ledger names the sender as `From`). A method TypeScript cannot tell is a read does not compile: a type parameter (`M extends keyof A & string`), a union that may name an update (`keyof Actor & string`), or any method of a `Canister
` with a generic `A`. Give the type arguments, `client.queryOptions(canister, method, vars)`, which keeps the run-time check and types the data `unknown`. The variables follow the same rule, checked at run time: the value for one argument, a tuple for several, `undefined` or `[]` for none (`[arg]` compiles but is refused `invalid_args`). `mutationOptions`, `queryKey` and `resendOf` take `` the same way; for a generic `A` only `queryOptions` widens the variables, so cast them for the other three. The target `{ id, certified: true }` certifies `query` replies: they are sent as replicated calls and checked against the subnet's certificate, where a plain query's reply is signed by the one replica that answered. A certified read costs what an update costs (as long, and the canister pays cycles). Certify the reads that decide where value goes or what a person approves (a recipient, a deposit address, an allowance, the details shown before someone confirms) and read the rest plainly, through two canister objects of one id. ## Writes ```tsx import { useClient } from "@ic-reactor/react" import { useMutation } from "@tanstack/react-query" import { actor, type Actor, type TransferArg } from "./generated/icrc1" export function Send({ arg }: { arg: TransferArg }) { const client = useClient() const ledger = client.canister(actor, { id: "ryjl3-tyaaa-aaaaa-aaaba-cai" }) const transfer = useMutation(client.mutationOptions(ledger, "icrc1_transfer")) return } ``` - The mutation invalidates the canister's reads, for every caller, after a success, a `canister_err` and a failure that may have executed. Nothing else is needed after an unknown outcome. A third argument, `{ invalidates: [canister, [canister, "method"]] }`, names the reads to invalidate instead (name the written canister too if its reads change); `[]`, none. To add an `onSettled`, call the client's from yours. - A write that timed out (`timeoutMs`, below in Errors) whose request went out is `outcome_unknown`: never send it again blindly. - Do not retry a write. `retry` is `false`; keep it. The client itself re-sends an update, at most twice, only after a failure proving the canister never got it (reject code 2, status 429); any other failure is final. - A write is sent as the caller current when `mutate()` was called, or not at all. Held back by TanStack Query (offline, queued behind its `scope`, or retried) while the account changes, it is refused (`cancelled`, `caller_changed`, `mayHaveExecuted: false`) and nothing is sent; a re-send `resendOf` offered is refused as `outcome_unknown` instead (below). This holds with an `onMutate` of yours that replaces the client's, on `client.queryClient`. A mutation restored from a persister is always refused that way: call `mutate()` again. On another `QueryClient`, keep the client's `onMutate` (spread its result into yours; before TanStack Query 5.89, pass it unwrapped). If nobody is signed in, the client refuses it (`unauthenticated`) before calling anything. - Send the same write again after `mayHaveExecuted: true` only to a method that runs the same argument from the same sender at most once, such as an ICRC-1 transfer with `created_at_time` set (it answers `Duplicate`). Stamp that key from the IC's clock, `await client.time(ledger)` (a certified `bigint` of nanoseconds), not from `Date.now()`. That time moves about once a second, so give each transfer its own `memo` too. A time more than five minutes before one the client read already rejects `not_delivered`. `client.resendOf(transfer.error, ledger, "icrc1_transfer", { dedupedBy: (arg) => arg.created_at_time })` is `undefined` unless that write's outcome is unknown, `dedupedBy` finds a key (not `null`) in its argument, the argument is unchanged since it was sent, the canister still resolves where the write went, and its sender is still the caller; then `again.send()` sends the same bytes to the same canister as that sender, and `transfer.mutate(again.arg)` sends the argument only as that same write, or sends nothing (`code` `caller_changed`, `target_changed`, `arg_changed`). A re-send that did not run, refused that way or turned away (a 429 or another 4xx status, reject code 1 to 3), rejects `outcome_unknown` with `mayHaveExecuted: true`, because the first attempt may have run: its `code`, `httpStatus` or `rejectCode` and its `cause` say why, `resendOf` offers that write again while its sender is the caller, and you read the state back before anything else. Never change an offered argument: build a new one for a new transfer. A method with no such key has no safe re-send: read the state back. - For the exact bytes a write will send, such as an ICRC-21 consent request's `arg`, use `client.encode(ledger, "icrc1_transfer", arg)` (a `Uint8Array`, made by the call's own encoder; variables that do not encode throw `invalid_args`), never a second encoding of your own. An offered re-send carries the bytes it sent as `again.bytes`. - A `canister_err` is a known outcome, so `resendOf` offers nothing after it. When the canister calls it temporary (an ICRC-1 `TemporarilyUnavailable`), send the same argument object again with `transfer.mutate(arg)`: with `created_at_time` set, that is the same bytes and the same key, answered `Duplicate` if an earlier attempt ran. - To keep an offer in state, type it from the method: `NonNullable>>`. - Call update methods only from `useMutation` or directly, never from `useQuery`; call query methods from `useQuery` or directly. ## Errors Every rejection is a `ReactorError`: test with `isReactorError(error)`, then read `kind` and `mayHaveExecuted`. For a direct call, test with `isReactorError(error, canister, method)`: it narrows `error.err` to that method's `Err` arm after `kind === "canister_err"` (no cast), and it is `false` for an error of any other method, canister object or `client.func` call (it checks at run time). A failed write either certainly had no effect, or may have executed: | What happened | `kind` | May have executed | | ------------------------------------------------------------------------------- | --------------------------------- | ----------------- | | refused before sending: arguments that do not encode, a write while signed out | `invalid_args`, `unauthenticated` | no | | HTTP 4xx except 408 (429 included): the replica or a boundary node refused it | `not_delivered` | no | | the identity did not sign it (a declined passkey or hardware-wallet prompt: the signer's error is the `cause`), or the request could not be built | `not_delivered` | no | | reject code 1, 2 (transient) or 3: rejected before any canister code ran | `rejected` (2: `not_delivered`) | no | | reject code 4 or 5: the canister rejected or trapped, maybe after changing state | `rejected` | yes (a write) | | a sent write got no trustworthy answer: network drop, timeout, 5xx, 408 | `outcome_unknown` | yes | | a reply that did not decode | `invalid_reply` | yes (a write) | | the canister returned `Err` | `canister_err` | no | | the caller changed, the call was aborted, or a read's `timeoutMs` passed (`code: "timeout"`) | `cancelled` | no (an aborted write: yes) | | a `client.resendOf()` re-send that did not run, refused (its `code` says why) or turned away by any of the rows above (its `httpStatus` or `rejectCode` says why); the first attempt may have run | `outcome_unknown` | yes | A write that got no answer (`outcome_unknown`, or `cancelled` with `mayHaveExecuted: true`) carries `error.expiresAt`: the latest ingress expiry its sends were signed with, a `bigint` of nanoseconds on the IC's clock (about five minutes after the send). A `client.resendOf()` re-send that did not run carries the `expiresAt` of the write it re-sends. Once the IC's time is past it, no send of that write can still start running. For a method that commits without awaiting another canister (an ICRC-1 transfer), a certified read-back of state newer than that which finds nothing is final. Compare with a margin, since the host's clock may differ from the IC's. On the management canister (`aaaaa-aa`), codes 1 to 3 prove nothing: a write there may have executed. A query changes nothing, so a failed read never "may have executed". How long a call waits: unless the call has a `timeoutMs` (below), neither the client nor the agent puts a timeout on an HTTP request (the call or query, or a `read_state` that polls), so a request that gets no answer waits as long as the `fetch` in use does. An accepted update is polled for about five minutes (a deadline checked when a poll is answered) before it rejects `outcome_unknown`. A read made with `queryOptions` stops waiting at any point when TanStack Query cancels it (`queryClient.cancelQueries(...)`, or its last observer unmounts), and rejects `cancelled` (with `mayHaveExecuted: true` for an update read with `{ update: "idempotent" }` whose request went out). To bound the wait, give the canister target `timeoutMs`: `client.canister(actor, { id, timeoutMs: 15_000 })` bounds each of its direct calls, its `queryOptions` reads, its mutations and `client.time()` on it, counted from the call. `client.mutationOptions(ledger, "icrc1_transfer", { timeoutMs: 15_000 })` bounds that mutation's runs instead (1 to 2147483647 ms; anything else throws). When it passes, the call stops waiting and rejects with `code: "timeout"`: `cancelled`, `mayHaveExecuted: false`, for a read and for a write that had not gone out; `outcome_unknown`, `mayHaveExecuted: true`, for a write whose request went out, for an `{ update: "idempotent" }` read whose request went out, and for a re-send of an offered write at any point. That write may still execute: it is an unknown outcome to reconcile like any other (read the state back, or `resendOf` for a method that deduplicates, given the canister object the write went through: another `timeoutMs` is another object), never one to send again blindly. Nothing is sent again for a timeout, and the request is not torn down. Unlike other `cancelled` errors, a `cancelled` with `code: "timeout"` is a real timeout: show it, do not ignore it. Canister objects that differ only in `timeoutMs` share query keys, so a read observed through two of them is bounded by the options TanStack Query was given last. ## Outside React ```ts import { principal } from "@meantjs/schema" import { isReactorError, parseUnits } from "@ic-reactor/core" import { client, ledger } from "./ledger" const account = { owner: principal("aaaaa-aa"), subaccount: null } const cached = await client.queryClient.fetchQuery(client.queryOptions(ledger, "icrc1_balance_of", account)) await client.queryClient.invalidateQueries({ queryKey: client.queryKey(ledger) }) const fresh = await ledger.icrc1_balance_of(account) try { const arg = { to: account, amount: parseUnits("1.5", 8), fee: null, memo: null, from_subaccount: null, created_at_time: null } await ledger.icrc1_transfer(arg) // refused unless `client` was built with an Identity } catch (error) { if (!isReactorError(error, ledger, "icrc1_transfer")) throw error if (error.kind === "canister_err") console.error(error.err.tag) // a TransferError else console.error(error.mayHaveExecuted ? "unknown outcome: re-read first" : error.kind) } ``` Direct calls never touch a cache. To test, `createTestClient()` from `@ic-reactor/core/testing` gives a real client over an in-memory replica with a sign-in you control. ## Example ```tsx import { principal } from "@meantjs/schema" import { createClient } from "@ic-reactor/core" import { ReactorProvider, useAuth, useClient } from "@ic-reactor/react" import { skipToken, useMutation, useQuery } from "@tanstack/react-query" import { toAuthLike, type SignInSource } from "./auth-like" import { actor, type Actor } from "./generated/backend" export function App({ auth }: { auth: SignInSource }) { return ( createClient({ network: "ic", auth: () => toAuthLike(auth) })}> ) } function Profile() { const client = useClient() const { status, principal: caller, signIn } = useAuth() const backend = client.canister(actor, { id: "rrkah-fqaaa-aaaaa-aaaaq-cai" }) const me = principal(caller) const signedIn = status === "signed-in" const profile = useQuery(client.queryOptions(backend, "get_profile", signedIn ? me : skipToken)) const rename = useMutation(client.mutationOptions(backend, "set_name")) if (!signedIn) return if (profile.data === undefined) return

Loading…

return ( <>

{profile.data.name}

{rename.error &&

{rename.error.mayHaveExecuted ? "Unknown outcome" : rename.error.message}

} ) } ``` ## Do not - Cast text to `Principal`: use `principal(text)`. - Convert `bigint` values to `number`: use `parseUnits` and `formatUnits`. - Add `retry` to a write (`{ ...client.mutationOptions(...), retry: 3 }` compiles), or call a write from `useQuery`: TanStack Query may run a query's function again whenever it refetches, and every run of an update executes again. - Write a query key by hand (it leaves the caller out), or carry data across keys (`keepPreviousData`, cross-key `initialData`). - Build agents yourself, a client per render, or one client for every user of a server. - Send a write as the anonymous identity: pass `identity: "anonymous"`, never an `AnonymousIdentity` you were handed. - Treat every failed write as "not executed": read `mayHaveExecuted`. - Pay, or ask a person to approve, a value a plain query read: read recipients, deposit addresses, allowances and approval details through a `certified: true` canister.