@xgamesfun/solana 0.26.2 → 0.26.4

package/js/approve/server.mjs

@@ -27,7 +27,7 @@ import { ACCOUNT_OVERHEAD, compressedTree, model, MOST_RENT_PER_BYTE } from '../
 import { madeSoFar, plan, PER_APPROVAL } from '../economy/plan.mjs';
 import { compareDetails, liveStepDetails, namesOf, outsideAddresses, stepDetails } from './details.mjs';
 import { freshKeypair, verifySignature } from './ed25519.mjs';
-import { checkLive, checkMints, LiveMismatch, MintMismatch } from './live-check.mjs';
+import { checkLive, checkMints, LiveMismatch, MintMismatch, readRenames } from './live-check.mjs';
 
 const PREPARE_TTL_MS = 90_000;
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -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),
   };
 }
 
@@ -148,11 +150,60 @@ export async function createApproval({
   const signatures = [];
   const at = now();
   const mode = !spec.live ? 'new' : spec.live.partial ? 'resume' : 'change';
-  /** The parts this session publishes: all of them for a new economy, what changed for a live one. */
-  let only = mode === 'change' ? changedParts(spec).only : spec.live?.changing ? new Set(spec.live.changing) : null;
+  /**
+   * The parts this session publishes: all of them for a new economy, what changed for a live one. A change that was
+   * cut short (`partial`, with what was `published` before it) goes on as what the file says changed now, with what
+   * it was changing when it stopped: a part added to the spec since is published too, never recorded as live unsent,
+   * and a change that had no part to publish (a token's name alone) is still a change.
+   */
+  let only =
+    mode === 'change'
+      ? changedParts(spec).only
+      : spec.live?.published
+        ? new Set([...(spec.live.changing ?? []), ...changedParts(spec).only])
+        : spec.live?.changing
+          ? new Set(spec.live.changing)
+          : null;
+  if (mode === 'resume' && spec.live.published) spec = { ...spec, live: { ...spec.live, changing: [...only] } };
+  /**
+   * The live tokens whose name record this session writes again (plan.mjs `renames`), and in words the names the spec
+   * changes that can't be written (`held`: their keys). Until a wallet connects: what the file itself says changed
+   * since it was published. Once one has: what the chain says (`readRenames`), which is all that is ever sent.
+   */
+  let renames = new Set(spec.live?.published ? changedParts(spec).renames : []);
+  let renameNotes = [];
+  let held = new Set();
+  /** The tokens whose record already says the spec's new name, though the file's published spec says the old one. */
+  let settled = new Set();
+  /**
+   * The names this session has written itself, with this spec's words: never offered again, even to a connection
+   * that reads a slot behind. (A name an earlier session sent is not among them: the spec may have changed since, so
+   * the chain alone says whether it is the one wanted.)
+   */
+  const renamed = new Set();
+  /** The transactions this session sent itself. */
+  const sentHere = new Set();
+  /** What a plan of this session is scoped by. */
+  const scope = () => ({ only, renames });
 
   /** 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 +213,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(
@@ -171,7 +225,21 @@ export async function createApproval({
       );
     }
     try {
-      return await checkLive({ live: live(), m: model(spec, { now: at }), wallet, chain });
+      const m = model(spec, { now: at });
+      const trusted = await checkLive({ live: live(), m, wallet, chain });
+      // which names are written again is the chain's to say, read for the project's owner
+      const read = await readRenames({
+        live: live(),
+        m,
+        chain,
+        owner: trusted.owner,
+        published: spec.live?.published ?? null,
+      });
+      renames = new Set(read.renames.filter(key => !renamed.has(key)));
+      renameNotes = read.notes;
+      held = new Set(read.held);
+      settled = new Set(read.settled);
+      return trusted;
     } catch (e) {
       if (!(e instanceof LiveMismatch)) throw e;
       throw new ApproveError(
@@ -182,7 +250,7 @@ export async function createApproval({
   }
 
   async function build(owner) {
-    const p0 = plan(spec, { now: at, live: live(), only });
+    const p0 = plan(spec, { now: at, live: live(), ...scope() });
     if (!p0.ok) throw new ApproveError(400, describe({ refusals: p0.refusals, warnings: [] }));
     for (const name of p0.freshKeys) if (!keys.has(name)) keys.set(name, freshKeypair());
     // The accounts the owner makes outside loot: a mint, and the project's tree of compressed NFTs.
@@ -208,7 +276,7 @@ export async function createApproval({
       live: live() ?? {},
       now: at,
       rent,
-      only,
+      ...scope(),
       slot: hashes[0] ?? null,
     });
     if (!p.ok) throw new ApproveError(400, describe({ refusals: p.refusals, warnings: [] }));
@@ -284,8 +352,11 @@ export async function createApproval({
 
   /** What each step does, in words, kept after it lands (the plan no longer lists it then). */
   const said = new Map();
+  /** The same for the steps still to do: a step's words become `said` when this session's own transaction lands it. */
+  const planned = new Map();
   function view(p, n = names(), extra = {}) {
-    const done = new Set(live()?.landed ?? []);
+    // A step the plan lists is still to do, whatever landed under its id before (a token's name written, then changed
+    // again before the change was gone on with): it is never shown as done, nor among what landed.
     const steps = p.ok
       ? p.transactions.flatMap(t =>
           t.steps.map((s, i) => ({
@@ -293,23 +364,27 @@ export async function createApproval({
             says: s.says,
             details: detailsOf(t, i, n),
             signer: t.signer,
-            done: done.has(s.id),
+            done: false,
           })),
         )
       : [];
-    for (const s of steps) said.set(s.id, s);
+    const todo = new Set(steps.map(s => s.id));
+    const done = new Set((live()?.landed ?? []).filter(id => !todo.has(id)));
+    // (what a landed step did is kept in its own words: a later step of the same id never rewrites them)
+    for (const s of steps) planned.set(s.id, s);
     return {
       name: spec.name ?? path.basename(file),
       file: path.basename(file),
       mode,
       program: LOOT_PROGRAM,
       cluster: 'devnet',
-      setupSol: cost(spec, { now: at, live: live(), only }).setup?.totalSol ?? null,
+      setupSol: cost(spec, { now: at, live: live(), ...scope() }).setup?.totalSol ?? null,
       warnings: [
         ...(extra.refused ? [extra.refused] : []),
         ...verdict.warnings.filter(w => !Object.hasOwn(LEGAL, w.code)).map(w => w.message),
         ...[
           settings,
+          ...renameNotes,
           unread(),
           remadeLists(),
           outsideAddresses(
@@ -319,8 +394,12 @@ 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() } : {}),
+      // A token's name the spec changes and the chain can't take: said whatever else is on the page, done or not.
+      unwritten: [...renameNotes],
       authority: model(spec).authority,
       steps,
       landed: [...done].map(id => ({ id, says: said.get(id)?.says ?? id, details: said.get(id)?.details ?? [] })),
@@ -349,9 +428,14 @@ export async function createApproval({
     },
     /** The steps still to go and what is done, built on stand-in addresses until a wallet connects. */
     state() {
-      const p = plan(spec, { now: at, live: live(), only });
+      const p = plan(spec, { now: at, live: live(), ...scope() });
       const v = view(p);
-      return { ...v, remaining: p.ok ? p.transactions.length : 0, done: p.ok && p.transactions.length === 0 };
+      // (a file still marked as under way is settled, and recorded as live, only by a connected wallet's read)
+      return {
+        ...v,
+        remaining: p.ok ? p.transactions.length : 0,
+        done: p.ok && p.transactions.length === 0 && !spec.live?.partial,
+      };
     },
     /**
      * The same, for the connected `wallet`: built exactly as its batches will be (its own project, the treasury on
@@ -361,10 +445,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) {
@@ -375,11 +462,15 @@ export async function createApproval({
 
   async function stateFor(wallet) {
     let trusted;
-    let p0 = plan(spec, { now: at, live: live(), only });
+    let p0 = plan(spec, { now: at, live: live(), ...scope() });
     try {
       await settlePending();
-      p0 = plan(spec, { now: at, live: live(), only });
+      // (what a transaction found landed leaves to do: shown as it is under a refusal too)
+      p0 = plan(spec, { now: at, live: live(), ...scope() });
       trusted = await trust(wallet);
+      await finish({ owner: trusted.owner });
+      await settle();
+      p0 = plan(spec, { now: at, live: live(), ...scope() });
     } catch (e) {
       if (!(e instanceof ApproveError)) throw e;
       const v = view(p0, namesOf(model(spec, { now: at }), { now: at, owner: wallet }), { refused: e.message });
@@ -388,6 +479,14 @@ export async function createApproval({
     if (!p0.ok || !p0.transactions.length)
       return { ...view(p0, names(), { project: trusted.project }), remaining: 0, done: p0.ok };
     const p = await build(trusted.owner);
+    if (!p.transactions.length) {
+      // Steps are planned and none builds: the lookup table's, which can't be made without a recent slot (the chain's
+      // slot hashes did not read). Nothing needs the table, or the build would have refused, so the setup is as live
+      // as it can be made and is recorded so.
+      await finish(p.ctx, { nothingBuilds: true });
+      const left = plan(spec, { now: at, live: live(), ...scope() });
+      return { ...view(left, names(), { project: trusted.project }), remaining: 0, done: !spec.live?.partial };
+    }
     await readLive(p);
     const v = view(p, namesOf(model(spec, { now: at }), { now: at, owner: wallet, treasury: p.ctx.treasury }), {
       project: p.ctx.project,
@@ -395,7 +494,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,8 +506,21 @@ export async function createApproval({
       return answer(prepared);
     await settlePending();
     const trusted = await trust(wallet);
+    await finish({ owner: trusted.owner });
+    await settle();
+    // 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.');
+    if (!p.transactions.length) {
+      // (planned steps none of which builds: see stateFor)
+      await finish(p.ctx, { nothingBuilds: true });
+      throw new ApproveError(409, 'Everything has landed already.');
+    }
     await readLive(p);
     const authority = p.ctx.authority;
     const first = p.transactions[0];
@@ -477,6 +589,7 @@ export async function createApproval({
         // sent twice (`settlePending`).
         const signature = encodeBase58(readTransaction(wire).signatures[0]);
         const sent = batch.batch[i];
+        sentHere.add(signature);
         await remember({
           signature,
           steps: sent.steps.map(s => s.id),
@@ -507,7 +620,7 @@ export async function createApproval({
           }
         }
         signatures.push(signature);
-        await landed(sent, batch.ctx, signature);
+        await landed(sent, batch.ctx, signature, { more: i < wires.length - 1 });
       }
     } finally {
       busy = false;
@@ -567,6 +680,12 @@ export async function createApproval({
     const pending = spec.live.pending.filter(p => p.signature !== signature);
     const { pending: _, ...rest } = spec.live;
     spec = { ...spec, live: pending.length ? { ...rest, pending } : rest };
+    // A change of which nothing was sent that could land is no change under way: the file reads as live again, and
+    // the next approve works out the change afresh.
+    if (!pending.length && rest.partial && rest.published && !rest.landed?.length) {
+      const { partial: _p, landed: _l, changing: _c, ...asItWas } = rest;
+      spec = { ...spec, live: asItWas };
+    }
     generation++;
     await write(file, `${JSON.stringify(spec, null, 2)}\n`);
   }
@@ -594,10 +713,13 @@ export async function createApproval({
       const status = await chain.signatureStatus(entry.signature);
       if (landedStatus(status)) {
         if (!signatures.includes(entry.signature)) signatures.push(entry.signature);
+        // (never recorded as the whole setup here: whether a token's name is still to write is read from the chain
+        // first, in `trust`, and `finish` records it after)
         await landed(
           { steps: entry.steps.map(id => ({ id })) },
           { ...(entry.made ?? {}), owner: await projectOwner(entry.made?.project ?? spec.live?.project) },
           entry.signature,
+          { more: true },
         );
         continue;
       }
@@ -621,15 +743,28 @@ export async function createApproval({
   /**
    * One transaction landed: the spec's live section learns its steps, and the file is written at once. It names only
    * what those steps made (the project once `project` landed, a mint once its `token:` step did, …): an account whose
-   * own transaction has not landed is made again when the setup goes on.
+   * own transaction has not landed is made again when the setup goes on. `more`: more of the same batch is still to
+   * send, or the chain has not been read yet for what is left (a transaction found landed from an earlier session):
+   * the file is not recorded as live on this landing.
    */
-  async function landed(transaction, ctx, signature) {
+  async function landed(transaction, ctx, signature, { more = false } = {}) {
     const was = spec.live ?? {};
     const ids = transaction.steps.map(s => s.id);
     const made = new Set(ids);
     const mints = { ...(was.mints ?? {}) };
     for (const id of ids)
       if (id.startsWith('token:') && ctx.mints?.[id.slice(6)]) mints[id.slice(6)] = ctx.mints[id.slice(6)];
+    // What this session sent itself did what its steps were shown to do (one found landed from an earlier session
+    // was built from the file as it was then, which may have been edited since: only the chain says what it did).
+    if (sentHere.has(signature))
+      for (const id of ids) {
+        if (planned.has(id)) said.set(id, planned.get(id));
+        // a name written with this spec's words is done
+        if (id.startsWith('name:')) {
+          renames.delete(id.slice(5));
+          renamed.add(id.slice(5));
+        }
+      }
     const progress = {
       ...was,
       program: LOOT_PROGRAM,
@@ -637,6 +772,8 @@ export async function createApproval({
       ...(made.has('collection') && ctx.collection ? { collection: ctx.collection } : {}),
       ...(made.has('tree') && ctx.tree ? { tree: ctx.tree } : {}),
       ...(made.has('table') && ctx.slot != null ? { tables: [tableAddress(ctx.owner, ctx.slot)[0]] } : {}),
+      // (a transaction found landed from an earlier session names the table it made itself)
+      ...(made.has('table') && ctx.slot == null && ctx.tables?.length ? { tables: ctx.tables } : {}),
       mints,
       landed: [...new Set([...(was.landed ?? []), ...ids])],
       partial: true,
@@ -652,22 +789,77 @@ export async function createApproval({
     if (!progress.collection) delete progress.collection;
     spec = { ...spec, live: progress };
     generation++;
-    const rest = plan(spec, { now: at, live: spec.live, only });
-    if (rest.ok && rest.transactions.length === 0) {
-      const { live: _, ...bare } = spec;
-      // Everything the setup made, whichever session or transaction made it.
-      const all = {
-        ...ctx,
-        ...Object.fromEntries(
-          ['project', 'treasury', 'authority', 'collection', 'tree', 'tables'].map(k => [k, progress[k] ?? ctx[k]]),
-        ),
-        mints: { ...(ctx.mints ?? {}), ...(progress.mints ?? {}) },
+    if (!more) record(ctx);
+    await write(file, `${JSON.stringify(spec, null, 2)}\n`);
+  }
+
+  /**
+   * Records the setup or the change as live, once nothing of it is left: no transaction still looked for, and no step
+   * in a plan made with what the chain says of the tokens' names (`trust`, read for this session's wallet before this
+   * is ever called). `published` becomes the spec as it is, but for a token's name the chain could not take (`held`):
+   * that token keeps the name, ticker and link it was published with, so the file never says of a name what the chain
+   * does not, and the next approve says it again. Returns whether it did.
+   */
+  function record(ctx = {}, { nothingBuilds = false } = {}) {
+    const progress = spec.live;
+    if (!progress?.partial || progress.pending?.length) return false;
+    // `nothingBuilds`: the plan built for this wallet has no transaction, whatever a plan on stand-in addresses lists
+    const rest = plan(spec, { now: at, live: progress, ...scope() });
+    if (!rest.ok || (rest.transactions.length && !nothingBuilds)) return false;
+    const { live: _, ...bare } = spec;
+    // Everything the setup made, whichever session or transaction made it.
+    const all = {
+      ...ctx,
+      ...Object.fromEntries(
+        ['project', 'treasury', 'authority', 'collection', 'tree', 'tables'].map(k => [k, progress[k] ?? ctx[k]]),
+      ),
+      mints: { ...(ctx.mints ?? {}), ...(progress.mints ?? {}) },
+    };
+    const final = recordLanded(bare, { ctx: all, now: at, at: new Date(clock()).toISOString() });
+    const before = progress.published?.tokens ?? null;
+    if (before && held.size)
+      final.live.published.tokens = final.live.published.tokens.map(t => {
+        const was = held.has(t.key) ? before.find(x => x.key === t.key) : null;
+        if (!was) return t;
+        const { name: _n, symbol: _s, uri: _u, ...kept } = t;
+        return {
+          ...kept,
+          ...Object.fromEntries(['name', 'symbol', 'uri'].filter(f => was[f] !== undefined).map(f => [f, was[f]])),
+        };
+      });
+    final.live = { ...final.live, transactions: progress.transactions ?? [] };
+    spec = final;
+    only = changedParts(spec).only;
+    return true;
+  }
+
+  /** `record`, with the file written when it did: after a wallet's read found nothing left of a setup under way. */
+  async function finish(ctx, options) {
+    if (!record(ctx, options)) return;
+    generation++;
+    await write(file, `${JSON.stringify(spec, null, 2)}\n`);
+  }
+
+  /**
+   * A name the chain already carries is the published one from here on (`settled`, from this wallet's read): only
+   * that token's name, ticker and link move in the file's published spec, so no tool keeps announcing a change that
+   * is done. A setup or change under way records it when it is recorded as live.
+   */
+  async function settle() {
+    const now = spec.live;
+    if (!now?.published || now.partial || !settled.size) return;
+    const tokens = (now.published.tokens ?? []).map(t => {
+      const said = settled.has(t.key) ? (spec.tokens ?? []).find(x => x.key === t.key) : null;
+      if (!said) return t;
+      const { name: _n, symbol: _s, uri: _u, ...kept } = t;
+      return {
+        ...kept,
+        ...Object.fromEntries(['name', 'symbol', 'uri'].filter(f => said[f] !== undefined).map(f => [f, said[f]])),
       };
-      const final = recordLanded(bare, { ctx: all, now: at, at: new Date(clock()).toISOString() });
-      final.live = { ...final.live, transactions: progress.transactions };
-      spec = final;
-      only = changedParts(spec).only;
-    }
+    });
+    spec = { ...spec, live: { ...now, published: { ...now.published, tokens } } };
+    settled = new Set();
+    generation++;
     await write(file, `${JSON.stringify(spec, null, 2)}\n`);
   }
 }
@@ -885,7 +1077,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/metadata.js

@@ -72,5 +72,97 @@ export function createFungibleMetadataIx({ mint, authority, payer = authority, n
   };
 }
 
+const UPDATE_V2 = 15;
+/**
+ * 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 function updateFungibleMetadataIx({ mint, authority, name, symbol, uri = '' }) {
+  for (const [field, value] of Object.entries({ name, symbol, uri })) {
+    if (typeof value !== 'string') throw new TypeError(`A token's ${field} is text`);
+    if (utf8(value).length > METADATA_LIMITS[field])
+      throw new RangeError(`A token's ${field} is at most ${METADATA_LIMITS[field]} bytes`);
+  }
+  return {
+    programId: METAPLEX_METADATA_PROGRAM,
+    keys: [meta(metadataAddress(mint), false, true), meta(authority, true, false)],
+    data: concat(
+      Uint8Array.of(UPDATE_V2),
+      Uint8Array.of(1), // new data
+      text(name),
+      text(symbol),
+      text(uri),
+      uintLE(0, 2), // no resale royalty
+      NONE, // no creators
+      NONE, // no collection
+      NONE, // no uses
+      NONE, // the update authority: as it is
+      NONE, // primary sale: as it is
+      NONE, // changeable: as it is
+    ),
+  };
+}
+
+/**
+ * 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 function parseRecord(data) {
+  try {
+    if (!data || data.length < 1 + 32 + 32 + 12 || data[0] !== 4) return null;
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    let at = 65;
+    const words = [];
+    for (let i = 0; i < 3; i++) {
+      const length = view.getUint32(at, true);
+      if (at + 4 + length > data.length) return null;
+      words.push(new TextDecoder().decode(data.subarray(at + 4, at + 4 + length)).replaceAll('\0', ''));
+      at += 4 + length;
+    }
+    if (at + 3 > data.length) return null;
+    const royalty = view.getUint16(at, true);
+    at += 2;
+    let creators = 0;
+    if (data[at++] === 1) {
+      creators = view.getUint32(at, true);
+      at += 4 + 34 * creators;
+    }
+    if (at + 2 > data.length) return null;
+    const mutable = data[at + 1] === 1;
+    at += 2; // sold once, and whether it can be changed
+    // What follows is each there or not (a byte), with its value when it is: the edition's nonce, the token's standard,
+    // then the collection (verified, and its address) and the uses (a method and two counts). A record cut short
+    // before them names neither.
+    for (let i = 0; i < 2 && at < data.length; i++) at += data[at] === 1 ? 2 : 1;
+    const collection = at < data.length && data[at] === 1;
+    at += collection ? 34 : 1;
+    const uses = at < data.length && data[at] === 1;
+    return {
+      updateAuthority: encodeBase58(data.subarray(1, 33)),
+      mint: encodeBase58(data.subarray(33, 65)),
+      name: words[0],
+      symbol: words[1],
+      uri: words[2],
+      royalty,
+      creators,
+      mutable,
+      collection,
+      uses,
+      plain: royalty === 0 && creators === 0 && !collection && !uses,
+    };
+  } catch {
+    return null;
+  }
+}
+
 /** The update authority a Token Metadata record names (who can change its name, ticker and link). */
 export const metadataUpdateAuthority = data => (data?.length >= 33 ? encodeBase58(data.subarray(1, 33)) : null);

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 }),
+  };
+}