@xgamesfun/solana 0.28.1 → 0.28.2

package/types/chain/borsh.d.ts

@@ -15,9 +15,11 @@ export declare function isAccount(idl: any, name: any, data: any): boolean;
  * [{ name, data }]. Only lines the program itself printed count: the log names which program each line comes from
  * (`Program <id> invoke [n]` … `success`), and any program can print a line that looks like an event. Logs alone
  * cannot say whether the transaction succeeded (the runtime can fail it after every instruction logged success), so
- * the caller decides that from the transaction's `meta.err` and reads events only when it is null.
+ * the caller decides that from the transaction's `meta.err` and reads events only when it is null. `program` is the
+ * address the program runs at: the IDL's own unless the caller names another (the program has an address of its own on
+ * each cluster, and an IDL holds one).
  */
-export declare function decodeEvents(idl: any, logs: any): {
+export declare function decodeEvents(idl: any, logs: any, program?: any): {
     name: any;
     data: any;
 }[];

package/types/chain/rpc.d.ts

@@ -19,13 +19,19 @@ export declare const GENESIS: Readonly<{
     mainnet: "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d";
     testnet: "4uhcVJyU9pJkvQyS88uRDiswHXSCkY3zQawwpjk2NsNY";
 }>;
+/**
+ * Refuses an RPC URL that names another cluster than the one the caller works on (`devnet` or `mainnet`). Returns the
+ * URL. A URL names nothing for certain: `checkCluster` reads the chain itself.
+ */
+export declare function rightCluster(url: any, cluster?: string): any;
 /** Refuses an RPC URL that names mainnet. Returns the URL. */
-export declare function notMainnet(url: any): any;
+export declare const notMainnet: (url: any) => any;
 /**
- * Refuses a chain that is mainnet or testnet, by its genesis block, whatever its URL says (a local validator is
- * let through). `rpc` has `call`. Returns the genesis hash.
+ * Refuses a chain that is not the cluster the caller works on, by its genesis block, whatever its URL says. On
+ * devnet, mainnet and testnet are refused and a local validator is let through; on mainnet, only mainnet itself
+ * passes. `rpc` has `call`. Returns the genesis hash.
  */
-export declare function checkCluster(rpc: any): Promise<any>;
+export declare function checkCluster(rpc: any, cluster?: string): Promise<any>;
 /** The program's own words for a failed run (`AnchorError … Error Message: …`), else the last error log line. A program
  * built without its errors' text logs the error's name as its message: then the name alone (the client's IDL has
  * the sentence: `loot.lootError`). */

package/types/client/cluster.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Each cluster: loot's program there (devnet's is the IDL's own address), the chain as a wallet names it (Wallet
+ * Standard), and the RPC used when none is given. Mainnet has none: its public RPC refuses or limits what loot reads
+ * (a program's accounts, a compressed NFT's proof), so a mainnet RPC is always named (XSOLANA_RPC_URL, or `rpcUrl`).
+ */
+export declare const CLUSTERS: Readonly<{
+    devnet: Readonly<{
+        program: string;
+        chain: "solana:devnet";
+        rpc: "https://api.devnet.solana.com";
+    }>;
+    mainnet: Readonly<{
+        program: "xgames8C758PyweWB9sDw8evvwsTVwyA2fGRUeAXVPy";
+        chain: "solana:mainnet";
+        rpc: null;
+    }>;
+}>;
+/**
+ * loot's program on this process's own cluster. A live binding: it follows `useCluster`. It knows nothing of
+ * `withCluster`: code that may run for either cluster asks `lootProgram()`, as the client itself does.
+ * @type {string}
+ */
+export declare let LOOT_PROGRAM: string;
+/**
+ * For a server's own set-up (js/mcp/with-cluster.mjs does it): `current()` answers the cluster of the work being done now,
+ * or nothing outside any. While it answers one, the client is on that cluster.
+ * @param {(() => string | undefined | null) | null} current
+ */
+export declare function scopeClusters(current: (() => string | undefined | null) | null): void;
+/**
+ * Names the cluster this process works on (`devnet` or `mainnet`) and returns it. Call it first, before any address
+ * is derived: it throws when the process already works on another cluster. Inside `withCluster` it names nothing: it
+ * throws unless the cluster named is the one that work is on.
+ * @param {'devnet' | 'mainnet'} cluster
+ * @returns {'devnet' | 'mainnet'}
+ */
+export declare function useCluster(cluster: 'devnet' | 'mainnet'): 'devnet' | 'mainnet';
+/**
+ * The cluster the client works on now: inside `withCluster` that work's, else the process's own (asking settles it).
+ * @returns {'devnet' | 'mainnet'}
+ */
+export declare function cluster(): 'devnet' | 'mainnet';
+/**
+ * loot's program on the cluster the client works on now (`cluster()`): what derives an address, builds an
+ * instruction or reads who owns an account calls this.
+ * @returns {string}
+ */
+export declare function lootProgram(): string;
+/** Whether the client works on mainnet now: what is paid and won there is real money. */
+export declare const realMoney: () => boolean;
+/** The cluster an economy is on: the `network` its file names, devnet when it names none. */
+export declare const networkOf: (economy: any) => any;
+/**
+ * The RPC URL this process reads and sends through: the one given, else XSOLANA_RPC_URL, else the cluster's own
+ * (devnet's public RPC; mainnet has none). A URL that names another cluster is refused.
+ */
+export declare function clusterRpcUrl(url?: any): any;
+/** Refuses a chain that is not this process's cluster, by its genesis block (`rpc.js`, `checkCluster`). */
+export declare const checkOnCluster: (rpc: any) => Promise<any>;
+/** This process's cluster as a wallet names it (Wallet Standard): `solana:devnet` or `solana:mainnet`. */
+export declare const walletChain: () => "solana:devnet" | "solana:mainnet";

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

