@idosgames/mcp 0.1.27 → 0.1.29

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>   ONE panel for EVM and Solana: it reads the title's networks and loads the\n>   right one — same form, deposit and withdraw on both (Solana through the\n>   platform pool, `createPlatformPoolAdapter`). The base already puts it in the\n>   lobby header (`src/base/lobby/WalletButton.tsx`) — don't add a second one.\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> A wallet BUTTON inside the frame calls `openPlatformWalletPanel()` (from `@idosgames/wallet/react/lazy`)\n> — the site shows its own wallet card; that is what the base's lobby button does.\n> `LazyWalletPanel` itself 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",
+  "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>   ONE panel for EVM and Solana: it reads the title's networks and loads the\n>   right one — same form, deposit and withdraw on both (Solana through the\n>   platform pool, `createPlatformPoolAdapter`). The base already puts it in the\n>   lobby header (`src/walletButton.tsx` over the SDK's lobby) — don't add a second one.\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> A wallet BUTTON inside the frame calls `openPlatformWalletPanel()` (from `@idosgames/wallet/react/lazy`)\n> — the site shows its own wallet card; that is what the base's lobby button does.\n> `LazyWalletPanel` itself 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(opts?)`                                                                              | The title's blockchain config: networks (pool addresses from the platform registry), NFT bindings, crypto currencies. Central cache by the config version — repeat reads ask nothing; pass `{ forceRefresh: true }` right before a deposit/withdrawal (the registry can be republished in place). | `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/checkout-system.json

@@ -1,6 +1,6 @@
 {
   "name": "checkout-system",
   "description": "Take payment for anything priced in a game on the iDosGames TypeScript SDK: price options (PriceOptions), real-money purchases through Google Play / App Store (client.purchase, PurchaseService), paying with an on-chain currency from the player's wallet (@idosgames/wallet payWithWalletEvm), and choosing what to show per platform (client.checkout, CheckoutService, usePayment). Use this whenever the user works in the iDosGames TS SDK and touches prices, IAP, receipts, store products, \"pay with crypto\", platform gating of payment methods, PriceOption, PaymentProof, SelectedOptionID, or asks why an option is missing or a purchase is refused — even if they don't name the module.",
-  "content": "---\nname: checkout-system\ndescription: >-\n  Take payment for anything priced in a game on the iDosGames TypeScript SDK:\n  price options (PriceOptions), real-money purchases through Google Play /\n  App Store (client.purchase, PurchaseService), paying with an on-chain\n  currency from the player's wallet (@idosgames/wallet payWithWalletEvm), and\n  choosing what to show per platform (client.checkout, CheckoutService,\n  usePayment). Use this whenever the user works in the iDosGames TS SDK and\n  touches prices, IAP, receipts, store products, \"pay with crypto\", platform\n  gating of payment methods, PriceOption, PaymentProof, SelectedOptionID, or\n  asks why an option is missing or a purchase is refused — even if they don't\n  name the module.\n---\n\n# Checkout (iDosGames TS SDK)\n\nEverything a title sells is priced the same way: a **`PriceOptions` dictionary**\non the entity, where each option is one way to pay. The key of the dictionary is\nthe option's `OptionID`, and the player picks one.\n\nOptions exist because a single cost is charged **as a whole** — that is \"and\".\nA price across platforms is a **choice** — \"or\": a store SKU on mobile, a token\non web. One option, one way to pay.\n\n```ts\n// An offer with two ways to pay.\nPriceOptions: {\n  gold:  { OptionID: \"gold\",  Cost: { Standard: { Entries: [{ Type: \"VirtualCurrency\", CurrencyID: \"gold\", Amount: 500 }] } } },\n  store: { OptionID: \"store\", Cost: { Standard: { Entries: [{ Type: \"Purchase\", ProductID: \"coin_pack_small\" }] } },\n           AllowedPlatforms: [\"Android\", \"Ios\"] },\n}\n```\n\n## The one rule that matters\n\n**The client renders, the server allows.**\n\nTitle config ships as one immutable artifact per (version, field set), so it\n_cannot_ be filtered per request — every platform receives the same price list.\nSo the client hides what it may not offer, and the server refuses to charge an\noption that is not available on the caller's platform. Showing an option a store\nforbids is a policy problem; paying with it is impossible either way.\n\nThat is why you never hand-roll the filter:\n\n```ts\nconst options = client.checkout.availableOptions(offer.PriceOptions);\n```\n\n## Paying\n\nWhich of the three shapes you are in is answered by one call:\n\n```ts\nconst requirement = client.checkout.requirementOf(option);\n// { kind: \"store\", productID }        → buy the SKU, then pass the receipt\n// { kind: \"resources\" }               → just call the module\n// { kind: \"resources\", shortfall }    → crypto price, player is short\n```\n\n### 1. Resources (currency, items, tokens)\n\nNothing special — call the module that owns the entity:\n\n```ts\nawait client.store.purchase(offerID, count); // SelectedOptionID defaults to the first available\n```\n\nPass `SelectedOptionID` explicitly whenever the player chose an option — the\ndefault only exists so a single-price entity keeps working without any client\nchange.\n\n### 2. Real money (Google Play / App Store)\n\nThe receipt comes from the store SDK on the device; the SDK never talks to a\nstore itself. Attach it to the purchase:\n\n```ts\nawait client.store.purchase(offerID, count, {\n  selectedOptionID: option.OptionID,\n  payment: { Store: \"GooglePlay\", Receipt: receiptJson, Signature: signature },\n});\n```\n\n⚠ **The money is already gone when the server first hears about it.** A refusal\nhere is an incident, not \"insufficient funds\" — the server records every refusal\nin the title's transaction ledger together with what the receipt was paying for.\nTwo consequences for your code:\n\n- **Never drop a receipt.** Hand every receipt the store gives you to the server,\n  including the unfinished ones it re-delivers on startup. An order confirmed to\n  the store but never delivered to us is a purchase the player paid for and will\n  never receive.\n- **Re-submitting the same receipt is safe** and grants nothing twice — but the\n  response then carries no resources. Apply `Resources` only when the server says\n  it granted something (`Granted: true` for `client.purchase`, a non-empty\n  `Resources` for module purchases).\n\nFor products that ARE the goods (gem packs, remove-ads, subscriptions) use\n`client.purchase` directly — `validatePurchase`, `validatePurchasesBatch` for\nrestore after a reinstall.\n\n### 3. On-chain currency from the player's wallet\n\nThe price is denominated in tokens, and the player pays from their in-game\nbalance. When that balance is short, top it up from their own wallet — this\nlives in `@idosgames/wallet`, because `core` never imports a wallet stack:\n\n```ts\nimport { payWithWalletEvm } from \"@idosgames/wallet\";\n\nconst { shortfall } = client.checkout.requirementOf(option);\nif (shortfall) {\n  await payWithWalletEvm({\n    client,\n    clients,\n    network,\n    tokenAddress,\n    decimals,\n    titleID,\n    shortfall,\n    completePurchase: () =>\n      client.store.purchase(offerID, count, {\n        selectedOptionID: option.OptionID,\n      }),\n  });\n}\n```\n\n### Host owns the session (Unity WebGL, native shells)\n\nWhen the wallet lives on the page but the game's session does not — a Unity WebGL build is the\ncase — use `depositTokenOnChainEvm` instead. It does only the on-chain half (approve → deposit →\nwait for the receipt) and reports nothing to the backend; the host registers the tx hash with its\nown session and then makes the purchase. Handing the page a logged-in client instead would give\nevery script on it full access to the player's account.\n\n⚠ **This is two steps and cannot be one.** A deposit confirms on-chain, so the\ntokens land on the balance in one request and the purchase happens in the next.\nNothing is lost if the game dies in between — the tokens are credited — but the\nplayer is left with money and no goods unless you can resume. **Keep the intent\nlocally and offer to finish it on the next launch.**\n\nOnly the **shortfall** is deposited, not the whole price: whatever the player\nalready holds in-game is spent first.\n\n## React\n\n`usePayment` owns the part every payment UI repeats — which options to show,\nwhat each needs, and which stage the attempt is at:\n\n```tsx\nconst { options, requirementOf, stage, error, pay } = usePayment(\n  offer.PriceOptions,\n);\n```\n\n`stage` is a value (`awaiting-store`, `awaiting-wallet`, `purchasing`, …) rather\nthan a boolean on purpose: a wallet payment takes tens of seconds while the\ndeposit confirms, and a dialog showing only \"loading\" makes a working payment\nlook hung — so the player taps again.\n\n## Where a price may NOT be paid in a store\n\nSome prices are resource-only, and the server says so explicitly rather than\nfailing deep inside the resource engine:\n\n| Where                                       | Why                                                                                                         |\n| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |\n| Item / character / stat upgrades            | Price grows by a formula per level; a store SKU is a fixed tier and cannot follow it                        |\n| Craft                                       | Price is per craft and multiplied by the count — there is no \"one and a half receipts\"                      |\n| Coop-event spins                            | Only the spins that actually happened are charged; a store cannot refund half a receipt                     |\n| Match creation fee, marketplace listing fee | May have to be refunded, and a store refund is not ours to issue — plus these are player-to-player contexts |\n| AI generation                               | A rate-limited micro-action; one receipt cannot be split across many of them                                |\n\nDeal offers, store offers, lootboxes, collection packs, character unlocks and\ntimed boosts **do** accept store payment — that is the main monetisation path.\n\n## Common mistakes\n\n- **Filtering options yourself by `AllowedPlatforms`.** Use\n  `client.checkout.availableOptions` — it also applies the same ordering the\n  server uses when the player did not choose an option.\n- **Trusting `PriceUsdCents` for display on mobile.** Show the store's own\n  localized price; the declared one is for analytics and sorting, and both\n  platforms require their price to be the one displayed.\n- **Applying `Resources` from a repeated receipt.** See above — that credits the\n  reward twice for a single payment.\n- **Assuming an option exists because the config has it.** On a platform where it\n  is not allowed, the server refuses the charge; render from\n  `availableOptions`, not from the raw dictionary.\n",
+  "content": "---\nname: checkout-system\ndescription: >-\n  Take payment for anything priced in a game on the iDosGames TypeScript SDK:\n  price options (PriceOptions), real-money purchases through Google Play /\n  App Store (client.purchase, PurchaseService), paying with an on-chain\n  currency from the player's wallet (@idosgames/wallet payWithWalletEvm), and\n  choosing what to show per platform (client.checkout, CheckoutService,\n  usePayment). Use this whenever the user works in the iDosGames TS SDK and\n  touches prices, IAP, receipts, store products, \"pay with crypto\", platform\n  gating of payment methods, PriceOption, PaymentProof, SelectedOptionID, or\n  asks why an option is missing or a purchase is refused — even if they don't\n  name the module.\n---\n\n# Checkout (iDosGames TS SDK)\n\nEverything a title sells is priced the same way: a **`PriceOptions` dictionary**\non the entity, where each option is one way to pay. The key of the dictionary is\nthe option's `OptionID`, and the player picks one.\n\nOptions exist because a single cost is charged **as a whole** — that is \"and\".\nA price across platforms is a **choice** — \"or\": a store SKU on mobile, a token\non web. One option, one way to pay.\n\n```ts\n// An offer with two ways to pay.\nPriceOptions: {\n  gold:  { OptionID: \"gold\",  Cost: { Standard: { Entries: [{ Type: \"VirtualCurrency\", CurrencyID: \"gold\", Amount: 500 }] } } },\n  store: { OptionID: \"store\", Cost: { Standard: { Entries: [{ Type: \"Purchase\", ProductID: \"coin_pack_small\" }] } },\n           AllowedPlatforms: [\"Android\", \"Ios\"] },\n}\n```\n\n## The one rule that matters\n\n**The client renders, the server allows.**\n\nTitle config ships as one immutable artifact per (version, field set), so it\n_cannot_ be filtered per request — every platform receives the same price list.\nSo the client hides what it may not offer, and the server refuses to charge an\noption that is not available on the caller's platform. Showing an option a store\nforbids is a policy problem; paying with it is impossible either way.\n\nThat is why you never hand-roll the filter:\n\n```ts\nconst options = client.checkout.availableOptions(offer.PriceOptions);\n```\n\n## Paying\n\nWhich of the three shapes you are in is answered by one call:\n\n```ts\nconst requirement = client.checkout.requirementOf(option);\n// { kind: \"store\", productID }        → buy the SKU, then pass the receipt\n// { kind: \"resources\" }               → just call the module\n// { kind: \"resources\", shortfall }    → crypto price, player is short\n```\n\n### 1. Resources (currency, items, tokens)\n\nNothing special — call the module that owns the entity:\n\n```ts\nawait client.store.purchase(offerID, count); // SelectedOptionID defaults to the first available\n```\n\nPass `SelectedOptionID` explicitly whenever the player chose an option — the\ndefault only exists so a single-price entity keeps working without any client\nchange.\n\n### 2. Real money (Google Play / App Store)\n\nThe receipt comes from the store SDK on the device; the SDK never talks to a\nstore itself. Attach it to the purchase:\n\n```ts\nawait client.store.purchase(offerID, count, {\n  selectedOptionID: option.OptionID,\n  payment: { Store: \"GooglePlay\", Receipt: receiptJson, Signature: signature },\n});\n```\n\n⚠ **The money is already gone when the server first hears about it.** A refusal\nhere is an incident, not \"insufficient funds\" — the server records every refusal\nin the title's transaction ledger together with what the receipt was paying for.\nTwo consequences for your code:\n\n- **Never drop a receipt.** Hand every receipt the store gives you to the server,\n  including the unfinished ones it re-delivers on startup. An order confirmed to\n  the store but never delivered to us is a purchase the player paid for and will\n  never receive.\n- **Re-submitting the same receipt is safe** and grants nothing twice — but the\n  response then carries no resources. Apply `Resources` only when the server says\n  it granted something (`Granted: true` for `client.purchase`, a non-empty\n  `Resources` for module purchases).\n\nFor products that ARE the goods (gem packs, remove-ads, subscriptions) use\n`client.purchase` directly — `validatePurchase`, `validatePurchasesBatch` for\nrestore after a reinstall.\n\n### 3. On-chain currency from the player's wallet\n\nThe price is denominated in tokens (or in USD — `AmountUsd`, converted to tokens\nby the server), and the player pays from their in-game balance.\n\n**Inside idosgames.com it is automatic — write nothing.** When the server refuses\na charge for a crypto shortfall, the SDK opens the SITE's payment window for the\nmissing amount (the game may not touch a wallet in the site's frame), the player\ndeposits from the wallet connected on the site, and the SDK repeats the very same\nrequest once the deposit is credited. Your `client.store.purchase(...)` (or any\nmodule call) simply resolves later — with the goods. Keep the buy button enabled\nfor a crypto price the player cannot cover yet when\n`client.checkout.topUpAvailable` is `true`; a top-up that did not happen comes back\nas the original refusal plus the `checkout:topUpFailed` event\n(`CANCELLED`, `PENDING` — sent but not yet credited, `ACCOUNT_MISMATCH` — the game\nis signed in to another account than the site, …).\n\n**Outside the site (the game's own link) the game's own wallet does the same** —\nin a project made from the base it is already wired: `src/walletButton.tsx`\nexports `WalletTopUp` (passed to `createBaseModule`, kept mounted over every\nmode), which calls `useWalletTopUp(client)` from `@idosgames/wallet/react/lazy`\nand shows `<LazyWalletPanel topUp={request} />`: the panel opens on the missing\namount only (rounded up to the token's decimals, no withdraw), the player\ndeposits from their wallet, and the purchase repeats once the engine credits it.\nA deposit the network has not confirmed yet is re-REPORTED, never re-sent. Don't\nremove `WalletTopUp`; a game without the base mounts its own component with the\nsame hook. A game framed by a foreign site gets no top-up (its wallet is barred).\n\nA fully custom flow is still possible: `client.checkout.setTopUpHandler(async\n(shortfall) => { …; return credited; })`, or top up explicitly from the player's\nown wallet before the purchase. That lives in `@idosgames/wallet`, because `core`\nnever imports a wallet stack:\n\n```ts\nimport { payWithWalletEvm } from \"@idosgames/wallet\";\n\nconst { shortfall } = client.checkout.requirementOf(option);\nif (shortfall) {\n  await payWithWalletEvm({\n    client,\n    clients,\n    network,\n    tokenAddress,\n    decimals,\n    titleID,\n    shortfall,\n    completePurchase: () =>\n      client.store.purchase(offerID, count, {\n        selectedOptionID: option.OptionID,\n      }),\n  });\n}\n```\n\n### Host owns the session (Unity WebGL, native shells)\n\nWhen the wallet lives on the page but the game's session does not — a Unity WebGL build is the\ncase — use `depositTokenOnChainEvm` instead. It does only the on-chain half (approve → deposit →\nwait for the receipt) and reports nothing to the backend; the host registers the tx hash with its\nown session and then makes the purchase. Handing the page a logged-in client instead would give\nevery script on it full access to the player's account.\n\n⚠ **This is two steps and cannot be one.** A deposit confirms on-chain, so the\ntokens land on the balance in one request and the purchase happens in the next.\nNothing is lost if the game dies in between — the tokens are credited — but the\nplayer is left with money and no goods unless you can resume. **Keep the intent\nlocally and offer to finish it on the next launch.**\n\nOnly the **shortfall** is deposited, not the whole price: whatever the player\nalready holds in-game is spent first.\n\n## React\n\n`usePayment` owns the part every payment UI repeats — which options to show,\nwhat each needs, and which stage the attempt is at:\n\n```tsx\nconst { options, requirementOf, stage, error, pay } = usePayment(\n  offer.PriceOptions,\n);\n```\n\n`stage` is a value (`awaiting-store`, `awaiting-wallet`, `purchasing`, …) rather\nthan a boolean on purpose: a wallet payment takes tens of seconds while the\ndeposit confirms, and a dialog showing only \"loading\" makes a working payment\nlook hung — so the player taps again.\n\n## Where a price may NOT be paid in a store\n\nSome prices are resource-only, and the server says so explicitly rather than\nfailing deep inside the resource engine:\n\n| Where                                       | Why                                                                                                         |\n| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |\n| Item / character / stat upgrades            | Price grows by a formula per level; a store SKU is a fixed tier and cannot follow it                        |\n| Craft                                       | Price is per craft and multiplied by the count — there is no \"one and a half receipts\"                      |\n| Coop-event spins                            | Only the spins that actually happened are charged; a store cannot refund half a receipt                     |\n| Match creation fee, marketplace listing fee | May have to be refunded, and a store refund is not ours to issue — plus these are player-to-player contexts |\n| AI generation                               | A rate-limited micro-action; one receipt cannot be split across many of them                                |\n\nDeal offers, store offers, lootboxes, collection packs, character unlocks and\ntimed boosts **do** accept store payment — that is the main monetisation path.\n\n## Common mistakes\n\n- **Filtering options yourself by `AllowedPlatforms`.** Use\n  `client.checkout.availableOptions` — it also applies the same ordering the\n  server uses when the player did not choose an option.\n- **Trusting `PriceUsdCents` for display on mobile.** Show the store's own\n  localized price; the declared one is for analytics and sorting, and both\n  platforms require their price to be the one displayed.\n- **Applying `Resources` from a repeated receipt.** See above — that credits the\n  reward twice for a single payment.\n- **Assuming an option exists because the config has it.** On a platform where it\n  is not allowed, the server refuses the charge; render from\n  `availableOptions`, not from the raw dictionary.\n",
   "references": []
 }

