Overview

Mirage provides production-ready privacy primitives for Solana applications with optional x402 payment integration for chain-agnostic micropayments. Built with a Python-first API powered by high-performance Rust cryptography, Mirage makes zero-knowledge proofs and private transactions accessible to Python developers without sacrificing performance.

Enable private transactions on Solana using Groth16 zkSNARKs. Shield your assets, transfer privately, and unshield without revealing amounts, senders, or recipients on-chain.

Python-First Design

• Intuitive API for Python developers
• Comprehensive type hints and documentation
• Async/await support for Solana integration
• Zero Rust knowledge required
• Works seamlessly with existing Python tooling

Rust Performance

• Cryptographic operations run at native speed
• Groth16 zkSNARK proofs: 2-5 seconds generation
• ~7,000 R1CS constraints on BN254 curve
• Poseidon hash optimized for zkSNARKs (~200 constraints/hash)
• PyO3 bindings for seamless Rust-Python integration

Production-Ready Cryptography

• Circuit-safe nullifier derivation (two-step Poseidon)
• Incremental Merkle tree (depth 20, ~1M leaves)
• ECDH + ChaCha20-Poly1305 note encryption
• Comprehensive test coverage
• MIRAGE domain-separated cryptographic operations

Complete Privacy

• Shielded amounts, senders, and recipients
• ECDH note encryption for recipient discovery
• Unlinkable nullifiers prevent transaction graph analysis
• 30-root history prevents front-running attacks
• Mathematically enforced privacy (information-theoretic for amounts)

x402 Payment Integration

• Pay for privacy services using any supported blockchain
• Chain-agnostic micropayments via x402 protocol
• 15+ supported networks (Base, Polygon, Avalanche, Solana, and more)
• Seamless integration with privacy operations

Unified Package Architecture

Mirage provides a single Python package with embedded Rust backend:

Note: Install with pip install mirage-solana - x402 support is included by default.

AI Agents with Private State

• Autonomous agents that need to hold and transfer assets privately
• Trading bots that don't reveal strategies through transaction patterns
• Multi-agent systems with confidential coordination

Institutional DeFi

• Large transfers without revealing positions
• Private OTC settlements
• Confidential treasury management
• Compliance-compatible privacy (selective disclosure)

Trading Bots (MEV Protection)

• Hide trade amounts and patterns from front-runners
• Private limit orders
• Confidential arbitrage execution
• Prevent sandwich attacks

Privacy-Preserving Payments

• Peer-to-peer transfers without public transaction graphs
• Payroll with hidden salary amounts
• Donations and grants with recipient privacy
• Cross-border transfers without surveillance

Chain-Agnostic Services

• Pay for privacy services from any blockchain using x402
• Cross-chain micropayments for API access
• Multi-network payment flexibility

Mirage combines several cryptographic primitives to achieve complete transaction privacy:

1. Pedersen Commitments hide amounts while allowing verification

   • Formula: C = amount * G + blinding * H (on BN254 G1)
   • Uses MIRAGE_PROTOCOL_PEDERSEN_H_V1 domain separator
   • Perfectly hiding (information-theoretic)
   • Computationally binding (under discrete log assumption)

2. Circuit-Safe Nullifiers prevent double-spending

   • Two-step derivation: spending_key = Poseidon(secret), nullifier = Poseidon(spending_key, index)
   • Uses MIRAGE_SPENDING_KEY and MIRAGE_NULLIFIER domain separators
   • Unlinkable to commitments without secret
   • PDA-based tracking on Solana

3. Groth16 zkSNARKs prove transaction validity

   • ~7,000 R1CS constraints
   • Proves commitment membership, nullifier correctness, amount conservation
   • 256-byte proofs verified on-chain in ~200k CU

4. ECDH Note Encryption enables recipient discovery

   • Encrypt note data with recipient's public key
   • Uses MIRAGE_NOTE_ENCRYPTION_V1 domain separator
   • Forward secrecy via ephemeral keys
   • Trial decryption for note scanning

5. x402 Payment Protocol enables chain-agnostic payments

   • HTTP 402 Payment Required flow
   • EIP-712 signatures for EVM chains
   • Native signing for Solana
   • Facilitator-based verification and settlement

Hardware Requirements (Client-Side):

• Proof generation: 2-4 GB RAM, modern CPU
• Other operations: Minimal resources

Cryptographic Assumptions:

• BN254 discrete logarithm is hard (~128-bit security)
• Trusted setup has at least one honest participant
• Poseidon hash is collision-resistant
• ChaCha20-Poly1305 is secure AEAD

Privacy Guarantees:

• Amount privacy: Information-theoretic (perfect hiding)
• Sender privacy: Computational (unlinkable nullifiers)
• Recipient privacy: Computational (unlinkable commitments)
• Transaction graph: Completely broken (no links between inputs/outputs)

Known Limitations:

• Timing analysis (deposits/withdrawals are public events)
• IP exposure without relayers
• Requires trusted setup (MPC ceremony mitigates)

See Privacy Model for detailed security analysis.

• Installation - Set up Mirage in your project
• Quick Start - Build your first private transaction
• Architecture - Understand the system design
• API Reference - Complete API documentation

Mirage x402 integration supports payments on 15+ blockchains:

Mainnets: Base, Polygon, Avalanche, Solana, IoTeX, Peaq, Sei, XLayer Testnets: Base Sepolia, Polygon Amoy, Avalanche Fuji, Solana Devnet, and more

• Documentation: mirage-sdk.com
• GitHub: Report issues and contribute
• Security Contact: security@mirage-sdk.com

MIT License - See LICENSE file for details