xsolana

io.github.XGamesFunPublished by GitHub account XGamesFunv0.20.1Updated Oct 30, 2026

Design, check, simulate and launch Solana game economies on loot, one shared program, no contract.

VerifiedSTDIODesktop onlyFinanceDeveloper ToolsAI & ML

Overview

AI-generated overview

Design, check, simulate and prepare Solana game economies on the shared loot program, from a JSON spec rather than a custom smart contract.

What you can do
  • Read guidance and find worked examples for shops, loot boxes, lotteries, auctions, staking farms, crafting and similar economies
  • Check an economy spec for refusals and warnings, and simulate expected payouts, house edge and pool flows
  • Estimate going-live and per-action costs, and explain the economy in plain words
  • Save a checked spec into the project and prepare a publish step the owner approves in their own wallet
  • Read a live economy's on-chain state, and show how an app calls it with the player's wallet
When to use it
Useful when someone wants to build or review a Solana game or community economy — loot boxes, raffles, auctions, staking farms, crafting — and wants it validated and simulated before anything goes on chain. Also handy for explaining an existing economy or wiring a game client to it.
Requirements
Runs locally over stdio via the npm package @xgamesfun/solana (Node 22 or later). No accounts, keys or API keys are declared. Optional environment variables: XSOLANA_RPC_URL for a devnet RPC used by approve and status, plus XSOLANA_NO_OPEN and XSOLANA_DEBUG. Going live needs a devnet wallet the owner connects in a local approval page.
Before you install
Devnet only and the program is not independently audited. Publishing prepares real transactions the owner must approve in their own wallet; the agent never signs or asks for a key, and specs must not contain keys. Simulations and cost figures are estimates, not guarantees, and the README disclaims warranty and legal or financial advice.

Installation

In SourceWeft

  1. Open xsolana in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

solana-kit

The tools for loot, one shared Solana program for game and community economies. This repository is the npm package @xgamesfun/solana:

  • a JavaScript client with no Solana SDK (@xgamesfun/solana/client), a player module for apps (/play) and a results client (/results);
  • the economy spec and its checker, quick simulation, cost and plain-words explainer;
  • the xsolana CLI and an MCP server with ten xsolana_* tools;
  • the xsolana-economy skill, and one plugin that carries the tools and the skill to Claude Code and Codex;
  • a local approval page where a project's owner approves going live in their own wallet.

An economy is a JSON spec, not a new smart contract. Every project shares the one program, and none writes its own.

Status: loot 0.22.0, program ID 9cwqM1TXytPnFZsLfmUyv2dg4uW6Ch9C6UJVPns7NFQ, devnet only. The program is not independently audited, and nothing runs on mainnet until it is. See SECURITY.md.

Disclaimer: provided as is, with no warranty and no guarantee that the program or the tools are safe. Use them at your own risk; you are responsible for every transaction you approve and for making sure what you build is legal where it runs. Nothing here is legal or financial advice. Read DISCLAIMER.md before you use it.

What an economy can be made of

  • payments and splits, in tokens or with an NFT
  • shops (a purchase in one transaction) and loot boxes
  • pools and timed schedules, sealed or not
  • lotteries and raffles, including no-loss lotteries
  • prizes of any kind on every route, random or not: items, tokens, and NFTs the project holds in a stash
  • an NFT as the price on every route that takes money
  • staking farms with lock tiers, boosts, early exits and tolls
  • crafting recipes
  • holds and contests, with prizes by rank or by stake
  • auctions: the highest bid wins, the outbid refunded at once
  • listings for sale or rent, and bids and loans between players
  • perks, staking and holds for any NFT, whether the project has authority over it or not
  • allowlists of any size (a Merkle list) on every gated route
  • capped rewards and grants that a server vouches for
  • rules on what a collectible says

Every move leaves a public receipt. docs/program.md describes how the program behaves.

Use it from an AI coding agent

The MCP server and the skill let Claude Code, Codex or any MCP agent turn a one-line idea into a checked, simulated economy and hand you the command that puts it live in your own wallet.

Claude Code

/plugin marketplace add XGamesFun/solana-kit/plugin install xsolana@xgamesfun

Codex

codex plugin marketplace add XGamesFun/solana-kitcodex plugin add xsolana@xgamesfun

