@xgamesfun/solana 0.25.0 → 0.25.2

package/types/mcp/server.d.mts

@@ -0,0 +1,321 @@
+export declare const INSTRUCTIONS: string;
+/**
+ * What a hosted server (js/mcp/http.mjs) tells the agent: the same work, with the spec passed whole in every call,
+ * and going live on the person's own computer, since a hosted server can neither write their files nor open a page there.
+ */
+export declare const REMOTE_INSTRUCTIONS: string;
+/**
+ * The protocol versions this server speaks, newest first. A client that asks for one of them gets it; any other ask
+ * gets the newest, and the client decides whether it can go on (the spec's version negotiation).
+ */
+export declare const PROTOCOLS: string[];
+/** Every way `input` does not fit a tool's input schema, in words; [] when it fits. */
+export declare function inputProblems(schema: any, input: any): any;
+/** Runs one tool by name: the same checks and answer on the server and in the terminal. */
+export declare function runTool(name: any, input?: {}, ctx?: {}): Promise<{
+    ok: boolean;
+    from: any;
+    refusals: any;
+    warnings: any;
+    text: string;
+} | {
+    name: any;
+    spec: any;
+    checks: string | any[];
+    text: string;
+    examples?: undefined;
+    ideas?: undefined;
+    hows?: undefined;
+    limits?: undefined;
+} | {
+    name?: undefined;
+    checks?: undefined;
+    examples: any;
+    ideas: {
+        count: any;
+    };
+    text: string;
+    hows?: undefined;
+    limits?: undefined;
+    spec?: undefined;
+} | {
+    name?: undefined;
+    checks?: undefined;
+    examples: any;
+    ideas: any;
+    hows: any;
+    limits: any;
+    text: string;
+    spec?: undefined;
+} | {
+    ok: boolean;
+    from: any;
+    summary: {
+        boxes: {
+            key: any;
+            returnPercent: any;
+            houseEdgePercent: any;
+        }[];
+        pools: {
+            key: any;
+            lasts: any;
+            lastsDays: any;
+            settlesAt: any;
+        }[];
+        farms: any;
+        platformSolPerDay: any;
+    };
+    simulation?: {
+        scenario: {
+            days: any;
+            perDay: any;
+            defaultPerDay: number;
+            defaultBidsPerDay: number;
+            defaultClaimsPerDay: number;
+        };
+        boxes: {
+            key: any;
+            name: any;
+            price: number;
+            averagePrice?: any;
+            token: any;
+            opensPerDay: number;
+            outcomes: any;
+            expectedBack: any;
+            returnPercent: any;
+            houseEdgePercent: any;
+            alsoPays: {};
+            unpriced: any[];
+            playerFee: number;
+            oracleFee: number;
+            realCost: {
+                price: any;
+                token: any;
+                atLeast?: boolean | undefined;
+                priceBack?: boolean | undefined;
+                playerFeeSol: number;
+                oracleSol: number;
+                networkSol: any;
+                rentSol: any;
+                rentIs?: string | undefined;
+                heldSol?: any;
+                heldIs?: string | undefined;
+                extrasSol: any;
+                totalSol?: any;
+                holdSol: any;
+            };
+            limitedStock?: boolean | undefined;
+            whenOut?: string | undefined;
+            stock?: {
+                whenOut: string;
+                stopsSellingInDays: any;
+                by: any;
+            } | {
+                by?: undefined;
+                whenOut: string;
+                runsOut: {
+                    inDays: any;
+                    outcomes: any;
+                    chancesAfter: any;
+                }[];
+                stopsSellingInDays?: any;
+            } | undefined;
+            returnOfRealCostPercent?: any;
+        }[];
+        items: any;
+        payments: any;
+        recipes: any;
+        schedules: any;
+        lotteries: any;
+        farms: any;
+        grants: any;
+        contests: any;
+        auctions: any;
+        stashes: any;
+        pools: {
+            key: any;
+            pot?: any;
+            farm?: any;
+            token: any;
+            seed: any;
+            inPerDay: any;
+            outPerDay: any;
+            ins: any;
+            outs: any[];
+        }[];
+        perDay: {
+            players: {
+                pay: {
+                    [k: string]: any;
+                };
+                getBack: {
+                    [k: string]: any;
+                };
+                playerFeesSol: any;
+                oracleFeesSol: any;
+                networkFeesSol: any;
+                rentSol: any;
+            };
+            creator: {
+                treasury: {
+                    [k: string]: any;
+                };
+                projectFeesSol: any;
+                oracleFeesSol: any;
+                networkFeesSol: any;
+                grantRentSol: any;
+            };
+            oracle: {
+                totalSol: any;
+            };
+            platform: {
+                playerFeesSol: any;
+                projectFeesSol: any;
+                totalSol: any;
+            };
+            burned: {
+                [k: string]: any;
+            };
+            accounts: {
+                [k: string]: any;
+            };
+        };
+        fees: {
+            playerSol: number;
+            projectSol: number;
+            oracleSol: number;
+            networkPerSignatureSol: number;
+            settleRentUnitSol: number;
+            ticketLineRentSol: any;
+            collectibleRentSol: number;
+            burnRefundSol: number;
+        };
+        notes: string[];
+    } | undefined;
+    text: string;
+} | {
+    ok: boolean;
+    from: any;
+    setup: any;
+    actions: any;
+    fees: any;
+    text: string;
+} | {
+    refusals?: undefined;
+    ok: boolean;
+    warnings: any[];
+    needsAuthority: boolean;
+    chance: boolean;
+    setupSol: any;
+    from: any;
+    text: string;
+} | {
+    ok: boolean;
+    from: any;
+    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;
+    text: string;
+} | {
+    file?: undefined;
+    ok: boolean;
+    isError: boolean;
+    text: string;
+    warnings?: undefined;
+} | {
+    isError?: undefined;
+    ok: boolean;
+    file: any;
+    warnings: any[];
+    text: string;
+} | {
+    ok: boolean;
+    transactions: number;
+    approvals: number;
+    steps: never[];
+    text: string;
+    command?: undefined;
+    setupSol?: undefined;
+} | {
+    ok: boolean;
+    command: string;
+    transactions: number;
+    approvals: number | undefined;
+    setupSol: any;
+    steps: any[];
+    text: string;
+} | {
+    ok: boolean;
+    text: string;
+    rows?: undefined;
+} | {
+    ok: boolean;
+    rows: ({
+        part: any;
+        address: any;
+        found: boolean;
+        kind: string;
+        sol: number;
+    } | {
+        sol?: undefined;
+        part: any;
+        address: any;
+        found: boolean;
+        amount?: number | undefined;
+        nfts?: any;
+        kind?: string | undefined;
+    })[];
+    text: string;
+} | {
+    program: string;
+    cluster: "devnet";
+    version: string;
+    idl: "@xgamesfun/solana/idl.json";
+    package: `@xgamesfun/solana@${any}`;
+    text: string;
+} | {
+    isError: boolean;
+    text: any;
+}>;
+/** The answer to one JSON-RPC request, or null for a notification. */
+export declare function handle(message: any, ctx?: {}): Promise<{
+    jsonrpc: string;
+    id: any;
+    result: any;
+} | {
+    jsonrpc: string;
+    id: any;
+    error: {
+        code: any;
+        message: any;
+    };
+} | null>;
+/**
+ * Serves the tools over stdio until stdin closes. Once it closes, every request already read is answered before
+ * `exit` runs, so a client that sends its last request and closes still gets the reply.
+ */
+export declare function serveStdio({ input, output, exit, }?: {
+    exit?: (() => any) | undefined;
+    input?: any;
+    output?: any;
+}): Promise<void>;

