# FERAL FROGS × LOOTPOOL 白皮书

版本：v1.0  
状态：艺术资产与前端已完成；合约通过本地测试，但 Robinhood 部署清单尚未广播。  
最后更新：2026-07-28

## 1. 摘要

Feral Frogs 是一套 4,444 供应量的生成式 NFT，也是 LOOTPOOL NFT/ETH 池中的标准库存单位。
它有意把视觉差异和经济权利拆开：

- 每只蛙可以在外观、稀有度与身份叙事上不同；
- 合约把每只蛙视为完全相同的一单位库存；
- 稀有度不会提高胜率、赔付、赎回权或协议收入；
- NFT 与 ETH 进入同一收藏池后形成合并托管，而不是每个用户独立的小金库。

这避免了视觉稀有度偷偷变成金融优先权，也避免 1/1 传奇款制造合约无法兑现的承诺。

## 2. 艺术系统

### 2.1 视觉语言

每只蛙都是正面蹲坐的湿皮沼泽蛙，像廉价新闻纸上的平面丝网印标本。画面只有固定粗黑描边、
纯平色块和八个锁定色值，不使用渐变、空气透视、软阴影或 3D 渲染。

酸绿 `#B9FF3B` 是唯一允许表现“发光”的颜色，而且每只蛙只出现一至两处。它不是普通装饰，
而是协议从动物眼睛、排气孔或口水中泄漏出来的视觉信号。

### 2.2 九层结构

| 层 | 名称 | 选项 | 作用 |
|---|---|---:|---|
| L0 | Backdrop | 8 | 不透明底板 |
| L1 | Hide | 12 | 本体与主剪影 |
| L2 | Gutplate | 6 | 腹部纹样 |
| L3 | Eyes | 12 | 64px 下的第一识别信号 |
| L4 | Maw | 9 | 嘴与第二识别信号 |
| L5 | Crown | 14 | 打破顶部剪影 |
| L6 | Growth | 10 | 打破左侧剪影 |
| L7 | Grip | 10 | 打破右侧剪影 |
| L8 | Wash | 7 | 最终全幅效果层 |

共计 88 个源图层资产。完整组合空间为：

```text
8 × 12 × 6 × 12 × 9 × 14 × 10 × 10 × 7
= 609,638,400
```

只计算会改变 64px 剪影的 Eyes、Maw、Crown、Growth、Grip，也有：

```text
12 × 9 × 14 × 10 × 10
= 151,200
```

相对于 4,444 供应量，完整组合空间约为供应量的 137,000 倍，剪影空间约为供应量的 34 倍。

### 2.3 生产约束

单一正面姿势不是偷懒，而是配件能够精确注册的必要条件。平色与固定描边也不是审美口号，
而是让 88 个分别生成的素材经过独立生产后仍能像同一个系列的唯一可靠办法。

4,444 张最终 PNG 已在本地构建完成。公开前端展示其中 88 张等距抽样图，覆盖从 #1 到 #4444
的完整编号范围；公开样本数不等于最终供应量。

## 3. 协议角色

### Custodian

池的公开托管人。创建池、设置最低单位价格、配置风险参数，并在风险暂停后执行整池关闭。
托管人拥有整池退出权，但不能提取挑战托管款、独立欠款或已计提协议费。

### Contributor

自愿把 NFT 与 ETH 合并进收藏池。贡献记录由 LPArmor 表示，但它只是可转移的信息收据，
不是个人赎回权、债权、收益凭证或特定 NFT 的所有权证明。

### Hunter

通过 commit/reveal 路径提交挑战。挑战资金先进入托管；揭示成功后才结算，放弃揭示则可由任何人
在期限后执行 expire，避免池永久冻结。

### Defender

池当前迎战的 NFT 单位。击杀数、守住的 ETH 与视觉变异构成叙事记忆，但不会绕开池级会计约束。

## 4. 运行机制

### 4.1 合并托管

`addLiquidityWithNFTs(poolId, tokenIds, lootBps, metadataDays, uri)` 会：

1. 把调用者指定的 ERC-721 转入已注册 Vault；
2. 转移后再次验证 Vault 所有权；
3. 按 NFT 数量增加池的标准库存单位；
4. 把 ETH 加入共享储备，并按受限比例增加可战利品 tranche；
5. 铸造信息型贡献收据。

