From a4b35e5600f192b372f049d3c8bda2722491e854 Mon Sep 17 00:00:00 2001 From: Etay Matzliah Date: Thu, 4 Jun 2026 20:02:09 +0300 Subject: [PATCH 1/6] Add Hot & Cold Inventories advanced-mechanics guide Documents a best-practice pattern for real-time games: keep tradeable assets on-chain (the cold inventory, which is the player's wallet) and keep consumable, fast-action items in an off-chain hot inventory, moving items across the boundary with on-chain mints and melts. Covers the mintable/non-mintable decision, the mint-in/melt-out lifecycle, a GraphQL worked example, and correctness pitfalls (finalization before crediting, the optimistic-consume exploit, collapsing-supply, and treating the hot ledger as production-critical). Adds glossary entries for hot/cold inventory and mintable/non-mintable items. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../07-hot-cold-inventories.md | 184 ++++++++++++++++++ src/glossary.js | 4 + 2 files changed, 188 insertions(+) create mode 100644 docs/02-guides/01-platform/03-advanced-mechanics/07-hot-cold-inventories.md diff --git a/docs/02-guides/01-platform/03-advanced-mechanics/07-hot-cold-inventories.md b/docs/02-guides/01-platform/03-advanced-mechanics/07-hot-cold-inventories.md new file mode 100644 index 0000000..81b9ec7 --- /dev/null +++ b/docs/02-guides/01-platform/03-advanced-mechanics/07-hot-cold-inventories.md @@ -0,0 +1,184 @@ +--- +title: "Hot & Cold Inventories" +slug: "hot-cold-inventories" +description: "A best-practice pattern for real-time games on the Enjin Platform: keep tradeable assets on-chain in a cold inventory, keep consumable fast-action items in an off-chain hot inventory, and move items between them with on-chain mints and melts." +--- + +import GlossaryTerm from '@site/src/components/GlossaryTerm'; + +Some games can wait a few seconds for the blockchain. Fast-paced games can't. This guide describes a pattern — **hot and cold inventories** — that lets a real-time game keep instant, web2-style gameplay while still giving players true on-chain ownership of the items that matter. + +## The problem: the blockchain isn't a real-time database + +Real-time games are full of **atomic actions** — things that have to resolve *now*. A player on low health drinks a potion this instant, or their character dies. There's no room for a loading spinner. + +On-chain, every state change is a that has to be included in a block and then finalized. That takes seconds, not milliseconds. Put a consumable's on-chain on the critical path of combat and the game becomes unplayable. + +:::warning A managed wallet doesn't fix this +It's tempting to think a second, platform-controlled wallet makes actions instant. It doesn't. A [managed wallet](/02-guides/01-platform/02-managing-users/03-using-managed-wallets.md) is a **real on-chain account** — the platform simply custodies its keys and signs on its behalf. Consuming a token from a managed wallet is still an on-chain transaction with the same finalization latency as any other. Moving an item between two wallets changes *who signs* and *where it lives*, not *whether the action touches the chain*. +::: + +The fix isn't to make the chain faster — it's to keep real-time actions **off** the chain entirely, and use the chain only for what it's uniquely good at: **ownership and settlement.** + +## The model: hot and cold inventories + +Give each player's items two possible homes: + +| | **Cold inventory** | **Hot inventory** | +| :--- | :--- | :--- | +| **What it is** | The player's on-chain wallet | An off-chain ledger your game server owns (a database table) | +| **Speed** | Seconds (on-chain transaction) | Instant (a database write) | +| **Good for** | Trading, transferring, true ownership | Consuming and mutating items in real time | +| **On-chain footprint** | Real tokens | None — while an item is hot, it doesn't exist on-chain | + +By default, items live **hot**: they're earned, bought, and used entirely off-chain, so to the player the game feels like any other. Moving an item to cold is a deliberate step a player takes when they want to trade it or hold it themselves. + +:::info "Cold inventory" is really a wallet +*Cold inventory* is just a friendlier, player-facing name for the player's on-chain wallet — a managed wallet you create for them, or a self-custodial wallet they connect. *Hot inventory* is not a wallet at all; it's rows in your own database. +::: + +One rule keeps the whole scheme honest: **a unit is either hot or cold, never both.** Moving an item across the boundary destroys it on one side as it's created on the other. As a result, the on-chain supply of a token always equals "the number of units currently held cold" — the hot units have no on-chain existence. + +## Deciding what goes where + +Two independent questions decide how an item behaves. + +### 1. Is the item *mintable*? (decided at design time) + +This is whether the item can ever exist as an on-chain token. + +- **Non-mintable** — has no on-chain token, ever, and lives in the hot inventory for its whole life. Best for high-churn, low-value items where putting them on-chain would cost a and fees for no real benefit: common consumables, ammunition, temporary buffs, crafting intermediates, soft currency. +- **Mintable** — has a real on-chain token, so it can move between hot and cold. Best for items players will trade or want to truly own: rare gear, cosmetics, named or unique drops. + +### 2. For mintable items: can it be used while cold? + +This depends on **what "using" the item actually does**: + +- If using it only **reads ownership** — equipping a sword, wearing a cosmetic, unlocking gated content — it works fine while **cold**. The game just checks that the wallet holds it; there's no real-time state change, so there's nothing to wait for. +- If using it **consumes or mutates** it in real time — drinking a potion, spending ammo, applying a one-shot buff — it must be **hot** first, because that change can't wait for finalization. + +| Item | Mintable? | Used by… | Where it's used | +| :--- | :--- | :--- | :--- | +| Common health potion | No | Consuming | Hot only | +| Rare elixir (tradeable) | Yes | Consuming | Move to hot, then use | +| Legendary sword | Yes | Equipping (reads ownership) | Usable while cold | +| Cosmetic skin | Yes | Wearing (reads ownership) | Usable while cold | + +## Moving items: mint in, melt out + +The lifecycle of a mintable item: + +- **Earn or buy** → credited straight to the **hot** inventory. An off-chain write — no transaction, no fee. +- **Move to cold** ("make it real") → the token to the player's cold wallet, and debit the hot ledger by the same amount. +- **Move to hot** ("bring it in to use") → melt (burn) the token from the cold wallet, and — once the transaction is finalized — credit the hot ledger. +- **Use from hot** → an off-chain decrement. Instant. + +The key insight: the on-chain transaction happens at the **move**, not at the **use**. A player moves a stack of 50 potions to hot once (a single melt), then consumes them instantly for the rest of the session. You pay the latency once, at the boundary — and you hide it behind a **cooldown**, the same "item is recharging" feedback players already understand. Use a for stackable consumables so an entire stack crosses the boundary in one transaction. + +:::note Naming the move for players +This guide calls it "moving" an item between inventories. In your game's UI, call it whatever fits — many games use something like "teleport" or "warp." If you use **teleport**, be aware it's unrelated to Enjin's **ENJ teleport** (which moves ENJ between the Matrixchain and Relaychain); choose wording that won't confuse players who also hold ENJ. +::: + +## Worked example on the Enjin Platform + +### Cold inventory: one wallet per player + +Each player gets a single on-chain wallet that acts as their cold inventory — either a [managed wallet](/02-guides/01-platform/02-managing-users/03-using-managed-wallets.md) you create for them (`CreateManagedWallet(externalId: "player-115")`), or a self-custodial wallet they [connect with WalletConnect](/02-guides/01-platform/02-managing-users/01-connecting-user-wallets/02-using-wallet-connect.md). + +:::tip One wallet per player, not two +You don't need separate "hot" and "cold" wallets. The hot inventory is rows in your own database; the cold inventory is the player's single on-chain wallet. A second on-chain wallet would just add a second slow account — it wouldn't make anything instant. +::: + +### Hot inventory: your database + +The hot inventory is a table you own — for example `(player_id, token_id, quantity)`. Consuming an item is an `UPDATE` against this table: instant, and entirely under your control. + +### Move to hot — melt from the cold wallet + +Burn the token from the player's cold wallet. For a managed wallet, the platform signs on its behalf via `signerExternalId`: + +```graphql +mutation MoveToHot { + CreateTransaction( + network: ENJIN # or CANARY for testnet + chain: MATRIX + signerExternalId: "player-115" # the player's cold inventory (their managed wallet) + transaction: { + burnToken: { + collectionId: 36105 + tokenId: 10 # e.g. "Health Potion" + amount: 50 # move a whole stack in one transaction + removeTokenStorage: false + } + } + ) { + uuid + action + state + } +} +``` + +Then **wait for finalization before crediting the hot ledger** — poll [`GetTransaction(uuid:)`](/03-api-reference/01-queries/01-transactions-queries.md#gettransaction) until `state` is `FINALIZED`: + +```graphql +query ConfirmMove { + GetTransaction(uuid: "") { + state # credit the hot ledger only once this is FINALIZED + } +} +``` + +See [Working with Events](/05-enjin-platform/03-working-with-events.md) for the full finalization-and-events workflow. (Real-time push events that remove the need to poll are [planned](/03-api-reference/03-websocket-events.md).) + +For a **self-custodial** cold wallet, your server can't sign the melt — the player approves it in their own wallet via WalletConnect instead. + +### Move to cold — mint to the cold wallet + +Mint the token to the player's cold wallet (signed by the collection owner via the by default), and debit the hot ledger by the same amount once finalized. The `recipient` is the cold wallet's public key, which you can look up with [`GetManagedWallet`](/02-guides/01-platform/02-managing-users/03-using-managed-wallets.md#finding-a-managed-wallet): + +```graphql +mutation MoveToCold { + CreateTransaction( + network: ENJIN + chain: MATRIX + transaction: { + mintToken: { + recipient: "0xded3c8f0296f5ee023f07aa5617fc261bd5991c4474ee775a16ec35c1d1a1e3a" + collectionId: 36105 + tokenId: 10 + amount: 50 + } + } + ) { + uuid + action + state + } +} +``` + +### Move several items at once + +If a player crosses the boundary with several different item types at once — a "withdraw everything to my wallet" button, say — bundle the actions into a single [`CreateBatchTransaction`](/03-api-reference/02-mutations/01-transaction-mutations.md) so they settle atomically with one fee instead of many. + +:::info Items stay hot between sessions +There's no need to push unused items back to cold when a player logs off. The hot inventory *is* their everyday inventory and persists across sessions. Crossing to cold is always something the player chooses to do — to trade or self-custody an item — never an automatic step. +::: + +### Cover the fees + +Moving to hot melts a token from the player's wallet, which needs ENJ to pay . Use a so your game sponsors these transactions and players never have to hold ENJ themselves. + +## Correctness & pitfalls + +- **Never credit the hot inventory before the melt is `FINALIZED`.** If you credit early and the transaction reverts, the player ends up with the item in *both* inventories — a double-spend. Treat finalization as the only signal that the move succeeded. +- **Don't try to "optimistically" consume a cold item.** Letting a player use or open a cold item *before* its melt finalizes is exploitable: in the gap, they can transfer or sell that same token and keep both the item and its result. This is especially dangerous with self-custodial wallets, where the player — not your server — holds the keys. The model itself is the defense: an item must be **hot**, under your server's control, before it can be used instantly. Don't shortcut around it. +- **Don't use Collapsing Supply for mintable items.** Burning a collapsing-supply token permanently lowers its maximum supply, so you couldn't mint it back the next time the player moves it to cold. Mintable hot/cold items need a normal supply cap. +- **The hot ledger is production-critical data.** Items that are hot were burned on-chain — they exist *only* in your database. Back it up and treat it as the source of truth it is. This is also the trade-off to be honest about: while an item is hot, the player is trusting your custody, exactly as they would in a web2 game. Cold is where they hold it themselves. +- **Make every move idempotent.** A double-submitted "move to hot" must not melt twice. Key each move by a unique request ID and ignore duplicates. +- **Wait for finalization, not just block inclusion.** A transaction that's included can still be reverted by a reorg. Only act on `FINALIZED`. + +:::info Related building blocks +This pattern combines several platform features documented elsewhere: [Managed Wallets](/02-guides/01-platform/02-managing-users/03-using-managed-wallets.md), [Minting Tokens](/02-guides/01-platform/01-managing-tokens/04-minting-a-token.md), [Melting / Burning Tokens](/02-guides/01-platform/01-managing-tokens/08-burning-destroying-tokens.md), [Fuel Tanks](/02-guides/01-platform/02-managing-users/04-using-fuel-tanks.md), and [Working with Events](/05-enjin-platform/03-working-with-events.md). For a complete (but simpler, fully on-chain) integration to build from, see the [Enjin Farmer sample game](/02-guides/01-platform/05-enjin-farmer-sample-game/03-implementation-breakdown.md). +::: diff --git a/src/glossary.js b/src/glossary.js index fcb2fd8..7594d50 100644 --- a/src/glossary.js +++ b/src/glossary.js @@ -80,6 +80,10 @@ const glossary = { collection: { name: "Collection", definition: "A Collection in the blockchain realm refers to a project on the Enjin blockchain that permits developers and users to design both Multi-Unit Tokens and Non-Fungible Tokens (NFTs) under a specific collection. \nThrough a collection on Enjin, the owner can set up and customize both Multi-Unit Tokens and non-fungible tokens without limitations on the amount. \n\nAdditionally, one can establish specific properties that are applicable to all tokens generated within the collection, such as forcing all tokens into the forced collapsing supply mode and configuring royalties for the entire collection for future marketplace interactions." }, multitoken: { name: "MultiToken", definition: "A token stored in the MultiTokens pallet is usually referred to as a \"MultiToken\".\nMultiTokens is a Pallet on the Enjin Blockchain designed for token creation.\nSimilar to the ERC-1155 standard on Ethereum, MultiTokens supports both NFTs (Non-Fungible Tokens) and Multi-Unit Tokens within a single framework. However, unlike ERC-1155, MultiTokens is integrated as a native pallet on the Enjin Blockchain, allowing users to create tokens quickly and securely without the need to deploy smart contracts." }, enjin_platform_cloud: { name: "Enjin Platform Cloud", definition: "A cloud hosted Enjin Platform that allows you to kickstart your next NFT project in just a few minutes. Ran on Enjin's robust servers, yet fully secure and isolated to your unique project instance, you can launch your NFT game with a few simple steps. Just create an account, set it up, generate your first API key, and voila! Your NFT game is operational." }, + hot_inventory: { name: "Hot Inventory", definition: "A player's off-chain inventory, stored in the game's own database rather than on the blockchain. Items in the hot inventory can be used, consumed, or modified instantly — exactly like items in a traditional, non-blockchain game — because acting on them does not require an on-chain transaction. The trade-off is that hot items have no on-chain representation, so they cannot be traded or transferred until they are moved into the player's cold inventory. See the Hot & Cold Inventories guide." }, + cold_inventory: { name: "Cold Inventory", definition: "A player's on-chain inventory — in practice, their blockchain wallet, whether a managed wallet created for them or a self-custodial wallet they connect. Items in the cold inventory are real tokens the player truly owns and can trade or transfer, but acting on them requires an on-chain transaction that takes a few seconds to finalize. This contrasts with the hot inventory, which is instant but off-chain. See the Hot & Cold Inventories guide." }, + mintable_item: { name: "Mintable Item", definition: "A game item that can exist as an on-chain token, and can therefore be moved between a player's hot (off-chain) and cold (on-chain) inventories. Mintable items suit anything players will trade or want to truly own, such as rare gear or cosmetics. This contrasts with a non-mintable item, which lives off-chain only." }, + non_mintable_item: { name: "Non-Mintable Item", definition: "A game item that has no on-chain token and lives only in the off-chain hot inventory. Non-mintable items suit high-churn, low-value items — common consumables, ammunition, or soft currency — where putting them on-chain would add cost and overhead for no real benefit. This contrasts with a mintable item, which can move on-chain." }, }; export default glossary; From fb5823445490602dafaa4e1d041faafdffbb6b6b Mon Sep 17 00:00:00 2001 From: Etay Matzliah Date: Thu, 4 Jun 2026 20:09:51 +0300 Subject: [PATCH 2/6] Drop premature managed-wallet callout from Hot & Cold Inventories The 'A managed wallet doesn't fix this' warning pre-empted an objection the reader hasn't formed yet and referenced moving items between two wallets before the hot/cold move is introduced. The substantive point (a second/managed on-chain wallet is still slow) is already made in context by the later 'One wallet per player, not two' tip. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../03-advanced-mechanics/07-hot-cold-inventories.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/02-guides/01-platform/03-advanced-mechanics/07-hot-cold-inventories.md b/docs/02-guides/01-platform/03-advanced-mechanics/07-hot-cold-inventories.md index 81b9ec7..cdff473 100644 --- a/docs/02-guides/01-platform/03-advanced-mechanics/07-hot-cold-inventories.md +++ b/docs/02-guides/01-platform/03-advanced-mechanics/07-hot-cold-inventories.md @@ -14,10 +14,6 @@ Real-time games are full of **atomic actions** — things that have to resolve * On-chain, every state change is a that has to be included in a block and then finalized. That takes seconds, not milliseconds. Put a consumable's on-chain on the critical path of combat and the game becomes unplayable. -:::warning A managed wallet doesn't fix this -It's tempting to think a second, platform-controlled wallet makes actions instant. It doesn't. A [managed wallet](/02-guides/01-platform/02-managing-users/03-using-managed-wallets.md) is a **real on-chain account** — the platform simply custodies its keys and signs on its behalf. Consuming a token from a managed wallet is still an on-chain transaction with the same finalization latency as any other. Moving an item between two wallets changes *who signs* and *where it lives*, not *whether the action touches the chain*. -::: - The fix isn't to make the chain faster — it's to keep real-time actions **off** the chain entirely, and use the chain only for what it's uniquely good at: **ownership and settlement.** ## The model: hot and cold inventories From 4db1e02c8aee242074f7df910c22b23f0624c58d Mon Sep 17 00:00:00 2001 From: Etay Matzliah Date: Thu, 4 Jun 2026 20:35:13 +0300 Subject: [PATCH 3/6] Tighten Hot & Cold Inventories: drop conversational callouts, fix links and jargon - Remove the 'One wallet per player, not two' and 'Items stay hot between sessions' callouts: both only made sense as rebuttals to ideas raised while drafting, and answer questions a fresh reader hasn't asked. - Replace WalletConnect links with the native wallet-request flow (sending-wallet-requests), which is the direction the docs are moving; link the linking step to its Step 1 anchor. - Replace the unexplained 'boundary' jargon with explicit 'between inventories' wording. - Minor phrasing tightening in the hot-ledger pitfall. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../07-hot-cold-inventories.md | 22 ++++++------------- 1 file changed, 7 insertions(+), 15 deletions(-) diff --git a/docs/02-guides/01-platform/03-advanced-mechanics/07-hot-cold-inventories.md b/docs/02-guides/01-platform/03-advanced-mechanics/07-hot-cold-inventories.md index cdff473..319f20f 100644 --- a/docs/02-guides/01-platform/03-advanced-mechanics/07-hot-cold-inventories.md +++ b/docs/02-guides/01-platform/03-advanced-mechanics/07-hot-cold-inventories.md @@ -33,7 +33,7 @@ By default, items live **hot**: they're earned, bought, and used entirely off-ch *Cold inventory* is just a friendlier, player-facing name for the player's on-chain wallet — a managed wallet you create for them, or a self-custodial wallet they connect. *Hot inventory* is not a wallet at all; it's rows in your own database. ::: -One rule keeps the whole scheme honest: **a unit is either hot or cold, never both.** Moving an item across the boundary destroys it on one side as it's created on the other. As a result, the on-chain supply of a token always equals "the number of units currently held cold" — the hot units have no on-chain existence. +One rule keeps the whole scheme honest: **a unit is either hot or cold, never both.** Moving an item between the two inventories removes it from one and recreates it in the other. As a result, the on-chain supply of a token always equals "the number of units currently held cold" — the hot units have no on-chain existence. ## Deciding what goes where @@ -69,7 +69,7 @@ The lifecycle of a mintable item: - **Move to hot** ("bring it in to use") → melt (burn) the token from the cold wallet, and — once the transaction is finalized — credit the hot ledger. - **Use from hot** → an off-chain decrement. Instant. -The key insight: the on-chain transaction happens at the **move**, not at the **use**. A player moves a stack of 50 potions to hot once (a single melt), then consumes them instantly for the rest of the session. You pay the latency once, at the boundary — and you hide it behind a **cooldown**, the same "item is recharging" feedback players already understand. Use a for stackable consumables so an entire stack crosses the boundary in one transaction. +The key insight: the on-chain transaction happens at the **move**, not at the **use**. A player moves a stack of 50 potions to hot once (a single melt), then consumes them instantly for the rest of the session. You pay the latency once, when the item moves between inventories — and you hide it behind a **cooldown**, the same "item is recharging" feedback players already understand. Use a for stackable consumables so an entire stack moves in one transaction. :::note Naming the move for players This guide calls it "moving" an item between inventories. In your game's UI, call it whatever fits — many games use something like "teleport" or "warp." If you use **teleport**, be aware it's unrelated to Enjin's **ENJ teleport** (which moves ENJ between the Matrixchain and Relaychain); choose wording that won't confuse players who also hold ENJ. @@ -77,13 +77,9 @@ This guide calls it "moving" an item between inventories. In your game's UI, cal ## Worked example on the Enjin Platform -### Cold inventory: one wallet per player +### Cold inventory: the player's wallet -Each player gets a single on-chain wallet that acts as their cold inventory — either a [managed wallet](/02-guides/01-platform/02-managing-users/03-using-managed-wallets.md) you create for them (`CreateManagedWallet(externalId: "player-115")`), or a self-custodial wallet they [connect with WalletConnect](/02-guides/01-platform/02-managing-users/01-connecting-user-wallets/02-using-wallet-connect.md). - -:::tip One wallet per player, not two -You don't need separate "hot" and "cold" wallets. The hot inventory is rows in your own database; the cold inventory is the player's single on-chain wallet. A second on-chain wallet would just add a second slow account — it wouldn't make anything instant. -::: +Each player gets an on-chain wallet that acts as their cold inventory — either a [managed wallet](/02-guides/01-platform/02-managing-users/03-using-managed-wallets.md) you create for them (`CreateManagedWallet(externalId: "player-115")`), or a self-custodial wallet they [link to your application](/02-guides/01-platform/02-managing-users/01-connecting-user-wallets/01-sending-wallet-requests.md#step-1--linking-a-players-wallet). ### Hot inventory: your database @@ -127,7 +123,7 @@ query ConfirmMove { See [Working with Events](/05-enjin-platform/03-working-with-events.md) for the full finalization-and-events workflow. (Real-time push events that remove the need to poll are [planned](/03-api-reference/03-websocket-events.md).) -For a **self-custodial** cold wallet, your server can't sign the melt — the player approves it in their own wallet via WalletConnect instead. +For a **self-custodial** cold wallet, your server can't sign the melt — instead, the player approves it in their own Enjin Wallet app via a [wallet request](/02-guides/01-platform/02-managing-users/01-connecting-user-wallets/01-sending-wallet-requests.md). ### Move to cold — mint to the cold wallet @@ -156,11 +152,7 @@ mutation MoveToCold { ### Move several items at once -If a player crosses the boundary with several different item types at once — a "withdraw everything to my wallet" button, say — bundle the actions into a single [`CreateBatchTransaction`](/03-api-reference/02-mutations/01-transaction-mutations.md) so they settle atomically with one fee instead of many. - -:::info Items stay hot between sessions -There's no need to push unused items back to cold when a player logs off. The hot inventory *is* their everyday inventory and persists across sessions. Crossing to cold is always something the player chooses to do — to trade or self-custody an item — never an automatic step. -::: +If a player moves several different item types between inventories at once — a "withdraw everything to my wallet" button, say — bundle the actions into a single [`CreateBatchTransaction`](/03-api-reference/02-mutations/01-transaction-mutations.md) so they settle atomically with one fee instead of many. ### Cover the fees @@ -171,7 +163,7 @@ Moving to hot melts a token from the player's wallet, which needs ENJ to pay Date: Thu, 4 Jun 2026 20:38:44 +0300 Subject: [PATCH 4/6] Reframe supply-cap pitfall around two-way vs one-way item movement Replaces the blanket 'don't use Collapsing Supply for mintable items' with guidance to match the cap to the movement pattern: fixed supply for items that round-trip between hot and cold (so they can be re-minted), Collapsing Supply for one-way items minted to cold once (e.g. a non-consumable sword). Links Collapsing Supply to the enforced-rarity guide. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../03-advanced-mechanics/07-hot-cold-inventories.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/02-guides/01-platform/03-advanced-mechanics/07-hot-cold-inventories.md b/docs/02-guides/01-platform/03-advanced-mechanics/07-hot-cold-inventories.md index 319f20f..b5658ba 100644 --- a/docs/02-guides/01-platform/03-advanced-mechanics/07-hot-cold-inventories.md +++ b/docs/02-guides/01-platform/03-advanced-mechanics/07-hot-cold-inventories.md @@ -162,7 +162,9 @@ Moving to hot melts a token from the player's wallet, which needs ENJ to pay Date: Thu, 4 Jun 2026 20:50:40 +0300 Subject: [PATCH 5/6] Add backlinks to Hot & Cold Inventories from related guides Adds inbound links so the new pattern is discoverable from where readers hit the problem: the Enjin Farmer breakdown (as the production follow-up to its on-chain melts), Using Managed Wallets (cold inventory), Melting/Burning Tokens (the move-to-hot operation), and Sending Wallet Requests (instant alternative to on-chain consumption). Phrased as 'can be used as/to' rather than asserting one canonical use. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../01-managing-tokens/08-burning-destroying-tokens.md | 4 ++++ .../01-connecting-user-wallets/01-sending-wallet-requests.md | 2 +- .../01-platform/02-managing-users/03-using-managed-wallets.md | 4 ++++ .../03-implementation-breakdown.md | 1 + 4 files changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/02-guides/01-platform/01-managing-tokens/08-burning-destroying-tokens.md b/docs/02-guides/01-platform/01-managing-tokens/08-burning-destroying-tokens.md index 10567ec..5099c19 100644 --- a/docs/02-guides/01-platform/01-managing-tokens/08-burning-destroying-tokens.md +++ b/docs/02-guides/01-platform/01-managing-tokens/08-burning-destroying-tokens.md @@ -11,6 +11,10 @@ import TabItem from '@theme/TabItem'; "Melting" (often called "Burning") refers to the process of decreasing a token's supply and removing it from circulation, or in some cases, even removing the token from the blockchain entirely. Melting a token with releases the Infused ENJ to the holder. +:::tip Common pattern: hot & cold inventories +In real-time games, melting can be used to move an item out of a player's on-chain ("cold") inventory so it can be used instantly in an off-chain ("hot") one. See [Hot & Cold Inventories](/02-guides/01-platform/03-advanced-mechanics/07-hot-cold-inventories.md). +::: + :::info What you'll need: - Some [Enjin Coin](/06-enjin-products/02-enjin-coin.md) on Enjin Matrixchain to pay for . You can obtain cENJ (Canary ENJ) for testing from the [built-in Canary faucet](/01-getting-started/04-using-the-enjin-platform.md#canary-faucet) in the Platform UI. diff --git a/docs/02-guides/01-platform/02-managing-users/01-connecting-user-wallets/01-sending-wallet-requests.md b/docs/02-guides/01-platform/02-managing-users/01-connecting-user-wallets/01-sending-wallet-requests.md index 25d1860..bb7f057 100644 --- a/docs/02-guides/01-platform/02-managing-users/01-connecting-user-wallets/01-sending-wallet-requests.md +++ b/docs/02-guides/01-platform/02-managing-users/01-connecting-user-wallets/01-sending-wallet-requests.md @@ -50,7 +50,7 @@ The transactions a player can sign are the same ones your application's Wallet D ### Consume an in-game item -Send a request to burn a **Health Potion** NFT the player owns. On `FINALIZED`, your game reads the `MultiTokens.Burned` event, confirms the burn matched the player's wallet and the potion's token id, and restores their HP in-game. The same pattern covers any "consume" action — eat food, drink mana, use a one-shot scroll. +Send a request to burn a **Health Potion** NFT the player owns. On `FINALIZED`, your game reads the `MultiTokens.Burned` event, confirms the burn matched the player's wallet and the potion's token id, and restores their HP in-game. The same pattern covers any "consume" action — eat food, drink mana, use a one-shot scroll. Because each consume is an on-chain burn that needs the player's approval and a few seconds to finalize, this fits deliberate actions rather than split-second use in fast-paced games. For instant consumption, see [Hot & Cold Inventories](/02-guides/01-platform/03-advanced-mechanics/07-hot-cold-inventories.md). ### List an item on the marketplace diff --git a/docs/02-guides/01-platform/02-managing-users/03-using-managed-wallets.md b/docs/02-guides/01-platform/02-managing-users/03-using-managed-wallets.md index db0f1ee..3a168c6 100644 --- a/docs/02-guides/01-platform/02-managing-users/03-using-managed-wallets.md +++ b/docs/02-guides/01-platform/02-managing-users/03-using-managed-wallets.md @@ -21,6 +21,10 @@ Here's how the typical flow works: This process ensures that users can interact with blockchain assets seamlessly within your application without needing to understand the underlying complexities of blockchain technology or operating his own crypto wallet. +:::tip Building a real-time game? +A managed wallet can serve as a player's on-chain **cold inventory**. For fast-paced games where some items must be used the instant a player taps them (drinking a potion mid-fight), you can pair it with an off-chain **hot inventory** so consumption never waits on the chain. See [Hot & Cold Inventories](/02-guides/01-platform/03-advanced-mechanics/07-hot-cold-inventories.md) to understand the pattern. +::: + :::info What you'll need: - Some [Enjin Coin](/06-enjin-products/02-enjin-coin.md) on Enjin Matrixchain to pay for . You can obtain cENJ (Canary ENJ) for testing from the [built-in Canary faucet](/01-getting-started/04-using-the-enjin-platform.md#canary-faucet) in the Platform UI. diff --git a/docs/02-guides/01-platform/05-enjin-farmer-sample-game/03-implementation-breakdown.md b/docs/02-guides/01-platform/05-enjin-farmer-sample-game/03-implementation-breakdown.md index 8171c6d..21bd94d 100644 --- a/docs/02-guides/01-platform/05-enjin-farmer-sample-game/03-implementation-breakdown.md +++ b/docs/02-guides/01-platform/05-enjin-farmer-sample-game/03-implementation-breakdown.md @@ -21,6 +21,7 @@ Before you begin, please keep the following in mind: * **Demonstration Purpose:** This is a simplified example designed to showcase a basic integration. It is **not suitable for a production environment** as is. * **WebSockets:** This implementation does not use [WebSocket events](/03-api-reference/03-websocket-events.md). In a real-world application, WebSockets can simplify the process of listening for transaction finalization and receiving real-time updates, such as when a user receives an NFT from an external source like the marketplace. * **Wallet Funding:** New managed wallets are created without any funds. To cover network fees for actions like melting or transferring tokens, you must either fund each wallet individually or use a [Fuel Tank](/02-guides/01-platform/02-managing-users/04-using-fuel-tanks.md) to subsidize transactions for all your users. + * **On-chain actions aren't instant:** This sample melts and mints on-chain whenever items change hands, which takes seconds to finalize — fine for a farming demo, but unplayable for real-time action. For a production pattern that keeps item use instant while preserving on-chain ownership, see [Hot & Cold Inventories](/02-guides/01-platform/03-advanced-mechanics/07-hot-cold-inventories.md). ----- From 6811cc64f535dbd83a842722bc2a7e21e370bce8 Mon Sep 17 00:00:00 2001 From: Etay Matzliah Date: Thu, 4 Jun 2026 20:54:22 +0300 Subject: [PATCH 6/6] Remove melting-page backlink to Hot & Cold Inventories Drops the tip added on the melting/burning page in b90ad2c, per request. The other three backlinks (managed wallets, Enjin Farmer breakdown, sending wallet requests) remain. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../01-managing-tokens/08-burning-destroying-tokens.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/02-guides/01-platform/01-managing-tokens/08-burning-destroying-tokens.md b/docs/02-guides/01-platform/01-managing-tokens/08-burning-destroying-tokens.md index 5099c19..10567ec 100644 --- a/docs/02-guides/01-platform/01-managing-tokens/08-burning-destroying-tokens.md +++ b/docs/02-guides/01-platform/01-managing-tokens/08-burning-destroying-tokens.md @@ -11,10 +11,6 @@ import TabItem from '@theme/TabItem'; "Melting" (often called "Burning") refers to the process of decreasing a token's supply and removing it from circulation, or in some cases, even removing the token from the blockchain entirely. Melting a token with releases the Infused ENJ to the holder. -:::tip Common pattern: hot & cold inventories -In real-time games, melting can be used to move an item out of a player's on-chain ("cold") inventory so it can be used instantly in an off-chain ("hot") one. See [Hot & Cold Inventories](/02-guides/01-platform/03-advanced-mechanics/07-hot-cold-inventories.md). -::: - :::info What you'll need: - Some [Enjin Coin](/06-enjin-products/02-enjin-coin.md) on Enjin Matrixchain to pay for . You can obtain cENJ (Canary ENJ) for testing from the [built-in Canary faucet](/01-getting-started/04-using-the-enjin-platform.md#canary-faucet) in the Platform UI.