@xgamesfun/solana 0.26.2 → 0.26.3

package/README.md

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

package/bin/xsolana.mjs

@@ -7,6 +7,7 @@
 //   xsolana guide [part] [--json]        what an economy can be made of, and what loot cannot do
 //   xsolana examples [words…] [--json]   the nearest worked examples and rated economies
 //   xsolana check|simulate|cost|explain|review|publish|status [file] [--json]   one tool on a spec file (default xsolana.json)
+//   xsolana token <mint> [--json]         a token made elsewhere, read from the chain: its `tokens` entry, powers and all
 //   xsolana approve [file] [--port n] [--no-open]   open the local page where the owner approves going live in their wallet
 //   xsolana connect [--agent claude|codex] [--scope user|project] [--local] [--remove] [--dry-run]   register the MCP server and the skill
 //   xsolana tool --list | xsolana tool <name> '<json>' [--args-file f] [--json]   any tool by name
@@ -30,13 +31,14 @@ const USAGE = `xsolana: the tools for loot, one shared Solana program for game a
   xsolana publish [file]          what going live does, and how to approve it
   xsolana approve [file]          approve going live in your own wallet (a local page; --port n, --no-open)
   xsolana status [file]           a live economy on chain
+  xsolana token <mint>            a token made elsewhere, as the chain has it: its "tokens" entry, with what its mint can do
   xsolana connect                 add the xsolana tools to Claude Code or Codex (--agent claude|codex, --scope user|project, --local, --remove, --dry-run)
   xsolana mcp                     serve the tools over MCP (stdio)
   xsolana mcp --http              serve the hosted tools over HTTP at http://127.0.0.1:8787/mcp (--port n, --host h)
   xsolana tool --list             every tool; xsolana tool <name> '<json>' runs one (--args-file f)
   xsolana version                 this package's xsolana version and program
 
-  A tool's command (guide, examples, check … status, tool) takes --json for its whole answer as JSON.
+  A tool's command (guide, examples, check … status, token, tool) takes --json for its whole answer as JSON.
   review exits 1 when it finds something high.`;
 
 /** A failure the person caused (a bad flag, a missing file): said in one line, without a stack. */
