@xgamesfun/solana 0.26.1 → 0.26.2

package/README.md

@@ -64,7 +64,7 @@ codex plugin add xsolana@xgamesfun
 
 **claude.ai, ChatGPT or Claude Desktop:** add `https://xgames.fun/mcp` as a custom connector. Nothing to install.
 
-**Cursor, Cline, opencode or any MCP client:** run `npx -y --package=@xgamesfun/solana@0.26.1 xsolana mcp`.
+**Cursor, Cline, opencode or any MCP client:** run `npx -y --package=@xgamesfun/solana@0.26.2 xsolana mcp`.
 
 **Any agent that reads skills** (Copilot, Gemini CLI, Windsurf…): `npx skills add XGamesFun/solana-kit`.
 
@@ -75,19 +75,19 @@ are in [docs/harnesses.md](docs/harnesses.md).
 
 ```bash
 # find a worked example close to your idea
-npx -y @xgamesfun/solana@0.26.1 examples shop with loot boxes
+npx -y @xgamesfun/solana@0.26.2 examples shop with loot boxes
 
 # does it work? where does the money go? what does it cost?
-npx -y @xgamesfun/solana@0.26.1 check xsolana.json
-npx -y @xgamesfun/solana@0.26.1 simulate xsolana.json
-npx -y @xgamesfun/solana@0.26.1 cost xsolana.json
+npx -y @xgamesfun/solana@0.26.2 check xsolana.json
+npx -y @xgamesfun/solana@0.26.2 simulate xsolana.json
+npx -y @xgamesfun/solana@0.26.2 cost xsolana.json
 
 # the whole economy in plain words, and what a cheater could get
-npx -y @xgamesfun/solana@0.26.1 explain xsolana.json
-npx -y @xgamesfun/solana@0.26.1 review xsolana.json
+npx -y @xgamesfun/solana@0.26.2 explain xsolana.json
+npx -y @xgamesfun/solana@0.26.2 review xsolana.json
 
 # go live, approved in your own wallet
-npx -y @xgamesfun/solana@0.26.1 approve xsolana.json
+npx -y @xgamesfun/solana@0.26.2 approve xsolana.json
 ```
 
 Each command names an exact version, so you always run the release you meant to. `xsolana help` lists them all.

package/js/chain/metadata.js

@@ -0,0 +1,76 @@
+// A token's name on chain: its Token Metadata record (Metaplex), where wallets and explorers read a classic SPL
+// token's name, ticker and picture link. Only what a setup needs: the record of a fungible token whose mint is made
+// already. Token Metadata takes it only from the mint's authority, so it is made while that authority can still sign:
+// once minting is handed on or turned off, no record can ever be made for the mint.
+import { addressBytes, encodeBase58 } from './base58.js';
+import { concat, uintLE, utf8 } from './bytes.js';
+import { METAPLEX_METADATA_PROGRAM, pdaOf, SYSTEM_PROGRAM, SYSVAR_INSTRUCTIONS, TOKEN_PROGRAM } from './pda.js';
+import { meta } from './programs.js';
+
+/** A record's size: Token Metadata pads every one to it, whatever its name, ticker and link. */
+export const METADATA_BYTES = 607;
+/** What Token Metadata keeps in each record it makes, on top of the record's rent: its own fee. */
+export const METADATA_FEE = 10_000_000n;
+/** The longest name, ticker and link a record takes, in UTF-8 bytes. */
+export const METADATA_LIMITS = Object.freeze({ name: 32, symbol: 10, uri: 200 });
+
+const CREATE = 42;
+const CREATE_V1 = 0;
+const FUNGIBLE = 2;
+const NONE = Uint8Array.of(0);
+const text = s => concat(uintLE(utf8(s).length, 4), utf8(s));
+
+/** The address of a mint's Token Metadata record. */
+export const metadataAddress = mint =>
+  pdaOf([utf8('metadata'), addressBytes(METAPLEX_METADATA_PROGRAM), addressBytes(mint)], METAPLEX_METADATA_PROGRAM);
+
+/**
+ * Token Metadata's CreateV1 for a fungible token whose mint exists: its name, its ticker and a link to a JSON file with
+ * its picture ('' for none). `authority` is the mint's authority and signs; it becomes the record's update authority,
+ * the only one who can change the record later. `payer` pays its rent and Token Metadata's fee (`METADATA_FEE`).
+ * The mint is listed read-only: this path of Token Metadata writes nothing to a mint that exists. That is the
+ * program's behaviour, not a lock: in a setup's own transaction the mint is writable all the same (the same
+ * transaction makes it), so the tests read its supply and authorities back after the record is made. The record says
+ * a fungible token whatever the decimals (CreateMetadataAccountV3 would call one of 0 decimals an asset, which
+ * wallets list with collectibles).
+ */
+export function createFungibleMetadataIx({ mint, authority, payer = authority, name, symbol, uri = '' }) {
+  for (const [field, value] of Object.entries({ name, symbol, uri })) {
+    if (typeof value !== 'string') throw new TypeError(`A token's ${field} is text`);
+    if (utf8(value).length > METADATA_LIMITS[field])
+      throw new RangeError(`A token's ${field} is at most ${METADATA_LIMITS[field]} bytes`);
+  }
+  return {
+    programId: METAPLEX_METADATA_PROGRAM,
+    keys: [
+      meta(metadataAddress(mint), false, true),
+      meta(METAPLEX_METADATA_PROGRAM, false, false), // no edition: a fungible token has none
+      meta(mint, false, false),
+      meta(authority, true, false),
+      meta(payer, true, true),
+      meta(authority, true, false), // the update authority
+      meta(SYSTEM_PROGRAM, false, false),
+      meta(SYSVAR_INSTRUCTIONS, false, false),
+      meta(TOKEN_PROGRAM, false, false),
+    ],
+    data: concat(
+      Uint8Array.of(CREATE, CREATE_V1),
+      text(name),
+      text(symbol),
+      text(uri),
+      uintLE(0, 2), // no resale royalty
+      NONE, // no creators
+      Uint8Array.of(0, 1), // no primary sale yet; the record can be changed
+      Uint8Array.of(FUNGIBLE),
+      NONE, // no collection
+      NONE, // no uses
+      NONE, // no collection details
+      NONE, // no rule set
+      NONE, // decimals: the mint's own
+      NONE, // no print supply
+    ),
+  };
+}
+
+/** The update authority a Token Metadata record names (who can change its name, ticker and link). */
+export const metadataUpdateAuthority = data => (data?.length >= 33 ? encodeBase58(data.subarray(1, 33)) : null);

