Installation

Mirage is available as a Python package with pre-compiled Rust binaries for major platforms.

Prerequisites

Required:

Python 3.12 or higher
pip or uv package manager

Optional (for building from source):

Rust 1.70 or higher
Cargo (Rust package manager)

Install from PyPI

The simplest way to get started:

# Install Mirage SDK (includes x402 payment support)
pip install mirage-solana

Using uv (recommended for faster installs):

uv pip install mirage-solana

This installs the pre-compiled package with Python bindings and Rust core.

Verify Installation

Check that Mirage is installed correctly:

from mirage import PrivacyClient, generate_secret
 
print("Mirage installation successful!")
 
# Optional: verify x402 support
try:
    from mirage.x402 import X402Client
    print("x402 support available!")
except ImportError:
    print("x402 not installed. Run: pip install mirage-solana")

Expected output:

Mirage installation successful!
x402 support available!

Note: x402 payment support is included by default in mirage-solana.

Install from Source

For contributors or those who want to build from source:

Step 1: Clone Repository

git clone https://github.com/miragesolana/mirage-sdk.git
cd mirage-sdk

Step 2: Install Rust (if not already installed)

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Verify Rust installation:

rustc --version  # Should be 1.70 or higher

Step 3: Build All Packages

# Install all packages in development mode
make install-dev
 
# Run tests
make test
 
# Build all packages
make build

Project Structure

Mirage uses a unified package structure with embedded Rust backend:

mirage/
├── mirage/                    # Python SDK
│   ├── __init__.py
│   ├── client.py             # PrivacyClient class
│   ├── types.py
│   ├── utils.py
│   └── x402/                 # x402 payment support (included)
│
├── src/                      # Rust cryptography (PyO3 bindings)
│   ├── crypto/               # Commitments, Poseidon, Merkle, encryption
│   ├── proof/                # Groth16 circuits and proof system
│   └── lib.rs                # PyO3 bindings
│
├── packages/
│   └── mirage-solana/        # On-chain Anchor program (separate)
│       └── programs/
│
├── Cargo.toml                # Rust configuration
├── pyproject.toml            # Python package configuration
└── Makefile                  # Build commands

Building from Source

Unified Package (Python + Rust):

# Install build tool
pip install maturin
 
# Build and install in development mode
PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 maturin develop --release
 
# Or use the Makefile
make install-dev

Solana Program (Anchor):

cd packages/mirage-solana
anchor build

Platform-Specific Notes

macOS

Apple Silicon (M1/M2/M3):

# May need to set architecture
arch -arm64 pip install mirage-solana

Intel:

pip install mirage-solana  # Works out of the box

Linux

Ubuntu/Debian:

# Install system dependencies
sudo apt update
sudo apt install build-essential pkg-config libssl-dev
 
# Then install Mirage
pip install mirage-solana

Arch Linux:

sudo pacman -S base-devel openssl
pip install mirage-solana

Windows

Using WSL (recommended):

# Install WSL2 and Ubuntu
wsl --install
 
# Then follow Linux instructions

Native Windows:

# Install Visual Studio Build Tools
# https://visualstudio.microsoft.com/downloads/
 
# Install Rust via rustup
# https://rustup.rs/
 
pip install mirage-solana

Docker Setup (Optional)

For isolated development environments:

FROM python:3.12-slim
 
RUN apt-get update && apt-get install -y \
    build-essential \
    pkg-config \
    libssl-dev \
    curl
 
# Install Rust
RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
ENV PATH="/root/.cargo/bin:${PATH}"
 
# Install Mirage with x402 support
RUN pip install mirage-solana
 
WORKDIR /app
COPY . .
 
CMD ["python", "main.py"]

Build and run:

docker build -t mirage-app .
docker run -it mirage-app

Troubleshooting

Import Errors

from mirage import PrivacyClient  # ModuleNotFoundError
 
# Solutions:
# 1. Reinstall: pip install --force-reinstall mirage-solana
# 2. Check Python path: python -c "import sys; print(sys.path)"
# 3. Virtual environment: python -m venv venv && source venv/bin/activate

x402 Import Errors

from mirage.x402 import X402Client  # ModuleNotFoundError
 
# x402 is included by default - this shouldn't happen
# If it does, reinstall:
pip install --force-reinstall mirage-solana

Version Conflicts

# Check installed version
pip show mirage-solana
 
# Upgrade to latest
pip install --upgrade mirage-solana
 
# Install specific version
pip install mirage-solana==0.1.0

Performance Issues

For optimal performance, ensure you're using the release build:

# Development (slow)
maturin develop
 
# Production (fast)
maturin develop --release

Installation Variants

# Standard installation (includes x402 support)
pip install mirage-solana
 
# Development dependencies
pip install mirage-solana[dev]

Next Steps

Quick Start - Build your first private transaction
API Reference - Complete API documentation
x402 Integration - Chain-agnostic payments

Getting Help

Documentation: mirage-sdk.com
GitHub Issues: Report bugs and request features
Security: security@mirage-sdk.com