@xgamesfun/solana 0.25.4 → 0.26.0

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.25.4 xsolana mcp`.
+**Cursor, Cline, opencode or any MCP client:** run `npx -y --package=@xgamesfun/solana@0.26.0 xsolana mcp`.
 
 **Any agent that reads skills** (Copilot, Gemini CLI, Windsurf…): `npx skills add XGamesFun/solana-kit`.
 
@@ -75,19 +75,19 @@ are in [docs/harnesses.md](docs/harnesses.md).
 
 ```bash
 # find a worked example close to your idea
-npx -y @xgamesfun/solana@0.25.4 examples shop with loot boxes
+npx -y @xgamesfun/solana@0.26.0 examples shop with loot boxes
 
 # does it work? where does the money go? what does it cost?
-npx -y @xgamesfun/solana@0.25.4 check xsolana.json
-npx -y @xgamesfun/solana@0.25.4 simulate xsolana.json
-npx -y @xgamesfun/solana@0.25.4 cost xsolana.json
+npx -y @xgamesfun/solana@0.26.0 check xsolana.json
+npx -y @xgamesfun/solana@0.26.0 simulate xsolana.json
+npx -y @xgamesfun/solana@0.26.0 cost xsolana.json
 
 # the whole economy in plain words, and what a cheater could get
-npx -y @xgamesfun/solana@0.25.4 explain xsolana.json
-npx -y @xgamesfun/solana@0.25.4 review xsolana.json
+npx -y @xgamesfun/solana@0.26.0 explain xsolana.json
+npx -y @xgamesfun/solana@0.26.0 review xsolana.json
 
 # go live, approved in your own wallet
