soroban-compliance-contracts/soroban-compliance-primitives

# soroban-compliance 原语 用于 Stellar 网络上受监管资产合规性的核心 Soroban 智能合约库。提供可审计、可组合的原语，用于管理允许列表、转账限制、KYC 认证以及链上审计日志。 此库是 [`soroban-compliance-adapters`](https://github.com/soroban-compliance-contracts/soroban-compliance-adapters) 的基础层，后者将这些原语连接到现实世界的 KYC 提供商和 SEP-8 受监管资产标准。 ## 模块 ### `允许列表` 地址的管理员控制允许列表和拒绝列表。任何代币合约都可以组合此模块来限制谁被允许发送或接收资产。 - `add(address)` / `remove(address)` — 仅限管理员操作 - `deny(address)` / `undeny(address)` — 仅限管理员操作 - `is_permitted(address) -> bool` — 根据两个列表检查地址是否被允许 ### `转让限制` 可组合的钩子，在资金实际转移之前，在合约层面强制执行转账规则。 - 锁定期 — 在指定的账本时间戳之前阻止转账 - 司法辖区阻止 — 阻止两个已标记地址对之间的转账 - 每地址限额 — 限制每笔交易或滚动时间窗口内的转账金额 ### `证明` 用于 KYC 认证预言机的标准 Soroban trait，以及一个用于本地测试的模拟实现。 ``` pub trait AttestationOracle { fn attest(env: &Env, address: Address) -> AttestationStatus; fn get_expiry(env: &Env, address: Address) -> u64; fn revoke(env: &Env, address: Address); } ``` `AttestationStatus` 变体：`Verified`（已验证）、`Pending`（待处理）、`Revoked`（已撤销）、`NotFound`（未找到）。 具体的预言机实现位于 [`soroban-compliance-adapters`](https://github.com/soroban-compliance-contracts/soroban-compliance-adapters) 中。 ### `事件记录器` 针对每个合规相关操作的结构化 Soroban 事件发出。所有事件都包含账本时间戳、操作地址和操作类型枚举。 | 事件 | 触发时机 | |---|---| | `address_allowed` | 地址被添加到允许列表 | | `address_denied` | 地址被添加到拒绝列表 | | `transfer_blocked` | 转账被限制钩子拒绝 | | `attestation_checked` | 查询地址的预言机认证状态 | | `attestation_revoked` | 地址的 KYC 状态被撤销 | ## 快速开始 ### 前置条件 - Rust `1.74+` - [`soroban-cli`](https://developers.stellar.org/docs/tools/developer-tools/cli/stellar-cli) - 一个有资金的 Stellar 测试网账户 ### 安装 将以下内容添加到您的 `Cargo.toml`： ``` [dependencies] soroban-compliance-primitives = { git = "https://github.com/soroban-compliance-contracts/soroban-compliance-primitives" } ``` ### 构建 ``` make build ``` ### 测试 ``` make test ``` ### 模糊测试 ``` make fuzz ``` 模糊测试目标使用 `cargo-fuzz` 覆盖允许列表和转账限制逻辑。 ### 部署到测试网 ``` make deploy-testnet ``` 需要在环境中设置 `STELLAR_SECRET_KEY`。此命令将所有合约部署到 Stellar 测试网并打印其合约 ID。 ## 使用示例 将允许列表和转账限制组合到一个代币合约中： ``` use soroban_compliance_primitives::{allowlist, transfer_restrictions, event_logger}; pub fn transfer(env: Env, from: Address, to: Address, amount: i128) { from.require_auth(); // Check allowlist if !allowlist::is_permitted(&env, &from) || !allowlist::is_permitted(&env, &to) { event_logger::emit_transfer_blocked(&env, &from, &to, "allowlist"); panic!("transfer not permitted"); } // Check transfer restrictions transfer_restrictions::enforce(&env, &from, &to, amount); // Proceed with transfer token::internal_transfer(&env, &from, &to, amount); } ``` ## 项目结构 ``` src/ allowlist.rs # Allowlist and denylist contract transfer_restrictions.rs # Transfer restriction hooks attestation.rs # KYC attestation trait and mock event_logger.rs # Compliance event emission lib.rs # Re-exports all modules fuzz/ fuzz_targets/ allowlist.rs transfer_restrictions.rs Makefile Cargo.toml ``` ## Makefile 目标 | 目标 | 描述 | |---|---| | `make build` | 编译所有合约 | | `make test` | 运行单元测试 | | `make fuzz` | 通过 cargo-fuzz 运行模糊测试目标 | | `make deploy-testnet` | 将合约部署到 Stellar 测试网 | ## 设计原则 **默认可审计。** 每个合规操作都会发出结构化的链上事件。不存在静默拒绝的情况。 **可组合，而非固执己见。** 每个模块都是独立的。仅使用您的代币合约所需的部分。 **无外部依赖。** 仅依赖 `soroban-sdk` 和 Rust 标准库。这使得审计面保持较小。 **管理员分离。** 所有可变函数都需要一个在初始化时设置的管理员地址，该地址存储在合约实例存储中。 ## 相关项目 - [`soroban-compliance-adapters`](https://github.com/soroban-compliance-contracts/soroban-compliance-adapters) — KYC 预言机适配器、SEP-8 集成、示例代币合约以及基于此库构建的 CLI 工具 - [Soroban 文档](https://developers.stellar.org/docs/build/smart-contracts/overview) - [SEP-8: 受监管资产](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0008.md) - [Drips 上的 Stellar Wave](https://www.drips.network/wave/stellar) ## 许可证 Apache 2.0

标签：KYC认证, SEP-8, Soroban, Stellar网络, 允许名单, 区块链, 去中心化金融, 可视化界面, 合规, 审计日志, 智能合约, 监管科技, 资产合规, 转账限制, 通知系统, 金融科技, 链上审计