zkml-soroban

面向 Stellar 的可证明 ML 推理运行时

zkml-soroban 是第一个支持在链下执行小型机器学习模型，并通过 Soroban 智能合约在 Stellar 网络上以密码学方式验证其推理正确性的运行时。 该项目利用了 Stellar Protocol 25 (X-Ray) 中引入的零知识密码学原语——特别是 BN254 椭圆曲线操作 (CAP-0074) 和 Poseidon 哈希函数 (CAP-0075)——构建了一条从模型导入到链上证明验证的完整 pipeline。 ## 目录 - [动机](#motivation) - [架构概述](#architecture-overview) - [支持的模型](#supported-models) - [技术栈](#technology-stack) - [项目结构](#project-structure) - [快速开始](#getting-started) - [开发状态](#development-status) - [文档](#documentation) - [贡献](#contributing) - [许可证](#license) ## 动机 机器学习模型在金融系统中越来越多地驱动着高风险决策：信用评分、风险评估和合规检查。然而，这些决策通常是不透明的——用户和交易对手无法验证所声称的 ML 输出确实是由特定模型在特定输入上产生的。 零知识证明解决了这个问题。证明者可以证明某个 ML 推理已被正确执行，而无需透露模型权重或输入数据。验证者（Stellar 上的智能合约）只需通过一次低成本的密码学校验即可确认其正确性。 Stellar 在该应用场景中具备独特的优势： - **原生 ZK 原语**：Protocol 25 引入了 BN254 和 Poseidon 宿主函数，支持直接在链上进行高效的 Groth16 证明验证。 - **机构级锚点**：Stellar 拥有庞大的受监管锚点和汇款通道网络，使得可证明的合规评分成为实际用例，而非仅仅停留在理论层面。 - **低成本验证**：Soroban 合约的执行成本比同类的 EVM 链低几个数量级，使得对于高频应用，链上验证在经济上具有可行性。 ## 架构概述 系统主要由两个核心组件构成： ``` Off-chain On-chain +-------------------+ +-------------------+ | | | | ONNX Model | zkml-prover | Groth16 | zkml-verifier | ----------->| | proof | | | 1. Import model |------------>| 1. Verify proof | Input Data | 2. Quantize | | 2. Check inputs | ----------->| 3. Run inference | | 3. Record result | | 4. Generate proof| | | +-------------------+ +-------------------+ | | v v zkml-common Stellar Ledger (shared types & structures) (immutable record) ``` 有关详细的架构说明，请参阅 [docs/architecture.md](docs/architecture.md)。 ## 支持的模型 | 模型类型 | 状态 | 电路复杂度 | 主要用例 | | ------------------- | ------- | ------------------ | --------------------- | | 决策树 | Phase 1 | 低 | KYC 风险评分 | | 逻辑回归 | Phase 1 | 低 | 二元分类 | | 微型 MLP (ReLU) | Phase 2 | 中 | 多类评分 | 所有模型均从 ONNX 格式导入，并量化为定点算术，以兼容 ZK 电路约束。 ## 技术栈 ### 链下证明者 | 组件 | 技术 | 用途 | | ----------------- | ------------------------- | ----------------------------------- | | 语言 | Rust | 性能优势，ZK 生态支持 | | 模型格式 | ONNX | 与 PyTorch, scikit-learn 互操作 | | 算术 | 定点数 (Q16.16) | 兼容 ZK 的数字表示 | | 证明系统 | RISC Zero zkVM (Phase 1) | Groth16 证明生成 | | 电路框架 | bellman / halo2 (Phase 2) | 原生 ML 电路 | ### 链上验证者 | 组件 | 技术 | 用途 | | ---------------- | ------------------------ | ---------------------------------- | | 平台 | Soroban (Stellar) | 智能合约执行 | | 编译 | Rust 编译为 WASM | 合约部署 | | 曲线操作 | BN254 宿主函数 | Groth16 配对检查 (CAP-0074) | | 哈希承诺 | Poseidon 宿主函数 | 模型/输入绑定 (CAP-0075) | ## 项目结构 ``` zkml-soroban/ ├── Cargo.toml Root workspace manifest ├── README.md ├── LICENSE Apache 2.0 ├── CONTRIBUTING.md Contribution guidelines ├── SECURITY.md Security policy ├── .gitignore │ ├── crates/ │ ├── zkml-common/ Shared types and utilities │ │ └── src/ │ │ ├── lib.rs │ │ ├── fixed_point.rs Fixed-point arithmetic │ │ ├── models.rs Model representations │ │ └── proof.rs Proof data structures │ │ │ ├── zkml-prover/ Off-chain prover │ │ └── src/ │ │ ├── lib.rs │ │ ├── inference.rs Model inference engine │ │ ├── onnx.rs ONNX model importer │ │ ├── prover.rs ZK proof generation │ │ └── quantization.rs Weight quantization │ │ │ └── zkml-verifier/ On-chain Soroban contract │ └── src/ │ └── lib.rs Verification contract │ └── docs/ ├── architecture.md System architecture ├── diagrams.md Technical diagrams ├── roadmap.md Development roadmap ├── technical-overview.md ZK primitives and stack details └── use-cases.md Target use cases ``` ## 快速开始 ### 前置条件 - [Rust](https://rustup.rs/) (stable, 1.79 或更高版本) - [Stellar CLI](https://developers.stellar.org/docs/build/smart-contracts/getting-started/setup) - wasm32-unknown-unknown target: rustup target add wasm32-unknown-unknown ### 构建 ``` # 构建所有 workspace crates cargo build # 构建用于部署的 verifier contract cargo build --release --target wasm32-unknown-unknown -p zkml-verifier # 运行所有测试 cargo test --workspace ``` ### 快速运行 ``` # Clone 该 repository git clone https://github.com/diegoveme/ZKML-Soroban.git cd ZKML-Soroban # 构建该项目 cargo build # 运行测试 cargo test --workspace ``` ## 开发状态 本项目正处于活跃的早期开发阶段。 | 阶段 | 描述 | 状态 | | ------- | ------------------------------- | ----------- | | Phase 1 | 包含 RISC Zero 证明者的 MVP | 进行中 | | Phase 2 | 原生 BN254 + Poseidon 电路 | 已规划 | | Phase 3 | SDK 及生态集成 | 已规划 | 有关完整的开发路线图，请参阅 [docs/roadmap.md](docs/roadmap.md)。 ## 文档 | 文档 | 描述 | | -------------------------------------------- | -------------------------------------- | | [架构](docs/architecture.md) | 系统设计与组件分解 | | [技术概述](docs/technical-overview.md) | ZK 原语、技术栈和设计细节 | | [图表](docs/diagrams.md) | 可视化系统与流程图 | | [路线图](docs/roadmap.md) | 分阶段开发计划 | | [用例](docs/use-cases.md) | Stellar 上的目标应用 | ## 许可证 本项目基于 Apache License 2.0 授权。有关完整文本，请参阅 [LICENSE](LICENSE)。 ## 致谢 - [Stellar Development Foundation](https://stellar.org/) 提供的 ZK 原生协议升级 (CAP-0074, CAP-0075)。 - [Nethermind](https://nethermind.io/) 在 Soroban 上部署的 RISC Zero zkVM 以及 `stellar-zk` 参考实现。 - [RISC Zero](https://risczero.com/) 提供的通用 zkVM。 ## 更多文档 完整的文档索引可在 [docs/README.md](docs/README.md) 中查看， 内容涵盖模型格式、承诺、证明 pipeline、验证者接口、威胁模型和测试指南。 ## 状态更新 (2026 年 6 月) 针对支持的模型系列，链下 pipeline 和链上接口的功能已开发完成，并由测试套件进行了验证。Phase 1 剩余的工作是密码学集成（RISC Zero 证明和 BN254 配对检查），相关进度已在[路线图](docs/roadmap.md)中追踪。

标签：CNCF毕业项目, Rust, Stellar, 区块链, 可视化界面, 智能合约, 机器学习推理, 网络流量审计, 通知系统, 零知识证明