DevKingOche/pulsegov

# PulseGov 合约 [](https://github.com/DevKingOche/pulsegov/actions/workflows/ci.yml) [](https://github.com/DevKingOche/pulsegov/actions/workflows/audit.yml) [](#testing) [](LICENSE) [](https://stellar.org) **PulseGov** 的 Soroban 智能合约 — 基于 Stellar 区块链的去中心化链上治理与投票。 PulseGov 使 DAO、协议和社区能够创建提案、进行代币加权投票、强制执行法定人数并执行决策 — 所有这些都在链上透明进行，并带有不可篡改的审计追踪。 ## 目录 - [概述](#overview) - [架构](#architecture) - [功能](#features) - [快速开始](#quick-start) - [项目结构](#project-structure) - [治理合约](#governance-contract) - [代币合约](#token-contract) - [提案生命周期](#proposal-lifecycle) - [存储模型](#storage-model) - [配置](#configuration) - [开发](#development) - [测试](#testing) - [安全](#security) - [贡献指南](#contributing) - [资源](#resources) ## 概述 去中心化治理对于 DAO、协议和社区透明、公平地做出集体决策至关重要。PulseGov 在 Stellar 的 Soroban 平台上提供了一个生产就绪的治理系统，具有以下特点： - **代币加权投票** — 投票权与经济权益成正比 - **法定人数执行** — 最低参与门槛 - **不可篡改的审计追踪** — 所有投票和决策均记录在链上 - **灵活的提案生命周期** — 从创建到执行或取消 - **经济高效的存储** — 针对 Soroban 的分层存储模型进行了优化 ## 架构 PulseGov 由两个互补的 Soroban 智能合约组成： ``` ┌─────────────────────────────────────────────────────────────┐ │ PulseGov System │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────────────┐ ┌──────────────────────┐ │ │ │ Governance Contract │ │ Token Contract │ │ │ ├──────────────────────┤ ├──────────────────────┤ │ │ │ • Proposals │ │ • Balances │ │ │ │ • Voting │◄─────┤ • Transfers │ │ │ │ • Finalization │ │ • Mint/Burn │ │ │ │ • Execution │ │ • Allowances │ │ │ │ • Cancellation │ │ • Admin Control │ │ │ └──────────────────────┘ └──────────────────────┘ │ │ │ │ │ │ └──────────────┬────────────┘ │ │ │ │ │ ┌────────▼───────┐ │ │ │ Soroban │ │ │ │ (Stellar) │ │ │ └────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` **关键设计决策：** | 决策 | 原理 | |---|---| | 代币加权投票 | 使投票权与经济权益一致 | | 实时余额快照 | 防止余额操纵攻击 | | 赞成 / 反对 / 弃权 | 弃权计入法定人数，但不影响结果 | | 分层存储 | 实例存储用于配置，持久化存储用于提案/投票 | | 链上事件 | 促进链下索引和可审计性 | 完整的架构决策记录请参见 [docs/adr/](docs/adr/)。 ## 功能 - 创建包含标题、描述、法定人数和投票期限的治理提案 - 代币加权投票 — 投票权重等于投票时治理代币余额 - 赞成 / 反对 / 弃权，并强制执行法定人数和多数决 - 防止重复投票 — 每个地址对每个提案只能投票一次 - 生命周期管理：`Active → Passed/Rejected → Executed`，或 `Cancelled` - 每次状态转换都有链上事件 - 管理员控制：暂停/恢复、更新法定人数、转移管理员 - 提案冷却期和最低余额要求 ## 快速开始 **前置条件：** Rust 1.75+，`wasm32-unknown-unknown` 目标，Docker（可选） ``` # 克隆 git clone https://github.com/DevKingOche/pulsegov.git cd pulsegov # 添加 WASM 目标 rustup target add wasm32-unknown-unknown # 运行所有测试 make test # 构建 WASM 二进制文件 make build # 查看文档 cargo doc --no-deps --open ``` 完整的逐步指南请参见 [SETUP.md](SETUP.md)。 ## 项目结构 ``` pulsegov/ ├── contracts/ │ ├── governance/ # Governance contract │ │ └── src/ │ │ ├── lib.rs # Contract implementation │ │ ├── storage.rs # Storage accessors & tier strategy │ │ ├── events.rs # Event emission │ │ ├── types.rs # Error types & data structures │ │ ├── test.rs # Unit tests (40+ tests) │ │ ├── test_helpers.rs │ │ └── prop_tests.rs # Property-based tests │ └── token/ # SEP-41-compatible token contract │ └── src/ │ ├── lib.rs │ ├── storage.rs │ ├── events.rs │ ├── types.rs │ └── test.rs # Unit tests (20+ tests) ├── docs/ │ ├── adr/ # Architecture Decision Records │ ├── security/ # Threat model, known issues, audit scope │ └── examples/ # Rust & JS integration examples ├── scripts/ │ ├── deploy.sh # Deploy to local/testnet │ ├── deploy_mainnet.sh # Deploy to mainnet │ └── test_wasm.sh # WASM build verification ├── config/ │ ├── local.toml │ ├── testnet.toml │ └── mainnet.toml ├── frontend/ # React + Vite proposal browser (read-only) ├── Cargo.toml # Workspace manifest ├── Makefile ├── Dockerfile ├── docker-compose.yml └── .env.example ``` ## 治理合约 ### 初始化 ``` pub fn initialize( env: Env, admin: Address, voting_token: Address, min_proposal_balance: i128, proposal_cooldown: u64, restrict_admin_vote: bool, ) -> Result<(), ContractError> ``` ### 核心函数 | 函数 | 描述 | |---|---| | `create_proposal(proposer, title, description, quorum, duration)` | 创建新提案 | | `cast_vote(voter, proposal_id, vote)` | 投票赞成/反对/弃权 | | `finalise(proposal_id)` | 在投票期结束后最终确定（任何人都可调用） | | `execute(admin, proposal_id)` | 将已通过的提案标记为已执行 | | `cancel(admin, proposal_id)` | 取消活动提案 | | `update_quorum(admin, proposal_id, new_quorum)` | 调整活动提案的法定人数 | | `transfer_admin(admin, new_admin)` | 转移管理员权限 | | `pause(admin)` / `unpause(admin)` | 紧急暂停 | ### 通过条件 ``` total_votes = votes_yes + votes_no + votes_abstain Passed if total_votes >= quorum AND votes_yes > votes_no Rejected otherwise ``` 弃权计入法定人数但不影响结果。平局（赞成 == 反对）将导致提案被否决。 ## 代币合约 符合 SEP-41 标准的治理代币，支持标准操作： | 函数 | 描述 | |---|---| | `initialize(admin, initial_supply)` | 部署并设置初始供应量 | | `balance(owner)` / `total_supply()` | 查询余额 | | `transfer(from, to, amount)` | 转移代币 | | `approve(owner, spender, amount)` | 授予花费额度 | | `transfer_from(spender, from, to, amount)` | 代表他人花费 | | `mint(admin, to, amount)` | 铸造新代币（仅限管理员） | | `burn(admin, from, amount)` | 销毁代币（仅限管理员） | ## 提案生命周期 ``` ┌──────────────┐ │ Active │ └──────────────┘ │ ┌──────────┼──────────┐ ▼ ▼ ▼ ┌────────┐ ┌────────┐ ┌──────────┐ │ Passed │ │Rejected│ │Cancelled │ └────────┘ └────────┘ └──────────┘ │ ▼ ┌──────────┐ │ Executed │ └──────────┘ ``` 完整的状态转换表请参见 [docs/lifecycle.md](docs/lifecycle.md)。 ## 存储模型 | 层级 | 键 | 用途 | |---|---|---| | 实例 | Admin, VotingToken, ProposalCount, ... | 合约级配置，读取成本低 | | 持久化 | Proposal(id), HasVoted(id, voter), VoteRecord(id, voter) | 每个提案/投票者数据 | | 临时 | Allowance(owner, spender) | 短期的额度 | 完整详情请参见 [docs/storage.md](docs/storage.md)。 ## 配置 将 `.env.example` 复制为 `.env` 并配置： ``` cp .env.example .env ``` | 变量 | 描述 | |---|---| | `NETWORK` | `local`、`testnet` 或 `mainnet` | | `STELLAR_RPC_URL` | Soroban RPC 端点 | | `STELLAR_NETWORK_PASSPHRASE` | 网络口令 | | `STELLAR_SECRET_KEY` | 部署者密钥 | | `GOVERNANCE_CONTRACT_ID` | 已部署的治理合约地址 | | `TOKEN_CONTRACT_ID` | 已部署的代币合约地址 | ## 开发 ### 不使用 Docker ``` rustup target add wasm32-unknown-unknown make test # Run all tests make build # Build WASM make lint # Clippy make fmt # Format ``` ### 使用 Docker ``` docker compose up # Start dev + local Stellar node docker compose run --rm dev make test # Run tests in container docker compose run --rm dev make build # Build WASM in container ``` ### Makefile 目标 | 目标 | 描述 | |---|---| | `make test` | 运行所有单元测试和属性测试 | | `make build` | 构建 WASM 二进制文件 | | `make lint` | 运行 Clippy（警告视为错误） | | `make fmt` | 使用 rustfmt 格式化代码 | | `make fmt-check` | 检查格式化 | | `make clean` | 清除构建产物 | | `make doc` | 生成并打开文档 | | `make wasm` | 通过 stellar CLI 构建优化的 WASM | | `make test-wasm` | 验证 WASM 构建 | ## 测试 ``` # 所有测试 make test # 包含输出 cargo test -- --nocapture # 特定测试 cargo test test_create_proposal -- --nocapture # 仅基于属性的测试 cargo test prop_ --all # 特定合约 cargo test -p pulsegov-governance cargo test -p pulsegov-token ``` **覆盖率：** 两个合约共 60 多个测试，涵盖提案创建、投票机制、最终确定、管理员操作、访问控制和边缘情况。 ## 安全 - 所有状态变更操作均使用 `require_auth()` - 通过持久化的 `HasVoted` 标志防止重复投票 - 投票权重快照防止余额操纵 - 最终确定时强制执行法定人数 - 可选的管理员投票限制 - 合约暂停/恢复机制 - 所有金额使用 `i128`（无浮点数） - `checked_add` 防止算术溢出 漏洞披露政策请参见 [SECURITY.md](SECURITY.md)，完整威胁模型请参见 [docs/security/](docs/security/)。 ## 贡献指南 欢迎贡献。在提交 PR 之前，请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。 快速检查清单： 1. Fork 并创建一个功能分支 2. 进行更改并附带测试 3. `make test && make lint && make fmt-check` 4. 提交拉取请求 ## 资源 - [SETUP.md](SETUP.md) — 本地设置逐步指南 - [CONTRIBUTING.md](CONTRIBUTING.md) — 贡献指南 - [SECURITY.md](SECURITY.md) — 安全政策 - [AUDIT.md](AUDIT.md) — 审计报告 - [CHANGELOG.md](CHANGELOG.md) — 版本历史 - [docs/adr/](docs/adr/) — 架构决策记录 - [docs/examples/](docs/examples/) — Rust 和 JS 集成示例 - [Stellar 文档](https://developers.stellar.org) — Stellar 区块链文档 - [Soroban SDK](https://docs.rs/soroban-sdk) — Rust SDK 参考 - [SEP-41](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0041.md) — Stellar 代币标准 ## 技术栈 | 层 | 技术 | 版本 | |---|---|---| | 区块链 | Stellar (Soroban) | 协议 22+ | | 语言 | Rust | 1.75+ | | SDK | soroban-sdk | 22.0.0 | | 构建目标 | WebAssembly | wasm32-unknown-unknown | | 测试 | soroban-sdk testutils | 22.0.0 | | 属性测试 | proptest | 1.6.0 | | CI/CD | GitHub Actions | 最新版本 | ## 许可证 Apache 2.0 — 请参见 [LICENSE](LICENSE)。 *使用 ❤️ 在 Stellar 上构建*

标签：AI工具, DAO, Soroban, Stellar, 不可变记录, 代币加权, 区块链, 区块链技术, 去中心化治理, 去中心化自治组织, 可视化界面, 审计跟踪, 投票系统, 提案管理, 智能合约, 智能合约开发, 治理协议, 法定人数, 社区治理, 经济激励, 透明决策, 通知系统, 链上治理