@idosgames/mcp 0.1.15 → 0.1.17

package/registry/modules/workshop.json

@@ -39,9 +39,9 @@
     "version": "0.1.0"
   },
   "dependencies": {
-    "@idosgames/core": "0.16.0",
-    "@idosgames/module-sdk": "0.3.3",
-    "@idosgames/react": "0.2.9",
+    "@idosgames/core": "0.18.0",
+    "@idosgames/module-sdk": "0.4.1",
+    "@idosgames/react": "0.2.11",
     "react": "19.2.7"
   },
   "contentHash": "01b9b8439ce44320e7ea8a1aa0a679b3773c291c784a5999c9eab7114c80339d",

package/registry/skills/authentication.json

@@ -1,7 +1,7 @@
 {
   "name": "authentication",
   "description": "Log players into a game on the iDosGames TypeScript SDK (@idosgames/core) via client.auth (AuthenticationService): guest/device-id login, two-step email registration with a confirmation code, email login, Google/Telegram login, SSO-code login from idosgames.com, wallet login, password reset, auto login on relaunch, session refresh, logout, and client-side email/password validation. Use this whenever the user is working in the iDosGames TS SDK or its game templates (board-game, idle-rpg) and asks about logging a player in, sessions, registration, email confirmation codes, resending a code, guest accounts, device-id login, Telegram login, Google login, SSO login, wallet login, forgot/reset password, auto-login, isLoggedIn, or otherwise touches client.auth, AuthenticationService, or AuthContext — even if they don't name the module explicitly.",
-  "content": "---\nname: authentication\ndescription: >-\n  Log players into a game on the iDosGames TypeScript SDK (@idosgames/core)\n  via client.auth (AuthenticationService): guest/device-id login, two-step\n  email registration with a confirmation code, email login, Google/Telegram\n  login, SSO-code login from idosgames.com, wallet login, password reset, auto\n  login on relaunch, session refresh, logout, and client-side email/password\n  validation. Use this whenever the user is working in the iDosGames TS SDK or\n  its game templates (board-game, idle-rpg) and asks about logging a player\n  in, sessions, registration, email confirmation codes, resending a code,\n  guest accounts, device-id login, Telegram login, Google login, SSO login,\n  wallet login, forgot/reset password, auto-login, isLoggedIn, or otherwise\n  touches client.auth, AuthenticationService, or AuthContext — even if they\n  don't name the module explicitly.\n---\n\n# Authentication (iDosGames TS SDK)\n\nThe Authentication module is how a player gets a session. It's the one module\nevery other feature depends on: nothing else on `client` works until a login\nmethod has succeeded. Unlike feature modules, most of its methods don't return\na narrow per-feature payload — they return the **entire post-login bootstrap\nstate** (`ClientState`: title config + the player's full `User` state),\nbecause a successful login is also \"give me everything the client needs to\nrender.\"\n\nThis skill is for **using** production login flows, not for porting or\nextending the service. If a login is rejected, that's the backend enforcing a\nrule (bad credentials, duplicate email, banned account) — surface the error,\ndon't try to reproduce the check client-side.\n\n## Remember me\n\n`setRememberSession(remember)` decides whether a successful login is written to storage. Call it\n**before** a `login*` method — it is read when that login completes, and it applies to whichever\nprovider runs next.\n\n```ts\nclient.auth.setRememberSession(rememberCheckbox); // default: true\nconst result = await client.auth.loginWithDeviceID();\n```\n\n- **On** (the default, and how every release before core 0.1.3 behaved) — the session is persisted,\n  so `autoLogin()` signs the player back in on the next launch.\n- **Off** — nothing is persisted and any previously remembered session is dropped, so the next\n  launch opens on the login screen. The current session is NOT weakened: the credentials stay in\n  memory for this tab, so the transport's automatic 401 re-login still works.\n\n`logout()` ends the session and clears the persisted one, so a reload does not walk back into the\naccount the player just left. (Before core 0.1.3 it left storage untouched and a reload silently\nsigned them back in.)\n\nA wallet session is never remembered either way — a fresh signature is required on every launch.\n\n## Mental model\n\n- **Guest login** (`loginWithDeviceID`) — anonymous account keyed off a\n  per-device ID the platform adapter generates/stores. Zero-friction first\n  launch; no credentials to lose, but also nothing to recover if the device ID\n  is gone (reinstall, new device).\n- **Linked login methods** — `loginWithEmail` / `registerWithEmail`,\n  `loginWithGoogle`, `loginWithTelegram`, `loginWithSsoCode`. These tie\n  the account to a real identity so the player can resume it elsewhere.\n- **`autoLogin()`** picks up where the player left off, but only for methods\n  that don't need a fresh externally-issued token: it replays `loginWithEmail`\n  if the last successful login was Email (saved password), `loginWithDeviceID`\n  if it was Device/None, and `loginWithTelegram` if it was Telegram (its\n  `initData` is re-read live from the Telegram WebApp bridge each time, not\n  stored). For Google/Facebook/GooglePlay/platform-token, there's no stored\n  credential to replay — `autoLogin()` returns `reason: \"client\"` instead of\n  guessing, because DeviceID and email/platform logins hash to **different\n  backend UserIDs** (see Gotchas), so silently falling back to a guest login\n  would strand the player on an unrelated empty account. What `autoLogin()`\n  has to replay is controlled by **\"remember me\"** — see below. Call this on app\n  start instead of hand-rolling \"which method did they use last,\" but be ready\n  to handle its failure by re-running the platform's sign-in flow.\n- **Session refresh is automatic.** The HTTP transport calls\n  `refreshSession()` itself when a request comes back 401 — it re-runs\n  `autoLogin()` under the hood and retries once. You almost never call\n  `refreshSession()` directly; it's documented here for completeness, not as a\n  method you wire up in app code.\n- **Static validators** (`AuthenticationService.isValidEmail`,\n  `AuthenticationService.isValidPasswordLength`) are plain synchronous\n  functions, not calls to the backend — use them to validate a form before\n  spending a network round-trip on a login/register call that will fail\n  server-side anyway. They mirror, but do not replace, the server's own\n  checks — the server always re-validates.\n\n## Setup\n\n```ts\nimport { createIDosGamesClient } from \"@idosgames/core\";\n\nconst client = createIDosGamesClient({ titleID: \"your-title-id\" });\nawait client.auth.loginWithDeviceID(); // or any other auth.* login method\n\nclient.auth.isLoggedIn; // true once a login call has succeeded\n```\n\nEvery other module's methods require this to have succeeded first — without a\nsession they return `{ ok: false, reason: \"unauthorized\" }` rather than\nthrowing. There is one `client` per player; don't share it across sessions.\nAuthentication requests carry no Bearer ticket at all — login/register/reset\nare the one family of calls that work before you have a session.\n\n## Methods\n\nAll login/register/reset methods return `Promise<OperationResult<T>>`: either\n`{ ok: true, data }` or `{ ok: false, reason, error }`. Always branch on\n`result.ok` before touching `result.data`. `reason` is one of `\"client\"` (bad\nlocal args, e.g. missing Telegram initData or empty platform token),\n`\"unauthorized\"`, `\"throttled\"` (fired the same endpoint again inside the\nthrottle window), `\"connection\"` (transient, offer Retry), `\"validation\"`\n(response/schema drift), or `\"server\"` (backend rejected it — `error` carries\nthe reason code the backend returned, e.g. `\"INCORRECT_EMAIL_OR_PASSWORD\"`,\n`\"INVALID_VERIFICATION_CODE\"` — see Gotchas for the verbatim set).\n\n| Method                                            | Purpose                                                                                                                                           | `data` on success                           |\n| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |\n| `loginWithDeviceID()`                             | Anonymous/guest login keyed off the device ID.                                                                                                    | `ClientState`                               |\n| `loginWithTelegram()`                             | Login using the Telegram Mini App's init data.                                                                                                    | `ClientState`                               |\n| `loginWithEmail(email, password)`                 | Login with email + password.                                                                                                                      | `ClientState`                               |\n| `registerWithEmail(email, password)`              | **Start** a registration. Only mails a code — never returns a session, see below.                                                                 | `EmailRegistrationOutcome`                  |\n| `confirmEmailRegistration(email, code)`           | Finish the registration with the code from the email, creating the player.                                                                        | `ClientState`                               |\n| `resendVerificationCode(email)`                   | Mail a fresh code. Resolves successfully whatever happened — except when there is no usable sender at all (`EMAIL_SENDER_NOT_CONFIGURED`).        | `void`                                      |\n| `requestWalletChallenge(networkID, address)`      | Ask for the message the player's wallet must sign. Step one of wallet login.                                                                      | `WalletChallengeResponse`                   |\n| `loginWithWallet(networkID, address, signature)`  | Exchange the signed challenge for a title session.                                                                                                | `ClientState`                               |\n| `loginWithGoogle(googleIDToken)`                  | Login with a Google ID token.                                                                                                                     | `ClientState`                               |\n| `loginWithSsoCode(code)`                          | Exchange a one-time code from idosgames.com for a title session. **Web only** — see below.                                                        | `ClientState`                               |\n| `forgotPassword(email)`                           | Trigger a password-reset email (a 6-digit code).                                                                                                  | `SuccessResponse`                           |\n| `resetPassword(email, resetToken, password)`      | Complete a password reset using the emailed code.                                                                                                 | `SuccessResponse`                           |\n| `autoLogin()`                                     | Replay the last-used auth method (Email/Device/None/Telegram only — fails with `reason: \"client\"` for Google/Facebook/GooglePlay/platform-token). | `ClientState`                               |\n| `refreshSession()`                                | Re-authenticate and return a fresh session ticket; used internally by the transport on 401.                                                       | `string \\| null` (not an `OperationResult`) |\n| `logout()`                                        | Clear the session, forget the saved login method, and reset the local cache. Synchronous, no network call.                                        | `void`                                      |\n| `setRememberSession(remember)`                    | \"Remember me\" — whether the NEXT login is persisted for `autoLogin()`. Default `true`. Call before a `login*` method.                             | `void`                                      |\n| `AuthenticationService.isValidEmail(email)`       | Static, synchronous client-side format check.                                                                                                     | `boolean`                                   |\n| `AuthenticationService.isValidPasswordLength(pw)` | Static, synchronous length check (8–100 chars).                                                                                                   | `boolean`                                   |\n\n⚠ **Each title has its OWN password.** The same address in two games means two independent\npasswords: resetting in one game does not change the login for the other. The reason is that the\nreset e-mail goes out through the PUBLISHER's SMTP — with one shared password, one publisher's mail\nserver would control access to every other publisher's game. So don't tell the player \"the same\npassword as in your other game\", and don't reuse stored credentials across titles.\nThe IDENTITY is still shared: Google, Apple and the idosgames.com sign-in recognise the same person\nin every game. Identity answers \"who is this\", not \"what proves they may sign in\".\n\n⚠ **Signing in through idosgames.com from a NATIVE build is not in this SDK.** `beginSsoRedirect` /\n`loginWithSsoCode` are the web half: the browser comes back to the same page with the code in the\nURL fragment. In a packaged Android/iOS build the browser is a separate program that tells the app\nnothing, so that flow uses a request the game polls for instead (`BeginNativeSsoRequest` /\n`PollNativeSsoRequest`), and it is implemented in the Unity SDK. Don't reach for `loginWithSsoCode`\nfrom a native wrapper — it has no way to receive the code.\n\n⚠ **That native flow now has a SHORT CODE, and a native client should use it.** `BeginNativeSsoRequest`\naccepts `UseUserCode: true` and then answers with `UserCode` (`WDJB-MJHT`) plus `VerificationUri`.\nThe game displays the code; the player opens the plain URL and types it there. The older shape — the\ngame opening `…/sso?title=X&request=<handle>` and the page confirming on its own — still works for\nalready-shipped builds, but **a request created with a code refuses that path**, so a build must do\none or the other, never a mix.\n\nThe reason is not convenience. In the older shape the handle travels IN THE ADDRESS, so the link can\nbe sent to somebody else: the attacker creates the request on their own device, the victim opens the\nlink and confirms, and the attacker's game gets a session as the victim. PKCE does not help (the\nverifier belongs to whoever created the request). With a code there is nothing in the URL to forward\n— the request is named only by what is on the device's own screen. `GetAuthOptions` reports\n`NativeSso.UserCodeSupported` and `NativeSso.PollIntervalSeconds`; ask before assuming, and follow\nthe interval or the poll quota will refuse you.\n\n⚠ **The code is shown, the secret is not.** Players read codes off screens, over shoulders and out\nof screenshots — so the code alone must never buy a session. Polling keeps requiring the request\nsecret, which never leaves the game.\n\nNon-Promise instance getters (read directly, no `await`):\n\n| Getter                     | Returns                                                                                                                                                                                        |\n| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `client.auth.context`      | `AuthContext \\| null` — `{ userID, clientSessionTicket, clientSessionTicketExpiration, platformUserID?, platformAuthToken?, platformAuthTokenExpiration? }`, or `null` if never logged in.     |\n| `client.auth.isLoggedIn`   | `true` once `context` has a non-empty `userID` and `clientSessionTicket`.                                                                                                                      |\n| `client.auth.lastAuthType` | The persisted `AuthType` (`\"None\" \\| \"Device\" \\| \"Email\" \\| \"iDosGames\" \\| \"Facebook\" \\| \"Google\" \\| \"GooglePlay\" \\| \"Telegram\"`) from the previous successful login, read from local storage. |\n\nOn a successful login/register call, the SDK mirrors the full `ClientState`\ninto `client.data` (title config + user state) — same cache every other\nmodule reads from — and emits events. `email`/`password` are persisted to\nlocal storage **only** after a successful `loginWithEmail` or\n`confirmEmailRegistration` call, so `autoLogin()` has something to replay.\n⚠ Note it is the CONFIRMATION, not `registerWithEmail`, that persists them:\nregistration alone creates no account, so there is nothing to replay yet (the\npassword is carried over from the first step internally). A leftover\nusername you pass in is only a fallback — Google logins use the Google\nprofile name, platform-token logins use the platform profile name, and if\nnone is available anywhere the backend assigns a generated one (see Gotchas).\n\n## Events\n\nSubscribe with `client.on(...)`; each returns an unsubscribe fn.\n\n- `auth:requestSent` → `void` — fired at the start of every login/reset call (before the network round-trip). One exception: `loginWithSsoCode` validates its argument first, so an empty-code `reason: \"client\"` failure doesn't fire it.\n- `auth:loggedIn` → `void` — fired after a login/register call succeeds and `ClientState` has been applied to the cache.\n- `auth:loggedOut` → `void` — fired synchronously by `logout()`.\n- `auth:unauthorized` → `void` — transport-level, fired by the HTTP layer only when a 401 could **not** be transparently recovered (the automatic refresh was unavailable, already attempted, or failed). A 401 that the refresh-and-retry rescues never emits it. Not emitted by `AuthenticationService` itself.\n- `user:clientStateReceived` → `ClientState` — fired whenever a full client state is applied (login, or any other flow that re-fetches it).\n- `user:stateUpdated` → `void` — fired whenever the cached `User` half of `ClientState` is replaced, which includes every successful login.\n- `user:anyUpdated` → `void` — coarsest \"something in the user cache changed\" signal; also fires on login.\n\n```ts\nconst off = client.on(\"auth:loggedIn\", () => {\n  console.log(\"logged in as\", client.auth.context?.userID);\n});\n// later: off();\n```\n\n## Recipes\n\n### Guest login on first launch\n\n```ts\nconst result = await client.auth.loginWithDeviceID();\nif (!result.ok) return showError(result.error ?? result.reason);\n// client.data now has the full ClientState; render the game.\n```\n\n### Try auto-login first, fall back appropriately\n\n```ts\nasync function bootstrap() {\n  const result = await client.auth.autoLogin();\n  if (result.ok) return; // resumed the last session\n  if (result.reason === \"client\" && client.auth.lastAuthType !== \"None\") {\n    // Last session used Google/Facebook/GooglePlay/a platform token — autoLogin\n    // can't replay that silently. Re-run that platform's sign-in flow and call\n    // the matching login method (e.g. loginWithGoogle) with a fresh token.\n    return reauthenticateViaPlatformSDK(client.auth.lastAuthType);\n  }\n  showError(result.error ?? result.reason);\n}\n```\n\n`autoLogin()` safely self-replays Email, Device/None, and Telegram — call it\nonce on app start for those. For anything else it deliberately does **not**\nfall back to a guest login (see Gotchas) — treat its `reason: \"client\"`\nfailure as \"go get a fresh token,\" not as a generic error to toast.\n\n### Register a new account with email\n\n```ts\nif (!AuthenticationService.isValidEmail(email)) {\n  return showFieldError(\"email\", \"Enter a valid email address.\");\n}\nif (!AuthenticationService.isValidPasswordLength(password)) {\n  return showFieldError(\"password\", \"Password must be 8–100 characters.\");\n}\n\nconst started = await client.auth.registerWithEmail(email, password);\nif (!started.ok) return showError(started.error ?? started.reason);\n\n// No account yet — a code was mailed. Show a code screen; the session arrives from confirm.\nconst done = await client.auth.confirmEmailRegistration(email, codeFromPlayer);\nif (!done.ok) return showError(done.error ?? done.reason);\n```\n\n⚠ **`registerWithEmail` never creates an account, and success does not mean the address was\nfree.**\n\nRegistration always stores the attempt and mails a 6-digit code; the player is created by\n`confirmEmailRegistration`. Building a screen that assumes an immediate session will leave players\nstaring at a spinner that never resolves.\n\nConfirmation is **platform behaviour, not a title setting** — there is no flag to switch it off,\nand no `verificationRequired` branch to write. Only the numbers are configurable (code lifetime,\nattempt cap, resend cooldown).\n\nThe answer is also deliberately **identical for a free and for a taken address** — there is no\n`EMAIL_ALREADY_EXISTS` on this path any more. Telling them apart would turn the registration form\ninto a way of checking whether a given person has an account here, which is exactly what the\npassword-recovery form goes out of its way to avoid. The owner of a taken address gets a \"you\nalready have an account\" e-mail instead, without a code.\n\nOne failure on this path **is** reported: `EMAIL_SENDER_NOT_CONFIGURED`, when the server has no\nusable mail sender at all. It says nothing about the address — the same answer comes back for a\nfree one, a taken one and a typo — and it exists because confirmation cannot be switched off: with\nno sender, e-mail registration does not work at all, and answering \"code sent\" would hide a broken\ndeployment behind a normal-looking screen. Show it as a server-side problem, not as the player's\nmistake, and do not offer a \"resend\" — the resend refuses the same way. A letter that merely fails\nto leave is a different case and still answers success.\n\nEvery way of getting the code wrong — no such registration, expired, mismatched — answers with the\nsame `INVALID_VERIFICATION_CODE`, for the same reason. Do not branch on it.\n\n`resendVerificationCode` mails a **new** code: only its hash is stored, so the previous one cannot\nbe re-sent and stops working. Rate-limit the button in the UI (the server's cooldown is reported as\n`resendCooldownSeconds`) — the server answers successfully even when it sent nothing.\n\nEmail is matched case-insensitively — the backend trims and lowercases it\nbefore every lookup and write, so `Player@Mail.com` and `player@mail.com`\ncollide on the same account.\n\n### Upgrade a guest account to an email account\n\nThe SDK has no dedicated \"link email to this guest\" call — `registerWithEmail`\nalways mints its **own** account (a fresh UserID derived from the email, via a\ndifferent hash than the device-id account uses). To move a guest forward\nwithout losing their progress, do it through your own game-side flow (e.g. a\ncloud script that copies/merges state) rather than assuming registration\ncarries the guest's inventory along; don't build a UI that implies it will.\n\n### Forgot / reset password\n\n```ts\nconst sent = await client.auth.forgotPassword(email);\nif (!sent.ok) return showError(sent.error ?? sent.reason);\n// If an account exists for this email, a 6-digit reset code was emailed,\n// valid for 5 minutes. The response looks identical whether or not the\n// email is registered (see Gotchas) — don't tell the player \"no such account.\"\n\nconst reset = await client.auth.resetPassword(email, resetToken, newPassword);\nif (!reset.ok) return showError(reset.error ?? reset.reason);\n// password changed; call loginWithEmail with the new password next\n```\n\n### Handle a rejected login\n\n```ts\nconst result = await client.auth.loginWithEmail(email, password);\nif (!result.ok) {\n  switch (result.reason) {\n    case \"connection\":\n      return offerRetry();\n    case \"throttled\":\n      return; // ignore — same call already in flight/just ran\n    case \"client\":\n    case \"server\":\n    default:\n      return showError(result.error ?? \"Login failed.\");\n  }\n}\n```\n\n### Log out\n\n```ts\nclient.auth.logout(); // synchronous — clears context + resets client.data cache\n// route to login screen; no network call is made\n```\n\n## Gotchas\n\n- **`autoLogin()` deliberately refuses to guess for federated/platform\n  logins.** The backend derives DeviceID UserIDs from\n  `SHA256(platform + device + deviceID)` and email/platform-linked UserIDs\n  from `SHA256(email + titleID)` — two different hashes with no server-side\n  link between them. Falling back to `loginWithDeviceID()` for a\n  Google/Facebook/GooglePlay/platform-token session would silently resolve to\n  a different, empty account, not \"safely resume as a guest.\" If\n  `lastAuthType` is one of those, `autoLogin()` returns\n  `{ ok: false, reason: \"client\" }` instead; the app must obtain a fresh token\n  from that platform's SDK and call the matching `login*` method itself.\n- **The exact `error` strings on `reason: \"server\"` are backend-defined\n  codes/messages**, not prose meant for direct display — surface them through\n  your own copy/localization layer rather than showing them raw. Verified\n  values from the backend for the flows above: `\"INVALID_INPUT_DATA\"`\n  (missing/blank required field) and `\"INCORRECT_EMAIL_OR_PASSWORD\"` (bad\n  credentials **or** unknown email — the backend intentionally doesn't\n  distinguish the two, so don't tell the player \"no such account\") and\n  `\"INVALID_VERIFICATION_CODE\"` (every way of getting the confirmation code\n  wrong, collapsed into one) are shared\n  `MessageCode` enum values also used elsewhere in the backend;\n  `\"EMAIL_ALREADY_EXISTS\"` is **no longer returned by registration** — the form\n  answers identically for a free and for a taken address, on purpose;\n  `\"RATE_LIMIT_EXCEEDED\"` / `\"OPERATION_IN_PROGRESS\"` (per-account login lock\n  — see below) are the same enum family. Google/platform-token logins instead\n  return ad-hoc string literals specific to that flow, e.g. `\"BANNED_GLOBAL\"`\n  (platform account is banned), `\"GOOGLE_ACCOUNT_CONFLICT\"` (email already\n  linked to a _different_ Google account), `\"INVALID_GOOGLE_TOKEN\"`\n  (bad/expired Google ID token) — see\n  [references/data-model.md](references/data-model.md) for the full list.\n  Telegram login instead surfaces plain sentences like `\"Invalid Telegram\ndata\"` / an internal `\"Telegram auth_date is stale\"` condition (initData\n  older than 24h or timestamped implausibly in the future) — treat any\n  non-uppercase-code string as an opaque message, not something to\n  pattern-match on.\n- **Per-account login is rate-limited server-side, independent of the SDK's\n  own 600 ms throttle.** Repeated `loginWithEmail` attempts for the same\n  account inside a ~1-second window come back `\"RATE_LIMIT_EXCEEDED\"`; a login\n  already being processed for that account comes back\n  `\"OPERATION_IN_PROGRESS\"`. This is a brute-force guard, not a bug — don't\n  retry-loop past it.\n- **Telegram login needs the platform adapter's init data.** `loginWithTelegram()`\n  calls `platform.getTelegramInitDataRaw()` first; if that returns falsy (not\n  running inside Telegram, or the adapter doesn't support it), the call fails\n  client-side with `reason: \"client\"` before any network request — no point\n  retrying without fixing the environment. Server-side, the init data is\n  rejected if its `auth_date` is missing, more than 24 hours old, or more than\n  5 minutes in the future — a Telegram Mini App that's been idle a long time\n  may need a fresh WebApp launch, not just a retry. On success it's recorded\n  under its own `AuthType.Telegram` (not `Device`) precisely so `autoLogin()`\n  replays `loginWithTelegram()` again rather than a device-id login.\n- **`loginWithPlatformToken` no longer exists.** The site used to hand games the\n  platform auth token — a 24-hour string that also authorizes the whole\n  management API. It was replaced by the one-time SSO code\n  (`loginWithSsoCode`), and the endpoint has since been removed as unreachable.\n  A session opened by that code is still recorded under `AuthType.iDosGames`,\n  which is what `lastAuthType` reports afterward.\n- **A username you pass in is a last resort, not a guarantee.** For Google and\n  platform-token logins, the backend prefers the identity provider's own\n  profile name over any client-supplied username on every login (not just the\n  first) — so a locally cached display name can be silently overwritten by the\n  linked account's name. If no name is available from any source at\n  registration time, the backend assigns a generated one\n  (`\"BraveTiger482\"`-style: adjective + noun + 2–4 digit number) rather than\n  leaving it blank.\n- **`forgotPassword` never reveals whether an email is registered.** Unknown\n  emails and known emails both return `{ ok: true }` with no email actually\n  sent for the unknown case — this is a deliberate anti-enumeration measure,\n  not a bug to work around. The emailed reset code is a 6-digit number valid\n  for 5 minutes; requesting again inside a 60-second cooldown silently\n  no-ops (still returns `ok: true`, no second email). `resetPassword` allows\n  at most 5 wrong-code attempts before the code is invalidated server-side and\n  a fresh `forgotPassword` call is required.\n  ⚠ **The remaining-attempt count is NOT in the response any more**, and neither\n  is \"no such account\": every outcome of `resetPassword` — unknown address, no\n  code requested, expired code, wrong code — answers `\"INVALID_RESET_CODE\"`, and\n  an exhausted code answers `\"RESET_CODE_ATTEMPTS_EXCEEDED\"`. Reporting the\n  remaining count both confirmed the account existed and told an attacker how\n  much room was left. Don't parse a number out of `error`.\n- **Email credentials are only saved on success.** `loginWithEmail` and\n  `confirmEmailRegistration` persist email+password to local storage (scoped by\n  `titleID`) only after `fetchAndApplyClientState` succeeds — a failed login\n  doesn't overwrite previously saved credentials, and a fresh install has\n  nothing saved until the first successful email login. `registerWithEmail` on\n  its own saves nothing: at that point the account does not exist yet.\n- **`refreshSession()` has a re-entrancy guard.** If it's already running\n  (e.g. two requests 401 at nearly the same time), a second call returns `null`\n  immediately instead of recursing — this exists to avoid deadlocking the\n  retry, so don't assume a `null` result means the session is actually dead.\n- **`logout()` forgets the saved login method too (changed in core 0.1.3).** It\n  nulls the auth context, wipes the cached user state and title-config bundle,\n  clears `lastAuthType` and any saved email/password, and emits\n  `auth:loggedOut` — so a later `autoLogin()` has nothing to resume. Before\n  0.1.3 storage survived a logout and the next launch silently signed the\n  player back into the account they had just left. If you want a sign-out the\n  player is remembered through, don't call `logout()`.\n- **`refreshSession()` and `logout()` don't return `OperationResult`.**\n  `refreshSession()` resolves to `string | null` (the fresh session ticket, or\n  `null` on failure/no saved method); `logout()` is synchronous `void`. Don't\n  branch on `.ok` for these two.\n- **`GameLoop` is excluded from the login `ClientState`.** Board/stage state\n  and its definitions are fetched separately per-stage by the GameLoop\n  feature, not bundled into every login response.\n- **Guard against double-submit.** Each call fires a real request; a\n  double-tapped \"Log in\" button can fire twice. Firing the same auth endpoint\n  again inside the SDK's own throttle window (default 600 ms) comes back\n  `reason: \"throttled\"` rather than duplicating the call, but disable the\n  control while a call is in flight rather than relying on that — and note the\n  server has its own, stricter per-account lock on top (see above).\n\n## Full reference\n\n[references/data-model.md](references/data-model.md) — request/response wire\nshapes, the exact backend validation and error-code rules for each login/reset\npath, UserID derivation, and the default-username generator. Read it when you\nneed to reason about _why_ a specific `error` string came back, or when\nbuilding a password-reset or registration UI that needs to match the backend's\ntiming/attempt rules exactly.\n",
+  "content": "---\nname: authentication\ndescription: >-\n  Log players into a game on the iDosGames TypeScript SDK (@idosgames/core)\n  via client.auth (AuthenticationService): guest/device-id login, two-step\n  email registration with a confirmation code, email login, Google/Telegram\n  login, SSO-code login from idosgames.com, wallet login, password reset, auto\n  login on relaunch, session refresh, logout, and client-side email/password\n  validation. Use this whenever the user is working in the iDosGames TS SDK or\n  its game templates (board-game, idle-rpg) and asks about logging a player\n  in, sessions, registration, email confirmation codes, resending a code,\n  guest accounts, device-id login, Telegram login, Google login, SSO login,\n  wallet login, forgot/reset password, auto-login, isLoggedIn, or otherwise\n  touches client.auth, AuthenticationService, or AuthContext — even if they\n  don't name the module explicitly.\n---\n\n# Authentication (iDosGames TS SDK)\n\nThe Authentication module is how a player gets a session. It's the one module\nevery other feature depends on: nothing else on `client` works until a login\nmethod has succeeded. Unlike feature modules, most of its methods don't return\na narrow per-feature payload — they return the **entire post-login bootstrap\nstate** (`ClientState`: title config + the player's full `User` state),\nbecause a successful login is also \"give me everything the client needs to\nrender.\"\n\nThis skill is for **using** production login flows, not for porting or\nextending the service. If a login is rejected, that's the backend enforcing a\nrule (bad credentials, duplicate email, banned account) — surface the error,\ndon't try to reproduce the check client-side.\n\n## Remember me\n\n`setRememberSession(remember)` decides whether a successful login is written to storage. Call it\n**before** a `login*` method — it is read when that login completes, and it applies to whichever\nprovider runs next.\n\n```ts\nclient.auth.setRememberSession(rememberCheckbox); // default: true\nconst result = await client.auth.loginWithDeviceID();\n```\n\n- **On** (the default, and how every release before core 0.1.3 behaved) — the session is persisted,\n  so `autoLogin()` signs the player back in on the next launch.\n- **Off** — nothing is persisted and any previously remembered session is dropped, so the next\n  launch opens on the login screen. The current session is NOT weakened: the credentials stay in\n  memory for this tab, so the transport's automatic 401 re-login still works.\n\n`logout()` ends the session and clears the persisted one, so a reload does not walk back into the\naccount the player just left. (Before core 0.1.3 it left storage untouched and a reload silently\nsigned them back in.)\n\nSessions are extended by the **refresh token** (`Authentication/RefreshSession`, core ≥ 0.18): every\nlogin returns one, it is kept in memory and — when remembering — in storage, and rotated on every\nrefresh. A 401 and a cold-start `autoLogin()` use it first, so ANY method comes back, wallet and\nGoogle included; replaying the login method is only the fallback for a missing/expired token. On a\ntitle whose login mode needs a token balance the server re-checks it on that refresh; a balance\nthat dropped closes the game (`client.auth.playAccess.Granted === false`), it does not end the session.\n\n## Mental model\n\n- **Guest login** (`loginWithDeviceID`) — anonymous account keyed off a\n  per-device ID the platform adapter generates/stores. Zero-friction first\n  launch; no credentials to lose, but also nothing to recover if the device ID\n  is gone (reinstall, new device).\n- **Linked login methods** — `loginWithEmail` / `registerWithEmail`,\n  `loginWithGoogle`, `loginWithTelegram`, `loginWithSsoCode`. These tie\n  the account to a real identity so the player can resume it elsewhere.\n- **`autoLogin()`** picks up where the player left off. It first extends the\n  remembered session by its **refresh token** (works for every method). Only\n  without a usable token does it fall back to replaying — and that fallback\n  covers just the methods that don't need a fresh externally-issued token: it replays `loginWithEmail`\n  if the last successful login was Email (saved password), `loginWithDeviceID`\n  if it was Device/None, and `loginWithTelegram` if it was Telegram (its\n  `initData` is re-read live from the Telegram WebApp bridge each time, not\n  stored). For Google/Facebook/GooglePlay/platform-token, there's no stored\n  credential to replay — `autoLogin()` returns `reason: \"client\"` instead of\n  guessing, because DeviceID and email/platform logins hash to **different\n  backend UserIDs** (see Gotchas), so silently falling back to a guest login\n  would strand the player on an unrelated empty account. What `autoLogin()`\n  has to replay is controlled by **\"remember me\"** — see below. Call this on app\n  start instead of hand-rolling \"which method did they use last,\" but be ready\n  to handle its failure by re-running the platform's sign-in flow.\n- **Session refresh is automatic.** The HTTP transport calls\n  `refreshSession()` itself when a request comes back 401 — it calls the\n  server's `RefreshSession` with the refresh token (falling back to replaying\n  the login method only without a usable token) and retries once. You almost never call\n  `refreshSession()` directly; it's documented here for completeness, not as a\n  method you wire up in app code.\n- **Static validators** (`AuthenticationService.isValidEmail`,\n  `AuthenticationService.isValidPasswordLength`) are plain synchronous\n  functions, not calls to the backend — use them to validate a form before\n  spending a network round-trip on a login/register call that will fail\n  server-side anyway. They mirror, but do not replace, the server's own\n  checks — the server always re-validates.\n\n## Setup\n\n```ts\nimport { createIDosGamesClient } from \"@idosgames/core\";\n\nconst client = createIDosGamesClient({ titleID: \"your-title-id\" });\nawait client.auth.loginWithDeviceID(); // or any other auth.* login method\n\nclient.auth.isLoggedIn; // true once a login call has succeeded\n```\n\nEvery other module's methods require this to have succeeded first — without a\nsession they return `{ ok: false, reason: \"unauthorized\" }` rather than\nthrowing. There is one `client` per player; don't share it across sessions.\nAuthentication requests carry no Bearer ticket at all — login/register/reset\nare the one family of calls that work before you have a session.\n\n## Methods\n\nAll login/register/reset methods return `Promise<OperationResult<T>>`: either\n`{ ok: true, data }` or `{ ok: false, reason, error }`. Always branch on\n`result.ok` before touching `result.data`. `reason` is one of `\"client\"` (bad\nlocal args, e.g. missing Telegram initData or empty platform token),\n`\"unauthorized\"`, `\"throttled\"` (fired the same endpoint again inside the\nthrottle window), `\"connection\"` (transient, offer Retry), `\"validation\"`\n(response/schema drift), or `\"server\"` (backend rejected it — `error` carries\nthe reason code the backend returned, e.g. `\"INCORRECT_EMAIL_OR_PASSWORD\"`,\n`\"INVALID_VERIFICATION_CODE\"` — see Gotchas for the verbatim set).\n\n| Method                                            | Purpose                                                                                                                                           | `data` on success                           |\n| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |\n| `loginWithDeviceID()`                             | Anonymous/guest login keyed off the device ID.                                                                                                    | `ClientState`                               |\n| `loginWithTelegram()`                             | Login using the Telegram Mini App's init data.                                                                                                    | `ClientState`                               |\n| `loginWithEmail(email, password)`                 | Login with email + password.                                                                                                                      | `ClientState`                               |\n| `registerWithEmail(email, password)`              | **Start** a registration. Only mails a code — never returns a session, see below.                                                                 | `EmailRegistrationOutcome`                  |\n| `confirmEmailRegistration(email, code)`           | Finish the registration with the code from the email, creating the player.                                                                        | `ClientState`                               |\n| `resendVerificationCode(email)`                   | Mail a fresh code. Resolves successfully whatever happened — except when there is no usable sender at all (`EMAIL_SENDER_NOT_CONFIGURED`).        | `void`                                      |\n| `requestWalletChallenge(networkID, address)`      | Ask for the message the player's wallet must sign. Step one of wallet login.                                                                      | `WalletChallengeResponse`                   |\n| `loginWithWallet(networkID, address, signature)`  | Exchange the signed challenge for a title session.                                                                                                | `ClientState`                               |\n| `loginWithGoogle(googleIDToken)`                  | Login with a Google ID token.                                                                                                                     | `ClientState`                               |\n| `loginWithSsoCode(code)`                          | Exchange a one-time code from idosgames.com for a title session. **Web only** — see below.                                                        | `ClientState`                               |\n| `forgotPassword(email)`                           | Trigger a password-reset email (a 6-digit code).                                                                                                  | `SuccessResponse`                           |\n| `resetPassword(email, resetToken, password)`      | Complete a password reset using the emailed code.                                                                                                 | `SuccessResponse`                           |\n| `autoLogin()`                                     | Replay the last-used auth method (Email/Device/None/Telegram only — fails with `reason: \"client\"` for Google/Facebook/GooglePlay/platform-token). | `ClientState`                               |\n| `refreshSession()`                                | Re-authenticate and return a fresh session ticket; used internally by the transport on 401.                                                       | `string \\| null` (not an `OperationResult`) |\n| `logout()`                                        | Clear the session, forget the saved login method, and reset the local cache. Synchronous, no network call.                                        | `void`                                      |\n| `setRememberSession(remember)`                    | \"Remember me\" — whether the NEXT login is persisted for `autoLogin()`. Default `true`. Call before a `login*` method.                             | `void`                                      |\n| `AuthenticationService.isValidEmail(email)`       | Static, synchronous client-side format check.                                                                                                     | `boolean`                                   |\n| `AuthenticationService.isValidPasswordLength(pw)` | Static, synchronous length check (8–100 chars).                                                                                                   | `boolean`                                   |\n\n⚠ **Each title has its OWN password.** The same address in two games means two independent\npasswords: resetting in one game does not change the login for the other. The reason is that the\nreset e-mail goes out through the PUBLISHER's SMTP — with one shared password, one publisher's mail\nserver would control access to every other publisher's game. So don't tell the player \"the same\npassword as in your other game\", and don't reuse stored credentials across titles.\nThe IDENTITY is still shared: Google, Apple and the idosgames.com sign-in recognise the same person\nin every game. Identity answers \"who is this\", not \"what proves they may sign in\".\n\n⚠ **Signing in through idosgames.com from a NATIVE build is not in this SDK.** `beginSsoRedirect` /\n`loginWithSsoCode` are the web half: the browser comes back to the same page with the code in the\nURL fragment. In a packaged Android/iOS build the browser is a separate program that tells the app\nnothing, so that flow uses a request the game polls for instead (`BeginNativeSsoRequest` /\n`PollNativeSsoRequest`), and it is implemented in the Unity SDK. Don't reach for `loginWithSsoCode`\nfrom a native wrapper — it has no way to receive the code.\n\n⚠ **That native flow now has a SHORT CODE, and a native client should use it.** `BeginNativeSsoRequest`\naccepts `UseUserCode: true` and then answers with `UserCode` (`WDJB-MJHT`) plus `VerificationUri`.\nThe game displays the code; the player opens the plain URL and types it there. The older shape — the\ngame opening `…/sso?title=X&request=<handle>` and the page confirming on its own — still works for\nalready-shipped builds, but **a request created with a code refuses that path**, so a build must do\none or the other, never a mix.\n\nThe reason is not convenience. In the older shape the handle travels IN THE ADDRESS, so the link can\nbe sent to somebody else: the attacker creates the request on their own device, the victim opens the\nlink and confirms, and the attacker's game gets a session as the victim. PKCE does not help (the\nverifier belongs to whoever created the request). With a code there is nothing in the URL to forward\n— the request is named only by what is on the device's own screen. `GetAuthOptions` reports\n`NativeSso.UserCodeSupported` and `NativeSso.PollIntervalSeconds`; ask before assuming, and follow\nthe interval or the poll quota will refuse you.\n\n⚠ **The code is shown, the secret is not.** Players read codes off screens, over shoulders and out\nof screenshots — so the code alone must never buy a session. Polling keeps requiring the request\nsecret, which never leaves the game.\n\nNon-Promise instance getters (read directly, no `await`):\n\n| Getter                     | Returns                                                                                                                                                                                        |\n| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `client.auth.context`      | `AuthContext \\| null` — `{ userID, clientSessionTicket, clientSessionTicketExpiration, platformUserID?, platformAuthToken?, platformAuthTokenExpiration? }`, or `null` if never logged in.     |\n| `client.auth.isLoggedIn`   | `true` once `context` has a non-empty `userID` and `clientSessionTicket`.                                                                                                                      |\n| `client.auth.lastAuthType` | The persisted `AuthType` (`\"None\" \\| \"Device\" \\| \"Email\" \\| \"iDosGames\" \\| \"Facebook\" \\| \"Google\" \\| \"GooglePlay\" \\| \"Telegram\"`) from the previous successful login, read from local storage. |\n\nOn a successful login/register call, the SDK mirrors the full `ClientState`\ninto `client.data` (title config + user state) — same cache every other\nmodule reads from — and emits events. `email`/`password` are persisted to\nlocal storage **only** after a successful `loginWithEmail` or\n`confirmEmailRegistration` call, so `autoLogin()` has something to replay.\n⚠ Note it is the CONFIRMATION, not `registerWithEmail`, that persists them:\nregistration alone creates no account, so there is nothing to replay yet (the\npassword is carried over from the first step internally). A leftover\nusername you pass in is only a fallback — Google logins use the Google\nprofile name, platform-token logins use the platform profile name, and if\nnone is available anywhere the backend assigns a generated one (see Gotchas).\n\n## Events\n\nSubscribe with `client.on(...)`; each returns an unsubscribe fn.\n\n- `auth:requestSent` → `void` — fired at the start of every login/reset call (before the network round-trip). One exception: `loginWithSsoCode` validates its argument first, so an empty-code `reason: \"client\"` failure doesn't fire it.\n- `auth:loggedIn` → `void` — fired after a login/register call succeeds and `ClientState` has been applied to the cache.\n- `auth:loggedOut` → `void` — fired synchronously by `logout()`.\n- `auth:unauthorized` → `void` — transport-level, fired by the HTTP layer only when a 401 could **not** be transparently recovered (the automatic refresh was unavailable, already attempted, or failed). A 401 that the refresh-and-retry rescues never emits it. Not emitted by `AuthenticationService` itself.\n- `user:clientStateReceived` → `ClientState` — fired whenever a full client state is applied (login, or any other flow that re-fetches it).\n- `user:stateUpdated` → `void` — fired whenever the cached `User` half of `ClientState` is replaced, which includes every successful login.\n- `user:anyUpdated` → `void` — coarsest \"something in the user cache changed\" signal; also fires on login.\n\n```ts\nconst off = client.on(\"auth:loggedIn\", () => {\n  console.log(\"logged in as\", client.auth.context?.userID);\n});\n// later: off();\n```\n\n## Recipes\n\n### Guest login on first launch\n\n```ts\nconst result = await client.auth.loginWithDeviceID();\nif (!result.ok) return showError(result.error ?? result.reason);\n// client.data now has the full ClientState; render the game.\n```\n\n### Try auto-login first, fall back appropriately\n\n```ts\nasync function bootstrap() {\n  const result = await client.auth.autoLogin();\n  if (result.ok) return; // resumed the last session\n  if (result.reason === \"client\" && client.auth.lastAuthType !== \"None\") {\n    // Last session used Google/Facebook/GooglePlay/a platform token — autoLogin\n    // can't replay that silently. Re-run that platform's sign-in flow and call\n    // the matching login method (e.g. loginWithGoogle) with a fresh token.\n    return reauthenticateViaPlatformSDK(client.auth.lastAuthType);\n  }\n  showError(result.error ?? result.reason);\n}\n```\n\n`autoLogin()` safely self-replays Email, Device/None, and Telegram — call it\nonce on app start for those. For anything else it deliberately does **not**\nfall back to a guest login (see Gotchas) — treat its `reason: \"client\"`\nfailure as \"go get a fresh token,\" not as a generic error to toast.\n\n### Register a new account with email\n\n```ts\nif (!AuthenticationService.isValidEmail(email)) {\n  return showFieldError(\"email\", \"Enter a valid email address.\");\n}\nif (!AuthenticationService.isValidPasswordLength(password)) {\n  return showFieldError(\"password\", \"Password must be 8–100 characters.\");\n}\n\nconst started = await client.auth.registerWithEmail(email, password);\nif (!started.ok) return showError(started.error ?? started.reason);\n\n// No account yet — a code was mailed. Show a code screen; the session arrives from confirm.\nconst done = await client.auth.confirmEmailRegistration(email, codeFromPlayer);\nif (!done.ok) return showError(done.error ?? done.reason);\n```\n\n⚠ **`registerWithEmail` never creates an account, and success does not mean the address was\nfree.**\n\nRegistration always stores the attempt and mails a 6-digit code; the player is created by\n`confirmEmailRegistration`. Building a screen that assumes an immediate session will leave players\nstaring at a spinner that never resolves.\n\nConfirmation is **platform behaviour, not a title setting** — there is no flag to switch it off,\nand no `verificationRequired` branch to write. Only the numbers are configurable (code lifetime,\nattempt cap, resend cooldown).\n\nThe answer is also deliberately **identical for a free and for a taken address** — there is no\n`EMAIL_ALREADY_EXISTS` on this path any more. Telling them apart would turn the registration form\ninto a way of checking whether a given person has an account here, which is exactly what the\npassword-recovery form goes out of its way to avoid. The owner of a taken address gets a \"you\nalready have an account\" e-mail instead, without a code.\n\nOne failure on this path **is** reported: `EMAIL_SENDER_NOT_CONFIGURED`, when the server has no\nusable mail sender at all. It says nothing about the address — the same answer comes back for a\nfree one, a taken one and a typo — and it exists because confirmation cannot be switched off: with\nno sender, e-mail registration does not work at all, and answering \"code sent\" would hide a broken\ndeployment behind a normal-looking screen. Show it as a server-side problem, not as the player's\nmistake, and do not offer a \"resend\" — the resend refuses the same way. A letter that merely fails\nto leave is a different case and still answers success.\n\nEvery way of getting the code wrong — no such registration, expired, mismatched — answers with the\nsame `INVALID_VERIFICATION_CODE`, for the same reason. Do not branch on it.\n\n`resendVerificationCode` mails a **new** code: only its hash is stored, so the previous one cannot\nbe re-sent and stops working. Rate-limit the button in the UI (the server's cooldown is reported as\n`resendCooldownSeconds`) — the server answers successfully even when it sent nothing.\n\nEmail is matched case-insensitively — the backend trims and lowercases it\nbefore every lookup and write, so `Player@Mail.com` and `player@mail.com`\ncollide on the same account.\n\n### Upgrade a guest account to an email account\n\nThe SDK has no dedicated \"link email to this guest\" call — `registerWithEmail`\nalways mints its **own** account (a fresh UserID derived from the email, via a\ndifferent hash than the device-id account uses). To move a guest forward\nwithout losing their progress, do it through your own game-side flow (e.g. a\ncloud script that copies/merges state) rather than assuming registration\ncarries the guest's inventory along; don't build a UI that implies it will.\n\n### Forgot / reset password\n\n```ts\nconst sent = await client.auth.forgotPassword(email);\nif (!sent.ok) return showError(sent.error ?? sent.reason);\n// If an account exists for this email, a 6-digit reset code was emailed,\n// valid for 5 minutes. The response looks identical whether or not the\n// email is registered (see Gotchas) — don't tell the player \"no such account.\"\n\nconst reset = await client.auth.resetPassword(email, resetToken, newPassword);\nif (!reset.ok) return showError(reset.error ?? reset.reason);\n// password changed; call loginWithEmail with the new password next\n```\n\n### Handle a rejected login\n\n```ts\nconst result = await client.auth.loginWithEmail(email, password);\nif (!result.ok) {\n  switch (result.reason) {\n    case \"connection\":\n      return offerRetry();\n    case \"throttled\":\n      return; // ignore — same call already in flight/just ran\n    case \"client\":\n    case \"server\":\n    default:\n      return showError(result.error ?? \"Login failed.\");\n  }\n}\n```\n\n### Log out\n\n```ts\nclient.auth.logout(); // synchronous — clears context + resets client.data cache\n// route to login screen; no network call is made\n```\n\n## Gotchas\n\n- **A title's login mode can refuse methods** (`cfg.Blockchain.PlayAccess`). `WalletOnly` accepts\n  only wallet login (others fail with `PLAY_ACCESS_WALLET_LOGIN_ONLY`); `AnyWithLinkedWallet` refuses\n  guests (`PLAY_ACCESS_GUEST_DISABLED`) and lets other logins in with `client.auth.playAccess.Granted\n=== false` until a wallet is linked and holds enough tokens. Read the mode BEFORE login with\n  `client.auth.getAuthOptions()` (`PlayAccessMode`) to hide dead buttons. The host template does all\n  of this already — see the `blockchain-system` skill, \"Login mode and play access\".\n- **`autoLogin()` deliberately refuses to guess for federated/platform\n  logins.** The backend derives DeviceID UserIDs from\n  `SHA256(platform + device + deviceID)` and email/platform-linked UserIDs\n  from `SHA256(email + titleID)` — two different hashes with no server-side\n  link between them. Falling back to `loginWithDeviceID()` for a\n  Google/Facebook/GooglePlay/platform-token session would silently resolve to\n  a different, empty account, not \"safely resume as a guest.\" If\n  `lastAuthType` is one of those, `autoLogin()` returns\n  `{ ok: false, reason: \"client\" }` instead; the app must obtain a fresh token\n  from that platform's SDK and call the matching `login*` method itself.\n- **The exact `error` strings on `reason: \"server\"` are backend-defined\n  codes/messages**, not prose meant for direct display — surface them through\n  your own copy/localization layer rather than showing them raw. Verified\n  values from the backend for the flows above: `\"INVALID_INPUT_DATA\"`\n  (missing/blank required field) and `\"INCORRECT_EMAIL_OR_PASSWORD\"` (bad\n  credentials **or** unknown email — the backend intentionally doesn't\n  distinguish the two, so don't tell the player \"no such account\") and\n  `\"INVALID_VERIFICATION_CODE\"` (every way of getting the confirmation code\n  wrong, collapsed into one) are shared\n  `MessageCode` enum values also used elsewhere in the backend;\n  `\"EMAIL_ALREADY_EXISTS\"` is **no longer returned by registration** — the form\n  answers identically for a free and for a taken address, on purpose;\n  `\"RATE_LIMIT_EXCEEDED\"` / `\"OPERATION_IN_PROGRESS\"` (per-account login lock\n  — see below) are the same enum family. Google/platform-token logins instead\n  return ad-hoc string literals specific to that flow, e.g. `\"BANNED_GLOBAL\"`\n  (platform account is banned), `\"GOOGLE_ACCOUNT_CONFLICT\"` (email already\n  linked to a _different_ Google account), `\"INVALID_GOOGLE_TOKEN\"`\n  (bad/expired Google ID token) — see\n  [references/data-model.md](references/data-model.md) for the full list.\n  Telegram login instead surfaces plain sentences like `\"Invalid Telegram\ndata\"` / an internal `\"Telegram auth_date is stale\"` condition (initData\n  older than 24h or timestamped implausibly in the future) — treat any\n  non-uppercase-code string as an opaque message, not something to\n  pattern-match on.\n- **Per-account login is rate-limited server-side, independent of the SDK's\n  own 600 ms throttle.** Repeated `loginWithEmail` attempts for the same\n  account inside a ~1-second window come back `\"RATE_LIMIT_EXCEEDED\"`; a login\n  already being processed for that account comes back\n  `\"OPERATION_IN_PROGRESS\"`. This is a brute-force guard, not a bug — don't\n  retry-loop past it.\n- **Telegram login needs the platform adapter's init data.** `loginWithTelegram()`\n  calls `platform.getTelegramInitDataRaw()` first; if that returns falsy (not\n  running inside Telegram, or the adapter doesn't support it), the call fails\n  client-side with `reason: \"client\"` before any network request — no point\n  retrying without fixing the environment. Server-side, the init data is\n  rejected if its `auth_date` is missing, more than 24 hours old, or more than\n  5 minutes in the future — a Telegram Mini App that's been idle a long time\n  may need a fresh WebApp launch, not just a retry. On success it's recorded\n  under its own `AuthType.Telegram` (not `Device`) precisely so `autoLogin()`\n  replays `loginWithTelegram()` again rather than a device-id login.\n- **`loginWithPlatformToken` no longer exists.** The site used to hand games the\n  platform auth token — a 24-hour string that also authorizes the whole\n  management API. It was replaced by the one-time SSO code\n  (`loginWithSsoCode`), and the endpoint has since been removed as unreachable.\n  A session opened by that code is still recorded under `AuthType.iDosGames`,\n  which is what `lastAuthType` reports afterward.\n- **A username you pass in is a last resort, not a guarantee.** For Google and\n  platform-token logins, the backend prefers the identity provider's own\n  profile name over any client-supplied username on every login (not just the\n  first) — so a locally cached display name can be silently overwritten by the\n  linked account's name. If no name is available from any source at\n  registration time, the backend assigns a generated one\n  (`\"BraveTiger482\"`-style: adjective + noun + 2–4 digit number) rather than\n  leaving it blank.\n- **`forgotPassword` never reveals whether an email is registered.** Unknown\n  emails and known emails both return `{ ok: true }` with no email actually\n  sent for the unknown case — this is a deliberate anti-enumeration measure,\n  not a bug to work around. The emailed reset code is a 6-digit number valid\n  for 5 minutes; requesting again inside a 60-second cooldown silently\n  no-ops (still returns `ok: true`, no second email). `resetPassword` allows\n  at most 5 wrong-code attempts before the code is invalidated server-side and\n  a fresh `forgotPassword` call is required.\n  ⚠ **The remaining-attempt count is NOT in the response any more**, and neither\n  is \"no such account\": every outcome of `resetPassword` — unknown address, no\n  code requested, expired code, wrong code — answers `\"INVALID_RESET_CODE\"`, and\n  an exhausted code answers `\"RESET_CODE_ATTEMPTS_EXCEEDED\"`. Reporting the\n  remaining count both confirmed the account existed and told an attacker how\n  much room was left. Don't parse a number out of `error`.\n- **Email credentials are only saved on success.** `loginWithEmail` and\n  `confirmEmailRegistration` persist email+password to local storage (scoped by\n  `titleID`) only after `fetchAndApplyClientState` succeeds — a failed login\n  doesn't overwrite previously saved credentials, and a fresh install has\n  nothing saved until the first successful email login. `registerWithEmail` on\n  its own saves nothing: at that point the account does not exist yet.\n- **`refreshSession()` has a re-entrancy guard.** If it's already running\n  (e.g. two requests 401 at nearly the same time), a second call returns `null`\n  immediately instead of recursing — this exists to avoid deadlocking the\n  retry, so don't assume a `null` result means the session is actually dead.\n- **`logout()` forgets the saved login method too (changed in core 0.1.3).** It\n  nulls the auth context, wipes the cached user state and title-config bundle,\n  clears `lastAuthType` and any saved email/password, and emits\n  `auth:loggedOut` — so a later `autoLogin()` has nothing to resume. Before\n  0.1.3 storage survived a logout and the next launch silently signed the\n  player back into the account they had just left. If you want a sign-out the\n  player is remembered through, don't call `logout()`.\n- **`refreshSession()` and `logout()` don't return `OperationResult`.**\n  `refreshSession()` resolves to `string | null` (the fresh session ticket, or\n  `null` on failure/no saved method); `logout()` is synchronous `void`. Don't\n  branch on `.ok` for these two.\n- **`GameLoop` is excluded from the login `ClientState`.** Board/stage state\n  and its definitions are fetched separately per-stage by the GameLoop\n  feature, not bundled into every login response.\n- **Guard against double-submit.** Each call fires a real request; a\n  double-tapped \"Log in\" button can fire twice. Firing the same auth endpoint\n  again inside the SDK's own throttle window (default 600 ms) comes back\n  `reason: \"throttled\"` rather than duplicating the call, but disable the\n  control while a call is in flight rather than relying on that — and note the\n  server has its own, stricter per-account lock on top (see above).\n\n## Full reference\n\n[references/data-model.md](references/data-model.md) — request/response wire\nshapes, the exact backend validation and error-code rules for each login/reset\npath, UserID derivation, and the default-username generator. Read it when you\nneed to reason about _why_ a specific `error` string came back, or when\nbuilding a password-reset or registration UI that needs to match the backend's\ntiming/attempt rules exactly.\n",
   "references": [
     {
       "path": "data-model.md",

package/registry/skills/blockchain-system.json

@@ -1,7 +1,7 @@
 {
   "name": "blockchain-system",
   "description": "Bridge in-game assets on-chain in a game on the iDosGames TypeScript SDK (@idosgames/core) via client.blockchain (BlockchainService): load blockchain network/config definitions, load the player's on-chain state (linked wallets, pending withdrawals, KYC, stats), deposit a token or NFT from a wallet into the game, request a token or NFT withdrawal out to a wallet, read on-chain transaction history, retry a still-pending withdrawal's signature, confirm a withdrawal's on-chain tx hash, and donate crypto to the developer or a users' pool. Use this whenever the user is working in the iDosGames TS SDK or its game templates (board-game, idle-rpg) and wants crypto wallets, NFT deposits/withdrawals, token bridging, on-chain asset transfers, KYC status, or otherwise touches client.blockchain, BlockchainService, BlockchainDefinitions, UserBlockchainState, DepositTokenResponse, TokenWithdrawalResponse, or NFTWithdrawalResponse — even if they don't name the module explicitly.",
-  "content": "---\nname: blockchain-system\ndescription: >-\n  Bridge in-game assets on-chain in a game on the iDosGames TypeScript SDK\n  (@idosgames/core) via client.blockchain (BlockchainService): load blockchain\n  network/config definitions, load the player's on-chain state (linked\n  wallets, pending withdrawals, KYC, stats), deposit a token or NFT from a\n  wallet into the game, request a token or NFT withdrawal out to a wallet,\n  read on-chain transaction history, retry a still-pending withdrawal's\n  signature, confirm a withdrawal's on-chain tx hash, and donate crypto to\n  the developer or a users' pool. Use this whenever the user is working in\n  the iDosGames TS SDK or its game templates (board-game, idle-rpg) and wants crypto wallets, NFT\n  deposits/withdrawals, token bridging, on-chain asset transfers, KYC status,\n  or otherwise touches client.blockchain, BlockchainService,\n  BlockchainDefinitions, UserBlockchainState, DepositTokenResponse,\n  TokenWithdrawalResponse, or NFTWithdrawalResponse — even if they don't name\n  the module explicitly.\n---\n\n# Blockchain system (iDosGames TS SDK)\n\nThe Blockchain module bridges in-game assets to and from real wallets on\nsupported chains (EVM and Solana networks). A player can deposit a token or\nNFT they already sent on-chain (crediting their in-game balance/inventory),\nor request a withdrawal that pays an in-game token/NFT out to their wallet\n(debiting their in-game balance/inventory and producing a signature the\nplayer submits on-chain themselves). Everything is **server-authoritative**:\nthe client reports/requests, the backend validates the transaction against\nthe chain, applies rules (network enabled, KYC, account-safety policy), and\nthe SDK mirrors the confirmed result into a local cache your UI reads. You\nnever credit/debit balances yourself.\n\nThis skill is for **using** the production `BlockchainService`, not for\nporting or extending it, and not for signing/broadcasting transactions\nyourself — this SDK reports deposits and requests withdrawals; actually\nsending the on-chain transaction (the deposit transfer, or broadcasting a\nwithdrawal signature) happens with a wallet SDK outside this client.\n\n> **The on-chain half is the `@idosgames/wallet` companion package.** It\n> connects browser & mobile wallets (EVM via wagmi/viem/WalletConnect, Solana\n> via wallet-adapter) and runs the exact RewardPool contract calls, threading\n> them through this service's request → submit → confirm / approve → deposit →\n> report lifecycle. If the user wants to actually connect a wallet and move\n> tokens/NFTs (not just call `client.blockchain.*`), reach for that package —\n> see its README. Everything below documents the server-authoritative\n> `client.blockchain` surface that `@idosgames/wallet` builds on. The wallet\n> package's EVM surface covers both NFT standards: `submitEvmNftWithdrawal` /\n> `depositNftEvm` (+ `erc1155Abi`) for ERC-1155 collections, and\n> `submitEvmNftWithdrawal721` / `depositNftEvm721` (+ `erc721Abi`) for\n> ERC-721 unique-item collections (4-arg `safeTransferFrom`, no `id`/`amount`\n> — the token is always qty 1). `submitEvmTokenWithdrawal`'s `withdrawERC20`\n> call now also threads `sig.BurnAmount` through (see\n> [Burn on withdrawal](#gotchas) below) — the ABI/contract call order changed,\n> so an app pinned to an older `@idosgames/wallet` build will revert on-chain\n> against an updated RewardPool contract.\n\n> **Never import `@idosgames/wallet/react` (or `/react/solana`) from a file\n> that loads on startup.** Those subpaths pull in Reown AppKit, and AppKit is\n> deliberately _not_ a dependency of a generated project — the live preview\n> resolves every declared dependency up front and times out on AppKit's tree.\n> A static import therefore blanks the preview before any game code runs\n> (`Could not find dependency: '@reown/appkit-adapter-wagmi'`), while the real\n> build stays green — that mismatch is the signature of this mistake.\n> Two rules keep both working:\n>\n> - **Sign-in button:** import `LazyWalletLogin` / `LazySolanaWalletLogin` from\n>   `@idosgames/wallet/react/lazy` (that entry has no AppKit in its graph; it\n>   also re-exports the chains as plain objects — never import chains from\n>   `wagmi/chains` or `viem/chains`, that barrel breaks the preview too).\n> - **In-game deposit/withdraw panel:** import `LazyWalletPanel` from\n>   `@idosgames/wallet/react/lazy` and pass it the authenticated `client` (a\n>   prop, like the login button — never a module context). Same lazy contract:\n>   AppKit stays out of the startup graph. Don't hand-roll your own\n>   `await import(\"./PanelImpl\")` wrapper — `LazyWalletPanel` is that wrapper.\n>   Because the wallet config is memoised per WalletConnect project id, the\n>   panel reuses the wallet the player connected at sign-in: same store, so it\n>   opens already-connected, no second tap and no second modal. This is exactly\n>   how the board-game and idle-rpg modules wire their `WalletPanel.tsx`.\n\n> **The wallet is unreachable while the game is embedded in an idosgames.com iframe** (owner's\n> decision, 2026-09-17 — deposit/withdraw goes through the site's own panel there, not a wallet\n> connected inside the game). You don't need to special-case this: `LazyWalletLogin` /\n> `LazySolanaWalletLogin` / `LazyWalletPanel` already detect it (`isEmbeddedInPlatform` from\n> `@idosgames/wallet`) and render a short \"use idosgames.com\" notice instead of the button/panel —\n> and every flow function (`depositTokenEvm`, `withdrawTokenEvm`, `loginWithWalletEvm`, their Solana\n> equivalents, `payWithWalletEvm`) refuses with `WALLET_USE_SITE_PANEL` if called anyway. A game\n> opened by its own direct link (not embedded) is unaffected — every one of these works exactly as\n> before there.\n\n### Operation category (`game_topup` by default)\n\nThe updated RewardPool contract tags every deposit/withdrawal with a string\n**category** (default `\"game_topup\"`; `\"community_reward\"` is the other known\nvalue, and arbitrary strings are allowed). On a **withdrawal** the server signs\nthe category into the on-chain hash and returns it on the signature payload\n(`EvmSignature.Category` / `.TitleID`); whoever submits the transaction **must\npass the same value on-chain verbatim** or the contract rejects the signature —\n`@idosgames/wallet` does this for you. Pass it as the optional last arg to\n`requestTokenWithdrawal`/`requestNFTWithdrawal` (omit → `\"game_topup\"`). On a\n**deposit** the category is read back from the on-chain transaction, so you\ndon't pass it to `depositToken`/`depositNFT`. It also appears on transaction\ndocuments as `Category`. Import the constants from `@idosgames/core`:\n`BlockchainOperationCategory.GameTopUp` / `.CommunityReward`.\n\n## Mental model: deposits vs. withdrawals\n\n- **Deposit** = the player already sent tokens/an NFT to the platform's pool\n  or vault address on-chain. The client then calls `depositToken`/`depositNFT`\n  with that transaction's hash so the backend can verify it and credit the\n  player in-game. One-shot: the credit happens directly on a successful call.\n- **Withdrawal** = the player wants an in-game token/NFT sent out to their\n  wallet. The client calls `requestTokenWithdrawal`/`requestNFTWithdrawal`,\n  which **debits in-game immediately** and returns a signed payload\n  (`EvmSignature` or `SolanaSignature`) the player's wallet must submit\n  on-chain to actually receive the asset. This is a **multi-step, async\n  flow** — see [Recipes](#recipes) for the full lifecycle, including what to\n  do when the on-chain submission fails.\n\nBoth flows are per-network: every call takes a `networkID` that must match one\nof the title's configured `Networks` (EVM or Solana), each with its own\ndeposit/withdrawal enable flags, contract/vault addresses, and (for NFTs) a\ncollection binding to an item catalog. Withdrawals additionally run through a\nlong chain of server-side gates (balances, per-network minimums, account\nsafety, KYC, daily/monthly compliance limits, a collective title-wide pool\ncap, and platform commission) — see\n[Withdrawal gates](#withdrawal-gates-what-can-reject-a-request) for the full\nlist with verbatim error strings.\n\nFor the full config/state field shapes (network definitions, NFT collection\nbindings, KYC tiers, transaction documents, signature payloads), read\n[references/data-model.md](references/data-model.md). You do **not** need it\nto call the methods — only to drive richer UI (network pickers, KYC gates,\ntransaction history tables).\n\n## Setup\n\n```ts\nimport { createIDosGamesClient } from \"@idosgames/core\";\n\nconst client = createIDosGamesClient({ titleID: \"your-title-id\" });\nawait client.auth.loginWithDeviceID(); // or any auth.* method\n\nconst blockchain = client.blockchain; // the BlockchainService\n```\n\nEvery blockchain method requires an authenticated session. Without one they\nreturn `{ ok: false, reason: \"unauthorized\" }` — they do not throw.\n\n## Methods\n\nAll methods return `Promise<OperationResult<T>>`: a discriminated union that\nis either `{ ok: true, data }` or `{ ok: false, reason, error }`. Always\nbranch on `result.ok` before touching `result.data`. `reason` is one of\n`\"client\"` (missing/empty required arg — rejected before any network call),\n`\"unauthorized\"`, `\"throttled\"` (fired the same endpoint again inside the\n600ms client-side throttle window), `\"connection\"` (transient, offer Retry),\n`\"validation\"` (response/schema drift), or `\"server\"` (backend rejected it —\n`error` carries the exact backend message). Withdrawals in particular can be\nrejected by a long chain of server-side gates — see\n[Withdrawal gates](#withdrawal-gates-what-can-reject-a-request) below for the\nfull list with verbatim error strings.\n\n| Method                                                                                               | Purpose                                                                                              | `data` on success             |\n| ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------- |\n| `getDefinitions()`                                                                                   | Load the title's blockchain config: networks, NFT bindings, crypto currencies.                       | `BlockchainConfigResponse`    |\n| `getUserState()`                                                                                     | Load this player's on-chain state: linked wallets, pending withdrawals, KYC, stats, crypto balances. | `UserBlockchainStateResponse` |\n| `depositToken(networkID, transactionHash)`                                                           | Report an on-chain token transfer; credits the matching crypto balance.                              | `DepositTokenResponse`        |\n| `depositNFT(networkID, transactionHash)`                                                             | Report an on-chain NFT transfer; grants the matching in-game item.                                   | `DepositNFTResponse`          |\n| `requestTokenWithdrawal(currencyID, networkID, walletAddress, amount, category?)`                    | Debit a crypto balance and get a signed payload to withdraw on-chain.                                | `TokenWithdrawalResponse`     |\n| `requestNFTWithdrawal(itemID, networkID, walletAddress, amount, category?, level?, itemInstanceID?)` | Consume an in-game item and get a signed payload to withdraw the NFT on-chain.                       | `NFTWithdrawalResponse`       |\n| `getTransactionHistory(limit?)`                                                                      | Load recent token + NFT transaction documents (default limit 50).                                    | `TransactionHistoryResponse`  |\n| `retryWithdrawal(titleTransactionID)`                                                                | Re-issue a fresh signature for a still-`Pending` withdrawal without re-debiting.                     | `RetryWithdrawalResponse`     |\n| `confirmWithdrawal(titleTransactionID, onChainTransactionHash)`                                      | Tell the backend the signed withdrawal was submitted on-chain, with its tx hash.                     | `ConfirmWithdrawalResponse`   |\n| `donateToDeveloper(networkID, transactionHash)`                                                      | Report an on-chain transfer as a donation to the developer pool (no personal credit).                | `DonationResponse`            |\n| `donateToUsersPool(networkID, transactionHash)`                                                      | Report an on-chain transfer as a donation to the users' pool (no personal credit).                   | `DonationResponse`            |\n\nAll string args (`networkID`, `transactionHash`, `currencyID`,\n`walletAddress`, `amount`, `itemID`, `titleTransactionID`,\n`onChainTransactionHash`) are required and checked client-side before any\nnetwork call — an empty one short-circuits with `reason: \"client\"`. `amount`\nis a decimal string for token withdrawals and an integer-as-string for NFT\nwithdrawals / not used for deposits (deposit amounts come from the verified\non-chain transaction, not from the client). `getTransactionHistory(limit)`\ndefaults to `50`, is capped at **200** server-side (values above are silently\nclamped, values `<= 0` fall back to 50), and is sent as `Amount` on the wire\n(reused request field, not an actual currency amount).\n\n`requestNFTWithdrawal`'s trailing `level`/`itemInstanceID` are both optional\nand only matter for NFT catalogs with leveled or unique (ERC-721) bindings:\n`level` selects which leveled instance/tokenId to withdraw (omit or `1` →\nbase level, prior behavior); `itemInstanceID` is **required** when the\nitem's NFT binding is ERC-721 — it tells the server exactly which\nunstackable instance to debit and tokenize (preserving its Level/RemainingUses/\nCustomData in the on-chain registry via a separate ItemBridge contract).\nBoth are ignored for stackable/ERC-1155 items.\n\nOn success, most methods **mirror the confirmed change into the cache and\nemit an event** — see the next section for exactly which cache each method\ntouches, since it's not uniform across this module.\n\n## Withdrawal gates (what can reject a request)\n\n`requestTokenWithdrawal` / `requestNFTWithdrawal` run through a long chain of\nserver-side checks, each a `reason: \"server\"` failure with a specific `error`\nstring. Surface the string; don't try to pre-validate all of these\nclient-side — the gate list can change without a client update:\n\n- **Global kill switch** — withdrawals can be turned off platform-wide\n  independently of any per-network/per-currency flag: `\"Withdrawals are\ncurrently disabled.\"`\n- **Network / currency / binding disabled** — `\"Withdrawals disabled for this\nnetwork.\"`, `\"Withdrawals are disabled for currency '{id}'.\"`, `\"This\ncurrency cannot be withdrawn in this network.\"`, or (currency under\n  maintenance) `\"Currency '{id}' is under maintenance. Try again later.\"`\n- **Per-network minimum** — every currency has a `MinWithdraw` for each\n  network it's bound to (`CryptoNetworkBinding.MinWithdraw`, see the\n  currency-system skill's data-model for the full shape): `\"Minimum withdraw\nis {MinWithdraw} {currencyID}.\"`\n- **Insufficient balance** — `\"Not enough balance: have {available}\n{currencyID}, need {amount}.\"` (tokens) or `\"Not enough items: have {owned},\nneed {amount}.\"` (NFTs).\n- **Account safety** (`BlockchainAccountSafetyPolicy`, read-only in\n  `getDefinitions()`'s `AccountSafety` block) — applies to withdrawals only,\n  never deposits: account younger than `MinAccountAgeDays` →\n  `\"Account is too fresh. Try again later.\"`; banned account → `\"Account is\nbanned. Contact support.\"`; withdrawing to a wallet address another account\n  already used, when `MultiAccountCheckEnabled` +\n  `BanOnSharedWithdrawalAddress` are both on, **bans the account on the\n  spot** and returns `\"Account banned. Contact support.\"`\n- **Compliance / KYC** (`CryptoCurrencyDefinition.Limits`, per currency) —\n  checked in USD-equivalent of the requested amount:\n  - Above `Limits.KycRequiredAboveUsd` without `Kyc.Status === \"Verified\"` →\n    `\"KYC verification required for withdrawals above {threshold} USD.\"`\n  - This UTC calendar day's spend would exceed `Limits.DailyWithdrawUsd`\n    (window resets at 00:00 UTC, not a rolling 24h window) →\n    `\"Daily withdraw limit exceeded ({spentSoFar} + {thisAmount} >\n{dailyLimit} USD).\"`\n  - This UTC calendar month's spend would exceed `Limits.MonthlyWithdrawUsd`\n    (window resets 00:00 UTC on the 1st) → `\"Monthly withdraw limit exceeded\n({spentSoFar} + {thisAmount} > {monthlyLimit} USD).\"`\n  - Any `Limits` field can be absent/null, which disables that specific\n    check for that currency. The daily/monthly counters live server-side on\n    `UserCryptoCurrencyState.Compliance` (not exposed as its own client\n    method) and reset at UTC day/month boundaries — there is no way to read\n    \"USD spent so far today\" from the client ahead of a request; read it off\n    a rejection's `error` string instead.\n- **Collective pool cap** — independent of the player's own balance, the\n  title's whole player-withdrawable pool for that (network, currency) pair\n  can be exhausted: `\"Title users-withdrawable limit reached: available\n{available} {currencyID}, requested {amount}.\"` This is a title-wide\n  economic limit, not specific to one player — if you see it, don't retry\n  immediately.\n- **Platform commission** — a platform-wide withdrawal commission percent can\n  reduce the net payout; if it would consume the entire requested amount,\n  the request is rejected outright: `\"Withdrawal amount is fully consumed by\nplatform commission.\"` Otherwise the withdrawal proceeds and\n  `NetAmountNative` reflects the amount after commission (see\n  [Gotchas](#gotchas)).\n\nNone of these are configurable or visible as a single \"can I withdraw right\nnow\" flag — the practical pattern is: build the request, call it, and render\n`error` on failure. Use `getDefinitions()`'s `AccountSafety` block and the\ncurrency's `Limits` (from `getDefinitions()`'s sibling `CryptoCurrencies` map)\nonly for soft, non-authoritative UI hints (e.g. \"KYC may be required above\n$X\").\n\n## Reading state and reacting to changes\n\n```ts\n// On-chain activity state (only present after getUserState()):\nconst bc = client.data.user.state?.Blockchain;\nbc?.LinkedWallets; // Record<networkID, LinkedWalletInfo>\nbc?.PendingWithdrawals; // PendingWithdrawalRef[] — light refs, not full tx docs\nbc?.Kyc; // UserKycState\nbc?.Stats; // BlockchainStats (deposit/withdrawal counters & volume)\n\n// Crypto balances (decimal-as-string), same cache Currency module reads:\nclient.data.user.getCryptoCurrencyAmount(\"usdt\");\n\n// Definitions (cached after getDefinitions()):\nimport type { BlockchainDefinitions } from \"@idosgames/core\";\nconst defs = client.data.config.getSection<BlockchainDefinitions>(\"Blockchain\");\n```\n\nSubscribe with `client.on(...)`; each returns an unsubscribe fn:\n\n- `blockchain:definitionsLoaded` → `BlockchainConfigResponse`\n- `blockchain:userStateLoaded` → `UserBlockchainStateResponse`\n- `blockchain:tokenDeposited` → `DepositTokenResponse`\n- `blockchain:nftDeposited` → `DepositNFTResponse`\n- `blockchain:tokenWithdrawalRequested` → `TokenWithdrawalResponse`\n- `blockchain:nftWithdrawalRequested` → `NFTWithdrawalResponse`\n- `blockchain:transactionHistoryLoaded` → `TransactionHistoryResponse`\n- `blockchain:withdrawalRetried` → `RetryWithdrawalResponse`\n- `blockchain:withdrawalConfirmed` → `ConfirmWithdrawalResponse`\n- `blockchain:donatedToDeveloper` → `DonationResponse`\n- `blockchain:donatedToUsersPool` → `DonationResponse`\n\n**Cache writes are not uniform across this module — read this carefully:**\n\n- `getUserState()` is the only call that writes `client.data.user.state.Blockchain`\n  (`LinkedWallets`, `PendingWithdrawals`, `Kyc`, `Stats`) and fires the coarse\n  `user:blockchainUpdated` (+ `user:anyUpdated`).\n- `depositToken` / `requestTokenWithdrawal` patch only the crypto **balance**\n  (`InventoryV2.CryptoCurrencies`) via a decimal delta, firing\n  `user:inventoryUpdated` (+ `user:anyUpdated`) — **not** `user:blockchainUpdated`.\n- `depositNFT` / `requestNFTWithdrawal` patch inventory (items and/or\n  currencies) via the shared `Resources` resource-operation pipeline, firing\n  `user:inventoryUpdated` (and `user:virtualCurrencyUpdated` if VC moved) —\n  again **not** `user:blockchainUpdated`.\n- `getTransactionHistory`, `retryWithdrawal`, `confirmWithdrawal`,\n  `donateToDeveloper`, `donateToUsersPool` only emit their own\n  `blockchain:*` event — they don't touch `client.data.user.state` at all.\n\nPractical consequence: after a deposit or withdrawal request, your **balance**\nis fresh in the cache, but `client.data.user.state.Blockchain.PendingWithdrawals`\nand `.Stats` are stale until you call `getUserState()` again. Re-fetch\n`getUserState()` after a withdrawal request/confirm/retry if your UI shows the\npending-withdrawals list or stats.\n\n**`StateDelta` / `Inventory` — the response already carries what changed, if\nyou want to apply it yourself instead of re-fetching.** `DepositTokenResponse`,\n`TokenWithdrawalResponse`, `NFTWithdrawalResponse`, and\n`ConfirmWithdrawalResponse` all carry an optional `StateDelta`\n(`BlockchainStateDelta`): a signed `CryptoBalances` delta per currency\n(`{ AmountDelta, FrozenDelta, UpdatedAt }` — add, don't overwrite), a\n`PendingAdded` ref (this call's newly-added pending withdrawal, if any), and\n`PendingRemovedIDs` (pending withdrawals this call confirmed or lazily\nexpired). `DepositNFTResponse` / `NFTWithdrawalResponse` similarly carry an\n`Inventory` (`InventoryDelta`) for the NFT's `UnstackableItems` instance —\nsame shape/semantics as the character-system module's `Inventory` deltas\n(`ChangedInstances` to upsert, `RemovedInstanceIDs` to drop). This mirrors the\nself-sufficient-response pattern used elsewhere in this SDK (see the\ncharacter-system skill) so a client that wants to reconcile\n`PendingWithdrawals`/balances/instances without another round trip can do so\nstraight from the mutating call's response. **Note:** `BlockchainService`\nitself does not auto-apply `StateDelta`/`Inventory` into\n`client.data.user.state.Blockchain` today — only the crypto **balance**\n(via the existing `AmountNative`-based patch) and item `Resources` are\napplied automatically. If you need `PendingWithdrawals` reconciled without a\nfull `getUserState()` refetch, read `result.data.StateDelta` yourself. Both\nare `null`/absent on an idempotent replay (nothing new to apply).\n\n```ts\nconst off = client.on(\"blockchain:tokenWithdrawalRequested\", (r) => {\n  console.log(`Withdrawal ${r.TitleTransactionID} expires at ${r.ExpiresAt}`);\n});\n// later: off();\n```\n\n## Recipes\n\n### Load config + state on a wallet/blockchain screen\n\n```ts\nawait client.blockchain.getDefinitions();\nawait client.blockchain.getUserState();\n\nconst defs = client.data.config.getSection<BlockchainDefinitions>(\"Blockchain\");\nconst bc = client.data.user.state?.Blockchain;\n\nfor (const [networkID, net] of Object.entries(defs?.Networks ?? {})) {\n  if (!net.DepositsEnabled && !net.WithdrawalsEnabled) continue;\n  // render a network card; net.NftCollections binds contracts to item catalogs\n}\nbc?.Kyc?.Status; // gate withdrawal UI on KYC if the title requires it\n```\n\n### Deposit a token (player already sent it on-chain)\n\n```ts\nconst res = await client.blockchain.depositToken(\"polygon\", \"0xabc123...\");\nif (!res.ok) return showError(res.error); // e.g. \"Transaction not found on chain.\",\n// \"Not enough confirmations (required 12). Try again in a few minutes.\",\n// \"Transaction hash already used.\"\n\nres.data.CurrencyID; // e.g. \"usdt\"\nres.data.AmountNative; // decimal string credited\n// Balance is already updated in the cache:\nclient.data.user.getCryptoCurrencyAmount(res.data.CurrencyID!);\n```\n\n### Full withdrawal lifecycle: request -> submit on-chain -> confirm, with a retry-after-failure path\n\n```ts\n// 1. Request the withdrawal — debits in-game immediately, returns a signature payload.\nconst req = await client.blockchain.requestTokenWithdrawal(\n  \"usdt\",\n  \"polygon\",\n  \"0xPlayerWallet...\",\n  \"25.00\",\n);\nif (!req.ok) return showError(req.error); // e.g. \"Not enough balance: have 10 usdt, need 25.00.\",\n// \"KYC verification required for withdrawals above 1000 USD.\",\n// \"Title users-withdrawable limit reached: available 5 usdt, requested 25.00.\"\n// — see \"Withdrawal gates\" above for the full list.\n\nconst { TitleTransactionID, EvmSignature, ExpiresAt } = req.data;\n// Balance is already debited (gross amount) in the cache.\n\n// 2. Hand EvmSignature (or SolanaSignature on a Solana network) to the\n//    player's wallet SDK to submit the on-chain transaction yourself —\n//    this SDK does not sign/broadcast. That step can fail (rejected in\n//    wallet, gas issue).\n\n// 2a. If on-chain submission failed WHILE the transaction is still Pending\n//     (before ExpiresAt), retry — this re-issues a fresh signature WITHOUT\n//     debiting again:\nconst retry = await client.blockchain.retryWithdrawal(TitleTransactionID!);\nif (!retry.ok) return showError(retry.error); // e.g. \"Transaction is not in Pending state (current: Abandoned).\"\nconst freshSignature = retry.data.EvmSignature ?? retry.data.SolanaSignature;\n// Submit freshSignature on-chain instead, then continue to step 3.\n//\n// IMPORTANT: retryWithdrawal only works while the transaction is Pending. If\n// ExpiresAt already passed, the backend has lazily moved it to Abandoned and\n// retryWithdrawal will reject it — there is no \"re-request\" for an Abandoned\n// withdrawal (the asset was already debited and is not refunded). The only\n// way to still complete it is confirmWithdrawal with a hash, if the player\n// actually managed to submit the original signature before it was swept —\n// see the Gotchas section.\n\n// 3. Once the wallet actually broadcasts the transaction, tell the backend\n//    the resulting on-chain hash so it can verify and close out the withdrawal:\nconst confirm = await client.blockchain.confirmWithdrawal(\n  TitleTransactionID!,\n  \"0xOnChainTxHash...\",\n);\nif (!confirm.ok) return showError(confirm.error);\nconfirm.data.Status; // e.g. \"Completed\" once the chain confirms it\n\n// 4. Refresh state — request/retry/confirm don't touch Blockchain cache themselves.\nawait client.blockchain.getUserState();\nclient.data.user.state?.Blockchain?.PendingWithdrawals; // should no longer list it once Completed\n```\n\n### KYC-gated withdrawal\n\nThe client never decides whether KYC is required — the backend compares the\nwithdrawal's USD-equivalent against the currency's configured threshold at\nrequest time. Use `Kyc.Status` only to pre-empt an obvious rejection in the\nUI; still branch on the real error:\n\n```ts\nawait client.blockchain.getUserState();\nconst kyc = client.data.user.state?.Blockchain?.Kyc;\n\nif (kyc?.Status !== \"Verified\") {\n  // Optional UX nicety: warn before the call for large amounts. This SDK has\n  // no startKyc/submitKyc method — verification happens through whatever KYC\n  // provider integration the title uses outside this SDK; Kyc here only\n  // reflects the result.\n}\n\nconst req = await client.blockchain.requestTokenWithdrawal(\n  \"usdt\",\n  \"polygon\",\n  \"0xPlayerWallet...\",\n  \"5000.00\",\n);\nif (!req.ok) {\n  if (req.error.startsWith(\"KYC verification required\")) {\n    // Route the player to the title's KYC verification flow.\n  }\n  return showError(req.error);\n}\n```\n\n### Deposit / withdraw an NFT\n\n```ts\n// Deposit: player already transferred the NFT to the vault address on-chain.\nconst dep = await client.blockchain.depositNFT(\"ethereum\", \"0xNftDepositTx...\");\nif (!dep.ok) return showError(dep.error);\ndep.data.ItemID; // the in-game item granted\ndep.data.Resources; // already applied to inventory in the cache\n\n// Withdraw: consumes the in-game item, returns a signature to submit on-chain.\nconst wd = await client.blockchain.requestNFTWithdrawal(\n  \"sword-of-embers-inst-1\", // ItemID (per NFTWithdrawalResponse/BlockchainRequest shape)\n  \"ethereum\",\n  \"0xPlayerWallet...\",\n  \"1\",\n);\nif (!wd.ok) return showError(wd.error);\nwd.data.TitleTransactionID; // use with retryWithdrawal / confirmWithdrawal exactly as tokens above\n\n// ERC-721 unique NFT: pass the specific instance to tokenize. level/itemInstanceID\n// are the trailing optional args — see the Methods table above.\nconst wd721 = await client.blockchain.requestNFTWithdrawal(\n  \"sword-of-embers\",\n  \"ethereum\",\n  \"0xPlayerWallet...\",\n  \"1\",\n  undefined, // category\n  1, // level\n  \"sword-of-embers-inst-1\", // ItemInstanceID — required for ERC-721 bindings\n);\n```\n\n### Edge case: not logged in / missing args\n\n```ts\nconst res = await client.blockchain.depositToken(\"\", \"0xabc\");\n// res.ok === false, res.reason === \"client\" — \"NetworkID is required.\" — no network call.\n\nconst res2 = await client.blockchain.getUserState();\n// If called before auth.loginWithDeviceID() (or any auth.* login):\n// res2.ok === false, res2.reason === \"unauthorized\"\n```\n\n### Donate crypto (no personal credit)\n\n```ts\nconst res = await client.blockchain.donateToDeveloper(\n  \"polygon\",\n  \"0xdonateTx...\",\n);\nif (!res.ok) return showError(res.error);\nres.data.Target; // \"Developer\" — confirms which pool bucket it landed in\n\n// donateToUsersPool is identical in shape, credits the users' pool bucket instead:\nawait client.blockchain.donateToUsersPool(\"polygon\", \"0xdonateTx2...\");\n```\n\n## Gotchas\n\n- **Withdrawal request debits immediately; the on-chain leg is separate and\n  can fail.** `requestTokenWithdrawal`/`requestNFTWithdrawal` already took the\n  asset from the player before any on-chain transaction exists. If the\n  player's wallet fails to submit (rejected, gas issue) **while the\n  transaction is still `Pending`**, don't ask them to request again — that\n  would debit twice. Use `retryWithdrawal` with the same\n  `TitleTransactionID` to get a fresh signature without a new charge. This\n  only works before `ExpiresAt` — see the next two points for what happens\n  after.\n- **`retryWithdrawal` vs `confirmWithdrawal` are opposite ends of the same\n  flow.** Retry re-issues the _signed payload_ before submission (nothing has\n  reached the chain yet); confirm reports the _resulting tx hash_ after\n  submission (the chain now has it). Calling confirm with a hash from a\n  transaction that never actually landed on-chain will simply fail\n  server-side verification — don't fabricate a hash to \"force\" completion.\n- **`ExpiresAt` is real, expiry does not refund the player, and — contrary to\n  what the name suggests — an expired withdrawal is NOT retryable.** A\n  withdrawal signature is time-boxed (`TokenWithdrawalResponse.ExpiresAt` /\n  `NFTWithdrawalResponse.ExpiresAt`, driven by\n  `BlockchainAccountSafetyPolicy.PendingWithdrawalTtlHours`). Once it passes\n  without a submission, the backend lazily transitions the transaction to\n  **`Abandoned`** (not `Expired` — that enum value exists but this backend\n  path never assigns it) and drops it off `PendingWithdrawals` — but the\n  already-debited asset is **not** credited back; this is intentional, not a\n  bug. Critically, `retryWithdrawal` requires the transaction to still be\n  `Pending` — calling it on an `Abandoned` one fails with `\"Transaction is\nnot in Pending state (current: Abandoned).\"` There is no \"re-request\"\n  operation for an abandoned withdrawal.\n- **A withdrawal can still be confirmed after it's `Abandoned`.** If the\n  player submits late — after `ExpiresAt` passed and the backend already\n  swept it to `Abandoned` — `confirmWithdrawal` still accepts it as long as\n  the on-chain transaction verifies (the signature itself doesn't expire\n  on-chain, only the title's own bookkeeping window does). Don't treat an\n  `Abandoned` transaction as unrecoverable if the player insists they\n  submitted it; calling `confirmWithdrawal` with the resulting hash is still\n  the right move, and is in fact the _only_ way to close out an\n  already-expired-but-actually-submitted withdrawal.\n- **`retryWithdrawal` only works on a `Pending` transaction the caller owns.**\n  It fails with `\"Transaction not found.\"` for an unknown or someone else's\n  `TitleTransactionID`, `\"Transaction is not in Pending state (current:\n{status}).\"` if it already completed/failed/was abandoned, or\n  `\"Signature data not found for this transaction.\"` if there's nothing to\n  reissue. A banned account additionally gets `\"Account is banned. Contact\nsupport.\"` on retry (deposits stay allowed for banned accounts; retrying a\n  withdrawal does not).\n- **Gross vs. net amounts on token withdrawals.** `AmountNative` is what was\n  debited from the player (gross); `NetAmountNative` is what actually gets\n  paid out on-chain after a platform commission percentage **and** an\n  optional on-chain burn are deducted (`NetAmountNative = AmountNative −\ncommission − BurnAmountNative`). Show the player the net figure they'll\n  receive, not the gross debit, to avoid support tickets about a \"missing\"\n  amount. NFT withdrawals have no such split — there's no `NetAmountNative`\n  on `NFTWithdrawalResponse`.\n- **Burn on withdrawal (EVM-only).** `TokenWithdrawalResponse.BurnAmountNative`\n  is the amount burned on-chain (sent to the DEAD address) for this\n  withdrawal, driven by the currency's `WithdrawalBurnPercent` (see the\n  currency-system skill) — `0` if burn is disabled for that currency or the\n  network is Solana. The raw-units counterpart, `WithdrawalSignatureResponse.\nBurnAmount`, is bound into the signed hash and must be passed to the\n  contract call verbatim, same as `Amount`/`Nonce` — `@idosgames/wallet`'s\n  `submitEvmTokenWithdrawal` does this for you; a client calling\n  `withdrawERC20` directly must include it too, or the signature check fails.\n- **`client.data.user.state.Blockchain` goes stale after deposits/withdrawal\n  requests.** Only `getUserState()` refreshes `LinkedWallets`,\n  `PendingWithdrawals`, `Kyc`, and `Stats`. A deposit/withdrawal call updates\n  your _balance_/_inventory_ cache correctly, but if your UI also shows the\n  pending-withdrawals list or lifetime stats, re-call `getUserState()`\n  afterward (see the withdrawal recipe above).\n- **Deposits are reporting, not sending.** `depositToken`/`depositNFT` don't\n  move any asset on-chain — they tell the backend \"verify this transaction\n  hash and credit me.\" The actual on-chain transfer to the platform's pool/\n  vault address must already have happened via a wallet SDK before you call\n  these.\n- **This SDK never signs or broadcasts.** `EvmSignature`/`SolanaSignature`\n  payloads are inputs to a wallet SDK/contract call that happens outside\n  `@idosgames/core`. Don't look for a \"submit on-chain\" method here — there\n  isn't one; `confirmWithdrawal` only reports the result afterward. The\n  `@idosgames/wallet` companion package is that outside layer — it submits the\n  signature on-chain and calls `confirmWithdrawal` for you.\n- **Donations never touch personal balances.** `donateToDeveloper` /\n  `donateToUsersPool` intentionally don't credit the player anything and\n  don't touch `client.data.user.state` — they only emit their own\n  `blockchain:donated*` event for a confirmation toast/receipt.\n- **Render from the cache, handle the error from the result.** The happy\n  path updates the relevant cache slice + emits an event; the failure path\n  gives you `reason` + `error`. Use `reason` to decide behavior (retry on\n  `\"connection\"`, re-auth on `\"unauthorized\"`, toast the `error` on\n  `\"server\"`).\n\n## Full reference\n\n[references/data-model.md](references/data-model.md) — every config and\nstate field: network definitions, NFT collection bindings, account-safety\npolicy, KYC state, transaction documents, the withdrawal-gate limits, and the\nEVM/Solana withdrawal signature payload shapes. Read it when building network\npickers, a transaction-history table, or KYC/limit-aware withdrawal UI. For\nthe shared `ResourceConsume`/`ResourceGrant`/`ResourceOperation`\ncost-and-reward shapes riding along on `depositNFT`/`requestNFTWithdrawal`,\nand for the full `CryptoCurrencyDefinition` shape (`Limits`, `Networks[].\nMinWithdraw`, `Permissions`) that the withdrawal gates enforce,\nsee the currency-system skill.\n",
+  "content": "---\nname: blockchain-system\ndescription: >-\n  Bridge in-game assets on-chain in a game on the iDosGames TypeScript SDK\n  (@idosgames/core) via client.blockchain (BlockchainService): load blockchain\n  network/config definitions, load the player's on-chain state (linked\n  wallets, pending withdrawals, KYC, stats), deposit a token or NFT from a\n  wallet into the game, request a token or NFT withdrawal out to a wallet,\n  read on-chain transaction history, retry a still-pending withdrawal's\n  signature, confirm a withdrawal's on-chain tx hash, and donate crypto to\n  the developer or a users' pool. Use this whenever the user is working in\n  the iDosGames TS SDK or its game templates (board-game, idle-rpg) and wants crypto wallets, NFT\n  deposits/withdrawals, token bridging, on-chain asset transfers, KYC status,\n  or otherwise touches client.blockchain, BlockchainService,\n  BlockchainDefinitions, UserBlockchainState, DepositTokenResponse,\n  TokenWithdrawalResponse, or NFTWithdrawalResponse — even if they don't name\n  the module explicitly.\n---\n\n# Blockchain system (iDosGames TS SDK)\n\nThe Blockchain module bridges in-game assets to and from real wallets on\nsupported chains (EVM and Solana networks). A player can deposit a token or\nNFT they already sent on-chain (crediting their in-game balance/inventory),\nor request a withdrawal that pays an in-game token/NFT out to their wallet\n(debiting their in-game balance/inventory and producing a signature the\nplayer submits on-chain themselves). Everything is **server-authoritative**:\nthe client reports/requests, the backend validates the transaction against\nthe chain, applies rules (network enabled, KYC, account-safety policy), and\nthe SDK mirrors the confirmed result into a local cache your UI reads. You\nnever credit/debit balances yourself.\n\nThis skill is for **using** the production `BlockchainService`, not for\nporting or extending it, and not for signing/broadcasting transactions\nyourself — this SDK reports deposits and requests withdrawals; actually\nsending the on-chain transaction (the deposit transfer, or broadcasting a\nwithdrawal signature) happens with a wallet SDK outside this client.\n\n> **The on-chain half is the `@idosgames/wallet` companion package.** It\n> connects browser & mobile wallets (EVM via wagmi/viem/WalletConnect, Solana\n> via wallet-adapter) and runs the exact RewardPool contract calls, threading\n> them through this service's request → submit → confirm / approve → deposit →\n> report lifecycle. If the user wants to actually connect a wallet and move\n> tokens/NFTs (not just call `client.blockchain.*`), reach for that package —\n> see its README. Everything below documents the server-authoritative\n> `client.blockchain` surface that `@idosgames/wallet` builds on. The wallet\n> package's EVM surface covers both NFT standards: `submitEvmNftWithdrawal` /\n> `depositNftEvm` (+ `erc1155Abi`) for ERC-1155 collections, and\n> `submitEvmNftWithdrawal721` / `depositNftEvm721` (+ `erc721Abi`) for\n> ERC-721 unique-item collections (4-arg `safeTransferFrom`, no `id`/`amount`\n> — the token is always qty 1). `submitEvmTokenWithdrawal`'s `withdrawERC20`\n> call now also threads `sig.BurnAmount` through (see\n> [Burn on withdrawal](#gotchas) below) — the ABI/contract call order changed,\n> so an app pinned to an older `@idosgames/wallet` build will revert on-chain\n> against an updated RewardPool contract.\n\n> **Never import `@idosgames/wallet/react` (or `/react/solana`) from a file\n> that loads on startup.** Those subpaths pull in Reown AppKit, and AppKit is\n> deliberately _not_ a dependency of a generated project — the live preview\n> resolves every declared dependency up front and times out on AppKit's tree.\n> A static import therefore blanks the preview before any game code runs\n> (`Could not find dependency: '@reown/appkit-adapter-wagmi'`), while the real\n> build stays green — that mismatch is the signature of this mistake.\n> Two rules keep both working:\n>\n> - **Sign-in button:** import `LazyWalletLogin` / `LazySolanaWalletLogin` from\n>   `@idosgames/wallet/react/lazy` (that entry has no AppKit in its graph; it\n>   also re-exports the chains as plain objects — never import chains from\n>   `wagmi/chains` or `viem/chains`, that barrel breaks the preview too).\n> - **In-game deposit/withdraw panel:** import `LazyWalletPanel` from\n>   `@idosgames/wallet/react/lazy` and pass it the authenticated `client` (a\n>   prop, like the login button — never a module context). Same lazy contract:\n>   AppKit stays out of the startup graph. Don't hand-roll your own\n>   `await import(\"./PanelImpl\")` wrapper — `LazyWalletPanel` is that wrapper.\n>   Because the wallet config is memoised per WalletConnect project id, the\n>   panel reuses the wallet the player connected at sign-in: same store, so it\n>   opens already-connected, no second tap and no second modal. This is exactly\n>   how the board-game and idle-rpg modules wire their `WalletPanel.tsx`.\n\n> **The game cannot reach the wallet while it is embedded in an idosgames.com iframe** (owner's\n> decision, 2026-09-17 — deposit/withdraw goes through the buttons in the site's own wallet card).\n> You don't need to special-case this: `LazyWalletPanel` renders nothing there, and\n> `LazyWalletLogin` / `LazySolanaWalletLogin` stay a working \"Sign in with wallet\" button — inside\n> the frame the SITE's connected wallet signs the engine's login message for the game\n> (`loginWithWalletViaPlatform` from `@idosgames/wallet`, used by the buttons automatically). Never\n> show a \"use idosgames.com\" notice inside the game. Every flow function that talks to the wallet\n> directly (`depositTokenEvm`, `withdrawTokenEvm`, `loginWithWalletEvm`, their Solana equivalents,\n> `payWithWalletEvm`) refuses with `WALLET_USE_SITE_PANEL` inside a frame. A game opened by its own\n> direct link (not embedded) is unaffected — every one of these works exactly as before there.\n\n### Login mode and play access by token balance (`cfg.Blockchain.PlayAccess`)\n\nA title can require players to HOLD tokens to play. The publisher picks one of three login modes:\n\n| `Mode`                | Who can sign in               | Balance check                                |\n| --------------------- | ----------------------------- | -------------------------------------------- |\n| `Open` (default)      | every method, guests included | none                                         |\n| `AnyWithLinkedWallet` | every method except guest     | the wallet the player linked by signature    |\n| `WalletOnly`          | wallet login only             | the wallet they signed in with — and only it |\n\nIn `WalletOnly` the account must BE the wallet's account: an account created another way before the\nmode was switched on gets `PLAY_ACCESS_WALLET_LOGIN_ONLY` on every check, and `linkWallet` refuses\nany wallet but the account's own with the same code — don't offer \"link wallet\" there, offer\n\"log out and sign in with your wallet\".\n\nRequirements are `TokenGates` (`CurrencyID`, `MinBalance`, `BalanceSource`: `OnChain` wallet /\n`InGame` game balance — no wallet needed / `Combined`; `NetworkID` for wallet ones). The SERVER\nchecks the balance on every login and session refresh — silently, no signature — and on\n`client.blockchain.confirmPlayAccess()`. Gameplay calls without a valid pass fail with HTTP 403\n`PLAY_ACCESS_REQUIRED`; `Blockchain` itself, account linking and the login-time `User` reads stay open.\n\n**The host template already handles all of it — don't rebuild it.** `mountHost` shows the\nplay-access screen (`renderPlayAccess`, the template's `src/PlayAccessScreen.tsx` over\n`DefaultPlayAccessScreen`) instead of the game whenever `client.auth.playAccess?.Granted === false`\nor `playAccess:required` fires, and the template's login screen hides the methods the mode refuses\n(`client.auth.getAuthOptions()` → `PlayAccessMode`). \"Link wallet\" on that screen is\n`LazyWalletLogin mode=\"link\"` (`renderWalletLink` in `src/walletLogin.tsx`); inside the\nidosgames.com frame the site's wallet signs the link (`linkWalletViaPlatform`).\n\nClient surface, if you roll your own screen: `client.auth.playAccess` (+ `playAccess:changed`),\n`client.blockchain.getPlayAccess()` (mode, requirements, the player's signature-linked wallets, last\ncheck), `client.blockchain.confirmPlayAccess(networkID?)` (choose a linked wallet and check now),\n`client.auth.linkWallet(address, networkID, signature?)` (two steps; the second returns the pass\nchecked against that wallet), `linkWalletEvm` / `linkWalletSolana` / `linkWalletViaPlatform` in\n`@idosgames/wallet`. Refusal codes: `PLAY_ACCESS_WALLET_REQUIRED`,\n`PLAY_ACCESS_WALLET_NETWORK_NOT_GATED`, `PLAY_ACCESS_GUEST_DISABLED`, `PLAY_ACCESS_WALLET_LOGIN_ONLY`,\n`PLAY_ACCESS_CHECK_FAILED` (the RPC could not be read — NOT an empty wallet; check again), or the\nrequirement's own `DenyMessage`. A login or refresh never fails for lack of balance — in every mode\nthe session is issued and the game stays closed until the pass is granted.\n\n### Operation category (`game_topup` by default)\n\nThe updated RewardPool contract tags every deposit/withdrawal with a string\n**category** (default `\"game_topup\"`; `\"community_reward\"` is the other known\nvalue, and arbitrary strings are allowed). On a **withdrawal** the server signs\nthe category into the on-chain hash and returns it on the signature payload\n(`EvmSignature.Category` / `.TitleID`); whoever submits the transaction **must\npass the same value on-chain verbatim** or the contract rejects the signature —\n`@idosgames/wallet` does this for you. Pass it as the optional last arg to\n`requestTokenWithdrawal`/`requestNFTWithdrawal` (omit → `\"game_topup\"`). On a\n**deposit** the category is read back from the on-chain transaction, so you\ndon't pass it to `depositToken`/`depositNFT`. It also appears on transaction\ndocuments as `Category`. Import the constants from `@idosgames/core`:\n`BlockchainOperationCategory.GameTopUp` / `.CommunityReward`.\n\n## Mental model: deposits vs. withdrawals\n\n- **Deposit** = the player already sent tokens/an NFT to the platform's pool\n  or vault address on-chain. The client then calls `depositToken`/`depositNFT`\n  with that transaction's hash so the backend can verify it and credit the\n  player in-game. One-shot: the credit happens directly on a successful call.\n- **Withdrawal** = the player wants an in-game token/NFT sent out to their\n  wallet. The client calls `requestTokenWithdrawal`/`requestNFTWithdrawal`,\n  which **debits in-game immediately** and returns a signed payload\n  (`EvmSignature` or `SolanaSignature`) the player's wallet must submit\n  on-chain to actually receive the asset. This is a **multi-step, async\n  flow** — see [Recipes](#recipes) for the full lifecycle, including what to\n  do when the on-chain submission fails.\n\nBoth flows are per-network: every call takes a `networkID` that must match one\nof the title's configured `Networks` (EVM or Solana), each with its own\ndeposit/withdrawal enable flags, contract/vault addresses, and (for NFTs) a\ncollection binding to an item catalog. Withdrawals additionally run through a\nlong chain of server-side gates (balances, per-network minimums, account\nsafety, KYC, daily/monthly compliance limits, a collective title-wide pool\ncap, and platform commission) — see\n[Withdrawal gates](#withdrawal-gates-what-can-reject-a-request) for the full\nlist with verbatim error strings.\n\nFor the full config/state field shapes (network definitions, NFT collection\nbindings, KYC tiers, transaction documents, signature payloads), read\n[references/data-model.md](references/data-model.md). You do **not** need it\nto call the methods — only to drive richer UI (network pickers, KYC gates,\ntransaction history tables).\n\n## Setup\n\n```ts\nimport { createIDosGamesClient } from \"@idosgames/core\";\n\nconst client = createIDosGamesClient({ titleID: \"your-title-id\" });\nawait client.auth.loginWithDeviceID(); // or any auth.* method\n\nconst blockchain = client.blockchain; // the BlockchainService\n```\n\nEvery blockchain method requires an authenticated session. Without one they\nreturn `{ ok: false, reason: \"unauthorized\" }` — they do not throw.\n\n## Methods\n\nAll methods return `Promise<OperationResult<T>>`: a discriminated union that\nis either `{ ok: true, data }` or `{ ok: false, reason, error }`. Always\nbranch on `result.ok` before touching `result.data`. `reason` is one of\n`\"client\"` (missing/empty required arg — rejected before any network call),\n`\"unauthorized\"`, `\"throttled\"` (fired the same endpoint again inside the\n600ms client-side throttle window), `\"connection\"` (transient, offer Retry),\n`\"validation\"` (response/schema drift), or `\"server\"` (backend rejected it —\n`error` carries the exact backend message). Withdrawals in particular can be\nrejected by a long chain of server-side gates — see\n[Withdrawal gates](#withdrawal-gates-what-can-reject-a-request) below for the\nfull list with verbatim error strings.\n\n| Method                                                                                               | Purpose                                                                                              | `data` on success             |\n| ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------- |\n| `getDefinitions()`                                                                                   | Load the title's blockchain config: networks, NFT bindings, crypto currencies.                       | `BlockchainConfigResponse`    |\n| `getUserState()`                                                                                     | Load this player's on-chain state: linked wallets, pending withdrawals, KYC, stats, crypto balances. | `UserBlockchainStateResponse` |\n| `depositToken(networkID, transactionHash)`                                                           | Report an on-chain token transfer; credits the matching crypto balance.                              | `DepositTokenResponse`        |\n| `depositNFT(networkID, transactionHash)`                                                             | Report an on-chain NFT transfer; grants the matching in-game item.                                   | `DepositNFTResponse`          |\n| `requestTokenWithdrawal(currencyID, networkID, walletAddress, amount, category?)`                    | Debit a crypto balance and get a signed payload to withdraw on-chain.                                | `TokenWithdrawalResponse`     |\n| `requestNFTWithdrawal(itemID, networkID, walletAddress, amount, category?, level?, itemInstanceID?)` | Consume an in-game item and get a signed payload to withdraw the NFT on-chain.                       | `NFTWithdrawalResponse`       |\n| `getTransactionHistory(limit?)`                                                                      | Load recent token + NFT transaction documents (default limit 50).                                    | `TransactionHistoryResponse`  |\n| `retryWithdrawal(titleTransactionID)`                                                                | Re-issue a fresh signature for a still-`Pending` withdrawal without re-debiting.                     | `RetryWithdrawalResponse`     |\n| `confirmWithdrawal(titleTransactionID, onChainTransactionHash)`                                      | Tell the backend the signed withdrawal was submitted on-chain, with its tx hash.                     | `ConfirmWithdrawalResponse`   |\n| `donateToDeveloper(networkID, transactionHash)`                                                      | Report an on-chain transfer as a donation to the developer pool (no personal credit).                | `DonationResponse`            |\n| `donateToUsersPool(networkID, transactionHash)`                                                      | Report an on-chain transfer as a donation to the users' pool (no personal credit).                   | `DonationResponse`            |\n\nAll string args (`networkID`, `transactionHash`, `currencyID`,\n`walletAddress`, `amount`, `itemID`, `titleTransactionID`,\n`onChainTransactionHash`) are required and checked client-side before any\nnetwork call — an empty one short-circuits with `reason: \"client\"`. `amount`\nis a decimal string for token withdrawals and an integer-as-string for NFT\nwithdrawals / not used for deposits (deposit amounts come from the verified\non-chain transaction, not from the client). `getTransactionHistory(limit)`\ndefaults to `50`, is capped at **200** server-side (values above are silently\nclamped, values `<= 0` fall back to 50), and is sent as `Amount` on the wire\n(reused request field, not an actual currency amount).\n\n`requestNFTWithdrawal`'s trailing `level`/`itemInstanceID` are both optional\nand only matter for NFT catalogs with leveled or unique (ERC-721) bindings:\n`level` selects which leveled instance/tokenId to withdraw (omit or `1` →\nbase level, prior behavior); `itemInstanceID` is **required** when the\nitem's NFT binding is ERC-721 — it tells the server exactly which\nunstackable instance to debit and tokenize (preserving its Level/RemainingUses/\nCustomData in the on-chain registry via a separate ItemBridge contract).\nBoth are ignored for stackable/ERC-1155 items.\n\nOn success, most methods **mirror the confirmed change into the cache and\nemit an event** — see the next section for exactly which cache each method\ntouches, since it's not uniform across this module.\n\n## Withdrawal gates (what can reject a request)\n\n`requestTokenWithdrawal` / `requestNFTWithdrawal` run through a long chain of\nserver-side checks, each a `reason: \"server\"` failure with a specific `error`\nstring. Surface the string; don't try to pre-validate all of these\nclient-side — the gate list can change without a client update:\n\n- **Global kill switch** — withdrawals can be turned off platform-wide\n  independently of any per-network/per-currency flag: `\"Withdrawals are\ncurrently disabled.\"`\n- **Network / currency / binding disabled** — `\"Withdrawals disabled for this\nnetwork.\"`, `\"Withdrawals are disabled for currency '{id}'.\"`, `\"This\ncurrency cannot be withdrawn in this network.\"`, or (currency under\n  maintenance) `\"Currency '{id}' is under maintenance. Try again later.\"`\n- **Per-network minimum** — every currency has a `MinWithdraw` for each\n  network it's bound to (`CryptoNetworkBinding.MinWithdraw`, see the\n  currency-system skill's data-model for the full shape): `\"Minimum withdraw\nis {MinWithdraw} {currencyID}.\"`\n- **Insufficient balance** — `\"Not enough balance: have {available}\n{currencyID}, need {amount}.\"` (tokens) or `\"Not enough items: have {owned},\nneed {amount}.\"` (NFTs).\n- **Account safety** (`BlockchainAccountSafetyPolicy`, read-only in\n  `getDefinitions()`'s `AccountSafety` block) — applies to withdrawals only,\n  never deposits: account younger than `MinAccountAgeDays` →\n  `\"Account is too fresh. Try again later.\"`; banned account → `\"Account is\nbanned. Contact support.\"`; withdrawing to a wallet address another account\n  already used, when `MultiAccountCheckEnabled` +\n  `BanOnSharedWithdrawalAddress` are both on, **bans the account on the\n  spot** and returns `\"Account banned. Contact support.\"`\n- **Compliance / KYC** (`CryptoCurrencyDefinition.Limits`, per currency) —\n  checked in USD-equivalent of the requested amount:\n  - Above `Limits.KycRequiredAboveUsd` without `Kyc.Status === \"Verified\"` →\n    `\"KYC verification required for withdrawals above {threshold} USD.\"`\n  - This UTC calendar day's spend would exceed `Limits.DailyWithdrawUsd`\n    (window resets at 00:00 UTC, not a rolling 24h window) →\n    `\"Daily withdraw limit exceeded ({spentSoFar} + {thisAmount} >\n{dailyLimit} USD).\"`\n  - This UTC calendar month's spend would exceed `Limits.MonthlyWithdrawUsd`\n    (window resets 00:00 UTC on the 1st) → `\"Monthly withdraw limit exceeded\n({spentSoFar} + {thisAmount} > {monthlyLimit} USD).\"`\n  - Any `Limits` field can be absent/null, which disables that specific\n    check for that currency. The daily/monthly counters live server-side on\n    `UserCryptoCurrencyState.Compliance` (not exposed as its own client\n    method) and reset at UTC day/month boundaries — there is no way to read\n    \"USD spent so far today\" from the client ahead of a request; read it off\n    a rejection's `error` string instead.\n- **Collective pool cap** — independent of the player's own balance, the\n  title's whole player-withdrawable pool for that (network, currency) pair\n  can be exhausted: `\"Title users-withdrawable limit reached: available\n{available} {currencyID}, requested {amount}.\"` This is a title-wide\n  economic limit, not specific to one player — if you see it, don't retry\n  immediately.\n- **Platform commission** — a platform-wide withdrawal commission percent can\n  reduce the net payout; if it would consume the entire requested amount,\n  the request is rejected outright: `\"Withdrawal amount is fully consumed by\nplatform commission.\"` Otherwise the withdrawal proceeds and\n  `NetAmountNative` reflects the amount after commission (see\n  [Gotchas](#gotchas)).\n\nNone of these are configurable or visible as a single \"can I withdraw right\nnow\" flag — the practical pattern is: build the request, call it, and render\n`error` on failure. Use `getDefinitions()`'s `AccountSafety` block and the\ncurrency's `Limits` (from `getDefinitions()`'s sibling `CryptoCurrencies` map)\nonly for soft, non-authoritative UI hints (e.g. \"KYC may be required above\n$X\").\n\n## Reading state and reacting to changes\n\n```ts\n// On-chain activity state (only present after getUserState()):\nconst bc = client.data.user.state?.Blockchain;\nbc?.LinkedWallets; // Record<networkID, LinkedWalletInfo>\nbc?.PendingWithdrawals; // PendingWithdrawalRef[] — light refs, not full tx docs\nbc?.Kyc; // UserKycState\nbc?.Stats; // BlockchainStats (deposit/withdrawal counters & volume)\n\n// Crypto balances (decimal-as-string), same cache Currency module reads:\nclient.data.user.getCryptoCurrencyAmount(\"usdt\");\n\n// Definitions (cached after getDefinitions()):\nimport type { BlockchainDefinitions } from \"@idosgames/core\";\nconst defs = client.data.config.getSection<BlockchainDefinitions>(\"Blockchain\");\n```\n\nSubscribe with `client.on(...)`; each returns an unsubscribe fn:\n\n- `blockchain:definitionsLoaded` → `BlockchainConfigResponse`\n- `blockchain:userStateLoaded` → `UserBlockchainStateResponse`\n- `blockchain:tokenDeposited` → `DepositTokenResponse`\n- `blockchain:nftDeposited` → `DepositNFTResponse`\n- `blockchain:tokenWithdrawalRequested` → `TokenWithdrawalResponse`\n- `blockchain:nftWithdrawalRequested` → `NFTWithdrawalResponse`\n- `blockchain:transactionHistoryLoaded` → `TransactionHistoryResponse`\n- `blockchain:withdrawalRetried` → `RetryWithdrawalResponse`\n- `blockchain:withdrawalConfirmed` → `ConfirmWithdrawalResponse`\n- `blockchain:donatedToDeveloper` → `DonationResponse`\n- `blockchain:donatedToUsersPool` → `DonationResponse`\n\n**Cache writes are not uniform across this module — read this carefully:**\n\n- `getUserState()` is the only call that writes `client.data.user.state.Blockchain`\n  (`LinkedWallets`, `PendingWithdrawals`, `Kyc`, `Stats`) and fires the coarse\n  `user:blockchainUpdated` (+ `user:anyUpdated`).\n- `depositToken` / `requestTokenWithdrawal` patch only the crypto **balance**\n  (`InventoryV2.CryptoCurrencies`) via a decimal delta, firing\n  `user:inventoryUpdated` (+ `user:anyUpdated`) — **not** `user:blockchainUpdated`.\n- `depositNFT` / `requestNFTWithdrawal` patch inventory (items and/or\n  currencies) via the shared `Resources` resource-operation pipeline, firing\n  `user:inventoryUpdated` (and `user:virtualCurrencyUpdated` if VC moved) —\n  again **not** `user:blockchainUpdated`.\n- `getTransactionHistory`, `retryWithdrawal`, `confirmWithdrawal`,\n  `donateToDeveloper`, `donateToUsersPool` only emit their own\n  `blockchain:*` event — they don't touch `client.data.user.state` at all.\n\nPractical consequence: after a deposit or withdrawal request, your **balance**\nis fresh in the cache, but `client.data.user.state.Blockchain.PendingWithdrawals`\nand `.Stats` are stale until you call `getUserState()` again. Re-fetch\n`getUserState()` after a withdrawal request/confirm/retry if your UI shows the\npending-withdrawals list or stats.\n\n**`StateDelta` / `Inventory` — the response already carries what changed, if\nyou want to apply it yourself instead of re-fetching.** `DepositTokenResponse`,\n`TokenWithdrawalResponse`, `NFTWithdrawalResponse`, and\n`ConfirmWithdrawalResponse` all carry an optional `StateDelta`\n(`BlockchainStateDelta`): a signed `CryptoBalances` delta per currency\n(`{ AmountDelta, FrozenDelta, UpdatedAt }` — add, don't overwrite), a\n`PendingAdded` ref (this call's newly-added pending withdrawal, if any), and\n`PendingRemovedIDs` (pending withdrawals this call confirmed or lazily\nexpired). `DepositNFTResponse` / `NFTWithdrawalResponse` similarly carry an\n`Inventory` (`InventoryDelta`) for the NFT's `UnstackableItems` instance —\nsame shape/semantics as the character-system module's `Inventory` deltas\n(`ChangedInstances` to upsert, `RemovedInstanceIDs` to drop). This mirrors the\nself-sufficient-response pattern used elsewhere in this SDK (see the\ncharacter-system skill) so a client that wants to reconcile\n`PendingWithdrawals`/balances/instances without another round trip can do so\nstraight from the mutating call's response. **Note:** `BlockchainService`\nitself does not auto-apply `StateDelta`/`Inventory` into\n`client.data.user.state.Blockchain` today — only the crypto **balance**\n(via the existing `AmountNative`-based patch) and item `Resources` are\napplied automatically. If you need `PendingWithdrawals` reconciled without a\nfull `getUserState()` refetch, read `result.data.StateDelta` yourself. Both\nare `null`/absent on an idempotent replay (nothing new to apply).\n\n```ts\nconst off = client.on(\"blockchain:tokenWithdrawalRequested\", (r) => {\n  console.log(`Withdrawal ${r.TitleTransactionID} expires at ${r.ExpiresAt}`);\n});\n// later: off();\n```\n\n## Recipes\n\n### Load config + state on a wallet/blockchain screen\n\n```ts\nawait client.blockchain.getDefinitions();\nawait client.blockchain.getUserState();\n\nconst defs = client.data.config.getSection<BlockchainDefinitions>(\"Blockchain\");\nconst bc = client.data.user.state?.Blockchain;\n\nfor (const [networkID, net] of Object.entries(defs?.Networks ?? {})) {\n  if (!net.DepositsEnabled && !net.WithdrawalsEnabled) continue;\n  // render a network card; net.NftCollections binds contracts to item catalogs\n}\nbc?.Kyc?.Status; // gate withdrawal UI on KYC if the title requires it\n```\n\n### Deposit a token (player already sent it on-chain)\n\n```ts\nconst res = await client.blockchain.depositToken(\"polygon\", \"0xabc123...\");\nif (!res.ok) return showError(res.error); // e.g. \"Transaction not found on chain.\",\n// \"Not enough confirmations (required 12). Try again in a few minutes.\",\n// \"Transaction hash already used.\"\n\nres.data.CurrencyID; // e.g. \"usdt\"\nres.data.AmountNative; // decimal string credited\n// Balance is already updated in the cache:\nclient.data.user.getCryptoCurrencyAmount(res.data.CurrencyID!);\n```\n\n### Full withdrawal lifecycle: request -> submit on-chain -> confirm, with a retry-after-failure path\n\n```ts\n// 1. Request the withdrawal — debits in-game immediately, returns a signature payload.\nconst req = await client.blockchain.requestTokenWithdrawal(\n  \"usdt\",\n  \"polygon\",\n  \"0xPlayerWallet...\",\n  \"25.00\",\n);\nif (!req.ok) return showError(req.error); // e.g. \"Not enough balance: have 10 usdt, need 25.00.\",\n// \"KYC verification required for withdrawals above 1000 USD.\",\n// \"Title users-withdrawable limit reached: available 5 usdt, requested 25.00.\"\n// — see \"Withdrawal gates\" above for the full list.\n\nconst { TitleTransactionID, EvmSignature, ExpiresAt } = req.data;\n// Balance is already debited (gross amount) in the cache.\n\n// 2. Hand EvmSignature (or SolanaSignature on a Solana network) to the\n//    player's wallet SDK to submit the on-chain transaction yourself —\n//    this SDK does not sign/broadcast. That step can fail (rejected in\n//    wallet, gas issue).\n\n// 2a. If on-chain submission failed WHILE the transaction is still Pending\n//     (before ExpiresAt), retry — this re-issues a fresh signature WITHOUT\n//     debiting again:\nconst retry = await client.blockchain.retryWithdrawal(TitleTransactionID!);\nif (!retry.ok) return showError(retry.error); // e.g. \"Transaction is not in Pending state (current: Abandoned).\"\nconst freshSignature = retry.data.EvmSignature ?? retry.data.SolanaSignature;\n// Submit freshSignature on-chain instead, then continue to step 3.\n//\n// IMPORTANT: retryWithdrawal only works while the transaction is Pending. If\n// ExpiresAt already passed, the backend has lazily moved it to Abandoned and\n// retryWithdrawal will reject it — there is no \"re-request\" for an Abandoned\n// withdrawal (the asset was already debited and is not refunded). The only\n// way to still complete it is confirmWithdrawal with a hash, if the player\n// actually managed to submit the original signature before it was swept —\n// see the Gotchas section.\n\n// 3. Once the wallet actually broadcasts the transaction, tell the backend\n//    the resulting on-chain hash so it can verify and close out the withdrawal:\nconst confirm = await client.blockchain.confirmWithdrawal(\n  TitleTransactionID!,\n  \"0xOnChainTxHash...\",\n);\nif (!confirm.ok) return showError(confirm.error);\nconfirm.data.Status; // e.g. \"Completed\" once the chain confirms it\n\n// 4. Refresh state — request/retry/confirm don't touch Blockchain cache themselves.\nawait client.blockchain.getUserState();\nclient.data.user.state?.Blockchain?.PendingWithdrawals; // should no longer list it once Completed\n```\n\n### KYC-gated withdrawal\n\nThe client never decides whether KYC is required — the backend compares the\nwithdrawal's USD-equivalent against the currency's configured threshold at\nrequest time. Use `Kyc.Status` only to pre-empt an obvious rejection in the\nUI; still branch on the real error:\n\n```ts\nawait client.blockchain.getUserState();\nconst kyc = client.data.user.state?.Blockchain?.Kyc;\n\nif (kyc?.Status !== \"Verified\") {\n  // Optional UX nicety: warn before the call for large amounts. This SDK has\n  // no startKyc/submitKyc method — verification happens through whatever KYC\n  // provider integration the title uses outside this SDK; Kyc here only\n  // reflects the result.\n}\n\nconst req = await client.blockchain.requestTokenWithdrawal(\n  \"usdt\",\n  \"polygon\",\n  \"0xPlayerWallet...\",\n  \"5000.00\",\n);\nif (!req.ok) {\n  if (req.error.startsWith(\"KYC verification required\")) {\n    // Route the player to the title's KYC verification flow.\n  }\n  return showError(req.error);\n}\n```\n\n### Deposit / withdraw an NFT\n\n```ts\n// Deposit: player already transferred the NFT to the vault address on-chain.\nconst dep = await client.blockchain.depositNFT(\"ethereum\", \"0xNftDepositTx...\");\nif (!dep.ok) return showError(dep.error);\ndep.data.ItemID; // the in-game item granted\ndep.data.Resources; // already applied to inventory in the cache\n\n// Withdraw: consumes the in-game item, returns a signature to submit on-chain.\nconst wd = await client.blockchain.requestNFTWithdrawal(\n  \"sword-of-embers-inst-1\", // ItemID (per NFTWithdrawalResponse/BlockchainRequest shape)\n  \"ethereum\",\n  \"0xPlayerWallet...\",\n  \"1\",\n);\nif (!wd.ok) return showError(wd.error);\nwd.data.TitleTransactionID; // use with retryWithdrawal / confirmWithdrawal exactly as tokens above\n\n// ERC-721 unique NFT: pass the specific instance to tokenize. level/itemInstanceID\n// are the trailing optional args — see the Methods table above.\nconst wd721 = await client.blockchain.requestNFTWithdrawal(\n  \"sword-of-embers\",\n  \"ethereum\",\n  \"0xPlayerWallet...\",\n  \"1\",\n  undefined, // category\n  1, // level\n  \"sword-of-embers-inst-1\", // ItemInstanceID — required for ERC-721 bindings\n);\n```\n\n### Edge case: not logged in / missing args\n\n```ts\nconst res = await client.blockchain.depositToken(\"\", \"0xabc\");\n// res.ok === false, res.reason === \"client\" — \"NetworkID is required.\" — no network call.\n\nconst res2 = await client.blockchain.getUserState();\n// If called before auth.loginWithDeviceID() (or any auth.* login):\n// res2.ok === false, res2.reason === \"unauthorized\"\n```\n\n### Donate crypto (no personal credit)\n\n```ts\nconst res = await client.blockchain.donateToDeveloper(\n  \"polygon\",\n  \"0xdonateTx...\",\n);\nif (!res.ok) return showError(res.error);\nres.data.Target; // \"Developer\" — confirms which pool bucket it landed in\n\n// donateToUsersPool is identical in shape, credits the users' pool bucket instead:\nawait client.blockchain.donateToUsersPool(\"polygon\", \"0xdonateTx2...\");\n```\n\n## Gotchas\n\n- **Withdrawal request debits immediately; the on-chain leg is separate and\n  can fail.** `requestTokenWithdrawal`/`requestNFTWithdrawal` already took the\n  asset from the player before any on-chain transaction exists. If the\n  player's wallet fails to submit (rejected, gas issue) **while the\n  transaction is still `Pending`**, don't ask them to request again — that\n  would debit twice. Use `retryWithdrawal` with the same\n  `TitleTransactionID` to get a fresh signature without a new charge. This\n  only works before `ExpiresAt` — see the next two points for what happens\n  after.\n- **`retryWithdrawal` vs `confirmWithdrawal` are opposite ends of the same\n  flow.** Retry re-issues the _signed payload_ before submission (nothing has\n  reached the chain yet); confirm reports the _resulting tx hash_ after\n  submission (the chain now has it). Calling confirm with a hash from a\n  transaction that never actually landed on-chain will simply fail\n  server-side verification — don't fabricate a hash to \"force\" completion.\n- **`ExpiresAt` is real, expiry does not refund the player, and — contrary to\n  what the name suggests — an expired withdrawal is NOT retryable.** A\n  withdrawal signature is time-boxed (`TokenWithdrawalResponse.ExpiresAt` /\n  `NFTWithdrawalResponse.ExpiresAt`, driven by\n  `BlockchainAccountSafetyPolicy.PendingWithdrawalTtlHours`). Once it passes\n  without a submission, the backend lazily transitions the transaction to\n  **`Abandoned`** (not `Expired` — that enum value exists but this backend\n  path never assigns it) and drops it off `PendingWithdrawals` — but the\n  already-debited asset is **not** credited back; this is intentional, not a\n  bug. Critically, `retryWithdrawal` requires the transaction to still be\n  `Pending` — calling it on an `Abandoned` one fails with `\"Transaction is\nnot in Pending state (current: Abandoned).\"` There is no \"re-request\"\n  operation for an abandoned withdrawal.\n- **A withdrawal can still be confirmed after it's `Abandoned`.** If the\n  player submits late — after `ExpiresAt` passed and the backend already\n  swept it to `Abandoned` — `confirmWithdrawal` still accepts it as long as\n  the on-chain transaction verifies (the signature itself doesn't expire\n  on-chain, only the title's own bookkeeping window does). Don't treat an\n  `Abandoned` transaction as unrecoverable if the player insists they\n  submitted it; calling `confirmWithdrawal` with the resulting hash is still\n  the right move, and is in fact the _only_ way to close out an\n  already-expired-but-actually-submitted withdrawal.\n- **`retryWithdrawal` only works on a `Pending` transaction the caller owns.**\n  It fails with `\"Transaction not found.\"` for an unknown or someone else's\n  `TitleTransactionID`, `\"Transaction is not in Pending state (current:\n{status}).\"` if it already completed/failed/was abandoned, or\n  `\"Signature data not found for this transaction.\"` if there's nothing to\n  reissue. A banned account additionally gets `\"Account is banned. Contact\nsupport.\"` on retry (deposits stay allowed for banned accounts; retrying a\n  withdrawal does not).\n- **Gross vs. net amounts on token withdrawals.** `AmountNative` is what was\n  debited from the player (gross); `NetAmountNative` is what actually gets\n  paid out on-chain after a platform commission percentage **and** an\n  optional on-chain burn are deducted (`NetAmountNative = AmountNative −\ncommission − BurnAmountNative`). Show the player the net figure they'll\n  receive, not the gross debit, to avoid support tickets about a \"missing\"\n  amount. NFT withdrawals have no such split — there's no `NetAmountNative`\n  on `NFTWithdrawalResponse`.\n- **Burn on withdrawal (EVM-only).** `TokenWithdrawalResponse.BurnAmountNative`\n  is the amount burned on-chain (sent to the DEAD address) for this\n  withdrawal, driven by the currency's `WithdrawalBurnPercent` (see the\n  currency-system skill) — `0` if burn is disabled for that currency or the\n  network is Solana. The raw-units counterpart, `WithdrawalSignatureResponse.\nBurnAmount`, is bound into the signed hash and must be passed to the\n  contract call verbatim, same as `Amount`/`Nonce` — `@idosgames/wallet`'s\n  `submitEvmTokenWithdrawal` does this for you; a client calling\n  `withdrawERC20` directly must include it too, or the signature check fails.\n- **`client.data.user.state.Blockchain` goes stale after deposits/withdrawal\n  requests.** Only `getUserState()` refreshes `LinkedWallets`,\n  `PendingWithdrawals`, `Kyc`, and `Stats`. A deposit/withdrawal call updates\n  your _balance_/_inventory_ cache correctly, but if your UI also shows the\n  pending-withdrawals list or lifetime stats, re-call `getUserState()`\n  afterward (see the withdrawal recipe above).\n- **Deposits are reporting, not sending.** `depositToken`/`depositNFT` don't\n  move any asset on-chain — they tell the backend \"verify this transaction\n  hash and credit me.\" The actual on-chain transfer to the platform's pool/\n  vault address must already have happened via a wallet SDK before you call\n  these.\n- **This SDK never signs or broadcasts.** `EvmSignature`/`SolanaSignature`\n  payloads are inputs to a wallet SDK/contract call that happens outside\n  `@idosgames/core`. Don't look for a \"submit on-chain\" method here — there\n  isn't one; `confirmWithdrawal` only reports the result afterward. The\n  `@idosgames/wallet` companion package is that outside layer — it submits the\n  signature on-chain and calls `confirmWithdrawal` for you.\n- **Donations never touch personal balances.** `donateToDeveloper` /\n  `donateToUsersPool` intentionally don't credit the player anything and\n  don't touch `client.data.user.state` — they only emit their own\n  `blockchain:donated*` event for a confirmation toast/receipt.\n- **Render from the cache, handle the error from the result.** The happy\n  path updates the relevant cache slice + emits an event; the failure path\n  gives you `reason` + `error`. Use `reason` to decide behavior (retry on\n  `\"connection\"`, re-auth on `\"unauthorized\"`, toast the `error` on\n  `\"server\"`).\n\n## Full reference\n\n[references/data-model.md](references/data-model.md) — every config and\nstate field: network definitions, NFT collection bindings, account-safety\npolicy, KYC state, transaction documents, the withdrawal-gate limits, and the\nEVM/Solana withdrawal signature payload shapes. Read it when building network\npickers, a transaction-history table, or KYC/limit-aware withdrawal UI. For\nthe shared `ResourceConsume`/`ResourceGrant`/`ResourceOperation`\ncost-and-reward shapes riding along on `depositNFT`/`requestNFTWithdrawal`,\nand for the full `CryptoCurrencyDefinition` shape (`Limits`, `Networks[].\nMinWithdraw`, `Permissions`) that the withdrawal gates enforce,\nsee the currency-system skill.\n",
   "references": [
     {
       "path": "data-model.md",

package/registry/skills/idosgames-module-contract.json

@@ -1,6 +1,6 @@
 {
   "name": "idosgames-module-contract",
   "description": "Write or modify an iDosGames feature module against the module contract in @idosgames/module-sdk: the Module manifest, ModuleContext, EngineScene (Three/Phaser/vanilla), UiPanel (React), route registration, and the shared controller-box bridge between an imperative scene and React panels. Use this whenever a developer authors a NEW module, edits an existing one (board-game, idle-rpg, voxelcraft, game-hud, workshop), or asks about defineModule, registerScene/registerPanel/registerRoute, activate/suspend, SceneMountContext, sharedUi / ctx.sharedUi.shouldDraw, ctx.events / defineTopic, ctx.content / ContentTypeHandler (letting the Workshop publish and open the game's content), ctx.navigate, the --idos-safe-* layout variables, or the {camelCase(id)}Module export convention.",
-  "content": "---\nname: idosgames-module-contract\ndescription: >-\n  Write or modify an iDosGames feature module against the module contract in @idosgames/module-sdk:\n  the Module manifest, ModuleContext, EngineScene (Three/Phaser/vanilla), UiPanel (React), route\n  registration, and the shared controller-box bridge between an imperative scene and React panels.\n  Use this whenever a developer authors a NEW module, edits an existing one (board-game, idle-rpg,\n  voxelcraft, game-hud, workshop), or asks about defineModule, registerScene/registerPanel/registerRoute,\n  activate/suspend, SceneMountContext, sharedUi / ctx.sharedUi.shouldDraw, ctx.events / defineTopic,\n  ctx.content / ContentTypeHandler (letting the Workshop publish and open the game's content),\n  ctx.navigate, the --idos-safe-* layout variables, or the {camelCase(id)}Module export convention.\n---\n\n# The module contract (@idosgames/module-sdk)\n\nA module is a manifest the host installs once. It exports `{camelCase(id)}Module` from its\n`index.ts` (e.g. `board-game` → `boardGameModule`, `idle-rpg` → `idleRpgModule`) — the host seeder\nderives the import name from the id, so this convention is required.\n\n```ts\nimport { defineModule } from \"@idosgames/module-sdk\";\n\nexport const boardGameModule = defineModule({\n  id: \"board-game\",\n  meta: { name: \"Board Game\", type: \"game\", genre: \"board\", engine: \"three\" }, // engine: three|phaser|dom\n  setup(ctx) {\n    // ctx.client (shared, authed) · ctx.events (typed cross-module bus) · ctx.sharedUi · ctx.surface\n    ctx.registerScene(createScene(box)); // rendered engine scene (optional)\n    ctx.registerPanel({ id: \"root\", slot: \"overlay\", component: RootPanel }); // React UI (optional)\n    ctx.registerRoute({ id: \"board-game\", label: \"Board\", icon: \"🎲\" }); // nav/mode entry\n  },\n});\n```\n\nOptional static field: `sharedUi: { provides?: SharedUiRole[]; requires?: SharedUiRole[] }` — see\n\"Shared chrome\" below.\n\n`meta.type` is `game | app | ai-app`; `meta.engine` is `three | phaser | dom` (`dom` = no renderer —\na pure React/DOM app module). `setup` is called ONCE with `ctx: ModuleContext`.\n\n## EngineScene (the rendered part)\n\nA scene mounts into a bare `HTMLElement` (framework-free — this is why a vanilla Three game like\nvoxelcraft fits). The host's Mode Router drives it; only the active mode runs.\n\n```ts\nconst scene: EngineScene = {\n  surface: \"fullbleed-canvas\",\n  mount(ctx: SceneMountContext) {\n    controller = new Controller(ctx.host);\n    box.set(controller);\n  },\n  activate() {\n    controller?.setRunning(true);\n  }, // became the active mode → resume RAF\n  suspend() {\n    controller?.setRunning(false);\n  }, // hidden → stop RAF (invariant: only active ticks)\n  destroy() {\n    controller?.destroy();\n  }, // permanent teardown\n};\n```\n\n`mount` takes a context object (not a bare element) so it can grow — e.g. a host-shared renderer in\nthe composition era — without breaking the contract. A scene MUST stop its RAF on `suspend`.\n\nA module that registers a scene MUST also publish its debug surface — `ctx.exposeToAgent({ state,\nactions, describeActions })` — and must NOT gate controls on Pointer Lock (unavailable in the\npreview's cross-origin iframe). Nothing inside a `<canvas>` is observable from the DOM, so without\nthe surface neither the AI Coder nor a human reviewer can tell what the game is doing. See the\n`idosgames-agent-debug-surface` skill.\n\n## UiPanel (the React part)\n\nPanels are React components the host renders inside its provider stack (client + status already\nprovided). Use `@idosgames/react` hooks (`useIDosGamesClient`, `useUserState`) — do NOT re-create\nproviders.\n\n- `slot`: `hud | sidebar | overlay | modal`.\n- `activeOnly` (default true): show only while this module's mode is active. Set `false` for shared\n  chrome that stays across every mode (e.g. a persistent HUD).\n- `overlay`/`sidebar` layers sit between the shared HUD and the nav (the host measures both), so a\n  panel positioned `absolute` inside its layer never ends up under them. Things drawn outside the\n  layers use `var(--idos-safe-top, 0px)` / `var(--idos-safe-bottom, 0px)`.\n- A `hud` panel's wrapper is `display: contents`: the panel is a direct flex child of the HUD row\n  (can `flex: 1`) and must set `pointer-events: auto` only on its controls.\n\n## Shared chrome (`sharedUi`)\n\nRoles: `currency-bar` (virtual-currency balances), `wallet` (crypto wallet entry — `LazyWalletPanel`),\n`status` (the `useStatus()` line), `account` (Log out + player ID). A module that draws one for every\nmode declares `sharedUi: { provides: [...] }` on the module object — statically, so the host resolves\nowners before any `setup()` and the answer never depends on module order.\n\n**Rule for templates: yield every role you draw yourself.** Read it once in `setup()` and close over\nthe answer (it is fixed for the session):\n\n```ts\nsetup(ctx) {\n  const chrome = {\n    wallet: ctx.sharedUi.shouldDraw(\"wallet\"),\n    balances: ctx.sharedUi.shouldDraw(\"currency-bar\"),\n    status: ctx.sharedUi.shouldDraw(\"status\"),\n  };\n  ctx.registerPanel({ id: \"root\", slot: \"overlay\", component: makeRootPanel(box, chrome) });\n}\n```\n\nHide only the SHARED pieces — genre UI (the board's stage/tile/cycle chips) always stays. Never\nwrap your UI in your own `<StatusProvider>`: the host provides ONE, and a nested one would swallow\nyour messages so the shared status line never sees them. A module that needs a role but does not\ndraw it declares `sharedUi: { requires: [\"currency-bar\"] }`. `ctx.sharedUi.ownerOf(role)` names the\nprovider (or `null`).\n\n## Events (`ctx.events`)\n\nTyped topic tokens — `defineTopic(\"<your-id>:<event>@1\", shape({ … }))` from\n`@idosgames/module-sdk`; emit only your own namespace; to listen to another module, copy its topic\nand payload descriptor from the catalog into your own `defineTopic` (never import it); declare both\nin `module.meta.json` (`events.emits` / `events.listens`). **Subscribe in `setup()`**, not in a panel\neffect — `activeOnly` panels unmount with their mode and miss events; store what arrives in a small\nstore the panel reads. Full rules and examples: **idosgames-compose-modules** (\"Signals between\nmodules\"). The string overloads (`emit(\"x\", …)`) are deprecated.\n\n## Content types (`ctx.content`) and switching modes (`ctx.navigate`)\n\nA game whose players make things (worlds, levels, skins) registers a **content type handler** so the\nshared Workshop module can publish and open them — the Workshop never imports the game:\n\n```ts\nsetup(ctx) {\n  ctx.content.registerType({\n    type: \"voxelcraft.world\",   // = a key of Workshop.ContentTypes in the title config\n    label: \"VoxelCraft world\",\n    icon: \"⛏️\",\n    modeId: \"voxelcraft\",        // route to switch to after open()\n    async listLocal() { return saves.map((s) => ({ id: s.id, name: s.name, updatedAt: s.at })); },\n    async capture(localId) {     // roles/MIME types must fit the title's content type config\n      return { files: [{ role: \"main\", contentType: \"application/json\", data: json }],\n               thumbnail: { contentType: \"image/webp\", data: webp }, suggestedTitle: name };\n    },\n    async open(content) { importSave(content.files[0].data); },\n  });\n}\n```\n\nHandlers registered in `setup()` are removed with the module; `registerType` returns an unregister\nfunction for anything dynamic. `ctx.navigate(modeId)` switches the host to another module's route\n(the Workshop uses it to jump into the game after `open`); an unknown id is ignored. Details:\n**workshop-system**.\n\n## Bridging scene ↔ panel\n\nThe scene creates its controller at `mount` (needs the canvas), but panels render before that. Share\nit with a one-slot observable and read it with `useSyncExternalStore`:\n\n```ts\nexport function createControllerBox<T>() {\n  /* get/set/subscribe */\n}\n// panel: const controller = useSyncExternalStore(box.subscribe, box.get); if (!controller) return <Loading/>;\n```\n\nFor the module's controller React context use the shared factory instead of hand-writing it:\n\n```ts\nexport const [BoardControllerProvider, useBoardController] =\n  createControllerContext<BoardController>(\"BoardController\"); // from @idosgames/react\n```\n\n## Layout and boundaries\n\nA module is one folder, `src/modules/<id>/`. It imports only its own files, the game's shared code\nin `src/shared/` and npm packages — never another module's files or host files. Talk to other\nmodules through the shared `ctx.client` (durable state) and `ctx.events` (live signals, typed\ntopics `<module-id>:<event>@<major>` declared in `module.meta.json`). A module shipped in the catalog is fully self-contained — it never uses\n`src/shared/`, so it installs into any game; a game's own module may use it, and its shared code is\ncopied into it when it is published for other creators.\n\n```\nsrc/modules/<id>/\n  index.ts           export { <camelCaseId>Module } from \"./module\";\n  module.ts          defineModule({ … })\n  module.meta.json   manifest: type (template|feature), summary, provides, tags, version, author\n  components/  game/  data/  react/   — as needed\n```\n\nEvery module carries its own `module.meta.json` (the `ModuleManifest` shape), including a game's own\nmodules. The full standard — where a new feature goes, file size, documentation — is\n**idosgames-project-structure**.\n\n## Dependencies\n\nDeclare only the module's UNIQUE deps (e.g. `phaser` for idle-rpg, `three` for board/voxel) plus the\nshared baseline (react, @idosgames/*). The platform pins shared libs identically across modules; two\nmodules must not request different versions of one package (the build allowlist rejects it).\n\nStudy a real module via `get_module {id}` (MCP) before writing a new one.\n",
+  "content": "---\nname: idosgames-module-contract\ndescription: >-\n  Write or modify an iDosGames feature module against the module contract in @idosgames/module-sdk:\n  the Module manifest, ModuleContext, EngineScene (Three/Phaser/vanilla), UiPanel (React), route\n  registration, and the shared controller-box bridge between an imperative scene and React panels.\n  Use this whenever a developer authors a NEW module, edits an existing one (board-game, idle-rpg,\n  voxelcraft, game-hud, workshop), or asks about defineModule, registerScene/registerPanel/registerRoute,\n  activate/suspend, SceneMountContext, sharedUi / ctx.sharedUi.shouldDraw, ctx.events / defineTopic,\n  ctx.content / ContentTypeHandler (letting the Workshop publish and open the game's content),\n  ctx.navigate, the --idos-safe-* layout variables, or the {camelCase(id)}Module export convention.\n---\n\n# The module contract (@idosgames/module-sdk)\n\nA module is a manifest the host installs once. It exports `{camelCase(id)}Module` from its\n`index.ts` (e.g. `board-game` → `boardGameModule`, `idle-rpg` → `idleRpgModule`) — the host seeder\nderives the import name from the id, so this convention is required.\n\n```ts\nimport { defineModule } from \"@idosgames/module-sdk\";\n\nexport const boardGameModule = defineModule({\n  id: \"board-game\",\n  meta: { name: \"Board Game\", type: \"game\", genre: \"board\", engine: \"three\" }, // engine: three|phaser|dom\n  setup(ctx) {\n    // ctx.client (shared, authed) · ctx.events (typed cross-module bus) · ctx.sharedUi · ctx.surface\n    ctx.registerScene(createScene(box)); // rendered engine scene (optional)\n    ctx.registerPanel({ id: \"root\", slot: \"overlay\", component: RootPanel }); // React UI (optional)\n    ctx.registerRoute({ id: \"board-game\", label: \"Board\", icon: \"🎲\" }); // nav/mode entry\n  },\n});\n```\n\nOptional static field: `sharedUi: { provides?: SharedUiRole[]; requires?: SharedUiRole[] }` — see\n\"Shared chrome\" below.\n\n`meta.type` is `game | app | ai-app`; `meta.engine` is `three | phaser | dom` (`dom` = no renderer —\na pure React/DOM app module). `setup` is called ONCE with `ctx: ModuleContext`.\n\n## EngineScene (the rendered part)\n\nA scene mounts into a bare `HTMLElement` (framework-free — this is why a vanilla Three game like\nvoxelcraft fits). The host's Mode Router drives it; only the active mode runs.\n\n```ts\nconst scene: EngineScene = {\n  surface: \"fullbleed-canvas\",\n  mount(ctx: SceneMountContext) {\n    controller = new Controller(ctx.host);\n    box.set(controller);\n  },\n  activate() {\n    controller?.setRunning(true);\n  }, // became the active mode → resume RAF\n  suspend() {\n    controller?.setRunning(false);\n  }, // hidden → stop RAF (invariant: only active ticks)\n  destroy() {\n    controller?.destroy();\n  }, // permanent teardown\n};\n```\n\n`mount` takes a context object (not a bare element) so it can grow — e.g. a host-shared renderer in\nthe composition era — without breaking the contract. A scene MUST stop its RAF on `suspend`.\n\nA module that registers a scene MUST also publish its debug surface — `ctx.exposeToAgent({ state,\nactions, describeActions })` — and must NOT gate controls on Pointer Lock (unavailable in the\npreview's cross-origin iframe). Nothing inside a `<canvas>` is observable from the DOM, so without\nthe surface neither the AI Coder nor a human reviewer can tell what the game is doing. See the\n`idosgames-agent-debug-surface` skill.\n\n### `capture()` — the frame for \"Take a shot and share\"\n\nidosgames.com has a **Shot** button under the game: it asks the game for one frame, puts the\nplatform's branding and a QR code on it and offers to post it. A scene answers through the optional\n`capture?(): Promise<Blob | null>`. The host (`@idosgames/app-shell`) wires the request itself —\na module only has to return a picture of its active scene.\n\n**Implement it in any scene that renders to a canvas.** Without it the host falls back to reading\nthe `<canvas>` from outside, and for WebGL that is a trap: a renderer created WITHOUT\n`preserveDrawingBuffer` (the default, and the right default — the flag costs memory and a copy every\nframe) has already cleared its buffer by the time anyone reads it, so `toBlob()` returns a **fully\nblack** image and reports nothing. The host rejects single-colour frames, so the player gets the\ngame's cover instead of their moment.\n\nRender and read in the SAME tick:\n\n```ts\n// three.js\ncapture() {\n  return new Promise((resolve) => {\n    renderer.render(scene, camera);          // draw now…\n    renderer.domElement.toBlob(resolve, \"image/png\"); // …and read before the buffer is cleared\n  });\n},\n\n// Phaser — use its own snapshot, it handles the timing\ncapture() {\n  return new Promise((resolve) => {\n    setTimeout(() => resolve(null), 1500); // no frame came (context lost) → answer \"no\", don't hang\n    game.loop.wake();                       // a sleeping loop never draws again → snapshot never fires\n    game.renderer.snapshot((image) => {\n      if (!(image instanceof HTMLImageElement)) return resolve(null);\n      const c = document.createElement(\"canvas\");\n      c.width = image.naturalWidth || image.width;\n      c.height = image.naturalHeight || image.height;\n      c.getContext(\"2d\")?.drawImage(image, 0, 0);\n      c.toBlob(resolve, \"image/png\");\n    });\n  });\n},\n```\n\nAlways answer — with a Blob or `null`. A `capture()` that never settles makes the site wait out its\ntimeout before it falls back, and the player stares at a spinner.\n\nReturn `null` when there is nothing worth showing (loading, no scene yet) — the site then uses the\ncover. Only the scene is captured, not the React panels over it: a shot for a feed reads better\nwithout the HUD. DOM-only modules (no canvas) simply omit `capture`. Working references:\n`modules/board-game` and `modules/voxelcraft` (three), `modules/idle-rpg` (Phaser).\n\n## UiPanel (the React part)\n\nPanels are React components the host renders inside its provider stack (client + status already\nprovided). Use `@idosgames/react` hooks (`useIDosGamesClient`, `useUserState`) — do NOT re-create\nproviders.\n\n- `slot`: `hud | sidebar | overlay | modal`.\n- `activeOnly` (default true): show only while this module's mode is active. Set `false` for shared\n  chrome that stays across every mode (e.g. a persistent HUD).\n- `overlay`/`sidebar` layers sit between the shared HUD and the nav (the host measures both), so a\n  panel positioned `absolute` inside its layer never ends up under them. Things drawn outside the\n  layers use `var(--idos-safe-top, 0px)` / `var(--idos-safe-bottom, 0px)`.\n- A `hud` panel's wrapper is `display: contents`: the panel is a direct flex child of the HUD row\n  (can `flex: 1`) and must set `pointer-events: auto` only on its controls.\n\n## Shared chrome (`sharedUi`)\n\nRoles: `currency-bar` (virtual-currency balances), `wallet` (crypto wallet entry — `LazyWalletPanel`),\n`status` (the `useStatus()` line), `account` (Log out + player ID). A module that draws one for every\nmode declares `sharedUi: { provides: [...] }` on the module object — statically, so the host resolves\nowners before any `setup()` and the answer never depends on module order.\n\n**Rule for templates: yield every role you draw yourself.** Read it once in `setup()` and close over\nthe answer (it is fixed for the session):\n\n```ts\nsetup(ctx) {\n  const chrome = {\n    wallet: ctx.sharedUi.shouldDraw(\"wallet\"),\n    balances: ctx.sharedUi.shouldDraw(\"currency-bar\"),\n    status: ctx.sharedUi.shouldDraw(\"status\"),\n  };\n  ctx.registerPanel({ id: \"root\", slot: \"overlay\", component: makeRootPanel(box, chrome) });\n}\n```\n\nHide only the SHARED pieces — genre UI (the board's stage/tile/cycle chips) always stays. Never\nwrap your UI in your own `<StatusProvider>`: the host provides ONE, and a nested one would swallow\nyour messages so the shared status line never sees them. A module that needs a role but does not\ndraw it declares `sharedUi: { requires: [\"currency-bar\"] }`. `ctx.sharedUi.ownerOf(role)` names the\nprovider (or `null`).\n\n## Events (`ctx.events`)\n\nTyped topic tokens — `defineTopic(\"<your-id>:<event>@1\", shape({ … }))` from\n`@idosgames/module-sdk`; emit only your own namespace; to listen to another module, copy its topic\nand payload descriptor from the catalog into your own `defineTopic` (never import it); declare both\nin `module.meta.json` (`events.emits` / `events.listens`). **Subscribe in `setup()`**, not in a panel\neffect — `activeOnly` panels unmount with their mode and miss events; store what arrives in a small\nstore the panel reads. Full rules and examples: **idosgames-compose-modules** (\"Signals between\nmodules\"). The string overloads (`emit(\"x\", …)`) are deprecated.\n\n## Content types (`ctx.content`) and switching modes (`ctx.navigate`)\n\nA game whose players make things (worlds, levels, skins) registers a **content type handler** so the\nshared Workshop module can publish and open them — the Workshop never imports the game:\n\n```ts\nsetup(ctx) {\n  ctx.content.registerType({\n    type: \"voxelcraft.world\",   // = a key of Workshop.ContentTypes in the title config\n    label: \"VoxelCraft world\",\n    icon: \"⛏️\",\n    modeId: \"voxelcraft\",        // route to switch to after open()\n    async listLocal() { return saves.map((s) => ({ id: s.id, name: s.name, updatedAt: s.at })); },\n    async capture(localId) {     // roles/MIME types must fit the title's content type config\n      return { files: [{ role: \"main\", contentType: \"application/json\", data: json }],\n               thumbnail: { contentType: \"image/webp\", data: webp }, suggestedTitle: name };\n    },\n    async open(content) { importSave(content.files[0].data); },\n  });\n}\n```\n\nHandlers registered in `setup()` are removed with the module; `registerType` returns an unregister\nfunction for anything dynamic. `ctx.navigate(modeId)` switches the host to another module's route\n(the Workshop uses it to jump into the game after `open`); an unknown id is ignored. Details:\n**workshop-system**.\n\n## Bridging scene ↔ panel\n\nThe scene creates its controller at `mount` (needs the canvas), but panels render before that. Share\nit with a one-slot observable and read it with `useSyncExternalStore`:\n\n```ts\nexport function createControllerBox<T>() {\n  /* get/set/subscribe */\n}\n// panel: const controller = useSyncExternalStore(box.subscribe, box.get); if (!controller) return <Loading/>;\n```\n\nFor the module's controller React context use the shared factory instead of hand-writing it:\n\n```ts\nexport const [BoardControllerProvider, useBoardController] =\n  createControllerContext<BoardController>(\"BoardController\"); // from @idosgames/react\n```\n\n## Layout and boundaries\n\nA module is one folder, `src/modules/<id>/`. It imports only its own files, the game's shared code\nin `src/shared/` and npm packages — never another module's files or host files. Talk to other\nmodules through the shared `ctx.client` (durable state) and `ctx.events` (live signals, typed\ntopics `<module-id>:<event>@<major>` declared in `module.meta.json`). A module shipped in the catalog is fully self-contained — it never uses\n`src/shared/`, so it installs into any game; a game's own module may use it, and its shared code is\ncopied into it when it is published for other creators.\n\n```\nsrc/modules/<id>/\n  index.ts           export { <camelCaseId>Module } from \"./module\";\n  module.ts          defineModule({ … })\n  module.meta.json   manifest: type (template|feature), summary, provides, tags, version, author\n  components/  game/  data/  react/   — as needed\n```\n\nEvery module carries its own `module.meta.json` (the `ModuleManifest` shape), including a game's own\nmodules. The full standard — where a new feature goes, file size, documentation — is\n**idosgames-project-structure**.\n\n## Dependencies\n\nDeclare only the module's UNIQUE deps (e.g. `phaser` for idle-rpg, `three` for board/voxel) plus the\nshared baseline (react, @idosgames/*). The platform pins shared libs identically across modules; two\nmodules must not request different versions of one package (the build allowlist rejects it).\n\nStudy a real module via `get_module {id}` (MCP) before writing a new one.\n",
   "references": []
 }