@xgamesfun/solana 0.25.0 → 0.25.2

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/client/index.d.ts

@@ -6,4 +6,5 @@ export * from './sizes.js';
 export * from './policy.js';
 export * from './compressed.js';
 export * from './traits.js';
+export * from './kit.js';
 export * as random from './random.js';

package/types/client/kit.d.ts

@@ -0,0 +1,49 @@
+/** @solana/kit's AccountRole: bit 1 is a signer, bit 0 is writable. */
+export declare const KIT_ACCOUNT_ROLE: Readonly<{
+    READONLY: 0;
+    WRITABLE: 1;
+    READONLY_SIGNER: 2;
+    WRITABLE_SIGNER: 3;
+}>;
+/**
+ * One instruction from a builder here, as @solana/kit takes it: `appendTransactionMessageInstruction(toKitInstruction(ix), m)`.
+ * @param {{ programId: string, keys: { pubkey: string, isSigner: boolean, isWritable: boolean }[], data: Uint8Array }} ix
+ * @returns {{ programAddress: string, accounts: { address: string, role: number }[], data: Uint8Array }}
+ */
+export declare function toKitInstruction(ix: {
+    programId: string;
+    keys: {
+        pubkey: string;
+        isSigner: boolean;
+        isWritable: boolean;
+    }[];
+    data: Uint8Array;
+}): {
+    programAddress: string;
+    accounts: {
+        address: string;
+        role: number;
+    }[];
+    data: Uint8Array;
+};
+/**
+ * A @solana/kit instruction in the shape this package's transactions take (js/chain/tx.js, js/play).
+ * @param {{ programAddress: string, accounts?: { address: string, role: number }[], data?: Uint8Array }} ix
+ * @returns {{ programId: string, keys: { pubkey: string, isSigner: boolean, isWritable: boolean }[], data: Uint8Array }}
+ */
+export declare function fromKitInstruction(ix: {
+    programAddress: string;
+    accounts?: {
+        address: string;
+        role: number;
+    }[];
+    data?: Uint8Array;
+}): {
+    programId: string;
+    keys: {
+        pubkey: string;
+        isSigner: boolean;
+        isWritable: boolean;
+    }[];
+    data: Uint8Array;
+};

package/types/economy/cost.d.mts

@@ -11,7 +11,7 @@ export declare function setupCost(plan: any, economy: any): {
     notes: string[];
 };
 /**
- * What each action costs whoever signs it while the economy runs: games.fun's fee, the network's, and for anything
+ * What each action costs whoever signs it while the economy runs: xgames.fun's fee, the network's, and for anything
  * that asks MagicBlock's oracle for a random number (a box's open, a lottery's draw, the authority's `roll`) the
  * oracle's own fee (`oracleSol`, model.mjs ORACLE_FEE).
  */

package/types/economy/explain.d.mts

