Table of Contents

1. System Overview
2. Architecture Components
3. Component Communication Flow
4. User Interaction Patterns
5. Data Flow Diagrams
6. API Design & Contracts
7. Integration Patterns

System Overview

The Firo SDK is built as a layered architecture where a Rust core implements Lelantus Spark cryptographic primitives, and language bindings expose these capabilities to different environments. The design separates protocol logic from language-specific concerns.

Core Principle: Protocol logic lives in Rust. Language bindings are thin wrappers that handle marshalling/unmarshalling and environment-specific concerns (like Web Workers in browsers).

Architecture Components

Layer 1: Rust Core Library (firo-lelantus-sdk)

Location: rust/src/

Responsibility: Implements all Lelantus Spark protocol operations.

Key Modules:

rust/src/
├── note.rs           # Note creation, commitment generation
├── nullifier.rs      # Nullifier tracking and management
├── proof.rs          # Proof generation (deposit/withdraw)
├── transaction.rs    # Transaction construction and validation
├── keys.rs           # Key derivation and management
├── balance.rs        # Balance calculation from note sets
└── lib.rs            # Public API exposed via UniFFI

Internal Communication:

• Modules communicate via Rust’s type system and standard library channels
• Async operations use Tokio for non-blocking I/O
• State management uses Rust’s ownership system (no shared mutable state)