真实 Vault 模式下，库存只能由真实 NFT 存入增加；不能用虚拟数量伪造库存。

### 4.2 安全挑战

生产路径使用隐藏秘密的 commit/reveal：

```text
commitment = keccak(secret, hunter, poolId, core, chainId)
commitChallenge  -> 托管 stake 并快照条款
revealChallenge  -> 将 secret 与未来区块哈希组合后结算
expireChallenge  -> 超时后没收放弃的 stake 并解除池锁
```

协议先计算：

```text
netStake = grossStake - protocolFee
F = max(declaredUnitPrice, reserve / inventory)
```

挑战只有在 `netStake >= F + quotedLoot` 时才能提交。这样即使一只 NFT 离开，剩余储备与库存的
固定地板账面价值也不会下降。

### 4.3 胜负

- Hunter 胜：一只 NFT 离开 Vault，同时支付受上限约束的战利品；
- Defender 胜：扣除协议费后的 stake 进入共享储备，一部分按参数进入 lootable；
- ETH 推送失败：记入独立 `owed` 账本，用户随后通过 `claimOwed()` 拉取；
- 每个池同时只能有一个待结算挑战，避免承诺期间库存和覆盖条件被稀释。

### 4.4 Floor Bid

Floor Bid 只能在扣费后的 ETH 不低于链上会计地板时购买一单位库存。客户端不应自行重算地板，
而应读取 Core 的 `floorPrice(poolId)`。协议不保护稀有编号或特定外观，释放的是标准库存单位。

## 5. 会计边界

所有开放池满足：

```text
Core ETH balance
= open pool reserves
+ challenge escrow
+ owed pull-payment liabilities
+ accrued protocol-fee liabilities
```

整池关闭只能提取目标池的 reserve，不能消耗挑战托管、用户独立欠款或协议费负债。

这是一条链上会计不变量，不是 NFT 市价保险。它不保证外部市场价格、流动性、交易量、Gas 成本、
私钥安全或贡献者回报。

## 6. 收益与费用

- 协议费从指定经济路由中显式计提，合约上限为 500 bps；
- 战利品来自受限 loot tranche，不得抽空受保护储备；
- LPArmor 不承诺个人手续费分成或固定收益；
- 本系统不承诺成交量、利润、代币价格或 NFT 升值。

## 7. 整池退出

Custodian 的完整退出流程：

1. `pauseRisk()` 停止新增风险；
2. 结算或 expire 所有待处理挑战；
3. `closeCustodialPool(poolId, recipient)` 永久关闭池并转出 ETH 储备；
4. 多次调用 `withdrawClosedPoolNFTs(poolId, recipient, maxCount)` 分批取完剩余 NFT。

关闭后的池不能重新接受风险。单个 NFT 转移失败不会阻塞 ETH 侧关闭，可稍后重试。

## 8. 当前完成度

| 层面 | 状态 |
|---|---|
| 88 个分层素材 | 完成 |
| 4,444 张最终图 | 完成 |
| 4,444 份 metadata | 完成 |
| 前端 | 已部署到生产域名 |
| Solidity 本地测试 | 已通过 |
| Robinhood 广播 | 未执行 |
| Robinhood 合约地址 | 当前清单为空 |
| 公开真实资金运行 | 未声称 |

前端中的交易与活动数据在没有已验证合约地址时属于模拟状态。网站上线不等于协议已经链上部署。

## 9. 风险

- 托管风险：用户贡献进入共享托管，不保留单独赎回权；
- 管理风险：Custodian 控制风险暂停和整池关闭；
- 市场风险：会计地板不等于外部市场价格；
- 智能合约风险：本地测试不能替代独立审计；
- MEV 与排序风险：commit/reveal 降低公开随机种子问题，但不能消除所有区块排序风险；
- 运维风险：RPC、索引器、前端和钱包状态可能不一致，Core/Vault 才是结算真相。

## 10. 结论

Feral Frogs 的核心矛盾是有意设计的：视觉上每只蛙都应该让人想认领、命名和传播；经济上每只蛙
必须保持同一标准库存单位。LOOTPOOL 把收藏身份、池级托管、挑战游戏和会计保护放进一个系统，
但不把审美稀有度包装成无法兑现的金融权利。