@xgamesfun/solana 0.26.1 → 0.26.3

package/js/chain/token2022.js

@@ -20,10 +20,16 @@ export const EXECUTE_DISCRIMINATOR = Uint8Array.of(105, 37, 101, 197, 75, 251, 1
 
 const ACCOUNT_TYPE_MINT = 1;
 const EXTENSION = {
+  TransferFeeConfig: 1,
+  MintCloseAuthority: 3,
+  ConfidentialTransferMint: 4,
   DefaultAccountState: 6,
   MemoTransfer: 8,
+  NonTransferable: 9,
+  InterestBearingConfig: 10,
   PermanentDelegate: 12,
   TransferHook: 14,
+  ScaledUiAmount: 25,
   PausableConfig: 26,
 };
 const META_BYTES = 35;
@@ -109,6 +115,89 @@ export function mintPowers({ owner, data }) {
   return out;
 }
 
+/**
+ * What a mint's own keys can do, as an economy spec's `powers` says it (schema `token.powers`), read from the mint's
+ * account (`owner`, its token program; `data`), so nobody has to look it up and type it in. Only what is so is named:
+ * a plain mint nobody can mint more of reads `{ mintAuthority: 'none' }`. `project`: the loot project's address, when
+ * known, whose own tokens read `mintAuthority: 'project'`; any other minter is `'someone else'`.
+ *   freeze: a freeze authority; permanentDelegate; transferHook (a hook program, or an authority who can name one);
+ *   transferFeePercent and feeChangeable (its authority is still there); closeAuthority; pausable; defaultState (the
+ *   mint sets what new accounts start as) and defaultFrozen (they start frozen); nonTransferable;
+ *   confidentialTransfers.
+ * A mint holds two transfer fees: the one in force until an epoch, and the one from that epoch on. With `epoch` (the
+ * chain's current one) the fee read is the one that applies: the newer once its epoch has come, else the higher of
+ * the two (the fee today, or the one already set to follow). Without it, the higher of the two: never less than what
+ * a transfer pays, and a fee since lowered still reads at its old rate.
+ * Returns null when the account is not a mint of either token program.
+ */
+export function powersOf({ owner, data }, { project = null, epoch = null } = {}) {
+  const classic = owner === TOKEN_PROGRAM;
+  if (!classic && owner !== TOKEN_2022_PROGRAM) return null;
+  const extended = !classic && data.length > TOKEN_ACCOUNT_BYTES && data[TOKEN_ACCOUNT_BYTES] === ACCOUNT_TYPE_MINT;
+  if (data.length !== MINT_BYTES && !extended) return null;
+  if (data[45] !== 1) return null;
+  const minter = readUintLE(data, 0, 4) === 1n ? encodeBase58(data.subarray(4, 36)) : null;
+  const out = { mintAuthority: !minter ? 'none' : project && minter === project ? 'project' : 'someone else' };
+  if (readUintLE(data, 46, 4) === 1n) out.freeze = true;
+  if (!extended) return out;
+  /** An address a Token-2022 extension holds at `at`, or null when it holds none (all zeros). */
+  const held = (value, at = 0) => {
+    const a = value && value.length >= at + 32 ? encodeBase58(value.subarray(at, at + 32)) : null;
+    return a === NO_ADDRESS ? null : a;
+  };
+  if (held(extension(data, EXTENSION.PermanentDelegate))) out.permanentDelegate = true;
+  const hook = extension(data, EXTENSION.TransferHook);
+  if (held(hook, 0) || held(hook, 32)) out.transferHook = true;
+  // TransferFeeConfig: its authority, the withdraw authority, what is withheld, then the fee in force and the one to
+  // come, each { epoch u64, most u64, basis points u16 }.
+  const fee = extension(data, EXTENSION.TransferFeeConfig);
+  if (fee && fee.length >= 108) {
+    const older = Number(readUintLE(fee, 88, 2)),
+      newer = Number(readUintLE(fee, 106, 2));
+    const since = readUintLE(fee, 90, 8);
+    const points = epoch !== null && BigInt(epoch) >= since ? newer : Math.max(older, newer);
+    if (points > 0) out.transferFeePercent = points / 100;
+    if (held(fee, 0)) out.feeChangeable = true;
+  }
+  if (held(extension(data, EXTENSION.MintCloseAuthority))) out.closeAuthority = true;
+  const pause = extension(data, EXTENSION.PausableConfig);
+  if (pause && (held(pause) || (pause.length > 32 && pause[32] !== 0))) out.pausable = true;
+  const state = extension(data, EXTENSION.DefaultAccountState);
+  if (state) {
+    out.defaultState = true;
+    if (state[0] === 2) out.defaultFrozen = true;
+  }
+  if (extension(data, EXTENSION.NonTransferable)) out.nonTransferable = true;
+  if (extension(data, EXTENSION.ConfidentialTransferMint)) out.confidentialTransfers = true;
+  return out;
+}
+
+/**
+ * What a Token-2022 mint's state does today that its powers don't say: `paused` (a pause is on: nothing moves),
+ * `scaled` (ScaledUiAmount or InterestBearing: wallets show amounts multiplied by a rate, not the base units the
+ * program moves and an economy counts in) and `scaler` (somebody can still change that rate). All false for a classic
+ * mint, or one with none of them.
+ */
+export function mintState({ owner, data }) {
+  const out = { paused: false, scaled: false, scaler: false };
+  if (
+    owner !== TOKEN_2022_PROGRAM ||
+    data.length <= TOKEN_ACCOUNT_BYTES ||
+    data[TOKEN_ACCOUNT_BYTES] !== ACCOUNT_TYPE_MINT
+  )
+    return out;
+  const set = value => Boolean(value) && value.length >= 32 && encodeBase58(value.subarray(0, 32)) !== NO_ADDRESS;
+  const pause = extension(data, EXTENSION.PausableConfig);
+  out.paused = Boolean(pause) && pause.length > 32 && pause[32] !== 0;
+  for (const kind of [EXTENSION.ScaledUiAmount, EXTENSION.InterestBearingConfig]) {
+    const value = extension(data, kind);
+    if (!value) continue;
+    out.scaled = true;
+    if (set(value)) out.scaler = true;
+  }
+  return out;
+}
+
 /** Whether a token account requires a memo on every transfer into it. */
 export function requiresMemo(accountData) {
   const value = accountData.length > TOKEN_ACCOUNT_BYTES ? extension(accountData, EXTENSION.MemoTransfer) : 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,
@@ -995,7 +996,7 @@ export function check(
         'E-TOKEN',
         where,
         `“${t.key}” is an existing token, so the economy needs its mint address and its decimals.`,
-        'Add "mint" (the token’s address) and "decimals", read from the mint (an explorer shows them): `xsolana approve` reads the mint and refuses decimals that differ.',
+        'Add "mint" (the token’s address) and "decimals": `xsolana token <mint>` (xsolana_token) reads the mint and gives the whole entry. `xsolana approve` reads the mint too and refuses decimals that differ.',
       );
     if (source === 'game' && t.program === 'token-2022')
       refuse(
@@ -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',
@@ -1082,7 +1110,7 @@ export function check(
         'W-MINT-POWERS',
         where,
         `The checker cannot read the mint of “${t.key}” from here, so it does not know what its owner can do (freeze, a permanent delegate, a transfer hook, which no rolled box can give a prize in, or fee).`,
-        'Look the mint up on an explorer and list what it can do under "powers".',
+        `Run \`xsolana token ${t.mint ?? '<mint>'}\` (xsolana_token): it reads the mint and gives this entry with "powers" filled in.`,
       );
   }
   if (!m.currency) {
@@ -4975,11 +5003,41 @@ export function check(
         `${label(c)} splits a prize of 0 among its winners: the program opens the contest but can never name its winner (PrizeNotCovered), so it runs past its result and is called off, every entry refunded.`,
         'Give the prize an amount above 0, or leave the prize out.',
       );
+    // A presale: one side, entries paid in money (SOL, or a coin made elsewhere), and another token split among the
+    // backers by what each put in: people pay for a share of a token, which is what the law on selling securities
+    // looks at first. The prize's own token is read (a pool's is what the pool holds), and entries paid in points
+    // the project mints are no sale.
+    const sold = cp?.gives === 'tokens' ? prizeToken(c.prize, m) : null;
+    if (
+      c.prize?.split &&
+      c.sides === 1 &&
+      sold &&
+      !sold.wsol &&
+      sold.source !== 'sol' &&
+      tok &&
+      tok.source !== 'game' &&
+      sold.key !== tok.key
+    )
+      warn(
+        'W-TOKEN-SALE',
+        `${where}.prize`,
+        `${label(c)} sells ${sold.symbol ?? sold.key} for ${tok.symbol ?? tok.key}: each backer pays in and takes a share of the tokens by what they put in. Selling a token to raise money is what securities law looks at first, and many places limit who may buy.`,
+        'Fine on devnet. Before mainnet, ask counsel.',
+      );
     // One NFT, the last units of an item, a pool's prize: the winning entries share it in the order they are claimed.
     const scarce =
       cp &&
       (cp.gives === 'nft' || (cp.gives === 'item' && Number(m.item.get(cp.item)?.supply ?? 0) > 0) || prizePool(cp));
-    if (scarce)
+    // A prize split by stake is set aside whole when the winner is named, or that decision is refused: no entry takes
+    // another's part, but the pool must hold all of it by then.
+    if (scarce && c.prize.split && prizePool(cp))
+      warn(
+        'W-CONTEST-PRIZE',
+        `${where}.prize`,
+        `${label(c)} splits ${prizeWords(cp, m)} among its winners: all of it is set aside when the winner is named, and naming one is refused while “${prizePool(cp)}” holds less (PrizeNotCovered), so the contest would run past its result and be called off.`,
+        'Keep the pool holding the whole prize until the winner is named: seed it with that much, and let nothing else pay out of it.',
+      );
+    else if (scarce)
       warn(
         'W-CONTEST-PRIZE',
         `${where}.prize`,

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}`)
@@ -589,7 +603,7 @@ export function explainEconomy(economy, { now = Math.floor(Date.now() / 1000) }
   );
   for (const n of sim.notes) lines.push(`- ${n}`);
 
-  const flagged = verdict.warnings.filter(w => w.code === 'W-CHANCE-PRIZE' || w.code === 'W-REVENUE-SHARE');
+  const flagged = verdict.warnings.filter(w => ['W-CHANCE-PRIZE', 'W-REVENUE-SHARE', 'W-TOKEN-SALE'].includes(w.code));
   const others = verdict.warnings.filter(w => !flagged.includes(w));
   if (flagged.length) section('Flagged for the law, once it is real money', [...new Set(flagged.map(w => w.message))]);
   section(

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. `xsolana token <mint>` (xsolana_token) reads any existing mint into its entry, with its decimals, program and `powers` (what its own keys can do), so none of it is typed by hand.',
     acts: 'nobody: a token is a fact',
   },
   currency: {
@@ -160,7 +160,7 @@ export const CANNOT = [
     words: 'bonding curve market trading fees launch pump.fun meteora swap liquidity sell back creator coin',
     why: 'loot runs no market: it moves and sells what the game owns, it doesn’t trade between strangers',
     nearest: [
-      'launch the coin on a token launchpad or an AMM (a launchpad’s creator fees pay on trades), then name its mint as an existing token: loot’s shops, boxes, farms and gates use it; gives up nothing on loot’s side',
+      'launch the coin on a token launchpad or an AMM (a launchpad’s creator fees pay on trades), then name its mint as an existing token (`xsolana token <mint>` reads it into its entry): loot’s shops, boxes, farms and gates use it; gives up minting, since a coin launched this way usually has nobody left who can mint it, so the economy pays out only what its owner puts into its pools',
       'a shop listing whose price rises after each sale (`rise`), and a recipe that buys the token back at a fixed price from a reserve pool a share of each sale fills (`in`: a `pay` line burned; `out`: tokens from the pool): a one-way curve with a floor; gives up a market price, and the reserve is the authority’s to spend',
       'a game token with a fixed `supply` minted once to the owner, minting off for good: a community token the owner keeps and hands out; gives up a public market',
     ],

package/js/economy/legal.mjs

@@ -12,6 +12,8 @@ export const LEGAL = Object.freeze({
     'Anyone, the seller included, can bid to push an auction’s price up (shill bidding): a reserve is the honest way to set a floor.',
   'W-REVENUE-SHARE':
     'Stakers are paid from what players spend, which regulators look at when they decide whether a token is a security: before real money, get a lawyer, or pay rewards from emissions instead.',
+  'W-TOKEN-SALE':
+    'People pay for a share of a new token (a presale). Selling a token to raise money is what securities law looks at first, and many places limit who may buy: before real money, get a lawyer.',
 });
 
 /** The legal flags a checker verdict raises, each once, in the order the checker raised them: [{ code, says }]. */

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/js/mcp/tools.mjs

@@ -5,7 +5,11 @@
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { addressBytes } from '../chain/base58.js';
+import { metadataAddress } from '../chain/metadata.js';
+import { parseMint, tokenEntry } from '../chain/mint.js';
 import { checkCluster, notMainnet, rpcClient } from '../chain/rpc.js';
+import { mintState } from '../chain/token2022.js';
 import { decodeAny } from '../client/accounts.js';
 import { IDL } from '../client/ix.js';
 import { LOOT_PROGRAM, pda } from '../client/pda.js';
@@ -82,6 +86,7 @@ export const REMOTE_TOOLS = new Set([
   'xsolana_explain',
   'xsolana_review',
   'xsolana_status',
+  'xsolana_token',
   'xsolana_client',
 ]);
 
@@ -688,6 +693,145 @@ export const tools = [
       return { ok: true, rows, text: text + footer };
     },
   },
+  {
+    name: 'xsolana_token',
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    description:
+      'A token made elsewhere, as the chain has it, for an economy that uses it: give its mint’s address and get its ready `tokens` entry (`source: "existing"`) with its name, ticker, decimals and token program, and `powers` filled in: what the mint’s own keys can do (mint more, freeze, a transfer fee, a transfer hook, a permanent delegate, a pause…), in words too. Use it instead of asking the person to look the mint up. Reads devnet (or XSOLANA_RPC_URL): the mint and its name record only, never the link the record names.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        mint: { type: 'string', description: 'The token’s mint address.' },
+        key: {
+          type: 'string',
+          pattern: '^[a-z][a-z0-9-]{0,31}$',
+          description: 'What the spec will call it (default: its ticker, in the letters a key takes).',
+        },
+        project: {
+          type: 'string',
+          description:
+            'The loot project’s address, when the token is one the project is to mint on a mint of its own: its mint authority then reads as the project’s, or as not handed over yet.',
+        },
+      },
+      required: ['mint'],
+      additionalProperties: false,
+    },
+    async handler(input, ctx) {
+      const mint = String(input.mint ?? '').trim();
+      try {
+        addressBytes(mint);
+      } catch {
+        return {
+          ok: false,
+          text: `${JSON.stringify(mint)} is not a Solana address. Give the token’s mint address.${footer}`,
+        };
+      }
+      // Devnet only: a mainnet URL is refused, and so is a chain whose first block is mainnet's or testnet's.
+      const rpc = (ctx?.rpc ?? rpcClient)(notMainnet(process.env.XSOLANA_RPC_URL || DEVNET_RPC));
+      if (!ctx?.rpc) await checkCluster(rpc);
+      let project = null;
+      if (input.project !== undefined) {
+        project = String(input.project).trim();
+        try {
+          addressBytes(project);
+        } catch {
+          return {
+            ok: false,
+            text: `${JSON.stringify(project)} is not a Solana address. Give the project’s address, or leave it out.${footer}`,
+          };
+        }
+      }
+      const [account, record] = await rpc.accounts([mint, metadataAddress(mint)]);
+      // A transfer fee changes on an epoch: with the chain's current one, a fee since lowered reads as it is now.
+      const epoch =
+        account && typeof rpc.call === 'function'
+          ? await rpc.call('getEpochInfo').then(
+              e => Number(e.epoch),
+              () => null,
+            )
+          : null;
+      const token = tokenEntry(mint, account, record?.data ?? null, {
+        ...(input.key ? { key: input.key } : {}),
+        project,
+        epoch,
+      });
+      if (!token)
+        return {
+          ok: false,
+          text: `${
+            account
+              ? `${mint} is not a token mint on ${CLUSTER} (a token account or a wallet is not the mint: an explorer’s token page names it)`
+              : `There is nothing at ${mint} on ${CLUSTER}. A coin launched on mainnet is not on ${CLUSTER}, where loot runs for now`
+          }.${footer}`,
+        };
+      if (token.source === 'sol')
+        return {
+          ok: true,
+          token,
+          text: `${mint} is wrapped SOL: in a spec that is SOL itself.\n\nIn the spec’s "tokens":\n${JSON.stringify(token)}${footer}`,
+        };
+      const read = parseMint(mint, account.owner, account.data, record?.data ?? null);
+      const supply = Number(BigInt(read.supply)) / 10 ** read.decimals;
+      const p = token.powers;
+      const state = mintState(account);
+      // The name and ticker are the token's own writing, anyone's to set: given as the entry has them (one line, cut
+      // to a spec's lengths), in quotes, as labels and never as words of this tool.
+      const called =
+        token.symbol || token.name
+          ? `calls itself ${[token.name && `“${token.name}”`, token.symbol && `ticker “${token.symbol}”`].filter(Boolean).join(', ')} (its own record’s words: a label anyone can write, not a fact)`
+          : 'has no name record, so wallets show it as an unknown token';
+      // What each power lets whoever holds it do, in the checker's words (check.mjs W-MINT-POWERS).
+      const can = [
+        p.mintAuthority === 'someone else' && `mint more of it whenever they want (${read.mintAuthority} can)`,
+        p.mintAuthority === 'project' && null,
+        p.freeze && 'freeze any account holding it, an economy’s pools and vaults included',
+        p.permanentDelegate && 'move or burn it out of any account',
+        p.transferHook && 'run a program of their own on every transfer, which can refuse one',
+        p.transferFeePercent > 0 && `keep ${p.transferFeePercent}% of every transfer`,
+        p.feeChangeable && 'raise its transfer fee, up to all of a transfer',
+        p.closeAuthority && 'close the mint and make it again with other powers',
+        p.pausable && 'pause every transfer of it',
+        p.defaultFrozen && 'have every new account of it start frozen',
+        !p.defaultFrozen && p.defaultState && p.freeze && 'switch every new account of it to start frozen',
+      ].filter(Boolean);
+      const also = [
+        p.nonTransferable && 'It cannot be transferred at all: nothing can be paid, staked or given as a prize in it.',
+        p.confidentialTransfers &&
+          'Its holders can turn plain transfers into their account away (confidential transfers).',
+        state.paused && 'It is paused now: nothing of it moves until its issuer ends the pause.',
+        state.scaled &&
+          `Wallets show its amounts multiplied by a rate its mint carries${state.scaler ? ', which its issuer can change' : ''}: an economy counts the amounts under it, so a price in a spec is not the number a wallet shows.`,
+        p.mintAuthority === 'project' &&
+          'Its mint authority is the project given: the project mints it, as its rules say.',
+        project &&
+          p.mintAuthority === 'someone else' &&
+          `Its mint authority is not the project given (${project}): until it is handed over, nothing the economy mints in it lands.`,
+      ].filter(Boolean);
+      const text = [
+        `The token at ${mint} on ${CLUSTER}: ${read.program === 'token-2022' ? 'a Token-2022' : 'a classic SPL'} token, ${plural(read.decimals, 'decimal')}, ${supply.toLocaleString('en-US')} in existence${p.mintAuthority === 'none' ? ', and nobody can mint more' : ''}. It ${called}.`,
+        can.length
+          ? `Whoever controls its mint can:\n${can.map(c => `- ${c}`).join('\n')}\nAn economy in it is only as safe as the token: say so where players pay, stake or are paid.`
+          : `Its mint has no key that can freeze it, take it, charge on it or stop a transfer${p.mintAuthority === 'project' ? ' (the project mints it)' : ''}.`,
+        ...also,
+        `In the spec’s "tokens" (xsolana_check then says what each power means for the economy’s parts):\n${JSON.stringify(token, null, 2)}`,
+      ].join('\n\n');
+      return {
+        ok: true,
+        token,
+        mint: {
+          address: mint,
+          program: read.program,
+          decimals: read.decimals,
+          supply: read.supply,
+          name: token.name ?? null,
+          symbol: token.symbol ?? null,
+          mintAuthority: read.mintAuthority,
+          freezeAuthority: read.freezeAuthority,
+        },
+        text: text + footer,
+      };
+    },
+  },
   {
     name: 'xsolana_client',
     annotations: READ,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xgamesfun/solana",
-  "version": "0.26.1",
+  "version": "0.26.3",
   "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": "8c8c89bfca22961d24379b2cc63964dfa2e68d3b65cdcbb33d52352677464533"
 }