package/types/mcp/tools.d.mts

@@ -25,6 +25,11 @@ export declare const PROGRAM_INFO: Readonly<{
     package: `@xgamesfun/solana@${any}`;
 }>;
 export declare const DEFAULT_FILE = "xsolana.json";
+/**
+ * The tools a hosted server (js/mcp/http.mjs) offers: those that read nothing but their arguments and the chain.
+ * xsolana_save and xsolana_publish write and read the person's own files, so they run only on the person's machine.
+ */
+export declare const REMOTE_TOOLS: Set<string>;
 /**
  * The spec file `rel` names, inside the project folder: a `.json` file there or in a folder below it. Anything else (an
  * absolute path elsewhere, `..`, a link out of the folder, another kind of file) is refused.
@@ -451,6 +456,68 @@ export declare const tools: ({
         from: any;
         text: string;
     }>;
+} | {
+    name: string;
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            spec: {
+                type: string;
+                description: string;
+            };
+            file: {
+                type: string;
+                description: string;
+            };
+            example: {
+                type: string;
+                description: string;
+            };
+        };
+        additionalProperties: boolean;
+        required?: undefined;
+    };
+    handler(input: any, ctx: any): Promise<{
+        ok: boolean;
+        from: any;
+        refusals: any;
+        warnings: any;
+        text: string;
+    } | {
+        ok: boolean;
+        from: any;
+        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;
+        text: string;
+    }>;
 } | {
     name: string;
     annotations: {
@@ -570,7 +637,10 @@ export declare const tools: ({
             name?: undefined;
             fit?: undefined;
             limit?: undefined;
-            spec?: undefined;
+            spec: {
+                type: string;
+                description: string;
+            };
             file: {
                 type: string;
                 description: string;

package/types/play/index.d.ts

@@ -1,3 +1,4 @@
+export { checkSponsored, httpSponsor, sponsoredCost, sponsorGiveBack, sponsorHandler, sponsorSigner, sponsorTopUp, stepShape, topUpFor, SPONSOR_MAX_LAMPORTS, } from './sponsor.js';
 /**
  * A signer from a Wallet Standard wallet and one of its accounts: the wallet signs, the app sends. With the wallet's
  * `solana:signMessage`, also `signMessage(bytes)`: the app's settle keys are made from one signature of it a session,
@@ -22,7 +23,7 @@ export declare const units: (amount: any, decimals: any) => bigint;
  * be made again from the wallet's signature is kept, encrypted (`browserStore()` in a browser; null keeps keys in memory
  * only).
  */
