Oby38/syncwise-audit-ledger

# 去中心化审计与透明度账本 一个用于在 Stellar 网络上不可变地记录金融交易的 Soroban 智能合约，提供公开可验证的审计追踪。使用 [Soroban SDK](https://soroban.stellar.org/) 构建。 ## 概述 `AuditLedger` 作为一个仅可追加的日志，用于记录金融和运营事件。每个条目都封装了时间戳、事件类型（`Symbol`）和提交者地址（`Address`），从而生成一份防篡改的历史记录，任何一方都可以独立验证。可配置的全局和按事件日志记录限制可防止状态膨胀，同时维护完整、有序的历史记录。 ## 核心功能 - **不可变事件记录** — 每个事件都通过标准化的 `Event` 结构体记录在链上，创建永久的审计追踪。 - **可配置的日志记录限制** — 独立的全局和按事件类型上限（`u32`）可防止合约状态垃圾信息。上限可以设置为任何值（包括 `0` 以冻结日志记录），或者通过 `remove_event_cap` 完全移除。 - **公开可验证性** — 任何人都可以枚举和验证完整的日志历史记录，或者按事件类型进行过滤 — 无需受信任的第三方介入。 - **元数据标准化** — 事件携带不透明的 `Bytes` 元数据，鼓励链下消费者采用一致的 schema。 - **边界安全验证** — 合约逻辑针对边缘情况进行了强化：零最大值配置、相等的最小/最大值范围、空元数据以及移除上限。 ## 智能合约架构 | 组件 | 描述 | |-----------|-------------| | **全局日志注册表** | 所有事件的顺序数组，受 `global_max_logs` 限制。 | | **按事件子账本** | 命名空间化的事件类型（`Symbol`），每个都具有可选的独立最大日志限制。 | | **上限控制门** | `event_cap_set` 布尔值控制每个事件的执行 — 上限是可选的，可以通过 `remove_event_cap` 移除。 | ### 事件结构 ``` pub struct Event { pub index: u32, pub timestamp: u64, pub event_type: Symbol, pub submitter: Address, pub metadata: Bytes, } ``` ## API 参考 ### 写入 ``` fn initialize(env: Env, owner: Address, global_max_logs: u32); fn log_event(env: Env, submitter: Address, event_type: Symbol, metadata: Bytes) -> u32; ``` ### 读取 ``` fn total_events(env: Env) -> u32; fn get_event(env: Env, index: u32) -> Event; fn event_count(env: Env, event_type: Symbol) -> u32; fn get_event_by_type(env: Env, event_type: Symbol, type_index: u32) -> Event; ``` ### 治理（仅限所有者） ``` fn set_global_max_logs(env: Env, caller: Address, new_max: u32); fn set_event_max_logs(env: Env, caller: Address, event_type: Symbol, new_max: u32); fn remove_event_cap(env: Env, caller: Address, event_type: Symbol); fn transfer_ownership(env: Env, caller: Address, new_owner: Address); ``` ## 快速开始 ``` # Build cargo build # 运行所有 tests cargo test # Format cargo fmt # Lint cargo clippy ``` ## 开发 ### 前置条件 - Rust 工具链（通过 [rustup](https://rustup.rs/) 安装） - Soroban SDK（作为 Cargo 依赖项包含） ### 编译为 WASM ``` cargo build --target wasm32-unknown-unknown --release ``` ### 使用 Soroban CLI 部署 ``` soroban contract deploy \ --wasm target/wasm32-unknown-unknown/release/audit_ledger.wasm \ --source \ --network testnet ``` ### 初始化 ``` soroban contract invoke \ --id \ --source \ --network testnet \ -- \ initialize \ --owner \ --global_max_logs 100000 ``` ## 测试覆盖率（22 个测试） | 测试文件 | 数量 | 描述 | |-----------|-------|-------------| | `src/test.rs` | 22 | 日志记录、查询、治理、所有权转移、上限管理、事件发射、空元数据、访问控制、边界条件 | 边界测试包括：零全局/事件最大日志数、将最大值设置为当前计数值、在零锁定后移除上限、混合多类型限制，以及在不存在时触发 panic 的访问。 ## CI/CD 每次推送和 pull request 都会触发一个 GitHub Actions 工作流，它会： 1. 通过 `dtolnay/rust-toolchain` 安装 Rust 工具链 2. 使用 `cargo fmt --check` 检查格式 3. 使用 `cargo clippy` 进行代码检查 4. 使用 `cargo build` 进行构建 5. 使用 `cargo test` 运行完整的测试套件 ## 许可证 [MIT](LICENSE)

标签：Rust, Soroban, Stellar, 区块链, 可视化界面, 审计日志, 智能合约, 网络流量审计, 通知系统