@xgamesfun/solana 0.24.0 → 0.25.1

package/skills/xsolana-economy/references/telling-the-person.md

@@ -7,7 +7,8 @@ and the spec differ (a limit, an amount, a key not set yet), change one of them
 1. **What each play costs and is worth.** Lead with the tools' "in all" number: "A cast costs about 0.0234 SOL in
    all (0.02 SOL, the 0.002 SOL player fee, the oracle and the network, and the Perch's rent when one is caught), and
    gives back 0.01 SOL in prizes on average (50%), plus a Perch 3 casts in 10." For a box of items, the odds; for a
-   lottery, what the pot reaches and what each place wins; for a farm, a day of rewards per unit staked and what the
+   lottery, where its places are paid from (its pot, which gifts and what earlier rounds left fill, or each round's own
+   ticket money, which nothing from outside can change), what that reaches and what each place wins; for a farm, a day of rewards per unit staked and what the
    lock tiers multiply.
 2. **Where the money goes.** "55% of each cast goes into the pond that pays the Golden Carp, 5% into the monthly
    draw's pot, and the other 40% to your treasury."
@@ -22,13 +23,14 @@ and the spec differ (a limit, an amount, a key not set yet), change one of them
    and how often, and what happens if nobody does. If a payout rewards a result the game reports (a clear, a win,
    a score): "Checking that a player really did it is up to you, on your own server: a game runs in the player's
    browser, and the program trusts the authority's signature."
-6. **Flags for the law.** `W-CHANCE-PRIZE`: "Players pay for a chance at money. That is gambling in many places once
+6. **Flags for the law, once.** `W-CHANCE-PRIZE`: "Players pay for a chance at money. That is gambling in many places once
    it is real money; this runs on devnet only." `W-CHANCE-ITEMS`: "Players pay for random items they can resell: some
    places treat that as gambling, and many require the odds to be shown." `W-REVENUE-SHARE`: "Stakers are paid from
-   what players spend; regulators look at that when they decide whether a token is a security." Say them every time
-   they are raised. Before they go live, every time: "The program isn't independently audited and comes as is, with
-   no warranty: you use it at your own risk, and making sure this is legal where you offer it is up to you." The
-   approval page shows all of this too, and keeps Approve off until the owner ticks that they read it.
+   what players spend; regulators look at that when they decide whether a token is a security." Say each once, the
+   first time the checker raises it; then leave them, saying them again only when the person asks or a flag of a new
+   kind appears, and keep them out of pages and apps unless asked. The approval page shows them, with the program's
+   status (not independently audited, as is, at their own risk, theirs to make legal where they offer it), and keeps
+   Approve off until the owner ticks that they read it.
 7. **For an auction**, say how it ends, in their words: "The highest bid when the 48 hours are up wins. Each bid must
    be at least 0.5 SOL and 5% over the last; a bid in the last 10 minutes gives everyone 10 more. Whoever is outbid
    has their SOL back at once, in the same transaction. With no bid, the lot goes back (an item's unit is never
@@ -38,6 +40,12 @@ and the spec differ (a limit, an amount, a key not set yet), change one of them
    For a collectible they already hold: "It stays with the project until someone wins it or the auction ends."
 8. **Anything else the checker warned about**, in a sentence each (a mint that can freeze accounts, a free box bots
    can drain, a grant with no limits or no funds).
+9. **What a cheater gets**, from `xsolana_review`, before the owner approves: for each route paid on a server's
+   voucher, which level it uses (the server decides, replays or only bounds the result), what one cheater gets there
+   (its ceiling, and what the prize goes on to earn), and what the stronger level would cost to build: "A script that
+   waits as long as a player would gets each reward NFT once per wallet, and each then earns tokens every day with no
+   end; having the server replay each run would stop forged runs, and needs the game to be deterministic." Then each
+   high finding and its fix. The person chooses the trade-off (`trust-and-cheating.md`).
 
 ## What stays the project's job
 
@@ -78,6 +86,7 @@ money; it holds no files and serves nothing.
   `xsolana_check` counts them.
 
 Don'ts:
+
 - Don't show mints, account addresses, PDAs, lamports or instruction names unless asked.
 - Don't promise returns, profits or "passive income". Say what the program does, with the numbers.
 - Don't hide a gap: if loot can't do what they asked, the first line says so and offers the nearest thing.

package/skills/xsolana-economy/references/trust-and-cheating.md

@@ -0,0 +1,126 @@
+# Trust and cheating
+
+The program enforces its own rules: a cheater can't take more than a route's limits, move a voucher to another
+wallet, harvest someone else's seat or mint into the project's collection. What a cheater can still take is what the
+economy's design and its servers leave open: a result the server never really checked, a person counted as many
+wallets, a reward that keeps earning for good. This page is how to read an economy for that, and how to tell the
+person what they are choosing. `xsolana_review` does the reading for a spec; this page says why.
+
+## How far a result can be trusted
+
+A result is worth paying only as far as the server that signs the voucher can tell it happened. Strongest first:
+
+- **The server decides it.** A turn game played on the server, or a room whose server runs the match: the page sends
+  inputs, never results. The result is what the server saw.
+- **The server replays it.** A deterministic game (a fixed time step, seeded randomness): the page sends its inputs,
+  and the server runs them again and reads the result itself. Mind CPU limits: replay short runs, or a long one in
+  pieces as it is played. Never hand the page the whole run's randomness up front: with the seed and the rules, a
+  script searches for the best run offline and sends only that. Reveal randomness as the run goes, or keep the seed on
+  the server; one open run per player, and count abandoned runs toward the day's.
+- **The server bounds it.** Any game the browser simulates: the server starts each run (an id and its own clock),
+  takes each checkpoint in order, refuses what is faster than the game allows, caps what one player earns a day, and
+  can ban. A script that plays at human speed still gets through: this limits what a cheater earns, it does not stop
+  one.
+
+| Level   | What it costs to build                                                                | CPU and latency                                           | What a cheater gets                                                          | Fits                                                                                  |
+| ------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| decides | the most: the game's rules run on the server (or in a room that runs the match)       | every move waits on the server                            | what a bot that plays well earns; nothing forged                             | turn games, card and board games, matches in a room, anything with hidden information |
+| replays | a deterministic game (fixed step, seeded randomness the server keeps) and a replayer  | a replay per run, after the fact; short runs or in pieces | what a bot that plays well earns; with the seed up front, the best run found | puzzles, runners, arcade games with short runs                                        |
+| bounds  | the least: a run id, the server's clock, checkpoints in order, daily caps, a ban list | almost none                                               | every reward a script claims at human speed, up to the limits                | anything the browser simulates; prizes that are cosmetic, small or capped             |
+
+Even a result the server decided is worth what a good bot can earn. Pay a bounded or replayed result only what you would
+accept losing to a patient script (small amounts, capped a day), and keep entry fees and prize pools for results the
+server decided and for chance (the oracle). Tell players which one your game is.
+
+**Say it in the spec.** Every grant paid on vouchers says what its server checks: `"trust": "decides"`, `"replays"` or
+`"bounds"`. It is the spec's own note (it never goes on chain, and changing it publishes nothing), and it must be
+honest: a server that takes the page's word within a pace is `bounds`, whatever else it does. `xsolana_review` reads a
+voucher grant that says nothing as `bounds`, the weakest.
+
+## Who gets paid: wallets are not people
+
+- **A wallet is free.** Any limit per wallet (`perWallet`, a gate's one claim per collectible shown) limits wallets,
+  never a person. What bounds a reward is its totals: `perDay` and `total` are the most it can ever pay, whatever
+  happens to a key or how many wallets come.
+- **Count people through vouchers.** `perPerson` counts the person the voucher names (a person hash), which only the
+  server chooses: the player can't pick or change it, and an open grant has none. So it is exactly as good as the
+  server's choice: a real outside identity (an X account) counts people; a wallet, or a voucher with no person, counts
+  nobody. For rewards worth farming, pay only players signed in with X.
+- **Make farming cost something.** Gate on holding a collectible the game sells or a locked stake (`gate`), pay only
+  wallets a player proved (`proofRequest` / `verifyProof`), and keep prizes for results small.
+- **Bots play well.** Even a verified result pays a bot what it pays a good player.
+
+## What the program guarantees
+
+These were attacked on devnet and refused by the program; there is nothing to build for them:
+
+- **A voucher is bound to its claim.** It signs the program, the grant, the grant's incarnation, the wallet, the person,
+  an expiry and its rounds. It can't be moved to another wallet, or replayed on another grant or a re-made one. A key
+  not among the grant's voucher keys is refused, and so is a claim with no voucher on a grant that isn't open.
+- **The winning wallet signs its own claim.** Anyone may pay its fees; nobody claims for it.
+- **A round pays a wallet once** per grant incarnation, whoever signs it again and whenever; `perWallet`,
+  `perPerson`, `perKey`, `perDay` and `total` are kept by the program.
+- **A farm's gate can't be forged.** It checks the project's collection and the item number the program writes at mint
+  and never lets change: an NFT of another collection, one in no collection, an attribute written by hand, or a mint
+  into the project's collection by anyone but the project are refused. Boosts read the staked NFT's own item number.
+- **One seat per NFT, ever.** In escrow, an NFT can't leave before its lock or be staked twice. Watched, an NFT sold
+  while staked earns its old staker nothing more, and its new holder takes the seat over. Nobody harvests or unstakes
+  someone else's seat.
+- **The project's keys.** A token the project mints has the project as its only minter and no freeze authority. Only
+  the authority mints or moves pool funds; only the owner changes mechanics or closes records. Money held for a
+  record (a farm's stakes and rewards, a pot, an order, a bid) leaves only by that record's rules.
+- **Chance is the oracle's.** Nobody, the project included, steers a roll or a draw.
+
+## What is still yours to get right: the checklist
+
+Run `xsolana_review` and go through what it reports; these are the points behind its findings.
+
+1. **The signer decides who is paid.** The program checks a voucher's signature, wallet and limits, never what
+   happened in the game. Declare `trust` honestly on every voucher grant, and make the server's checks match it.
+2. **Person counting.** `perPerson` holds only when the server names a real person (an X account) in every voucher,
+   never a wallet. Without it, each free wallet claims again: set `perDay` and `total` as if every claim were a new
+   wallet.
+3. **Sybil wallets.** Open grants (no voucher, code or list) pay any wallet that asks: gate them on something a sybil
+   must pay for, keep their prizes small or soulbound, and set `perDay`.
+4. **Voucher key custody.** The key's secret lives only on the server: never in a page, a repository, a spec or a
+   chat. Anyone holding it pays anyone, up to the grant's limits, which is why `perDay` and `total` matter. To rotate
+   it, put the new public key in the grant's `vouchers` and publish. Use a different key on each cluster: a voucher's
+   bytes don't name the cluster.
+5. **Re-made grants pay again.** Closing and making a grant again starts a new incarnation: a new campaign whose
+   limits start from zero, and whose list pays every listed round again. Give a re-made grant fresh rounds.
+6. **Emission without an end.** A farm whose rate is minted, with no `runs`, no term on every tier (`earnsFor`), no
+   upkeep and no halving, mints for as long as anything is staked. Every way to get what it takes is then worth that
+   stream: a cheatable claim of a staked NFT compounds into tokens for good. Give it an end, or pay its rate from its
+   vault.
+7. **Prizes worth farming.** A tradeable prize (tokens, an NFT that can be sold, a roll) on a route a script can reach
+   is what a cheater farms. Keep such prizes for results the server decides, or small and capped.
+8. **Entry fees and prize pools.** Players' money (a payment, a box's or a lottery's share into a pool) paid out on a
+   bounded or replayed result goes to whoever scripts it. Keep those for decided results and chance.
+9. **NFT farm custody.** Escrow moves the NFT to the project while staked; freeze locks it in the wallet; watch leaves
+   it free, so it can be sold while staked and its buyer takes the seat. The issuer's own controls still apply to
+   NFTs of other collections.
+10. **The gate.** A farm or a route gated on the project's items (`items`, `item_id`, `rarity`) is as strong as the
+    ways those items are had. A gate on another collection's attributes trusts whoever can write them.
+11. **The authority and the treasury.** The owner's wallet alone changes every price, rate, grant, limit and voucher
+    key; the authority mints, moves pool funds, decides contests and releases holds, with no caps. Keep them in a
+    hardware wallet or a multisig; a server that signs gets an authority key of its own, never the owner's.
+12. **The page is untrusted.** A page builds the player's transactions, and a cheater builds their own: the program's
+    checks are what count, never the page's. Anything the page decides (a score, a reward amount, who won) is only as
+    good as the server that checks it.
+13. **Ordering.** A lottery's tickets are not weighted by time: one buyer can take most of a round right before the
+    draw. Anyone, the seller included, can bid an auction up. A box that keeps selling when an outcome runs out
+    (`drawLeft`) lets someone watching the stock empty a common outcome to make a rare likelier.
+14. **Contests.** Players' stakes go to the side the authority or a decider key names: keep contests for results the
+    server decides, or that anyone can check outside the game.
+
+## Telling the person
+
+After `xsolana_review`, before the owner approves, say in plain words:
+
+- for each signed route, which level its server uses and what a cheater gets ("A script that waits long enough gets
+  a Legendary per wallet, up to 100 a day, and each earns 50 tokens a day for good");
+- what the next level would cost to build ("replaying runs needs the game to be deterministic and a server that re-runs
+  each run");
+- every high finding, and its fix, or that they accept it.
+
+They choose the trade-off, not you.

package/types/chain/core.d.ts

@@ -6,7 +6,7 @@ export { MPL_CORE_PROGRAM };
  * it also carries Bubblegum's plugin, so compressed NFTs can be minted into it. The collection address signs too (a
  * fresh key).
  */
-export declare function createCollectionInstruction({ collection, creator, name, uri, royaltyBps, project, compressed }: {
+export declare function createCollectionInstruction({ collection, creator, name, uri, royaltyBps, project, compressed, }: {
     collection: any;
     compressed?: boolean | undefined;
     creator: any;

package/types/chain/lookup.d.ts

@@ -176,7 +176,7 @@ declare const pause: (ms: any) => Promise<any>;
  * plain sentence when it can't be sent. Returns { signature (the last transaction's), table (its address, or null),
  * steps (the signatures of the transactions before it) }.
  */
-export declare function sendFitting({ rpc, payer, instructions, sign, table, alone, first, standing, sleep }: {
+export declare function sendFitting({ rpc, payer, instructions, sign, table, alone, first, standing, sleep, }: {
     alone?: (() => boolean) | undefined;
     first?: never[] | undefined;
     instructions: any;

package/types/client/accounts.d.ts

@@ -86,6 +86,17 @@ export declare const ENDED = 2;
 /** How many losers' NFTs a winner of a contest of NFTs takes: the share fixed at the decision, one more for an early
  * place on its side. */
 export declare const shareOf: (contest: any, entry: any) => number;
+/**
+ * What a winning entry that put in `amount` takes with its first claim of a decided contest of tokens: its part of what
+ * the decision wrote (`pot_won`, the pot once the shares were taken; `prize_won`, a split prize's vault), by what it put
+ * in against its side's total. The winners claimed before it took `won × claimed ÷ total`, so the parts add up exactly
+ * whatever the order: `{ pot, prize }` (the prize part is 0 when the claim forgoes it). Tokens sent to the pot after the
+ * decision are nobody's.
+ */
+export declare function contestWinnings(contest: any, amount: any): {
+    pot: bigint;
+    prize: bigint;
+};
 /** What a count allows `n` more of at `now` under `limit` ({ total, per_window, window }, 0 is no limit; a lottery's
  * window is its round plus one, given as `window`). */
 export declare function countAllows(count: any, limit: any, now: any, n?: number, window?: number): boolean;
@@ -179,10 +190,20 @@ export declare function decodeTokenMetadata(data: any): {
     ruleSet: string | null;
 } | null;
 export declare const OWN_PAID: bigint;
-/** The mint a lottery's tickets are paid in (`terms`: a Lottery's or a round's): its ticket mint, burned, or its pot's. */
+/** The mint a lottery's tickets are paid in (`terms`: a Lottery's or a round's): its ticket mint, burned, or `mint`. */
 export declare const paymentMint: (terms: any) => any;
 /** Whether a lottery's tickets are burned: they are paid in a ticket mint of its own. */
 export declare const ticketsBurn: (terms: any) => boolean;
+/** The most pots one lottery keeps (`MAX_POTS`): a pot's id is below it. */
+export declare const MAX_POTS: number;
+/** The pot a lottery's places are paid from (`terms.pays_from`: `{ Pot: [id] }`), or null when each round pays from its
+ * own ticket money (`{ Round: { rest } }`). */
+export declare const potIdOf: (terms: any) => number | null;
+/** Where what a round's places leave goes (`Part::Common` past the shares): its pot, or the `rest` a round paid from
+ * its own money names (`lotteryAddress`: the lottery's). */
+export declare const leftoverTo: (lotteryAddress: any, terms: any) => any;
+/** The ids of the pots a lottery opened (`Lottery::pots`, one bit an id), lowest first: a close empties each. */
+export declare const lotteryPots: (lottery: any) => number[];
 /** A share the buyer chooses (a referrer, a collectible's holder): paid out of the price as they buy, from their own account. */
 export declare const chosenAtPurchase: (share: any) => boolean;
 /** The bytes of one entry of a round: buyer, word, what arrived (`fee`: a fee mint, or a chosen share), the NFT ticket. */
@@ -250,7 +271,7 @@ export declare function partsOwed(r: any, i: any, { places }?: {
 })[];
 /**
  * The parts of a round owed in common, of no entry (`{ Common: [i] }`): each share paid in common once drawn (one that
- * burns is burned at the close), then what the round owes the lottery's pot (`i` = the shares' count), then after a
+ * burns is burned at the close), then what its places leave, owed to its pot or to `rest` (`i` = the shares' count), then after a
  * cancel each pool's token prize back to its pool (past it).
  */
 export declare function commonOwed(r: any): {
@@ -260,7 +281,7 @@ export declare function commonOwed(r: any): {
 export declare const entryOf: (r: any, ticket: any) => any;
 /** Whether a round is done and owes nothing: the next pull closes it, given its close's accounts. */
 export declare const roundFinished: (r: any) => boolean;
-/** Whether a lottery's place wins something: a share of the pot, a prize, or both. */
+/** Whether a lottery's place wins something: a part of what the round pays from, a prize, or both. */
 export declare const placeSet: (place: any) => boolean;
 /** The address of a lottery's current round's record (there or not). */
 export declare const roundAddress: (lotteryAddress: any, lottery: any) => any;

package/types/client/grant.d.ts

@@ -12,7 +12,7 @@ export declare const dayOf: (unixSeconds: any) => number;
 /** An i64 little-endian (two's complement), as the program reads `expires`. */
 export declare const i64LE: (value: any) => Uint8Array<any>;
 /** A voucher's body, which its key signs the sha256 of (`voucherBytes`). */
-export declare function voucherBody({ program, grant, incarnation, wallet, personHash, expires, rounds, round, amount }: {
+export declare function voucherBody({ program, grant, incarnation, wallet, personHash, expires, rounds, round, amount, }: {
     amount?: bigint | undefined;
     expires: any;
     grant: any;
@@ -123,7 +123,7 @@ export declare function shardBitsFor(wallets: any, rounds?: number): number;
  * order only (`askRollIx` then asks for it, in the same transaction when it fits). Send it with a compute limit of
  * `CLAIM_COMPUTE_UNITS`.
  */
-export declare function claimGrantIx({ project, id, grant, wallet, signer, count, rounds, round, expires, personHash, amount, proofs, proof, paidRounds, poolMint, item, nft, shown, listProof, programs, voucherKey, nonce, extra }: {
+export declare function claimGrantIx({ project, id, grant, wallet, signer, count, rounds, round, expires, personHash, amount, proofs, proof, paidRounds, poolMint, item, nft, shown, listProof, programs, voucherKey, nonce, extra, }: {
     amount?: bigint | undefined;
     count?: number | undefined;
     expires: any;

package/types/client/idl/loot.d.ts

@@ -4460,6 +4460,28 @@ declare const _default: {
             })[];
             variants?: undefined;
         };
+    } | {
+        name: string;
+        docs: string[];
+        type: {
+            fields?: undefined;
+            kind: string;
+            variants: ({
+                fields?: undefined;
+                name: string;
+            } | {
+                name: string;
+                fields: string[];
+            } | {
+                name: string;
+                fields: {
+                    name: string;
+                    type: {
+                        vec: string;
+                    };
+                }[];
+            })[];
+        };
     } | {
         name: string;
         docs: string[];