这是我们研发「BlockLever」的第 5 篇研发日志，前 4 篇如下：
- BlockLever实战营日志 #1 | 开营
- BlockLever实战营日志 #2 | 产品需求梳理
- BlockLever实战营日志 #3 | 合约开发阶段
- BlockLever实战营日志 #4 | 完成第一个里程碑
前几天，我们完成了「BlockLever」第一个重要里程碑（核心合约开发 + 基础单测完成），也宣布了这一期实战营正式涨价为 $499 了。之后这几天，我们又重新梳理了几个重要的文档，下面就简单介绍一下最新的进展。
核心文档
过去这几天，我与 AI 一起，把 BlockLever 的文档体系重新梳理了一遍，形成了当前阶段最核心的几份文档：
- 产品需求文档（PRD v3）
- 技术架构文档（TAD v4）
- AssetRegistry 详细设计文档
- AccountFactory 详细设计文档
- UserAccount 详细设计文档
- BlockLeverRouter 详细设计文档
这些文档都是我与 Claude Code 基于最新的设计思路和已经完成的核心实现共同迭代出来的。下面，我会简单介绍它们各自的重点内容与作用。
产品需求文档（PRD v3）
一开始的时候，Claude Code 帮我生成的 PRD v3 虽然内容非常丰富，但它其实并不是一份真正意义上的 PRD。文档里大部分内容都偏向技术层面：包括技术架构图、核心合约的逻辑说明、接口设计、函数签名等等。
换句话说，这份“PRD v3”更像是一份 技术架构文档（TAD），而不是 产品需求文档（PRD）。
因此，我和 AI 又花了不少时间，把原本混杂的内容重新拆分、重组，最终产出了一个真正从“用户视角”出发的 PRD v3。
新版 PRD 清晰地定义了 BlockLever 的产品定位：
让现货投资者用“买入 / 卖出”这套熟悉语言，就能获得 1–3 倍的温和杠杆收益。
在这个愿景之上，PRD v3 从用户需求出发，重新梳理了整个产品的关键内容，包括：
- 目标用户是谁、他们有哪些痛点、为什么需要 BlockLever
- BlockLever 与永续合约 DEX、现货钱包之间的差异化定位
- 四大核心交易流程：做多 / 平多、做空 / 平空
- 两个关键风险管理功能：追加本金、提前还债
- “我的资产”信息结构与风险等级展示规则
- 用户在操作前必须看到的所有预览信息（投入、借入、盈亏、清算价格等）
- 术语映射体系（把期货语言完全转译成现货语言）
- 风险提示、费用规则、成功指标以及 MVP 范围
相比之前的版本，PRD v3 的定位更加明确：
不谈实现、不讲合约，只专注用户行为与产品体验本身。
它不仅重新定义了 BlockLever 的核心价值主张，也完整描述了一个现货投资者，从第一次交易到持仓管理再到最终平仓的完整路径。
最终，PRD v3 让我们已经完成的合约实现第一次被完整、系统地转化为一份真正的“产品文档”，使 BlockLever 的整体设计从工程层走向用户层，也为接下来的前端开发和集成测试奠定了清晰的蓝图。
技术架构文档（TAD v4）
一开始，我是同时让 AI 帮我生成 PRD v3 和 TAD v3 两份文档的。等两份都生成完，我才开始认真 review 当时的 PRD v3，结果发现这份“PRD”从头到尾都在讲技术架构、合约模块、接口设计，气质上完全是一份 TAD，而不是产品文档。
于是我们就做了一个调整：
- 原本的 PRD v3，被正式“转正”为 TAD v4，在此基础上继续打磨技术架构；
- 同时，让 AI 再根据产品视角，重新生成了一份全新的 PRD v3。
也就是说，现在的 TAD v4，其实是从那份“伪 PRD”进化而来的一个更成熟、结构更清晰的技术架构文档。
TAD v4 的核心，是确立了 BlockLever 目前采用的 Per-Asset Account 架构。在这个架构下，每个用户针对每一种资产都会拥有独立的 UserAccount 智能合约，实现了：
- 风险隔离（ETH 爆仓不影响 BNB）
- 位置独立（每个资产都有自己的抵押与债务）
- 并行操作（同一用户可同时做多 A、做空 B）
- 便于升级（账户可单独迁移、单独升级）
此外，TAD v4 还对几个核心合约进行了详细说明，包括：
- BlockLeverRouter：用户所有操作的入口（开仓、平仓、还债、追加本金等）
- AccountFactory：负责账户创建、模板升级、费率管理
- AssetRegistry：管理支持资产、杠杆倍数、最小本金、流动性池配置
- UserAccount：与 Venus 交互的核心执行单元（负责 supply / borrow / repay / redeem）
这份架构文档还包含：
- 完整的合约间调用关系图
- Flash Swap 的执行流程
- EIP-1167 Minimal Proxy 的部署模式
- 费用机制（交易费、持仓费）
- health factor / collateral / debt 的计算方式
- Preview 系列只读方法的设计（前端依赖）
- Gas 指标与性能目标
可以说，TAD v4 基本等价于一份“BlockLever 技术白皮书”，从系统结构到合约接口都做了工程级的完整描述。
它让我们现在的合约实现不再只是“能跑”，而是有了清晰、可扩展、可维护的技术框架，为后续模块扩展、前端对接、集成测试提供了非常坚实的基础。
合约模块详细设计文档
在完成 PRD v3 与 TAD v4 之后，我们又进一步整理了 BlockLever 的四个核心合约，形成了各自独立的《详细设计文档》：BlockLeverRouter、AccountFactory、AssetRegistry、UserAccount。这四份文档全部基于已经实现的合约代码编写，完整描述了 BlockLever 的底层技术结构，也标志着整个系统已经从“架构设计阶段”正式进入到“工程文档完善阶段”。
以下我分别总结这四份文档的核心价值与技术亮点。
1. AssetRegistry：资产配置的中枢大脑
AssetRegistry 是 BlockLever 协议最关键的基础组件之一，用于管理所有可交易资产的配置，包括：
- 支持资产列表
- vToken 映射关系
- 最大杠杆倍数（基于 Venus 抵押因子 + 安全边际计算）
- 最小本金要求
- 资产启用/禁用开关
这一模块保证了“BlockLever 能不能交易某个资产、能用多少倍数、需要多少本金”等一系列核心规则都能被严格校验。
文档里也完整描述了其 安全验证流程：例如配置新资产时，会检查 underlying 是否匹配、vToken 是否上市、抵押因子是否有效，以及杠杆倍数是否超过可计算上限。
此外，文档还展示了其与 Venus 的深度结合，包括动态读取抵押因子、根据 Comptroller 的最新参数自适应杠杆倍数等机制。
总结来看：AssetRegistry 负责定义“规则”。规则严谨，系统才稳得住。
2. AccountFactory：账户生命周期管理者
AccountFactory 负责创建、维护、升级每个用户的 Per-Asset 账户（UserAccount），是账户体系的“制造厂”。
几个极其关键的点：
① 每个用户每种资产拥有独立的账户（Per-Asset Account）
Factory 负责管理 user → asset → account 的映射关系。
② 使用 EIP-1167 Minimal Proxy 创建账户
- 创建账户仅需 ~45k gas
- 比传统部署 ~500k gas 节省巨大
这使得 BlockLever 在高链上 Gas 环境下依然可用。
③ 费率管理中心
Factory 负责：
- tradingFee（交易费）
- holdingFee（持仓费）
- feeCollector（手续费接收者）
所有费率均可配置，所有逻辑在文档中有完整描述。
④ 模板升级机制
Factory 支持：
- 用户单资产账户升级
- 用户一次性升级所有账户
- 模板版本递增管理
升级时还要求用户必须先平仓（无债务、无抵押），确保安全性。
总的来说，AccountFactory 是 账户管理、费率管理、版本管理的三合一核心模块。
3. UserAccount：与 Venus 交互的仓位执行引擎
UserAccount 是最贴近实际业务的模块，也是用户仓位真正存在的地方。
每个 UserAccount 独立管理：
- 抵押品数量
- 借贷数量
- vToken 余额
- 累计费用
- 健康因子
- 仓位方向（做多 / 做空）
文档非常详细地描述了做多、做空、平仓等函数的执行逻辑。例如：
supplyAssetAndBorrowUSDT()做多开仓repayUSDTAndRedeemAsset()做多平仓supplyUSDTAndBorrowAsset()做空开仓repayAssetAndRedeemUSDT()做空平仓
所有 Venus 操作均在此模块中执行，包括 deposit/borrow/repay/redeem。
一个特别重要的点是：文档展示了 UserAccount 的 gas 优化策略，尤其是大量常用地址（vToken、comptroller、USDT）在初始化时缓存，以减少后续读取成本。
UserAccount 是整个 BlockLever 在链上真正“跑起来”的执行单元。
4. BlockLeverRouter：所有交易的入口与协调者
Router 是用户与协议交互的入口，也是协调 Flash Swap 与 Venus 操作的总控模块。
文档中列出了其四大核心职责：
- 执行做多（borrowToBuy）、平多（sellToRepay）
- 执行做空（borrowToSell）、平空（buyToRepay）
- 调用 PancakeSwap V3 的 flash swap
- 调用 UserAccount 完成 Venus 操作
- 提供 Preview 预览查询
- 健康因子检查 + 滑点保护
Router 是整个协议“串联所有模块的关键纽带”。
它确保：
- 做多操作的 flash swap 流程完整且安全
- 所有操作都符合资产配置规则
- 仓位开仓后健康因子必须 ≥ 1.0
- 每笔交易都有事件记录便于追踪
简而言之，Router 是 BlockLever 的“指挥系统”。
四个模块串起来是什么？
BlockLever 的四个模块结构非常清晰：
| 模块 | 作用 |
|---|---|
| AssetRegistry | 定义规则（能交易什么、最大杠杆是多少） |
| AccountFactory | 创造账户（账户生命周期 + 费率 + 升级） |
| UserAccount | 持仓与借贷执行单元（仓位所在之处） |
| BlockLeverRouter | 协调所有步骤（用户操作入口 + Flash Swap） |
分别承担：规则层、账户层、仓位层、操作层的职责。
这一体系让 BlockLever 拥有：
- 可扩展性强（增加新资产非常简单）
- 风险隔离能力强（每种资产独立账户）
- Gas 成本低（clone 部署 + 缓存优化）
- 安全性高（多层验证机制）
- 维护性好（模块边界清晰）
📌 小结：
这四份详细设计文档的完成，意味着 BlockLever 的整个合约体系已经达到了“生产级别可维护”的水平。从架构、账户体系、资产规则，到执行模块与安全机制，都已形成完整闭环。
它们让 BlockLever 不仅是“能跑起来”，而且是“结构化、模块化、可扩展、可升级”的一套 DeFi 杠杆协议。
下一步：进入集成测试与前端开发
经过这几天对 PRD、TAD，以及四个核心合约详细设计文档的全面梳理，BlockLever 的整体架构已经清晰成型：产品层有统一逻辑，架构层有完整体系，工程层有可维护的模块化实现。
这意味着，我们已经正式从“合约实现阶段”迈入了真正的 系统化工程阶段。
接下来，我们将进入两个关键工作：
- 搭建集成测试环境（Integration Test Environment）：让完整协议第一次在“准真实链上环境”中跑起来
- 前端 MVP 开发：把所有链上流程变成用户可操作的界面
这是 BlockLever 从“技术可行”走向“产品可用”的关键一步，也会是下一篇日志的重点。
敬请期待。
参考阅读：