Any agent with MCP (Cursor, opencode, Cline…): run the server with npx -y --package=@xgamesfun/[email protected] xsolana mcp. Or let npx -y @xgamesfun/[email protected] connect register it, with the skill, for Claude Code and Codex.

Then ask for an economy, for example "a fishing game where each cast costs 0.02 SOL, with a rare golden fish and a monthly draw".

Going live is always yours: npx -y @xgamesfun/[email protected] approve opens a page on your computer where you connect a devnet wallet and approve each transaction. The agent never signs and never asks for a key.

Use it from a terminal

Every tool runs from the CLI too, on a spec file (xsolana.json by default):

bash
npx -y @xgamesfun/[email protected] examples shop with loot boxes   # the nearest worked examplesnpx -y @xgamesfun/[email protected] check xsolana.json                 # refusals and warningsnpx -y @xgamesfun/[email protected] simulate xsolana.json              # where the money goes, day by daynpx -y @xgamesfun/[email protected] cost xsolana.json                  # what going live and each action costnpx -y @xgamesfun/[email protected] explain xsolana.json               # the economy in plain wordsnpx -y @xgamesfun/[email protected] approve xsolana.json               # go live, approved in your own wallet

xsolana help lists every command. Every command names the exact version, so npx runs that release and never whatever is newest under the name.

Use it from code

