@xgamesfun/solana 0.26.2 → 0.26.4

package/js/mcp/tools.mjs

@@ -5,14 +5,18 @@
 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';
 import { check, describe } from '../economy/check.mjs';
 import { legalFlags } from '../economy/legal.mjs';
 import { cost, explainCost } from '../economy/cost.mjs';
-import { changedParts } from '../economy/live.mjs';
+import { changedParts, renamesNote } from '../economy/live.mjs';
 import { example, examples, ideas, search, partsUsed } from '../economy/examples.mjs';
 import { explainEconomy } from '../economy/explain.mjs';
 import { describeReview, review } from '../economy/review.mjs';
@@ -82,6 +86,7 @@ export const REMOTE_TOOLS = new Set([
   'xsolana_explain',
   'xsolana_review',
   'xsolana_status',
+  'xsolana_token',
   'xsolana_client',
 ]);
 
@@ -242,10 +247,11 @@ function flagsToTell(economy, now) {
  * what can't change or was taken out.
  */
 function liveChange(economy) {
-  if (!economy.live?.project || !economy.live?.published) return { scope: {}, notes: '', settings: [] };
-  const { only, fixed, removed, settings } = changedParts(economy);
+  if (!economy.live?.project || !economy.live?.published) return { scope: {}, notes: '', settings: [], changes: 0 };
+  const { only, fixed, removed, settings, renames } = changedParts(economy);
   const notes = [
     settings.length ? `\n${settingsNote(settings, economy.live)}` : '',
+    renames.length ? `\n${renamesNote(renames)}` : '',
     fixed.length
       ? `\nThese can't change once live, and stay as they were: ${fixed.join(', ')} (a farm, an auction or a pool's token).`
       : '',
@@ -253,7 +259,8 @@ function liveChange(economy) {
       ? `\nTaken out of the spec but still on chain: ${removed.join(', ')}. To stop one, keep it and set "active": false.`
       : '',
   ].join('');
-  return { scope: { only, live: economy.live }, notes, settings };
+  // (`changes`: whether anything is to be published at all: a part, or a token's name)
+  return { scope: { only, live: economy.live, renames }, notes, settings, changes: only.size + renames.length };
 }
 
 /** In words: the spec changes the project's own settings, which publishing never writes. */
@@ -423,11 +430,20 @@ export const tools = [
       const c = cost(economy, { now: nowOf(ctx), ...change.scope });
       if (!c.ok) return refused(c, from);
       const head = change.scope.live
-        ? change.scope.only.size
-          ? `This economy is live: this prices only the change (${[...change.scope.only].join(', ')}).\n`
+        ? change.changes
+          ? `This economy is live: this prices only the change (${[...change.scope.only, ...change.scope.renames.map(key => `the name of ${key}`)].join(', ')}).\n`
           : 'This economy is live and nothing has changed since it went live: publishing costs nothing.\n'
         : '';
-      return { ok: true, from, setup: c.setup, actions: c.actions, fees: c.fees, text: head + explainCost(c) + footer };
+      // (a name's price is a transaction's, if it is sent at all: only approving reads the token's record)
+      const names = change.scope.renames?.length ? `\n${renamesNote(change.scope.renames)}` : '';
+      return {
+        ok: true,
+        from,
+        setup: c.setup,
+        actions: c.actions,
+        fees: c.fees,
+        text: head + explainCost(c) + names + footer,
+      };
     },
   },
   {
@@ -554,7 +570,7 @@ export const tools = [
     async handler(input, ctx) {
       const { economy, from, file } = await load(input, ctx);
       const change = liveChange(economy);
-      if (change.scope.live && !change.scope.only.size && change.settings.length)
+      if (change.scope.live && !change.changes && change.settings.length)
         return {
           ok: false,
           transactions: 0,
@@ -562,7 +578,7 @@ export const tools = [
           steps: [],
           text: `${from} is live, and its parts are as they are on chain. ${settingsNote(change.settings, economy.live)}${footer}`,
         };
-      if (change.scope.live && !change.scope.only.size)
+      if (change.scope.live && !change.changes)
         return {
           ok: true,
           transactions: 0,
@@ -573,7 +589,15 @@ export const tools = [
       const p = plan(economy, { now: nowOf(ctx), ...change.scope });
       if (!p.ok) return refused(p, from);
       const c = cost(economy, { now: nowOf(ctx), ...change.scope });
-      const steps = p.transactions.flatMap(t => t.steps.map(s => s.says));
+      // A token's new name is listed as the file has it: whether it is sent is the chain's to say, as approving reads it.
+      const steps = p.transactions.flatMap(t =>
+        t.steps.map(s =>
+          s.id.startsWith('name:')
+            ? `${s.says} (sent only if the token has a name record its owner can still change, read when approving)`
+            : s.says,
+        ),
+      );
+      const renaming = Boolean(change.scope.renames?.length);
       // the file as the approve command names it, relative to the project folder (projectFile's), and plain (plainName)
       const target = file ? path.relative(realPath(path.resolve(cwdOf(ctx))), file) || DEFAULT_FILE : DEFAULT_FILE;
       if (plainName(target) === null)
@@ -587,7 +611,7 @@ export const tools = [
       const command = approveCommand(target);
       const text = [
         ...flagsToTell(economy, nowOf(ctx)),
-        `${change.scope.live ? 'Publishing this change to the live economy' : 'Going live'}: ${plural(p.transactions.length, 'transaction')}, ${plural(p.approvals, 'wallet approval')}, about ${c.setup.totalSol} SOL on devnet:`,
+        `${change.scope.live ? 'Publishing this change to the live economy' : 'Going live'}: ${renaming ? 'at most ' : ''}${plural(p.transactions.length, 'transaction')}, ${plural(p.approvals, 'wallet approval')}, about ${c.setup.totalSol} SOL on devnet:`,
         ...steps.map((s, i) => `${i + 1}. ${s}`),
         '',
         `To put it live, the person runs this in a terminal in the project folder (not you): ${command}`,
@@ -688,6 +712,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.4",
   "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": "fcb5710a80efbff36c80d0249104c8d7c65b9d84cf70c12b8567e3a7d0af4a2b"
 }

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.4 <guide|examples|check|simulate|cost|explain|review|publish|status> [xsolana.json]`,
+`npx -y @xgamesfun/solana@0.26.4 token <mint>` for a coin made elsewhere,
+or `npx -y @xgamesfun/solana@0.26.4 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.4 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
@@ -120,8 +122,10 @@ Don'ts:
 - **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:
+  picture. Only the owner's wallet can change the three later (Token Metadata's rule, not loot's): change them in the
+  spec and approve again, and the record is written again for the price of a transaction (approving reads the record
+  first: one its owner handed to another wallet, made unchangeable or gave a royalty or creators outside these tools
+  is left as it is, and the page says so at each approve until the spec gives the old name back). 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

package/types/chain/metadata.d.ts

@@ -36,5 +36,50 @@ export declare function createFungibleMetadataIx({ mint, authority, payer, name,
     }[];
     data: Uint8Array<any>;
 };
+/**
+ * Token Metadata's UpdateMetadataAccountV2 for a fungible token's record: a new name, ticker and link ('' for none),
+ * all three written as given. `authority` is the record's update authority (for a token a setup made: the project's
+ * owner) and signs; it stays the update authority, and the record stays changeable. The record's words are written
+ * whole, with no royalty, creators, collection or uses: as a record a setup made has them. One that was given any of
+ * those outside these tools would lose them (or refuse the write), so the approval sends this only to a record that
+ * has none (`parseRecord`'s `plain`; approve/live-check.mjs readRenames). The mint is untouched, and it costs only the
+ * transaction: the record keeps its size.
+ */
+export declare function updateFungibleMetadataIx({ mint, authority, name, symbol, uri }: {
+    authority: any;
+    mint: any;
+    name: any;
+    symbol: any;
+    uri?: string | undefined;
+}): {
+    programId: string;
+    keys: {
+        pubkey: any;
+        isSigner: any;
+        isWritable: any;
+    }[];
+    data: Uint8Array<any>;
+};
+/**
+ * A Token Metadata record as the chain holds it, or null when the data is not one (its first byte says a metadata
+ * record; the strings are padded with NULs to their full length):
+ * { updateAuthority, mint, name, symbol, uri, royalty, creators, mutable, collection, uses, plain }.
+ * `royalty`: its resale royalty, in hundredths of a percent. `creators`: how many it lists. `mutable`: its update
+ * authority can still change it. `collection`, `uses`: whether it names one. `plain`: none of royalty, creators,
+ * collection or uses, as a setup's own record is: writing its words again changes nothing else of it.
+ */
+export declare function parseRecord(data: any): {
+    updateAuthority: string;
+    mint: string;
+    name: string;
+    symbol: string;
+    uri: string;
+    royalty: number;
+    creators: number;
+    mutable: boolean;
+    collection: boolean;
+    uses: boolean;
+    plain: boolean;
+} | null;
 /** 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/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/cost.d.mts

@@ -19,10 +19,11 @@ export declare function setupCost(plan: any, economy: any): {
 export declare function actionCosts(economy: any, { now }?: Readonly<Record<string, any>>): any[];
 /** Setup and play costs for a spec, or its refusals. */
 /** `only` and `live`: a change to a live economy, priced as only what it publishes (live.mjs `changedParts`). */
-export declare function cost(economy: any, { now, only, live }?: {
+export declare function cost(economy: any, { now, only, live, renames }?: {
     live?: null | undefined;
     now?: number | undefined;
     only?: null | undefined;
+    renames?: null | undefined;
 }): {
     ok: boolean;
     refusals: any[];
@@ -35,7 +36,14 @@ export declare function cost(economy: any, { now, only, live }?: {
     refusals?: undefined;
     ok: boolean;
     warnings: any[];
-    steps: any[];
+    steps: {
+        creates: never[];
+        signers: string[];
+        id: string;
+        part: string;
+        says: string;
+        build: {};
+    }[];
     transactions: {
         signer: string;
         steps: any[];
@@ -46,7 +54,7 @@ export declare function cost(economy: any, { now, only, live }?: {
         alone: boolean;
     }[];
     approvals: number;
-    freshKeys: any[];
+    freshKeys: string[];
 } | {
     ok: boolean;
     setup: {

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) => {