package/registry/skills/cloud-code.json

@@ -1,6 +1,6 @@
 {
   "name": "cloud-code",
-  "description": "Write and call custom server-side game logic on the iDosGames platform: author a CloudCode handler (sandboxed JavaScript with a server.* API) and invoke it from the game via client.cloudCode (CloudCodeService) with an arbitrary JSON payload. Use this whenever the user wants bespoke server logic, a \"cloud script\", \"cloud function\" or \"server callable\", logic that must be authoritative (granting rewards, validating a reported result, anti-cheat), a write to protected player data (UserCustomData ReadOnly / Internal buckets) or to shared title state (TitleCustomData Runtime scope), or otherwise touches client.cloudCode, CloudCodeService, handlers, server.SetUserCustomData, server.IncrementTitleCustomData, server.HttpRequest or ExecuteCloudCodeResponse — even if they don't name the module explicitly. Also covers integrating a title with a third-party service (calling an external API with a stored API key, webhooks out, payment or analytics providers) and the {{secret:NAME}} / {{var:NAME}} placeholders, handlers that run on a schedule (cron-like jobs: daily resets, auction settlement) and incoming webhooks from external services (payment callbacks, site form posts, bots).",
-  "content": "---\nname: cloud-code\ndescription: >-\n  Write and call custom server-side game logic on the iDosGames platform:\n  author a CloudCode handler (sandboxed JavaScript with a server.* API) and\n  invoke it from the game via client.cloudCode (CloudCodeService) with an\n  arbitrary JSON payload. Use this whenever the user wants bespoke server\n  logic, a \"cloud script\", \"cloud function\" or \"server callable\", logic that\n  must be authoritative (granting rewards, validating a reported result,\n  anti-cheat), a write to protected player data (UserCustomData ReadOnly /\n  Internal buckets) or to shared title state (TitleCustomData Runtime scope),\n  or otherwise touches client.cloudCode, CloudCodeService, handlers,\n  server.SetUserCustomData, server.IncrementTitleCustomData,\n  server.HttpRequest or ExecuteCloudCodeResponse — even if they don't name the\n  module explicitly. Also covers integrating a title with a third-party service\n  (calling an external API with a stored API key, webhooks out, payment or\n  analytics providers) and the {{secret:NAME}} / {{var:NAME}} placeholders,\n  handlers that run on a schedule (cron-like jobs: daily resets, auction\n  settlement) and incoming webhooks from external services (payment callbacks,\n  site form posts, bots).\n---\n\n# Cloud Code (iDosGames TS SDK)\n\nCloud Code runs **your** JavaScript on the platform's servers. A script defines\nnamed handlers; the game calls one by name and gets back whatever JSON it\nreturns.\n\nTwo distinct reasons to reach for it:\n\n1. **Authority.** Client code that \"grants\" a reward, \"validates\" a score or\n   \"unlocks\" a level is a suggestion — the player owns the browser. Logic whose\n   outcome must be trusted belongs in a handler.\n2. **Protected data.** The `ReadOnly`/`Internal` buckets of a player's\n   UserCustomData and the `Runtime` scope of the title's data store have no\n   client write path at all. A handler is the only way to write them.\n\nIf a dedicated module already covers what you need (currency, item, store,\nquest, character, leaderboard…), prefer that module — it gives you typed\nrequest/response shapes and cache integration; Cloud Code gives you neither.\n\nPublishing a script is a platform operation, not an SDK one: the AI Coder does\nit with its `SaveCloudCode` tool, an external agent with the backend MCP's\n`publish_cloud_code`, and a publisher from the dashboard. Publishing **replaces\nthe whole revision** — read the current source first (`GetCloudCode` with\n`include_code`, or `get_cloud_code`) and send it back with your handler added,\nor you silently delete every handler the game still calls.\n\n## Mental model\n\nThere is exactly one client-facing action: `execute`. You pass a **function\nname** (a handler defined in the title's deployed script's `handlers` object)\nand an optional **arbitrary JSON payload**; the server runs it in a sandboxed\nJS engine and returns an arbitrary JSON result plus execution metadata (logs,\ntiming, error info). The SDK has no idea what a given script's args or result\nlook like — **you** know your title's script contract, so you type the\npayload and result yourself (see Gotchas). There's no \"config vs state\" split\nhere like other modules — Cloud Code has no persistent per-player data model\nof its own; it's pure request/response.\n\nScript failure is a **first-class outcome, not a network error**: if the\nscript throws, times out, is rate-limited, or the handler doesn't exist, the\ncall still comes back `{ ok: true, data }` with `data.Error` populated and\n`data.FunctionResult` empty. Only infrastructure problems (not logged in, bad\nlocal args, connection issues, backend down) surface as `{ ok: false }`.\n\n## Writing a handler\n\nA revision is one plain JavaScript file that fills the global `handlers` object.\nNo imports, no modules, no `async`/`await`, no `fetch` — everything you can touch\nis on `server.*` and `log.*`, and every call is synchronous. Outbound network\naccess exists but only through `server.HttpRequest`, and only to hosts the\npublisher allow-listed (see _Calling another service_).\n\n```js\nhandlers.claimDailyBonus = function (args, context) {\n  // context: { UserID, FunctionName, Revision, InvokedAt }\n  var data = server.GetUserCustomData();\n  if (!data.Success) throw new Error(data.Error);\n\n  var last = data.Data.ReadOnly[\"daily_claimed_at\"];\n  var today = new Date().toISOString().slice(0, 10);\n  if (last && last.Value === today)\n    return { granted: false, reason: \"already_claimed\" };\n\n  var write = server.SetUserCustomData(\"ReadOnly\", \"daily_claimed_at\", today);\n  if (!write.Success) throw new Error(write.Error);\n\n  server.IncrementTitleCustomData(\"Public\", \"daily_claims_total\", 1);\n  log.Info(\"daily bonus granted\", { user: context.UserID });\n  return { granted: true };\n};\n```\n\n### The `server.*` API\n\nEvery call returns `{ Success, Error, Data }` — **check `Success`**; a rejected\nwrite (limit hit, wrong bucket, version conflict) is a normal result, not a\nthrow. Each call also counts against the per-execution API budget, so batch.\n\n| Call                                                              | What it does                                                       |\n| ----------------------------------------------------------------- | ------------------------------------------------------------------ |\n| `server.ReadUserData([\"InventoryV2\", \"Premium\", …])`              | Read whitelisted sections of the caller's player document.         |\n| `server.GetTitleConfig(\"Currency\", \"Item\", …)`                    | Read the title's configuration sections.                           |\n| `server.GetUserCustomData()`                                      | All four buckets of the caller, **including `Internal`**.          |\n| `server.GetPublicUserCustomDataOf(userId)`                        | Another player's `Public` bucket.                                  |\n| `server.SetUserCustomData(bucket, key, value)`                    | Write any bucket — this is the protected-data write.               |\n| `server.DeleteUserCustomData(bucket, key)`                        | Delete a key from any bucket (idempotent).                         |\n| `server.BatchSetUserCustomData([{Bucket, KeyID, Value}, …])`      | Atomic multi-key write (all-or-nothing).                           |\n| `server.BatchDeleteUserCustomData([{Bucket, KeyID}, …])`          | Atomic multi-key delete.                                           |\n| `server.GetTitleCustomData()`                                     | Title store: both scopes, both buckets.                            |\n| `server.SetTitleCustomData(bucket, key, value, expectedVersion?)` | Write the title's `Runtime` scope; pass a version for CAS.         |\n| `server.IncrementTitleCustomData(bucket, key, delta)`             | Atomic counter on shared data — use this, never read-modify-write. |\n| `server.DeleteTitleCustomData(bucket, key)`                       | Delete a `Runtime` key.                                            |\n| `server.BatchSetTitleCustomData` / `BatchDeleteTitleCustomData`   | Atomic multi-key variants for the title store.                     |\n| `server.GetIntegrationVariable(name)`                             | Read a non-secret integration setting (base URL, account id).      |\n| `server.HttpRequest({ Method, Url, Headers, Body, ContentType })` | Call an external API — the only way out of the sandbox.            |\n| `server.AddQuestProgress(metricID, value)`                        | Advance quest objectives configured with `Source: \"ServerApi\"`.    |\n\n`server.AddQuestProgress` is the only way to move a `ServerApi` objective —\nneither the client nor the dashboard can touch those. Use it when only the server\nknows the fact (anti-cheat verdict, match result, an external system confirming\nvia `server.HttpRequest`). Unlike the client's `addQuestProgress` it neither bans\nnor clamps on `MaxProgressPerCall`: the script is written by the title owner, so\nthe value is trusted. It still clamps to the objective's `TargetValue`. Quests\nwhose objectives use `ClientApi` or `SystemEvent` are unreachable from here.\n\n`log.Debug/Info/Warning/Error(message, data?)` records a line the publisher sees\n(and, if the title reveals logs, the client too). It costs no API budget.\n\nNotes that bite:\n\n- Bucket and scope names are **case-sensitive strings**: `\"Private\"`,\n  `\"Public\"`, `\"ReadOnly\"`, `\"Internal\"` for player data; `\"Public\"`,\n  `\"Private\"` for title data. Anything else comes back as an error result.\n- Title writes always land in the `Runtime` scope — the `Static` scope is\n  authored configuration and a script cannot touch it.\n- Shared counters must go through `IncrementTitleCustomData` (or\n  `SetTitleCustomData` with `expectedVersion` from the record you read).\n  Read-then-write from two concurrent calls silently loses one of them.\n- `throw` inside a handler is fine — it reaches the caller as a script-level\n  error with your message, which is usually what you want for \"not allowed\".\n\n### Calling another service\n\nA handler can call a third-party API. The credential never appears in your code:\nyou reference it by placeholder and the platform substitutes it after your script\nhas run, immediately before the request leaves.\n\n```js\nhandlers.notifyDiscord = function (args, context) {\n  var res = server.HttpRequest({\n    Method: \"POST\",\n    Url: \"https://discord.com/api/webhooks/{{var:DISCORD_WEBHOOK_PATH}}\",\n    Headers: { Authorization: \"Bearer {{secret:DISCORD_TOKEN}}\" },\n    Body: JSON.stringify({ content: \"Player \" + context.UserID + \" won!\" }),\n  });\n  if (!res.Success) throw new Error(res.Error); // network/policy failure\n  if (!res.Data.Ok) return { sent: false, status: res.Data.Status };\n  return { sent: true };\n};\n```\n\n- `{{secret:NAME}}` — an API key or token. **You can never read its value**, in\n  any tool or any call; there is no `GetSecret`. That is deliberate: a value in\n  JS could be returned to the player or logged by accident.\n- `{{var:NAME}}` — a non-secret setting. Also readable with\n  `server.GetIntegrationVariable(name)` when you need it as a value.\n- `res.Data` is `{ Status, Ok, Body, BodyTooLarge, ContentType }`. `Body` is a\n  string — parse it yourself; anything matching a substituted secret is replaced\n  with `***` before you see it.\n\nWhat the platform enforces, and what you cannot work around from a script:\n\n- **Only allow-listed hosts.** The publisher lists them per title; there is no\n  allow-all. An unlisted host fails with a clear message — surface it rather than\n  retrying.\n- **https only** (unless the title explicitly allows plain http), **no\n  redirects**, and no requests to private/loopback addresses.\n- **Per-execution request cap** (3 by default) and a **response size cap** — an\n  oversized body is dropped, not truncated, with `BodyTooLarge: true`.\n- The whole call still lives inside the 10-second execution budget, so one slow\n  integration can starve everything after it.\n\nIf the credential or the host you need does not exist yet, say exactly what has\nto be added in the title's **Integrations** settings — you cannot add either one.\n\n### Limits you are designing against\n\n10 seconds of wall-clock per call (hard, whatever the title configures), a cap\non statements and recursion depth, a cap on `server.*` calls per execution, and\nbyte ceilings on the returned result and the logs. Handlers are short decisions,\nnot jobs.\n\n### Schedules and incoming webhooks\n\nHandlers can also run **without a player**. Both are declared in the title\nconfig (`CloudCode.Schedules` / `CloudCode.Webhooks`, dashboard → Tools → Cloud\nfunctions) — not by publishing the script. At most 20 of each.\n\n- **Schedule** — runs a handler every `IntervalMinutes` (5 … 10080) from\n  `StartAtUtc` (empty = aligned to 00:00 UTC: 60 runs on the hour, 1440 at\n  midnight UTC) with `args = { Trigger: \"Schedule\", ScheduleID, ScheduledAtUtc, Args }`\n  (`Args` is the schedule's own JSON). There is no player session: pass user ids\n  explicitly to `server.*` calls that take one. One run per slot however many\n  servers there are; a slot missed during an outage is **not** replayed — make\n  the handler idempotent per `ScheduledAtUtc`.\n- **Incoming webhook** — `POST https://api.idosgames.com/api/v2/{titleID}/Public/CloudCode/Webhook/{id}`\n  runs a handler for an external service. The request is verified **before**\n  the handler runs with a title secret (kind Secret, from Integrations):\n  `HmacSha256` — hex HMAC-SHA256 of the raw body (optionally `sha256=`-prefixed)\n  in `X-Signature`; `Token` — the secret itself in `X-Webhook-Token` (the header\n  name is configurable). `args = { Trigger: \"Webhook\", WebhookID, Headers, Query, Body }`:\n  `Body` is the raw text (parse it yourself), header names are lower-case, and\n  the signature, `Authorization` and `Cookie` headers are removed. The return\n  value is the HTTP 200 body; a script error answers 500 so the sender retries —\n  make the handler idempotent by the event id. Unknown, disabled or badly signed\n  requests all get the same 401. Body ≤ 256 KB.\n\n```js\nhandlers.onPayment = function (args, context) {\n  var evt = JSON.parse(args.Body);\n  if (server.GetDataItem(\"payments\", evt.id).Success) return { ok: true }; // a retried delivery\n  var res = server.CreateDataItem(\"payments\", { type: evt.type }, evt.id);\n  if (!res.Success) throw new Error(res.Error); // 500 → the provider retries\n  return { ok: true };\n};\n```\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 cloudCode = client.cloudCode; // the CloudCodeService\n```\n\nRequires an authenticated session — without one, `execute` returns\n`{ ok: false, reason: \"unauthorized\" }` rather than making a request.\n\n## Methods\n\n`execute` returns `Promise<OperationResult<ExecuteCloudCodeResponse>>`: either\n`{ ok: true, data }` or `{ ok: false, reason, error }`. Always branch on\n`result.ok` before touching `result.data` — and then check `data.Error` before\ntrusting `data.FunctionResult` (see below). `reason` is one of `\"client\"`\n(empty/whitespace-only function name), `\"unauthorized\"`, `\"throttled\"` (fired\nthe same call again inside the throttle window), `\"connection\"` (transient,\noffer Retry), `\"validation\"` (response/schema drift), or `\"server\"`\n(infrastructure-level rejection — `error` carries the human-readable reason).\n\n| Method                                                                             | Purpose                                           | `data` on success          |\n| ---------------------------------------------------------------------------------- | ------------------------------------------------- | -------------------------- |\n| `execute(functionName, functionParameter?, revisionSelection?, specificRevision?)` | Run a title-defined cloud script handler by name. | `ExecuteCloudCodeResponse` |\n\nParameters:\n\n- `functionName` — the handler name inside the deployed script's `handlers`\n  object. Case-sensitive; trimmed before sending. Client-side, only\n  empty/whitespace is rejected (`reason: \"client\"`). Server-side, the backend\n  additionally rejects (as a script-level `InvalidFieldName` error, not an\n  `OperationResult` failure) names containing `.`, `$`, whitespace, or control\n  characters, or longer than 128 characters — these are illegal as MongoDB\n  field names since the name can end up in audit/log paths.\n- `functionParameter?` — any `JsonValue` (object, array, string, number,\n  boolean, or null) passed as the handler's first argument. Omit if the script\n  needs no input. If it's an object (at any nesting depth), none of its keys\n  may contain `.` or `$` — the backend rejects such payloads with a\n  script-level `InvalidFieldName` error before the script ever runs.\n- `revisionSelection?` — `\"Live\"` (default when omitted), `\"Latest\"`, or\n  `\"Specific\"`. Lets you target a non-live revision for testing.\n- `specificRevision?` — the revision number to run; only used when\n  `revisionSelection` is `\"Specific\"`.\n\n`ExecuteCloudCodeResponse` shape:\n\n| Field                    | Meaning                                                                                                                             |\n| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |\n| `FunctionName`           | Echo of the handler that ran.                                                                                                       |\n| `Revision`               | Which revision actually executed.                                                                                                   |\n| `FunctionResult`         | The script's return value — arbitrary JSON, `null` if it returned nothing or on error.                                              |\n| `FunctionResultTooLarge` | `true` if the result was dropped for exceeding the title's result-size limit (`FunctionResult` is `null` in that case).             |\n| `Logs`                   | Array of `{ Level, Message?, Data? }` entries from `log.debug/info/warn/error` calls inside the script.                             |\n| `LogsTooLarge`           | `true` if logs were truncated for exceeding the title's log-size limit.                                                             |\n| `ExecutionTimeSeconds`   | Server-side wall-clock execution duration.                                                                                          |\n| `APIRequestsIssued`      | Count of server API calls the script made internally (e.g. reading user data) — counts toward a per-execution cap.                  |\n| `Error`                  | `{ Error: CloudCodeErrorCode, Message?, StackTrace? }`, present only when the script failed or never ran; `null`/absent on success. |\n\n`CloudCodeErrorCode` values: `None`, `Disabled`, `NoActiveRevision`,\n`RevisionNotFound`, `InvalidFieldName`, `RateLimited`, `HandlerNotFound`,\n`HandlerDisabled`, `Timeout`, `StatementCountExceeded`, `StackOverflow`,\n`ApiCallLimitExceeded`, `JavaScriptException`, `ExecutionError` — stable, safe\nto switch on for retry/UX logic (e.g. treat `RateLimited`/`Timeout` as\nretryable, others as not).\n\nOn success, the SDK emits an event — it does **not** write anything into\n`client.data`, since the result shape is script-specific and there's no\ngeneric cache slot for it. If your script mutates player state (grants\ncurrency, items, etc. via server-side APIs), re-fetch that state through its\nowning module afterward — Cloud Code itself won't refresh your local cache.\n\n## Events\n\nSubscribe with `client.on(...)`; returns an unsubscribe fn.\n\n- `cloudCode:executed` → `ExecuteCloudCodeResponse` — fired whenever `execute` returns `{ ok: true }`, regardless of whether the script itself succeeded (check `data.Error` inside the handler).\n\n```ts\nconst off = client.on(\"cloudCode:executed\", (r) => {\n  if (r.Error) console.warn(\"script failed:\", r.Error.Error, r.Error.Message);\n});\n// later: off();\n```\n\n## Recipes\n\n### Call a script and handle both failure layers\n\n```ts\ninterface GrantBonusArgs {\n  reason: string;\n}\ninterface GrantBonusResult {\n  granted: number;\n}\n\nconst args: GrantBonusArgs = { reason: \"daily\" };\nconst result = await client.cloudCode.execute(\"grantLoginBonus\", args);\nif (!result.ok) return showError(result.error ?? result.reason); // infra-level failure\n\nif (result.data.Error) {\n  return showError(result.data.Error.Message ?? result.data.Error.Error); // script-level failure\n}\n\nconst payload = result.data.FunctionResult as GrantBonusResult; // your contract — cast/validate it yourself\nconsole.log(`granted ${payload.granted}`);\n```\n\n### Fire-and-forget script with no input\n\n```ts\nconst result = await client.cloudCode.execute(\"resetDailyQuests\");\nif (!result.ok || result.data.Error) {\n  console.warn(\"resetDailyQuests failed\", result.error ?? result.data.Error);\n}\n```\n\n### Test against a specific revision before it goes live\n\n```ts\nconst result = await client.cloudCode.execute(\n  \"computeMatchReward\",\n  { matchID },\n  \"Specific\",\n  42, // revision number\n);\n```\n\n### Surface script logs during development\n\n```ts\nconst result = await client.cloudCode.execute(\"debugScript\", { x: 1 });\nif (result.ok) {\n  for (const log of result.data.Logs ?? []) {\n    console.log(`[${log.Level}]`, log.Message, log.Data);\n  }\n}\n```\n\nLogs only come back at all if the title has logs enabled for clients; on\ntitles that don't, `Logs` is always an empty array even though the script did\nlog server-side — don't treat an empty array as proof the script logged\nnothing.\n\n### Chain a cloud-code call with a resource refresh\n\n```ts\nconst res = await client.cloudCode.execute(\"craftSpecialItem\", { recipeID });\nif (!res.ok || res.data.Error) return showError(res.error ?? res.data.Error);\n\n// The script granted items/currency server-side — Cloud Code didn't touch the\n// cache, so pull the owning module's state to see the new balance/inventory.\nawait client.user.getClientState(); // or the specific module's getter, e.g. client.item...\n```\n\n## Gotchas\n\n- **Two failure layers, don't conflate them.** `result.ok === false` means the\n  call itself failed (auth, bad args, connection) — the script never ran or\n  its outcome is unknown. `result.ok === true && result.data.Error` means the\n  call succeeded but the _script_ failed (threw, timed out, disabled,\n  unknown/undeclared handler, rate-limited) — always check both before\n  trusting `FunctionResult`.\n- **Unknown handler is a script-level error, not a client-side check.** The\n  SDK never validates that `functionName` refers to a real handler — that's\n  entirely server-side. Depending on the title's config you can get\n  `HandlerNotFound` either because the name isn't in the title's declared\n  handler whitelist, or because the deployed script simply never defined\n  `handlers[functionName]`; both look the same to the caller. A handler can\n  also be individually killed by an admin, which comes back as\n  `HandlerDisabled`.\n- **A hard 10-second ceiling always applies.** Whatever timeout the title/\n  revision configures, the backend clamps every single execution to a 10\n  second wall-clock budget; past that you get `Timeout` no matter what. Don't\n  design a script-based feature around long-running work.\n- **Rate limiting can hit independently of the generic per-endpoint throttle.**\n  Beyond the SDK's own ~600ms client-side throttle per call and the\n  transport's per-user rate limit, the title can configure CloudCode-specific\n  limits at three levels — whole title, this user, or this user+handler pair.\n  Any of them tripping comes back as `data.Error.Error === \"RateLimited\"`\n  (an in-band script-level outcome, `result.ok` is still `true`), with\n  `data.Error.Message` naming which layer triggered it — treat it as\n  retryable-after-a-delay, not a hard failure.\n- **No client-side validation of script logic.** The SDK only validates that\n  `functionName` is non-empty and that you're logged in. Argument shape,\n  business rules, and error handling are entirely up to the script — a\n  malformed `functionParameter` will fail server-side (`JavaScriptException`\n  or similar), not client-side.\n- **Type the payload and result yourself.** `functionParameter` is `JsonValue`\n  and `FunctionResult` is `JsonValue | null` — the SDK has no schema for your\n  title's specific scripts. Define your own request/response interfaces per\n  handler (as in the recipes above) and cast/validate after the call.\n- **Cloud Code doesn't touch `client.data`.** Unlike feature modules, a\n  successful `execute` doesn't mirror anything into the cache. If the script\n  changed player-facing state, re-fetch it via the owning module (e.g. call\n  the Economy/Item/Character module's getter) so the UI reflects it.\n- **`Logs`/`FunctionResult` can be silently dropped.** Both are subject to a\n  title-configured byte-size ceiling; check `LogsTooLarge` /\n  `FunctionResultTooLarge` before assuming absence means the script produced\n  nothing. Whether `Logs` is populated at all (even under the size limit) also\n  depends on a title setting — some titles never reveal script logs to\n  clients.\n- **Keys in your JSON payload can't contain `.` or `$`.** This is a MongoDB\n  field-name restriction the backend enforces recursively on\n  `functionParameter` (and on whatever the script returns) — a payload with a\n  dotted or `$`-prefixed key fails with `InvalidFieldName` before the script\n  even starts. Stick to plain alphanumeric/underscore keys.\n- **Never put a third-party key in game code.** The project ships to the\n  player's browser; a key there is a public key. The call belongs in a handler,\n  and the key belongs in the title's integration store.\n- **Treat an integration's response as untrusted.** Check `Status`, don't echo\n  the whole body back to the player, and never write an unvalidated field\n  straight into player data.\n- **Prefer a dedicated module when one exists.** Cloud Code has no typed\n  contract, no cache integration, and no per-feature event — reach for it only\n  when the feature genuinely isn't covered elsewhere.\n- **Publishing replaces everything.** A revision is the whole script: publish\n  one containing only your new handler and every other handler stops existing,\n  with the game getting `HandlerNotFound` at runtime and nothing failing at\n  build time. Always read the live source first and extend it.\n- **The handler whitelist is separate from the code.** A title can declare the\n  handlers it allows; a function that exists in the script but not in that list\n  is rejected with `HandlerNotFound`. When you add a handler to a title that\n  uses a whitelist, add it to the list in the same publish.\n",
+  "description": "Write and call custom server-side game logic on the iDosGames platform: author a CloudCode handler (sandboxed JavaScript with a server.* API) and invoke it from the game via client.cloudCode (CloudCodeService) with a JSON payload. Use this whenever the user wants bespoke or authoritative server logic — a \"cloud script\" or \"server callable\", granting rewards, validating a reported result, anti-cheat, writes to protected player data (UserCustomData ReadOnly / Internal) or shared title state (TitleCustomData Runtime) — or touches client.cloudCode, handlers, server.SetUserCustomData, server.HttpRequest or ExecuteCloudCodeResponse, even without naming the module. Also covers third-party integrations (external APIs with a stored key, outgoing and incoming webhooks, the {{secret:NAME}} / {{var:NAME}} placeholders) and scheduled handlers (daily resets, auction settlement).",
+  "content": "---\nname: cloud-code\ndescription: >-\n  Write and call custom server-side game logic on the iDosGames platform:\n  author a CloudCode handler (sandboxed JavaScript with a server.* API) and\n  invoke it from the game via client.cloudCode (CloudCodeService) with a JSON\n  payload. Use this whenever the user wants bespoke or authoritative server\n  logic — a \"cloud script\" or \"server callable\", granting rewards, validating a\n  reported result, anti-cheat, writes to protected player data (UserCustomData\n  ReadOnly / Internal) or shared title state (TitleCustomData Runtime) — or\n  touches client.cloudCode, handlers, server.SetUserCustomData,\n  server.HttpRequest or ExecuteCloudCodeResponse, even without naming the\n  module. Also covers third-party integrations (external APIs with a stored key,\n  outgoing and incoming webhooks, the {{secret:NAME}} / {{var:NAME}}\n  placeholders) and scheduled handlers (daily resets, auction settlement).\n---\n\n# Cloud Code (iDosGames TS SDK)\n\nCloud Code runs **your** JavaScript on the platform's servers. A script defines\nnamed handlers; the game calls one by name and gets back whatever JSON it\nreturns.\n\nTwo distinct reasons to reach for it:\n\n1. **Authority.** Client code that \"grants\" a reward, \"validates\" a score or\n   \"unlocks\" a level is a suggestion — the player owns the browser. Logic whose\n   outcome must be trusted belongs in a handler.\n2. **Protected data.** The `ReadOnly`/`Internal` buckets of a player's\n   UserCustomData and the `Runtime` scope of the title's data store have no\n   client write path at all. A handler is the only way to write them.\n\nIf a dedicated module already covers what you need (currency, item, store,\nquest, character, leaderboard…), prefer that module — it gives you typed\nrequest/response shapes and cache integration; Cloud Code gives you neither.\n\nPublishing a script is a platform operation, not an SDK one: the AI Coder does\nit with its `SaveCloudCode` tool, an external agent with the backend MCP's\n`publish_cloud_code`, and a publisher from the dashboard. Publishing **replaces\nthe whole revision** — read the current source first (`GetCloudCode` with\n`include_code`, or `get_cloud_code`) and send it back with your handler added,\nor you silently delete every handler the game still calls.\n\n## Mental model\n\nThere is exactly one client-facing action: `execute`. You pass a **function\nname** (a handler defined in the title's deployed script's `handlers` object)\nand an optional **arbitrary JSON payload**; the server runs it in a sandboxed\nJS engine and returns an arbitrary JSON result plus execution metadata (logs,\ntiming, error info). The SDK has no idea what a given script's args or result\nlook like — **you** know your title's script contract, so you type the\npayload and result yourself (see Gotchas). There's no \"config vs state\" split\nhere like other modules — Cloud Code has no persistent per-player data model\nof its own; it's pure request/response.\n\nScript failure is a **first-class outcome, not a network error**: if the\nscript throws, times out, is rate-limited, or the handler doesn't exist, the\ncall still comes back `{ ok: true, data }` with `data.Error` populated and\n`data.FunctionResult` empty. Only infrastructure problems (not logged in, bad\nlocal args, connection issues, backend down) surface as `{ ok: false }`.\n\n## Writing a handler\n\nA revision is one plain JavaScript file that fills the global `handlers` object.\nNo imports, no modules, no `async`/`await`, no `fetch` — everything you can touch\nis on `server.*` and `log.*`, and every call is synchronous. Outbound network\naccess exists but only through `server.HttpRequest`, and only to hosts the\npublisher allow-listed (see _Calling another service_).\n\n```js\nhandlers.claimDailyBonus = function (args, context) {\n  // context: { UserID, FunctionName, Revision, InvokedAt }\n  var data = server.GetUserCustomData();\n  if (!data.Success) throw new Error(data.Error);\n\n  var last = data.Data.ReadOnly[\"daily_claimed_at\"];\n  var today = new Date().toISOString().slice(0, 10);\n  if (last && last.Value === today)\n    return { granted: false, reason: \"already_claimed\" };\n\n  var write = server.SetUserCustomData(\"ReadOnly\", \"daily_claimed_at\", today);\n  if (!write.Success) throw new Error(write.Error);\n\n  server.IncrementTitleCustomData(\"Public\", \"daily_claims_total\", 1);\n  log.Info(\"daily bonus granted\", { user: context.UserID });\n  return { granted: true };\n};\n```\n\n### The `server.*` API\n\nEvery call returns `{ Success, Error, Data }` — **check `Success`**; a rejected\nwrite (limit hit, wrong bucket, version conflict) is a normal result, not a\nthrow. Each call also counts against the per-execution API budget, so batch.\n\n| Call                                                              | What it does                                                       |\n| ----------------------------------------------------------------- | ------------------------------------------------------------------ |\n| `server.ReadUserData([\"InventoryV2\", \"Premium\", …])`              | Read whitelisted sections of the caller's player document.         |\n| `server.GetTitleConfig(\"Currency\", \"Item\", …)`                    | Read the title's configuration sections.                           |\n| `server.GetUserCustomData()`                                      | All four buckets of the caller, **including `Internal`**.          |\n| `server.GetPublicUserCustomDataOf(userId)`                        | Another player's `Public` bucket.                                  |\n| `server.SetUserCustomData(bucket, key, value)`                    | Write any bucket — this is the protected-data write.               |\n| `server.DeleteUserCustomData(bucket, key)`                        | Delete a key from any bucket (idempotent).                         |\n| `server.BatchSetUserCustomData([{Bucket, KeyID, Value}, …])`      | Atomic multi-key write (all-or-nothing).                           |\n| `server.BatchDeleteUserCustomData([{Bucket, KeyID}, …])`          | Atomic multi-key delete.                                           |\n| `server.GetTitleCustomData()`                                     | Title store: both scopes, both buckets.                            |\n| `server.SetTitleCustomData(bucket, key, value, expectedVersion?)` | Write the title's `Runtime` scope; pass a version for CAS.         |\n| `server.IncrementTitleCustomData(bucket, key, delta)`             | Atomic counter on shared data — use this, never read-modify-write. |\n| `server.DeleteTitleCustomData(bucket, key)`                       | Delete a `Runtime` key.                                            |\n| `server.BatchSetTitleCustomData` / `BatchDeleteTitleCustomData`   | Atomic multi-key variants for the title store.                     |\n| `server.GetIntegrationVariable(name)`                             | Read a non-secret integration setting (base URL, account id).      |\n| `server.HttpRequest({ Method, Url, Headers, Body, ContentType })` | Call an external API — the only way out of the sandbox.            |\n| `server.AddQuestProgress(metricID, value)`                        | Advance quest objectives configured with `Source: \"ServerApi\"`.    |\n\n`server.AddQuestProgress` is the only way to move a `ServerApi` objective —\nneither the client nor the dashboard can touch those. Use it when only the server\nknows the fact (anti-cheat verdict, match result, an external system confirming\nvia `server.HttpRequest`). Unlike the client's `addQuestProgress` it neither bans\nnor clamps on `MaxProgressPerCall`: the script is written by the title owner, so\nthe value is trusted. It still clamps to the objective's `TargetValue`. Quests\nwhose objectives use `ClientApi` or `SystemEvent` are unreachable from here.\n\n`log.Debug/Info/Warning/Error(message, data?)` records a line the publisher sees\n(and, if the title reveals logs, the client too). It costs no API budget.\n\nNotes that bite:\n\n- Bucket and scope names are **case-sensitive strings**: `\"Private\"`,\n  `\"Public\"`, `\"ReadOnly\"`, `\"Internal\"` for player data; `\"Public\"`,\n  `\"Private\"` for title data. Anything else comes back as an error result.\n- Title writes always land in the `Runtime` scope — the `Static` scope is\n  authored configuration and a script cannot touch it.\n- Shared counters must go through `IncrementTitleCustomData` (or\n  `SetTitleCustomData` with `expectedVersion` from the record you read).\n  Read-then-write from two concurrent calls silently loses one of them.\n- `throw` inside a handler is fine — it reaches the caller as a script-level\n  error with your message, which is usually what you want for \"not allowed\".\n\n### Calling another service\n\nA handler can call a third-party API. The credential never appears in your code:\nyou reference it by placeholder and the platform substitutes it after your script\nhas run, immediately before the request leaves.\n\n```js\nhandlers.notifyDiscord = function (args, context) {\n  var res = server.HttpRequest({\n    Method: \"POST\",\n    Url: \"https://discord.com/api/webhooks/{{var:DISCORD_WEBHOOK_PATH}}\",\n    Headers: { Authorization: \"Bearer {{secret:DISCORD_TOKEN}}\" },\n    Body: JSON.stringify({ content: \"Player \" + context.UserID + \" won!\" }),\n  });\n  if (!res.Success) throw new Error(res.Error); // network/policy failure\n  if (!res.Data.Ok) return { sent: false, status: res.Data.Status };\n  return { sent: true };\n};\n```\n\n- `{{secret:NAME}}` — an API key or token. **You can never read its value**, in\n  any tool or any call; there is no `GetSecret`. That is deliberate: a value in\n  JS could be returned to the player or logged by accident.\n- `{{var:NAME}}` — a non-secret setting. Also readable with\n  `server.GetIntegrationVariable(name)` when you need it as a value.\n- `res.Data` is `{ Status, Ok, Body, BodyTooLarge, ContentType }`. `Body` is a\n  string — parse it yourself; anything matching a substituted secret is replaced\n  with `***` before you see it.\n\nWhat the platform enforces, and what you cannot work around from a script:\n\n- **Only allow-listed hosts.** The publisher lists them per title; there is no\n  allow-all. An unlisted host fails with a clear message — surface it rather than\n  retrying.\n- **https only** (unless the title explicitly allows plain http), **no\n  redirects**, and no requests to private/loopback addresses.\n- **Per-execution request cap** (3 by default) and a **response size cap** — an\n  oversized body is dropped, not truncated, with `BodyTooLarge: true`.\n- The whole call still lives inside the 10-second execution budget, so one slow\n  integration can starve everything after it.\n\nIf the credential or the host you need does not exist yet, say exactly what has\nto be added in the title's **Integrations** settings — you cannot add either one.\n\n### Limits you are designing against\n\n10 seconds of wall-clock per call (hard, whatever the title configures), a cap\non statements and recursion depth, a cap on `server.*` calls per execution, and\nbyte ceilings on the returned result and the logs. Handlers are short decisions,\nnot jobs.\n\n### Schedules and incoming webhooks\n\nHandlers can also run **without a player**. Both are declared in the title\nconfig (`CloudCode.Schedules` / `CloudCode.Webhooks`, dashboard → Tools → Cloud\nfunctions) — not by publishing the script. At most 20 of each.\n\n- **Schedule** — runs a handler every `IntervalMinutes` (5 … 10080) from\n  `StartAtUtc` (empty = aligned to 00:00 UTC: 60 runs on the hour, 1440 at\n  midnight UTC) with `args = { Trigger: \"Schedule\", ScheduleID, ScheduledAtUtc, Args }`\n  (`Args` is the schedule's own JSON). There is no player session: pass user ids\n  explicitly to `server.*` calls that take one. One run per slot however many\n  servers there are; a slot missed during an outage is **not** replayed — make\n  the handler idempotent per `ScheduledAtUtc`.\n- **Incoming webhook** — `POST https://api.idosgames.com/api/v2/{titleID}/Public/CloudCode/Webhook/{id}`\n  runs a handler for an external service. The request is verified **before**\n  the handler runs with a title secret (kind Secret, from Integrations):\n  `HmacSha256` — hex HMAC-SHA256 of the raw body (optionally `sha256=`-prefixed)\n  in `X-Signature`; `Token` — the secret itself in `X-Webhook-Token` (the header\n  name is configurable). `args = { Trigger: \"Webhook\", WebhookID, Headers, Query, Body }`:\n  `Body` is the raw text (parse it yourself), header names are lower-case, and\n  the signature, `Authorization` and `Cookie` headers are removed. The return\n  value is the HTTP 200 body; a script error answers 500 so the sender retries —\n  make the handler idempotent by the event id. Unknown, disabled or badly signed\n  requests all get the same 401. Body ≤ 256 KB.\n\n```js\nhandlers.onPayment = function (args, context) {\n  var evt = JSON.parse(args.Body);\n  if (server.GetDataItem(\"payments\", evt.id).Success) return { ok: true }; // a retried delivery\n  var res = server.CreateDataItem(\"payments\", { type: evt.type }, evt.id);\n  if (!res.Success) throw new Error(res.Error); // 500 → the provider retries\n  return { ok: true };\n};\n```\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 cloudCode = client.cloudCode; // the CloudCodeService\n```\n\nRequires an authenticated session — without one, `execute` returns\n`{ ok: false, reason: \"unauthorized\" }` rather than making a request.\n\n## Methods\n\n`execute` returns `Promise<OperationResult<ExecuteCloudCodeResponse>>`: either\n`{ ok: true, data }` or `{ ok: false, reason, error }`. Always branch on\n`result.ok` before touching `result.data` — and then check `data.Error` before\ntrusting `data.FunctionResult` (see below). `reason` is one of `\"client\"`\n(empty/whitespace-only function name), `\"unauthorized\"`, `\"throttled\"` (fired\nthe same call again inside the throttle window), `\"connection\"` (transient,\noffer Retry), `\"validation\"` (response/schema drift), or `\"server\"`\n(infrastructure-level rejection — `error` carries the human-readable reason).\n\n| Method                                                                             | Purpose                                           | `data` on success          |\n| ---------------------------------------------------------------------------------- | ------------------------------------------------- | -------------------------- |\n| `execute(functionName, functionParameter?, revisionSelection?, specificRevision?)` | Run a title-defined cloud script handler by name. | `ExecuteCloudCodeResponse` |\n\nParameters:\n\n- `functionName` — the handler name inside the deployed script's `handlers`\n  object. Case-sensitive; trimmed before sending. Client-side, only\n  empty/whitespace is rejected (`reason: \"client\"`). Server-side, the backend\n  additionally rejects (as a script-level `InvalidFieldName` error, not an\n  `OperationResult` failure) names containing `.`, `$`, whitespace, or control\n  characters, or longer than 128 characters — these are illegal as MongoDB\n  field names since the name can end up in audit/log paths.\n- `functionParameter?` — any `JsonValue` (object, array, string, number,\n  boolean, or null) passed as the handler's first argument. Omit if the script\n  needs no input. If it's an object (at any nesting depth), none of its keys\n  may contain `.` or `$` — the backend rejects such payloads with a\n  script-level `InvalidFieldName` error before the script ever runs.\n- `revisionSelection?` — `\"Live\"` (default when omitted), `\"Latest\"`, or\n  `\"Specific\"`. Lets you target a non-live revision for testing.\n- `specificRevision?` — the revision number to run; only used when\n  `revisionSelection` is `\"Specific\"`.\n\n`ExecuteCloudCodeResponse` shape:\n\n| Field                    | Meaning                                                                                                                             |\n| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |\n| `FunctionName`           | Echo of the handler that ran.                                                                                                       |\n| `Revision`               | Which revision actually executed.                                                                                                   |\n| `FunctionResult`         | The script's return value — arbitrary JSON, `null` if it returned nothing or on error.                                              |\n| `FunctionResultTooLarge` | `true` if the result was dropped for exceeding the title's result-size limit (`FunctionResult` is `null` in that case).             |\n| `Logs`                   | Array of `{ Level, Message?, Data? }` entries from `log.debug/info/warn/error` calls inside the script.                             |\n| `LogsTooLarge`           | `true` if logs were truncated for exceeding the title's log-size limit.                                                             |\n| `ExecutionTimeSeconds`   | Server-side wall-clock execution duration.                                                                                          |\n| `APIRequestsIssued`      | Count of server API calls the script made internally (e.g. reading user data) — counts toward a per-execution cap.                  |\n| `Error`                  | `{ Error: CloudCodeErrorCode, Message?, StackTrace? }`, present only when the script failed or never ran; `null`/absent on success. |\n\n`CloudCodeErrorCode` values: `None`, `Disabled`, `NoActiveRevision`,\n`RevisionNotFound`, `InvalidFieldName`, `RateLimited`, `HandlerNotFound`,\n`HandlerDisabled`, `Timeout`, `StatementCountExceeded`, `StackOverflow`,\n`ApiCallLimitExceeded`, `JavaScriptException`, `ExecutionError` — stable, safe\nto switch on for retry/UX logic (e.g. treat `RateLimited`/`Timeout` as\nretryable, others as not).\n\nOn success, the SDK emits an event — it does **not** write anything into\n`client.data`, since the result shape is script-specific and there's no\ngeneric cache slot for it. If your script mutates player state (grants\ncurrency, items, etc. via server-side APIs), re-fetch that state through its\nowning module afterward — Cloud Code itself won't refresh your local cache.\n\n## Events\n\nSubscribe with `client.on(...)`; returns an unsubscribe fn.\n\n- `cloudCode:executed` → `ExecuteCloudCodeResponse` — fired whenever `execute` returns `{ ok: true }`, regardless of whether the script itself succeeded (check `data.Error` inside the handler).\n\n```ts\nconst off = client.on(\"cloudCode:executed\", (r) => {\n  if (r.Error) console.warn(\"script failed:\", r.Error.Error, r.Error.Message);\n});\n// later: off();\n```\n\n## Recipes\n\n### Call a script and handle both failure layers\n\n```ts\ninterface GrantBonusArgs {\n  reason: string;\n}\ninterface GrantBonusResult {\n  granted: number;\n}\n\nconst args: GrantBonusArgs = { reason: \"daily\" };\nconst result = await client.cloudCode.execute(\"grantLoginBonus\", args);\nif (!result.ok) return showError(result.error ?? result.reason); // infra-level failure\n\nif (result.data.Error) {\n  return showError(result.data.Error.Message ?? result.data.Error.Error); // script-level failure\n}\n\nconst payload = result.data.FunctionResult as GrantBonusResult; // your contract — cast/validate it yourself\nconsole.log(`granted ${payload.granted}`);\n```\n\n### Fire-and-forget script with no input\n\n```ts\nconst result = await client.cloudCode.execute(\"resetDailyQuests\");\nif (!result.ok || result.data.Error) {\n  console.warn(\"resetDailyQuests failed\", result.error ?? result.data.Error);\n}\n```\n\n### Test against a specific revision before it goes live\n\n```ts\nconst result = await client.cloudCode.execute(\n  \"computeMatchReward\",\n  { matchID },\n  \"Specific\",\n  42, // revision number\n);\n```\n\n### Surface script logs during development\n\n```ts\nconst result = await client.cloudCode.execute(\"debugScript\", { x: 1 });\nif (result.ok) {\n  for (const log of result.data.Logs ?? []) {\n    console.log(`[${log.Level}]`, log.Message, log.Data);\n  }\n}\n```\n\nLogs only come back at all if the title has logs enabled for clients; on\ntitles that don't, `Logs` is always an empty array even though the script did\nlog server-side — don't treat an empty array as proof the script logged\nnothing.\n\n### Chain a cloud-code call with a resource refresh\n\n```ts\nconst res = await client.cloudCode.execute(\"craftSpecialItem\", { recipeID });\nif (!res.ok || res.data.Error) return showError(res.error ?? res.data.Error);\n\n// The script granted items/currency server-side — Cloud Code didn't touch the\n// cache, so pull the owning module's state to see the new balance/inventory.\nawait client.user.getClientState(); // or the specific module's getter, e.g. client.item...\n```\n\n## Gotchas\n\n- **Two failure layers, don't conflate them.** `result.ok === false` means the\n  call itself failed (auth, bad args, connection) — the script never ran or\n  its outcome is unknown. `result.ok === true && result.data.Error` means the\n  call succeeded but the _script_ failed (threw, timed out, disabled,\n  unknown/undeclared handler, rate-limited) — always check both before\n  trusting `FunctionResult`.\n- **Unknown handler is a script-level error, not a client-side check.** The\n  SDK never validates that `functionName` refers to a real handler — that's\n  entirely server-side. Depending on the title's config you can get\n  `HandlerNotFound` either because the name isn't in the title's declared\n  handler whitelist, or because the deployed script simply never defined\n  `handlers[functionName]`; both look the same to the caller. A handler can\n  also be individually killed by an admin, which comes back as\n  `HandlerDisabled`.\n- **A hard 10-second ceiling always applies.** Whatever timeout the title/\n  revision configures, the backend clamps every single execution to a 10\n  second wall-clock budget; past that you get `Timeout` no matter what. Don't\n  design a script-based feature around long-running work.\n- **Rate limiting can hit independently of the generic per-endpoint throttle.**\n  Beyond the SDK's own ~600ms client-side throttle per call and the\n  transport's per-user rate limit, the title can configure CloudCode-specific\n  limits at three levels — whole title, this user, or this user+handler pair.\n  Any of them tripping comes back as `data.Error.Error === \"RateLimited\"`\n  (an in-band script-level outcome, `result.ok` is still `true`), with\n  `data.Error.Message` naming which layer triggered it — treat it as\n  retryable-after-a-delay, not a hard failure.\n- **No client-side validation of script logic.** The SDK only validates that\n  `functionName` is non-empty and that you're logged in. Argument shape,\n  business rules, and error handling are entirely up to the script — a\n  malformed `functionParameter` will fail server-side (`JavaScriptException`\n  or similar), not client-side.\n- **Type the payload and result yourself.** `functionParameter` is `JsonValue`\n  and `FunctionResult` is `JsonValue | null` — the SDK has no schema for your\n  title's specific scripts. Define your own request/response interfaces per\n  handler (as in the recipes above) and cast/validate after the call.\n- **Cloud Code doesn't touch `client.data`.** Unlike feature modules, a\n  successful `execute` doesn't mirror anything into the cache. If the script\n  changed player-facing state, re-fetch it via the owning module (e.g. call\n  the Economy/Item/Character module's getter) so the UI reflects it.\n- **`Logs`/`FunctionResult` can be silently dropped.** Both are subject to a\n  title-configured byte-size ceiling; check `LogsTooLarge` /\n  `FunctionResultTooLarge` before assuming absence means the script produced\n  nothing. Whether `Logs` is populated at all (even under the size limit) also\n  depends on a title setting — some titles never reveal script logs to\n  clients.\n- **Keys in your JSON payload can't contain `.` or `$`.** This is a MongoDB\n  field-name restriction the backend enforces recursively on\n  `functionParameter` (and on whatever the script returns) — a payload with a\n  dotted or `$`-prefixed key fails with `InvalidFieldName` before the script\n  even starts. Stick to plain alphanumeric/underscore keys.\n- **Never put a third-party key in game code.** The project ships to the\n  player's browser; a key there is a public key. The call belongs in a handler,\n  and the key belongs in the title's integration store.\n- **Treat an integration's response as untrusted.** Check `Status`, don't echo\n  the whole body back to the player, and never write an unvalidated field\n  straight into player data.\n- **Prefer a dedicated module when one exists.** Cloud Code has no typed\n  contract, no cache integration, and no per-feature event — reach for it only\n  when the feature genuinely isn't covered elsewhere.\n- **Publishing replaces everything.** A revision is the whole script: publish\n  one containing only your new handler and every other handler stops existing,\n  with the game getting `HandlerNotFound` at runtime and nothing failing at\n  build time. Always read the live source first and extend it.\n- **The handler whitelist is separate from the code.** A title can declare the\n  handlers it allows; a function that exists in the script but not in that list\n  is rejected with `HandlerNotFound`. When you add a handler to a title that\n  uses a whitelist, add it to the list in the same publish.\n",
   "references": []
 }

