@xgamesfun/solana 0.26.1 → 0.26.3

package/skills/xsolana-economy/SKILL.md

@@ -9,8 +9,9 @@ An economy is one JSON spec (`xsolana.json` in the project) on **loot**, a Solan
 writes or deploys a contract: the spec is checked, simulated and priced by the `xsolana_*` tools, and the project's
 owner puts it live by approving in their own wallet. It runs on **devnet** until the program is audited.
 
-The tools are the `xsolana_*` MCP tools. Without MCP, the same from a terminal: `npx -y @xgamesfun/solana@0.26.1 <guide|examples|check|simulate|cost|explain|review|publish|status> [xsolana.json]`,
-or `npx -y @xgamesfun/solana@0.26.1 tool <name> '<json>'` for any tool (always with the exact version).
+The tools are the `xsolana_*` MCP tools. Without MCP, the same from a terminal: `npx -y @xgamesfun/solana@0.26.3 <guide|examples|check|simulate|cost|explain|review|publish|status> [xsolana.json]`,
+`npx -y @xgamesfun/solana@0.26.3 token <mint>` for a coin made elsewhere,
+or `npx -y @xgamesfun/solana@0.26.3 tool <name> '<json>'` for any tool (always with the exact version).
 
 ## Rules (always)
 
@@ -26,8 +27,9 @@ or `npx -y @xgamesfun/solana@0.26.1 tool <name> '<json>'` for any tool (always w
    `xsolana_simulate`, `xsolana_cost` and `xsolana_explain`, never your own arithmetic. What a player pays is the tools'
    "in all" number for that action (price, fee, oracle, network and rent that never comes back): quote it as is.
 6. **Flag the law once.** The first time the checker raises `W-CHANCE-PRIZE` (paid chance at money: boxes with
-   prizes, lotteries, contests), `W-CHANCE-ITEMS` (paid random collectibles a player can resell: loot boxes, gacha) or
-   `W-REVENUE-SHARE` (stakers paid from sales), say it in one plain sentence. Don't repeat it in later answers, or add
+   prizes, lotteries, contests), `W-CHANCE-ITEMS` (paid random collectibles a player can resell: loot boxes, gacha),
+   `W-REVENUE-SHARE` (stakers paid from sales) or `W-TOKEN-SALE` (a presale: people pay for a share of a new token),
+   say it in one plain sentence. Don't repeat it in later answers, or add
    legal notes to pages and apps you build, unless the person asks or a flag of a new kind appears. When they ask about
    the law, answer what you know and leave the rest to their lawyer: you are not one. Never call anything an
    investment, a return or passive income, and never promise it is safe. The approval page shows the flags and that
@@ -121,13 +123,33 @@ or `npx -y @xgamesfun/solana@0.26.1 tool <name> '<json>'` for any tool (always w
    level would cost. Run it again after every change that touches a route that pays.
 9. **When they say "put it live"**: `xsolana_publish` lists every step and its cost and gives the command. Tell them to
    run it themselves in the project folder, exactly as `xsolana_publish` gives it (it names the exact version:
-   `npx -y @xgamesfun/solana@0.26.1 approve xsolana.json`; never drop the version). It opens a page on their computer where
+   `npx -y @xgamesfun/solana@0.26.3 approve xsolana.json`; never drop the version). It opens a page on their computer where
    they connect a devnet wallet and approve; what lands is written back into `xsolana.json`. You publish nothing.
 10. **After it is live**: `xsolana_status` shows each part on chain; read it before acting on what the person says
     happened. A later change is the same loop: save, publish, and the approval sends only what changed. What only the
     owner signs (open or decide a contest, pay out) goes on an owner page they approve in their own wallet:
     `references/after-launch.md`.
 