-export declare function solanaApp({ spec, rpcUrl, rpc, wallet, programs, now, keyStore, }: {
+export declare function solanaApp({ spec, rpcUrl, rpc, wallet, programs, now, keyStore, sponsor, }: {
     keyStore?: {
         get: (k: any) => string | null;
         set: (k: any, v: any) => void;
@@ -35,6 +36,7 @@ export declare function solanaApp({ spec, rpcUrl, rpc, wallet, programs, now, ke
     rpc?: null | undefined;
     rpcUrl?: string | undefined;
     spec: any;
+    sponsor?: null | undefined;
     wallet: any;
 }): {
     project: any;

package/types/play/sponsor.d.ts

@@ -0,0 +1,149 @@
+/** What a signature costs the fee payer, in lamports. */
+export declare const SIGNATURE_LAMPORTS = 5000n;
+/** The most a sponsored transaction may cost the sponsor by default: its top-up and its network fee, 0.01 SOL. */
+export declare const SPONSOR_MAX_LAMPORTS = 10000000n;
+/** The top-up: the sponsor's transfer to the player, first in the transaction. */
+export declare const sponsorTopUp: (sponsor: any, player: any, lamports: any) => {
+    programId: string;
+    keys: {
+        pubkey: any;
+        isSigner: any;
+        isWritable: any;
+    }[];
+    data: Uint8Array<any>;
+};
+/** The give-back: what the step didn't need of the top-up, from the player back to the sponsor, last in the transaction. */
+export declare const sponsorGiveBack: (sponsor: any, player: any, lamports: any) => {
+    programId: string;
+    keys: {
+        pubkey: any;
+        isSigner: any;
+        isWritable: any;
+    }[];
+    data: Uint8Array<any>;
+};
+/**
+ * What a step cost in fees and rent, from the accounts it names before and after a dry run (`pre`, `post`: one each
+ * per address, null when there is none): what the project's fee box and the oracle took, and the full rent of each
+ * account it opened that loot, Core or a token program owns. Only what the program's own moves open counts: a token
+ * account counts when its mint is named by one of the step's loot instructions (`lootNamed`), and a Core asset when no
+ * instruction of the step calls Core itself (`programs`: the programs its instructions call), so a player can't open
+ * accounts of their own on the sponsor and close them for the rent. `skip`: the payer and the player.
+ * @param {{ addresses: string[], pre: ({ owner: string, lamports: number | bigint, data?: Uint8Array } | null)[],
+ *   post: ({ owner: string, lamports: number | bigint, data?: Uint8Array } | null)[], project: string, skip?: string[],
+ *   programs?: string[], lootNamed?: string[] }} input
+ * @returns {bigint}
+ */
+export declare function sponsoredCost({ addresses, pre, post, project, skip, programs, lootNamed }: {
+    addresses: string[];
+    pre: ({
+        owner: string;
+        lamports: number | bigint;
+        data?: Uint8Array;
+    } | null)[];
+    post: ({
+        owner: string;
+        lamports: number | bigint;
+        data?: Uint8Array;
+    } | null)[];
+    project: string;
+    skip?: string[];
+    programs?: string[];
+    lootNamed?: string[];
+}): bigint;
+/** The programs a step's instructions call, and every account its loot instructions name: what `sponsoredCost` reads. */
+export declare function stepShape(instructions: any): {
+    programs: any[];
+    lootNamed: any[];
+};
+/**
+ * The top-up a step needs: what it cost the player (`spend`, before any top-up) bounded by its fees and rent
+ * (`cost`), never below 0. A step that leaves the player richer, or costs nothing, needs none.
+ */
+export declare const topUpFor: ({ spend, cost }: {
+    cost: any;
+    spend: any;
+}) => any;
+/**
+ * Whether the project's sponsor should sign this transaction (a wire, the player's signature in it): read it, dry-run
+ * it, and hold it to the rules above. Returns { ok: true, player, topUp, cost, lamports, message } (`topUp`: what the
+ * player kept of it, the top-up less the give-back; `lamports`: what it costs the sponsor, that and the network fee)
+ * or { ok: false, reason } in words.
+ * @param {Uint8Array} wire
+ * @param {{ rpc: any, project: string, sponsor: string, maxLamports?: bigint | number, maxPriorityMicroLamports?: bigint | number,
+ *   budget?: ((ask: { player: string, lamports: bigint, topUp: bigint }) => boolean | Promise<boolean>) | null }} options
+ */
+export declare function checkSponsored(wire: Uint8Array, { rpc, project, sponsor, maxLamports, maxPriorityMicroLamports, budget }: {
+    rpc: any;
+    project: string;
+    sponsor: string;
+    maxLamports?: bigint | number;
+    maxPriorityMicroLamports?: bigint | number;
+    budget?: ((ask: {
+        player: string;
+        lamports: bigint;
+        topUp: bigint;
+    }) => boolean | Promise<boolean>) | null;
+}): Promise<{
+    ok: boolean;
+    reason: any;
+} | {
+    ok: boolean;
+    player: any;
+    topUp: bigint;
+    cost: bigint;
+    lamports: bigint;
+    message: any;
+}>;
+/**
+ * The project's server side: `sign(wire)` checks a transaction (`checkSponsored`) and, when it passes, returns it with
+ * the sponsor's signature; otherwise it throws the reason (`refused: true`). `sponsor.sign(message)`: the sponsor key's
+ * ed25519 signature of the message bytes, made by the project's server, which alone holds that key.
+ * @param {{ rpc: any, project: string, sponsor: { address: string, sign: (message: Uint8Array) => Uint8Array | Promise<Uint8Array> },
+ *   maxLamports?: bigint | number, maxPriorityMicroLamports?: bigint | number,
+ *   budget?: ((ask: { player: string, lamports: bigint, topUp: bigint }) => boolean | Promise<boolean>) | null }} options
+ */
+export declare function sponsorSigner({ rpc, project, sponsor, ...limits }: {
+    rpc: any;
+    project: string;
+    sponsor: {
+        address: string;
+        sign: (message: Uint8Array) => Uint8Array | Promise<Uint8Array>;
+    };
+    maxLamports?: bigint | number;
+    maxPriorityMicroLamports?: bigint | number;
+    budget?: ((ask: {
+        player: string;
+        lamports: bigint;
+        topUp: bigint;
+    }) => boolean | Promise<boolean>) | null;
+}): {
+    address: string;
+    sign(wire: any): Promise<Uint8Array<any>>;
+};
+/**
+ * The sponsor as an HTTP endpoint (a Next.js route, a Worker): POST { transaction } (base64) answers { transaction }
+ * signed, or 403 { error } in words. `signer`: a `sponsorSigner`.
+ * @param {Request} request
+ * @param {{ address: string, sign: (wire: Uint8Array) => Promise<Uint8Array> }} signer
+ * @returns {Promise<Response>}
+ */
+export declare function sponsorHandler(request: Request, signer: {
+    address: string;
+    sign: (wire: Uint8Array) => Promise<Uint8Array>;
+}): Promise<Response>;
+/**
+ * The app's side of a sponsor behind `url` (`sponsorHandler`): what `solanaApp({ sponsor })` takes. `address`: the
+ * sponsor's public key; `maxLamports`: the most it pays a transaction, as its server says.
+ * @param {{ url: string, address: string, maxLamports?: bigint | number, fetchImpl?: typeof fetch }} options
+ */
+export declare function httpSponsor({ url, address, maxLamports, fetchImpl }: {
+    url: string;
+    address: string;
+    maxLamports?: bigint | number;
+    fetchImpl?: typeof fetch;
+}): {
+    address: string;
+    maxLamports: bigint;
+    sign(wire: any): Promise<Uint8Array<ArrayBuffer>>;
+};

package/types/results/index.d.ts

@@ -1,5 +1,5 @@
 export { canonicalJson, CERT_KINDS, CLUSTERS, drawText, entryText, giveawayHostText, hostCertText, lockText, NO_GRANT, RESULT_DOMAIN, resultBytes, revokeGiveawayText, revokeText, rosterHash, } from './wire.js';
-/** games.fun's results server, on its play host (devnet until the program's audit). */
+/** xgames.fun's results server, on its play host (devnet until the program's audit). */
 export declare const RESULTS_SERVER = "https://play.xgames.fun/xsolana";
 /** A fresh round id: 16 random bytes, in hex. Make it when the round starts. */
 export declare const newRound: () => string;

package/examples/holder-den.json

@@ -1,38 +0,0 @@
-{
-  "version": 2,
-  "network": "devnet",
-  "name": "Holder Den",
-  "prompt": "Holders of our NFT collection stake them without the NFT leaving their wallet and earn 10 DUST a day each. Locking for 30 days doubles it, 90 days triples it. NFTs with a gold background earn 25% more. Every day staked adds a point to the NFT, which the game shows as its rank.",
-  "currency": "dust",
-  "tokens": [{ "key": "dust", "source": "project", "name": "Den Dust", "symbol": "DUST", "decimals": 6 }],
-  "collection": false,
-  "farms": [
-    {
-      "key": "den",
-      "name": "The Den",
-      "stakes": "collectibles",
-      "custody": "freeze",
-      "gate": { "collection": "5N3f6KXYGvtX4zCVD3DeQoEGbzahifQiFtkxfTfEyiRz" },
-      "rewards": "dust",
-      "rate": { "perDay": 10, "minted": true },
-      "tiers": [
-        { "lock": "0d", "multiplier": 1 },
-        { "lock": "30d", "multiplier": 2 },
-        { "lock": "90d", "multiplier": 3 }
-      ],
-      "boosts": [
-        {
-          "when": {
-            "collection": "5N3f6KXYGvtX4zCVD3DeQoEGbzahifQiFtkxfTfEyiRz",
-            "attribute": "Background",
-            "equals": "Gold"
-          },
-          "add": { "addPercent": 25 }
-        }
-      ],
-      "maxBoostPercent": 25,
-      "growth": { "attribute": "points", "perDay": 1 }
-    }
-  ],
-  "scenario": { "days": 90, "perDay": { "farm:den": 30 }, "staked": { "den": 1500 } }
-}