PurgeGame/degenerus-protocol

# Degenerus Protocol [Degenerus Protocol](https://degener.us) 的智能合约。 ## 它是什么 Degenerus 是 Ethereum 上的链上博彩协议。玩家购买彩票，购票 ETH 填充奖池，当奖池达到目标时关卡完成并触发 Jackpot。彩票价格在每个 100 级的“世纪”中循环切换层级。奖池在每个周期中棘轮式上涨。Chainlink VRF 决定每一个结果。 三种产品共享一个经济体系： - **Tickets** — 直接的彩票条目。特征由 VRF 分配，Jackpot 支付给特征匹配的持有者。老实说是 -EV（负期望值），但可证明公平。 - **Lootboxes and passes** — 长线产品，为奖池提供资金并获得未来级别的彩票作为回报。EV 取决于活跃度得分（你玩多少）和关卡速度（游戏进展多快）。 - **Affiliate network** — 三级推荐系统。佣金以 BURNIE 投币信用支付，而非直接 ETH，这过滤掉了唯利是图的推荐农夫。 协议在预售后提取零抽成。进入的每一 wei ETH 都进入奖池并循环回流给玩家。无运营商费用，无管理员提款功能。合约不可变且无升级路径。存在一个管理员角色，其权力范围非常有限（仅限紧急情况的 VRF 协调员轮换），但无法访问资金或修改游戏规则。 如果游戏连续 365 天停滞，将触发终端状态并将所有剩余 ETH 分配给符合条件的彩票持有者。终端支付数学使得在停滞期间购买对个人而言是理性的，这正是防止停滞持续 365 天的原因。完整分析见 [博弈论论文](https://degener.us/theory/)。 ## 快速开始 ``` npm install npx hardhat compile ``` 需要 Node.js 18+。 ## 测试 ``` # Hardred 测试 (1,241 项测试) npx hardhat test # Foundry 不变性模糊测试 forge test ``` ## 架构 - **23 个可部署合约**（13 个核心 + 10 个 delegatecall 模块），通过 `DegenerusGameStorage` 共享存储 - Solidity 0.8.34，启用 `viaIR`，optimizer runs = 200 - 所有合约小于 24KB（DegenerusGame 最大，为 19KB） - 外部依赖：Chainlink VRF V2.5, Lido stETH, LINK token - Pull 模式 ETH/stETH 提款（无 push 支付） ``` DegenerusGame.sol (main entry point, delegatecall dispatcher) ├── MintModule Ticket purchasing, ETH splitting ├── AdvanceModule Level advancement, VRF requests ├── JackpotModule Daily/weekly/grand jackpots ├── EndgameModule Final-round resolution ├── GameOverModule Game-over distribution and sweep ├── LootboxModule Lootbox drops and claims ├── WhaleModule Whale bundles, lazy passes, deity passes ├── BoonModule Deity boon rewards ├── DecimatorModule Elimination events └── DegeneretteModule Degenerette mini-game ``` ### 支持合约 | 合约 | 用途 | |----------|---------| | BurnieCoin | 通缩 ERC-20 游戏代币 | | BurnieCoinflip | 每日投币小游戏 | | DegenerusVault | stETH 收益金库 | | DegenerusJackpots | Jackpot 池核算 | | DegenerusQuests | 链上任务/连击系统 | | DegenerusAffiliate | 推荐跟踪和支付 | | DegenerusAdmin | 管理员配置，VRF 连接 | | DegenerusDeityPass | 具有链上 SVG 渲染的 ERC-721 | | DegenerusStonk | 储备支持的销毁代币 (ETH/stETH/BURNIE) | | DeityBoonViewer | 独立的神性恩赐槽查看器 | | WrappedWrappedXRP | Meme 包装合约 | ### 库 | 库 | 用途 | |---------|---------| | BitPackingLib | 用于节省 Gas 存储的位级打包 | | EntropyLib | 从 VRF 种子获取确定性熵 | | GameTimeLib | 天/纪元边界计算 | | JackpotBucketLib | Jackpot 层级分配数学 | | PriceLookupLib | 按级别的彩票价格曲线 | ## 部署 所有合约地址是 `ContractAddresses.sol` 中的编译时常量。部署流程： 1. 预测基于 Nonce 的地址 (`scripts/lib/predictAddresses.js`) 2. 用具体地址修补 `ContractAddresses.sol` 3. 以确定性顺序重新编译和部署 Icons32Data 和模块首先部署 (nonce N+0..10)，然后是支持合约 (COIN, COINFLIP, GAME 等)，接着是依赖于早期合约的合约 (VAULT, DGNLR, ADMIN)。 ## 范围 有关完整的范围内文件列表，请参阅 [`scope.txt`](scope.txt)。 **范围内：** 15 个核心文件（13 个可部署 + 2 个库）+ 12 个模块文件（10 个可部署 + 2 个抽象工具）+ 1 个共享存储 + 5 个库 + 12 个接口 = 45 个 Solidity 文件 **范围外：** `contracts/mocks/`, `contracts/test/` ## 关键机制 - **VRF 状态机：** `rngLockedFlag` 防止并发 VRF 请求。请求 -> 完成 -> 解锁循环。18 小时重试超时，3 天紧急回退。 - **奖池分配：** 购买彩票时 90% 当前级别 / 10% 未来级别。 - **巨鲸定价：** 捆绑包 2.4-4 ETH，懒惰通行证 0.24 ETH+，神性通行证 24 + T(n) ETH 三角形。 - **游戏结束：** 多步过程：advanceGame -> VRF 请求 -> 完成 -> advanceGame -> gameOver = true。30 天最终清理。 - **Pull 支付：** 所有 ETH/stETH 提款通过 `claimWinnings()` 使用 pull 模式。 ## 审计 [`audit/`](audit/) 目录包含内部审计工作的发现： - **[`KNOWN-ISSUES.md`](audit/KNOWN-ISSUES.md)** — 整合的已知问题及其当前状态 - **[`FINAL-FINDINGS-REPORT.md`](audit/FINAL-FINDINGS-REPORT.md)** — 包含需求可追溯性的完整发现报告 - **[`EXTERNAL-AUDIT-PROMPT.md`](audit/EXTERNAL-AUDIT-PROMPT.md)** — 协议概述和威胁模型 - **[`state-changing-function-audits.md`](audit/state-changing-function-audits.md)** — 所有更改状态的入口点的函数级审计 ### 发现摘要 | 严重程度 | 数量 | |----------|-------| | Critical | 0 | | High | 0 | | Medium | 1 (已确认的设计权衡) | | Low | 0 | | Informational | 8 | ### 测试覆盖率 - **1,241 个 Hardhat 测试** — 单元、集成、访问控制、边缘情况、对抗性、PoC、验证 - **21 个 Foundry 测试工具**（10 个不变量，7 个模糊，3 个 Halmos，1 个助手）— ETH 偿付能力、供应不变量、VRF 生命周期、金库数学、FSM、组合 - **Slither** 静态分析分类（所有 HIGH/MEDIUM 检测已审查） ## 许可证 [AGPL-3.0-only](LICENSE)

标签：Chainlink VRF, DeFi, Foundry, GameFi, Hardhat, Lootbox, MITM代理, NFT, Solidity, 不变量测试, 不可变合约, 以太坊, 公平博彩, 区块链, 博彩协议, 可验证随机性, 奖池, 彩票系统, 战利品箱, 抽奖, 推荐系统, 无抽水, 智能合约, 智能合约审计, 游戏理论, 源代码, 赌博 DApp