This is a major architectural release that completely swaps the computationally intensive pipeline stages of Paradox
(coordinateevolution, walk loops, neighbor extraction, seed evolution, and entropy aggregation) with a native Rust
implementation exposed to Python via PyO3 and Maturin.
This update delivers massive performance improvements (up to a 31.2× latency speedup) while maintaining 100% bit-for-
bit key derivation parity and backward compatibility with the original v1 Python API.
──────
🚀 Key Highlights & Speedup Metrics
The transition of the coordinate mapping and recursive walk layer loops to Rust yields significant latency reductions:
| Security Level | Steps × Layers | v1 Python (ms) | v2 Rust (ms) | Speedup Factor |
|---|---|---|---|---|
| LOW | 1,000 × 2 | 91.0 ms | 7.6 ms | 11.9× |
| MEDIUM | 10,000 × 4 | 2,140.0 ms | 93.5 ms | 22.9× |
| HIGH | 100,000 × 8 | 58,300.0 ms | 1,866.3 ms | 31.2× |
Note: Latency scales linearly in Rust, allowing the HIGH security configuration (800,000 recursive walk steps) to
execute in under 2 seconds (down from nearly a minute).
──────
🛠️ Codebase & Packaging Improvements
• PyO3 Bindings: Swapped the slow coordinate loop with _paradox_core , a native C extension.
• Maturin Build Integration: Added full configuration to pyproject.toml and Cargo.toml to support direct building
and publishing to PyPI.
• Ruff, Black, & MyPy Compliant: Standardized type-checking and code formatting to pass all static linting checks with
zero warnings.
• Critical Decryption Bugfix: Fixed a bug in encrypt.py where decrypted files were decoded to UTF-8 text strings
prior to output writing, which formerly corrupted non-text binary files (e.g. PDFs, ZIPs, images) during decryption.
• Circular Import Resolution: Refactored package level imports to prevent circular dependencies at startup.
──────
🧪 Cryptographic & Parity Validation
All 12 validation tests pass successfully:
• Bit-for-bit Parity: Verified key generation output against v1 baseline reference vectors.
• Avalanche Effect: Average bit difference of 50.1367% (ideal: 50.0%) within a strict ±5% cryptographic acceptance band.
• Shannon Entropy: Key entropy metrics consistently measure at 7.945204 bits/byte (ideal: 8.0) passing the Chi-Square
uniformity test (p = 0.75 > 0.01).
• Collisions: Zero collisions observed over 1,000 generated keys.
──────
📦 How to Install & Compile
# Clone the repository
git clone https://github.com/chiragferwani/paradox.git
cd paradox
# Activate virtual environment
python3 -m venv .venv
source .venv/bin/activate
# Install build tools and compile the extension
pip install maturin patchelf
export PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1
maturin develop --release