Component Interactions
Component Interactions in Roru Labs
This document details how the various components of the Roru ecosystem interact with each other, providing developers with a comprehensive understanding of system integration points.
Interaction Patterns
Wallet to SDK
Interaction Flow:
Wallet calls SDK API
SDK validates input
SDK constructs protocol message
SDK handles response
Wallet updates UI
APIs Used:
Transaction builder API
Proof generation API
State sync API
Offline transfer API
Data Format:
JSON for API calls
Protocol buffers for internal communication
Encrypted channels for sensitive data
SDK to Protocol
Interaction Flow:
SDK constructs transaction
Protocol validates structure
Protocol selects notes
Protocol generates proof
Protocol creates bundle
SDK returns to wallet
Protocol Operations:
Note selection algorithms
Proof circuit execution
Nullifier generation
Commitment creation
SDK to Infra
Interaction Flow:
SDK connects to Infra endpoints
Infra authenticates connection
SDK sends requests
Infra processes in enclaves
Infra returns encrypted responses
SDK decrypts and processes
Infra Services:
Encrypted RPC gateways
Prover clusters
Sync nodes
Relayer clusters
Protocol to Blockchain
Interaction Flow:
Protocol creates settlement transaction
Adapter formats for target chain
Relayer broadcasts to blockchain
Blockchain confirms transaction
State updated in protocol
Adapter Functions:
Chain-specific formatting
Gas estimation
Fee calculation
Transaction construction
Synchronization Patterns
State Synchronization
Wallet to Sync Node:
Wallet requests state root
Sync node returns current root
Wallet compares with local
Wallet requests Merkle proofs
Sync node provides proofs
Wallet verifies and updates
Incremental Updates:
Only changed state downloaded
Merkle proofs for efficiency
Batch updates when possible
Encrypted synchronization
Multi-Device Sync
Device to Device:
Device A creates transaction
Encrypted sync to Device B
Device B validates
Both devices updated
State consistent across devices
Sync Protocol:
End-to-end encryption
Conflict resolution
State verification
Incremental updates
Hardware Interactions
Wallet to Roru One
Pairing Flow:
Wallet initiates pairing
Roru One generates code
Both devices confirm
Encrypted connection established
Keys synchronized (encrypted)
Transaction Signing:
Wallet creates transaction
Sends to Roru One
Roru One displays/communicates details
User confirms on device
Roru One signs in secure element
Returns signed transaction
Wallet broadcasts
Offline Operations:
Roru One creates transaction
Signs offline
Generates proof locally
Creates bundle
Transfers via NFC/Bluetooth
Wallet receives and queues
Roru One to Network
Attestation Flow:
Roru One generates attestation
Sends to attestation server
Server verifies hardware
Server issues certificate
Device can authenticate
Firmware Updates:
Server pushes update
Device verifies signature
Device installs in secure boot
Device attests new firmware
Update complete
Infrastructure Interactions
Node to Node
Gossip Protocol:
Node receives transaction
Validates locally
Propagates to neighbors
Network converges
State synchronized
Consensus:
State root consensus
Proof verification consensus
Settlement consensus
No blockchain consensus needed
Enclave Processing
TEE/SGX Flow:
Request received
Verified by enclave
Data processed in enclave
Results encrypted
Returned to caller
Attestation:
Remote attestation
Enclave integrity proof
Trust establishment
Secure communication
API Interaction Patterns
RESTful APIs
Request Format:
HTTPS endpoints
JSON request body
Authentication headers
Rate limiting
Response Format:
JSON response
Error codes
Pagination
Metadata
WebSocket APIs
Connection:
WSS (WebSocket Secure)
Authentication on connect
Heartbeat for keepalive
Reconnection logic
Message Types:
State updates
Transaction notifications
Proof status
Error messages
gRPC APIs
Service Definition:
Protocol buffer schemas
Streaming support
Bidirectional streams
Error handling
Use Cases:
High-performance operations
Real-time updates
Batch operations
Internal services
Error Handling
Error Propagation
Error Flow:
Error occurs in component
Error wrapped with context
Propagated to caller
SDK handles gracefully
User-friendly message
Error Types:
Network errors
Validation errors
Cryptographic errors
State errors
Retry Logic
Retry Strategies:
Exponential backoff
Maximum retry count
Circuit breaker pattern
Fallback mechanisms
Performance Optimization
Caching Strategies
Local Caching:
State cache in wallet
Proof cache
Address cache
Transaction cache
Cache Invalidation:
State root changes
Time-based expiration
Manual invalidation
Event-driven updates
Batch Operations
Batching Benefits:
Reduced network calls
Lower latency
Better throughput
Cost efficiency
Batch Types:
Transaction batching
Proof batching
State update batching
Network request batching
Security Interactions
Authentication Flow
User Authentication:
User provides credentials
Wallet authenticates
Session established
Encrypted communication
Token refresh
Device Authentication:
Device generates keypair
Attestation to server
Server verifies
Certificate issued
Device authenticated
Authorization Flow
Transaction Authorization:
User initiates transaction
Wallet requests authorization
Roru One confirms (if used)
Authorization granted
Transaction proceeds
Conclusion
Component interactions in Roru:
Clear Interfaces: Well-defined APIs
Secure Communication: Encrypted channels
Efficient Protocols: Optimized data flows
Error Handling: Robust error management
Performance: Optimized interactions
Understanding these interactions is essential for effective development and integration.
Last updated