package/registry/skills/currency-system.json

@@ -5,7 +5,7 @@
   "references": [
     {
       "path": "data-model.md",
-      "content": "# Currency data model — reference\n\nFull shape of the `CurrencyDefinitions` config, and — the canonical\ndocumentation for the whole SDK — the shared `ResourceConsume` /\n`ResourceGrant` / `ResourceOperation` / `ResourceEntry` cost-and-reward\nprimitives. All types are **strictly typed** and exported from\n`@idosgames/core`; every object schema keeps `.passthrough()`, so a field the\nbackend adds later still round-trips instead of being stripped. Field names\nare PascalCase (straight from the backend JSON).\n\n## Contents\n\n- [Config: CurrencyDefinitions](#config-currencydefinitions)\n- [VirtualCurrencyDefinition](#virtualcurrencydefinition)\n- [CryptoCurrencyDefinition](#cryptocurrencydefinition)\n- [Shared conversion config](#shared-conversion-config)\n- [Backend conversion formulas](#backend-conversion-formulas) — transcribed from `ConversionService.cs`\n- [The shared resource primitives](#the-shared-resource-primitives) — canonical home\n  - [ResourceEntry](#resourceentry)\n  - [ResourceBundle](#resourcebundle)\n  - [PremiumTierBundle](#premiumtierbundle)\n  - [ResourceGrant](#resourcegrant)\n  - [ResourceConsume](#resourceconsume)\n  - [ResourceOperation](#resourceoperation)\n  - [EventTokenOperation / EventTokenAddress](#eventtokenoperation--eventtokenaddress)\n  - [ResourceDualPartyResult / ResourceTransferResult](#resourcedualpartyresult--resourcetransferresult)\n- [How the SDK applies a ResourceOperation](#how-the-sdk-applies-a-resourceoperation)\n\n---\n\n## Config: CurrencyDefinitions\n\n```ts\ninterface CurrencyDefinitions {\n  VirtualCurrencies?: Record<string, VirtualCurrencyDefinition> | null;\n  CryptoCurrencies?: Record<string, CryptoCurrencyDefinition> | null;\n  CryptoRewardsFromDeveloperShare?: boolean; // top up unbacked crypto rewards from the developer share (off by default; otherwise the IOU is granted)\n  CryptoIouForScriptsAndAI?: boolean; // CloudCode / AI rewards also fall back to the IOU instead of refusing (off by default)\n  CryptoAutoRepayIouOnWithdrawal?: boolean; // repay IOUs on withdrawal from the players' reward pool, only the missing part (absent = on)\n}\n```\n\nKey in both maps is the `CurrencyID`. A currency is \"known\" iff it has an\nentry in one of these maps under its `CurrencyType` (`Virtual` or `Crypto`).\n\n---\n\n## VirtualCurrencyDefinition\n\n```ts\ninterface VirtualCurrencyDefinition {\n  CurrencyID: string;\n  DisplayName?: string;\n  AssetPaths?: Record<string, string>; // \"icon\", ...\n  Economy?: {\n    ValueInUSD?: string; // decimal string\n    ValueInUSDUpdatedAt?: string; // ISO timestamp\n    InitialDeposit?: number; // starting balance for new players\n    MinBalance?: number;\n    MaxBalance?: number;\n    DailyEarnLimit?: number;\n    DailySpendLimit?: number;\n  };\n  Recharge?: {\n    // Energy-style auto-regen, credited in BATCHES: every FULL `Period` seconds the\n    // player gets `Rate` units at once, up to `Max`. Rate=5/Period=60 means \"+5 once a\n    // minute\", NOT \"+1 every 12 seconds\" — an incomplete period credits nothing.\n    // The batch is clipped exactly at `Max` (if less than Rate is missing, only the\n    // remainder is credited); at or above `Max` nothing is credited.\n    // `Max` is the auto-recharge cap only — explicit grants may exceed it, up to\n    // Economy.MaxBalance.\n    Rate?: number;\n    Max?: number;\n    Period?: number;\n  };\n  Conversion?: CurrencyConversion; // see below\n  Permissions?: {\n    IsTradable?: boolean;\n    IsPurchasable?: boolean;\n    IsRefundable?: boolean;\n  };\n  Audit?: { CreatedAt?: string; UpdatedAt?: string };\n  Status?: \"Active\" | \"Hidden\" | \"Deprecated\" | \"Maintenance\";\n}\n```\n\n`Status` governs whether the currency is usable/visible; `\"Maintenance\"` /\n`\"Deprecated\"` currencies typically reject conversions server-side even if\n`Conversion.Enabled` is true.\n\n---\n\n## CryptoCurrencyDefinition\n\n```ts\ninterface CryptoCurrencyDefinition {\n  CurrencyID: string;\n  DisplayName?: string;\n  AssetPaths?: Record<string, string>;\n  DisplayDecimals?: number; // UI rounding, not wire precision\n  ValueInUSD?: string; // decimal string\n  ValueInUSDUpdatedAt?: string;\n  DeveloperWithdrawalFeePercent?: string; // decimal string; fee on PLAYER withdrawal, see blockchain-system\n  CommunityMarketingWithdrawalFeePercent?: string; // decimal string; fee on PLAYER withdrawal\n  UnbackedRewardCurrencyID?: string; // IOU virtual currency: unbacked part of a crypto reward arrives in it 1:1; spent first when this crypto is spent\n  Networks?: CryptoNetworkBinding[]; // per-chain bindings\n  Limits?: {\n    DailyWithdrawUsd?: string;\n    MonthlyWithdrawUsd?: string;\n    KycRequiredAboveUsd?: string;\n  };\n  Permissions?: {\n    DepositsEnabled?: boolean;\n    WithdrawalsEnabled?: boolean;\n    SpendableInGame?: boolean;\n    ConvertibleToVirtual?: boolean; // gates cryptoConvert eligibility\n  };\n  Conversion?: CurrencyConversion;\n  Audit?: { CreatedAt?: string; UpdatedAt?: string };\n  Status?: \"Active\" | \"Hidden\" | \"Deprecated\" | \"Maintenance\";\n}\n\ninterface CryptoNetworkBinding {\n  NetworkID: string;\n  ContractAddress?: string;\n  Decimals?: number; // on-chain token decimals\n  MinWithdraw?: string;\n  DepositsEnabled?: boolean;\n  WithdrawalsEnabled?: boolean;\n}\n```\n\nDeposit/withdrawal flows (and `Networks`/`Limits` enforcement for those flows)\nbelong to the Blockchain module — see the blockchain-system skill.\n`Permissions.ConvertibleToVirtual` is the flag most relevant here: it's what\nlets a crypto balance participate in `cryptoConvert`.\n\n---\n\n## Shared conversion config\n\nBoth currency kinds reuse the same `CurrencyConversion` shape for their\n`Conversion` field:\n\n```ts\ninterface CurrencyConversion {\n  Enabled?: boolean;\n  RateMode?: \"Automatic\" | \"Manual\";\n  Fee?: number; // SHARE of the debited amount: 0.05 = 5% (never 0..100)\n  Targets?: ConversionTarget[]; // whitelist of valid conversion targets\n}\n\ninterface ConversionTarget {\n  TargetCurrencyType?: \"Virtual\" | \"Crypto\";\n  TargetCurrencyID: string;\n  Rate?: string; // decimal string; used when RateMode is \"Manual\"\n  MinAmount?: number;\n  MaxAmount?: number;\n  DailyLimit?: number;\n}\n```\n\nA conversion is only accepted if the source currency's `Conversion.Enabled`\nis true and the target appears in `Targets` (by type + id). `\"Automatic\"`\nrate mode means the backend derives the rate from each side's `ValueInUSD`;\n`\"Manual\"` uses the `Rate` pinned on the `ConversionTarget`. Either way, treat\n`RateApplied` on the response as the source of truth — don't recompute it.\n\n---\n\n## Backend conversion formulas\n\nTranscribed from `ConversionService.ConvertAsync` /\n`ConversionService.ConvertCryptoAsync` in the backend\n(`IDosGamesSDK/API/Client/v2/Currency/Services/ConversionService.cs`). These\nare enforced server-side; the SDK never recomputes them — use this section\nonly for building accurate cost/reward **previews**, not for validating a\nconversion before sending it.\n\n**Order of checks** (any failure short-circuits, no partial debit):\n\n1. Basic shape: non-empty `SourceID`/`TargetID`, positive amount, source ≠\n   target.\n2. `Convert` (VC↔VC) rejects a `Crypto` source outright (\"Convert supports\n   VC↔VC only\") and a `Crypto` target outright (\"Virtual→Crypto conversion is\n   not supported\"). `CryptoConvert` rejects a non-`Crypto` source outright\n   (\"CryptoConvert requires source to be Crypto\").\n3. **Status**: source or target `Maintenance` → rejected on that side (\"is\n   under maintenance\"). Target (only) `Deprecated` → rejected (\"is deprecated\n   and cannot receive new credits\"). A `Deprecated` **source** is allowed —\n   deprecating a currency only stops new inflow, it doesn't trap the player's\n   remaining balance.\n4. Source's `Conversion` must be non-null and `Enabled`, and must have a\n   `Targets` entry matching `(TargetCurrencyType, TargetCurrencyID)` exactly —\n   otherwise \"Conversion from 'X' to 'Y' is not allowed.\"\n5. Crypto-source → Virtual-target additionally requires\n   `CryptoCurrencyPermissions.ConvertibleToVirtual` — false rejects even a\n   listed target.\n6. Per-pair `MinAmount`/`MaxAmount` on the matched `ConversionTarget`, checked\n   against the raw source amount before fee.\n7. **Rate resolution**:\n   - `RateMode = Manual` → `rate = ConversionTarget.Rate`; a pair configured\n     Manual with no `Rate` set is rejected (\"Manual conversion rate is not set\n     for this pair\"), not treated as 0 or 1.\n   - `RateMode = Automatic` → `rate = source.ValueInUSD / target.ValueInUSD`.\n     Either side missing/zero `ValueInUSD` rejects the conversion (\"Automatic\n     rate cannot be computed\").\n8. **Fee**: `Fee` is a SHARE (`0.05` = 5%), so `feeAmount = sourceAmount * Fee`\n   — there is no division by 100. It is **not** clamped to a range: only `NaN`\n   is treated as zero, and the fee is capped at the source amount itself. On the\n   VC→VC path a fee below `1.0` additionally leaves at least one unit\n   (`MaxPerPosition = sourceAmount - 1`), so that rounding alone can never make\n   a small conversion impossible; `Fee = 1.0` is a deliberate ban and keeps its\n   full effect. `netSource = sourceAmount - feeAmount`; `netSource <= 0` is\n   rejected.\n9. **Output**: `output = netSource * rate`.\n   - VC↔VC (`ConvertAsync`): `output` is cast straight to `long`, i.e.\n     **truncated toward zero**. `output <= 0` after truncation is rejected\n     (\"Resulting target amount is zero\").\n   - Crypto-source (`ConvertCryptoAsync`): `output` stays a full-precision\n     `decimal` if the target is `Crypto`. If the target is `Virtual`, it is\n     **floored** (`Math.Floor`) to a `long` before the zero-check.\n10. Per-pair `DailyLimit` on the matched `ConversionTarget`: today's\n    already-converted amount for this exact `(SourceType:SourceID ->\nTargetType:TargetID)` pair (tracked server-side per UTC day; not exposed\n    to the client) plus this operation's raw source amount must not exceed\n    it.\n11. The debit/credit itself runs through `ResourceService\n.ApplyResourceOperationAtomicAsync`, which additionally enforces the\n    source currency's own `Economy.MinBalance`/`MaxBalance` (for VC) and\n    `Economy.DailyEarnLimit`/`DailySpendLimit` — a **second, independent**\n    limit layer scoped to the whole currency rather than this one pair. A\n    crypto source's live balance is checked directly against\n    `InventoryV2.CryptoCurrencies[id].Amount` before the debit.\n\n**Practical takeaway**: two conversions that look identical (same pair, same\namount) can differ in outcome depending on how much of the _daily_ pair\nallowance or the _daily_ currency-wide allowance is already used — always\nrender the server's `error` rather than trying to precompute eligibility.\n\n---\n\n## The shared resource primitives\n\nThis is the **canonical documentation** for these types — every other module\nskill (Store, Character, Craft, Lootbox, Blockchain, …) links here instead of\nredefining them. They describe \"spend this, receive that\" in one uniform\nshape used for offer costs, upgrade costs, craft inputs/outputs, lootbox\nprices/rewards, and blockchain deposit/withdrawal resource deltas.\n\n### ResourceEntry\n\nThe atomic unit: one currency or item quantity.\n\n```ts\ninterface ResourceEntry {\n  Type?:\n    | \"Item\"\n    | \"VirtualCurrency\"\n    | \"CryptoCurrency\"\n    | \"Purchase\"\n    | \"RewardedVideoCredit\"; // ResourceEntryType\n  CurrencyID?: string; // set when Type is a currency kind\n  Amount?: number; // integer amount; C# `long` on the wire, parsed via zVcAmount (exact up to 2^53-1)\n  CatalogID?: string; // set when Type is \"Item\": which catalog\n  ItemID?: string; // set when Type is \"Item\": which item definition\n  ProductID?: string; // set when Type is \"Purchase\": the IAP product that pays for this entry\n}\n```\n\nOnly the fields relevant to `Type` are populated — e.g. a `VirtualCurrency`\nentry sets `CurrencyID` + `Amount` and leaves `CatalogID`/`ItemID` unset; an\n`Item` entry sets `CatalogID`/`ItemID` (+ `Amount` for stackable quantity) and\nleaves `CurrencyID` unset.\n\n### ResourceBundle\n\nA flat list of entries, plus optional event-token deltas:\n\n```ts\ninterface ResourceBundle {\n  Entries?: ResourceEntry[] | null;\n  EventTokens?: EventTokenOperation[] | null;\n}\n```\n\n### PremiumTierBundle\n\nAn alternate bundle that only applies if the player holds a qualifying\npremium tier — used inside `ResourceGrant`/`ResourceConsume` to express\n\"VIPs get a better grant / a cheaper cost.\"\n\n```ts\ninterface PremiumTierBundle {\n  MinPremiumTier?: number;\n  RequiredPremiumID?: string;\n  Resources?: ResourceBundle | null;\n}\n```\n\n### ResourceGrant\n\nWhat a player receives.\n\n```ts\ninterface ResourceGrant {\n  Standard?: ResourceBundle | null; // baseline grant, always applies\n  PremiumBonuses?: unknown[] | null; // reserved/opaque bonus list\n  PremiumTiers?: PremiumTierBundle[] | null; // tier-gated additional/alternate grants\n}\n```\n\n### ResourceConsume\n\nWhat a player is charged. Mirror-shaped to `ResourceGrant`, but the\ntier-based array is a **discount** mechanism rather than a bonus one — see\nGotchas below.\n\n```ts\ninterface ResourceConsume {\n  Standard?: ResourceBundle | null; // baseline cost\n  PremiumDiscounts?: unknown[] | null; // reserved/opaque discount list\n  PremiumTiers?: PremiumTierBundle[] | null; // tier-gated reduced/alternate cost\n}\n```\n\n### ResourceOperation\n\nThe full manifest for one action: what's granted and what's consumed. This is\nthe shape every \"did an action succeed\" response embeds under a `Resources`\nfield (e.g. `DepositNFTResponse.Resources`, `NFTWithdrawalResponse.Resources`\nin Blockchain).\n\n```ts\ninterface ResourceOperation {\n  Grant?: ResourceGrant | null;\n  Consume?: ResourceConsume | null;\n}\n```\n\nEither side can be `null`/absent — a pure grant (no cost) sets only `Grant`;\na pure charge (no payout) sets only `Consume`.\n\n### EventTokenOperation / EventTokenAddress\n\nEvent tokens are a lighter-weight counter mechanic (e.g. season/event\ncurrency) addressed by an entity rather than a flat `CurrencyID`:\n\n```ts\ninterface EventTokenAddress {\n  Type?: string; // EventTokenType — which kind of entity owns the token bucket\n  EntityID: string;\n}\n\ninterface EventTokenOperation {\n  Address?: EventTokenAddress | null;\n  Amount?: number;\n  Source?: string; // free-form provenance tag\n}\n```\n\n### ResourceDualPartyResult / ResourceTransferResult\n\nUsed by PvP/transfer-style features where two accounts are affected by one\naction:\n\n```ts\n// Each side gets its own independent grant/consume manifest.\ninterface ResourceDualPartyResult {\n  FromUserID?: string;\n  ToUserID?: string;\n  FromResult?: ResourceOperation | null;\n  ToResult?: ResourceOperation | null;\n}\n\n// A straight transfer: one bundle moves from one account to another.\ninterface ResourceTransferResult {\n  FromUserID?: string;\n  ToUserID?: string;\n  Transferred?: ResourceBundle | null;\n}\n```\n\n---\n\n## How the SDK applies a ResourceOperation\n\nEvery module that returns a `ResourceOperation` (directly, or via a\n`Resources` field) has already had it **applied server-side**; the SDK's job\nis only to mirror it into the local cache so balances/inventory read\ncorrectly without a re-fetch. Internally this goes through\n`UserData.applyResourceOperation(op, itemDefs)`, which:\n\n- walks `Consume.Standard.Entries` and `Grant.Standard.Entries` (the\n  `PremiumDiscounts`/`PremiumTiers`/`PremiumBonuses` arrays describe _why_ the\n  standard amount is what it is — the server has already resolved them into\n  `Standard` before sending the response; the client does not re-apply tiers),\n- for `VirtualCurrency` entries, adjusts the integer balance and emits\n  `user:virtualCurrencyUpdated`,\n- for `Item` entries, adjusts stackable counts / creates unstackable instances\n  and emits `user:inventoryUpdated`,\n- for `EventTokens`, adjusts the addressed token bucket and emits\n  `user:eventTokenUpdated`,\n- always emits the umbrella `user:anyUpdated` when anything changed.\n\n`CryptoCurrency` amounts do **not** flow through this integer pipeline —\nthey're decimal and go through a separate patch\n(`UserData.patchCryptoCurrencyDelta(currencyID, delta, serverTimeUtc)`), which\nis what `CurrencyService.cryptoConvert` and the Blockchain deposit/withdrawal\nmethods use directly instead of embedding crypto deltas in a\n`ResourceOperation`.\n\n**Practical takeaway when building UI in any module:** don't hand-roll cost\npreviews from `PremiumDiscounts`/`PremiumTiers` internals unless you're\nexplicitly building a \"your VIP tier saves you N%\" comparison — for \"what will\nthis cost me right now,\" prefer the value the server already resolved\n(`Standard`, or the flat response fields like `ConvertResponse.SourceSpent`).\nTreat `Amount` on VC entries as a signed integer conceptually (consume vs.\ngrant is which container it's in, not a negative number) and crypto strings as\nopaque decimal values to hand to `decimal.js`, not to parse with `Number()`\nonce you're near precision limits.\n"
+      "content": "# Currency data model — reference\n\nFull shape of the `CurrencyDefinitions` config, and — the canonical\ndocumentation for the whole SDK — the shared `ResourceConsume` /\n`ResourceGrant` / `ResourceOperation` / `ResourceEntry` cost-and-reward\nprimitives. All types are **strictly typed** and exported from\n`@idosgames/core`; every object schema keeps `.passthrough()`, so a field the\nbackend adds later still round-trips instead of being stripped. Field names\nare PascalCase (straight from the backend JSON).\n\n## Contents\n\n- [Config: CurrencyDefinitions](#config-currencydefinitions)\n- [VirtualCurrencyDefinition](#virtualcurrencydefinition)\n- [CryptoCurrencyDefinition](#cryptocurrencydefinition)\n- [Shared conversion config](#shared-conversion-config)\n- [Backend conversion formulas](#backend-conversion-formulas) — transcribed from `ConversionService.cs`\n- [The shared resource primitives](#the-shared-resource-primitives) — canonical home\n  - [ResourceEntry](#resourceentry)\n  - [ResourceBundle](#resourcebundle)\n  - [PremiumTierBundle](#premiumtierbundle)\n  - [ResourceGrant](#resourcegrant)\n  - [ResourceConsume](#resourceconsume)\n  - [ResourceOperation](#resourceoperation)\n  - [EventTokenOperation / EventTokenAddress](#eventtokenoperation--eventtokenaddress)\n  - [ResourceDualPartyResult / ResourceTransferResult](#resourcedualpartyresult--resourcetransferresult)\n- [How the SDK applies a ResourceOperation](#how-the-sdk-applies-a-resourceoperation)\n\n---\n\n## Config: CurrencyDefinitions\n\n```ts\ninterface CurrencyDefinitions {\n  VirtualCurrencies?: Record<string, VirtualCurrencyDefinition> | null;\n  CryptoCurrencies?: Record<string, CryptoCurrencyDefinition> | null;\n  CryptoRewardsFromDeveloperShare?: boolean; // top up unbacked crypto rewards from the developer share (off by default; otherwise the IOU is granted)\n  CryptoIouForScriptsAndAI?: boolean; // CloudCode / AI rewards also fall back to the IOU instead of refusing (off by default)\n  CryptoAutoRepayIouOnWithdrawal?: boolean; // repay IOUs on withdrawal from the players' reward pool, only the missing part (absent = on)\n}\n```\n\nKey in both maps is the `CurrencyID`. A currency is \"known\" iff it has an\nentry in one of these maps under its `CurrencyType` (`Virtual` or `Crypto`).\n\n---\n\n## VirtualCurrencyDefinition\n\n```ts\ninterface VirtualCurrencyDefinition {\n  CurrencyID: string;\n  DisplayName?: string;\n  AssetPaths?: Record<string, string>; // \"icon\", ...\n  Economy?: {\n    ValueInUSD?: string; // decimal string\n    ValueInUSDUpdatedAt?: string; // ISO timestamp\n    InitialDeposit?: number; // starting balance for new players\n    MinBalance?: number;\n    MaxBalance?: number;\n    DailyEarnLimit?: number;\n    DailySpendLimit?: number;\n  };\n  Recharge?: {\n    // Energy-style auto-regen, credited in BATCHES: every FULL `Period` seconds the\n    // player gets `Rate` units at once, up to `Max`. Rate=5/Period=60 means \"+5 once a\n    // minute\", NOT \"+1 every 12 seconds\" — an incomplete period credits nothing.\n    // The batch is clipped exactly at `Max` (if less than Rate is missing, only the\n    // remainder is credited); at or above `Max` nothing is credited.\n    // `Max` is the auto-recharge cap only — explicit grants may exceed it, up to\n    // Economy.MaxBalance.\n    Rate?: number;\n    Max?: number;\n    Period?: number;\n  };\n  Conversion?: CurrencyConversion; // see below\n  Permissions?: {\n    IsTradable?: boolean;\n    IsPurchasable?: boolean;\n    IsRefundable?: boolean;\n  };\n  Audit?: { CreatedAt?: string; UpdatedAt?: string };\n  Status?: \"Active\" | \"Hidden\" | \"Deprecated\" | \"Maintenance\";\n}\n```\n\n`Status` governs whether the currency is usable/visible; `\"Maintenance\"` /\n`\"Deprecated\"` currencies typically reject conversions server-side even if\n`Conversion.Enabled` is true.\n\n---\n\n## CryptoCurrencyDefinition\n\n```ts\ninterface CryptoCurrencyDefinition {\n  CurrencyID: string;\n  DisplayName?: string;\n  AssetPaths?: Record<string, string>;\n  DisplayDecimals?: number; // UI rounding, not wire precision\n  ValueInUSD?: string; // decimal string\n  ValueInUSDUpdatedAt?: string;\n  DeveloperWithdrawalFeePercent?: string; // decimal string; fee on PLAYER withdrawal, see blockchain-system\n  CommunityMarketingWithdrawalFeePercent?: string; // decimal string; fee on PLAYER withdrawal\n  PlayerTradeFeePercent?: string; // decimal string, 0–50; developer's fee on crypto moving BETWEEN players (marketplace sale, PvP win, Workshop author sale). In-game prices are not affected: spent crypto goes to the developer in full\n  UnbackedRewardCurrencyID?: string; // IOU virtual currency: unbacked part of a crypto reward arrives in it 1:1; spent first when this crypto is spent\n  Networks?: CryptoNetworkBinding[]; // per-chain bindings\n  Limits?: {\n    DailyWithdrawUsd?: string;\n    MonthlyWithdrawUsd?: string;\n    KycRequiredAboveUsd?: string;\n  };\n  Permissions?: {\n    DepositsEnabled?: boolean;\n    WithdrawalsEnabled?: boolean;\n    SpendableInGame?: boolean;\n    ConvertibleToVirtual?: boolean; // gates cryptoConvert eligibility\n  };\n  Conversion?: CurrencyConversion;\n  Audit?: { CreatedAt?: string; UpdatedAt?: string };\n  Status?: \"Active\" | \"Hidden\" | \"Deprecated\" | \"Maintenance\";\n}\n\ninterface CryptoNetworkBinding {\n  NetworkID: string;\n  ContractAddress?: string;\n  Decimals?: number; // on-chain token decimals\n  MinWithdraw?: string;\n  DepositsEnabled?: boolean;\n  WithdrawalsEnabled?: boolean;\n}\n```\n\nDeposit/withdrawal flows (and `Networks`/`Limits` enforcement for those flows)\nbelong to the Blockchain module — see the blockchain-system skill.\n`Permissions.ConvertibleToVirtual` is the flag most relevant here: it's what\nlets a crypto balance participate in `cryptoConvert`.\n\n---\n\n## Shared conversion config\n\nBoth currency kinds reuse the same `CurrencyConversion` shape for their\n`Conversion` field:\n\n```ts\ninterface CurrencyConversion {\n  Enabled?: boolean;\n  RateMode?: \"Automatic\" | \"Manual\";\n  Fee?: number; // SHARE of the debited amount: 0.05 = 5% (never 0..100)\n  Targets?: ConversionTarget[]; // whitelist of valid conversion targets\n}\n\ninterface ConversionTarget {\n  TargetCurrencyType?: \"Virtual\" | \"Crypto\";\n  TargetCurrencyID: string;\n  Rate?: string; // decimal string; used when RateMode is \"Manual\"\n  MinAmount?: number;\n  MaxAmount?: number;\n  DailyLimit?: number;\n}\n```\n\nA conversion is only accepted if the source currency's `Conversion.Enabled`\nis true and the target appears in `Targets` (by type + id). `\"Automatic\"`\nrate mode means the backend derives the rate from each side's `ValueInUSD`;\n`\"Manual\"` uses the `Rate` pinned on the `ConversionTarget`. Either way, treat\n`RateApplied` on the response as the source of truth — don't recompute it.\n\n---\n\n## Backend conversion formulas\n\nTranscribed from `ConversionService.ConvertAsync` /\n`ConversionService.ConvertCryptoAsync` in the backend\n(`IDosGamesSDK/API/Client/v2/Currency/Services/ConversionService.cs`). These\nare enforced server-side; the SDK never recomputes them — use this section\nonly for building accurate cost/reward **previews**, not for validating a\nconversion before sending it.\n\n**Order of checks** (any failure short-circuits, no partial debit):\n\n1. Basic shape: non-empty `SourceID`/`TargetID`, positive amount, source ≠\n   target.\n2. `Convert` (VC↔VC) rejects a `Crypto` source outright (\"Convert supports\n   VC↔VC only\") and a `Crypto` target outright (\"Virtual→Crypto conversion is\n   not supported\"). `CryptoConvert` rejects a non-`Crypto` source outright\n   (\"CryptoConvert requires source to be Crypto\").\n3. **Status**: source or target `Maintenance` → rejected on that side (\"is\n   under maintenance\"). Target (only) `Deprecated` → rejected (\"is deprecated\n   and cannot receive new credits\"). A `Deprecated` **source** is allowed —\n   deprecating a currency only stops new inflow, it doesn't trap the player's\n   remaining balance.\n4. Source's `Conversion` must be non-null and `Enabled`, and must have a\n   `Targets` entry matching `(TargetCurrencyType, TargetCurrencyID)` exactly —\n   otherwise \"Conversion from 'X' to 'Y' is not allowed.\"\n5. Crypto-source → Virtual-target additionally requires\n   `CryptoCurrencyPermissions.ConvertibleToVirtual` — false rejects even a\n   listed target.\n6. Per-pair `MinAmount`/`MaxAmount` on the matched `ConversionTarget`, checked\n   against the raw source amount before fee.\n7. **Rate resolution**:\n   - `RateMode = Manual` → `rate = ConversionTarget.Rate`; a pair configured\n     Manual with no `Rate` set is rejected (\"Manual conversion rate is not set\n     for this pair\"), not treated as 0 or 1.\n   - `RateMode = Automatic` → `rate = source.ValueInUSD / target.ValueInUSD`.\n     Either side missing/zero `ValueInUSD` rejects the conversion (\"Automatic\n     rate cannot be computed\").\n8. **Fee**: `Fee` is a SHARE (`0.05` = 5%), so `feeAmount = sourceAmount * Fee`\n   — there is no division by 100. It is **not** clamped to a range: only `NaN`\n   is treated as zero, and the fee is capped at the source amount itself. On the\n   VC→VC path a fee below `1.0` additionally leaves at least one unit\n   (`MaxPerPosition = sourceAmount - 1`), so that rounding alone can never make\n   a small conversion impossible; `Fee = 1.0` is a deliberate ban and keeps its\n   full effect. `netSource = sourceAmount - feeAmount`; `netSource <= 0` is\n   rejected.\n9. **Output**: `output = netSource * rate`.\n   - VC↔VC (`ConvertAsync`): `output` is cast straight to `long`, i.e.\n     **truncated toward zero**. `output <= 0` after truncation is rejected\n     (\"Resulting target amount is zero\").\n   - Crypto-source (`ConvertCryptoAsync`): `output` stays a full-precision\n     `decimal` if the target is `Crypto`. If the target is `Virtual`, it is\n     **floored** (`Math.Floor`) to a `long` before the zero-check.\n10. Per-pair `DailyLimit` on the matched `ConversionTarget`: today's\n    already-converted amount for this exact `(SourceType:SourceID ->\nTargetType:TargetID)` pair (tracked server-side per UTC day; not exposed\n    to the client) plus this operation's raw source amount must not exceed\n    it.\n11. The debit/credit itself runs through `ResourceService\n.ApplyResourceOperationAtomicAsync`, which additionally enforces the\n    source currency's own `Economy.MinBalance`/`MaxBalance` (for VC) and\n    `Economy.DailyEarnLimit`/`DailySpendLimit` — a **second, independent**\n    limit layer scoped to the whole currency rather than this one pair. A\n    crypto source's live balance is checked directly against\n    `InventoryV2.CryptoCurrencies[id].Amount` before the debit.\n\n**Practical takeaway**: two conversions that look identical (same pair, same\namount) can differ in outcome depending on how much of the _daily_ pair\nallowance or the _daily_ currency-wide allowance is already used — always\nrender the server's `error` rather than trying to precompute eligibility.\n\n---\n\n## The shared resource primitives\n\nThis is the **canonical documentation** for these types — every other module\nskill (Store, Character, Craft, Lootbox, Blockchain, …) links here instead of\nredefining them. They describe \"spend this, receive that\" in one uniform\nshape used for offer costs, upgrade costs, craft inputs/outputs, lootbox\nprices/rewards, and blockchain deposit/withdrawal resource deltas.\n\n### ResourceEntry\n\nThe atomic unit: one currency or item quantity.\n\n```ts\ninterface ResourceEntry {\n  Type?:\n    | \"Item\"\n    | \"VirtualCurrency\"\n    | \"CryptoCurrency\"\n    | \"Purchase\"\n    | \"RewardedVideoCredit\"; // ResourceEntryType\n  CurrencyID?: string; // set when Type is a currency kind\n  Amount?: number; // integer amount; C# `long` on the wire, parsed via zVcAmount (exact up to 2^53-1)\n  CatalogID?: string; // set when Type is \"Item\": which catalog\n  ItemID?: string; // set when Type is \"Item\": which item definition\n  ProductID?: string; // set when Type is \"Purchase\": the IAP product that pays for this entry\n}\n```\n\nOnly the fields relevant to `Type` are populated — e.g. a `VirtualCurrency`\nentry sets `CurrencyID` + `Amount` and leaves `CatalogID`/`ItemID` unset; an\n`Item` entry sets `CatalogID`/`ItemID` (+ `Amount` for stackable quantity) and\nleaves `CurrencyID` unset.\n\n### ResourceBundle\n\nA flat list of entries, plus optional event-token deltas:\n\n```ts\ninterface ResourceBundle {\n  Entries?: ResourceEntry[] | null;\n  EventTokens?: EventTokenOperation[] | null;\n}\n```\n\n### PremiumTierBundle\n\nAn alternate bundle that only applies if the player holds a qualifying\npremium tier — used inside `ResourceGrant`/`ResourceConsume` to express\n\"VIPs get a better grant / a cheaper cost.\"\n\n```ts\ninterface PremiumTierBundle {\n  MinPremiumTier?: number;\n  RequiredPremiumID?: string;\n  Resources?: ResourceBundle | null;\n}\n```\n\n### ResourceGrant\n\nWhat a player receives.\n\n```ts\ninterface ResourceGrant {\n  Standard?: ResourceBundle | null; // baseline grant, always applies\n  PremiumBonuses?: unknown[] | null; // reserved/opaque bonus list\n  PremiumTiers?: PremiumTierBundle[] | null; // tier-gated additional/alternate grants\n}\n```\n\n### ResourceConsume\n\nWhat a player is charged. Mirror-shaped to `ResourceGrant`, but the\ntier-based array is a **discount** mechanism rather than a bonus one — see\nGotchas below.\n\n```ts\ninterface ResourceConsume {\n  Standard?: ResourceBundle | null; // baseline cost\n  PremiumDiscounts?: unknown[] | null; // reserved/opaque discount list\n  PremiumTiers?: PremiumTierBundle[] | null; // tier-gated reduced/alternate cost\n}\n```\n\n### ResourceOperation\n\nThe full manifest for one action: what's granted and what's consumed. This is\nthe shape every \"did an action succeed\" response embeds under a `Resources`\nfield (e.g. `DepositNFTResponse.Resources`, `NFTWithdrawalResponse.Resources`\nin Blockchain).\n\n```ts\ninterface ResourceOperation {\n  Grant?: ResourceGrant | null;\n  Consume?: ResourceConsume | null;\n}\n```\n\nEither side can be `null`/absent — a pure grant (no cost) sets only `Grant`;\na pure charge (no payout) sets only `Consume`.\n\n### EventTokenOperation / EventTokenAddress\n\nEvent tokens are a lighter-weight counter mechanic (e.g. season/event\ncurrency) addressed by an entity rather than a flat `CurrencyID`:\n\n```ts\ninterface EventTokenAddress {\n  Type?: string; // EventTokenType — which kind of entity owns the token bucket\n  EntityID: string;\n}\n\ninterface EventTokenOperation {\n  Address?: EventTokenAddress | null;\n  Amount?: number;\n  Source?: string; // free-form provenance tag\n}\n```\n\n### ResourceDualPartyResult / ResourceTransferResult\n\nUsed by PvP/transfer-style features where two accounts are affected by one\naction:\n\n```ts\n// Each side gets its own independent grant/consume manifest.\ninterface ResourceDualPartyResult {\n  FromUserID?: string;\n  ToUserID?: string;\n  FromResult?: ResourceOperation | null;\n  ToResult?: ResourceOperation | null;\n}\n\n// A straight transfer: one bundle moves from one account to another.\ninterface ResourceTransferResult {\n  FromUserID?: string;\n  ToUserID?: string;\n  Transferred?: ResourceBundle | null;\n}\n```\n\n---\n\n## How the SDK applies a ResourceOperation\n\nEvery module that returns a `ResourceOperation` (directly, or via a\n`Resources` field) has already had it **applied server-side**; the SDK's job\nis only to mirror it into the local cache so balances/inventory read\ncorrectly without a re-fetch. Internally this goes through\n`UserData.applyResourceOperation(op, itemDefs)`, which:\n\n- walks `Consume.Standard.Entries` and `Grant.Standard.Entries` (the\n  `PremiumDiscounts`/`PremiumTiers`/`PremiumBonuses` arrays describe _why_ the\n  standard amount is what it is — the server has already resolved them into\n  `Standard` before sending the response; the client does not re-apply tiers),\n- for `VirtualCurrency` entries, adjusts the integer balance and emits\n  `user:virtualCurrencyUpdated`,\n- for `Item` entries, adjusts stackable counts / creates unstackable instances\n  and emits `user:inventoryUpdated`,\n- for `EventTokens`, adjusts the addressed token bucket and emits\n  `user:eventTokenUpdated`,\n- always emits the umbrella `user:anyUpdated` when anything changed.\n\n`CryptoCurrency` amounts do **not** flow through this integer pipeline —\nthey're decimal and go through a separate patch\n(`UserData.patchCryptoCurrencyDelta(currencyID, delta, serverTimeUtc)`), which\nis what `CurrencyService.cryptoConvert` and the Blockchain deposit/withdrawal\nmethods use directly instead of embedding crypto deltas in a\n`ResourceOperation`.\n\n**Practical takeaway when building UI in any module:** don't hand-roll cost\npreviews from `PremiumDiscounts`/`PremiumTiers` internals unless you're\nexplicitly building a \"your VIP tier saves you N%\" comparison — for \"what will\nthis cost me right now,\" prefer the value the server already resolved\n(`Standard`, or the flat response fields like `ConvertResponse.SourceSpent`).\nTreat `Amount` on VC entries as a signed integer conceptually (consume vs.\ngrant is which container it's in, not a negative number) and crypto strings as\nopaque decimal values to hand to `decimal.js`, not to parse with `Number()`\nonce you're near precision limits.\n"
     }
   ]
 }

