arturdeluca/SimplesFinance-Audit

# Simples Protocol — SwapVault 一个极简的、部署于 Arbitrum 上的去中心化期权协议。用户可以通过点对点的方式创建条件互换合约——无需 oracles，无需流动性池，无需自动定价。 ## 概述 该协议允许任何用户将 token 存入 vault 并自行定义 strike price。买家获取 **VaultKeys**（代表行使互换权利的 ERC-20 token）并手动决定何时行权。结算完全在链上进行；其他所有环节——挂牌、定价、发现——都在前端市场完成。 **盈利模式：** 协议本身是免费且公开的。前端市场作为商业项目，会在行权时向 taker 和 maker 收取费用。 ## 合约 | 合约 | 描述 | |----------|-------------| | `SwapVaultFactory.sol` | 核心协议。负责创建 vault，管理行权、结算以及紧急恢复。 | | `VaultKey.sol` | 代表 vault 行权的 ERC-20 token。每个 vault 对应 100 个 VaultKeys（固定供应量）。 | | `VaultViewer.sol` | 用于批量查询和派生字段的只读辅助工具。 | | `VaultKeyMarketplace.sol` | 用于交易 VaultKey 的去信任市场。基于 approval（无需 escrow）。支持 EIP-712 无 gas 费挂牌。 | | `BuyOrderBook.sol` | 带有 escrow 的链上买单。买家存入付款；卖家以原子方式成交。 | ## 架构 ``` 1. CREATE Alice approves tokenDeposited → calls createVault() → receives 100 VaultKeys 2. SELL (via marketplace) Alice lists VaultKeys → Bob buys them, paying premium to Alice 3. EXERCISE Bob approves (tokenRequired + takerFeeAmount) → calls exercise() → Contract receives totalFromTaker → Alice receives requiredAmount - makerFeeAmount → feeCollector receives takerFeeAmount + makerFeeAmount → Bob receives proportional tokenDeposited 4. EXPIRATION Vault expires → creator or VaultKey holder calls finalizeVault() → Unexercised tokens return to creator 5. EMERGENCY (30 days after expiration) Anyone can call emergencyFinalize() → Prevents permanently locked tokens ``` ### 关键设计决策 - **无 oracles** — 创建者可自由设定 strike price；市场进行自我调节。 - **手动行权** — 持有者自行决定何时行权；没有任何自动化操作会强制干预决策。 - **每个 vault 单独隔离费用** — `lockedTakerFee` 和 `lockedMakerFee` 在创建时被写入 vault 结构体中。全局费用的更改仅影响未来创建的 vault。 - **两种独立费用** — `takerFee`（由行权者在 `amountRequired` 基础上额外支付）和 `makerFee`（从创建者收到的款项中扣除）。两者上限均为 1% (100 bps)，初始值为 0%。 - **Fee-on-transfer 保护** — 在存款前后测量 `balanceOf`；若金额不一致则回退。 - **Marketplace 基于 approval** — VaultKey 在被购买前会一直保留在卖家钱包中。 - **BuyOrderBook 基于 escrow** — 买家将款项存入合约中，确保在成交时资金充裕。 ## 已部署合约 (Arbitrum Sepolia Testnet) | 合约 | 地址 | |----------|---------| | SwapVaultFactory | `0xb1c28ae53740D9cf2c7DEd8C6C3AcB9298bfa3b6` | | VaultViewer | `0xFcF53ad3d9e3Af51dA4668E4a49D855030883713` | | VaultKeyMarketplace | `0xDE4dB06151d7ce4dAb61289d00b213408DF7FB65` | | BuyOrderBook | `0x5a54D5E1b96FD9365b3FA6f88FE8398bA4e9c44b` | **Chain ID:** 421614 (Arbitrum Sepolia) **Explorer:** https://sepolia.arbiscan.io ## 技术栈 | 层级 | 技术 | |-------|-----------| | 智能合约 | Solidity ^0.8.20 / ^0.8.28 | | 测试 | Hardhat v3 (同时运行 `.t.sol` Solidity 测试和 `.ts` Mocha/Chai 测试) | | Solidity 测试风格 | forge-std (`vm.prank`, `vm.expectRevert`, 通过 `bound` 进行 fuzz 测试) | | 库 | OpenZeppelin Contracts v5 | | 网络 | Arbitrum (L2) | ## 设置 **要求:** Node.js v20+ 无需安装 Foundry。Hardhat v3 可通过单条命令原生运行 Solidity 测试 (`.t.sol`) 和 TypeScript 测试。 ``` # 克隆并安装 git clone cd swapvault-audit npm install # 编译合约 npx hardhat compile # 运行全部 299 个测试 npx hardhat test ``` ### 环境变量 仅在部署到正式网络时需要——**在本地运行测试时不需要。** 将 `.env.example` 复制为 `.env` 并填入你的值： ``` DEPLOYER_PRIVATE_KEY=0x... ARBITRUM_SEPOLIA_RPC=https://arb-sepolia.g.alchemy.com/v2/YOUR_KEY ``` ## 测试覆盖率 跨两个测试框架的 **299 项测试，0 次失败**。 所有测试均通过 `npx hardhat test` 运行。Solidity 测试 (`.t.sol`) 采用 forge-std 风格；TypeScript 测试 (`.ts`) 采用 Mocha/Chai。 | 文件 | 语言 | 范围 | |------|----------|-------| | `SwapVaultFactory.t.sol` | Solidity | 创建、管理、查看功能 | | `Exercise.t.sol` | Solidity | 包含 taker/maker 费用的行权、边缘情况 | | `FuzzExercise.t.sol` | Solidity | 比例算术、费用计算 (每个运行 256 次) | | `Finalization.t.sol` | Solidity | 结算及紧急结算 | | `ViewFunctions.t.sol` | Solidity | VaultViewer 批量查询 | | `VaultKey.t.sol` | Solidity | ERC-20 合规性、销毁限制 | | `VaultKeyMarketplace.t.sol` | Solidity | 挂牌、层级、无 gas 费购买 | | `BuyOrderBook.t.sol` | Solidity | 订单 CRUD、费用、查看功能 | | `full-lifecycle.ts` | TypeScript | 端到端: 创建 → 出售 → 行权 → 结算 | | `fee-lifecycle.ts` | TypeScript | 费用锁定、taker/maker 费用场景 | | `multiple-exercisers.ts` | TypeScript | 多个买家对同一个 vault 行权 | | `expiration-scenarios.ts` | TypeScript | 7 个基于时间的场景 | | `fee-on-transfer.ts` | TypeScript | Fee-on-transfer token 保护 | | `reentrancy.ts` | TypeScript | Reentrancy 防护验证 | | `rounding-attack.ts` | TypeScript | 分数次行权下的 token 守恒 | | `vault-viewer.ts` | TypeScript | VaultViewer 集成 | | `buy-order-book.ts` | TypeScript | BuyOrderBook 集成 (36 项测试) | ## 许可证 MIT

标签：Arbitrum, DeFi, Solidity, 区块链, 智能合约, 期权交易