@xgamesfun/solana 0.26.2 → 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

@@ -996,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(
@@ -1110,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) {
@@ -5003,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/explain.mjs

@@ -603,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). 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.',
+    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/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.2",
+  "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": "20e40ee24d808d10091a0bd9973c3c4883e9dd35da4a6beac97557dd85a362c8"
+  "clientSha256": "8c8c89bfca22961d24379b2cc63964dfa2e68d3b65cdcbb33d52352677464533"
 }

package/skills/xsolana-economy/SKILL.md

@@ -9,8 +9,9 @@ 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.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).
+The tools are the `xsolana_*` MCP tools. Without MCP, the same from a terminal: `npx -y @xgamesfun/solana@0.26.3 <guide|examples|check|simulate|cost|explain|review|publish|status> [xsolana.json]`,
+`npx -y @xgamesfun/solana@0.26.3 token <mint>` for a coin made elsewhere,
+or `npx -y @xgamesfun/solana@0.26.3 tool <name> '<json>'` for any tool (always with the exact version).
 
 ## Rules (always)
 
@@ -26,8 +27,9 @@ or `npx -y @xgamesfun/solana@0.26.2 tool <name> '<json>'` for any tool (always w
    `xsolana_simulate`, `xsolana_cost` and `xsolana_explain`, never your own arithmetic. What a player pays is the tools'
    "in all" number for that action (price, fee, oracle, network and rent that never comes back): quote it as is.
 6. **Flag the law once.** The first time the checker raises `W-CHANCE-PRIZE` (paid chance at money: boxes with
-   prizes, lotteries, contests), `W-CHANCE-ITEMS` (paid random collectibles a player can resell: loot boxes, gacha) or
-   `W-REVENUE-SHARE` (stakers paid from sales), say it in one plain sentence. Don't repeat it in later answers, or add
+   prizes, lotteries, contests), `W-CHANCE-ITEMS` (paid random collectibles a player can resell: loot boxes, gacha),
+   `W-REVENUE-SHARE` (stakers paid from sales) or `W-TOKEN-SALE` (a presale: people pay for a share of a new token),
+   say it in one plain sentence. Don't repeat it in later answers, or add
    legal notes to pages and apps you build, unless the person asks or a flag of a new kind appears. When they ask about
    the law, answer what you know and leave the rest to their lawyer: you are not one. Never call anything an
    investment, a return or passive income, and never promise it is safe. The approval page shows the flags and that