package/registry/skills/idosgames-compose-modules.json

@@ -1,6 +1,6 @@
 {
   "name": "idosgames-compose-modules",
   "description": "Put an iDosGames app together from the base and modules — the systems (shop, heroes, leaderboards, quests, chests, multiplayer…) as lobby tabs, one or several games behind \"Play\", progress shared across them. Use this whenever a developer wants to COMBINE or MERGE modules into a single title, add or remove a system, add a second game, switch between the lobby and game modes, share currency/inventory across modules, or asks how the lobby, \"Play\", ctx.modes, activeOnly panels, the shared-UI roles (sharedUi, shouldDraw, the \"modes\" role), typed cross-module events (defineTopic/shape) or host-level shared state work. Builds on idosgames-getting-started (scaffolding) and idosgames-module-contract (a single module).",
-  "content": "---\nname: idosgames-compose-modules\ndescription: >-\n  Put an iDosGames app together from the base and modules — the systems (shop, heroes, leaderboards,\n  quests, chests, multiplayer…) as lobby tabs, one or several games behind \"Play\", progress shared across them. Use this\n  whenever a developer wants to COMBINE or MERGE modules into a single title, add or remove a system,\n  add a second game, switch between the lobby and game modes, share currency/inventory across modules,\n  or asks how the lobby, \"Play\", ctx.modes, activeOnly panels, the shared-UI roles (sharedUi,\n  shouldDraw, the \"modes\" role), typed cross-module events (defineTopic/shape) or host-level shared\n  state work. Builds on idosgames-getting-started (scaffolding) and idosgames-module-contract (a single\n  module).\n---\n\n# Putting an app together: the base + modules\n\nEvery project is **the base + modules**. The base (`src/base/`, from the host scaffold) is sign-in and\nthe lobby; everything else is a module in `src/modules/<id>/`:\n\n- **systems** (`type: feature`) — one per player-facing module of the engine: store, premium (VIP),\n  character, inventory, lootboxes, boosts, leaderboard, rewards (daily), quests, collections, craft,\n  marketplace, deals, events, coop-events, season, friends, chat, invite, pvp, multiplayer, profile,\n  tutorials, workshop, ai, mailbox. Each registers its screen as a **feature** → a tab of the lobby.\n  The base installs only six of them into every new project (`inBase: true`: profile, inventory,\n  invite, friends, quests, mailbox); every other system is installed only when the app needs it — a game\n  brings the ones it lists in `uses`, and you install any other one as soon as the task needs what\n  it `provides` (InstallModule / `get_module`) — the user does not have to name the module; reuse it\n  instead of writing that feature again. Never install one the task does not need.\n- **games** (`type: template`) — board-game, idle-rpg, voxelcraft, mini-game, or the game's own. Each\n  registers a **route** → a \"Play\" button in the lobby. A game that plugs into a system lists it in\n  `uses` in its module.meta.json (`ctx.multiplayer` → `\"multiplayer\"`, `ctx.content` → `\"workshop\"`;\n  `npm run check` enforces those two) — install those together with the game.\n\n## Register modules\n\n```ts\n// src/modules.ts — the platform regenerates it; by hand it is imports + the array\nexport const modules: Module[] = [\n  storeModule, // systems: lobby tabs\n  characterModule,\n  leaderboardModule,\n  boardGameModule, // games: \"Play\"\n  idleRpgModule,\n];\n```\n\n`src/main.tsx` mounts `[baseModule, ...modules]`. After sign-in the player lands in the game that\nlives inside the lobby, or in the lobby when the games take the whole screen (`src/app.config.ts`\n`start`: `\"game\"` — the default, `\"lobby\"`, or a game's mode id). \"Play\" switches the host to the\ngame's mode: only the active mode's scene is mounted and ticking; the rest are suspended (their RAF\nstops). This is why two different engines (Three + Phaser) live in one project — they never render\nat the same time. Two kinds of game (owner's decision 03.10.2026 — chosen per game, never for all):\n\n- `ctx.registerRoute({ …, inLobby: true })` — the game sits INSIDE the lobby (idle-rpg): the base\n  keeps the balances on top and the tabs at the bottom (host panel slots `header`/`footer` — the\n  game is laid out between them, it does nothing for it); \"Play\" is the game, any other tab opens\n  that screen, the app starts in it. A game with its own bar to the systems hides it when\n  `ctx.sharedUi.shouldDraw(\"menu\")` is false (idle-rpg does).\n- without it (the default) — the game takes the whole screen (voxelcraft, board-game, mini-game):\n  \"Play\" in the lobby launches it, over it the base draws only a small \"To the lobby\" button.\n\n- A system tab is hidden while the title has nothing for it (no store offers, no heroes…): the module\n  registers with `available: false` and calls `ctx.features.setAvailable(id, ok, reason)`.\n- `ctx.modes.list()` / `current()` / `subscribe()` — every mode (id, label, icon, module, module type);\n  the lobby builds \"Play\" from the `game` ones. Switch with `ctx.navigate(id)` (`\"lobby\"` is the base).\n- Open another system's screen by id: `ctx.features.open(\"store\")` — from a game too (the host shows\n  it in a window while the lobby is off screen). Never import another module.\n\n## Share progress across modes (the merge)\n\nShared state lives in the ONE SDK client, not in any module. Every module reads/writes the same\n`client` (currency, inventory, characters), so progress carries across modes automatically:\n\n- Gold earned idle in the RPG mode is spendable in the Board mode and in the shop — same\n  `client.currency`, same cache. No cross-module plumbing needed for durable state.\n- For live cross-module signals (not durable state), use `ctx.events` with a **typed topic** — see\n  \"Signals between modules\" below.\n- Modules never import each other's files or `src/base/`. The client and the event bus are the seams\n  between them — which is what keeps a module reusable in another game. Code several of THIS game's\n  modules need (shared types, the game's UI kit, helpers) goes to `src/shared/`, which never imports a\n  module (see idosgames-project-structure).\n\n## Shared chrome: roles, and the base takes them\n\nBalances, the crypto wallet, the status line, \"Log out\" / player ID, the menu of features and the\nswitch between modes are **shared-UI roles** (`currency-bar | wallet | status | account | menu |\nmodes`). A module that draws one for EVERY mode declares it statically on the module object —\nthe base does:\n\n```ts\ndefineModule({\n  id: \"base\",\n  meta: { name: \"Base\", type: \"app\", engine: \"dom\" },\n  sharedUi: {\n    provides: [\"currency-bar\", \"wallet\", \"account\", \"menu\", \"modes\"],\n  },\n  setup(ctx) {\n    /* the lobby: balances, wallet, profile, tabs, \"Play\" */\n  },\n});\n```\n\nThe host resolves role owners from these declarations BEFORE any `setup()` — the first provider wins,\na conflict is warned — and every module asks `ctx.sharedUi.shouldDraw(role)`. A game draws its own\ncopy only while nobody took the role. So:\n\n- Next to the base a game hides its own balances and wallet by itself. Do NOT edit a catalog game to\n  remove them: it does that itself, and an edit marks it customized (no more catalog updates).\n- `status` — the line of a game's own actions (\"Rolling…\") — stays with each game.\n- A game installed without a base stays complete — nobody owns a role, it draws everything, and the\n  host draws its own nav of routes, ☰ and \"Log out\" (those are the host-drawn roles `modes`, `menu`,\n  `account`).\n- A new module that needs, say, the balance bar but does not draw it declares\n  `sharedUi: { requires: [\"currency-bar\"] }`; with no provider installed the host warns.\n\n**Layout is the host's job.** A game's overlay fills the screen under the base's small button; a\nscene's own DOM HUD can keep clear of host chrome with the CSS variables on the host root —\n`top: calc(var(--idos-safe-top, 0px) + 8px)`, `bottom: calc(var(--idos-safe-bottom, 0px) + 8px)`\n(voxelcraft's hotbar does this). Both are 0 when nothing is pinned. `hud`-slot panels are wrapped in\n`display: contents`, so a panel can stretch (`flex: 1`) and decide its own pointer-events: let clicks\nthrough to the game, take them only on controls.\n\n## Signals between modules (typed topics)\n\nA topic is a token passed by value: the name carries the major version, the payload is a flat JSON\nshape — one artifact that gives the TS type, the runtime check and the catalog entry.\n\n```ts\n// idle-rpg/events.ts — the EMITTER owns the topic\nimport { defineTopic, shape } from \"@idosgames/module-sdk\";\nexport const characterUpgraded = defineTopic(\n  \"idle-rpg:character-upgraded@1\",\n  shape({ characterId: \"string\", level: \"number\" }),\n);\n// setup(): hand the panel a callback that does\n//   ctx.events.emit(characterUpgraded, { characterId, level });\n```\n\n```ts\n// board-game/events.ts — the LISTENER keeps its OWN copy (copied from the catalog), never an import.\n// Optional: idle-rpg may not be installed. Only the fields this module reads.\nexport const idleCharacterUpgraded = defineTopic(\n  \"idle-rpg:character-upgraded@1\",\n  shape({ level: \"number\" }),\n);\n// setup() — NOT a panel effect (activeOnly panels unmount with their mode and miss events):\nctx.events.on(idleCharacterUpgraded, ({ level }) =>\n  news.push(`Idle RPG hero reached Lv ${level}`),\n);\n```\n\nDeclare both sides in `module.meta.json` — the catalog and the agent read this, not your code:\n\n```json\n\"events\": {\n  \"emits\": [{ \"topic\": \"idle-rpg:character-upgraded@1\", \"when\": \"a hero levelled up\",\n              \"payload\": { \"characterId\": \"string\", \"level\": \"number\" } }],\n  \"listens\": [{ \"topic\": \"idle-rpg:character-upgraded@1\", \"why\": \"news chip in the board HUD\" }]\n}\n```\n\nRules:\n\n- Name `<your-module-id>:<event>@<major>`. Emit only into your own namespace — the host drops an\n  emit into another module's namespace with `console.error`; `host:` is reserved. The only topics\n  you import are `hostTopics` from `@idosgames/module-sdk` (`hostTopics.modeChanged` =\n  `host:mode-changed@1 { from?: string; to: string }`, sent on every mode switch).\n- Shape leaves: `\"string\" | \"number\" | \"boolean\"`, with `\"[]\"` and/or a trailing `\"?\"`; nested\n  objects allowed. Payloads are plain JSON — no functions, class instances or engine objects.\n- An incompatible change is a NEW topic `@2` (send both during the transition); within a major, only\n  add fields. A listener whose fields are missing is skipped (one `console.warn`), never crashed.\n- An event is a signal, not state, and is never replayed — \"what exists now\" is SDK data or\n  `ctx.sharedUi`. No request/response between modules: if you need an answer, it is data.\n- A throwing handler does not stop other listeners or reach the emitter; the host removes every\n  subscription on logout, so re-login does not double handlers.\n- In the AI editor's preview, `gameState` returns the last 50 events, who listens to what, and hints\n  like \"board-game listens to x@1 but only x@2 is emitted\".\n- A game's OWN modules may keep shared topic tokens in `src/shared/events/` and import them on both\n  sides — still declare them in each `module.meta.json`.\n\n## Reference app\n\nThe base + the systems + `board-game` + `idle-rpg`:\n\n- sign-in → the lobby: balances, wallet and profile on top, the systems as tabs, \"Play\" with two games;\n- \"Play\" → one engine scene mounted at a time; the lobby's tabs stay around an `inLobby` game, a\n  full-screen game gets the button back;\n- the games hide their own balances and wallet (the lobby has them); their status lines stay theirs;\n- currency changed in one mode is immediately visible in the others and in the lobby; levelling a hero\n  in Idle RPG shows a news chip on the board (`idle-rpg:character-upgraded@1`).\n\nTo pull the modules, use `get_module {id}` for each (MCP) and register them as above. Adjust layouts\nper module (a full-bleed overlay UI vs a docked side panel) — see each module's RootPanel.\n",
+  "content": "---\nname: idosgames-compose-modules\ndescription: >-\n  Put an iDosGames app together from the base and modules — the systems (shop, heroes, leaderboards,\n  quests, chests, multiplayer…) as lobby tabs, one or several games behind \"Play\", progress shared across them. Use this\n  whenever a developer wants to COMBINE or MERGE modules into a single title, add or remove a system,\n  add a second game, switch between the lobby and game modes, share currency/inventory across modules,\n  or asks how the lobby, \"Play\", ctx.modes, activeOnly panels, the shared-UI roles (sharedUi,\n  shouldDraw, the \"modes\" role), typed cross-module events (defineTopic/shape) or host-level shared\n  state work. Builds on idosgames-getting-started (scaffolding) and idosgames-module-contract (a single\n  module).\n---\n\n# Putting an app together: the base + modules\n\nEvery project is **the base + modules**. The base is sign-in and the lobby and comes from the SDK\n(`@idosgames/app-shell`: `createBaseModule`, `DefaultLoginScreen`, `DefaultPlayAccessScreen`); the project\nconfigures it in `src/app.config.ts` (where the player lands, the tab order, guest sign-in), `src/ui.config.ts`\n(the look) and `src/main.tsx`. Everything else is a module in `src/modules/<id>/`:\n\n- **systems** (`type: feature`) — one per player-facing module of the engine: store, premium (VIP),\n  character, inventory, lootboxes, boosts, leaderboard, rewards (daily), quests, collections, craft,\n  marketplace, deals, events, coop-events, season, friends, chat, invite, pvp, multiplayer, profile,\n  tutorials, workshop, ai, mailbox. Each registers its screen as a **feature** → a tab of the lobby.\n  The base installs only six of them into every new project (`inBase: true`: profile, inventory,\n  invite, friends, quests, mailbox); every other system is installed only when the app needs it — a game\n  brings the ones it lists in `uses`, and you install any other one as soon as the task needs what\n  it `provides` (InstallModule / `get_module`) — the user does not have to name the module; reuse it\n  instead of writing that feature again. Never install one the task does not need.\n- **games** (`type: template`) — board-game, idle-rpg, voxelcraft, mini-game, or the game's own. Each\n  registers a **route** → a \"Play\" button in the lobby. A game that plugs into a system lists it in\n  `uses` in its module.meta.json (`ctx.multiplayer` → `\"multiplayer\"`, `ctx.content` → `\"workshop\"`;\n  `npm run check` enforces those two) — install those together with the game.\n\n## Register modules\n\n```ts\n// src/modules.ts — the platform regenerates it; by hand it is imports + the array\nexport const modules: Module[] = [\n  storeModule, // systems: lobby tabs\n  characterModule,\n  leaderboardModule,\n  boardGameModule, // games: \"Play\"\n  idleRpgModule,\n];\n```\n\n`src/main.tsx` mounts `[createBaseModule(appConfig, …), ...modules]`. After sign-in the player lands in the game that\nlives inside the lobby, or in the lobby when the games take the whole screen (`src/app.config.ts`\n`start`: `\"game\"` — the default, `\"lobby\"`, or a game's mode id). \"Play\" switches the host to the\ngame's mode: only the active mode's scene is mounted and ticking; the rest are suspended (their RAF\nstops). This is why two different engines (Three + Phaser) live in one project — they never render\nat the same time. Two kinds of game (owner's decision 03.10.2026 — chosen per game, never for all):\n\n- `ctx.registerRoute({ …, inLobby: true })` — the game sits INSIDE the lobby (idle-rpg): the base\n  keeps the balances on top and the tabs at the bottom (host panel slots `header`/`footer` — the\n  game is laid out between them, it does nothing for it); \"Play\" is the game, any other tab opens\n  that screen, the app starts in it. A game with its own bar to the systems hides it when\n  `ctx.sharedUi.shouldDraw(\"menu\")` is false (idle-rpg does).\n- without it (the default) — the game takes the whole screen (voxelcraft, board-game, mini-game):\n  \"Play\" in the lobby launches it, over it the base draws only a small \"To the lobby\" button.\n\n- A system tab is hidden while the title has nothing for it (no store offers, no heroes…): the module\n  registers with `available: false` and calls `ctx.features.setAvailable(id, ok, reason)`.\n- `ctx.modes.list()` / `current()` / `subscribe()` — every mode (id, label, icon, module, module type);\n  the lobby builds \"Play\" from the `game` ones. Switch with `ctx.navigate(id)` (`\"lobby\"` is the base).\n- Open another system's screen by id: `ctx.features.open(\"store\")` — from a game too (the host shows\n  it in a window while the lobby is off screen). Never import another module.\n\n## Share progress across modes (the merge)\n\nShared state lives in the ONE SDK client, not in any module. Every module reads/writes the same\n`client` (currency, inventory, characters), so progress carries across modes automatically:\n\n- Gold earned idle in the RPG mode is spendable in the Board mode and in the shop — same\n  `client.currency`, same cache. No cross-module plumbing needed for durable state.\n- For live cross-module signals (not durable state), use `ctx.events` with a **typed topic** — see\n  \"Signals between modules\" below.\n- Modules never import each other's files. The client and the event bus are the seams\n  between them — which is what keeps a module reusable in another game. Code several of THIS game's\n  modules need (shared types, the game's UI kit, helpers) goes to `src/shared/`, which never imports a\n  module (see idosgames-project-structure).\n\n## Shared chrome: roles, and the base takes them\n\nBalances, the crypto wallet, the status line, \"Log out\" / player ID, the menu of features and the\nswitch between modes are **shared-UI roles** (`currency-bar | wallet | status | account | menu |\nmodes`). A module that draws one for EVERY mode declares it statically on the module object —\nthe base does:\n\n```ts\ndefineModule({\n  id: \"base\",\n  meta: { name: \"Base\", type: \"app\", engine: \"dom\" },\n  sharedUi: {\n    provides: [\"currency-bar\", \"wallet\", \"account\", \"menu\", \"modes\"],\n  },\n  setup(ctx) {\n    /* the lobby: balances, wallet, profile, tabs, \"Play\" */\n  },\n});\n```\n\nThe host resolves role owners from these declarations BEFORE any `setup()` — the first provider wins,\na conflict is warned — and every module asks `ctx.sharedUi.shouldDraw(role)`. A game draws its own\ncopy only while nobody took the role. So:\n\n- Next to the base a game hides its own balances and wallet by itself. Do NOT edit a catalog game to\n  remove them: it does that itself, and an edit marks it customized (no more catalog updates).\n- `status` — the line of a game's own actions (\"Rolling…\") — stays with each game.\n- A game installed without a base stays complete — nobody owns a role, it draws everything, and the\n  host draws its own nav of routes, ☰ and \"Log out\" (those are the host-drawn roles `modes`, `menu`,\n  `account`).\n- A new module that needs, say, the balance bar but does not draw it declares\n  `sharedUi: { requires: [\"currency-bar\"] }`; with no provider installed the host warns.\n\n**Layout is the host's job.** A game's overlay fills the screen under the base's small button; a\nscene's own DOM HUD can keep clear of host chrome with the CSS variables on the host root —\n`top: calc(var(--idos-safe-top, 0px) + 8px)`, `bottom: calc(var(--idos-safe-bottom, 0px) + 8px)`\n(voxelcraft's hotbar does this). Both are 0 when nothing is pinned. `hud`-slot panels are wrapped in\n`display: contents`, so a panel can stretch (`flex: 1`) and decide its own pointer-events: let clicks\nthrough to the game, take them only on controls.\n\n## Signals between modules (typed topics)\n\nA topic is a token passed by value: the name carries the major version, the payload is a flat JSON\nshape — one artifact that gives the TS type, the runtime check and the catalog entry.\n\n```ts\n// idle-rpg/events.ts — the EMITTER owns the topic\nimport { defineTopic, shape } from \"@idosgames/module-sdk\";\nexport const characterUpgraded = defineTopic(\n  \"idle-rpg:character-upgraded@1\",\n  shape({ characterId: \"string\", level: \"number\" }),\n);\n// setup(): hand the panel a callback that does\n//   ctx.events.emit(characterUpgraded, { characterId, level });\n```\n\n```ts\n// board-game/events.ts — the LISTENER keeps its OWN copy (copied from the catalog), never an import.\n// Optional: idle-rpg may not be installed. Only the fields this module reads.\nexport const idleCharacterUpgraded = defineTopic(\n  \"idle-rpg:character-upgraded@1\",\n  shape({ level: \"number\" }),\n);\n// setup() — NOT a panel effect (activeOnly panels unmount with their mode and miss events):\nctx.events.on(idleCharacterUpgraded, ({ level }) =>\n  news.push(`Idle RPG hero reached Lv ${level}`),\n);\n```\n\nDeclare both sides in `module.meta.json` — the catalog and the agent read this, not your code:\n\n```json\n\"events\": {\n  \"emits\": [{ \"topic\": \"idle-rpg:character-upgraded@1\", \"when\": \"a hero levelled up\",\n              \"payload\": { \"characterId\": \"string\", \"level\": \"number\" } }],\n  \"listens\": [{ \"topic\": \"idle-rpg:character-upgraded@1\", \"why\": \"news chip in the board HUD\" }]\n}\n```\n\nRules:\n\n- Name `<your-module-id>:<event>@<major>`. Emit only into your own namespace — the host drops an\n  emit into another module's namespace with `console.error`; `host:` is reserved. The only topics\n  you import are `hostTopics` from `@idosgames/module-sdk` (`hostTopics.modeChanged` =\n  `host:mode-changed@1 { from?: string; to: string }`, sent on every mode switch).\n- Shape leaves: `\"string\" | \"number\" | \"boolean\"`, with `\"[]\"` and/or a trailing `\"?\"`; nested\n  objects allowed. Payloads are plain JSON — no functions, class instances or engine objects.\n- An incompatible change is a NEW topic `@2` (send both during the transition); within a major, only\n  add fields. A listener whose fields are missing is skipped (one `console.warn`), never crashed.\n- An event is a signal, not state, and is never replayed — \"what exists now\" is SDK data or\n  `ctx.sharedUi`. No request/response between modules: if you need an answer, it is data.\n- A throwing handler does not stop other listeners or reach the emitter; the host removes every\n  subscription on logout, so re-login does not double handlers.\n- In the AI editor's preview, `gameState` returns the last 50 events, who listens to what, and hints\n  like \"board-game listens to x@1 but only x@2 is emitted\".\n- A game's OWN modules may keep shared topic tokens in `src/shared/events/` and import them on both\n  sides — still declare them in each `module.meta.json`.\n\n## Reference app\n\nThe base + the systems + `board-game` + `idle-rpg`:\n\n- sign-in → the lobby: balances, wallet and profile on top, the systems as tabs, \"Play\" with two games;\n- \"Play\" → one engine scene mounted at a time; the lobby's tabs stay around an `inLobby` game, a\n  full-screen game gets the button back;\n- the games hide their own balances and wallet (the lobby has them); their status lines stay theirs;\n- currency changed in one mode is immediately visible in the others and in the lobby; levelling a hero\n  in Idle RPG shows a news chip on the board (`idle-rpg:character-upgraded@1`).\n\nTo pull the modules, use `get_module {id}` for each (MCP) and register them as above. Adjust layouts\nper module (a full-bleed overlay UI vs a docked side panel) — see each module's RootPanel.\n",
   "references": []
 }