# AGENTS.md · Reishi Hunt

给在 https://reishi-hunt.pages.dev 上作业的 AI agent 看的操作契约。人类可读版在 README.md，提示词全文在 https://reishi-hunt.pages.dev/llms-full.txt。

## 这个项目是什么

《死神》主题的军衔 NFT 狩猎场。三条合约在 **BSC Testnet（chainId 97）**。核心交互全部通过 AI 完成 —— 页面上没有按钮流程，只有可复制的提示词。

## 地址

```
链          BSC Testnet（chainId 97）
RPC         https://bsc-testnet-rpc.publicnode.com
BLC         0xC5AEade4A0Eb1C13A6e5299f1194820Dd3556F11
军衔 NFT     0x0347cce19d69847b841076c83087cFDF1412A322
狩猎场       0x61d0432ccaceDbd6B8f8b56eB05eBA65cbba10b9
单价        0.0013328 BNB（每个势力首枚免费，之后每枚这个价，单钱包每势力上限 8 枚）
```

## 硬约束（违反会直接 revert 或算错账）

1. **收益按当量分，不按军衔分。** weightOf(id) = 累计消耗 BLC。铸造 5，升阶 +10/+50/+280，合成守恒。
2. **只有领先势力拿产出。** 在线当量最高的势力独吞 7,200/天，其余两家 pending 冻结。平局归编号小的。
3. **mint 和 quoteMint 的 faction 参数必填**：mint(faction, count) / quoteMint(who, faction, count)。少传一个是参数错误，不是 revert。
4. **合成要 approve 手续费**（该阶升阶成本的 0.5%）。不授权会 revert。
5. **msg.value 必须精确等于 quoteMint 的返回值**，不能自己按单价乘。
6. **免费额度按势力独立**：每势力第 1 枚免费，不是全站共用 1 枚。
7. **回本天数 = 全网总当量 ÷ 7,200**，所有升阶档位相同。别做「性价比排序」。
8. **战斗中不能转账、不能合成**（TokenLocked / TokenInBattle）。

## 典型动作序列

### 铸造

```
nft.quoteMint(myAddress, faction, count)  → (payableWei, freeCount, remaining)
nft.mint(faction, count) { value: payableWei }
```

faction：死神 0 / 虚 1 / 灭却师 2。

### 升阶

```
blc.allowance(myAddress, hunt) < cost  →  blc.approve(hunt, cost)   // 精确额度，不要无限
hunt.upgrade(tokenId)
```

cost = upgradeCost(tier)：10 / 50 / 280 BLC。其中 0.5% 进 treasury，其余销毁。当量 +cost。

### 合成

```
hunt.fuseRecipeOf(faction, tier)  → uint256[4]  // [下级, 中级, 上级, 顶级] 各吞几枚
blc.approve(hunt, fee)                          // fee = upgradeCost(tier) × 0.5%
hunt.fuse(tokenIds)
```

### 狩猎

```
hunt.stake(tokenIds)      // 需要 miningOpen() == true
hunt.pendingOf(myAddress) // 待结算
hunt.claim()              // 到账 = pending × 99%
hunt.unstake(tokenIds)    // pending 保留，不会丢
```

## 错误码

