UNITS Engine 🔐

UNITS (Universal Information Tokenisation System) Engine is a confidentiality layer built on top of Madara, designed to offer transaction privacy while maintaining verifiability through Zero-Knowledge proofs. Together, UNITS Engine and Madara form a complete UNITS implementation, providing both the high-performance ZK infrastructure and the privacy layer needed for confidential transactions.

Overview 🌟

In traditional blockchain architectures and ZK rollups, while write access is carefully controlled through ACLs, read access remains completely public - anyone can read any data on the chain. UNITS engine takes a different approach by introducing a confidentiality layer that allows for controlled data visibility while maintaining the benefits of verifiability.

Key Features ✨

• Confidential Transactions: UNITS enables private transactions while maintaining verifiability
• Flexible Privacy Rules: Participants can define custom privacy rules that the operator enforces
• Custom UNITS RPC: Dedicated RPC interface designed specifically for UNITS functionality

Architecture 🏗️

UNITS engine is built as a layer on top of Madara to leverage its robust infrastructure and high performant ZK architecture. The codebase is organized into several key components:

Design Philosophy 💡

By building on top of Madara, UNITS Engine achieves two critical objectives:

1. Future-Proof Development: We automatically benefit from the latest advancements in ZK technology and improvements in the Starknet (SN) Stack, as Madara stays in sync with these developments
2. Focused Innovation: While Madara handles the core ZK infrastructure, UNITS Engine can focus exclusively on building robust privacy features and confidentiality mechanisms

This separation of concerns allows us to maintain a cutting-edge ZK foundation while developing specialized privacy features that make UNITS unique.

Core Components 🧩

• Engine: The main binary and entry point, containing CLI configuration
• Handlers: Core business logic implementing UNITS functionality and Madara interactions
• DB: Database interaction layer for persistent storage
• UNITS Primitives: Core primitives and types used across multiple crates
• Utils: Basic utility functions and helpers shared across crates
• RPC: UNITS RPC implementation for native functionality
• Telemetry: OpenTelemetry integration for metrics and monitoring
• Proc Macros: Procedural macros for code generation
• Test Utils: Testing utilities and helpers
• E2E Tests: End-to-end test suite

Getting Started 🚀

📖 For comprehensive documentation on UNITS privacy features, RPC methods, and implementation patterns, see Getting Started with UNITS Privacy.

Prerequisites

• Rust (see rust-toolchain.toml for version)
• Madara CLI

Running Tests 🧪

1. First, install and start a Madara devnet:

   # Clone the Madara CLI
   git clone https://github.com/madara-alliance/madara-cli.git
   cd madara-cli
   
   # Run the devnet
   cargo run create
   # Select "Devnet" mode when prompted

2. Run the test suite:

   cargo test --workspace --all-features

Privacy Model 🛡️

UNITS engine implements a trusted operator model where:

• The operator maintains privacy between participants
• Participants can define and enforce their own privacy rules
• The operator can see all data (by design)
• Future integration with Fully Homomorphic Encryption (FHE) is possible as the technology matures

Learn more about implementing privacy controls in the Getting Started Guide.

RPC Support 🔌

UNITS RPC

UNITS provides a custom RPC interface designed specifically for UNITS functionality. The RPC is built with privacy in mind from the ground up, allowing participants to define and enforce their own privacy rules while maintaining the benefits of verifiability.

For detailed documentation on all UNITS RPC methods, read signatures, and privacy patterns, see the Getting Started Guide.

Performance Benchmarks 📊

UNITS is built on top of Madara, which has demonstrated impressive performance metrics:

• 7,000 TPS with merkleization
• 15,000 TPS without merkleization

Note: Benchmarking integration with CI is in progress to provide more reproducible results across different environments and configurations.

Acknowledgments 🙏

UNITS engine is heavily inspired by and built upon Madara, which Karnot is a maintainer of along with Moongsong Labs and Kasar Labs. We're grateful for their foundational work that made this project possible.