Soroban-shield/soroban-shield-contracts

# soroban-shield-合约 [](https://www.drips.network/wave/stellar) [](https://www.rust-lang.org/) [](LICENSE) [](.github/workflows/ci.yml) ## 概述 `soroban-shield-contracts` 是 Soroban Shield 组织的核心。它提供了一系列安全、可重用的 Rust 智能合约模块，可通过 Soroban 部署在 Stellar 区块链上。每个模块都是自包含的、文档齐全的，并设计为可以与其他模块组合使用。 ## 文件结构 ``` soroban-shield-contracts/ │ ├── Cargo.toml # Workspace manifest ├── Cargo.lock ├── README.md # This file ├── CONTRIBUTING.md # Contribution guidelines (mirrors org root) ├── LICENSE ├── CODEOWNERS ├── .gitignore │ ├── .github/ │ ├── workflows/ │ │ ├── ci.yml # Build, test, clippy, fmt on every PR │ │ └── release.yml # Publish crate on tag push │ └── ISSUE_TEMPLATE/ │ ├── bug_report.md │ ├── feature_request.md │ └── stellar_wave_task.md # Template for Wave-scoped issues │ ├── src/ │ ├── lib.rs # Crate root — re-exports all modules │ │ │ ├── contracts/ │ │ ├── mod.rs │ │ │ │ │ ├── ownable/ │ │ │ ├── mod.rs # Ownable contract: single-owner with 2-step transfer │ │ │ ├── contract.rs # #[contract] impl │ │ │ ├── interface.rs # Trait definition │ │ │ └── test.rs # Unit tests │ │ │ │ │ ├── access_control/ │ │ │ ├── mod.rs # Role-based access control (RBAC) │ │ │ ├── contract.rs │ │ │ ├── interface.rs │ │ │ ├── roles.rs # Role constants and helpers │ │ │ └── test.rs │ │ │ │ │ ├── pausable/ │ │ │ ├── mod.rs # Emergency pause / unpause with role gate │ │ │ ├── contract.rs │ │ │ ├── interface.rs │ │ │ └── test.rs │ │ │ │ │ ├── reentrancy_guard/ │ │ │ ├── mod.rs # Cross-contract reentrancy protection │ │ │ ├── contract.rs │ │ │ ├── interface.rs │ │ │ └── test.rs │ │ │ │ │ ├── rate_limiter/ │ │ │ ├── mod.rs # Per-address call throttling with sliding window │ │ │ ├── contract.rs │ │ │ ├── interface.rs │ │ │ ├── window.rs # Sliding window logic │ │ │ └── test.rs │ │ │ │ │ ├── multi_sig/ │ │ │ ├── mod.rs # N-of-M signature threshold execution │ │ │ ├── contract.rs │ │ │ ├── interface.rs │ │ │ ├── proposal.rs # Proposal lifecycle types │ │ │ └── test.rs │ │ │ │ │ └── upgradeable/ │ │ ├── mod.rs # WASM proxy upgrade pattern for Soroban │ │ ├── contract.rs │ │ ├── interface.rs │ │ ├── proxy.rs # Proxy delegation logic │ │ └── test.rs │ │ │ ├── types/ │ │ ├── mod.rs │ │ ├── address.rs # Shared address wrapper types │ │ ├── role.rs # Generic role type definitions │ │ └── proposal.rs # Shared proposal types for multi-sig │ │ │ ├── events/ │ │ ├── mod.rs │ │ ├── ownable.rs # OwnershipTransferred, OwnershipTransferStarted │ │ ├── access_control.rs # RoleGranted, RoleRevoked │ │ ├── pausable.rs # Paused, Unpaused │ │ └── multi_sig.rs # ProposalCreated, ProposalExecuted, ProposalCancelled │ │ │ └── errors/ │ ├── mod.rs │ ├── access.rs # Unauthorized, RoleNotFound, etc. │ ├── pausable.rs # ContractPaused, ContractNotPaused │ ├── rate_limiter.rs # RateLimitExceeded, WindowTooShort │ └── multi_sig.rs # QuorumNotMet, ProposalExpired, etc. │ ├── tests/ │ ├── unit/ │ │ ├── ownable_test.rs │ │ ├── access_control_test.rs │ │ ├── pausable_test.rs │ │ ├── reentrancy_guard_test.rs │ │ ├── rate_limiter_test.rs │ │ ├── multi_sig_test.rs │ │ └── upgradeable_test.rs │ │ │ └── integration/ │ ├── ownable_pausable_test.rs # Composability: Ownable + Pausable │ ├── access_multi_sig_test.rs # Composability: AccessControl + MultiSig │ └── full_stack_test.rs # All modules composed together │ └── scripts/ ├── build.sh # cargo build --target wasm32-unknown-unknown ├── test.sh # cargo test + fmt + clippy └── deploy_testnet.sh # soroban contract deploy to testnet ``` ## 模块 ### `Ownable` 具有安全两步所有权转移的单所有者合约。待定所有者必须在所有权变更前明确接受。 **关键函数：** `initialize(owner)`, `transfer_ownership(new_owner)`, `accept_ownership()`, `renounce_ownership()`, `owner()` ### `AccessControl` 基于角色的访问控制。角色以 `Symbol` 为键，可被授予、撤销和查询。支持角色管理员。 **关键函数：** `grant_role(role, account)`, `revoke_role(role, account)`, `has_role(role, account)`, `set_role_admin(role, admin_role)` ### `Pausable` 紧急中断开关。当暂停时，受保护的函数将回退。可与 `AccessControl` 集成，实现基于角色的暂停控制。 **关键函数：** `pause()`, `unpause()`, `is_paused()` ### `ReentrancyGuard` 防止在单个合约执行内进行重入调用。使用 Soroban 账本存储作为锁定机制。 **关键函数：** `enter()`, `exit()` — 通常用作包裹函数体的守卫。 ### `RateLimiter` 使用可配置滑动窗口的按地址调用节流。用于防止垃圾信息或滥用。 **关键函数：** `configure(max_calls, window_seconds)`, `check_and_record(caller)`, `reset(caller)` ### `MultiSig` 用于执行特权操作的 M 选 N 签名阈值。提案在可配置的 TTL 后过期。 **关键函数：** `create_proposal(action, expiry)`, `approve(proposal_id)`, `execute(proposal_id)`, `cancel(proposal_id)` ### `Upgradeable` 兼容 Soroban 合约部署模型的 WASM 代理升级模式。存储当前实现哈希并委托调用。 **关键函数：** `upgrade(new_wasm_hash)`, `current_implementation()`, `lock_upgrades()` ## 入门指南 ### 前置条件 ``` # 安装 Rust 工具链 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # 添加 WASM 目标 rustup target add wasm32-unknown-unknown # 安装 Soroban CLI cargo install --locked soroban-cli ``` ### 构建 ``` git clone https://github.com/soroban-shield/soroban-shield-contracts cd soroban-shield-contracts cargo build --target wasm32-unknown-unknown --release ``` ### 测试 ``` cargo test cargo fmt --all -- --check cargo clippy -- -D warnings ``` ### 在您的项目中使用模块 添加到您的 `Cargo.toml`： ``` [dependencies] soroban-shield-contracts = { git = "https://github.com/soroban-shield/soroban-shield-contracts", tag = "v0.1.0" } ``` 示例 — 将 `Ownable` 添加到您的合约： ``` use soroban_shield_contracts::contracts::ownable::interface::OwnableInterface; #[contract] pub struct MyContract; #[contractimpl] impl MyContract { pub fn sensitive_action(env: Env) { // Restricts to owner only ownable::only_owner(&env); // ... your logic } } ``` ## Stellar Wave — 开放性议题 本仓库参与 **Stellar Wave 计划**。标记为 `Stellar Wave` 的议题可供社区贡献者申请，并有机会获得 USDC 奖励。 浏览开放的 Wave 议题：[github.com/soroban-shield/soroban-shield-contracts/issues](https://github.com/soroban-shield/soroban-shield-contracts/issues?q=label%3A%22Stellar+Wave%22) 通过 Wave 做出贡献： 1. 在 [drips.network/wave/stellar](https://www.drips.network/wave/stellar) 登录 2. 在此仓库中找到一个议题并点击 **申请** 3. 等待分配 — 在分配前请勿开始 4. 提交一个引用该议题的 PR **积分：** 简单 = 100 分 | 中等 = 150 分 | 高难 = 200 分 ## 许可证 MIT — 详见 [LICENSE](LICENSE)

标签：dApp 开发, DNS解析, Golang, Rust 编程语言, SOC Prime, Soroban 智能合约平台, Stellar 区块链, 代码复用, 分布式账本, 加密货币, 区块链开发, 去中心化应用, 可视化界面, 可重用组件, 安全编程, 开发工具, 开源项目, 智能合约, 核心库, 模块化设计, 生态系统工具, 自动化修复, 通知系统