```
AlreadyOpen           狩猎已经开过了，不用重复开
AlreadyStaked         这枚已经在战斗中了
BadCount              count 为 0，或单次超过钱包上限（8）
BadFaction            faction 只能是 0 / 1 / 2
BadFuseCount          配方数量对不上，先用 fuseRecipeOf(faction, tier) 读准确的
EmptyBatch            传了空数组，至少给一个 tokenId
InvalidTier           tier 只能是 0 / 1 / 2 / 3
MiningClosed          狩猎未开启
MixedFactions         合成不能跨势力
NotAuthorized         调用者没有权限（多半是 owner-only 方法）
NotFarm               只有狩猎场合约能调（NFT 合约侧的守卫）
NotOwner              合约 owner 才能调
NotReady              还没有任何势力售罄，开矿条件未满足
NotStaked             这枚不在战斗中，无法中止
NotTokenOwner         这枚 NFT 不属于你
SaleClosed            发售已关闭（owner 关的），不是你的问题
SoldOut               该势力 8,888 枚下级已售罄 —— 换势力，或等二级市场
TierMaxed             已经是顶级（队长 / 归刃 / 皇帝），没有下一档
TokenInBattle         NFT 在战斗中，不能参与合成
TokenLocked           NFT 在战斗中，先 unstake 才能转账或挂单
WalletCapReached      这个钱包在该势力已满 8 枚 —— 换钱包或换势力
WrongPrice            msg.value 不等于 quoteMint 返回的 wei —— 重新报价再发，不要手算
ZeroAddress           地址不能是零地址
```

## MCP 接入

仓库自带一个 stdio MCP server（`blc/agent/server.mjs`），16 个工具，只依赖 ethers，不需要任何 MCP SDK。

```bash
BLC_RPC=https://bsc-testnet-rpc.publicnode.com \
BLC_TOKEN=0xC5AEade4A0Eb1C13A6e5299f1194820Dd3556F11 \
BLC_NFT=0x0347cce19d69847b841076c83087cFDF1412A322 \
BLC_FARM=0x61d0432ccaceDbd6B8f8b56eB05eBA65cbba10b9 \
node blc/agent/server.mjs
```

客户端配置（Claude Code / Cursor 的 `mcpServers`）：

```json
{
  "mcpServers": {
    "reishi-hunt": {
      "command": "node",
      "args": ["/abs/path/to/blc/agent/server.mjs"],
      "env": {
        "BLC_RPC": "https://bsc-testnet-rpc.publicnode.com",
        "BLC_TOKEN": "0xC5AEade4A0Eb1C13A6e5299f1194820Dd3556F11",
        "BLC_NFT": "0x0347cce19d69847b841076c83087cFDF1412A322",
        "BLC_FARM": "0x61d0432ccaceDbd6B8f8b56eB05eBA65cbba10b9"
      }
    }
  }
}
```

**默认只读**：所有写操作返回「待签名交易」，由上层钱包签名广播。只有同时满足 `BLC_PRIVATE_KEY` + `BLC_ALLOW_SEND=1` + 调用时 `confirm: true` 三者，才会真正发送。

工具清单：

```
blc_get_config      环境自检：链 ID、地址、价格、税率、能否广播。任何操作前先调它
nft_list_owned      某地址的全部 NFT：档位、当量、是否锁定、日产、下一档成本
farm_get_position   狩猎持仓：总当量、待结算/已结算、质押数量、全网份额
farm_get_stats      全网状态：总当量、日产出、狩猎开关、铸造进度、售罄情况
farm_quote_yield    单枚 NFT 的日产、升一档的增益、静态回本天数
nft_mint_quote      铸造报价：要付多少 BNB、几个免单、还剩几个额度（不下单）
nft_mint            铸造下级 NFT
farm_stake          投入狩猎
farm_unstake        中止狩猎并解锁
farm_claim          结算待发 BLC（抽 1%）
farm_upgrade        升阶（自动给出 approve + upgrade 两步计划）
farm_fuse           按势力配方合成
blc_approve_exact   精确额度授权，拒绝无限授权
farm_plan_upgrade   预算内规划升阶（纯计算，不发交易）
nft_quote_sale      出售定价参考（30 / 60 天产出）
farm_daily_report   持仓日报 + 风险点 + 建议
```

## 本仓库的验证脚本

```bash
cd blc/agent
node e2e_local.mjs       # 本地 ganache 端到端，48 项
node payout_test.mjs     # 势力独吞 + 收款地址，35 项，断言精确到 wei
```

## 许可与风险

测试网部署，treasury 当前是单私钥 EOA、LP 未锁仓。主网前需换多签。合约未经审计。