xsolana

solana-kit

为 loot 提供的工具。loot 是一个供游戏和社区经济使用的共享 Solana 程序。本仓库是 npm 包 @xgamesfun/solana：

• 一个不依赖 Solana SDK 的 JavaScript 客户端（@xgamesfun/solana/client）、供应用使用的玩家模块（/play），以及一个结果客户端（/results）；
• 经济规范及其检查器、快速模拟、成本说明和通俗易懂的解释；
• xsolana CLI，以及包含十个 xsolana_* 工具的 MCP 服务；
• xsolana-economy 技能，以及一个将这些工具和技能带给 Claude Code 和 Codex 的插件；
• 一个本地审批页面，供项目所有者使用自己的钱包批准上线。

经济由 JSON 规范定义，而不是新智能合约。所有项目共用同一个程序，任何项目都不会编写自己的程序。

状态： loot 0.22.0，程序 ID 为 9cwqM1TXytPnFZsLfmUyv2dg4uW6Ch9C6UJVPns7NFQ，仅支持 devnet。该程序尚未经过独立审计，在完成审计前不会在 mainnet 上运行任何内容。请参阅 SECURITY.md。

免责声明： 本软件按原样提供，不作任何保证，也不保证该程序或工具安全。使用风险由你自行承担；你有责任为自己批准的每笔交易负责，并确保你构建的内容在运行所在地合法。本文内容不构成法律或财务建议。使用前请阅读 DISCLAIMER.md。

经济可以包含哪些内容

• 支付和分成，可以使用代币或 NFT
• 商店（一次交易即可完成购买）和盲盒
• 池和定时计划，可以密封，也可以不密封
• 彩票和抽奖，包括无损彩票
• 每条路线都可以提供任意类型的奖品，无论是否随机：项目存放在储备中的物品、代币和 NFT
• 每条接受金钱的路线都可以将 NFT 作为价格
• 质押农场，支持锁定等级、加成、提前退出和通行费
• 合成配方
• 持有和竞赛，奖品可按排名或质押金额发放
• 拍卖：最高出价者获胜，被超出的出价立即退还
• 出售或出租的挂单，以及玩家之间的出价和贷款
• 为任何 NFT 提供特权、质押和持有机制，无论项目是否拥有其控制权
• 在每条受限路线中使用任意规模的允许名单（Merkle 列表）
• 由服务器担保的封顶奖励和赠款
• 关于收藏品描述内容的规则

每个操作都会留下公开收据。docs/program.md 说明了程序的行为。

通过 AI 编码 Agent 使用

MCP 服务和技能可让 Claude Code、Codex 或任何 MCP Agent 将一句话的想法转化为经过检查和模拟的经济方案，并提供一条命令，让你用自己的钱包将其上线。

Claude Code

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

Codex

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

任何支持 MCP 的 Agent（Cursor、opencode、Cline……）：运行服务 npx -y --package=@xgamesfun/[email protected] xsolana mcp。也可以运行 npx -y @xgamesfun/[email protected] connect，为 Claude Code 和 Codex 注册服务及技能。

然后提出经济方案，例如 “一个钓鱼游戏，每次抛竿花费 0.02 SOL，有一种稀有的金色鱼，并且每月抽奖一次”。

上线始终由你决定：npx -y @xgamesfun/[email protected] approve 会在你的电脑上打开一个页面，你可以在其中连接 devnet 钱包并逐笔批准交易。Agent 绝不会签名，也不会索要密钥。

在终端中使用

每个工具也可以通过 CLI 运行，并使用规范文件（默认为 xsolana.json）：

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

xsolana help 会列出所有命令。每条命令都会指定确切版本，因此 npx 会运行该版本，而不会运行同名的最新版本。

在代码中使用

npm install @xgamesfun/solana

import * as loot from '@xgamesfun/solana/client';
const ix = loot.openBoxIx({ player, project, box, nonce }); // one builder per instruction, no Solana SDK

导入项	说明
@xgamesfun/solana	经济系统工具：check、simulate、plan、cost、explainEconomy、model
@xgamesfun/solana/client	所有 PDA、每条指令对应的一个构建器、账户和收据解码器、授权凭证
@xgamesfun/solana/play	solanaApp：玩家在浏览器应用中与运行中的经济系统交互的方式
@xgamesfun/solana/results	游戏服务器签署的结果和凭证
@xgamesfun/solana/chain/*	浏览器安全的 Solana 基础组件：base58、Borsh、交易、PDA、代币、Core
@xgamesfun/solana/idl.json	程序的 IDL，是账户和参数布局的权威来源
@xgamesfun/solana/release.json	此版本固定使用的程序构建版本、IDL 和客户端

client、chain 和 play 模块可在浏览器以及 Node 22 或更高版本中运行，无需打包工具。该软件包为每个入口点 都提供 TypeScript 声明。

文档

docs/program.md	程序：签名者、账户、每条指令、费用、限制、收据、成本
docs/nfts.md	NFT 和代币，包括使用和不使用项目授权的情况
docs/harnesses.md	插件如何接入 Claude Code 和 Codex，以及发布检查清单
skills/xsolana-economy	Agent 遵循的技能
examples/	可在测试中通过检查并上线的完整经济系统；ideas.json 中有 112 个经过评估的真实经济系统
evals/	Agent 基于 loot 构建功能时的新会话评估
CHANGELOG.md、SECURITY.md	版本、信任模型、漏洞报告方式

目录结构

路径	说明
js/chain/	浏览器安全的 Solana 基础组件，无需 SDK
js/client/	客户端；idl/ 是程序的 IDL
js/economy/	经济系统规范（版本 2，schema.json）、检查器、模拟、设置计划、成本、说明器、指南
js/play/、js/results/	运行中经济系统的玩家端；服务器背书的结果
js/approve/、js/mcp/、js/connect/	审批页面、MCP 服务及其工具、xsolana connect
js/sim/、js/test/	运行真实程序的 LiteSVM；测试及其固定夹具
bin/xsolana.mjs	CLI
skills/、plugin/	技能（复制到 plugin/skills、.claude/skills、.agents/skills）和插件
scripts/	夹具、技能同步、IDL 同步、发布清单、devnet 端到端运行
release.json	此版本固定使用的程序二进制文件、IDL 和客户端哈希

开发

Node 22 或更高版本。

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

测试不会部署程序，也不会花费 SOL。

变量	作用
XSOLANA_RPC_URL	供 xsolana approve 和 xsolana status 使用的自有 devnet RPC（不接受 mainnet URL）
XSOLANA_NO_OPEN	xsolana approve 仅打印链接，不打开浏览器
XSOLANA_DEBUG	CLI 输出完整的失败堆栈，而非单行信息
XSOLANA_PROGRAM_DIR	测试运行该程序构建目录中的 target/deploy/loot.so，并检查 IDL 是否与之匹配
运行 node bin/xsolana.mjs connect --local，即可向 Claude Code 和 Codex 注册此代码库的 MCP 服务和技能
（运行 --remove 可将它们移除）。

编辑 skills/ 后，运行 npm run sync-skills。工具文本、技能或插件的更改，最好通过前后运行评估来衡量 （evals/README.md）。AGENTS.md 列出了在此代码库中工作的规则，适用于人员和编码 Agent。

贡献

欢迎提交问题和拉取请求：请参阅 CONTRIBUTING.md。提交更改前请运行 npm run check， 并按照 SECURITY.md 中的说明私下报告漏洞。

许可证

Apache-2.0。请参阅 NOTICE 和 DISCLAIMER.md：按原样提供，不作任何保证，使用风险由您自行承担。