@xgamesfun/solana 0.25.3 → 0.25.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +145 -228
- package/package.json +1 -1
- package/skills/xsolana-economy/SKILL.md +3 -3
package/README.md
CHANGED
|
@@ -1,96 +1,52 @@
|
|
|
1
|
-
# solana-kit
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
>
|
|
19
|
-
>
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
named), lottery draws, auction ends, refunds (anyone), contest results (the authority or its deciders) and schedule
|
|
51
|
-
runs (the project's keys). A run nobody sends on time is missed, except a sealed schedule's fixed amount. Apps built
|
|
52
|
-
with `@xgamesfun/solana/play` send the steps a player needs. Don't count on a hosted keeper.
|
|
53
|
-
- **The rules are strict.** A prize is a fixed amount: a jackpot that grows is a lottery's pot. A lottery says where its
|
|
54
|
-
places are paid from: a pot that carries over (gifts and what earlier rounds left count), or each round's own ticket
|
|
55
|
-
money, which nothing from outside can change. A prize never shifts to a later round. A draw uses the odds
|
|
56
|
-
as written. When an outcome runs out, a box either stops selling (`stopSales`, the default) or keeps selling and
|
|
57
|
-
draws among what's left (`drawLeft`, which lets a player empty a common outcome to make a rare one likelier).
|
|
58
|
-
- **Chance comes from an oracle.** MagicBlock's VRF answers every random roll and draw. If it stops answering, rolls wait. An
|
|
59
|
-
order still unanswered after 7 days can be refunded. Once a roll has waited 10 minutes, a buyer who sees a late
|
|
60
|
-
answer coming can take a refund instead.
|
|
61
|
-
- **Fees and rent.** The platform sets two flat fees: by default 0.002 SOL a player action and 0.00001 SOL a project
|
|
62
|
-
action. Each is capped at 0.01 SOL, and a raise waits 7 days. Accounts cost rent: going live, and each settle that
|
|
63
|
-
opens or mints something. `xsolana cost` gives the totals. The platform can suspend purchases, but it never stops
|
|
64
|
-
payouts, refunds or unstakes (the one exception is a recipe that charges).
|
|
65
|
-
- **Some things aren't built,** and some limits are kept by design. Read
|
|
66
|
-
[Known limits](docs/program.md#known-limits) before promising players something unusual.
|
|
67
|
-
- **The law is yours to check.** The checker's legal flags (chance at money, resellable random items, revenue
|
|
68
|
-
sharing) are reminders, not advice. A spec with no flag isn't therefore legal.
|
|
69
|
-
|
|
70
|
-
## What an economy can be made of
|
|
71
|
-
|
|
72
|
-
- payments and splits, in tokens or with an NFT
|
|
73
|
-
- shops (a purchase in one transaction) and loot boxes
|
|
74
|
-
- pools and timed schedules, sealed or not
|
|
75
|
-
- lotteries and raffles, including no-loss lotteries
|
|
76
|
-
- prizes of any kind on every route, random or not: items, tokens, and NFTs the project holds in a stash
|
|
77
|
-
- an NFT as the price on every route that takes money
|
|
78
|
-
- staking farms with lock tiers, boosts, early exits, fixed or shared rates and terms
|
|
79
|
-
- crafting recipes
|
|
80
|
-
- holds and contests, with prizes by rank or by stake
|
|
81
|
-
- auctions: the highest bid wins, the outbid refunded at once
|
|
82
|
-
- listings for sale or rent, and bids and loans between players
|
|
83
|
-
- perks, staking and holds for any NFT, whether the project has authority over it or not
|
|
84
|
-
- allowlists of any size (a Merkle list) on every gated route
|
|
85
|
-
- capped rewards and grants that a server vouches for
|
|
86
|
-
- rules on what a collectible says
|
|
87
|
-
|
|
88
|
-
Every move leaves a public receipt. [`docs/program.md`](docs/program.md) describes how the program behaves.
|
|
89
|
-
|
|
90
|
-
## Use it from an AI coding agent
|
|
91
|
-
|
|
92
|
-
The MCP server and the skill let Claude Code, Codex or any MCP agent turn a one-line idea into a checked, simulated
|
|
93
|
-
economy and hand you the command that puts it live in your own wallet.
|
|
1
|
+
# solana-kit
|
|
2
|
+
|
|
3
|
+
**Build loot boxes, shops, lotteries, auctions, NFT staking and rewards on Solana without writing a smart contract.**
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@xgamesfun/solana)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
[](#good-to-know)
|
|
8
|
+
[](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.XGamesFun/solana-kit)
|
|
9
|
+
|
|
10
|
+
You describe your game's or community's economy in a small JSON file: what players buy, open, stake, win or craft.
|
|
11
|
+
The tools check it, show you where the money goes, tell you what it costs, and then you put it live by approving it in
|
|
12
|
+
your own wallet. It runs on **loot**, one Solana program that every project shares, so there is no Anchor or Rust to
|
|
13
|
+
write, deploy or audit yourself.
|
|
14
|
+
|
|
15
|
+
Most people never touch the JSON: they ask an AI agent (Claude Code, Codex, Cursor, ChatGPT or Claude) for _"a fishing
|
|
16
|
+
game where each cast costs 0.02 SOL, with a rare golden fish and a monthly draw"_ and the agent does the rest.
|
|
17
|
+
|
|
18
|
+
> **Devnet only for now.** The program is not yet independently audited, so nothing here is for real money. The
|
|
19
|
+
> tools are provided as is: read [DISCLAIMER.md](DISCLAIMER.md) before you use them.
|
|
20
|
+
|
|
21
|
+
## What you can build
|
|
22
|
+
|
|
23
|
+
| Build | For example |
|
|
24
|
+
| ----------------------------- | -------------------------------------------------------------------------------- |
|
|
25
|
+
| **Shops** | A potion for 0.01 SOL, a skin paid in your own token, an item that costs an NFT |
|
|
26
|
+
| **Loot boxes, gacha, packs** | A crate with a 1% legendary, a five-card pack with a guaranteed rare, gacha pity |
|
|
27
|
+
| **Lotteries and raffles** | A weekly draw, a no-loss lottery, a raffle for an NFT with an allowlist |
|
|
28
|
+
| **Auctions** | Highest bid wins, and anyone outbid gets their money back at once |
|
|
29
|
+
| **NFT staking** | Lock tiers and boosts, for your collection or any collection you didn't mint |
|
|
30
|
+
| **Crafting** | Burn three common gems to forge a rare one |
|
|
31
|
+
| **Contests and predictions** | Pick a side, prizes by rank or by stake |
|
|
32
|
+
| **Rewards, quests, airdrops** | Capped rewards your game's server vouches for, daily chests, holder-only drops |
|
|
33
|
+
| **Trading between players** | Listings for sale or rent, offers, and loans against an NFT |
|
|
34
|
+
|
|
35
|
+
Every move leaves a public receipt on chain. Random rolls come from MagicBlock's verifiable randomness.
|
|
36
|
+
|
|
37
|
+
## How it works
|
|
38
|
+
|
|
39
|
+
1. **Describe it.** In a sentence to your agent, or as a spec file (`xsolana.json`).
|
|
40
|
+
2. **Check it.** `check` refuses anything the program would refuse; `simulate` shows where the money goes, day by
|
|
41
|
+
day; `cost` prices going live and each player action; `review` shows what a cheater could get.
|
|
42
|
+
3. **Approve it.** A page opens on your own computer, lists every transaction, and you approve them in your wallet.
|
|
43
|
+
Nothing here ever signs for you or asks for a key.
|
|
44
|
+
|
|
45
|
+
New here? The [loot box tutorial](docs/tutorial-loot-box.md) walks through all three with real output.
|
|
46
|
+
|
|
47
|
+
## Get started
|
|
48
|
+
|
|
49
|
+
### With an AI agent
|
|
94
50
|
|
|
95
51
|
**Claude Code**
|
|
96
52
|
|
|
@@ -106,165 +62,126 @@ codex plugin marketplace add XGamesFun/solana-kit
|
|
|
106
62
|
codex plugin add xsolana@xgamesfun
|
|
107
63
|
```
|
|
108
64
|
|
|
109
|
-
**
|
|
110
|
-
by URL). It is the hosted server (below, "Over HTTP"): nothing to install, and going live stays your own approval on your
|
|
111
|
-
computer. More at [xgames.fun/solana](https://xgames.fun/solana).
|
|
65
|
+
**claude.ai, ChatGPT or Claude Desktop:** add `https://xgames.fun/mcp` as a custom connector. Nothing to install.
|
|
112
66
|
|
|
113
|
-
**
|
|
114
|
-
`npx -y --package=@xgamesfun/solana@0.25.3 xsolana mcp`. Or let `npx -y @xgamesfun/solana@0.25.3 connect` register it, with
|
|
115
|
-
the skill, for Claude Code and Codex.
|
|
67
|
+
**Cursor, Cline, opencode or any MCP client:** run `npx -y --package=@xgamesfun/solana@0.25.4 xsolana mcp`.
|
|
116
68
|
|
|
117
|
-
**
|
|
118
|
-
opencode…): `npx skills add XGamesFun/solana-kit` finds it and installs it for the agents you have. Without the MCP
|
|
119
|
-
server it runs the same tools through `npx`. Each GitHub release also carries `xsolana-economy.zip`, the skill as one
|
|
120
|
-
file for apps that take a skill as an upload (the Claude and ChatGPT desktop apps).
|
|
69
|
+
**Any agent that reads skills** (Copilot, Gemini CLI, Windsurf…): `npx skills add XGamesFun/solana-kit`.
|
|
121
70
|
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
`http://127.0.0.1:8787/mcp`, MCP's Streamable HTTP transport. `@xgamesfun/solana/mcp/http` exports the same handler
|
|
125
|
-
(`mcpHttp(request) → response`) for a hosted endpoint: it reads no files, and the agent hands the person the spec and the
|
|
126
|
-
`approve` command to go live.
|
|
71
|
+
Then ask for the economy you want. More ways in, such as the skill as a zip for desktop apps or the server over HTTP,
|
|
72
|
+
are in [docs/harnesses.md](docs/harnesses.md).
|
|
127
73
|
|
|
128
|
-
|
|
129
|
-
monthly draw"_.
|
|
74
|
+
### From a terminal
|
|
130
75
|
|
|
131
|
-
|
|
132
|
-
|
|
76
|
+
```bash
|
|
77
|
+
# find a worked example close to your idea
|
|
78
|
+
npx -y @xgamesfun/solana@0.25.4 examples shop with loot boxes
|
|
133
79
|
|
|
134
|
-
|
|
80
|
+
# does it work? where does the money go? what does it cost?
|
|
81
|
+
npx -y @xgamesfun/solana@0.25.4 check xsolana.json
|
|
82
|
+
npx -y @xgamesfun/solana@0.25.4 simulate xsolana.json
|
|
83
|
+
npx -y @xgamesfun/solana@0.25.4 cost xsolana.json
|
|
135
84
|
|
|
136
|
-
|
|
85
|
+
# the whole economy in plain words, and what a cheater could get
|
|
86
|
+
npx -y @xgamesfun/solana@0.25.4 explain xsolana.json
|
|
87
|
+
npx -y @xgamesfun/solana@0.25.4 review xsolana.json
|
|
137
88
|
|
|
138
|
-
|
|
139
|
-
npx -y @xgamesfun/solana@0.25.
|
|
140
|
-
npx -y @xgamesfun/solana@0.25.3 check xsolana.json # refusals and warnings
|
|
141
|
-
npx -y @xgamesfun/solana@0.25.3 simulate xsolana.json # where the money goes, day by day
|
|
142
|
-
npx -y @xgamesfun/solana@0.25.3 cost xsolana.json # what going live and each action cost
|
|
143
|
-
npx -y @xgamesfun/solana@0.25.3 explain xsolana.json # the economy in plain words
|
|
144
|
-
npx -y @xgamesfun/solana@0.25.3 review xsolana.json # what a cheater gets on each route (exits 1 on a high finding)
|
|
145
|
-
npx -y @xgamesfun/solana@0.25.3 approve xsolana.json # go live, approved in your own wallet
|
|
89
|
+
# go live, approved in your own wallet
|
|
90
|
+
npx -y @xgamesfun/solana@0.25.4 approve xsolana.json
|
|
146
91
|
```
|
|
147
92
|
|
|
148
|
-
|
|
149
|
-
is newest under the name.
|
|
93
|
+
Each command names an exact version, so you always run the release you meant to. `xsolana help` lists them all.
|
|
150
94
|
|
|
151
|
-
|
|
95
|
+
### In your app
|
|
152
96
|
|
|
153
97
|
```bash
|
|
154
98
|
npm install @xgamesfun/solana
|
|
155
99
|
```
|
|
156
100
|
|
|
157
101
|
```js
|
|
158
|
-
import
|
|
159
|
-
const ix = loot.openBoxIx({ player, project, box, nonce }); // one builder per instruction, no Solana SDK
|
|
160
|
-
```
|
|
102
|
+
import { solanaApp, walletStandardSigner } from '@xgamesfun/solana/play';
|
|
161
103
|
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
side: `sponsorSigner` dry-runs and checks every transaction before it signs, under the project's own per-player budget.
|
|
165
|
-
|
|
166
|
-
Building on `@solana/kit`? `loot.toKitInstruction(ix)` gives any builder's instruction in Kit's shape
|
|
167
|
-
(`{ programAddress, accounts, data }`), and `loot.fromKitInstruction` turns one back.
|
|
168
|
-
|
|
169
|
-
| Import | What |
|
|
170
|
-
| -------------------------------- | ------------------------------------------------------------------------------------------- |
|
|
171
|
-
| `@xgamesfun/solana` | the economy tools: `check`, `simulate`, `plan`, `cost`, `explainEconomy`, `review`, `model` |
|
|
172
|
-
| `@xgamesfun/solana/client` | every PDA, one builder per instruction, account and receipt decoders, grant vouchers |
|
|
173
|
-
| `@xgamesfun/solana/play` | `solanaApp`: what a player does with a live economy, from a browser app |
|
|
174
|
-
| `@xgamesfun/solana/results` | results and vouchers a game's server signs |
|
|
175
|
-
| `@xgamesfun/solana/chain/*` | browser-safe Solana primitives: base58, Borsh, transactions, PDAs, tokens, Core |
|
|
176
|
-
| `@xgamesfun/solana/idl.json` | the program's IDL, the authority for account and argument layouts |
|
|
177
|
-
| `@xgamesfun/solana/release.json` | the program build, IDL and client this release is pinned to |
|
|
178
|
-
|
|
179
|
-
The client, chain and play modules run in browsers and Node 22 or later, with no bundler required. The package
|
|
180
|
-
ships TypeScript declarations for every entry point.
|
|
181
|
-
|
|
182
|
-
## Questions people ask
|
|
183
|
-
|
|
184
|
-
**How do I make a loot box, gacha or pack opening on Solana without writing a smart contract?** Describe it as a box
|
|
185
|
-
in a spec (its price, its outcomes and their odds, what each one pays), run `xsolana check` and `xsolana simulate`, then
|
|
186
|
-
approve it in your wallet with `xsolana approve`. Rolls come from MagicBlock's VRF, and a buyer is refunded if the
|
|
187
|
-
oracle never answers. [`examples/`](examples) has whole worked economies.
|
|
188
|
-
|
|
189
|
-
**How do I add staking to an NFT collection, even one I didn't mint?** A staking farm takes any collection, with lock
|
|
190
|
-
tiers, boosts and fixed or shared reward rates. The project needs no authority over the NFTs: see
|
|
191
|
-
[`docs/nfts.md`](docs/nfts.md).
|
|
192
|
-
|
|
193
|
-
**Can I run a lottery, raffle or auction on Solana without deploying a program?** Yes: lotteries (including no-loss
|
|
194
|
-
ones), raffles with a Merkle allowlist, and auctions that refund the outbid at once are all routes in the same spec.
|
|
195
|
-
|
|
196
|
-
**Is there an MCP server or Claude Code plugin for building on Solana?** Yes: the `xsolana` plugin for Claude Code and
|
|
197
|
-
Codex, the hosted server at `https://xgames.fun/mcp` for chat apps, and `npx -y --package=@xgamesfun/solana@0.25.3 xsolana mcp` for any MCP client. It is listed in the MCP
|
|
198
|
-
Registry as `io.github.XGamesFun/solana-kit`.
|
|
199
|
-
|
|
200
|
-
**How is this different from writing my own Anchor program?** Nothing is written, deployed or upgraded per project:
|
|
201
|
-
every project's rules are checked by the one program, and its tests run every instruction against that program in
|
|
202
|
-
LiteSVM. The trade-off is that an economy can only be what the spec can say ([known limits](docs/program.md#known-limits)).
|
|
203
|
-
|
|
204
|
-
**Does it run on mainnet?** Not yet: devnet only until the program is independently audited.
|
|
205
|
-
|
|
206
|
-
## Documentation
|
|
207
|
-
|
|
208
|
-
| | |
|
|
209
|
-
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
|
|
210
|
-
| [`docs/tutorial-loot-box.md`](docs/tutorial-loot-box.md) | a loot box from one sentence to going live, step by step |
|
|
211
|
-
| [`docs/program.md`](docs/program.md) | the program: who signs, accounts, every instruction, fees, limits, receipts, costs |
|
|
212
|
-
| [`docs/nfts.md`](docs/nfts.md) | NFTs and tokens, with and without the project's authority |
|
|
213
|
-
| [`docs/harnesses.md`](docs/harnesses.md) | how the plugin reaches Claude Code and Codex, and the release checklist |
|
|
214
|
-
| [`skills/xsolana-economy`](skills/xsolana-economy/SKILL.md) | the skill an agent follows |
|
|
215
|
-
| [`trust-and-cheating.md`](skills/xsolana-economy/references/trust-and-cheating.md) | what a server decides, replays or bounds; who gets paid; an exploit checklist |
|
|
216
|
-
| [`examples/`](examples) | whole economies that check and go live in the tests; `ideas.json`, 112 real economies rated |
|
|
217
|
-
| [`evals/`](evals/README.md) | fresh-session evals of agents building on loot |
|
|
218
|
-
| [`CHANGELOG.md`](CHANGELOG.md), [`SECURITY.md`](SECURITY.md) | versions, the trust model, reporting a vulnerability |
|
|
219
|
-
|
|
220
|
-
## Layout
|
|
221
|
-
|
|
222
|
-
| Path | What |
|
|
223
|
-
| --------------------------------------- | ---------------------------------------------------------------------------------------------------- |
|
|
224
|
-
| `js/chain/` | browser-safe Solana primitives, no SDK |
|
|
225
|
-
| `js/client/` | the client; `idl/` is the program's IDL |
|
|
226
|
-
| `js/economy/` | the economy spec (version 2, `schema.json`), checker, simulation, setup plan, cost, explainer, guide |
|
|
227
|
-
| `js/play/`, `js/results/` | a player's side of a live economy; results a server vouches for |
|
|
228
|
-
| `js/approve/`, `js/mcp/`, `js/connect/` | the approval page, the MCP server and its tools, `xsolana connect` |
|
|
229
|
-
| `js/sim/`, `js/test/` | LiteSVM running the real program; the tests and their pinned fixtures |
|
|
230
|
-
| `bin/xsolana.mjs` | the CLI |
|
|
231
|
-
| `skills/`, `plugin/` | the skill (copied to `plugin/skills`, `.claude/skills`, `.agents/skills`) and the plugin |
|
|
232
|
-
| `scripts/` | fixtures, skill sync, IDL sync, release manifest, a devnet end-to-end run |
|
|
233
|
-
| `release.json` | the program binary, IDL and client hashes this version is pinned to |
|
|
234
|
-
|
|
235
|
-
## Development
|
|
236
|
-
|
|
237
|
-
Node 22 or later.
|
|
104
|
+
// spec: your live xsolana.json; wallet: the player's own (Phantom, Solflare, Backpack…)
|
|
105
|
+
const app = solanaApp({ spec, wallet: walletStandardSigner(wallet, account) });
|
|
238
106
|
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
npm test # every instruction the client builds, and every example's whole setup, against the real program in LiteSVM
|
|
243
|
-
npm run lint # ESLint and Prettier (npm run format fixes the formatting)
|
|
244
|
-
npm run check # fixtures, skill copies and release.json in step, lint, then the tests
|
|
107
|
+
// the player sees the price, then approves the purchase in their wallet
|
|
108
|
+
const shop = await app.shop();
|
|
109
|
+
await app.buy('potion', { listing: shop.find(item => item.key === 'potion') });
|
|
245
110
|
```
|
|
246
111
|
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
|
252
|
-
|
|
|
253
|
-
| `
|
|
254
|
-
|
|
|
255
|
-
| `
|
|
256
|
-
|
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
112
|
+
No Solana SDK needed: it runs in the browser and in Node 22 or later, with TypeScript types included. The player
|
|
113
|
+
module covers buying, opening boxes, staking, crafting, tickets, bids and claims;
|
|
114
|
+
[apps.md](skills/xsolana-economy/references/apps.md) shows a whole page.
|
|
115
|
+
|
|
116
|
+
| Import | What it gives you |
|
|
117
|
+
| -------------------------------- | ------------------------------------------------------------------------------------- |
|
|
118
|
+
| `@xgamesfun/solana/play` | everything a player does with a live economy, from a web page |
|
|
119
|
+
| `@xgamesfun/solana/client` | one builder per instruction, every address, account and receipt decoders |
|
|
120
|
+
| `@xgamesfun/solana/sponsor` | your server pays players' fees (never their price), so players with no SOL can play |
|
|
121
|
+
| `@xgamesfun/solana/results` | results and vouchers your game's server signs |
|
|
122
|
+
| `@xgamesfun/solana` | the tools themselves: `check`, `simulate`, `cost`, `review`, `explainEconomy`, `plan` |
|
|
123
|
+
| `@xgamesfun/solana/mcp/http` | the MCP server as a web handler, to host it yourself |
|
|
124
|
+
| `@xgamesfun/solana/chain/*` | small browser-safe Solana building blocks: base58, Borsh, transactions, tokens, Core |
|
|
125
|
+
| `@xgamesfun/solana/idl.json` | the program's IDL |
|
|
126
|
+
| `@xgamesfun/solana/release.json` | the exact program build this release is for |
|
|
127
|
+
|
|
128
|
+
Using `@solana/kit`? `loot.toKitInstruction(ix)` turns any builder's instruction into Kit's shape.
|
|
129
|
+
|
|
130
|
+
## Good to know
|
|
131
|
+
|
|
132
|
+
- **Devnet only, not yet audited.** Use a devnet wallet. Mainnet waits for an independent audit.
|
|
133
|
+
- **Upgrades can mean setting up again.** No program version so far has carried accounts over. Pin the package version.
|
|
134
|
+
- **Players trust the project.** Your keys can mint and move your project's pools. The program protects players from
|
|
135
|
+
each other and from mistakes, not from the project they chose.
|
|
136
|
+
- **The chain can't see your game.** Wins and scores are vouched for by your server; checking that a player really did
|
|
137
|
+
it is your job. `review` shows what a cheater gets on each route.
|
|
138
|
+
- **Nothing runs by itself.** Draws, settles and schedule runs are sent by someone, usually your app.
|
|
139
|
+
- **Fees:** 0.002 SOL per player action and 0.00001 SOL per project action, plus rent. `cost` gives the totals.
|
|
140
|
+
|
|
141
|
+
The full list, with the details behind each, is in [Before you use it](docs/before-you-use.md). Some things aren't
|
|
142
|
+
built yet: read the [known limits](docs/program.md#known-limits) before promising players something unusual.
|
|
143
|
+
|
|
144
|
+
## Questions
|
|
145
|
+
|
|
146
|
+
**How do I make a loot box or gacha on Solana without writing a smart contract?** Describe it as a box (its price,
|
|
147
|
+
its outcomes and their odds), run `check` and `simulate`, then `approve` it in your wallet. If the randomness oracle
|
|
148
|
+
never answers, the buyer can get a refund. See the [tutorial](docs/tutorial-loot-box.md) and the
|
|
149
|
+
[examples](examples).
|
|
150
|
+
|
|
151
|
+
**Can I add staking to an NFT collection I didn't mint?** Yes. A staking farm takes any collection, with lock tiers,
|
|
152
|
+
boosts and reward rates, and needs no authority over the NFTs. See [NFTs and tokens](docs/nfts.md).
|
|
153
|
+
|
|
154
|
+
**Can I run a lottery, raffle or auction without deploying a program?** Yes: lotteries (no-loss ones too), raffles
|
|
155
|
+
with allowlists, and auctions that refund the outbid at once are all part of the same spec.
|
|
156
|
+
|
|
157
|
+
**Is there an MCP server or Claude Code plugin for this?** Yes: the `xsolana` plugin for Claude Code and Codex, the
|
|
158
|
+
hosted server at `https://xgames.fun/mcp`, and the local server for any MCP client. It's in the MCP Registry as
|
|
159
|
+
`io.github.XGamesFun/solana-kit`.
|
|
160
|
+
|
|
161
|
+
**How is this different from writing my own Anchor program?** Nothing is written or deployed per project: one shared
|
|
162
|
+
program enforces every project's rules, and it is tested instruction by instruction. The trade-off is that you can
|
|
163
|
+
build what the spec can describe, which is a lot, but not everything.
|
|
164
|
+
|
|
165
|
+
**Can players with no SOL play?** Yes, if you sponsor their fees from your own server
|
|
166
|
+
(`@xgamesfun/solana/sponsor`). They still pay any price themselves.
|
|
167
|
+
|
|
168
|
+
## Learn more
|
|
169
|
+
|
|
170
|
+
- [Loot box tutorial](docs/tutorial-loot-box.md): one sentence to going live, step by step
|
|
171
|
+
- [Examples](examples): whole economies that are checked and put live in the tests
|
|
172
|
+
- [How the program works](docs/program.md): who signs, every instruction, fees, limits, receipts
|
|
173
|
+
- [NFTs and tokens](docs/nfts.md): with and without the project's authority
|
|
174
|
+
- [Trust and cheating](skills/xsolana-economy/references/trust-and-cheating.md): what your server must check
|
|
175
|
+
- [The agent skill](skills/xsolana-economy/SKILL.md): what an AI agent follows to build an economy
|
|
176
|
+
- [Agents and harnesses](docs/harnesses.md): every way to reach the tools, and how releases are made
|
|
177
|
+
- [Changelog](CHANGELOG.md) · [Security](SECURITY.md) · [xgames.fun/solana](https://xgames.fun/solana)
|
|
261
178
|
|
|
262
179
|
## Contributing
|
|
263
180
|
|
|
264
|
-
Issues and pull requests are welcome
|
|
265
|
-
|
|
181
|
+
Issues and pull requests are welcome. [CONTRIBUTING.md](CONTRIBUTING.md) has the setup (`npm ci`, `npm run fixtures`,
|
|
182
|
+
`npm run check`), the repository's layout and how to send a change. Report a vulnerability privately, as
|
|
183
|
+
[SECURITY.md](SECURITY.md) describes.
|
|
266
184
|
|
|
267
185
|
## License
|
|
268
186
|
|
|
269
|
-
[Apache-2.0](LICENSE). See [NOTICE](NOTICE) and [DISCLAIMER.md](DISCLAIMER.md)
|
|
270
|
-
own risk.
|
|
187
|
+
[Apache-2.0](LICENSE). See [NOTICE](NOTICE) and [DISCLAIMER.md](DISCLAIMER.md).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@xgamesfun/solana",
|
|
3
|
-
"version": "0.25.
|
|
3
|
+
"version": "0.25.4",
|
|
4
4
|
"mcpName": "io.github.XGamesFun/solana-kit",
|
|
5
5
|
"description": "Loot boxes, gacha, shops, lotteries, auctions, NFT staking, crafting and rewards on Solana without writing a smart contract: one shared program, its JS client, a CLI, and an MCP server and skill so Claude Code, Codex or any AI agent can design, check, simulate and launch an economy.",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -9,8 +9,8 @@ An economy is one JSON spec (`xsolana.json` in the project) on **loot**, a Solan
|
|
|
9
9
|
writes or deploys a contract: the spec is checked, simulated and priced by the `xsolana_*` tools, and the project's
|
|
10
10
|
owner puts it live by approving in their own wallet. It runs on **devnet** until the program is audited.
|
|
11
11
|
|
|
12
|
-
The tools are the `xsolana_*` MCP tools. Without MCP, the same from a terminal: `npx -y @xgamesfun/solana@0.25.
|
|
13
|
-
or `npx -y @xgamesfun/solana@0.25.
|
|
12
|
+
The tools are the `xsolana_*` MCP tools. Without MCP, the same from a terminal: `npx -y @xgamesfun/solana@0.25.4 <guide|examples|check|simulate|cost|explain|review|publish|status> [xsolana.json]`,
|
|
13
|
+
or `npx -y @xgamesfun/solana@0.25.4 tool <name> '<json>'` for any tool (always with the exact version).
|
|
14
14
|
|
|
15
15
|
## Rules (always)
|
|
16
16
|
|
|
@@ -113,7 +113,7 @@ or `npx -y @xgamesfun/solana@0.25.3 tool <name> '<json>'` for any tool (always w
|
|
|
113
113
|
level would cost. Run it again after every change that touches a route that pays.
|
|
114
114
|
9. **When they say "put it live"**: `xsolana_publish` lists every step and its cost and gives the command. Tell them to
|
|
115
115
|
run it themselves in the project folder, exactly as `xsolana_publish` gives it (it names the exact version:
|
|
116
|
-
`npx -y @xgamesfun/solana@0.25.
|
|
116
|
+
`npx -y @xgamesfun/solana@0.25.4 approve xsolana.json`; never drop the version). It opens a page on their computer where
|
|
117
117
|
they connect a devnet wallet and approve; what lands is written back into `xsolana.json`. You publish nothing.
|
|
118
118
|
10. **After it is live**: `xsolana_status` shows each part on chain; read it before acting on what the person says
|
|
119
119
|
happened. A later change is the same loop: save, publish, and the approval sends only what changed. What only the
|