xsolana

solana-kit

loot向けのツールです。lootは、ゲームやコミュニティの経済向けの共有Solanaプログラムです。このリポジトリはnpm パッケージ@xgamesfun/solanaです。

• Solana SDKを必要としないJavaScriptクライアント（@xgamesfun/solana/client）、アプリ向けのプレイヤーモジュール（/play）、結果 クライアント（/results）；
• 経済仕様とそのチェッカー、簡易シミュレーション、コストの説明、わかりやすい解説；
• xsolana CLIと、10個のxsolana_*ツールを備えたMCPサーバー；
• xsolana-economyスキル、およびツールとスキルをClaude CodeとCodexに提供するプラグイン1つ；
• プロジェクトの所有者が自分のウォレットで本番稼働を承認するためのローカル承認ページ。

経済はJSON仕様であり、新しいスマートコントラクトではありません。すべてのプロジェクトが共通のプログラムを使用し、個別のプログラムを作成することはありません。

ステータス： loot 0.22.0、プログラムID 9cwqM1TXytPnFZsLfmUyv2dg4uW6Ch9C6UJVPns7NFQ、devnetのみ。プログラムは 独立した監査を受けておらず、監査が完了するまでmainnetでは何も稼働しません。SECURITY.mdをご覧ください。

免責事項： 本ソフトウェアは現状有姿で提供され、保証はなく、プログラムやツールの安全性も保証されません。ご自身の責任で使用し、 承認するすべてのトランザクションと、構築したものが稼働場所の法律に準拠していることの確認は、ご自身の責任となります。ここに記載された内容は、 法的または金融上の助言ではありません。使用前にDISCLAIMER.mdをお読みください。

経済に含められる要素

• トークンまたはNFTによる支払いと分配
• ショップ（1回のトランザクションで購入）とルートボックス
• プールと時間指定スケジュール（シールドの有無を選択可能）
• 宝くじと抽選（損失のない宝くじを含む）
• ランダムかどうかを問わず、あらゆるルートでの賞品：アイテム、トークン、プロジェクトが保管庫に保持するNFT
• 金銭を受け取るすべてのルートで、価格としてNFTを使用
• ロック段階、ブースト、早期退出、通行料を備えたステーキングファーム
• クラフトレシピ
• 順位またはステークに応じた賞品を用意する保留とコンテスト
• オークション：最高額の入札者が落札し、上回られた入札額はただちに返金
• 販売またはレンタル用の出品、およびプレイヤー間の入札とローン
• プロジェクトがそのNFTに対する権限を持つかどうかを問わず、あらゆるNFT向けの特典、ステーキング、保留
• ゲート付きのすべてのルートに適用できる、任意のサイズの許可リスト（Merkleリスト）
• サーバーが保証する、上限付きの報酬と助成金
• コレクティブルの説明文に関するルール

すべてのアクションで公開レシートが残ります。プログラムの動作についてはdocs/program.mdをご覧ください。

AIコーディングエージェントから使用する

MCPサーバーとスキルを使うと、Claude Code、Codex、または任意のMCPエージェントが、ひとことのアイデアから検証・シミュレーション済みの 経済を作成し、自分のウォレットで本番稼働させるためのコマンドを提示できます。

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対応の任意のエージェント（Cursor、opencode、Clineなど）：サーバーを npx -y --package=@xgamesfun/[email protected] xsolana mcpで実行します。または、npx -y @xgamesfun/[email protected] connectで、スキルとともにClaude CodeとCodexに登録できます。

次に、たとえば「1回の釣りに0.02 SOLかかり、珍しい金色の魚と毎月の抽選がある釣りゲーム」のような経済を依頼します。

本番稼働を決めるのは常にあなたです：npx -y @xgamesfun/[email protected] approveを実行すると、コンピューター上でページが開きます。そこで devnetウォレットを接続し、各トランザクションを承認します。エージェントが署名することはなく、秘密鍵を求めることもありません。

ターミナルから使用する

すべてのツールは、仕様ファイル（デフォルトはxsolana.json）を指定してCLIからも実行できます。

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	エージェントが従うスキル
examples/	テストで検証され、稼働するエコノミー一式：ideas.json、評価済みの実在するエコノミー 112 件
evals/	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 が失敗時に 1 行ではなくスタック全体を出力します
XSOLANA_PROGRAM_DIR	テストで指定したプログラムビルドの target/deploy/loot.so を実行し、IDL がそれと一致するか確認します
node bin/xsolana.mjs connect --local を実行して、このチェックアウトの MCP サーバーとスキルを Claude Code および Codex に登録します
（--remove を指定すると登録を解除します）。

skills/ を編集した後は、npm run sync-skills を実行してください。ツールのテキスト、スキル、またはプラグインへの変更は、評価の前後を比較することで最も適切に測定できます （evals/README.md）。AGENTS.md には、このリポジトリで作業する人とコーディングエージェントの双方に適用されるルールが記載されています。

貢献

イシューやプルリクエストを歓迎します。CONTRIBUTING.md をご覧ください。変更を送る前に npm run check を実行し、 脆弱性は SECURITY.md の説明に従って非公開で報告してください。

ライセンス

Apache-2.0。NOTICE および DISCLAIMER.md をご確認ください。本ソフトウェアは現状有姿で提供され、保証はなく、ご自身の責任でご利用ください。