Firo SDK Lelantus Spark Integration Toolkit by emmzyCod

Firo SDK Lelantus Spark Integration Toolkit

Rust-based SDK with multi-language bindings for building privacy-preserving Lelantus Spark-enabled applications across platforms

---

Team

Charles Emmanuel - Lead Developer

• GitHub: @CodexEmmzy
• Telegram: @charlesCode
• Email: [email protected]

Gospel Ifediora - Core Developer

• GitHub: @steven3002
• X/Twitter: @Steven_Hert

Gospel is a blockchain developer with experience building developer tools and SDKs. He'll be working alongside Charles on the Rust core implementation and language bindings.

Experience

We've built developer tooling and SDKs across different blockchain ecosystems:

• Ox-rollup - Layer-2 developer tooling with multi-language SDKs
• RetrievalTester - Storage and testing infrastructure tools
• VoxBridge - Web3 game tooling and asset conversion (Python/TypeScript)
• Arbitrum Stylus VS Code extension - Tooling around complex cryptographic backends

Technical Stack: Rust, TypeScript, UniFFI, WASM, developer tooling, blockchain SDKs

---

Why This Project?

The Problem

Right now, developers building Lelantus Spark applications have to deal with:

• No high-level SDK for note management and proof generation
• Having to dig deep into protocol details to do basic operations
• No reusable library - everyone reinvents the wheel
• Existing tools are either too low-level, inconsistent, or require server-side components
• Each project ends up reimplementing the same cryptographic primitives

This means teams either:

• Build everything from scratch (lots of room for errors), or
• Force users through server-side flows (bad UX), or
• Just wait around hoping someone builds the tooling

Bottom line: there's no production-ready Rust SDK with language bindings for Lelantus Spark, and that's blocking adoption.

The Solution

We're building a Rust SDK that wraps Lelantus Spark's primitives in developer-friendly APIs. The Rust core uses UniFFI (like BDK/LDK) to automatically generate bindings for other languages. Starting with JavaScript/TypeScript for web apps, but designed to expand to mobile and other platforms easily.

What you'll get:

• Rust crate (firo-lelantus-sdk) - production-ready library with tests and docs
• JavaScript/TypeScript SDK - npm package built from UniFFI-generated bindings, compiled to WASM for browsers
• Type-safe APIs - clean interfaces with proper TypeScript definitions
• Examples - working wallet adapters and demo dApp
• Security guidance - best practices and audit checklists

---

What Will Be Delivered?

Core Deliverables

Component	Description
Rust Core Library	Production-ready Rust crate (firo-lelantus-sdk) with high-level APIs for deposit, withdraw, balance, and note management. Full test suite and documentation.
UniFFI Bindings	Automatically generated language bindings from Rust core. Initial release includes JavaScript/TypeScript bindings (WASM-compiled for browser).
JavaScript/TypeScript SDK	npm package (@firo/lelantus-js) wrapping UniFFI-generated bindings with Web Worker integration and promise-based APIs for web applications.
Wallet Adapters	Reference implementations for wallet integrations (injected wallets, extensions, iframe wallets) using the JavaScript SDK.
Reference Demo	React + Vite example dApp demonstrating deposit/withdraw flows and Anonymity Set visualization.
Documentation	Rust API docs, JavaScript/TypeScript quickstart guides, integration tutorials, and demo video.
Security Toolkit	Audit checklist, security best practices, and compliance guidelines for both Rust and language binding usage.

Project Structure

firo-lelantus-sdk/
├── rust/                          # Primary Rust crate (main deliverable)
│   ├── src/                       # Core Lelantus Spark primitives and high-level APIs
│   ├── tests/                     # Full Rust test suite
│   └── Cargo.toml                 # Rust package configuration
├── bindings/                      # UniFFI-generated language bindings
│   ├── javascript/                # JS/TS bindings and npm package
│   │   ├── src/                   # JavaScript SDK wrapper
│   │   ├── wasm/                  # WebAssembly compilation output
│   │   └── package.json           # npm package configuration
│   └── (future: swift, kotlin, python)
├── examples/                      # Reference implementations
│   ├── rust-example/              # Rust usage example
│   ├── web-demo/                  # React + Vite demo dApp
│   └── wallet-adapters/           # Wallet integration examples
├── docs/                          # Documentation site
├── .github/                       # CI/CD workflows
└── README.md                      # Project documentation

