Architecture Overview
Roru Labs Architecture Overview for Developers
This document provides a comprehensive technical overview of the Roru Labs architecture, designed for developers who need to understand the system at a deep level.
System Architecture
High-Level Architecture
The Roru ecosystem consists of five integrated layers:
┌─────────────────────────────────────────────────────────────┐
│ Application Layer │
│ (Roru Wallet, Custom Apps, Merchant Integrations) │
└───────────────────────┬─────────────────────────────────────┘
│
┌───────────────────────▼─────────────────────────────────────┐
│ SDK Layer │
│ (Rust, TypeScript, Python, Go, Swift, C Bindings) │
└───────────────────────┬─────────────────────────────────────┘
│
┌───────────────────────▼─────────────────────────────────────┐
│ Protocol Layer │
│ (Shielded State, ZK Circuits, Settlement Engine) │
└───────────────────────┬─────────────────────────────────────┘
│
┌───────────────────────▼─────────────────────────────────────┐
│ Infrastructure Layer │
│ (Relayers, Provers, Sync Nodes, Attestation Servers) │
└───────────────────────┬─────────────────────────────────────┘
│
┌───────────────────────▼─────────────────────────────────────┐
│ Blockchain Layer │
│ (Ethereum, Solana, Bitcoin, Multi-Chain Adapters) │
└─────────────────────────────────────────────────────────────┘Core Components
Roru Protocol
Purpose: Defines the cryptographic rules and privacy guarantees
Key Components:
Shielded state Merkle tree
Zero-knowledge proof circuits
Nullifier system for double-spend prevention
Multi-chain adapter layer
Settlement engine
Technical Details:
State tree depth: 32 levels (supports 2^32 notes)
Proof system: Groth16 zk-SNARKs (BLS12-381 curve)
Commitment scheme: Pedersen commitments
Hash function: Poseidon (for zk circuits), SHA-256 (for Merkle trees)
Roru Infra
Purpose: Distributed computation and messaging backbone
Key Components:
Attestation Servers: Verify hardware device integrity
Relayer Clusters: Broadcast transactions to blockchains
Encrypted RPC Gateways: Provide encrypted blockchain access
Sync Nodes: Maintain synchronized shielded state
Gossip Coordinators: Enable offline message propagation
Prover Clusters: Generate and validate zk proofs at scale
Technical Details:
TEE/SGX enclaves for encrypted processing
Horizontal scaling architecture
Redundancy mesh for high availability
Proof batching for efficiency
Roru SDK
Purpose: High-level developer interface
Supported Platforms:
Mobile: iOS (Swift), Android (Kotlin/Java)
Desktop: Windows, macOS, Linux
Browser: WebAssembly, JavaScript
Server: Node.js, Python, Go, Rust
Embedded: C bindings
Core Modules:
Transaction builder
Proof generator
State sync API
Offline transfer API
Enclave signing API
Merchant checkout API
Roru Wallet
Purpose: User-facing application
Architecture:
Client-side shielded state management
Local proof verification
Encrypted state cache
Multi-device sync
Hardware integration (Roru One)
Roru One
Purpose: Hardware security device
Architecture:
Secure element (dedicated cryptographic processor)
Tamper detection mesh
Secure boot with attestation
Communication interfaces (NFC, Bluetooth)
Offline proof generation
Data Flow
Transaction Flow
User Action
│
├─> Wallet: Create Transaction
│ │
│ ├─> SDK: Build Transaction
│ │ │
│ │ ├─> Protocol: Select Notes
│ │ ├─> Protocol: Generate Proof
│ │ └─> Protocol: Create Bundle
│ │
│ └─> Infra: Broadcast Transaction
│ │
│ ├─> Relayer: Route to Blockchain
│ ├─> Prover: Verify Proof
│ └─> Sync Node: Update State
│
└─> Blockchain: SettlementState Synchronization
Sync Node (Global State)
│
├─> State Root Updates
├─> Merkle Proof Generation
└─> Incremental Updates
│
└─> Wallet: Sync State
│
├─> Verify State Root
├─> Download Merkle Proofs
└─> Update Local CacheCryptographic Architecture
Zero-Knowledge Proof System
Circuit Architecture:
Input Circuit: Validates note selection and nullifier generation
Output Circuit: Validates new note creation and commitment generation
Balance Circuit: Validates value conservation
Authorization Circuit: Validates spending authorization
Proof Generation:
Witness creation from private inputs
Circuit execution
Proof generation using proving key
Proof size: ~1-2 KB
Generation time: 1-5 seconds (device-dependent)
Shielded State Architecture
Merkle Tree Structure:
Binary Merkle tree
Depth: 32 levels
Leaf nodes: Shielded notes (commitments)
Internal nodes: Hash of children
Root: State root (commits to entire state)
State Updates:
Incremental updates via Merkle proofs
Batch updates for efficiency
Epoch-based organization
State root commits to all updates
Network Architecture
Infrastructure Topology
┌─────────────┐
│ Attestation│
│ Servers │
└──────┬──────┘
│
┌──────────────────┼──────────────────┐
│ │ │
┌───────▼──────┐ ┌───────▼──────┐ ┌───────▼──────┐
│ Relayer │ │ Sync Nodes │ │ Prover │
│ Cluster │ │ │ │ Cluster │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
└──────────────────┼──────────────────┘
│
┌───────▼───────┐
│ Encrypted RPC │
│ Gateways │
└───────┬───────┘
│
┌───────▼───────┐
│ Blockchains │
│ (Multi-Chain) │
└───────────────┘Communication Protocols
Encrypted Channels:
TLS 1.3 for all network communication
End-to-end encryption for sensitive data
Certificate pinning for security
Message Formats:
Protocol Buffers for structured data
JSON for API responses
Binary formats for proofs and commitments
Security Architecture
Trust Model
Hardware Root of Trust:
Roru One provides hardware attestation
Secure element stores keys
Tamper detection prevents physical attacks
Cryptographic Trust:
Zero-knowledge proofs provide mathematical guarantees
State roots commit to entire state
Nullifiers prevent double-spending
Infrastructure Trust:
TEE/SGX enclaves for encrypted processing
Node operators cannot access data
Attestation verifies infrastructure integrity
Threat Model
Protected Against:
Network surveillance
Blockchain analysis
Device compromise (with Roru One)
Infrastructure attacks
Physical attacks (with Roru One)
Security Guarantees:
Privacy: Mathematical guarantees via zk-SNARKs
Integrity: Cryptographic state roots
Availability: Distributed infrastructure
Authenticity: Hardware attestation
Performance Characteristics
Scalability
State Tree:
Logarithmic depth: O(log n) for proofs
Efficient updates: O(log n) for state changes
Supports millions of notes
Proof System:
Constant proof size: ~1-2 KB
Fast verification: <100ms
Batch verification: Even faster
Network:
Horizontal scaling
Load balancing
Geographic distribution
Efficiency
Proof Generation:
Optimized circuits
Efficient witness encoding
Parallel processing support
State Sync:
Incremental updates
Merkle proof optimization
Bandwidth efficient
Development Workflow
Integration Points
SDK Integration:
Install SDK for your platform
Initialize client with configuration
Connect to Roru Infra
Use SDK APIs for operations
Protocol Integration:
Understand protocol specifications
Implement adapter for your chain
Integrate with settlement engine
Test with sandbox environment
Infrastructure Integration:
Set up node infrastructure
Configure TEE/SGX enclaves
Connect to network
Begin processing transactions
Conclusion
The Roru architecture provides:
Modularity: Clear separation of concerns
Scalability: Designed for growth
Security: Multiple layers of protection
Privacy: Mathematical guarantees
Flexibility: Multiple integration points
Understanding this architecture is essential for effective development with Roru Labs.
Last updated