-npx -y @xgamesfun/solana@0.25.4 approve xsolana.json
+npx -y @xgamesfun/solana@0.26.0 approve xsolana.json
 ```
 
 Each command names an exact version, so you always run the release you meant to. `xsolana help` lists them all.

package/js/approve/details.mjs

@@ -6,10 +6,31 @@ import { decodeBorsh } from '../chain/borsh.js';
 import { equalBytes, toHex } from '../chain/bytes.js';
 import { accountKind, decode, IDL, instructionOf, keyLeaf, merkleRoot } from '../client/index.js';
 import { LOOT_PROGRAM, pda } from '../client/pda.js';
+import { dateWords, FAR_SECONDS } from '../economy/check.mjs';
 import { fromUnits } from '../economy/model.mjs';
 import { grantArgs } from '../economy/plan.mjs';
 
 const NOBODY = '11111111111111111111111111111111';
+/** What places of tokens from a short pool get, by their `when_short`. */
+const SHORT = {
+  InOrder: 'whole prizes, first place first, while the pool covers one',
+  InProportion: 'every place the same share of its prize',
+  Nothing: 'no place gets anything, and the pool keeps it',
+};
+/** What a far time is, by the field that holds it. */
+const FAR = {
+  draws_at: 'The first draw',
+  ends_at: 'The auction ends',
+  result_by: 'The result is due',
+  next_at: 'The first run',
+};
+/** A number of seconds in words: "1 day", "36 hours", "90 seconds". */
+const duration = v => {
+  const n = Number(v);
+  if (n % 86_400 === 0) return `${n / 86_400} day${n === 86_400 ? '' : 's'}`;
+  if (n % 3_600 === 0) return `${n / 3_600} hours`;
+  return `${n} seconds`;
+};
 const ZERO = new Uint8Array(32);
 
 /** An instruction's accounts by name, nested groups flattened, in the order the program takes them. */
@@ -32,11 +53,12 @@ function readLootInstruction(ix) {
  * connected; `treasury`: the treasury's address when it is known (else "your wallet" stands for it, as the setup
  * makes it).
  */
-export function namesOf(m, { owner = null, treasury = null } = {}) {
+export function namesOf(m, { owner = null, treasury = null, now = null } = {}) {
   return {
     m,
     owner,
     treasury,
+    now,
     pools: new Map(m.pools.map(p => [p.index, p.key])),
     stashes: new Map(m.stashes.map(s => [s.id, s.name ?? s.key])),
     grants: new Map(m.grants.map(g => [g.id, g])),
@@ -151,6 +173,8 @@ function readDetails(reads, names) {
           : treasury()
         : treasury();
     const to = v => (v === 'Burn' ? 'burned' : `to ${where(v)}`);
+    // A time more than three years after now: the program takes it, and the owner sees its date before signing.
+    const far = v => Number(v) - (names.now ?? Math.floor(Date.now() / 1000)) > FAR_SECONDS;
     const isTo = v =>
       v === 'Burn' ||
       v === 'Treasury' ||
@@ -176,7 +200,33 @@ function readDetails(reads, names) {
               ? `Places paid from: its pot ${v.Pot[0]}, kept from round to round (what anyone sends it, yield and what earlier rounds left all count)`
               : `Places paid from: each round’s own ticket money alone; what they leave is ${v.Round.rest === 'Burn' ? 'burned' : `sent to ${where(v.Round.rest)}`}`,
           );
-        } else if (k === 'to' && isTo(v))
+        } else if (k === 'when_out' && v === 'GiveNothing')
+          lines.push(
+            'When an outcome is out: a draw on it gives nothing, and a paid draw is not refunded (the box keeps selling)',
+          );
+        else if (k === 'closes_before' && BigInt(v ?? 0) > 0n)
+          lines.push(`Sales close ${duration(v)} before each draw`);
+        else if (k === 'time_weighted' && v === true)
+          lines.push(
+            'Tickets weighed by time: each purchase counts its tickets times the seconds left until sales close, so a ticket bought early has a better chance',
+          );
+        else if (k === 'places' && Array.isArray(v)) {
+          // What places of tokens from a pool get when it is short, read once when the draw is asked.
+          const short = [...new Set(v.filter(p => p?.prize?.Tokens?.from?.Pool).map(p => p.when_short))];
+          if (short.length)
+            lines.push(
+              `If a pool its places are paid from holds less than they win: ${short.map(x => SHORT[x] ?? x).join('; ')}`,
+            );
+          walk(v);
+        } else if (['draws_at', 'ends_at', 'result_by', 'next_at'].includes(k) && far(v))
+          lines.push(
+            `${FAR[k]} on ${dateWords(Number(v))}, ${Math.floor((Number(v) - (names.now ?? Math.floor(Date.now() / 1000))) / 31_536_000)} years from now: what waits on it is locked until then. Check the unit before approving`,
+          );
+        else if (k === 'extend' && read.name === 'open_auction' && Number(v) > FAR_SECONDS)
+          lines.push(
+            `A late bid moves the end by ${duration(v)}: one bid holds the lot and itself that long. Check the unit before approving`,
+          );
+        else if (k === 'to' && isTo(v))
           lines.push(v === 'Burn' ? 'Burns the tokens it takes' : `Sends tokens to ${where(v)}`);
         else if (k === 'Give' && Array.isArray(v) && typeof v[0] === 'string')
           lines.push(`Gives the NFT to ${address(v[0])}`);

package/js/approve/live-check.mjs

@@ -6,7 +6,6 @@
 import { encodeBase58 } from '../chain/base58.js';
 import { parseCoreCollection, MPL_CORE_PROGRAM } from '../chain/core.js';
 import { parseMint } from '../chain/mint.js';
-import { mayStartFrozen } 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';
@@ -128,16 +127,6 @@ export class MintMismatch extends Error {}
  */
 export async function checkMints({ m, chain }) {
   const named = [...m.tokens.values()].filter(t => t.mint && !t.mint.startsWith('@'));
-  // The routes that read a mint's default account state once, as they open, and refuse one that can start frozen.
-  const once = new Map();
-  const reads = (key, what) => key && !once.has(key) && once.set(key, what);
-  for (const l of m.lotteries)
-    (reads(l.currency ?? m.currencyKey, `the lottery ${l.name ?? l.key}`),
-      reads(l.ticketCurrency, `the lottery ${l.name ?? l.key}`));
-  for (const c of m.contests) reads(c.currency ?? m.currencyKey, `the contest ${c.name ?? c.key}`);
-  for (const a of m.auctions) reads(a.currency ?? m.currencyKey, `the auction ${a.name ?? a.key}`);
-  for (const s of m.schedules.filter(x => x.sealed))
-    reads(s.currency ?? m.currencyKey, `the sealed schedule ${s.name ?? s.key}`);
   for (const t of named) {
     const what = `the token ${t.symbol ?? t.key} (“${t.key}”)`;
     if (t.wsol) {
@@ -162,10 +151,6 @@ 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}".`,
       );
