A Provable ML Inference Runtime for Stellar
zkml-soroban is the first runtime that enables executing small machine learning models off-chain and cryptographically verifying the correctness of their inference on the Stellar network through Soroban smart contracts.
The project leverages the zero-knowledge cryptographic primitives introduced in Stellar Protocol 25 (X-Ray) -- specifically BN254 elliptic curve operations (CAP-0074) and Poseidon hash functions (CAP-0075) -- to build a complete pipeline from model import to on-chain proof verification.
- Motivation
- Architecture Overview
- Supported Models
- Technology Stack
- Project Structure
- Getting Started
- Development Status
- Documentation
- Contributing
- License
Machine learning models increasingly drive high-stakes decisions in financial systems: credit scoring, risk assessment, and compliance checks. However, these decisions are typically opaque -- users and counterparties cannot verify that a claimed ML output was actually produced by a specific model on specific inputs.
Zero-knowledge proofs solve this problem. A prover can demonstrate that an ML inference was executed correctly without revealing the model weights or input data. The verifier (a smart contract on Stellar) confirms correctness with a single, cheap cryptographic check.
Stellar is uniquely positioned for this application:
- Native ZK primitives: Protocol 25 introduced BN254 and Poseidon host functions, enabling efficient Groth16 proof verification directly on-chain.
- Institutional anchors: Stellar has the largest network of regulated anchors and remittance corridors, making provable compliance scoring a practical use case rather than a theoretical exercise.
- Low-cost verification: Soroban contract execution costs are orders of magnitude lower than comparable EVM chains, making on-chain verification economically viable for high-volume applications.
The system consists of two primary components:
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)
For a detailed architecture description, see docs/architecture.md.
| Model Type | Status | Circuit Complexity | Primary Use Case |
|---|---|---|---|
| Decision Tree | Phase 1 | Low | KYC risk scoring |
| Logistic Regression | Phase 1 | Low | Binary classification |
| Tiny MLP (ReLU) | Phase 2 | Medium | Multi-class scoring |
All models are imported from the ONNX format and quantized to fixed-point arithmetic for compatibility with ZK circuit constraints.
| Component | Technology | Purpose |
|---|---|---|
| Language | Rust | Performance, ZK ecosystem support |
| Model format | ONNX | Interop with PyTorch, scikit-learn |
| Arithmetic | Fixed-point (Q16.16) | ZK-compatible number representation |
| Proof system | RISC Zero zkVM (Phase 1) | Groth16 proof generation |
| Circuit framework | bellman / halo2 (Phase 2) | Native ML circuits |
| Component | Technology | Purpose |
|---|---|---|
| Platform | Soroban (Stellar) | Smart contract execution |
| Compilation | Rust to WASM | Contract deployment |
| Curve operations | BN254 host functions | Groth16 pairing checks (CAP-0074) |
| Hash commitments | Poseidon host functions | Model/input binding (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 (stable, 1.79 or later)
- Stellar CLI
- wasm32-unknown-unknown target:
rustup target add wasm32-unknown-unknown
# Build all workspace crates
cargo build
# Build the verifier contract for deployment
cargo build --release --target wasm32-unknown-unknown -p zkml-verifier
# Run all tests
cargo test --workspace# Clone the repository
git clone https://github.com/diegoveme/ZKML-Soroban.git
cd ZKML-Soroban
# Build the project
cargo build
# Run tests
cargo test --workspaceThis project is in active early development.
| Phase | Description | Status |
|---|---|---|
| Phase 1 | MVP with RISC Zero prover | In Progress |
| Phase 2 | Native BN254 + Poseidon circuits | Planned |
| Phase 3 | SDK and ecosystem integration | Planned |
See docs/roadmap.md for the full development roadmap.
| Document | Description |
|---|---|
| Architecture | System design and component breakdown |
| Technical Overview | ZK primitives, stack, and design details |
| Diagrams | Visual system and flow diagrams |
| Roadmap | Phased development plan |
| Use Cases | Target applications on Stellar |
Contributions are welcome. Please read CONTRIBUTING.md for development setup, coding standards, and the pull request process.
For security vulnerabilities, follow the process described in SECURITY.md.
This project is licensed under the Apache License 2.0. See LICENSE for the full text.
- Stellar Development Foundation for the ZK-native protocol upgrades (CAP-0074, CAP-0075).
- Nethermind for the RISC Zero zkVM deployment on
Soroban and the
stellar-zkreference implementation. - RISC Zero for the general-purpose zkVM.
A full documentation index is available in docs/README.md, covering the model format, commitments, the proving pipeline, the verifier interface, the threat model, and the testing guide.
The off-chain pipeline and the on-chain interface are feature-complete for the supported model families and exercised by the test suite. The remaining Phase 1 work is the cryptographic integration (RISC Zero proving and the BN254 pairing check), tracked in the roadmap.