@@ -1,3 +1,6 @@
+export declare const ruleWords: (r: any) => string;
+/** A gate in a sentence: "Only players who show …", "Only the wallets it names …", "Only wallets with … staked …". */
+export declare const gateWords: (gate: any, verb: any, m: any) => string;
 export declare function explainEconomy(economy: any, { now }?: {
     now?: number | undefined;
 }): {

package/types/economy/plan.d.mts

@@ -30,11 +30,11 @@ export declare function tableBatches(t: any): never[][];
 export declare function partPrize(o: any, m: any): "Raffled" | {
     Stash: any[];
 } | {
+    Item?: undefined;
     Compressed: {
         item: any;
         tree: string;
     };
-    Item?: undefined;
     Held?: undefined;
     Nft?: undefined;
     Roll?: undefined;
@@ -137,8 +137,8 @@ export declare function boxArgs(b: any, m: any): {
                 Item: any[];
                 Collection?: undefined;
             } | {
-                Collection: any[];
                 Item?: undefined;
+                Collection: any[];
             };
             key: any;
             test: any;
@@ -159,8 +159,8 @@ export declare function boxArgs(b: any, m: any): {
             Item: any[];
             Collection?: undefined;
         } | {
-            Collection: any[];
             Item?: undefined;
+            Collection: any[];
         };
         key: any;
         test: any;
@@ -341,11 +341,11 @@ export declare function scheduleArgs(s: any, m: any): {
  * of the pool), an item (a compressed NFT of it into the project's tree, "@tree"), one NFT of a stash, or a roll of a box.
  */
 export declare function prizeArgs(p: any, m: any): "Raffled" | {
+    Item?: undefined;
     Compressed: {
         item: any;
         tree: string;
     };
-    Item?: undefined;
     Held?: undefined;
     Nft?: undefined;
     Roll?: undefined;
@@ -464,8 +464,8 @@ export declare function lotteryArgs(l: any, m: any): {
                     Item: any[];
                     Collection?: undefined;
                 } | {
-                    Collection: any[];
                     Item?: undefined;
+                    Collection: any[];
                 };
                 key: any;
                 test: any;
@@ -512,8 +512,8 @@ export declare function lotteryArgs(l: any, m: any): {
                 Item: any[];
                 Collection?: undefined;
             } | {
-                Collection: any[];
                 Item?: undefined;
+                Collection: any[];
             };
             key: any;
             test: any;
@@ -587,8 +587,8 @@ export declare function contestArgs(c: any, m: any, at?: any): {
                 Item: any[];
                 Collection?: undefined;
             } | {
-                Collection: any[];
                 Item?: undefined;
+                Collection: any[];
             };
             key: any;
             test: any;
@@ -598,11 +598,11 @@ export declare function contestArgs(c: any, m: any, at?: any): {
     min_pot: bigint;
     stake: bigint;
     prize: string | {
+        Item?: undefined;
         Compressed: {
             item: any;
             tree: string;
         };
-        Item?: undefined;
         Held?: undefined;
         Nft?: undefined;
         Roll?: undefined;
@@ -661,8 +661,8 @@ export declare function contestArgs(c: any, m: any, at?: any): {
             Item: any[];
             Collection?: undefined;
         } | {
-            Collection: any[];
             Item?: undefined;
+            Collection: any[];
         };
         key: any;
         test: any;
@@ -679,8 +679,8 @@ export declare function farmArgs(f: any, m: any): {
             Item: any[];
             Collection?: undefined;
         } | {
-            Collection: any[];
             Item?: undefined;
+            Collection: any[];
         };
         key: any;
         test: any;
@@ -759,8 +759,8 @@ export declare function auctionArgs(a: any, m: any): {
                 Item: any[];
                 Collection?: undefined;
             } | {
-                Collection: any[];
                 Item?: undefined;
+                Collection: any[];
             };
             key: any;
             test: any;
@@ -771,8 +771,8 @@ export declare function auctionArgs(a: any, m: any): {
             Item: any[];
             Collection?: undefined;
         } | {
-            Collection: any[];
             Item?: undefined;
+            Collection: any[];
         };
         key: any;
         test: any;
@@ -780,11 +780,11 @@ export declare function auctionArgs(a: any, m: any): {
 };
 export declare function grantArgs(g: any, m: any): {
     gives: string | {
+        Item?: undefined;
         Compressed: {
             item: any;
             tree: string;
         };
-        Item?: undefined;
         Held?: undefined;
         Nft?: undefined;
         Roll?: undefined;
@@ -890,8 +890,8 @@ export declare function grantArgs(g: any, m: any): {
                 Item: any[];
                 Collection?: undefined;
             } | {
-                Collection: any[];
                 Item?: undefined;
+                Collection: any[];
             };
             key: any;
             test: any;

package/types/economy/review.d.mts

@@ -0,0 +1,45 @@
+import { TRUST_LEVELS, TRUST_WORDS } from './trust.mjs';
+/** Severities, most serious first. */
+export declare const SEVERITIES: readonly string[];
+export { TRUST_LEVELS, TRUST_WORDS };
+/**
+ * The review of an economy: { ok, routes, findings, tradeoffs }. `ok` is false when there is a high finding, or when
+ * the spec does not check (then `refusals` says why, and the rest is empty).
+ */
+export declare function review(economy: any, { now }?: {
+    now?: number | undefined;
+}): {
+    ok: boolean;
+    refusals: any[];
+    routes: never[];
+    findings: never[];
+    tradeoffs: string;
+} | {
+    refusals?: undefined;
+    ok: boolean;
+    routes: ({
+        kind: string;
+        key: any;
+        name: any;
+        trigger: string;
+        enforced: any[];
+        trusts: any[];
+        trust: any;
+        ceiling: string;
+        feeds: any[];
+    } | {
+        kind: string;
+        key: any;
+        name: any;
+        trigger: string;
+        enforced: any[];
+        trusts: any;
+        trust: null;
+        ceiling: string;
+        feeds: any[];
+    })[];
+    findings: any[];
+    tradeoffs: string;
+};
+/** A review in words, for the terminal and the tool's text. */
+export declare function describeReview(r: any, name?: string): string;

package/types/economy/trust.d.mts

@@ -0,0 +1,8 @@
+/** The trust levels a voucher grant declares, strongest first. */
+export declare const TRUST_LEVELS: readonly string[];
+/** Each trust level in words: what the server does, and what a cheater still gets. */
+export declare const TRUST_WORDS: Readonly<{
+    decides: "the server decides the result itself (it runs the game or the match; the page sends only inputs): nothing the page says can forge one, though a bot that plays well still earns what a good player does";
+    replays: "the server runs the page’s inputs again and reads the result itself: a forged result fails, though a bot that plays well still earns, and one that knows the run’s randomness up front can search for the best run offline";
+    bounds: "the page runs the game and reports the result, and the server checks only its pace, order and daily caps: a script that waits as long as a person would gets every reward, up to the limits";
+}>;

package/types/index.d.ts

@@ -3,6 +3,7 @@ export { simulate, explain } from './economy/simulate.mjs';
 export { plan, setupSteps, playSteps } from './economy/plan.mjs';
 export { cost, explainCost } from './economy/cost.mjs';
 export { explainEconomy } from './economy/explain.mjs';
+export { review, describeReview, SEVERITIES, TRUST_LEVELS, TRUST_WORDS } from './economy/review.mjs';
 export { model } from './economy/model.mjs';
 export { prepare, recordLanded, changedParts } from './economy/live.mjs';
 export { guideText, catalog, CANNOT } from './economy/guide.mjs';

package/types/mcp/http.d.mts

@@ -0,0 +1,30 @@
+/** The largest request body read: a spec is a few kilobytes; a megabyte is far more than any. */
+export declare const MAX_BODY_BYTES = 1000000;
+/**
+ * One HTTP request to the MCP endpoint, answered. `allowOrigin(origin)` decides which browser origins may call it (a
+ * request with no Origin header, from a server or a desktop app, always may); by default every origin, since the
+ * endpoint holds no session, no cookie and nothing private.
+ * @param {Request} request
+ * @param {{ allowOrigin?: (origin: string) => boolean, maxBodyBytes?: number, ctx?: object }} [options]
+ * @returns {Promise<Response>}
+ */
+export declare function mcpHttp(request: Request, { allowOrigin, maxBodyBytes, ctx }?: {
+    allowOrigin?: (origin: string) => boolean;
+    maxBodyBytes?: number;
+    ctx?: object;
+}): Promise<Response>;
+/**
+ * Serves mcpHttp at `path` on this machine (`xsolana mcp --http`). It listens on 127.0.0.1 unless told otherwise, and
+ * then answers only pages on localhost: a site in the browser can't reach it by renaming its host (DNS rebinding).
+ * @returns {Promise<{ address(): { port: number } | string | null, close(done?: () => void): unknown }>} the node:http server
+ */
+export declare function serveHttp({ port, host, path }?: {
+    host?: string | undefined;
+    path?: string | undefined;
+    port?: number | undefined;
+}): Promise<{
+    address(): {
+        port: number;
+    } | string | null;
+    close(done?: () => void): unknown;
+}>;