@xgamesfun/solana 0.26.2 → 0.26.4

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.4 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.4 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.4 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.4 check xsolana.json
+npx -y @xgamesfun/solana@0.26.4 simulate xsolana.json
+npx -y @xgamesfun/solana@0.26.4 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.4 explain xsolana.json
+npx -y @xgamesfun/solana@0.26.4 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.4 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

@@ -5,10 +5,14 @@
 // the tree the file calls made must be on chain and be that project's.
 import { encodeBase58 } from '../chain/base58.js';
 import { parseCoreCollection, MPL_CORE_PROGRAM } from '../chain/core.js';
+import { utf8 } from '../chain/bytes.js';
+import { METADATA_LIMITS, metadataAddress, parseRecord } from '../chain/metadata.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';
+import { METAPLEX_METADATA_PROGRAM, SYSTEM_PROGRAM } from '../chain/pda.js';
+import { tokenLabels } from '../economy/model.mjs';
 import { madeSoFar } from '../economy/plan.mjs';
 
 /** A `live` section that does not match the chain: the message says what differs, in plain words. */
@@ -115,18 +119,216 @@ export async function checkLive({ live, m, wallet, chain }) {
   return { owner, project };
 }
 
+/**
+ * A record's own words, to show: whoever holds the record wrote them, so they are put on one line, cut short, with
+ * nothing in them that hides, reorders or closes a quote (controls, marks that turn text around or take no room, line
+ * breaks, quote marks), and are only ever shown inside quotes.
+ */
+const HIDES = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\p{Default_Ignorable_Code_Point}"“”„‟«»]/gu;
+const clip = text => [...String(text).replace(HIDES, '')].slice(0, 40).join('');
+
+/**
+ * The tokens whose name record this approval writes again, read from the chain: `renames`, their keys; `notes`, in
+ * words, for a name the spec changes that can't be written; and `held`, the keys of those. A token the setup made
+ * (`live.mints`) is called on chain what its record says. Its spec's name, ticker or link is written there again when
+ *   - the spec gives them otherwise than it was published with (`published`: the file's own snapshot; with none, a
+ *     setup cut short, the chain alone is the measure, so a name edited before a resume is written), and
+ *   - the record says something else, is the mint's, is the project owner's to change (its update authority, and
+ *     still changeable) and holds nothing a write of its words would take away (a royalty, creators, a collection,
+ *     uses: `parseRecord`'s `plain`).
+ * A token with no record (one that went live before setups named tokens), or a record handed on, made unchangeable
+ * or given a royalty or creators outside these tools, is not written: said in `notes`, and nothing else is held up.
+ * A name so held is not recorded as published (approve/server.mjs), so it is said again at each approve until the
+ * spec gives the old name back. Nothing here trusts the file for what is on chain. `owner`: the project's owner.
+ */
+export async function readRenames({ live, m, chain, owner, published = null }) {
+  const out = { renames: [], notes: [], held: [], settled: [] };
+  const made = madeSoFar(live) ?? {};
+  // A name this setup or change wrote already, or sent and has not seen land (the file is still `partial`): the
+  // record no longer says what was published, so the published spec is no measure of it and the chain is read.
+  const step = key => `name:${key}`;
+  const written = key =>
+    Boolean(live?.partial) &&
+    ((live.landed ?? []).includes(step(key)) || (live.pending ?? []).some(p => (p.steps ?? []).includes(step(key))));
+  if (typeof chain.account !== 'function') return out;
+  const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+  const hold = (key, note) => {
+    out.held.push(key);
+    out.notes.push(note);
+  };
+  for (const [key, address] of Object.entries(made.mints ?? {})) {
+    const t = m.tokens.get(key);
+    if (t?.source !== 'game' || (t.mint && !t.mint.startsWith('@'))) continue;
+    const want = [t.name, t.symbol, t.uri ?? ''];
+    const was = published ? (published.tokens ?? []).find(x => x.key === key) : null;
+    const said = was ? tokenLabels(was) : null;
+    // as it was published: nothing asked for, and a record its owner changed elsewhere is left as it is
+    const asPublished = Boolean(said) && same(said, want);
+    if (asPublished && !written(key)) continue;
+    // (the token as the person knows it: by the ticker it was published with)
+    const what = `the token ${said?.[1] ?? t.symbol ?? key}`;
+    const again = 'This is said at each approve until the spec gives the old name, ticker and link back.';
+    const account = await chain.account(metadataAddress(address));
+    const record = account?.owner === METAPLEX_METADATA_PROGRAM ? parseRecord(account.data) : null;
+    if (!record || record.mint !== address) {
+      if (said && !asPublished)
+        hold(
+          key,
+          account?.owner === METAPLEX_METADATA_PROGRAM
+            ? `The spec changes what ${what} is called, but the name record of its mint ${address} can’t be read as one: nothing is sent for it. ${again}`
+            : `The spec changes what ${what} is called, but it went live before setups named tokens on chain: it has no name record, and none can be made now (only a mint’s own authority makes one, and its minting was handed on or turned off). Nothing is sent for it, and wallets keep showing it as before. ${again}`,
+        );
+      continue;
+    }
+    if (same([record.name, record.symbol, record.uri], want)) {
+      // the chain says the spec's name already (written by another tool, or by a session whose file was lost): it is
+      // the published one from here on
+      if (said && !asPublished) out.settled.push(key);
+      continue;
+    }
+    const called = `“${clip(record.name)}” (“${clip(record.symbol)}”)`;
+    const kept = `nothing is sent for it, and wallets keep showing ${called}. ${said ? again : ''}`.trim();
+    if (record.updateAuthority !== owner)
+      hold(
+        key,
+        `The spec changes what ${what} is called, but its name record is no longer the project owner’s to change (it was handed to another wallet, outside these tools): ${kept}`,
+      );
+    else if (!record.mutable)
+      hold(
+        key,
+        `The spec changes what ${what} is called, but its name record can no longer be changed (it was made unchangeable, outside these tools): ${kept}`,
+      );
+    else if (!record.plain)
+      hold(
+        key,
+        `The spec changes what ${what} is called, but its name record was given ${[record.royalty ? 'a royalty' : null, record.creators ? 'creators' : null, record.collection ? 'a collection' : null, record.uses ? 'uses' : null].filter(Boolean).join(', ')} outside these tools, which writing its name from here would take away or be refused for: ${kept} Change its name with the tool that set those.`,
+      );
+    // (the checker holds a changed name to what a record takes; a setup cut short has no published spec to say it
+    // changed, so it is held to it here)
+    else if (
+      want.some(
+        (v, i) => utf8(String(v)).length > [METADATA_LIMITS.name, METADATA_LIMITS.symbol, METADATA_LIMITS.uri][i],
+      ) ||
+      !String(t.name).trim() ||
+      !String(t.symbol).trim()
+    )
+      hold(
+        key,
+        `The spec changes what ${what} is called to words a name record can’t take (a name of at most ${METADATA_LIMITS.name} bytes, a ticker of at most ${METADATA_LIMITS.symbol}, a link of at most ${METADATA_LIMITS.uri}, and neither name nor ticker blank): ${kept}`,
+      );
+    else out.renames.push(key);
+  }
+  return out;
+}
+
 /** 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 +353,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.html

@@ -208,7 +208,7 @@
       </section>
 
       <section class="panel" id="warnbox" hidden>
-        <b>Before you approve</b>
+        <b id="warnhead">Before you approve</b>
         <ul class="warn" id="warnings"></ul>
       </section>
 

package/js/approve/page.js

@@ -60,11 +60,23 @@ 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}”`;
+    // A token's name the spec changes and the chain can't take (`unwritten`): said whether or not anything else was
+    // sent. With nothing else to send, the page never calls that a landing.
+    const unwritten = state.unwritten ?? [];
+    const nothingSent = state.done && unwritten.length > 0 && !state.signatures?.length;
+    $('title').textContent = state.done
+      ? nothingSent
+        ? `Nothing to send for “${state.name}”`
+        : `“${state.name}” is live`
+      : `Approve “${state.name}”`;
     $('sub').textContent = state.done
-      ? `Every step landed on devnet. ${state.file} now holds the project’s addresses: you can close this page.`
+      ? nothingSent
+        ? `The only change in ${state.file} is a token’s name, and it can’t be written on chain: nothing was sent, and the file is as it was. See below.`
+        : `Every step landed on devnet. ${state.file} now holds the project’s addresses: you can close this page.`
       : `${state.mode === 'change' ? 'A change to a live economy' : state.mode === 'resume' ? 'A setup that was cut short goes on' : 'A new economy'} from ${state.file}, on the shared loot program ${state.program.slice(0, 6)}…${state.project ? `, in the project ${state.project}${state.wallet ? `, made from your wallet ${state.wallet}` : ''}` : ''}`;
     $('cost').textContent = state.setupSol !== null && state.mode === 'new' ? `about ${state.setupSol} SOL` : '';
     const steps = $('steps');
@@ -89,29 +101,43 @@ export function approvalPage(token) {
         return li;
       }),
     );
-    const warnings = state.warnings ?? [];
-    $('warnbox').hidden = !warnings.length || state.done;
+    // Once done, what was to be read before approving is past; what could not be written still stands.
+    const warnings = state.done ? unwritten : (state.warnings ?? []);
+    $('warnbox').hidden = !warnings.length;
+    $('warnhead').textContent = state.done ? 'Not written' : 'Before you approve';
     $('warnings').replaceChildren(
       ...warnings.map(w => Object.assign(document.createElement('li'), { textContent: w })),
     );
     // 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.'
+      ? nothingSent
+        ? 'Nothing to approve.'
+        : '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 +185,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 +230,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('. ')}` : ''}`,