@@ -57,6 +59,7 @@ const FLAGS = {
   review: TOOL_FLAGS,
   publish: TOOL_FLAGS,
   status: TOOL_FLAGS,
+  token: TOOL_FLAGS,
   approve: ['--port', '--no-open'],
   connect: ['--agent', '--scope', '--local', '--remove', '--dry-run'],
   tool: ['--list', '--args-file', ...TOOL_FLAGS],
@@ -146,6 +149,10 @@ async function main(argv) {
     case 'status':
       await tool(`xsolana_${command}`, fileInput());
       break;
+    case 'token':
+      if (!positional[0]) throw new UsageError('xsolana token <mint>: give the token’s mint address.');
+      await tool('xsolana_token', { mint: positional[0] });
+      break;
     case 'approve': {
       const port = portOf(values.get('--port'));
       const { approve } = await import('../js/approve/server.mjs');

package/examples/blind-forge.json

@@ -17,7 +17,8 @@
       "powers": {
         "mintAuthority": "someone else",
         "freeze": false,
-        "transferFeePercent": 1
+        "transferFeePercent": 1,
+        "feeChangeable": true
       }
     }
   ],

package/examples/community-coin.json

@@ -0,0 +1,100 @@
+{
+  "version": 2,
+  "network": "devnet",
+  "name": "Community Coin",
+  "prompt": "Our own coin, EMBER: 100 million, a fixed supply, no more ever. 10 million go to a week-long presale, split by what each backer put in, and everyone is refunded if it raises under 50 SOL. 24 million vest to the team: nothing for three months, then 2 million a month for a year, and nobody can stop it. 30 million pay the people who stake it, a little every day. We keep the rest.",
+  "currency": "sol",
+  "tokens": [
+    {
+      "key": "sol",
+      "source": "sol"
+    },
+    {
+      "key": "ember",
+      "source": "project",
+      "name": "Ember",
+      "symbol": "EMBER",
+      "decimals": 6,
+      "supply": 100000000,
+      "uri": "https://example.com/ember.json"
+    }
+  ],
+  "collection": false,
+  "pools": [
+    {
+      "key": "presale",
+      "currency": "ember",
+      "seed": 10000000,
+      "about": "What the presale's backers split."
+    },
+    {
+      "key": "rewards",
+      "currency": "ember",
+      "seed": 30000000,
+      "about": "What stakers are paid from, a little every day."
+    }
+  ],
+  "contests": [
+    {
+      "key": "raise",
+      "name": "The presale",
+      "currency": "sol",
+      "sides": 1,
+      "sideNames": ["Back it"],
+      "entriesClose": "7d",
+      "resultDue": "8d",
+      "minPot": 50,
+      "split": [
+        {
+          "to": "treasury",
+          "percent": 100
+        }
+      ],
+      "prize": {
+        "gives": "tokens",
+        "amount": 10000000,
+        "from": "pool:presale",
+        "currency": "ember",
+        "split": true
+      }
+    }
+  ],
+  "schedules": [
+    {
+      "key": "team",
+      "name": "Team vesting",
+      "does": "pay",
+      "sealed": true,
+      "currency": "ember",
+      "to": "wallet:5DckzByxgf3nMQ1m1SGfpsnRXozawiFncTBZDtZ9Nj7T",
+      "amount": 2000000,
+      "start": "publish+90d",
+      "every": "30d",
+      "maxRuns": 12,
+      "fund": 24000000
+    },
+    {
+      "key": "drip",
+      "name": "Stakers' drip",
+      "does": "pay",
+      "from": "rewards",
+      "to": "farm:hearth",
+      "percent": 1,
+      "every": "1d"
+    }
+  ],
+  "farms": [
+    {
+      "key": "hearth",
+      "name": "The hearth",
+      "stakes": "ember",
+      "rewards": "ember",
+      "tiers": [
+        {
+          "lock": "7d",
+          "multiplier": 1
+        }
+      ]
+    }
+  ]
+}

package/js/approve/live-check.mjs

@@ -6,6 +6,7 @@
 import { encodeBase58 } from '../chain/base58.js';
 import { parseCoreCollection, MPL_CORE_PROGRAM } from '../chain/core.js';
 import { parseMint } from '../chain/mint.js';
+import { mintState, powersOf } from '../chain/token2022.js';
 import { accountKind, decode } from '../client/accounts.js';
 import { BUBBLEGUM_PROGRAM, LOOT_PROGRAM, pda } from '../client/pda.js';
 import { SYSTEM_PROGRAM } from '../chain/pda.js';
@@ -118,15 +119,111 @@ export async function checkLive({ live, m, wallet, chain }) {
 /** A token the spec names by its mint address that is not that mint on chain: the message says what differs. */
 export class MintMismatch extends Error {}
 
+/** What each power of a mint's own keys lets its holder do, in the checker's words (check.mjs W-MINT-POWERS). */
+const POWER_SAYS = {
+  freeze: 'freeze any account holding it, the economy’s pools and vaults included',
+  permanentDelegate: 'move or burn it out of any account',
+  transferHook: 'run a program of their own on every transfer, which can refuse one',
+  feeChangeable: 'raise its transfer fee, up to all of a transfer',
+  closeAuthority: 'close the mint and make it again with other powers',
+  pausable: 'pause every transfer of it',
+  defaultFrozen: 'have every new account of it start frozen',
+  defaultState: 'switch every new account of it to start frozen',
+};
+/** What the mint itself does, whoever controls it: said as a sentence of its own. */
+const MINT_SAYS = {
+  nonTransferable: 'It cannot be transferred at all: nothing can be paid, staked or given as a prize in it.',
+  confidentialTransfers: 'Its holders can turn plain transfers into their account away (confidential transfers).',
+};
+/** What a spec says of a power when it denies it, for the refusal. */
+const POWER_NAMES = {
+  freeze: 'no freeze authority',
+  permanentDelegate: 'no permanent delegate',
+  transferHook: 'no transfer hook',
+  feeChangeable: 'a transfer fee nobody can change',
+  closeAuthority: 'no close authority',
+  pausable: 'no pause',
+  defaultFrozen: 'accounts that don’t start frozen',
+  defaultState: 'no default account state',
+  nonTransferable: 'a token that can be transferred',
+  confidentialTransfers: 'no confidential transfers',
+};
+
+/**
+ * A named mint's powers as the chain has them (`onChain`: token2022.js `powersOf`) against what the spec says of them
+ * (`said`: its `powers`, or nothing). The spec denying a power the mint has is a contradiction: the checker's warnings
+ * were worked out from the spec, so the person read that a risk was not there (throws MintMismatch). A power the spec
+ * is silent on is not refused (a spec written before the tools could read a mint names none): it is returned in words,
+ * for the page to show before the owner approves. → the sentence, or null when the spec says all the chain has.
+ */
+function powersAgainst(t, what, onChain, said = {}, { state = {}, project = null } = {}) {
+  const fix = `Run \`xsolana token ${t.mint}\` and write its "powers" as the chain has them.`;
+  for (const [power, name] of Object.entries(POWER_NAMES))
+    if (said[power] === false && onChain[power])
+      throw new MintMismatch(
+        `The spec says ${what} has ${name} ("${power}": false); on chain, ${POWER_SAYS[power] ? `whoever controls its mint ${t.mint} can ${POWER_SAYS[power]}` : `its mint ${t.mint} says otherwise`}. ${fix}`,
+      );
+  if (said.mintAuthority === 'none' && onChain.mintAuthority !== 'none')
+    throw new MintMismatch(
+      `The spec says nobody can mint more of ${what} ("mintAuthority": "none"); on chain its mint ${t.mint} has a mint authority. ${fix}`,
+    );
+  const fee = onChain.transferFeePercent ?? 0;
+  if (said.transferFeePercent !== undefined && fee > Number(said.transferFeePercent))
+    throw new MintMismatch(
+      `The spec says ${what} keeps ${said.transferFeePercent}% of every transfer; on chain its mint ${t.mint} keeps ${fee}%, so pools, prizes and stakes receive less than the page shows. ${fix}`,
+    );
+  // A default state only matters with someone who can freeze: with no freeze authority nobody can switch it.
+  const can = power => (power === 'defaultState' ? !onChain.defaultFrozen && onChain.freeze : true);
+  const unsaid = [
+    onChain.mintAuthority === 'someone else' &&
+      said.mintAuthority === undefined &&
+      'mint more of it whenever they want',
+    ...Object.entries(POWER_SAYS).map(
+      ([power, says]) => onChain[power] && said[power] === undefined && can(power) && says,
+    ),
+    fee > 0 && said.transferFeePercent === undefined && `keep ${fee}% of every transfer`,
+  ].filter(Boolean);
+  const lines = [];
+  if (unsaid.length)
+    lines.push(
+      `whoever controls the mint of ${what} (${t.mint}) can ${unsaid.join('; ')}. The checker’s warnings did not count it`,
+    );
+  for (const [power, says] of Object.entries(MINT_SAYS))
+    if (onChain[power] && said[power] === undefined) lines.push(says.replace(/\.$/, ''));
+  // The spec says the project mints it: true only once the mint's authority is the project. Until then whatever the
+  // economy mints in it fails, and whoever holds the authority mints as they like.
+  if (['project', 'game'].includes(said.mintAuthority) && onChain.mintAuthority !== 'project')
+    lines.push(
+      onChain.mintAuthority === 'none'
+        ? `the spec says the project mints ${what}, and on chain nobody can mint it (its mint ${t.mint} has no authority, for good): everything this economy would mint in it will fail`
+        : `the spec says the project mints ${what}, and on chain its mint ${t.mint} is someone else’s to mint${project ? `: until its authority is handed to the project (${project}), what this economy mints in it fails, and its holder can mint more` : ', not the project’s yet'}`,
+    );
+  if (state.paused) lines.push(`${what} is paused now: nothing of it moves until its issuer ends the pause`);
+  if (state.scaled)
+    lines.push(
+      `wallets show amounts of ${what} multiplied by a rate its mint carries${state.scaler ? ', which its issuer can change' : ''}: the economy counts the amounts under it, so a price here is not the number a wallet shows`,
+    );
+  return lines.length
+    ? `Read from the chain, and not in the spec: ${lines.join('. ')}. An economy in it is only as safe as the token.`
+    : null;
+}
+
 /**
  * Checks every token the spec names by its mint address (an existing token, or a game token on a mint of its own)
  * against `chain` ({ account }): the mint must be there, of the token program the spec says, with the decimals the
  * spec says. Every amount the page shows is written in base units with the spec's decimals, and the program takes them
  * as they are, so one decimal off is ten times what the page says. A mint the setup makes is made with the spec's
- * decimals, and is not read. Throws MintMismatch.
+ * decimals, and is not read. What the mint's own keys can do is read too (`powersAgainst`): a power the spec denies
+ * and the mint has is refused, and one the spec is silent on is returned for the page to show. Throws MintMismatch.
+ * `project`: the project's address (the wallet's own, or the live one), which a mint the project mints must name as
+ * its authority. `chain.epoch`, when the chain has it, tells a transfer fee since lowered from one still in force.
+ * → { powers: [{ key, mint, says }] }, one for each named token with something its spec doesn't say.
  */
-export async function checkMints({ m, chain }) {
+export async function checkMints({ m, chain, project = null }) {
   const named = [...m.tokens.values()].filter(t => t.mint && !t.mint.startsWith('@'));
+  const powers = [];
+  let epoch = null;
+  if (named.some(t => !t.wsol) && typeof chain.epoch === 'function') epoch = await chain.epoch().catch(() => null);
   for (const t of named) {
     const what = `the token ${t.symbol ?? t.key} (“${t.key}”)`;
     if (t.wsol) {
@@ -151,8 +248,20 @@ export async function checkMints({ m, chain }) {
       throw new MintMismatch(
         `The spec says ${what} is a ${t.program} token; its mint ${t.mint} is ${mint.program}. Write "program": "${mint.program}".`,
       );
+    let onChain, state;
+    try {
+      onChain = powersOf(account, { project, epoch }) ?? {};
+      state = mintState(account);
+    } catch {
+      throw new MintMismatch(
+        `The mint ${t.mint} of ${what} does not read as a mint: its data is not what its token program writes.`,
+      );
+    }
+    const says = powersAgainst(t, what, onChain, t.powers, { state, project });
+    if (says) powers.push({ key: t.key, mint: t.mint, says });
   }
   await checkTreasury({ m, chain });
+  return { powers };
 }
 
 /** Programs whose own accounts are often pasted where their vault was meant: a multisig's or a DAO's account. */

package/js/approve/page.js

@@ -60,6 +60,8 @@ export function approvalPage(token) {
 
   // The last state shown: ticking the legal box shows it again, with Approve enabled or not.
   let last = null;
+  // The legal lines the box was last shown with.
+  let legalShown = new Set();
   function render(state) {
     last = state;
     $('title').textContent = state.done ? `“${state.name}” is live` : `Approve “${state.name}”`;
@@ -97,21 +99,31 @@ export function approvalPage(token) {
     // The notice (no warranty, at the owner's own risk, legal where it runs) and this economy's legal flags, in a
     // block of their own whatever the agent said: Approve waits until the owner ticks that they read them.
     const legal = state.legal ?? [];
+    // A line that was not there when the box was ticked (what the chain says of a token, read once a wallet connects)
+    // has not been read: the box is cleared, and Approve waits for it again.
+    const lines = legal.map(f => f.says);
+    if (lines.some(l => !legalShown.has(l))) $('legalok').checked = false;
+    legalShown = new Set(lines);
     $('legalbox').hidden = Boolean(state.done);
     $('legal').hidden = !legal.length;
     $('legal').replaceChildren(...legal.map(f => Object.assign(document.createElement('li'), { textContent: f.says })));
     const unread = !$('legalok').checked;
+    // The state on the page is the connected wallet's own only once the server has read the chain for it: what it
+    // says of the tokens comes with that. Until then (the read is on its way, or failed) nothing can be approved.
+    const reading = Boolean(account) && !state.done && !state.refused && state.wallet !== account.address;
     // A live section the chain does not bear out: nothing can be approved.
-    $('approve').disabled = state.done || !account || busy || Boolean(state.refused) || unread;
+    $('approve').disabled = state.done || !account || busy || Boolean(state.refused) || unread || reading;
     $('status').textContent = state.done
       ? 'Done.'
       : state.refused
         ? 'Nothing can be approved: see above.'
         : !account
           ? 'Connect a wallet first.'
-          : unread
-            ? 'Read the notice above and tick that you have.'
-            : `${state.remaining} transaction${state.remaining === 1 ? '' : 's'} to go.`;
+          : reading
+            ? 'Reading the chain for your wallet…'
+            : unread
+              ? 'Read the notice above and tick that you have.'
+              : `${state.remaining} transaction${state.remaining === 1 ? '' : 's'} to go.`;
   }
 
   async function refresh() {
@@ -159,7 +171,10 @@ export function approvalPage(token) {
   }
 
   $('legalok').addEventListener('change', () => {
-    if (last) render(last);
+    if (!last) return;
+    // The wallet's own state never arrived (its read failed): asked again, so the box is ticked on what it shows.
+    if (account && !last.done && last.wallet !== account.address) refresh();
+    else render(last);
   });
 
   // One wallet is connected at once; with several in the browser, the person picks one from a list.
@@ -201,7 +216,8 @@ export function approvalPage(token) {
     const signer = account;
     const signingWallet = wallet;
     try {
-      const batch = await api('/api/prepare', { wallet: signer.address });
+      // `read`: the lines about its tokens this page showed when the box was ticked (the server gives no batch for others)
+      const batch = await api('/api/prepare', { wallet: signer.address, read: last?.read ?? null });
       const details = (batch.details ?? []).flat();
       log(
         `Asking your wallet to approve ${batch.transactions.length} transaction${batch.transactions.length === 1 ? '' : 's'} in the project ${batch.project}: ${batch.says.join(' | ')}${details.length ? `. ${details.join('. ')}` : ''}`,

package/js/approve/server.mjs

@@ -71,6 +71,8 @@ export function devnetChain(url = process.env.XSOLANA_RPC_URL || DEVNET) {
     signatureStatus: async signature =>
       (await rpc.call('getSignatureStatuses', [[signature], { searchTransactionHistory: true }])).value[0],
     blockHeight: () => rpc.blockHeight(),
+    /** The chain's current epoch (a mint's transfer fee changes on one). */
+    epoch: async () => Number((await rpc.call('getEpochInfo')).epoch),
   };
 }
 
@@ -153,6 +155,22 @@ export async function createApproval({
 
   /** What is live so far: the spec's own live section (a resumed or changed economy) and what landed this session. */
   const live = () => spec.live ?? null;
+  /**
+   * What the chain says the keys of the mints this spec names can do, where the spec doesn't say it (`checkMints`,
+   * read when a wallet connects): shown with the legal flags, so the owner ticks having read them before approving.
+   */
+  let mintPowers = [];
+  /**
+   * A name for those lines as they stand (null: none). The page hands it back with the owner's tick: a batch is given
+   * out only to a page that showed these very lines, so nothing read after the tick, or never shown, is skipped.
+   */
+  const readKey = () =>
+    mintPowers.length
+      ? createHash('sha256')
+          .update(JSON.stringify(mintPowers.map(t => t.says)))
+          .digest('hex')
+          .slice(0, 24)
+      : null;
 
   /**
    * The owner a setup for `wallet` is built for, and its project, once every mint the spec names is held against the
@@ -162,7 +180,10 @@ export async function createApproval({
    */
   async function trust(wallet) {
     try {
-      await checkMints({ m: model(spec, { now: at }), chain });
+      const m = model(spec, { now: at });
+      // the project a mint the spec calls the project's must name: the live one, else this wallet's own to be
+      const project = live()?.project ?? pda.project(wallet, m.projectNumber);
+      mintPowers = (await checkMints({ m, chain, project })).powers;
     } catch (e) {
       if (!(e instanceof MintMismatch)) throw e;
       throw new ApproveError(
@@ -319,8 +340,10 @@ export async function createApproval({
         ].filter(Boolean),
       ],
       // The legal flags in plain words, shown in a block of their own whatever the agent said: Approve waits until the
-      // owner ticks that they read them.
-      legal,
+      // owner ticks that they read them. With them, what the chain says a named token's mint can do that the spec
+      // doesn't say.
+      legal: [...legal, ...mintPowers.map(t => ({ code: 'W-MINT-POWERS', says: t.says }))],
+      ...(readKey() ? { read: readKey() } : {}),
       authority: model(spec).authority,
       steps,
       landed: [...done].map(id => ({ id, says: said.get(id)?.says ?? id, details: said.get(id)?.details ?? [] })),
@@ -361,10 +384,13 @@ export async function createApproval({
     stateFor(wallet) {
       return serial(() => stateFor(walletAddress(wallet)));
     },
-    /** The next batch for `wallet` to sign: [base64 wire], with what each does. */
-    prepare(wallet) {
+    /**
+     * The next batch for `wallet` to sign: [base64 wire], with what each does. `read`: the state's `read`, as the page
+     * showed it when the owner ticked the box (what the chain says of the tokens this economy names).
+     */
+    prepare(wallet, read = null) {
       if (busy) return Promise.reject(new ApproveError(409, 'A batch is being sent: wait for it.'));
-      return serial(() => prepareFor(walletAddress(wallet)));
+      return serial(() => prepareFor(walletAddress(wallet), read));
     },
     /** The wallet's answer: checked against what was prepared, then sent and confirmed one by one. */
     complete(wallet, id, signed) {
@@ -395,7 +421,7 @@ export async function createApproval({
     return { ...v, remaining: p.transactions.length, done: false };
   }
 
-  async function prepareFor(wallet) {
+  async function prepareFor(wallet, read = null) {
     // A second ask while a batch is out for signing (a double click) gets that same batch, not a new one that would
     // make the first signature fail.
     if (
@@ -407,6 +433,13 @@ export async function createApproval({
       return answer(prepared);
     await settlePending();
     const trusted = await trust(wallet);
+    // What the chain says a named token's mint can do, where the spec doesn't say it, is read with the wallet's own
+    // state: nothing is handed out to sign until the page has shown those very lines and the owner ticked after.
+    if (readKey() && read !== readKey())
+      throw new ApproveError(
+        409,
+        'What the chain says of this economy’s tokens was not on the page when the box was ticked: read the lines above, tick the box again, then approve.',
+      );
     const p = await build(trusted.owner);
     if (!p.transactions.length) throw new ApproveError(409, 'Everything has landed already.');
     await readLive(p);
@@ -885,7 +918,10 @@ export async function approve({
       }
       const body = req.method === 'POST' ? await readJson(req) : {};
       if (req.method === 'POST' && url.pathname === '/api/prepare')
-        return send(200, await session.prepare(String(body.wallet ?? '')));
+        return send(
+          200,
+          await session.prepare(String(body.wallet ?? ''), typeof body.read === 'string' ? body.read : null),
+        );
       if (req.method === 'POST' && url.pathname === '/api/complete') {
         const state = await session.complete(String(body.wallet ?? ''), body.id, body.transactions);
         if (state.done) {

package/js/chain/mint.js

@@ -5,6 +5,7 @@ import { encodeBase58 } from './base58.js';
 import { fromUtf8, readUintLE } from './bytes.js';
 import { NATIVE_MINT, TOKEN_2022_PROGRAM, TOKEN_PROGRAM } from './pda.js';
 import { MINT_BYTES, TOKEN_ACCOUNT_BYTES } from './token.js';
+import { powersOf } from './token2022.js';
 
 /** Where Token-2022 writes what an account with extensions is (1 a mint, 2 a token account): right after a token
  * account's classic bytes. */
@@ -98,3 +99,57 @@ export function parseMint(address, owner, data, metadataData = null) {
     uri: meta?.uri || null,
   };
 }
+
+/** A ticker as a spec's key: lower case, the letters a key takes, a letter first; null when nothing is left. */
+function keyOf(symbol) {
+  const key = String(symbol ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, '')
+    .replace(/^[^a-z]+/, '')
+    .slice(0, 32);
+  // "sol" is SOL's own key in every spec: a coin that calls itself SOL is not it
+  return key === 'sol' ? 'sol-coin' : key || null;
+}
+/**
+ * A text cut to what a spec takes: at most `most` UTF-16 units (what its schema counts), never half a character, with
+ * no control characters (a name is a label on one line).
+ */
+function clip(text, most) {
+  let out = '';
+  for (const c of String(text)) {
+    const code = c.codePointAt(0);
+    // a control character or a line break is a space: a name is a label on one line
+    const plain = code < 0x20 || (code >= 0x7f && code <= 0x9f) || code === 0x2028 || code === 0x2029 ? ' ' : c;
+    if (out.length + plain.length > most) break;
+    out += plain;
+  }
+  return out.replace(/ +/g, ' ').trim();
+}
+
+/**
+ * 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 function tokenEntry(address, account, record = null, { key = null, project = null, epoch = null } = {}) {
+  const mint = account ? parseMint(address, account.owner, account.data, record) : null;
+  if (!mint) return null;
+  if (mint.native) return { key: key ?? 'sol', source: 'sol' };
+  const name = mint.name ? clip(mint.name, 32) : '',
+    symbol = mint.symbol ? clip(mint.symbol, 10) : '';
+  return {
+    key: key ?? keyOf(symbol) ?? 'token',
+    source: 'existing',
+    ...(name ? { name } : {}),
+    ...(symbol ? { symbol } : {}),
+    decimals: mint.decimals,
+    program: mint.program,
+    mint: mint.mint,
+    powers: powersOf(account, { project, epoch }),
+  };
+}