saorsa_logic/
lib.rs

1// Copyright 2024 Saorsa Labs Limited
2//
3// Licensed under the Apache License, Version 2.0 or MIT license, at your option.
4// This file may not be copied, modified, or distributed except according to those terms.
5
6//! # saorsa-logic
7//!
8//! Pure logic crate for the Saorsa network, designed for zkVM compatibility.
9//!
10//! This crate provides the core verification logic that can be executed inside
11//! zero-knowledge virtual machines (zkVMs) like SP1 or RISC Zero. All code is
12//! `no_std` compatible and deterministic.
13//!
14//! ## Design Philosophy
15//!
16//! The Saorsa network uses "Entangled Attestation" to ensure nodes run authorized
17//! software. This crate extracts the pure verification logic so that:
18//!
19//! 1. **zkVM Proofs**: Nodes can prove they computed their EntangledId correctly
20//! 2. **Data Verification**: Storage operations can be proven correct
21//! 3. **Determinism**: All operations are deterministic and reproducible
22//!
23//! ## Architecture
24//!
25//! ```text
26//! ┌─────────────────────────────────────────────────────────────────┐
27//! │                        saorsa-node                              │
28//! │  (Thin wrapper: CLI, config, auto-upgrade)                      │
29//! └────────────────────────────┬────────────────────────────────────┘
30//!                              │
31//! ┌────────────────────────────▼────────────────────────────────────┐
32//! │                        saorsa-core                              │
33//! │  (Networking, DHT, trust, storage coordination)                 │
34//! └────────────────────────────┬────────────────────────────────────┘
35//!                              │
36//! ┌────────────────────────────▼────────────────────────────────────┐
37//! │                       saorsa-logic                              │
38//! │  (Pure verification logic - THIS CRATE)                         │
39//! │  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐             │
40//! │  │ attestation  │ │    data      │ │   merkle     │             │
41//! │  │ (EntangledId)│ │ (hash, sig)  │ │  (proofs)    │             │
42//! │  └──────────────┘ └──────────────┘ └──────────────┘             │
43//! └─────────────────────────────────────────────────────────────────┘
44//!                              │
45//!                              ▼
46//!                    ┌─────────────────┐
47//!                    │  zkVM (SP1)     │
48//!                    │  Proves logic   │
49//!                    │  is correct     │
50//!                    └─────────────────┘
51//! ```
52//!
53//! ## Usage
54//!
55//! ### Native (with std)
56//!
57//! ```rust
58//! use saorsa_logic::attestation::{derive_entangled_id, verify_entangled_id};
59//!
60//! // Derive an entangled identity
61//! let public_key = [0u8; 1952]; // ML-DSA-65 public key
62//! let binary_hash = [1u8; 32];   // BLAKE3 hash of binary
63//! let nonce = 12345u64;
64//!
65//! let entangled_id = derive_entangled_id(&public_key, &binary_hash, nonce);
66//!
67//! // Verify the identity
68//! assert!(verify_entangled_id(&entangled_id, &public_key, &binary_hash, nonce));
69//! ```
70//!
71//! ### In zkVM (SP1)
72//!
73//! ```rust,ignore
74//! // In SP1 guest program
75//! use saorsa_logic::attestation::derive_entangled_id;
76//!
77//! // Read inputs from prover
78//! let public_key: [u8; 1952] = sp1_zkvm::io::read();
79//! let binary_hash: [u8; 32] = sp1_zkvm::io::read();
80//! let nonce: u64 = sp1_zkvm::io::read();
81//!
82//! // Compute EntangledId (this computation is proven)
83//! let entangled_id = derive_entangled_id(&public_key, &binary_hash, nonce);
84//!
85//! // Commit result to public outputs
86//! sp1_zkvm::io::commit(&entangled_id);
87//! ```
88//!
89//! ## Features
90//!
91//! - `std`: Enable standard library support (for native execution)
92//! - `alloc`: Enable heap allocation
93//! - `zkvm`: Generic zkVM optimizations
94//! - `sp1`: SP1-specific optimizations
95//! - `risc0`: RISC Zero-specific optimizations
96//!
97//! ## no_std Compatibility
98//!
99//! This crate is `no_std` by default. To use with std:
100//!
101//! ```toml
102//! saorsa-logic = { version = "0.1", features = ["std"] }
103//! ```
104
105#![cfg_attr(not(feature = "std"), no_std)]
106#![forbid(unsafe_code)]
107#![warn(missing_docs)]
108#![warn(clippy::all)]
109#![warn(clippy::pedantic)]
110// Allow in no_std context where Result is commonly used
111#![allow(clippy::missing_errors_doc)]
112// Allow technical terms without backticks in docs
113#![allow(clippy::doc_markdown)]
114
115#[cfg(feature = "alloc")]
116extern crate alloc;
117
118pub mod attestation;
119pub mod data;
120pub mod error;
121pub mod merkle;
122
123// Re-exports for convenience
124pub use attestation::{derive_entangled_id, verify_entangled_id, EntangledIdComponents};
125pub use data::{compute_content_hash, verify_content_hash};
126pub use error::{LogicError, LogicResult};
saorsa_logic/lib.rs

saorsa_logic/
lib.rs