-    if (once.has(t.key) && mayStartFrozen(account))
-      throw new MintMismatch(
-        `The mint ${t.mint} of ${what} has a default account state that starts new accounts frozen, or that its freeze authority can switch to frozen, so ${once.get(t.key)} would be refused as it opens (the program refuses such a mint wherever a refund or a payout goes into an account opened for it). Use another token there.`,
-      );
   }
   await checkTreasury({ m, chain });
 }

package/js/approve/server.mjs

@@ -221,6 +221,7 @@ export async function createApproval({
    */
   const names = () =>
     namesOf(model(spec, { now: at }), {
+      now: at,
       treasury: madeSoFar(live())?.treasury ?? model(spec, { now: at }).treasuryWallet ?? null,
     });
   /**
@@ -232,7 +233,7 @@ export async function createApproval({
   async function readLive(p) {
     if (!spec.live?.published || typeof chain.account !== 'function') return;
     // The names a published list or key list goes by: the published spec's, each held against the root on chain.
-    const n = namesOf(model(spec.live.published, { now: at }), { treasury: p.ctx.treasury });
+    const n = namesOf(model(spec.live.published, { now: at }), { now: at, treasury: p.ctx.treasury });
     const was = new Map();
     for (const t of p.transactions) {
       for (const [i, step] of t.steps.entries()) {
@@ -381,14 +382,14 @@ export async function createApproval({
       trusted = await trust(wallet);
     } catch (e) {
       if (!(e instanceof ApproveError)) throw e;
-      const v = view(p0, namesOf(model(spec, { now: at }), { owner: wallet }), { refused: e.message });
+      const v = view(p0, namesOf(model(spec, { now: at }), { now: at, owner: wallet }), { refused: e.message });
       return { ...v, remaining: p0.ok ? p0.transactions.length : 0, done: false };
     }
     if (!p0.ok || !p0.transactions.length)
       return { ...view(p0, names(), { project: trusted.project }), remaining: 0, done: p0.ok };
     const p = await build(trusted.owner);
     await readLive(p);
-    const v = view(p, namesOf(model(spec, { now: at }), { owner: wallet, treasury: p.ctx.treasury }), {
+    const v = view(p, namesOf(model(spec, { now: at }), { now: at, owner: wallet, treasury: p.ctx.treasury }), {
       project: p.ctx.project,
     });
     return { ...v, remaining: p.transactions.length, done: false };
@@ -435,7 +436,7 @@ export async function createApproval({
       return wireTransaction(message, sigs);
     });
     // What each transaction pays to whom, read back from the very instructions the wallet signs.
-    const n = namesOf(model(spec, { now: at }), { owner: wallet, treasury: p.ctx.treasury });
+    const n = namesOf(model(spec, { now: at }), { now: at, owner: wallet, treasury: p.ctx.treasury });
     // Every line names the project it goes to first: always the wallet's own, or the one it is the authority of.
     const details = batch.map(t => [
       `Project: ${p.ctx.project}${p.ctx.owner === wallet ? ' (your own)' : ` (owned by ${p.ctx.owner})`}`,

package/js/chain/token2022.js

@@ -60,8 +60,9 @@ export function hookProgramOf(mintData) {
 /**
  * Whether a mint's new accounts start frozen, or can be made to (as the program judges it): a Token-2022
  * mint carrying `DefaultAccountState` set to frozen, or set to anything while it has a freeze authority, which can switch
- * it to frozen whenever it likes. An auction, a contest, a lottery, an offer and a sealed schedule refuse such a mint:
- * each reads the setting once, as it opens, and a refund or payout opened into a frozen account would never land.
+ * it to frozen whenever it likes. The program takes such a mint everywhere: it is the project's choice. A refund or a
+ * payout opened into an account that starts frozen does not land until its issuer thaws it, so the tools warn the
+ * project, and a bidder or a borrower before they sign.
  */
 export function mayStartFrozen({ owner, data }) {
   if (

package/js/client/accounts.js

@@ -107,6 +107,9 @@ const RECORDS = [
         // The totals, split at each purchase: what each share paid in common takes, the entries that own a part of
         // their own, and the parts owed now.
         ['sold', 'u64'],
+        // In a weighted round (`time_weighted`), the weight sold: each purchase's tickets times the seconds from it
+        // to the close of sales. Null: each ticket weighs one, and the draw is over `sold`.
+        ['weight', { option: 'u128' }],
         ['to_pot', 'u64'],
         ['common', { vec: 'u64' }],
         ['owns', 'u32'],
@@ -117,7 +120,8 @@ const RECORDS = [
         ['first_asked_at', 'i64'],
         ['asked_at', 'i64'],
         ['answer', { array: ['u8', 32] }],
-        ['first', 'u64'],
+        // First place's point: below the draw's total (`roundTotal`), so in a weighted round a point of its weight.
+        ['first', 'u128'],
         ['pot_total', 'u64'],
         ['pot_sent', 'u64'],
         ['pot_arrived', 'u64'],
@@ -506,55 +510,94 @@ export const lotteryPots = lottery =>
 /** A share the buyer chooses (a referrer, a collectible's holder): paid out of the price as they buy, from their own account. */
 export const chosenAtPurchase = share => Boolean(share.to?.Chosen);
 
-/** The bytes of one entry of a round: buyer, word, what arrived (`fee`: a fee mint, or a chosen share), the NFT ticket. */
-export const entryWidth = (fee, nft) => 40 + (fee ? 8 : 0) + (nft ? 32 : 0);
+/** The bytes of one entry of a round: buyer, word, what arrived (`fee`: a fee mint, a chosen share, or a weighted
+ * round of paid tickets), where its weight ends (`weighted`: a round that weighs its tickets by time), the NFT ticket. */
+export const entryWidth = (fee, nft, weighted = false) => 40 + (fee ? 8 : 0) + (weighted ? 16 : 0) + (nft ? 32 : 0);
+
+/** What a round's draw picks a point below: the weight sold in a weighted round, the tickets sold otherwise. */
+export const roundTotal = r => (r.weight != null ? BigInt(r.weight) : BigInt(r.sold));
 
 /**
  * A lottery round (`["round", lottery, incarnation, round]`): its header (`status` 'Open' | 'Drawing' | 'Drawn' |
- * 'Cancelled', the terms it copied, `sold`, `owed`, the draw and the money the ask fixed, `nfts` the NFT of the
- * lottery's own stash each such place got), and `entries`, one a purchase: { buyer, start, end (its tickets), paid (its
- * own part's bit), amount (what reached the round), nft (its NFT ticket) }.
+ * 'Cancelled', the terms it copied, `sold`, `weight` (null in a round that doesn't weigh its tickets), `owed`, the draw
+ * and the money the ask fixed, `nfts` the NFT of the lottery's own stash each such place got), and `entries`, one a
+ * purchase: { buyer, start, end (its slice of the draw: its tickets, or in a weighted round its weight), tickets (how
+ * many it bought), paid (its own part's bit), amount (what reached the round), nft (its NFT ticket) }.
  */
 export function decodeRound(data) {
   const r = decode('LotteryRound', data);
   const at = Number(r.head);
   const width = Number(readUintLE(data, at, 2));
   const count = Number(readUintLE(data, at + 2, 4));
-  if (width !== entryWidth(r.fee, r.terms.nft_ticket != null) || data.length !== at + 6 + width * count)
+  const weighted = r.weight != null;
+  if (width !== entryWidth(r.fee, r.terms.nft_ticket != null, weighted) || data.length !== at + 6 + width * count)
     throw new Error('LotteryRound entries do not match its header');
   let start = 0n;
+  let sold = 0n;
   const entries = Array.from({ length: count }, (_, i) => {
     const e = data.subarray(at + 6 + width * i, at + 6 + width * (i + 1));
     const word = readUintLE(e, 32, 8);
-    const end = word & END_BITS;
+    // Its tickets end at the word's low 48 bits; its slice of the draw ends there too, or at its weight's end.
+    const last = word & END_BITS;
+    const tickets = last - sold;
     let k = 40;
     const take = n => e.subarray((k += n) - n, k);
-    const amount = r.fee ? readUintLE(take(8), 0, 8) : (end - start) * BigInt(r.terms.price);
+    const amount = r.fee ? readUintLE(take(8), 0, 8) : tickets * BigInt(r.terms.price);
+    const end = weighted ? readUintLE(take(16), 0, 16) : last;
     const entry = {
       buyer: encodeBase58(e.subarray(0, 32)),
       start,
       end,
+      tickets,
       paid: word & ~END_BITS,
       amount,
       nft: r.terms.nft_ticket ? encodeBase58(take(32)) : NO_ADDRESS,
     };
     start = end;
+    sold = last;
     return entry;
   });
   return { ...r, entries };
 }
 
+/** When a lottery's sales close (`terms`: a Lottery's or a round's): `closes_before` seconds before its draw. */
+export const salesCloseAt = terms => BigInt(terms.draws_at) - BigInt(terms.closes_before ?? 0);
+
+/**
+ * What a purchase of `count` tickets at `now` (Unix seconds, the chain's clock) weighs in a round's draw: one a ticket,
+ * or in a lottery that weighs tickets by time (`terms.time_weighted`) each ticket the seconds from the purchase to the
+ * close of sales (`salesCloseAt`). 0 once sales have closed: nothing more is sold. The same tickets bought later weigh less.
+ */
+export function ticketWeight(terms, count, now) {
+  const left = salesCloseAt(terms) - BigInt(now);
+  if (left <= 0n) return 0n;
+  return BigInt(count) * (terms.time_weighted ? left : 1n);
+}
+
+/**
+ * A buyer's chance before they buy: { weight, total, share } of a purchase of `count` tickets at `now` into `round` (its
+ * decoded record, null when nobody bought into it yet; `terms` the lottery's then): what it would weigh, the round's
+ * weight with it, and its share of that (a number from 0 to 1). Each place is drawn over the round's whole weight, so a
+ * share is the purchase's chance at one place as things stand: later purchases make it smaller.
+ */
+export function purchaseOdds(round, terms, count, now) {
+  const weight = ticketWeight(round?.terms ?? terms, count, now);
+  const total = (round ? roundTotal(round) : 0n) + weight;
+  return { weight, total, share: total > 0n ? Number((weight * 1_000_000n) / total) / 1_000_000 : 0 };
+}
+
 /** How many places a lottery's (or a round's) `places` are, every run counted (`Place.times`). */
 export const placeCount = places => places.reduce((n, p) => n + Number(p.times ?? 1), 0);
 
 /** The places of a round that have a winner: every place, but no more than tickets. */
 export const roundWinners = r => Math.min(placeCount(r.terms.places), Number(r.sold));
 
-/** The ticket that wins `place` of a drawn round: even steps around the list from first place's ticket. */
+/** The point that wins `place` of a drawn round: even steps of the draw's total around the list from first place's
+ * (a ticket's number, or in a weighted round a point of its weight). */
 export function ticketOfPlace(r, place) {
-  const sold = BigInt(r.sold);
-  const ahead = BigInt(place) * (sold / BigInt(roundWinners(r) || 1));
-  const toEnd = sold - BigInt(r.first);
+  const total = roundTotal(r);
+  const ahead = BigInt(place) * (total / BigInt(roundWinners(r) || 1));
+  const toEnd = total - BigInt(r.first);
   return ahead < toEnd ? BigInt(r.first) + ahead : ahead - toEnd;
 }
 
@@ -575,18 +618,18 @@ export function runPlaces(r, run) {
   return [Math.min(first, w), Math.min(first + Number(r.terms.places[run].times), w)];
 }
 
-/** The places of run `run` whose ticket is in `start..end` (an entry's), in order. */
+/** The places of run `run` whose point is in `start..end` (an entry's slice of the draw), in order. */
 export function placesIn(r, run, start, end) {
   const [from, to] = runPlaces(r, run);
   const out = [];
   if (from >= to || BigInt(start) >= BigInt(end)) return out;
-  const sold = BigInt(r.sold);
-  const step = sold / BigInt(roundWinners(r));
-  const d = (BigInt(start) + sold - BigInt(r.first)) % sold;
+  const total = roundTotal(r);
+  const step = total / BigInt(roundWinners(r));
+  const d = (BigInt(start) + total - BigInt(r.first)) % total;
   const len = BigInt(end) - BigInt(start);
   for (const [a, b] of [
-    [d, d + len < sold ? d + len : sold],
-    [0n, d + len > sold ? d + len - sold : 0n],
+    [d, d + len < total ? d + len : total],
+    [0n, d + len > total ? d + len - total : 0n],
   ]) {
     let p = Number((a + step - 1n) / step);
     for (p = Math.max(p, from); p < to && BigInt(p) * step < b; p++) out.push(p);
@@ -761,14 +804,13 @@ export const placeSet = place => Number(place.bps) > 0 || place.prize != null;
 /** The address of a lottery's current round's record (there or not). */
 export const roundAddress = (lotteryAddress, lottery) => pda.round(lotteryAddress, lottery.incarnation, lottery.round);
 
-/** Whether a lottery (decoded) drew once and has ended. */
-export const lotteryEnded = lottery => Number(lottery.every) === 0 && Number(lottery.round) > 0;
+/** Whether a lottery (decoded) drew its last round and has ended: it draws once (`every` 0) and is past round `last`. */
+export const lotteryEnded = lottery => Number(lottery.every) === 0 && Number(lottery.round) > Number(lottery.last ?? 0);
 
-/** The round a lottery's close, its write again and its own stash's moves name (`lottery::check_idle`): its current
- * round's, or once a lottery that draws once has ended, round 0's (which keeps its stash's NFTs until its places took
- * them out). */
+/** The round a lottery's close, its write again and its own stash's moves name (`Lottery::waits_on`): its current
+ * round's, or once it has ended, its last round's (which keeps its stash's NFTs until its places took them out). */
 export const idleRound = (lotteryAddress, lottery) =>
-  pda.round(lotteryAddress, lottery.incarnation, lotteryEnded(lottery) ? 0 : lottery.round);
+  pda.round(lotteryAddress, lottery.incarnation, lotteryEnded(lottery) ? lottery.last : lottery.round);
 
 /**
  * Who rents a listed NFT at `now` (Unix seconds), from its decoded Listing (or null for none): the renter's wallet while

package/js/client/grant.js

@@ -19,7 +19,7 @@ import { compareBytes, concat, fromHex, intLE, readUintLE, toBigInt, uintLE, utf
 import { meta } from '../chain/programs.js';
 import { sha256 } from '../chain/sha256.js';
 import { recordKey16 } from './accounts.js';
-import { ASSOCIATED_TOKEN_PROGRAM, gateAccounts, lootIx, prizeMetas, prizeNonce, tailOf } from './ix.js';
+import { ASSOCIATED_TOKEN_PROGRAM, gateAccounts, lootIx, prizeMetas, prizeNonce, shownFor, tailOf } from './ix.js';
 import { LOOT_PROGRAM, pda } from './pda.js';
 import IDL from './idl/loot.js';
 
@@ -400,7 +400,12 @@ export function claimGrantIx({
     },
     {
       remaining: [
-        ...gateAccounts(project, { gate: grant.gate, wallet, shown, listProof }),
+        ...gateAccounts(project, {
+          gate: grant.gate,
+          wallet,
+          shown: shownFor(project, grant.gate, wallet, shown),
+          listProof,
+        }),
         ...shards,
         ...prizes,
         ...tailOf(extra),