+## When they ask for a token
+
+"A token for my game" is one of four things. Find out which from what they say it is for, before writing anything
+(ask only when they haven't said):
+
+| They mean                                                                   | It is                                                | In the spec                                                                                                                                                     |
+| --------------------------------------------------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| points, tickets, shards: what players earn and spend in the game            | a token the project mints as its rules say           | `source: "project"`, given by a recipe's or a grant's prize (`"from": "mint"`), a farm's `rate` (`"minted": true`) or a schedule (`"does": "issue"`)            |
+| "our own coin, 10 million, we hand it out", a community token               | a fixed supply, all of it to the owner, no more ever | `source: "project"` with `supply`; pools are seeded from it, and a presale (a contest), sealed vesting (a schedule) and a farm hand it out                      |
+| "a coin people can trade", "on pump.fun", "a bonding curve", "creator fees" | a market, which loot does not run                    | they launch it on a launchpad or an AMM, in their own wallet; then `xsolana_token {"mint": …}` gives its entry, and loot's shops, boxes, farms and gates use it |
+| "our token", "the coin we launched", "this mint"                            | a coin that exists                                   | `xsolana_token {"mint": …}`: its entry with decimals, program and `powers` read from the chain. Never type them by hand, and never guess an address             |
+
+Say what each gives up. The first two have no public market: nobody trades them unless the project lists them
+somewhere itself. A coin launched on a market usually has nobody left who can mint it (`xsolana_token` says so): the
+economy pays out only what its owner puts into its pools. On devnet a coin trades nothing of value.
+
+A token the setup makes is named on chain as it goes live, so ask for its name, its ticker and a picture first
+(`references/telling-the-person.md`). Whatever the kind, rule 6 holds: never call a token an investment or promise it
+a price.
+
 ## Building the app around it
 
 A game, a site or a bot calls the live economy with the player's own wallet, through the package's player module

package/skills/xsolana-economy/references/sentence-to-spec.md

@@ -119,7 +119,7 @@ maps to a part of the spec (`xsolana_guide` has every field).
 | "holders of the ticket claim a free badge once"                                                                                            | an open grant: no `vouchers`, `keys` or `list`, a `gate` of the ticket, and `limits.perWallet: 1` (each ticket shown claims once too)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | "bring your own NFT", "any NFT of a partner collection can play", "holders of X get"                                                       | a `gate` (or a farm's, or odds') rule with `collection`: the collection's address; the project's notes about each NFT (a level) go in its Sheet                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | "our own token, 10 million, we keep it", "a fixed supply", "a community token"                                                             | `source: "project"` with `supply`: going live mints all of it to the owner and turns minting off for good; pools are seeded from it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| "our token", "the coin we already launched", "this mint"                                                                                   | `source: "existing"` with `mint` and `decimals` (ask for the address). loot doesn't put a token on a market: for trading, launch it on a token launchpad or an exchange first                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| "our token", "the coin we already launched", "this mint"                                                                                   | `source: "existing"`: ask for the mint's address, and `xsolana_token {"mint": …}` gives the whole entry (decimals, program, `powers`). loot doesn't put a token on a market: for trading, launch it on a token launchpad or an exchange first (SKILL.md, "When they ask for a token")                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | "Token-2022", "a transfer fee"                                                                                                             | `program: "token-2022"` and `powers.transferFeePercent`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | "tokens only, no NFTs"                                                                                                                     | `"collection": false`: no collection is made (no collectibles; normal items and tokens work)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | "mint into our existing collection", "two collections"                                                                                     | `collections`: Core collections the owner's wallet already controls, each with the project added as an update delegate; an item's `collection` names the one it is minted into                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

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

@@ -26,7 +26,9 @@ and the spec differ (a limit, an amount, a key not set yet), change one of them
 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 each once, the
+   what players spend; regulators look at that when they decide whether a token is a security." `W-TOKEN-SALE`:
+   "People pay for a share of a new token; selling a token to raise money is what securities law looks at first."
+   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
@@ -117,6 +119,13 @@ Don'ts:
   otherwise, and until it is filled those prizes pay nothing.
 - **A token the project mints** (`source: "project"`) is how points, tickets, attempts and shards work; an existing coin
   needs its mint address and decimals from the person (ask; never guess an address).
+- **A token the setup makes is named on chain as it goes live**: its `name`, its `symbol` and its `uri` (a link to a
+  JSON file the project hosts, `{ "name", "symbol", "image": "https://…" }`), which is what wallets and explorers show.
+  Ask for the name, the ticker and a picture before going live: with no `uri` it shows by name and ticker with no
+  picture. Only the owner's wallet can change the three later (Token Metadata's rule, not loot's), and these tools
+  don't change a live token's yet, so get them right first. The record costs about 0.014 SOL (`xsolana_cost` says it:
+  rent, and 0.01 SOL Token Metadata keeps). A token that went live before the tools wrote one has none and
+  can't be given one: only a mint's own authority can name it, and its minting was handed on or turned off.
 - **NFTs the project has no authority over** (any collection but its own): they count as they are. Say that
   whatever their collection lets be written on an NFT (even by its holder) is what a gate or a boost reads, and that
   the project's notes about one (levels, uses) live in its Sheet, which the authority writes and pays for. Every

package/types/chain/metadata.d.ts

@@ -0,0 +1,40 @@
+/** A record's size: Token Metadata pads every one to it, whatever its name, ticker and link. */
+export declare const METADATA_BYTES = 607;
+/** What Token Metadata keeps in each record it makes, on top of the record's rent: its own fee. */
+export declare const METADATA_FEE = 10000000n;
+/** The longest name, ticker and link a record takes, in UTF-8 bytes. */
+export declare const METADATA_LIMITS: Readonly<{
+    name: 32;
+    symbol: 10;
+    uri: 200;
+}>;
+/** The address of a mint's Token Metadata record. */
+export declare const metadataAddress: (mint: any) => any;
+/**
+ * Token Metadata's CreateV1 for a fungible token whose mint exists: its name, its ticker and a link to a JSON file with
+ * its picture ('' for none). `authority` is the mint's authority and signs; it becomes the record's update authority,
+ * the only one who can change the record later. `payer` pays its rent and Token Metadata's fee (`METADATA_FEE`).
+ * The mint is listed read-only: this path of Token Metadata writes nothing to a mint that exists. That is the
+ * program's behaviour, not a lock: in a setup's own transaction the mint is writable all the same (the same
+ * transaction makes it), so the tests read its supply and authorities back after the record is made. The record says
+ * a fungible token whatever the decimals (CreateMetadataAccountV3 would call one of 0 decimals an asset, which
+ * wallets list with collectibles).
+ */
+export declare function createFungibleMetadataIx({ mint, authority, payer, name, symbol, uri }: {
+    authority: any;
+    mint: any;
+    name: any;
+    payer?: any;
+    symbol: any;
+    uri?: string | undefined;
+}): {
+    programId: string;
+    keys: {
+        pubkey: any;
+        isSigner: any;
+        isWritable: any;
+    }[];
+    data: Uint8Array<any>;
+};
+/** The update authority a Token Metadata record names (who can change its name, ticker and link). */
+export declare const metadataUpdateAuthority: (data: any) => string | null;

package/types/chain/mint.d.ts

@@ -23,3 +23,32 @@ export declare function parseMint(address: any, owner: any, data: any, metadataD
     symbol: string | null;
     uri: string | null;
 } | null;
+/**
+ * A token made elsewhere as an economy spec names it: its `tokens` entry (`source: "existing"`), every field read from
+ * the chain so nothing is typed in by hand: the mint, its decimals and token program, its name and ticker when it has
+ * a name record, and `powers` (token2022.js `powersOf`: what the mint's own keys can do). `account`: the mint's
+ * ({ owner, data }); `record`: its Token Metadata record's data, when there is one. `key`: what the spec will call it
+ * (default: its ticker in the letters a key takes, else "token"). `project`: the loot project, whose own tokens read
+ * `mintAuthority: "project"`; `epoch`: the chain's current epoch, for a transfer fee since changed (`powersOf`). The
+ * name and ticker are cut to what a spec takes, on one line. Wrapped SOL is SOL (`{ key: "sol", source: "sol" }`).
+ * Null when `account` is no mint.
+ */
+export declare function tokenEntry(address: any, account: any, record?: null, { key, project, epoch }?: {
+    epoch?: null | undefined;
+    key?: null | undefined;
+    project?: null | undefined;
+}): {
+    key: string;
+    source: string;
+} | {
+    key: string;
+    source: string;
+    name?: string | undefined;
+    symbol?: string | undefined;
+    decimals: any;
+    program: string;
+    mint: any;
+    powers: {
+        mintAuthority: string;
+    } | null;
+} | null;

package/types/chain/token2022.d.ts

@@ -26,6 +26,44 @@ export declare function mintPowers({ owner, data }: {
     data: any;
     owner: any;
 }): any[];
+/**
+ * What a mint's own keys can do, as an economy spec's `powers` says it (schema `token.powers`), read from the mint's
+ * account (`owner`, its token program; `data`), so nobody has to look it up and type it in. Only what is so is named:
+ * a plain mint nobody can mint more of reads `{ mintAuthority: 'none' }`. `project`: the loot project's address, when
+ * known, whose own tokens read `mintAuthority: 'project'`; any other minter is `'someone else'`.
+ *   freeze: a freeze authority; permanentDelegate; transferHook (a hook program, or an authority who can name one);
+ *   transferFeePercent and feeChangeable (its authority is still there); closeAuthority; pausable; defaultState (the
+ *   mint sets what new accounts start as) and defaultFrozen (they start frozen); nonTransferable;
+ *   confidentialTransfers.
+ * A mint holds two transfer fees: the one in force until an epoch, and the one from that epoch on. With `epoch` (the
+ * chain's current one) the fee read is the one that applies: the newer once its epoch has come, else the higher of
+ * the two (the fee today, or the one already set to follow). Without it, the higher of the two: never less than what
+ * a transfer pays, and a fee since lowered still reads at its old rate.
+ * Returns null when the account is not a mint of either token program.
+ */
+export declare function powersOf({ owner, data }: {
+    data: any;
+    owner: any;
+}, { project, epoch }?: {
+    epoch?: null | undefined;
+    project?: null | undefined;
+}): {
+    mintAuthority: string;
+} | null;
+/**
+ * What a Token-2022 mint's state does today that its powers don't say: `paused` (a pause is on: nothing moves),
+ * `scaled` (ScaledUiAmount or InterestBearing: wallets show amounts multiplied by a rate, not the base units the
+ * program moves and an economy counts in) and `scaler` (somebody can still change that rate). All false for a classic
+ * mint, or one with none of them.
+ */
+export declare function mintState({ owner, data }: {
+    data: any;
+    owner: any;
+}): {
+    paused: boolean;
+    scaled: boolean;
+    scaler: boolean;
+};
 /** Whether a token account requires a memo on every transfer into it. */
 export declare function requiresMemo(accountData: any): boolean;
 /** The hook's list of extra accounts for this mint. */

package/types/economy/cost.d.mts

@@ -2,6 +2,7 @@
 export declare function setupCost(plan: any, economy: any): {
     accounts: any;
     rentSol: any;
+    metadataFeesSol: any;
     programFeesSol: any;
     networkFeesSol: any;
     seeds: {};
@@ -51,6 +52,7 @@ export declare function cost(economy: any, { now, only, live }?: {
     setup: {
         accounts: any;
         rentSol: any;
+        metadataFeesSol: any;
         programFeesSol: any;
         networkFeesSol: any;
         seeds: {};

package/types/economy/legal.d.mts

@@ -4,6 +4,7 @@ export declare const LEGAL: Readonly<{
     'W-CHANCE-ITEMS': "Players pay for random items they can resell (a loot box). Some places treat that as gambling and many require the odds shown: show them on the page, and get a lawyer before real money.";
     'W-AUCTION-SHILL': "Anyone, the seller included, can bid to push an auction’s price up (shill bidding): a reserve is the honest way to set a floor.";
     'W-REVENUE-SHARE': "Stakers are paid from what players spend, which regulators look at when they decide whether a token is a security: before real money, get a lawyer, or pay rewards from emissions instead.";
+    'W-TOKEN-SALE': "People pay for a share of a new token (a presale). Selling a token to raise money is what securities law looks at first, and many places limit who may buy: before real money, get a lawyer.";
 }>;
 /** The legal flags a checker verdict raises, each once, in the order the checker raised them: [{ code, says }]. */
 export declare const legalFlags: (verdict: 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;
             } | {
-                Item?: undefined;
                 Collection: any[];
+                Item?: undefined;
             };
             key: any;
             test: any;
@@ -159,8 +159,8 @@ export declare function boxArgs(b: any, m: any): {
             Item: any[];
             Collection?: undefined;
         } | {
-            Item?: undefined;
             Collection: any[];
+            Item?: undefined;
         };
         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;
                 } | {
-                    Item?: undefined;
                     Collection: any[];
+                    Item?: undefined;
                 };
                 key: any;
                 test: any;
@@ -514,8 +514,8 @@ export declare function lotteryArgs(l: any, m: any): {
                 Item: any[];
                 Collection?: undefined;
             } | {
-                Item?: undefined;
                 Collection: any[];
+                Item?: undefined;
             };
             key: any;
             test: any;
@@ -608,8 +608,8 @@ export declare function contestArgs(c: any, m: any, at?: any): {
                 Item: any[];
                 Collection?: undefined;
             } | {
-                Item?: undefined;
                 Collection: any[];
+                Item?: undefined;
             };
             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;
         } | {
-            Item?: undefined;
             Collection: any[];
+            Item?: undefined;
         };
         key: any;
         test: any;
@@ -700,8 +700,8 @@ export declare function farmArgs(f: any, m: any): {
             Item: any[];
             Collection?: undefined;
         } | {
-            Item?: undefined;
             Collection: any[];
+            Item?: undefined;
         };
         key: any;
         test: any;
@@ -780,8 +780,8 @@ export declare function auctionArgs(a: any, m: any): {
                 Item: any[];
                 Collection?: undefined;
             } | {
-                Item?: undefined;
                 Collection: any[];
+                Item?: undefined;
             };
             key: any;
             test: any;
@@ -792,8 +792,8 @@ export declare function auctionArgs(a: any, m: any): {
             Item: any[];
             Collection?: undefined;
         } | {
-            Item?: undefined;
             Collection: any[];
+            Item?: undefined;
         };
         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;
             } | {
-                Item?: undefined;
                 Collection: any[];
+                Item?: undefined;
             };
             key: any;
             test: any;

package/types/mcp/server.d.mts

@@ -260,13 +260,13 @@ export declare function runTool(name: any, input?: {}, ctx?: {}): Promise<{
     warnings: any[];
     text: string;
 } | {
+    setupSol?: undefined;
     ok: boolean;
     transactions: number;
     approvals: number;
     steps: never[];
     text: string;
     command?: undefined;
-    setupSol?: undefined;
 } | {
     ok: boolean;
     command: string;
@@ -297,6 +297,58 @@ export declare function runTool(name: any, input?: {}, ctx?: {}): Promise<{
         kind?: string | undefined;
     })[];
     text: string;
+} | {
+    mint?: undefined;
+    ok: boolean;
+    text: string;
+    token?: undefined;
+} | {
+    mint?: undefined;
+    ok: boolean;
+    token: {
+        key: string;
+        source: string;
+    } | {
+        key: string;
+        source: string;
+        name?: string | undefined;
+        symbol?: string | undefined;
+        decimals: any;
+        program: string;
+        mint: any;
+        powers: {
+            mintAuthority: string;
+        } | null;
+    };
+    text: string;
+} | {
+    ok: boolean;
+    token: {
+        key: string;
+        source: string;
+    } | {
+        key: string;
+        source: string;
+        name?: string | undefined;
+        symbol?: string | undefined;
+        decimals: any;
+        program: string;
+        mint: any;
+        powers: {
+            mintAuthority: string;
+        } | null;
+    };
+    mint: {
+        address: string;
+        program: string;
+        decimals: any;
+        supply: string;
+        name: any;
+        symbol: any;
+        mintAuthority: string | null;
+        freezeAuthority: string | null;
+    };
+    text: string;
 } | {
     program: string;
     cluster: "devnet";