aadityakumarsah/Staking-Vault

# VaultLab — 线性质押金库 一个全栈式的质押产品原型：一个确定性的 Rust 金库引擎 以及一个专业的、多路由的浏览器控制台，用于安全地测试其流程。 **在线演示：** [aadityakumarsah.github.io/Staking-Vault](https://aadityakumarsah.github.io/Staking-Vault/) ## 问题 定期质押产品看起来简单，但其核心规则很容易出 错： - 对于 1.5 年等非整数年的期限，奖励公式可能会变得不一致。 - 金库承诺的奖励可能会超过其拥有的支付资金。 - 浮点运算对于 token 余额来说是不安全的。 - 用户需要一个清晰、可测试的视图，以了解何时可以领取奖励以及何时可以提取本金。 - 如果没有交互式的产品体验，智能合约逻辑很难解释清楚。 ## 解决方案 VaultLab 实现了一种抵押、定期质押设计，具有线性 奖励和交互式测试控制台。 当用户创建一个头寸时，金库会计算所选期限的最大 奖励，并立即将其预留。如果奖励池无法覆盖该承诺，质押将被拒绝。奖励会持续释放，而本金将一直锁定直到到期。 在 10% 的年化奖励率下，模型行为如下： | 锁定期限 | 到期总奖励 | 1,000 TOK 的奖励 | | --- | ---: | ---: | | 1 年 | 1.0× 年化奖励 | 100 TOK | | 1.5 年 | 1.5× 年化奖励 | 150 TOK | | 2 年 | 2.0× 年化奖励 | 200 TOK | ``` maximum reward = principal × annual_reward_bps / 10,000 × lock_seconds / 31,536,000 vested reward = maximum reward × min(elapsed, lock_seconds) / lock_seconds claimable = vested reward − previously claimed reward ``` ## 为什么使用 VaultLab？ - **清晰的奖励经济学** — 回报随所选期限呈线性增长。 - **全额奖励抵押** — 新的质押无法过度透支储备金。 - **安全的记账模型** — Rust 使用带检查的 `u128` 运算；不包含浮点数。 - **确定性测试** — 时间被传入金库，使得边缘情况可复现。 - **专业的产品演示** — 前端使得合约流程易于向招聘人员、审查人员和利益相关者展示。 - **演示无需设置** — 托管的 UI 使用本地测试状态，从不要求连接钱包。 ## 如何使用该应用 ### 选项 1：打开托管应用 1. 打开 [VaultLab](https://aadityakumarsah.github.io/Staking-Vault/)。 2. 在 **概览** 中，查看活跃的钱包、金库余额、可用奖励和抵押状态。 3. 从侧边栏打开 **创建质押**。 4. 在 **注入奖励** 中，作为模拟管理员向奖励池添加 TOK。 5. 输入本金金额，选择 1 年、1.5 年或 2 年的锁定期限，并确认抵押预览已注资。 6. 选择 **预留奖励并创建质押**。 7. 打开 **头寸** 以检查释放进度和可领取的奖励。 8. 使用快捷控件推进模拟时间。在可用时领取已释放的奖励；到期后，提取本金以及任何剩余的奖励。 9. 打开 **活动** 以审查每个状态转换，移动时间滑块，将当前状态导出为 JSON，或重置本地测试会话。 测试状态会持久化保存在浏览器的本地存储中，因此当您在路由之间切换时，它仍然可用。随时使用 **重置本地数据** 即可重新开始。 ### 选项 2：在本地运行前端 ``` git clone https://github.com/aadityakumarsah/Staking-Vault.git cd Staking-Vault python3 -m http.server 4173 --directory frontend ``` 在浏览器中打开 [http://localhost:4173](http://localhost:4173)。 ### 运行 Rust 金库引擎 安装稳定的 [Rust 工具链](https://www.rust-lang.org/tools/install)， 然后运行： ``` cargo test cargo run cargo fmt --check cargo clippy --all-targets -- -D warnings ``` `cargo run` 演示了一个 1.5 年的头寸，包含期中奖励领取和到期提款。`cargo test` 验证财务规则和失败路径。 ## 产品路由 | 路由 | 用途 | | --- | --- | | [概览](https://aadityakumarsah.github.io/Staking-Vault/) | 金库健康状况、储备状态、未平仓头寸和近期事件 | | [创建质押](https://aadityakumarsah.github.io/Staking-Vault/stake.html) | 注入奖励，配置期限，并创建抵押头寸 | | [头寸](https://aadityakumarsah.github.io/Staking-Vault/positions.html) | 查看释放情况，领取奖励，提取已到期本金，并推进时间 | | [活动](https://aadityakumarsah.github.io/Staking-Vault/activity.html) | 检查审计跟踪，导出状态，并运行 1.5 年的示例场景 | ## 技术栈 | 层级 | 技术 | 用途 | | --- | --- | --- | | 合约域 | Rust 2021 | 确定性的质押规则和 token 记账 | | 财务类型 | 原生 `u128`，带检查的算术运算 | 精确的 token 单位计算，无浮点数 | | 前端 | HTML5，现代 CSS，原生 JavaScript 模块 | 无依赖的响应式产品控制台 | | 浏览器状态 | `localStorage` | 在路由间共享测试钱包、时钟、头寸和事件 | | 测试与质量 | Rust 测试，`rustfmt`，Clippy | 单元测试、格式化和 Lint 强制执行 | | CI/CD | GitHub Actions | 在每次 push 时运行格式化、Clippy 和所有 Rust 测试 | | 托管 | GitHub Pages | 自动从 `main` 分支发布静态前端 | ## 架构 ``` ┌──────────────────────────────┐ │ Browser test console │ │ HTML + CSS + JavaScript │ │ Local storage test state │ └──────────────┬───────────────┘ │ mirrors the same business rules ┌──────────────▼───────────────┐ │ Rust staking vault engine │ │ Positions · rewards · auth │ │ Reservation · invariants │ └──────────────────────────────┘ ``` 前端有意设计为安全的模拟器，而不是 Rust 库的直接运行时适配器。Rust 单元测试是合约行为的真实来源。生产环境的集成会将浏览器状态替换为区块链运行时或 API 适配器。 ## 核心规则与安全机制 - 头寸具有不可变的所有者、本金、创建时间和锁定持续时间。 - 只有管理员才能注入奖励。 - 只有头寸所有者才能领取奖励或提取本金。 - 本金在到期前不可用。 - 奖励线性释放，可以在多次交易中领取。 - 在创建质押时即预留所有未领取的奖励权益。 - 金库维持以下不变性： ``` vault balance = outstanding principal liability + reward balance reserved rewards ≤ reward balance ``` ## 应用场景 VaultLab 可用于： - 一个 **DeFi / 质押产品原型**，在选择链运行时之前使用。 - 一个 **作品集项目**，展示 Rust 财务逻辑、测试、CI/CD 和以产品为中心的前端设计。 - 一个 **QA 沙盒**，用于手动演练注入资金、质押、释放、领取和到期边缘情况。 - 一个 **教学工具**，用于解释抵押和基于时间的奖励计算，而不会让用户暴露于真实资金的风险中。 - 作为 **CosmWasm、Solana 或 EVM 适配器**的起点，前提是将内存账本替换为链原生存储、转账、身份和时间。 ## 项目结构 ``` . ├── src/ │ ├── lib.rs # Staking-vault domain model and tests │ └── main.rs # Runnable Rust demonstration ├── frontend/ │ ├── index.html # Overview route │ ├── stake.html # Create-stake route │ ├── positions.html # Position operations route │ ├── activity.html # Audit and simulation route │ ├── app.js # Shared persistent simulator state │ └── styles.css # Responsive professional UI system └── .github/workflows/ ├── ci.yml # Rust quality checks └── deploy-frontend.yml # GitHub Pages deployment ``` ## 生产环境注意事项 在使用真实资产应用此设计之前，请添加特定于链的 token 适配器、持久化的链上存储、原生的调用者身份、链上时间、治理和紧急控制、token 小数位处理、集成测试以及独立的安全审计。 ## 简历描述

标签：Rust, Web3, 区块链, 可视化界面, 数据可视化, 智能合约, 网络流量审计, 质押金库, 通知系统, 金融模型