SDK Architecture

SDK Architecture - Technical Deep Dive

This document provides a comprehensive technical overview of the Roru SDK architecture, including detailed component descriptions, data flows, and implementation details.

Architecture Overview

SDK Structure

The Roru SDK is organized into four distinct layers, each with specific responsibilities:

┌─────────────────────────────────────────┐
│         Application Layer                 │
│  (Your Application Code)                  │
└──────────────┬────────────────────────────┘
               │
┌──────────────▼────────────────────────────┐
│           API Layer                        │
│  - TransactionBuilder                     │
│  - Wallet API                              │
│  - ProofGenerator                          │
│  - StateSync                               │
│  - OfflineTransfer                         │
└──────────────┬────────────────────────────┘
               │
┌──────────────▼────────────────────────────┐
│           Core Layer                       │
│  - Note Management                         │
│  - Commitment Operations                   │
│  - Nullifier Generation                    │
│  - Merkle Tree Operations                  │
│  - Key Management                          │
└──────────────┬────────────────────────────┘
               │
┌──────────────▼────────────────────────────┐
│        Protocol Layer                      │
│  - Shielded State Tree                     │
│  - ZK Circuit Execution                    │
│  - Proof Generation/Verification            │
│  - Transaction Validation                 │
└──────────────┬────────────────────────────┘
               │
┌──────────────▼────────────────────────────┐
│         Network Layer                      │
│  - Encrypted RPC Client                    │
│  - WebSocket Connections                   │
│  - State Synchronization                  │
│  - Transaction Broadcasting               │
└────────────────────────────────────────────┘

Layer Responsibilities

API Layer:

Provides high-level, developer-friendly interfaces
Handles input validation and error formatting
Manages async operations and callbacks
Abstracts protocol complexity

Core Layer:

Implements cryptographic primitives
Manages local state and caching
Handles key derivation and storage
Performs note selection and management

Protocol Layer:

Executes zero-knowledge circuits
Generates and verifies proofs
Manages shielded state tree
Validates transactions

Network Layer:

Handles all network communication
Manages connection pooling and retries
Implements encryption and authentication
Synchronizes state with infrastructure

Core Components

RoruClient

The RoruClient is the main entry point for SDK operations. It manages connections, configuration, and provides access to all SDK functionality.

Rust Implementation:

use roru_sdk::prelude::*;

pub struct RoruClient {
    config: ClientConfig,
    network_client: NetworkClient,
    state_manager: StateManager,
    key_manager: KeyManager,
    proof_generator: ProofGenerator,
}

impl RoruClient {
    /// Create a new Roru client with configuration
    pub async fn new(config: ClientConfig) -> Result<Self> {
        // Initialize network client with encrypted connection
        let network_client = NetworkClient::new(
            config.infra_endpoint.clone(),
            config.api_key.clone(),
        ).await?;
        
        // Initialize state manager with local cache
        let state_manager = StateManager::new(
            config.state_cache_path.clone(),
            network_client.clone(),
        ).await?;
        
        // Initialize key manager with secure storage
        let key_manager = KeyManager::new(
            config.key_storage_path.clone(),
        )?;
        
        // Initialize proof generator with circuit keys
        let proof_generator = ProofGenerator::new(
            config.proving_key_path.clone(),
        )?;
        
        Ok(Self {
            config,
            network_client,
            state_manager,
            key_manager,
            proof_generator,
        })
    }
    
    /// Create a new wallet instance
    pub async fn create_wallet(&self) -> Result<Wallet> {
        // Generate master key
        let master_key = self.key_manager.generate_master_key()?;
        
        // Derive wallet keys
        let spending_key = self.key_manager.derive_spending_key(&master_key)?;
        let viewing_key = self.key_manager.derive_viewing_key(&master_key)?;
        
        // Create wallet with keys
        Wallet::new(
            spending_key,
            viewing_key,
            self.state_manager.clone(),
            self.proof_generator.clone(),
            self.network_client.clone(),
        )
    }
    
    /// Load existing wallet from keys
    pub async fn load_wallet(&self, master_key: &MasterKey) -> Result<Wallet> {
        let spending_key = self.key_manager.derive_spending_key(master_key)?;
        let viewing_key = self.key_manager.derive_viewing_key(master_key)?;
        
        Wallet::new(
            spending_key,
            viewing_key,
            self.state_manager.clone(),
            self.proof_generator.clone(),
            self.network_client.clone(),
        )
    }
    
    /// Get current state root
    pub async fn get_state_root(&self) -> Result<StateRoot> {
        self.state_manager.get_current_root().await
    }
    
    /// Sync state with network
    pub async fn sync_state(&self) -> Result<SyncResult> {
        self.state_manager.sync().await
    }
}

TypeScript Implementation:

import { RoruClient, ClientConfig, Wallet } from '@roru/sdk';

export class RoruClient {
    private config: ClientConfig;
    private networkClient: NetworkClient;
    private stateManager: StateManager;
    private keyManager: KeyManager;
    private proofGenerator: ProofGenerator;
    
    constructor(config: ClientConfig) {
        this.config = config;
        // Initialize components
        this.networkClient = new NetworkClient(config.infraEndpoint, config.apiKey);
        this.stateManager = new StateManager(config.stateCachePath, this.networkClient);
        this.keyManager = new KeyManager(config.keyStoragePath);
        this.proofGenerator = new ProofGenerator(config.provingKeyPath);
    }
    
    async createWallet(): Promise<Wallet> {
        const masterKey = await this.keyManager.generateMasterKey();
        const spendingKey = await this.keyManager.deriveSpendingKey(masterKey);
        const viewingKey = await this.keyManager.deriveViewingKey(masterKey);
        
        return new Wallet(
            spendingKey,
            viewingKey,
            this.stateManager,
            this.proofGenerator,
            this.networkClient
        );
    }
    
    async loadWallet(masterKey: MasterKey): Promise<Wallet> {
        const spendingKey = await this.keyManager.deriveSpendingKey(masterKey);
        const viewingKey = await this.keyManager.deriveViewingKey(masterKey);
        
        return new Wallet(
            spendingKey,
            viewingKey,
            this.stateManager,
            this.proofGenerator,
            this.networkClient
        );
    }
    
    async getStateRoot(): Promise<StateRoot> {
        return await this.stateManager.getCurrentRoot();
    }
    
    async syncState(): Promise<SyncResult> {
        return await this.stateManager.sync();
    }
}

Wallet

The Wallet component manages user funds, transactions, and state synchronization.

Rust Implementation:

pub struct Wallet {
    spending_key: SpendingKey,
    viewing_key: ViewingKey,
    state_manager: StateManager,
    proof_generator: ProofGenerator,
    network_client: NetworkClient,
    local_state: LocalState,
}

impl Wallet {
    pub fn new(
        spending_key: SpendingKey,
        viewing_key: ViewingKey,
        state_manager: StateManager,
        proof_generator: ProofGenerator,
        network_client: NetworkClient,
    ) -> Result<Self> {
        let local_state = LocalState::new();
        
        Ok(Self {
            spending_key,
            viewing_key,
            state_manager,
            proof_generator,
            network_client,
            local_state,
        })
    }
    
    /// Generate a new shielded address
    pub fn generate_address(&self) -> Result<ShieldedAddress> {
        let address_index = self.local_state.next_address_index();
        let address = self.viewing_key.derive_address(address_index)?;
        self.local_state.add_address(address.clone());
        Ok(address)
    }
    
    /// Get shielded balance
    pub async fn get_balance(&self) -> Result<Balance> {
        // Sync state first
        self.sync_state().await?;
        
        // Calculate balance from local notes
        let notes = self.local_state.get_notes(&self.viewing_key)?;
        let balance = notes.iter()
            .map(|note| note.value)
            .sum();
        
        Ok(Balance {
            shielded: balance,
            unconfirmed: 0,
        })
    }
    
    /// Send a private transaction
    pub async fn send(
        &self,
        recipient: ShieldedAddress,
        amount: u64,
    ) -> Result<TransactionResult> {
        // Sync state to get latest notes
        self.sync_state().await?;
        
        // Select input notes
        let input_notes = self.select_notes(amount)?;
        
        // Create output notes
        let change = self.calculate_change(&input_notes, amount)?;
        let mut outputs = vec![
            Note::new(amount, recipient.clone(), &self.viewing_key)?,
        ];
        
        if change > 0 {
            let change_address = self.generate_address()?;
            outputs.push(Note::new(change, change_address, &self.viewing_key)?);
        }
        
        // Build transaction
        let tx = TransactionBuilder::new()
            .inputs(input_notes)
            .outputs(outputs)
            .build()?;
        
        // Generate proof
        let proof = self.proof_generator.generate_proof(&tx).await?;
        
        // Sign transaction
        let signed_tx = self.sign_transaction(tx, proof)?;
        
        // Broadcast transaction
        let tx_hash = self.network_client.broadcast_transaction(&signed_tx).await?;
        
        Ok(TransactionResult {
            tx_hash,
            status: TransactionStatus::Pending,
        })
    }
    
    /// Sync state with network
    pub async fn sync_state(&self) -> Result<SyncResult> {
        // Get current state root from network
        let network_root = self.network_client.get_state_root().await?;
        let local_root = self.local_state.get_state_root();
        
        if network_root != local_root {
            // Download incremental updates
            let updates = self.network_client.get_state_updates(
                local_root,
                network_root,
            ).await?;
            
            // Apply updates to local state
            for update in updates {
                self.local_state.apply_update(update, &self.viewing_key)?;
            }
        }
        
        Ok(SyncResult {
            synced: true,
            new_notes: self.local_state.get_new_notes_count(),
        })
    }
    