bash
npm install @xgamesfun/solana
js
import * as loot from '@xgamesfun/solana/client';const ix = loot.openBoxIx({ player, project, box, nonce }); // one builder per instruction, no Solana SDK
ImportWhat
@xgamesfun/solanathe economy tools: check, simulate, plan, cost, explainEconomy, model
@xgamesfun/solana/clientevery PDA, one builder per instruction, account and receipt decoders, grant vouchers
@xgamesfun/solana/playsolanaApp: what a player does with a live economy, from a browser app
@xgamesfun/solana/resultsresults and vouchers a game's server signs
@xgamesfun/solana/chain/*browser-safe Solana primitives: base58, Borsh, transactions, PDAs, tokens, Core
@xgamesfun/solana/idl.jsonthe program's IDL, the authority for account and argument layouts
@xgamesfun/solana/release.jsonthe program build, IDL and client this release is pinned to

The client, chain and play modules run in browsers and Node 22 or later, with no bundler required. The package ships TypeScript declarations for every entry point.

Documentation

docs/program.mdthe program: who signs, accounts, every instruction, fees, limits, receipts, costs
docs/nfts.mdNFTs and tokens, with and without the project's authority
docs/harnesses.mdhow the plugin reaches Claude Code and Codex, and the release checklist
skills/xsolana-economythe skill an agent follows
examples/whole economies that check and go live in the tests; ideas.json, 112 real economies rated
evals/fresh-session evals of agents building on loot
CHANGELOG.md, SECURITY.mdversions, the trust model, reporting a vulnerability

Layout

PathWhat
js/chain/browser-safe Solana primitives, no SDK
js/client/the client; idl/ is the program's IDL
js/economy/the economy spec (version 2, schema.json), checker, simulation, setup plan, cost, explainer, guide
js/play/, js/results/a player's side of a live economy; results a server vouches for
js/approve/, js/mcp/, js/connect/the approval page, the MCP server and its tools, xsolana connect
js/sim/, js/test/LiteSVM running the real program; the tests and their pinned fixtures
bin/xsolana.mjsthe CLI
skills/, plugin/the skill (copied to plugin/skills, .claude/skills, .agents/skills) and the plugin
scripts/fixtures, skill sync, IDL sync, release manifest, a devnet end-to-end run
release.jsonthe program binary, IDL and client hashes this version is pinned to

Development

Node 22 or later.

bash
npm cinpm run fixtures   # downloads the loot program from devnet and the programs it calls from mainnet, each checked by hashnpm test           # every instruction the client builds, and every example's whole setup, against the real program in LiteSVMnpm run lint       # ESLintnpm run check      # fixtures, skill copies and release.json in step, lint, then the tests

Nothing in the tests deploys or spends SOL.

VariableWhat it does
XSOLANA_RPC_URLa devnet RPC of your own for xsolana approve and xsolana status (a mainnet URL is refused)
XSOLANA_NO_OPENxsolana approve prints its link without opening a browser
XSOLANA_DEBUGthe CLI prints a failure's whole stack, not one line
XSOLANA_PROGRAM_DIRthe tests run that program build's target/deploy/loot.so, and check the IDL against it
node bin/xsolana.mjs connect --local registers this checkout's MCP server and the skill with Claude Code and Codex
(--remove takes them out again).

After editing skills/, run npm run sync-skills. Changes to tool texts, the skill or the plugin are best measured with the evals before and after (evals/README.md). AGENTS.md has the rules for working in this repository, for people and coding agents alike.

Contributing

Issues and pull requests are welcome: see CONTRIBUTING.md. Please run npm run check before sending a change, and report a vulnerability privately as SECURITY.md describes.

License

Apache-2.0. See NOTICE and DISCLAIMER.md: provided as is, without warranty, at your own risk.

Source: README.md at commit 30826a2

Tools

10

xsolana_guide

Read this first whenever someone wants a web3 economy, game economy, token economy, NFT mechanic or onchain reward system: a shop, loot boxes or packs, gacha, a lottery or raffle, an auction (highest bid wins, the outbid refunded at once), staking or a farm, crafting or merging, seasons and emissions, a prediction pool or contest, quests and airdrops, holder-gated drops, using NFTs of any other collection in a game. loot is ONE shared Solana program (devnet until it is audited): the economy is a JSON spec, not a new smart contract, so never write Anchor/Rust for what it covers. Returns every part an economy can have (fields from the schema, who acts at play time, fees), how to write a spec, and what loot cannot do (with the nearest alternative). Pass `part` for one part with its nested shapes.

Parameterspart

xsolana_examples

Find an economy to start from. With `query` (the person’s own words, as they said them), returns the closest worked examples (whole specs that check and go live in the tests), the closest of 112 real or trending economies rated against loot (great / some / a-lot / cannot, with what carries it or what is missing), and what loot can’t do exactly in the ask, each with the nearest versions it can. Call it again with the words of any part that looks impossible: the answer is a nearest version to offer, not a dead end. With `name`, returns that example’s whole spec to copy and change. With neither, lists every example.

Parametersfitnamelimitquery

xsolana_check

Check an economy spec: refusals (each with a code, what it means and its fix) stop it from going live; warnings are what the person must hear (chance that pays money, revenue paid to stakers, an unfunded prize, a grant without limits, a mint’s powers). Run it after every change. Give the spec inline (`spec`), a file, or an example.

Parametersfilespecexample

xsolana_simulate

The quick simulation (expected values from the spec, instant): what each box, ticket and craft gives back against its price, the house edge, each pool’s money in and out per day and whether it runs dry, settles or grows, farm rewards per unit staked, what players, the treasury and the platform get each day. `scenario` overrides the spec’s own ({"perDay": {"box:flip": 1000}, "days": 30, "staked": {"<farm>": 1000}}). Quote its numbers; never your own arithmetic.

Parametersfilejsonspecexamplescenario

xsolana_cost

What going live costs (each account’s rent, the program’s fees, network fees, the seeds, the transactions and wallet approvals it takes) and what each action costs whoever signs it while it runs.

Parametersfilespecexample

xsolana_explain

The economy in plain words for the person: what players do and what it costs and is worth, how the pools fill and drain, what runs by itself, what the authority must sign, what going live costs, and what is flagged for the law. Tell them the essentials in a few lines, from this text.

Parametersfilespecexample

xsolana_save

Save a spec into the project (default xsolana.json), only if it checks. A file that is already live keeps its program numbers and its live section. Never put a key in it: the checker refuses one.

Parametersfilespecrequired

xsolana_publish

When the person says to put it live: returns what going live does (every step, in order, and its cost) and the one command they run themselves to approve it in their own wallet (`npx -y @xgamesfun/[email protected] approve`, pinned to this exact version: give it as it is): it opens a local page where they connect a devnet wallet and approve each transaction. You never sign, never ask for a key, and never run the approval for them.

Parametersfilespecexample

xsolana_status

A live economy as it is on chain: the project, every pool’s balance, every record the spec names (found or missing). Reads devnet (or XSOLANA_RPC_URL).

Parametersfile

xsolana_client

How an app (a game, a site, a bot) uses a live economy: the program’s address and cluster, the npm package and IDL, and the calls a page makes with the player’s own wallet (open a box, buy, stake, craft, enter, claim). Use this instead of writing chain code from memory.

Takes no parameters.

Version history

1
  1. v0.20.1LatestOct 30, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts