fluxion-protocol/fluxion-contracts

# Fluxion Contracts 用于在 Stellar 上实现持续资产流式传输的 Soroban 智能合约。 [](https://github.com/fluxion-protocol/fluxion-contracts/actions/workflows/ci.yml) [](LICENSE) ## 概述 Fluxion 为 Stellar Soroban 生态系统引入了一种可编程的、持续的资金分配架构。将离散的 token 转账转化为可预测的、基于时间的数学分布渠道，可用于： - **实时薪酬**：将稳定币直接流式传输到员工钱包中 - **线性解锁**：通过锁定期和里程碑自动进行 token 分配 - **资助资金**：在固定时间间隔内线性释放资金，并提供撤销选项 ## 快速开始 ### 前置条件 - Rust 1.75+ - WASM target: `rustup target add wasm32-unknown-unknown` - [Stellar CLI](https://developers.stellar.org/docs/tools/developer-tools/cli) ### 构建 ``` # 格式化与 lint make fmt lint # 运行测试 make test # 构建优化的 WASM make build ``` ### 部署到测试网 ``` # 有关详细说明，请参见 DEPLOYMENT_GUIDE.md ./scripts/deploy_all.sh testnet ``` ## 架构 ### 组件概述 ``` fluxion-contracts/ ├── packages/fluxion_math/ # Fixed-point math (no blockchain dependencies) ├── contracts/fluxion_core/ # Primary streaming contract ├── contracts/fluxion_factory/ # Factory for deploying verified instances ├── contracts/fluxion_vesting/ # Specialized vesting with cliffs └── .github/workflows/ # CI/CD automation ``` ### 存储模型 **Instance Storage**（捆绑 TTL）： - `Admin`：合约升级权限 - `GlobalCounter`：单调递增的 stream ID 生成器 **Persistent Storage**（独立 TTL）： - `StreamRecord(u64)`：独立的 stream 元数据 - 自动 TTL 续期可防止在长期 vesting 期间状态过期 ### 数据流 ``` User → create_stream() ↓ Contract calculates rate per second (fixed-point) ↓ Contract locks tokens via SAC transfer_from() ↓ Stream stored with TTL management ↓ [Time passes, ledgers close...] ↓ recipient → withdraw() [can happen at any time] ↓ Contract calculates elapsed time ↓ Contract transfers accrued tokens via SAC transfer() ``` ## 核心合约 ### Fluxion Core (`fluxion_core`) 实现持续流式传输的主合约。 **关键 endpoint：** - `initialize(admin)` - 使用升级权限进行初始化 - `create_stream(sender, recipient, token, deposit, start, stop, is_revocable)` - 创建 stream - `withdraw(stream_id, requested_amount)` - 提取已累计的 token - `cancel_stream(stream_id)` - 取消可撤销的 stream（仅限 sender） - `bump_stream_ttl(stream_id)` - 延长 TTL（任何人都可以调用） - `upgrade_contract(new_wasm_hash)` - 升级代码（仅限 admin） **特性：** - 定点数学运算可防止舍入错误 - 支持 4 年以上 vesting 计划的 TTL 管理 - 可撤销/不可变的 stream 选项 - 为 indexer 提供结构化事件 ### Fluxion Vesting (`fluxion_vesting`) 用于带有锁定期 token vesting 的专用合约。 **关键 endpoint：** - `setup_vesting(creator, beneficiary, token, amount, start, cliff, end)` - `claim_vested(beneficiary)` - `get_vested_amount(beneficiary)` - `get_claimable_amount(beneficiary)` **特性：** - 强制锁定期（cliff 之前没有 token） - 锁定期后的线性分配 - 用于查询已 vested/可提取金额的函数 ### Fluxion Factory (`fluxion_factory`) 用于部署已验证合约实例的 Factory 模式。 **关键 endpoint：** - `deploy_core(wasm_hash, salt, admin)` - 部署 Core 实例 - `deploy_vesting(wasm_hash, salt, admin)` - 部署 Vesting 实例 **优势：** - 确定性部署地址 - 跨实例的一致初始化 - 对每个已部署合约的 admin 控制 ## 数学精度 所有速率计算均使用 1e18 缩放： ``` Rate = (Deposit × 10^18) / Duration Accrued = floor((ElapsedSeconds × Rate) / 10^18) ``` 优势： - 无浮点运算 - 在所有节点上具有确定性 - 向下舍入可防止因微小余额累积而产生的提取 ## 安全性 ### 安全不变量 1. **偿付能力**：合约余额 ≥ 所有未提取 stream 的总和 2. **授权**：所有状态更改都需要显式的 `require_auth()` 3. **溢出保护**：所有算术均使用 `checked_*` 操作 4. **精度**：1e18 缩放确保了准确的分数流式传输 ### 威胁模型缓解措施 | 威胁 | 缓解措施 | |--------|-----------| | 重入 | Soroban 强制执行栈隔离；在转账前更新状态 | | 数学溢出 | Rust 严格类型 + checked arithmetic + 1e18 缩放 | | 状态过期 | 读取时自动延长 TTL；公开的 `bump_stream_ttl()` | | 微小余额累积 | 定点数学运算在最后一步向下舍入 | ### 漏洞披露 将安全问题报告至 `security@fluxion.xyz`（通过 PGP 加密）。详情请参阅 [SECURITY.md](SECURITY.md)。 ## 测试 ``` # 运行所有测试 make test # 以详细输出运行 cargo test --all -- --nocapture # 测试特定 contract cargo test -p fluxion-core # 运行 property-based testing cargo test --all -- --include-ignored ``` ## 文档 - [ARCHITECTURE.md](ARCHITECTURE.md) - 深入了解 Soroban 存储和状态管理 - [DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md) - 逐步部署说明 - [API_REFERENCE.md](API_REFERENCE.md) - 完整的函数签名和示例 - [SECURITY.md](SECURITY.md) - 安全策略和审计范围 ## 开发工作流 ``` # 1. 进行修改 # 2. 格式化代码 make fmt # 3. 使用 clippy 进行 lint make lint # 4. 运行测试 make test # 5. 构建优化的 WASM make build # 6. 部署（参见 DEPLOYMENT_GUIDE.md） ``` ## GitHub Actions - **CI 流水线**（`.github/workflows/ci.yml`）： - 格式检查 - Clippy 代码检查 - 完整测试套件 - 安全审计 - WASM 编译 - 文档生成 - **部署**（`.github/workflows/deploy.yml`）： - 手动部署到测试网/主网 - 字节码安装 - 特定于环境的配置 ## 路线图 计划的功能和里程碑请参阅 [ROADMAP.md](ROADMAP.md)。 ## 许可证 在 Apache License, Version 2.0 下授权。详情请参阅 [LICENSE](LICENSE)。

标签：Rust, Stellar, Web3, 代币释放, 区块链, 可视化界面, 智能合约, 网络流量审计, 资金流, 通知系统