    fn select_notes(&self, amount: u64) -> Result<Vec<Note>> {
        let available_notes = self.local_state.get_notes(&self.viewing_key)?;
        
        // Greedy selection algorithm
        let mut selected = Vec::new();
        let mut total = 0u64;
        
        for note in available_notes {
            if total >= amount {
                break;
            }
            selected.push(note);
            total += note.value;
        }
        
        if total < amount {
            return Err(Error::InsufficientBalance);
        }
        
        Ok(selected)
    }
    
    fn sign_transaction(
        &self,
        tx: Transaction,
        proof: Proof,
    ) -> Result<SignedTransaction> {
        // Create transaction bundle
        let bundle = TransactionBundle {
            transaction: tx,
            proof,
            signature: self.spending_key.sign(&tx)?,
        };
        
        Ok(SignedTransaction { bundle })
    }
}

Module Structure

Transaction Module

Purpose: Build and manage private transactions

Key Types:

pub struct TransactionBuilder {
    inputs: Vec<InputNote>,
    outputs: Vec<OutputNote>,
    fee: Option<u64>,
    memo: Option<Vec<u8>>,
}

pub struct Transaction {
    pub inputs: Vec<Input>,
    pub outputs: Vec<Output>,
    pub proof: Proof,
    pub nullifiers: Vec<Nullifier>,
    pub public_data: PublicData,
}

Proof Module

Purpose: Generate and verify zero-knowledge proofs

Key Types:

pub struct ProofGenerator {
    proving_key: ProvingKey,
    circuit: Circuit,
}

pub struct Proof {
    pub a: Point,
    pub b: Point,
    pub c: Point,
    pub public_inputs: Vec<Scalar>,
}

State Module

Purpose: Manage and synchronize shielded state

Key Types:

pub struct StateManager {
    local_cache: StateCache,
    network_client: NetworkClient,
    state_tree: StateTree,
}

pub struct StateSync {
    current_root: StateRoot,
    updates: Vec<StateUpdate>,
}

Network Module

Purpose: Handle network communication

Key Types:

pub struct NetworkClient {
    endpoint: String,
    api_key: String,
    http_client: HttpClient,
    ws_client: Option<WebSocketClient>,
}

pub struct NetworkResponse<T> {
    pub data: T,
    pub status: u16,
    pub headers: HashMap<String, String>,
}

Data Flow

Transaction Creation Flow

User calls wallet.send()
    │
    ├─> Sync state (get latest notes)
    │
    ├─> Select input notes
    │
    ├─> Create output notes
    │
    ├─> Build transaction
    │
    ├─> Generate proof
    │
    ├─> Sign transaction
    │
    └─> Broadcast to network

State Synchronization Flow

wallet.sync_state()
    │
    ├─> Get network state root
    │
    ├─> Compare with local root
    │
    ├─> Request incremental updates
    │
    ├─> Download Merkle proofs
    │
    ├─> Verify proofs
    │
    └─> Update local state

Configuration

ClientConfig

Rust:

pub struct ClientConfig {
    pub infra_endpoint: String,
    pub api_key: Option<String>,
    pub state_cache_path: PathBuf,
    pub key_storage_path: PathBuf,
    pub proving_key_path: PathBuf,
    pub network_id: NetworkId,
    pub timeout: Duration,
    pub retry_config: RetryConfig,
}

TypeScript:

interface ClientConfig {
    infraEndpoint: string;
    apiKey?: string;
    stateCachePath: string;
    keyStoragePath: string;
    provingKeyPath: string;
    networkId: NetworkId;
    timeout?: number;
    retryConfig?: RetryConfig;
}

Error Handling

Error Types

#[derive(Debug, Error)]
pub enum RoruError {
    #[error("Network error: {0}")]
    Network(#[from] NetworkError),
    
    #[error("Insufficient balance")]
    InsufficientBalance,
    
    #[error("Invalid transaction: {0}")]
    InvalidTransaction(String),
    
    #[error("Proof generation failed: {0}")]
    ProofGeneration(String),
    
    #[error("State sync failed: {0}")]
    StateSync(String),
    
    #[error("Key management error: {0}")]
    KeyManagement(#[from] KeyError),
}

Performance Considerations

Caching

State cache: Reduces network calls
Proof cache: Reuses proofs when possible
Address cache: Fast address lookups

Optimization

Batch operations: Multiple transactions at once
Parallel proof generation: Multiple proofs concurrently
Incremental sync: Only download changes

Conclusion

The SDK architecture provides:

Modularity: Clear separation of concerns
Extensibility: Easy to add new features
Performance: Optimized for production use
Developer Experience: Clean, intuitive APIs
Security: Secure key management and operations

Understanding the SDK architecture is essential for effective development with Roru Labs.

PreviousRoadmap for Developers NextSDK Modules

Last updated 29 minutes ago

Good morning

Architecture Overview

SDK Structure

Layer Responsibilities

Core Components

RoruClient

Wallet

Module Structure

Transaction Module

Proof Module

State Module

Network Module

Data Flow

Transaction Creation Flow

State Synchronization Flow

Configuration

ClientConfig

Error Handling

Error Types

Performance Considerations

Caching

Optimization

Conclusion