---

Technical Design & SDK Functionality

Architecture Overview

Rust core + UniFFI bindings architecture. The Rust core implements Lelantus Spark primitives, and UniFFI generates language bindings automatically (same approach as BDK/LDK). One Rust implementation, multiple language bindings with minimal maintenance overhead.

Project Components

1. Rust Core Library (firo-lelantus-sdk)

• Purpose: Implements all Lelantus Spark cryptographic operations in Rust
• Contains: Note management, nullifier tracking, proof generation, transaction building, balance calculation, key handling
• Deliverable: Published Rust crate on crates.io

2. UniFFI Interface Layer

• Purpose: Defines the API contract exposed to other languages
• How it works: Define public API in Rust, UniFFI generates bindings automatically
• Benefit: Changes to Rust core automatically propagate to all language bindings with type safety

3. JavaScript/TypeScript SDK (@firo/lelantus-js)

• Purpose: Browser-friendly SDK for web applications and wallets
• Provides: Transaction creation, note operations, proof generation (Web Workers), balance queries, TypeScript types
• Deliverable: npm package ready for web integration

4. Wallet Adapter Examples

• Purpose: Reference implementations showing wallet integration patterns
• Includes: Injected wallet examples, browser extension patterns, headless UI components, best practices
• Deliverable: Working examples and integration guides

5. Demo dApp

• Purpose: Working example demonstrating complete flows
• Shows: Deposit flow, withdraw flow, anonymity set visualization, integration patterns
• Deliverable: Deployed demo application on testnet

SDK Functionality: What It Does and Doesn't Do

What the SDK provides:

• Transaction creation (deposit, withdraw) - properly formatted Lelantus Spark transactions
• Note management - create, store, track Spark notes
• Proof generation - generate proofs client-side in Web Workers (non-blocking)
• Balance operations - calculate balance from note sets, query note status

What the SDK does NOT provide:

• Network layer (RPC calls, transaction broadcasting) - wallets handle this
• Wallet features (account management, UI components, key storage UI) - wallets handle this

Design philosophy: SDK focuses on Lelantus Spark protocol operations. Wallets integrate it to add privacy features but handle their own network layer, UI, and account management. This keeps the SDK focused and reusable.

Example flow:

1. Wallet calls SDK with amount/notes
2. SDK creates transaction and generates proof
3. SDK returns formatted transaction
4. Wallet signs and broadcasts (using wallet's network layer)

---

Development Roadmap: Phased Approach

We're building this in phases. This proposal covers Phase 1 - getting the core Rust SDK and JavaScript bindings done. Future phases add mobile support and advanced features.

Phase 1: Core Foundation (Current Proposal)

Duration: 6–8 weeks | Budget: $19,000 USD

Deliverables:

• Production-ready Rust core library (firo-lelantus-sdk)
• JavaScript/TypeScript SDK with WebAssembly bindings
• Reference implementations and examples
• Full documentation and developer tooling
• Security guidance and audit checklist

Phase 1 gives us a working Rust SDK that can be used directly, plus JavaScript/TypeScript bindings for web apps. Everything comes with docs, examples, and security guidelines.

Phase 2: Mobile SDKs (Future)

Swift and Kotlin bindings for iOS/Android, built on the same Rust core. Includes native wallet examples and mobile-specific features (secure storage, biometrics, offline support).

Phase 3: Additional Languages & Advanced Features (Future)

Python and Go bindings for backend/research use, plus advanced features like batch processing, privacy analytics, and developer tooling (CLI, testing frameworks).

Note: This proposal only covers Phase 1. Phases 2 and 3 are future roadmap items that would need separate funding.

---

Key Features

1. Rust Core Library (Primary Deliverable)

• Production-ready Rust crate (firo-lelantus-sdk) with full API coverage
• High-level APIs for note creation, nullifier management, proof generation
• Rust's memory safety for key/note management (no leaks, no crashes)
• Async/await for non-blocking operations
• Full test coverage (unit, integration, property-based tests)
• Complete docs with examples
• Works standalone in Rust, or as the base for language bindings

2. UniFFI-Generated Multi-Language Bindings

• UniFFI interface (same pattern as BDK/LDK)
• Auto-generated bindings with type safety built-in
• JavaScript/TypeScript bindings (first release) - compiled to WASM for browsers
• Web Workers for proof generation (doesn't block the main thread)
• Easy to add more languages later (Swift, Kotlin, Python) - same Rust core

3. JavaScript/TypeScript SDK (First Language Binding)

• npm package (@firo/lelantus-js) providing promise-based APIs for web applications
• TypeScript type definitions automatically generated from Rust
• Evented interface for UI integration and progress tracking
• Utilities for proof orchestration: queueing, async worker integration, batching helpers
• Browser-friendly fallbacks for mobile/limited-device UX

4. Wallet Integration Layer

• Reference wallet adapter implementations for common wallet types
• Headless UI primitives (logic-only components) for React/Vue/Svelte
• Integration examples and patterns documentation

5. Reference Implementations

• Rust example application demonstrating direct crate usage
• Web demo dApp (React + Vite) showing deposit/withdraw flows
• Anonymity Set visualization and secure session lifecycle management

6. Security & Compliance

• Rust's compile-time safety (no memory bugs, thread-safe by default)
• Replay protection, nullifier management, secure key storage patterns
• Clear guidelines for storing keys safely in all language bindings
• Security checklist for audits and integration reviews

---

Technical Architecture: UniFFI-Based Approach

Overview

We're following the same approach as BDK and LDK - Rust core with UniFFI-generated bindings. UniFFI automatically creates type-safe bindings from the Rust code, so we get consistency across languages without writing manual binding code.

Why UniFFI?

Why UniFFI:

• No manual binding code to write or maintain
• Same API surface across all languages (automatically)
• Battle-tested by BDK and LDK in production
• Easy to add new languages later (Swift, Kotlin, Python, etc.)
• Type safety handled automatically

Implementation Strategy: Phased Development Roadmap

Phase 1: Core Foundation (Current Funding Request)

Scope: This proposal covers Phase 1, delivering the foundational Rust SDK and JavaScript/TypeScript bindings.

Rust Core Library Implementation:

• Design and implement Rust crate (firo-lelantus-sdk) with high-level Lelantus Spark APIs
• Core cryptographic primitives: note creation, nullifier management, proof generation, balance tracking (Lelantus Spark protocol)
• High-level abstractions for common operations (deposit, withdraw, balance queries)
• Async/await patterns for non-blocking operations
• Safe key/note storage abstractions with Rust's memory safety guarantees
• Full Rust test suite (unit, integration, property-based tests)
• Full Rust API documentation with examples and usage patterns
• Deliverable: Production-ready Rust crate published to crates.io, usable independently in Rust applications

UniFFI Interface Definition:

• Create UniFFI Interface Definition Language (IDL) files or use procedural macros
• Define clean public API surface optimized for multi-language consumption
• Generate Rust scaffolding automatically via UniFFI
• Verify interface contracts are suitable for binding generation
• Design API surface to support future language bindings

JavaScript/TypeScript Bindings (First Language Binding):

• Generate JavaScript/TypeScript bindings from UniFFI interface
• Compile to WebAssembly for optimal browser performance
• TypeScript type definitions automatically generated
• Create npm package (@firo/lelantus-js) with promise-based JavaScript SDK wrapper
• Web Worker integration for non-blocking proof generation
• Browser-friendly utilities and helpers for common web integration patterns
• Evented interface for UI integration and progress tracking
• Reference wallet adapter implementations for common wallet types

Documentation and Developer Experience:

• Rust API documentation (cargo doc)
• JavaScript/TypeScript quickstart guides and integration tutorials
• Rust example application demonstrating direct crate usage
• Web demo dApp (React + Vite) showing deposit/withdraw flows
• Security checklist and best practices documentation
• Community outreach and initial adoption support

Phase 1 Deliverables Summary:

• Production-ready Rust crate (firo-lelantus-sdk v0.1.0)
• JavaScript/TypeScript SDK (@firo/lelantus-js v0.1.0)
• Reference implementations and examples
• Full documentation
• Test suites and CI/CD pipelines
• Security guidance and audit checklist

---

Note: Later phases (mobile SDKs and additional language bindings) are outlined in the roadmap section above. This proposal focuses on Phase 1 only.

Comparison: Manual WASM vs UniFFI Approach

Aspect	Manual WASM Bindings	UniFFI-Generated Bindings
Development Time	Higher (manual coding)	Lower (automated generation)
Type Safety	Manual verification	Automated via UniFFI
Maintenance	Higher (manual updates)	Lower (regenerate on changes)
Multi-Platform	Requires new manual work	Minimal additional effort
Industry Proven	Variable	Used by BDK/LDK
Consistency	Risk of inconsistencies	Guaranteed by automation

Technical Benefits

• Security: Rust's memory safety model extends to generated bindings
• Performance: Native Rust performance with minimal FFI overhead
• Reliability: Battle-tested approach used in production Bitcoin infrastructure
• Developer Experience: Clean, type-safe APIs in target languages
• Maintainability: Changes to Rust core automatically propagate via regeneration

Browser Compatibility

For web/browser environments, UniFFI-generated bindings will:

• Compile to WebAssembly for optimal performance
• Execute in Web Workers to avoid blocking the main thread
• Provide fallback strategies for limited-device scenarios
• Maintain full TypeScript support with generated type definitions

---

Budget Breakdown

Total Requested: $19,000 USD

Category	Amount	Description
Development	$12,000	Rust core library implementation (2 developers), UniFFI bindings, JavaScript SDK wrapper, test suites (Rust + JS)
Documentation	$2,000	Rust API docs, JavaScript tutorials, demo dApp, video production
Integrations	$1,800	Wallet adapter examples (Rust usage + JavaScript SDK), reference implementations
CI/Infrastructure	$800	GitHub Actions, automated test nodes, Rust/JS CI pipelines
Security Review	$700	Pre-audit checks, security consult (focus on Rust core + binding safety)
Community Outreach	$800	Workshop, forum posts, maintainers outreach
Contingency	$900	~5% buffer for unexpected items
Total	$19,000

Exchange Rate: FIRO equivalent computed at payout time using prevailing FIRO/USD rate.

---

Project Timeline

Duration: 6–8 weeks (fast, targeted MVP suitable for FCS "quick win" funding)

Milestone Breakdown

Milestone 1 — Project Kickoff & Rust Core Design (1 week)

• Deliverables: Project repo skeleton, Rust crate structure, design spec (Rust API surface), UniFFI interface definition plan, acceptance tests, CI setup for Rust
• Acceptance: Repo with README, Rust API spec, Cargo.toml structure, UniFFI IDL structure defined, initial Rust CI passes
• Funding: $2,000

Milestone 2 — Rust Core Implementation + UniFFI Bindings (2–3 weeks)

• Primary Deliverable: Complete Rust core library (firo-lelantus-sdk) with all core primitives (deposit, withdraw, note management, proof generation), full Rust test suite, and complete Rust API documentation
• Secondary Deliverable: UniFFI interface definition and generated JavaScript/WASM bindings, npm package (@firo/lelantus-js), Web Worker integration, JavaScript unit tests
• Acceptance: Passing Rust test suite (unit + integration), Rust example demonstrating full deposit→withdraw flow, passing JavaScript tests, demo script using JS SDK running complete flow locally, UniFFI-generated bindings verified
• Funding: $7,500

Milestone 3 — Wallet Adapters & Demo dApp (1–2 weeks)

• Deliverables: Reference wallet adapters, headless UI hooks, complete demo dApp with Anonymity Set visualization
• Acceptance: Demo deploy accessible and documented, example wallet integration README
• Funding: $3,500

Milestone 4 — Documentation, Security Checklist, Outreach (1 week)

• Deliverables: Full docs site (API + integration guides), tutorial video, security checklist, community outreach plan
• Acceptance: Docs published, video uploaded, forum post link provided
• Funding: $2,700

Milestone 5 — Buffer, Final Polish, Handover (continuous)

• Deliverables: Bug fixes, final tests, community-requested changes, npm package release
• Acceptance: npm package published under semantic version (v0.1.0), release notes
• Funding: $3,300

---

Success Metrics

Concrete Deliverables

• Primary: MIT-licensed Rust crate firo-lelantus-sdk (v0.1.0) - production-ready core library
• Secondary: MIT-licensed npm package @firo/lelantus-js (v0.1.0) - JavaScript/TypeScript SDK
• Rust example application demonstrating direct crate usage
• JavaScript wallet adapter examples (injected and extension reference adapters)
• Web demo app with deposit/withdraw flows and anonymity indicator
• Full documentation: Rust API docs, JavaScript quickstart guides, integration tutorials
• 5–7 minute demo video
• Test suites (Rust + JavaScript) and CI pipeline with reproducible examples
• Security checklist and recommended audit-entry points (covering both Rust core and bindings)
• Community outreach: forum post, workshop recording, demo session

Adoption Targets

• Rust crate usage: At least 1 Rust project integrating firo-lelantus-sdk directly within 8 weeks
• JavaScript SDK usage: 1–2 web integrations (testnet) by active dev teams within 8 weeks
• Package adoption: 200+ npm downloads + 50+ crates.io downloads within first 30 days
• Security validation: 1+ independent security review requested by project integrator
• Community contributions: GH stars/forks + 1+ community PR (Rust or JS) within 60 days

---

Security & Risk Management

Security Approach

• Client-side proof generation handled with best-practice guidance and safe defaults
• Defensive patterns for replay protection, nullifier management, and key storage
• Storage guidelines: Secure platform storage (not localStorage) with migration guides
• Third-party audit recommendation for production-sensitive deployments (budget includes lightweight pre-audit)

Risk Mitigation

• Code will be MIT licensed (FCS requirement for free, reusable public goods)
• Comprehensive security checklist for integrators and auditors
• Documentation includes clear warnings and best practices
• Maintenance window: 30–60 days post-delivery for integration feedback

---

Maintenance & Sustainability

• Post-delivery support: 30–60 day maintenance window to address integration feedback
• Community contribution model: CONTRIBUTING.md included to enable external maintainers
• Open-source governance: MIT license enables community-driven extensions and improvements

---

Quick Acceptance Checklist

For reviewers and community:

• [ ] Rust crate published to crates.io with README, API docs, and install guide
• [ ] npm package published with README and install guide
• [ ] Rust example application demonstrating core library usage
• [ ] Demo dApp showing full deposit → withdraw flow on testnet (using JavaScript SDK)
• [ ] UniFFI-generated WASM bindings running in-browser (non-blocking via Web Workers)
• [ ] Wallet adapter examples and headless UI patterns documented
• [ ] Comprehensive docs (Rust) + video + forum post link provided

---

Community Feedback

Looking for feedback before we submit!

Let us know what you think about:

• What features matter most
• Integration approaches
• Security concerns
• Documentation needs
• Technical decisions

Contact: Telegram: @charlesCode | [email protected]

---

License

All code will be MIT licensed (FCS requirement for free, reusable public goods).