@@ -121,13 +123,33 @@ or `npx -y @xgamesfun/solana@0.26.2 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.2 approve xsolana.json`; never drop the version). It opens a page on their computer where
+   `npx -y @xgamesfun/solana@0.26.3 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
     owner signs (open or decide a contest, pay out) goes on an owner page they approve in their own wallet:
     `references/after-launch.md`.
 
+## When they ask for a token
+
+"A token for my game" is one of four things. Find out which from what they say it is for, before writing anything
+(ask only when they haven't said):
+
+| They mean                                                                   | It is                                                | In the spec                                                                                                                                                     |
+| --------------------------------------------------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| points, tickets, shards: what players earn and spend in the game            | a token the project mints as its rules say           | `source: "project"`, given by a recipe's or a grant's prize (`"from": "mint"`), a farm's `rate` (`"minted": true`) or a schedule (`"does": "issue"`)            |
+| "our own coin, 10 million, we hand it out", a community token               | a fixed supply, all of it to the owner, no more ever | `source: "project"` with `supply`; pools are seeded from it, and a presale (a contest), sealed vesting (a schedule) and a farm hand it out                      |
+| "a coin people can trade", "on pump.fun", "a bonding curve", "creator fees" | a market, which loot does not run                    | they launch it on a launchpad or an AMM, in their own wallet; then `xsolana_token {"mint": …}` gives its entry, and loot's shops, boxes, farms and gates use it |
+| "our token", "the coin we launched", "this mint"                            | a coin that exists                                   | `xsolana_token {"mint": …}`: its entry with decimals, program and `powers` read from the chain. Never type them by hand, and never guess an address             |
+
+Say what each gives up. The first two have no public market: nobody trades them unless the project lists them
+somewhere itself. A coin launched on a market usually has nobody left who can mint it (`xsolana_token` says so): the
+economy pays out only what its owner puts into its pools. On devnet a coin trades nothing of value.
+
+A token the setup makes is named on chain as it goes live, so ask for its name, its ticker and a picture first
+(`references/telling-the-person.md`). Whatever the kind, rule 6 holds: never call a token an investment or promise it
+a price.
+
 ## Building the app around it
 
 A game, a site or a bot calls the live economy with the player's own wallet, through the package's player module

package/skills/xsolana-economy/references/sentence-to-spec.md

@@ -119,7 +119,7 @@ maps to a part of the spec (`xsolana_guide` has every field).
 | "holders of the ticket claim a free badge once"                                                                                            | an open grant: no `vouchers`, `keys` or `list`, a `gate` of the ticket, and `limits.perWallet: 1` (each ticket shown claims once too)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | "bring your own NFT", "any NFT of a partner collection can play", "holders of X get"                                                       | a `gate` (or a farm's, or odds') rule with `collection`: the collection's address; the project's notes about each NFT (a level) go in its Sheet                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | "our own token, 10 million, we keep it", "a fixed supply", "a community token"                                                             | `source: "project"` with `supply`: going live mints all of it to the owner and turns minting off for good; pools are seeded from it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| "our token", "the coin we already launched", "this mint"                                                                                   | `source: "existing"` with `mint` and `decimals` (ask for the address). loot doesn't put a token on a market: for trading, launch it on a token launchpad or an exchange first                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| "our token", "the coin we already launched", "this mint"                                                                                   | `source: "existing"`: ask for the mint's address, and `xsolana_token {"mint": …}` gives the whole entry (decimals, program, `powers`). loot doesn't put a token on a market: for trading, launch it on a token launchpad or an exchange first (SKILL.md, "When they ask for a token")                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | "Token-2022", "a transfer fee"                                                                                                             | `program: "token-2022"` and `powers.transferFeePercent`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | "tokens only, no NFTs"                                                                                                                     | `"collection": false`: no collection is made (no collectibles; normal items and tokens work)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | "mint into our existing collection", "two collections"                                                                                     | `collections`: Core collections the owner's wallet already controls, each with the project added as an update delegate; an item's `collection` names the one it is minted into                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

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

@@ -26,7 +26,9 @@ and the spec differ (a limit, an amount, a key not set yet), change one of them
 6. **Flags for the law, once.** `W-CHANCE-PRIZE`: "Players pay for a chance at money. That is gambling in many places once
    it is real money; this runs on devnet only." `W-CHANCE-ITEMS`: "Players pay for random items they can resell: some
    places treat that as gambling, and many require the odds to be shown." `W-REVENUE-SHARE`: "Stakers are paid from
-   what players spend; regulators look at that when they decide whether a token is a security." Say each once, the
+   what players spend; regulators look at that when they decide whether a token is a security." `W-TOKEN-SALE`:
+   "People pay for a share of a new token; selling a token to raise money is what securities law looks at first."
+   Say each once, the
    first time the checker raises it; then leave them, saying them again only when the person asks or a flag of a new
    kind appears, and keep them out of pages and apps unless asked. The approval page shows them, with the program's
    status (not independently audited, as is, at their own risk, theirs to make legal where they offer it), and keeps

package/types/chain/mint.d.ts

@@ -23,3 +23,32 @@ export declare function parseMint(address: any, owner: any, data: any, metadataD
     symbol: string | null;
     uri: string | null;
 } | null;
+/**
+ * A token made elsewhere as an economy spec names it: its `tokens` entry (`source: "existing"`), every field read from
+ * the chain so nothing is typed in by hand: the mint, its decimals and token program, its name and ticker when it has
+ * a name record, and `powers` (token2022.js `powersOf`: what the mint's own keys can do). `account`: the mint's
+ * ({ owner, data }); `record`: its Token Metadata record's data, when there is one. `key`: what the spec will call it
+ * (default: its ticker in the letters a key takes, else "token"). `project`: the loot project, whose own tokens read
+ * `mintAuthority: "project"`; `epoch`: the chain's current epoch, for a transfer fee since changed (`powersOf`). The
+ * name and ticker are cut to what a spec takes, on one line. Wrapped SOL is SOL (`{ key: "sol", source: "sol" }`).
+ * Null when `account` is no mint.
+ */
+export declare function tokenEntry(address: any, account: any, record?: null, { key, project, epoch }?: {
+    epoch?: null | undefined;
+    key?: null | undefined;
+    project?: null | undefined;
+}): {
+    key: string;
+    source: string;
+} | {
+    key: string;
+    source: string;
+    name?: string | undefined;
+    symbol?: string | undefined;
+    decimals: any;
+    program: string;
+    mint: any;
+    powers: {
+        mintAuthority: string;
+    } | null;
+} | null;

package/types/chain/token2022.d.ts

@@ -26,6 +26,44 @@ export declare function mintPowers({ owner, data }: {
     data: any;
     owner: any;
 }): any[];
+/**
+ * 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 declare function powersOf({ owner, data }: {
+    data: any;
+    owner: any;
+}, { project, epoch }?: {
+    epoch?: null | undefined;
+    project?: null | undefined;
+}): {
+    mintAuthority: string;
+} | null;
+/**
+ * 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 declare function mintState({ owner, data }: {
+    data: any;
+    owner: any;
+}): {
+    paused: boolean;
+    scaled: boolean;
+    scaler: boolean;
+};
 /** Whether a token account requires a memo on every transfer into it. */
 export declare function requiresMemo(accountData: any): boolean;
 /** The hook's list of extra accounts for this mint. */

package/types/economy/legal.d.mts

@@ -4,6 +4,7 @@ export declare const LEGAL: Readonly<{
     'W-CHANCE-ITEMS': "Players pay for random items they can resell (a loot box). Some places treat that as gambling and many require the odds shown: show them on the page, and get a lawyer before real money.";
     'W-AUCTION-SHILL': "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 }]. */
 export declare const legalFlags: (verdict: any) => {