@xgamesfun/solana 0.25.1 → 0.25.2

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

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.
@@ -632,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;
@@ -735,17 +737,18 @@ export declare function solanaApp({ spec, rpcUrl, rpc, wallet, programs, now, ke
      * it (base units, as text). Pass one to `claim`.
      */
     claims(): Promise<({
+        key?: undefined;
         tree?: undefined;
         kind: string;
         order: any;
         says: string;
         hold?: undefined;
-        key?: undefined;
         round?: undefined;
         pulls?: undefined;
         asset?: undefined;
         table?: undefined;
     } | {
+        key?: undefined;
         tree?: undefined;
         order?: undefined;
         kind: string;
@@ -755,30 +758,29 @@ export declare function solanaApp({ spec, rpcUrl, rpc, wallet, programs, now, ke
         potUnits?: string | undefined;
         prizeUnits?: string | undefined;
         hold?: undefined;
-        key?: undefined;
         round?: undefined;
         pulls?: undefined;
         asset?: undefined;
         table?: undefined;
     } | {
+        key?: undefined;
         tree?: undefined;
         order?: undefined;
         kind: string;
         asset: any;
         hold: any;
         says: string;
-        key?: undefined;
         round?: undefined;
         pulls?: undefined;
         table?: undefined;
     } | {
+        key?: undefined;
         order?: undefined;
         hold?: undefined;
         kind: string;
         asset: string;
         tree: string;
         says: string;
-        key?: undefined;
         round?: undefined;
         pulls?: undefined;
         table?: undefined;
@@ -816,10 +818,10 @@ export declare function solanaApp({ spec, rpcUrl, rpc, wallet, programs, now, ke
         asset?: undefined;
         table?: undefined;
     } | {
+        key?: undefined;
         tree?: undefined;
         order?: undefined;
         hold?: undefined;
-        key?: undefined;
         round?: undefined;
         pulls?: undefined;
         kind: string;
@@ -827,10 +829,10 @@ export declare function solanaApp({ spec, rpcUrl, rpc, wallet, programs, now, ke
         says: string;
         table?: undefined;
     } | {
+        key?: undefined;
         tree?: undefined;
         order?: undefined;
         hold?: undefined;
-        key?: undefined;
         round?: undefined;
         pulls?: undefined;
         asset?: undefined;

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