package/js/economy/check.mjs

@@ -14,6 +14,7 @@ import { TOKEN_2022_PROGRAM, TOKEN_PROGRAM } from '../chain/pda.js';
 import { addressBytes, encodeBase58 } from '../chain/base58.js';
 import { isOnCurve } from '../chain/curve.js';
 import { utf8 } from '../chain/bytes.js';
+import { METADATA_LIMITS } from '../chain/metadata.js';
 import { sha256 } from '../chain/sha256.js';
 import {
   FEES,
@@ -1013,6 +1014,33 @@ export function check(
         `“${t.key}” is a token the project makes when the economy goes live, but it names the mint ${t.mint}: the setup would never make it, and would mint from an address the project has no say over.`,
         'Remove "mint" for a token the setup makes, or make it an existing token (source "existing", with its "decimals").',
       );
+    // A token the setup makes is named on chain as it is made (its Token Metadata record), and the record takes so
+    // many bytes of each, not characters: a longer one would be refused on chain, in the middle of going live. One
+    // with no name or ticker at all would be written blank, and show as an unknown token for the record's price. A
+    // token that is live already is not named again: its words here stay labels, as they were.
+    if (source === 'game' && !economy.live?.mints?.[t.key])
+      for (const [field, what] of [
+        ['name', 'name'],
+        ['symbol', 'ticker'],
+        ['uri', 'link'],
+      ]) {
+        const value = String(tok[field] ?? '');
+        const bytes = utf8(value).length;
+        if (bytes > METADATA_LIMITS[field])
+          refuse(
+            'E-TOKEN',
+            `${where}.${field}`,
+            `The ${what} of “${t.key}” is ${bytes} bytes, and a token’s ${what} on chain is at most ${METADATA_LIMITS[field]} (a letter outside plain English takes two or more).`,
+            `Shorten it to ${METADATA_LIMITS[field]} bytes${field === 'uri' ? ', for instance with a shorter path or host' : ''}.`,
+          );
+        else if (field !== 'uri' && !value.trim())
+          refuse(
+            'E-TOKEN',
+            `${where}.${field}`,
+            `“${t.key}” has an empty ${what}: going live writes it on chain as it is, and wallets would show a token with no ${what}.`,
+            `Give it a ${what}, or leave "${field}" out (${field === 'symbol' ? 'its key in capitals is used' : 'its ticker is used'}).`,
+          );
+      }
     if (t.supply !== undefined && source !== 'game')
       refuse(
         'E-TOKEN',

package/js/economy/cost.mjs

@@ -47,11 +47,19 @@ export function setupCost(plan, economy) {
   const m = model(economy);
   // An account that grows (a live stash taking more NFTs) pays rent for its new bytes only.
   const rentOf = c => (c.grows ? BigInt(c.bytes) * RENT_PER_BYTE : rent(c.bytes));
+  // `fee`: what the program that makes an account keeps in it on top of its rent (Token Metadata's, for a token's name
+  // on chain). It is not rent: it never comes back.
   const accounts = plan.transactions
     .flatMap(t => t.steps)
     .flatMap(s => s.creates ?? [])
-    .map(c => ({ ...c, lamports: rentOf(c).toString(), sol: sol(rentOf(c)) }));
+    .map(c => ({
+      ...c,
+      lamports: rentOf(c).toString(),
+      sol: sol(rentOf(c)),
+      ...(c.fee ? { feeSol: sol(BigInt(c.fee)) } : {}),
+    }));
   const rentLamports = accounts.reduce((n, a) => n + BigInt(a.lamports), 0n);
+  const metadataLamports = accounts.reduce((n, a) => n + BigInt(a.fee ?? 0), 0n);
   const charged = plan.transactions.flatMap(t => t.steps).filter(s => !NO_FEE_STEP.test(s.id));
   const feeLamports = BigInt(charged.length) * FEES.project;
   const networkLamports = plan.transactions.reduce((n, t) => n + BigInt(t.signers.length) * SIGNATURE_FEE, 0n);
@@ -76,7 +84,7 @@ export function setupCost(plan, economy) {
   for (const l of m.lotteries) if (steps.has(`rent:lottery:${l.key}`)) seedLamports += roundRentOf(l, m);
   for (const sc of m.schedules)
     if (sc.sealed && (sc.fundFrom ?? 'wallet') === 'wallet') putIn(sc.currency, sc.fund, `fund:${sc.key}`);
-  const total = rentLamports + feeLamports + networkLamports + seedLamports;
+  const total = rentLamports + metadataLamports + feeLamports + networkLamports + seedLamports;
   const notes = [];
   if (accounts.some(a => a.approx))
     notes.push('Accounts marked “about” are sized roughly (a Core collection or an external token account).');
@@ -96,6 +104,7 @@ export function setupCost(plan, economy) {
   return {
     accounts,
     rentSol: sol(rentLamports),
+    metadataFeesSol: sol(metadataLamports),
     programFeesSol: sol(feeLamports),
     networkFeesSol: sol(networkLamports),
     seeds,
@@ -483,6 +492,8 @@ export function explainCost(c) {
   ];
   lines.push(
     `  rent ${s.rentSol} SOL for ${s.accounts.length} accounts; program fees ${s.programFeesSol} SOL; network fees ${s.networkFeesSol} SOL${
+      s.metadataFeesSol ? `; Token Metadata’s fees ${s.metadataFeesSol} SOL (a token’s name on chain)` : ''
+    }${
       Object.keys(s.seeds).length
         ? `; seeds ${Object.entries(s.seeds)
             .map(([k, v]) => `${v} ${k}`)
@@ -490,7 +501,10 @@ export function explainCost(c) {
         : ''
     }.`,
   );
-  for (const a of s.accounts) lines.push(`  ${a.approx ? 'about ' : ''}${a.sol} SOL: ${a.what} (${a.bytes} bytes)`);
+  for (const a of s.accounts)
+    lines.push(
+      `  ${a.approx ? 'about ' : ''}${a.sol} SOL: ${a.what} (${a.bytes} bytes)${a.feeSol ? `, and ${a.feeSol} SOL Token Metadata keeps for it` : ''}`,
+    );
   lines.push('While it runs (for a player, quote the “in all” number: it is what leaves their wallet for good):');
   for (const r of c.actions) {
     const deposits = r.deposits.map(d => `${d.sol} SOL for ${d.what} (back: ${d.back})`).join('; ');

package/js/economy/explain.mjs

@@ -204,6 +204,18 @@ export function explainEconomy(economy, { now = Math.floor(Date.now() / 1000) }
   );
   if (economy.prompt) lines.push(`Asked for: “${economy.prompt}”`);
 
+  // A token the setup makes is named on chain as it is made (plan.mjs): what wallets will show, and that a picture
+  // needs its link before going live. One that is live already keeps what it has.
+  section(
+    'The tokens going live makes',
+    [...m.tokens.values()]
+      .filter(t => t.source === 'game' && !economy.live?.mints?.[t.key])
+      .map(
+        t =>
+          `${t.symbol}${t.name !== t.symbol ? ` (“${t.name}”)` : ''}: ${t.fixedSupply ? `a fixed supply of ${num(t.supply)}, all of it to your wallet, and no more ever` : 'minted by the project as its rules say'}. It is named on chain as it is made, so wallets show ${t.uri ? 'its name, its ticker and the picture its link gives' : 'its name and ticker and no picture: for one, give it a `uri` (a link to a JSON file that names its `image`) before going live'}. Only your wallet can change the name, ticker and link later, and these tools don’t change a live token’s yet: get them right first.`,
+      ),
+  );
+
   const fee = num(sim.fees.playerSol);
   const actions = [];
   for (const it of sim.items) {
@@ -559,6 +571,8 @@ export function explainEconomy(economy, { now = Math.floor(Date.now() / 1000) }
   lines.push('', 'What setting it up costs');
   lines.push(
     `- About ${num(s.totalSol)} SOL in all, in ${plural(s.transactions, 'transaction')} (${plural(s.approvals, 'wallet approval')}): rent ${num(s.rentSol)} SOL for ${plural(s.accounts.length, 'account')}, program fees ${num(s.programFeesSol)} SOL, network fees ${num(s.networkFeesSol)} SOL${
+      s.metadataFeesSol ? `, Token Metadata’s fees ${num(s.metadataFeesSol)} SOL (a token’s name on chain)` : ''
+    }${
       Object.keys(s.seeds).length
         ? `, seeds ${Object.entries(s.seeds)
             .map(([k, v]) => `${num(v)} ${k}`)

package/js/economy/guide.mjs

@@ -10,7 +10,7 @@ const sol = lamports => Number(lamports) / Number(LAMPORTS_PER_SOL);
 export const PARTS = {
   tokens: {
     def: 'token',
-    says: 'The currencies: SOL, any existing mint by address (classic or Token-2022, coins from a token launchpad or an AMM included), or a token the game makes when it goes live: one the game mints as its rules say (points, tickets, shards, an emission), or one with a fixed `supply` minted once to the owner with minting turned off for good (a community token you keep). loot does not put a token on a market: for trading, launch it on a token launchpad or an AMM, then name the mint.',
+    says: 'The currencies: SOL, any existing mint by address (classic or Token-2022, coins from a token launchpad or an AMM included), or a token the game makes when it goes live: one the game mints as its rules say (points, tickets, shards, an emission), or one with a fixed `supply` minted once to the owner with minting turned off for good (a community token you keep). A token the game makes is named on chain as it is made (`name`, `symbol`, and `uri`: a link to a JSON file naming its picture), which is what wallets show; only the owner’s wallet can change that later, and changing them in a spec that is already live changes nothing on chain yet. loot does not put a token on a market: for trading, launch it on a token launchpad or an AMM, then name the mint.',
     acts: 'nobody: a token is a fact',
   },
   currency: {

package/js/economy/plan.mjs

@@ -1,7 +1,8 @@
 // The setup plan: every instruction that puts an economy live on loot, in order, built with the client and
 // packed into transactions that fit. Nothing here signs or talks to the chain. Pure.
 //
-// A step is { id, part, says, signers, creates: [{ what, bytes }], build(ctx) → instructions }. `ctx` names the
+// A step is { id, part, says, signers, creates: [{ what, bytes, fee? }], build(ctx) → instructions } (`fee`: lamports
+// the program that makes the account keeps in it, on top of its rent: Token Metadata's). `ctx` names the
 // addresses a step needs: { owner, authority, project, collection, tree, treasury, mints: { tokenKey: mint }, keys: {
 // name: address } } where `keys` are the fresh keys this setup makes ("new:collection", "new:tree", "new:mint/points"), each of
 // which signs the step that creates it. `placeholderContext` fills every address with a stand-in, so a plan can be
@@ -20,6 +21,7 @@ import {
   TOKEN_PROGRAM,
 } from '../chain/pda.js';
 import { createTableIx, extendTableIx } from '../chain/lookup.js';
+import { createFungibleMetadataIx, METADATA_BYTES, METADATA_FEE, METADATA_LIMITS } from '../chain/metadata.js';
 import { MEMO_PROGRAM } from '../chain/token2022.js';
 import {
   computeUnitLimit,
@@ -732,18 +734,40 @@ export function setupSteps(economy, { now = 0, only = null, live: given = null }
   const fresh = !live?.project;
 
   // Tokens the project mints: a classic mint with the owner as its authority, handed to the project right after.
+  // Each is named on chain in the same step (its Token Metadata record: the name, the ticker and the link wallets
+  // show), while the owner is still its mint authority: Token Metadata takes a record from nobody else, so a mint whose
+  // minting was handed on or turned off without one can never have one. The owner stays the record's update authority.
   for (const t of m.tokens.values()) {
     if (t.source !== 'game' || live?.mints?.[t.key] || (t.mint && !t.mint.startsWith('@'))) continue;
     const key = `new:mint/${t.key}`;
+    const named = `write its name on chain (“${t.name}”, ${t.symbol}, ${t.uri ? `with the link ${t.uri}` : 'no picture link'}: only your wallet can change it later, which these tools don’t do yet, and Token Metadata keeps ${Number(METADATA_FEE) / 1e9} SOL for it)`;
+    const record = { what: `the name of ${t.symbol} on chain`, bytes: METADATA_BYTES, fee: Number(METADATA_FEE) };
+    // The checker refuses a name, ticker or link too long for a record before any plan is made, except on a token
+    // that is live already, whose words are only labels. Such a token is made here only when a live economy is
+    // planned as if it were new (explain's cost of the whole setup, which is never sent): its record is left out.
+    const fits = ['name', 'symbol', 'uri'].every(f => utf8(String(t[f] ?? '')).length <= METADATA_LIMITS[f]);
+    const name = ctx =>
+      fits
+        ? [
+            createFungibleMetadataIx({
+              mint: ctx.keys[key],
+              authority: ctx.owner,
+              name: t.name,
+              symbol: t.symbol,
+              uri: t.uri ?? '',
+            }),
+          ]
+        : [];
     if (t.fixedSupply) {
       const supply = amount(t.supply, t);
       add({
         id: `token:${t.key}`,
         part: `token:${t.key}`,
-        says: `Make the token ${t.symbol} (${t.decimals} decimals) with a fixed supply of ${t.supply}, all of it to your wallet, then turn its minting off for good`,
+        says: `Make the token ${t.symbol} (${t.decimals} decimals) with a fixed supply of ${t.supply}, all of it to your wallet, ${named}, then turn its minting off for good`,
         signers: [owner, key],
         creates: [
           { what: `the mint of ${t.symbol}`, bytes: MINT_BYTES },
+          ...(fits ? [record] : []),
           { what: `your ${t.symbol} account`, bytes: 165 },
         ],
         build: ctx => [
@@ -755,6 +779,7 @@ export function setupSteps(economy, { now = 0, only = null, live: given = null }
             owner: TOKEN_PROGRAM,
           }),
           initializeMint2Ix({ mint: ctx.keys[key], decimals: t.decimals, authority: ctx.owner }),
+          ...name(ctx),
           createAssociatedTokenAccountIdempotent(ctx.owner, ctx.owner, ctx.keys[key]),
           mintToIx({
             mint: ctx.keys[key],
@@ -770,9 +795,9 @@ export function setupSteps(economy, { now = 0, only = null, live: given = null }
     add({
       id: `token:${t.key}`,
       part: `token:${t.key}`,
-      says: `Make the token ${t.symbol} (${t.decimals} decimals), then hand its minting to the project`,
+      says: `Make the token ${t.symbol} (${t.decimals} decimals), ${named}, then hand its minting to the project`,
       signers: [owner, key],
-      creates: [{ what: `the mint of ${t.symbol}`, bytes: MINT_BYTES }],
+      creates: [{ what: `the mint of ${t.symbol}`, bytes: MINT_BYTES }, ...(fits ? [record] : [])],
       build: ctx => [
         createAccountIx({
           from: ctx.owner,
@@ -782,6 +807,7 @@ export function setupSteps(economy, { now = 0, only = null, live: given = null }
           owner: TOKEN_PROGRAM,
         }),
         initializeMint2Ix({ mint: ctx.keys[key], decimals: t.decimals, authority: ctx.owner }),
+        ...name(ctx),
         setAuthorityIx({ account: ctx.keys[key], current: ctx.owner, newAuthority: ctx.project }),
       ],
     });

package/js/economy/schema.json

@@ -363,7 +363,7 @@
       "type": "object",
       "required": ["key", "source"],
       "additionalProperties": false,
-      "description": "A currency. `sol`: SOL (players pay in wrapped SOL). `existing`: any mint by address, launched anywhere, classic or Token-2022, pump.fun included (xgames.fun takes no share of its fees). `project` (`game` is its older spelling): a token made when the economy goes live: the project mints it as its rules say (points, tickets, shards), or, with `supply`, a fixed supply minted once to the owner (a community token you keep).",
+      "description": "A currency. `sol`: SOL (players pay in wrapped SOL). `existing`: any mint by address, launched anywhere, classic or Token-2022, pump.fun included (xgames.fun takes no share of its fees). `project` (`game` is its older spelling): a token made when the economy goes live: the project mints it as its rules say (points, tickets, shards), or, with `supply`, a fixed supply minted once to the owner (a community token you keep). A token made this way is named on chain as it is made (its `name`, `symbol` and `uri`), which is what wallets show. Only the owner's wallet can change that later, and a change to them in a spec that is already live changes nothing on chain yet.",
       "properties": {
         "key": {
           "$ref": "#/$defs/key"
@@ -401,11 +401,12 @@
           "description": "Where the token trades, recorded for the app and not read or enforced by the tools: loot doesn't launch or trade tokens. A token launched elsewhere is `existing`, by its mint. `games.fun` is the older spelling of `xgames.fun`."
         },
         "uri": {
-          "$ref": "#/$defs/link"
+          "$ref": "#/$defs/link",
+          "description": "`project` only: a link to a JSON file that names the token's picture (`{ \"name\", \"symbol\", \"image\": \"https://…\" }`), at most 200 bytes. Going live writes it on chain with the token's name and ticker; without it wallets show the name and ticker and no picture."
         },
         "image": {
           "$ref": "#/$defs/link",
-          "description": "A picture of it, recorded for the app: the tools don't read it, and the setup doesn't write it to the mint."
+          "description": "A picture of it, recorded for the app: the tools don't read it, and the setup doesn't write it on chain (what wallets show is the `image` the JSON file at `uri` names)."
         },
         "powers": {
           "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xgamesfun/solana",
-  "version": "0.26.1",
+  "version": "0.26.2",
   "mcpName": "io.github.XGamesFun/solana-kit",
   "description": "Loot boxes, gacha, shops, lotteries, auctions, NFT staking, crafting and rewards on Solana without writing a smart contract: one shared program, its JS client, a CLI, and an MCP server and skill so Claude Code, Codex or any AI agent can design, check, simulate and launch an economy.",
   "license": "Apache-2.0",

package/release.json

@@ -4,5 +4,5 @@
   "sbfBytes": 1783800,
   "sbfSha256": "af318ccfa4d2901076b85fcd1b4467b03253adf0de16e73a9dfc1ef8077b2c14",
   "idlSha256": "0e88fc826a585cf17917cbc654e33b68232771769fe9aae1d5899a257940ff47",
-  "clientSha256": "01d85ff69999efc8b0641ce684dd060cf0ad421a8e125f91d620fef50bb5aedd"
+  "clientSha256": "20e40ee24d808d10091a0bd9973c3c4883e9dd35da4a6beac97557dd85a362c8"
 }

package/skills/xsolana-economy/SKILL.md

@@ -9,8 +9,8 @@ An economy is one JSON spec (`xsolana.json` in the project) on **loot**, a Solan
 writes or deploys a contract: the spec is checked, simulated and priced by the `xsolana_*` tools, and the project's
 owner puts it live by approving in their own wallet. It runs on **devnet** until the program is audited.
 
-The tools are the `xsolana_*` MCP tools. Without MCP, the same from a terminal: `npx -y @xgamesfun/solana@0.26.1 <guide|examples|check|simulate|cost|explain|review|publish|status> [xsolana.json]`,
-or `npx -y @xgamesfun/solana@0.26.1 tool <name> '<json>'` for any tool (always with the exact version).
+The tools are the `xsolana_*` MCP tools. Without MCP, the same from a terminal: `npx -y @xgamesfun/solana@0.26.2 <guide|examples|check|simulate|cost|explain|review|publish|status> [xsolana.json]`,
+or `npx -y @xgamesfun/solana@0.26.2 tool <name> '<json>'` for any tool (always with the exact version).
 
 ## Rules (always)
 
@@ -121,7 +121,7 @@ or `npx -y @xgamesfun/solana@0.26.1 tool <name> '<json>'` for any tool (always w
    level would cost. Run it again after every change that touches a route that pays.
 9. **When they say "put it live"**: `xsolana_publish` lists every step and its cost and gives the command. Tell them to
    run it themselves in the project folder, exactly as `xsolana_publish` gives it (it names the exact version:
-   `npx -y @xgamesfun/solana@0.26.1 approve xsolana.json`; never drop the version). It opens a page on their computer where
+   `npx -y @xgamesfun/solana@0.26.2 approve xsolana.json`; never drop the version). It opens a page on their computer where
    they connect a devnet wallet and approve; what lands is written back into `xsolana.json`. You publish nothing.
 10. **After it is live**: `xsolana_status` shows each part on chain; read it before acting on what the person says
     happened. A later change is the same loop: save, publish, and the approval sends only what changed. What only the

package/skills/xsolana-economy/references/telling-the-person.md

@@ -117,6 +117,13 @@ Don'ts:
   otherwise, and until it is filled those prizes pay nothing.
 - **A token the project mints** (`source: "project"`) is how points, tickets, attempts and shards work; an existing coin
   needs its mint address and decimals from the person (ask; never guess an address).
+- **A token the setup makes is named on chain as it goes live**: its `name`, its `symbol` and its `uri` (a link to a
+  JSON file the project hosts, `{ "name", "symbol", "image": "https://…" }`), which is what wallets and explorers show.
+  Ask for the name, the ticker and a picture before going live: with no `uri` it shows by name and ticker with no
+  picture. Only the owner's wallet can change the three later (Token Metadata's rule, not loot's), and these tools
+  don't change a live token's yet, so get them right first. The record costs about 0.014 SOL (`xsolana_cost` says it:
+  rent, and 0.01 SOL Token Metadata keeps). A token that went live before the tools wrote one has none and
+  can't be given one: only a mint's own authority can name it, and its minting was handed on or turned off.
 - **NFTs the project has no authority over** (any collection but its own): they count as they are. Say that
   whatever their collection lets be written on an NFT (even by its holder) is what a gate or a boost reads, and that
   the project's notes about one (levels, uses) live in its Sheet, which the authority writes and pays for. Every

package/types/chain/metadata.d.ts

@@ -0,0 +1,40 @@
+/** A record's size: Token Metadata pads every one to it, whatever its name, ticker and link. */
+export declare const METADATA_BYTES = 607;
+/** What Token Metadata keeps in each record it makes, on top of the record's rent: its own fee. */
+export declare const METADATA_FEE = 10000000n;
+/** The longest name, ticker and link a record takes, in UTF-8 bytes. */
+export declare const METADATA_LIMITS: Readonly<{
+    name: 32;
+    symbol: 10;
+    uri: 200;
+}>;
+/** The address of a mint's Token Metadata record. */
+export declare const metadataAddress: (mint: any) => any;
+/**
+ * Token Metadata's CreateV1 for a fungible token whose mint exists: its name, its ticker and a link to a JSON file with
+ * its picture ('' for none). `authority` is the mint's authority and signs; it becomes the record's update authority,
+ * the only one who can change the record later. `payer` pays its rent and Token Metadata's fee (`METADATA_FEE`).
+ * The mint is listed read-only: this path of Token Metadata writes nothing to a mint that exists. That is the
+ * program's behaviour, not a lock: in a setup's own transaction the mint is writable all the same (the same
+ * transaction makes it), so the tests read its supply and authorities back after the record is made. The record says
+ * a fungible token whatever the decimals (CreateMetadataAccountV3 would call one of 0 decimals an asset, which
+ * wallets list with collectibles).
+ */
+export declare function createFungibleMetadataIx({ mint, authority, payer, name, symbol, uri }: {
+    authority: any;
+    mint: any;
+    name: any;
+    payer?: any;
+    symbol: any;
+    uri?: string | undefined;
+}): {
+    programId: string;
+    keys: {
+        pubkey: any;
+        isSigner: any;
+        isWritable: any;
+    }[];
+    data: Uint8Array<any>;
+};
+/** The update authority a Token Metadata record names (who can change its name, ticker and link). */
+export declare const metadataUpdateAuthority: (data: any) => string | null;

package/types/economy/cost.d.mts

@@ -2,6 +2,7 @@
 export declare function setupCost(plan: any, economy: any): {
     accounts: any;
     rentSol: any;
+    metadataFeesSol: any;
     programFeesSol: any;
     networkFeesSol: any;
     seeds: {};
@@ -51,6 +52,7 @@ export declare function cost(economy: any, { now, only, live }?: {
     setup: {
         accounts: any;
         rentSol: any;
+        metadataFeesSol: any;
         programFeesSol: any;
         networkFeesSol: any;
         seeds: {};

package/types/economy/plan.d.mts

@@ -30,11 +30,11 @@ export declare function tableBatches(t: any): never[][];
 export declare function partPrize(o: any, m: any): "Raffled" | {
     Stash: any[];
 } | {
-    Item?: undefined;
     Compressed: {
         item: any;
         tree: string;
     };
+    Item?: undefined;
     Held?: undefined;
     Nft?: undefined;
     Roll?: undefined;
@@ -137,8 +137,8 @@ export declare function boxArgs(b: any, m: any): {
                 Item: any[];
                 Collection?: undefined;
             } | {
-                Item?: undefined;
                 Collection: any[];
+                Item?: undefined;
             };
             key: any;
             test: any;
@@ -159,8 +159,8 @@ export declare function boxArgs(b: any, m: any): {
             Item: any[];
             Collection?: undefined;
         } | {
-            Item?: undefined;
             Collection: any[];
+            Item?: undefined;
         };
         key: any;
         test: any;
@@ -341,11 +341,11 @@ export declare function scheduleArgs(s: any, m: any): {
  * of the pool), an item (a compressed NFT of it into the project's tree, "@tree"), one NFT of a stash, or a roll of a box.
  */
 export declare function prizeArgs(p: any, m: any): "Raffled" | {
-    Item?: undefined;
     Compressed: {
         item: any;
         tree: string;
     };
+    Item?: undefined;
     Held?: undefined;
     Nft?: undefined;
     Roll?: undefined;
@@ -464,8 +464,8 @@ export declare function lotteryArgs(l: any, m: any): {
                     Item: any[];
                     Collection?: undefined;
                 } | {
-                    Item?: undefined;
                     Collection: any[];
+                    Item?: undefined;
                 };
                 key: any;
                 test: any;
@@ -514,8 +514,8 @@ export declare function lotteryArgs(l: any, m: any): {
                 Item: any[];
                 Collection?: undefined;
             } | {
-                Item?: undefined;
                 Collection: any[];
+                Item?: undefined;
             };
             key: any;
             test: any;
@@ -608,8 +608,8 @@ export declare function contestArgs(c: any, m: any, at?: any): {
                 Item: any[];
                 Collection?: undefined;
             } | {
-                Item?: undefined;
                 Collection: any[];
+                Item?: undefined;
             };
             key: any;
             test: any;
@@ -619,11 +619,11 @@ export declare function contestArgs(c: any, m: any, at?: any): {
     min_pot: bigint;
     stake: bigint;
     prize: string | {
-        Item?: undefined;
         Compressed: {
             item: any;
             tree: string;
         };
+        Item?: undefined;
         Held?: undefined;
         Nft?: undefined;
         Roll?: undefined;
@@ -682,8 +682,8 @@ export declare function contestArgs(c: any, m: any, at?: any): {
             Item: any[];
             Collection?: undefined;
         } | {
-            Item?: undefined;
             Collection: any[];
+            Item?: undefined;
         };
         key: any;
         test: any;
@@ -700,8 +700,8 @@ export declare function farmArgs(f: any, m: any): {
             Item: any[];
             Collection?: undefined;
         } | {
-            Item?: undefined;
             Collection: any[];
+            Item?: undefined;
         };
         key: any;
         test: any;
@@ -780,8 +780,8 @@ export declare function auctionArgs(a: any, m: any): {
                 Item: any[];
                 Collection?: undefined;
             } | {
-                Item?: undefined;
                 Collection: any[];
+                Item?: undefined;
             };
             key: any;
             test: any;
@@ -792,8 +792,8 @@ export declare function auctionArgs(a: any, m: any): {
             Item: any[];
             Collection?: undefined;
         } | {
-            Item?: undefined;
             Collection: any[];
+            Item?: undefined;
         };
         key: any;
         test: any;
@@ -801,11 +801,11 @@ export declare function auctionArgs(a: any, m: any): {
 };
 export declare function grantArgs(g: any, m: any): {
     gives: string | {
-        Item?: undefined;
         Compressed: {
             item: any;
             tree: string;
         };
+        Item?: undefined;
         Held?: undefined;
         Nft?: undefined;
         Roll?: undefined;
@@ -911,8 +911,8 @@ export declare function grantArgs(g: any, m: any): {
                 Item: any[];
                 Collection?: undefined;
             } | {
-                Item?: undefined;
                 Collection: any[];
+                Item?: undefined;
             };
             key: any;
             test: any;