@@ -3613,8 +3613,8 @@ declare const _default: {
                     };
                 }[];
             } | {
-                fields?: undefined;
                 name: string;
+                fields?: undefined;
             })[];
             fields?: undefined;
         };
@@ -3862,7 +3862,6 @@ declare const _default: {
         name: string;
         docs: string[];
         type: {
-            fields?: undefined;
             kind: string;
             variants: ({
                 name: string;
@@ -3888,6 +3887,7 @@ declare const _default: {
                     type: string;
                 })[];
             })[];
+            fields?: undefined;
         };
     } | {
         name: string;
@@ -4041,11 +4041,11 @@ declare const _default: {
         docs?: undefined;
         name: string;
         type: {
-            fields?: undefined;
             kind: string;
             variants: {
                 name: string;
             }[];
+            fields?: undefined;
         };
     } | {
         name: string;
@@ -4378,7 +4378,6 @@ declare const _default: {
         name: string;
         docs: string[];
         type: {
-            fields?: undefined;
             kind: string;
             variants: ({
                 name: string;
@@ -4397,9 +4396,10 @@ declare const _default: {
                 name: string;
                 fields: string[];
             } | {
-                fields?: undefined;
                 name: string;
+                fields?: undefined;
             })[];
+            fields?: undefined;
         };
     } | {
         name: string;
@@ -4485,11 +4485,10 @@ declare const _default: {
         name: string;
         docs: string[];
         type: {
-            fields?: undefined;
             kind: string;
             variants: ({
-                fields?: undefined;
                 name: string;
+                fields?: undefined;
             } | {
                 name: string;
                 fields: string[];
@@ -4502,16 +4501,16 @@ declare const _default: {
                     };
                 }[];
             })[];
+            fields?: undefined;
         };
     } | {
         name: string;
         docs: string[];
         type: {
-            fields?: undefined;
             kind: string;
             variants: ({
-                fields?: undefined;
                 name: string;
+                fields?: undefined;
             } | {
                 name: string;
                 fields: string[];
@@ -4524,6 +4523,7 @@ declare const _default: {
                     };
                 }[];
             })[];
+            fields?: undefined;
         };
     })[];
     constants: ({

package/types/client/pda.d.ts

@@ -1,5 +1,5 @@
 import { MPL_CORE_PROGRAM } from '../chain/pda.js';
-export declare const LOOT_PROGRAM: string;
+export { checkOnCluster, CLUSTERS, cluster, clusterRpcUrl, LOOT_PROGRAM, lootProgram, networkOf, realMoney, scopeClusters, useCluster, walletChain, } from './cluster.js';
 /** MagicBlock's VRF program and its default queue, the only queue the program accepts. */
 export declare const VRF_PROGRAM = "Vrf1RNUjXmQGjmQrQLvJHs9SNkvDJEsRVFPkfSQUwGz";
 export declare const VRF_QUEUE = "Cuj97ggrhhidhbu39TijNVqE74xvKJ69gDervRUXAxGh";

package/types/economy/check.d.mts

@@ -93,8 +93,7 @@ export declare function dateWords(seconds: any): string;
  * (`ASSUMED_TRIES`).
  * Returns { ok, refusals: [{ code, where, message, fix }], warnings: [{ code, where, message, fix? }] }.
  */
-export declare function check(economy: any, { network, now, project }?: {
-    network?: string | undefined;
+export declare function check(economy: any, { now, project }?: {
     now?: number | undefined;
     project?: any;
 }): {

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;
@@ -514,8 +514,8 @@ export declare function lotteryArgs(l: any, m: any): {
                 Item: any[];
                 Collection?: undefined;
             } | {
-                Collection: any[];
                 Item?: undefined;
+                Collection: any[];
             };
             key: any;
             test: any;
@@ -608,8 +608,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;
@@ -619,11 +619,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;
@@ -682,8 +682,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;
@@ -700,8 +700,8 @@ export declare function farmArgs(f: any, m: any): {
             Item: any[];
             Collection?: undefined;
         } | {
-            Collection: any[];
             Item?: undefined;
+            Collection: any[];
         };
         key: any;
         test: any;
@@ -780,8 +780,8 @@ export declare function auctionArgs(a: any, m: any): {
                 Item: any[];
                 Collection?: undefined;
             } | {
-                Collection: any[];
                 Item?: undefined;
+                Collection: any[];
             };
             key: any;
             test: any;
@@ -792,8 +792,8 @@ export declare function auctionArgs(a: any, m: any): {
             Item: any[];
             Collection?: undefined;
         } | {
-            Collection: any[];
             Item?: undefined;
+            Collection: any[];
         };
         key: any;
         test: any;
@@ -801,11 +801,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;
@@ -911,8 +911,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/mcp/server.d.mts

@@ -352,7 +352,7 @@ export declare function runTool(name: any, input?: {}, ctx?: {}): Promise<{
     text: string;
 } | {
     program: string;
-    cluster: "devnet";
+    cluster: "devnet" | "mainnet";
     version: string;
     idl: "@xgamesfun/solana/idl.json";
     package: `@xgamesfun/solana@${any}`;

package/types/mcp/tools.d.mts

@@ -22,12 +22,14 @@ export declare function approveCommand(file?: string, paths?: any): string;
 export declare function keyFileFor(name: any): string;
 /** The command that makes a project's key file (it prints the key's address, never the key). */
 export declare const keygenCommand: (keyFile: any) => string;
-export declare const CLUSTER = "devnet";
 export declare const DEVNET_RPC = "https://api.devnet.solana.com";
-/** What every answer carries, so an agent never has to remember the program's address. */
+/**
+ * What every answer carries, so an agent never has to remember the program's address. The program and the cluster are
+ * read when asked for: this process's cluster (`client/cluster.js`).
+ */
 export declare const PROGRAM_INFO: Readonly<{
-    program: string;
-    cluster: "devnet";
+    readonly program: string;
+    readonly cluster: "devnet" | "mainnet";
     version: string;
     idl: "@xgamesfun/solana/idl.json";
     package: `@xgamesfun/solana@${any}`;
@@ -90,7 +92,7 @@ export declare const tools: ({
     };
     handler({ part }?: Readonly<Record<string, any>>): Promise<{
         program: string;
-        cluster: "devnet";
+        cluster: "devnet" | "mainnet";
         version: string;
         idl: "@xgamesfun/solana/idl.json";
         package: `@xgamesfun/solana@${any}`;
@@ -743,10 +745,10 @@ export declare const tools: ({
         additionalProperties: boolean;
     };
     handler(input: any, ctx: any): Promise<{
+        token?: undefined;
         mint?: undefined;
         ok: boolean;
         text: string;
-        token?: undefined;
     } | {
         mint?: undefined;
         ok: boolean;
@@ -823,7 +825,7 @@ export declare const tools: ({
     };
     handler(): Promise<{
         program: string;
-        cluster: "devnet";
+        cluster: "devnet" | "mainnet";
         version: string;
         idl: "@xgamesfun/solana/idl.json";
         package: `@xgamesfun/solana@${any}`;

package/types/mcp/with-cluster.d.mts

@@ -0,0 +1,8 @@
+/**
+ * Runs `fn` on `cluster` (`devnet` or `mainnet`) and returns what it returns. A cluster loot does not know is refused.
+ * @template T
+ * @param {'devnet' | 'mainnet'} cluster
+ * @param {() => T} fn
+ * @returns {T}
+ */
+export declare function withCluster<T>(cluster: 'devnet' | 'mainnet', fn: () => T): T;

package/types/play/index.d.ts

@@ -4,7 +4,7 @@ export { checkSponsored, httpSponsor, sponsoredCost, sponsorGiveBack, sponsorHan
  * `solana:signMessage`, also `signMessage(bytes)`: the app's settle keys are made from one signature of it a session,
  * so a page that closes can make them again (`recover`).
  */
-export declare function walletStandardSigner(wallet: any, account: any, chain?: string): {
+export declare function walletStandardSigner(wallet: any, account: any, chain?: "solana:devnet" | "solana:mainnet"): {
     address: any;
     signTransaction(wire: any): Promise<any>;
     signMessage?: ((message: any) => Promise<any>) | undefined;
@@ -34,7 +34,7 @@ export declare function solanaApp({ spec, rpcUrl, rpc, wallet, programs, now, ke
     now?: (() => number) | undefined;
     programs?: {} | undefined;
     rpc?: null | undefined;
-    rpcUrl?: string | undefined;
+    rpcUrl?: null | undefined;
     spec: any;
     sponsor?: null | undefined;
     wallet: any;

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';
-/** xgames.fun's results server, on its play host (devnet until the program's audit). */
+/** xgames.fun's results server, on its play host. One host answers for devnet and for mainnet: each request names its cluster. */
 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;
@@ -19,7 +19,7 @@ export declare function keyFromSecret(secret: any): Promise<{
     sign: (message: any) => Promise<Uint8Array<ArrayBuffer>>;
 }>;
 /** One signer's signature of a result: { key, signature }. `signer` is a key from newKey, or anything with sign(). */
-export declare function signResult(signer: any, result: any, cluster?: string): Promise<{
+export declare function signResult(signer: any, result: any, cluster?: "devnet" | "mainnet"): Promise<{
     key: any;
     signature: string;
 }>;
@@ -30,7 +30,7 @@ export declare function signResult(signer: any, result: any, cluster?: string):
  */
 export declare function report({ server, cert, signer, game, round, endedAt, winners, cluster, fetchImpl, }: {
     cert: any;
-    cluster?: string | undefined;
+    cluster?: "devnet" | "mainnet" | undefined;
     endedAt: any;
     fetchImpl?: typeof fetch | undefined;
     game: any;
@@ -96,7 +96,7 @@ export declare const draws: {
     }) => Promise<any>;
     /** A player enters with their play-host token, or with their wallet's signature (`wallet`, `signMessage`). */
     enter: ({ server, game, draw, token, wallet, signMessage, cluster, fetchImpl, }: {
-        cluster?: string | undefined;
+        cluster?: "devnet" | "mainnet" | undefined;
         draw: any;
         fetchImpl?: typeof fetch | undefined;
         game: any;
@@ -110,7 +110,7 @@ export declare const draws: {
         beacon: any;
         by: any;
         cert?: null | undefined;
-        cluster?: string | undefined;
+        cluster?: "devnet" | "mainnet" | undefined;
         draw: any;
         fetchImpl?: typeof fetch | undefined;
         game: any;
@@ -142,7 +142,7 @@ export declare const giveaways: {
     }) => Promise<any>;
     /** Reports its result, signed by its session key. `grant`: the host's grant (each winner is paid from it). */
     report: ({ server, game, giveaway, session, endedAt, winners, grant, cluster, fetchImpl, }: {
-        cluster?: string | undefined;
+        cluster?: "devnet" | "mainnet" | undefined;
         endedAt: any;
         fetchImpl?: typeof fetch | undefined;
         game: any;

package/types/results/server.d.ts

@@ -35,7 +35,7 @@ export declare function holds({ rpc, spec, wallet, item, atLeast, attribute, min
 }): Promise<number>;
 /** The exact text a wallet signs to prove it is its owner's: fixed lines, so nothing else can be passed off as it. */
 export declare const proofText: ({ cluster, game, wallet, purpose, nonce, expires }: {
-    cluster?: string | undefined;
+    cluster?: "devnet" | "mainnet" | undefined;
     expires: any;
     game: any;
     nonce: any;
@@ -47,7 +47,7 @@ export declare const proofText: ({ cluster, game, wallet, purpose, nonce, expire
  * (unix seconds, `seconds` from now) and takes each nonce once, so a signed proof can't be replayed.
  */
 export declare function proofRequest({ cluster, game, wallet, purpose, seconds, now, }: {
-    cluster?: string | undefined;
+    cluster?: "devnet" | "mainnet" | undefined;
     game: any;
     now?: number | undefined;
     purpose?: string | undefined;
@@ -69,7 +69,7 @@ export declare function readProof(text: any): {
  * `fields.nonce` against the ones the server handed out and not yet used.
  */
 export declare function verifyProof({ text, signature, wallet, game, purpose, cluster, now, }: {
-    cluster?: string | undefined;
+    cluster?: "devnet" | "mainnet" | undefined;
     game: any;
     now?: number | undefined;
     purpose?: null | undefined;

package/types/results/wire.d.ts

@@ -37,14 +37,14 @@ export declare const CERT_KINDS: Readonly<{
 }>;
 /** The text the owner signs to let `host` report `game`'s results until `until` (unix seconds). */
 export declare const hostCertText: ({ cluster, game, host, until }: {
-    cluster?: string | undefined;
+    cluster?: "devnet" | "mainnet" | undefined;
     game: any;
     host: any;
     until: any;
 }) => string;
 /** The text the owner signs to take `host` back. */
 export declare const revokeText: ({ cluster, game, host }: {
-    cluster?: string | undefined;
+    cluster?: "devnet" | "mainnet" | undefined;
     game: any;
     host: any;
 }) => string;
@@ -57,7 +57,7 @@ export declare const revokeText: ({ cluster, game, host }: {
  * JSON), or 'default'.
  */
 export declare const drawText: ({ cluster, game, draw, engine, winners, prizes, payout, identity, slug, rates, }: {
-    cluster?: string | undefined;
+    cluster?: "devnet" | "mainnet" | undefined;
     draw: any;
     engine: any;
     game: any;
@@ -71,7 +71,7 @@ export declare const drawText: ({ cluster, game, draw, engine, winners, prizes,
 /** The text the organizer signs to lock a draw's players (`roster`: rosterHash) to a beacon round still to come. */
 export declare const lockText: ({ cluster, game, draw, roster, players, beacon, net }: {
     beacon: any;
-    cluster?: string | undefined;
+    cluster?: "devnet" | "mainnet" | undefined;
     draw: any;
     game: any;
     net?: string | undefined;
@@ -80,7 +80,7 @@ export declare const lockText: ({ cluster, game, draw, roster, players, beacon,
 }) => string;
 /** The text a player's wallet signs to enter a draw (identity 'wallet'). */
 export declare const entryText: ({ cluster, game, draw }: {
-    cluster?: string | undefined;
+    cluster?: "devnet" | "mainnet" | undefined;
     draw: any;
     game: any;
 }) => string;
@@ -89,7 +89,7 @@ export declare const entryText: ({ cluster, game, draw }: {
  * with that X account through the play host) or a wallet address; their giveaways pay from grant `grant` alone.
  */
 export declare const giveawayHostText: ({ cluster, game, who, slug, grant, until }: {
-    cluster?: string | undefined;
+    cluster?: "devnet" | "mainnet" | undefined;
     game: any;
     grant: any;
     slug: any;
@@ -98,7 +98,7 @@ export declare const giveawayHostText: ({ cluster, game, who, slug, grant, until
 }) => string;
 /** The text the owner (or authority) signs to take a giveaway host back. */
 export declare const revokeGiveawayText: ({ cluster, game, who }: {
-    cluster?: string | undefined;
+    cluster?: "devnet" | "mainnet" | undefined;
     game: any;
     who: any;
 }) => string;
@@ -114,7 +114,7 @@ export declare function canonicalJson(value: any): any;
  * place past 255 and more than 255 winners are refused, never written as something else.
  */
 export declare function resultBytes({ cluster, game, round, endedAt, winners }: {
-    cluster?: string | undefined;
+    cluster?: "devnet" | "mainnet" | undefined;
     endedAt: any;
     game: any;
     round: any;