Metadata-Version: 2.1
Name: matrices-evolved
Version: 1.0.3
Summary: High-performance Matrix event signing library
Author-Email: Aless Microsystems <albertalesso@gmail.com>
License: Aless Microsystems Source-Available License (Non-Commercial, No Military) v1.0
         
         Copyright (c) 2025 Albert Blasczykowski (Aless Microsystems)
         
         All rights reserved.
         
         Preamble
         This license grants limited, revocable permission to access, use, modify, and share the Licensed Work for strictly non‑commercial purposes and expressly forbids any military, intelligence, or defense‑affiliated use, including derivative use for those purposes. This license is source‑available and is not an open‑source license.
         
         1. Definitions
         “Licensor” means Albert Blasczykowski, doing business as Aless Microsystems, and any authorized successors or assigns.
         
         “Licensee” means the individual or legal entity exercising rights under this License.
         
         “Licensed Work” means the software, algorithms, models, documentation, and associated materials distributed by the Licensor under this License, including any updates or supplements.
         
         “Modification” means any work based on or incorporating the Licensed Work, including derivative works, adaptations, translations, or integrations, whether in source or object form.
         
         “Non‑Commercial Use” means use that is not intended for, directed toward, or in connection with generating revenue or other commercial advantage, and is limited to personal, hobbyist, educational, academic, research, or internal testing/evaluation by non‑profit institutions and individual researchers.
         
         “Prohibited Parties” means: (a) any military, intelligence, or defense organization; (b) any person or entity acting on behalf of, funded by, contracting for, or in material collaboration with such organizations; (c) defense contractors and subcontractors at any tier; and (d) any party on an applicable sanctions or export‑control list.
         
         “Prohibited Purposes” means any military, intelligence, or defense application, including but not limited to weapons design or operation, command‑and‑control, targeting, surveillance or reconnaissance outside lawful civilian law‑enforcement norms, signals or human intelligence collection/analysis, cyber offense, battlefield logistics, training, simulation, or testing in support of any of the foregoing.
         
         2. License Grant
         Subject to full and continuous compliance with this License, the Licensor grants the Licensee a personal, worldwide, non‑exclusive, non‑transferable, non‑sublicensable, revocable license to:
         
         access and use the Licensed Work solely for Non‑Commercial Use;
         
         reproduce the Licensed Work for Non‑Commercial Use;
         
         create, use, and reproduce Modifications for Non‑Commercial Use;
         
         distribute the Licensed Work and Modifications for Non‑Commercial Use only, strictly under the terms of this same License.
         
         No rights are granted by implication or estoppel. All rights not expressly granted are reserved.
         
         3. Field-of-Use and User Restrictions
         No Commercial Use: Use by for‑profit entities or for revenue‑generating, production, operational, or service‑providing purposes (including SaaS, internal business operations, consulting deliverables, or advertising‑supported offerings) is prohibited.
         
         No Military/Intelligence Use: Use by or for any Prohibited Parties or for any Prohibited Purposes is strictly prohibited.
         
         No Indirect Facilitation: The Licensed Work and any Modifications must not be used to enable, assist, train, fine‑tune, integrate, evaluate, or otherwise support any activity by Prohibited Parties or for Prohibited Purposes, whether directly or indirectly, including through intermediaries, contractors, agents, affiliates, resellers, or downstream recipients.
         
         Government Use: Civilian government use is permitted only to the extent it is Non‑Commercial and not for Prohibited Purposes.
         
         4. Redistribution and Pass‑Through
         Any redistribution of the Licensed Work or Modifications must be solely for Non‑Commercial Use and must include a complete, verbatim copy of this License, copyright notices, and any attribution notices provided by the Licensor.
         
         The Licensee must not impose additional terms that conflict with or dilute the restrictions herein, and must not sublicense under different terms.
         
         Any downstream recipient automatically becomes a “Licensee” under this License and must accept it prior to use or receipt.
         
         5. Source Availability and Network Use
         If the Licensed Work or Modifications are made available to third parties in object code or are used to provide functionality over a network to third parties (including via web services, APIs, or hosted interfaces), the complete corresponding source code for the provided functionality must be made available to those third parties at no charge under this same License.
         
         “Corresponding source” means all source files and build scripts necessary to generate, install, and run the distributed or network‑accessible components, excluding general‑purpose tools and unmodified third‑party dependencies distributed under their own licenses.
         
         6. Attribution and Notices
         Copyright and license notices provided by the Licensor must be preserved in source distributions and, where technically feasible, in user‑visible notices for object/hosted deployments.
         
         The names “Aless Microsystems” and “Albert Blasczykowski” may not be used to endorse or promote derivative projects without prior written permission.
         
         7. Third-Party Software
         The Licensed Work may include or interface with third‑party components that are licensed under their own terms. Those terms govern such components, and nothing in this License grants rights to third‑party intellectual property.
         
         8. Support, Issues, and Verification
         Support Channel: Any voluntary support, issue triage, or feature request process (if offered) is available exclusively through the Licensor’s designated public issue tracker as announced by the Licensor from time to time.
         
         Currently Support Channel is only at Github issue tracker at https://github.com/alessblaze/Matrices-Evolved/issues 
         
         Identity Requirement: Issue submitters must provide their full legal name; anonymous or pseudonymous requests may be declined.
         
         No Indirect Support: Requests submitted by or on behalf of Prohibited Parties, or attempts to route support through intermediaries, may be refused.
         
         Discretionary Nature: Support is provided at the Licensor’s discretion and is not a contractual obligation.
         
         9. Compliance Assurance
         On reasonable written request, the Licensee must provide a short, good‑faith written attestation describing the Licensee’s Non‑Commercial Use and confirming that neither the Licensee nor known downstream recipients are Prohibited Parties and that the Licensed Work is not used for Prohibited Purposes.
         
         The Licensor may decline or terminate distribution, updates, keys, or access to new versions upon credible evidence of non‑compliance.
         
         10. Term and Termination
         This License is effective upon first access to or use of the Licensed Work and continues unless terminated.
         
         Immediate Termination: All rights under this License terminate automatically and without notice if any term is breached, including but not limited to any Commercial Use, use by or for Prohibited Parties, or use for Prohibited Purposes.
         
         Post‑Termination: Upon termination, all use must cease, and all copies (including Modifications) must be destroyed or permanently deleted; sections that by their nature should survive (including 3–7 and 9–15) shall survive.
         
         Reinstatement: Any reinstatement is solely at the Licensor’s written discretion.
         
         11. No Warranty
         THE LICENSED WORK IS PROVIDED “AS IS” AND “AS AVAILABLE” WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, NON‑INFRINGEMENT, ACCURACY, OR RELIABILITY.
         
         12. Limitation of Liability
         TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL THE LICENSOR BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES, OR FOR ANY LOSS OF PROFITS, REVENUE, DATA, OR GOODWILL, ARISING OUT OF OR RELATING TO THIS LICENSE OR THE LICENSED WORK, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. THE LICENSOR’S AGGREGATE LIABILITY SHALL NOT EXCEED ONE HUNDRED U.S. DOLLARS (USD $100).
         
         13. Export Controls and Sanctions
         The Licensee represents and warrants compliance with all applicable export‑control and sanctions laws and regulations and shall not export, re‑export, transfer, or make available the Licensed Work or Modifications in violation thereof.
         
         14. Privacy and Data
         The Licensed Work is not designed to process regulated personal data unless expressly stated by the Licensor; the Licensee is solely responsible for compliance with applicable data‑protection laws in any deployment.
         
         15. Injunctive Relief
         Breach of Sections 3–5 constitutes irreparable harm for which monetary damages may be inadequate; the Licensor is entitled to seek immediate injunctive or equitable relief in addition to any other remedies available at law or in equity.
         
         16. Governing Law and Forum
         This License is governed by the laws of India, without regard to conflicts of law principles. Courts located in Bengaluru, Karnataka, India shall have exclusive jurisdiction and venue over all disputes arising out of or relating to this License.
         
         17. Severability; No Waiver
         If any provision is held unenforceable, it shall be reformed to the minimum extent necessary to be enforceable, and the remainder shall continue in effect. Failure to enforce any provision shall not constitute a waiver.
         
         18. Assignment
         The Licensee may not assign, delegate, or transfer this License, by operation of law or otherwise, without the Licensor’s prior written consent. Any unauthorized assignment is void.
         
         19. Entire Agreement; Changes
         This License is the entire agreement concerning the Licensed Work and supersedes all prior understandings related to its subject matter. The Licensor may publish updated versions for new releases; existing releases remain under the version accompanying that release unless the Licensor permits re‑licensing.
         
         20. Compliance with Laws
         Use of the Licensed Work must comply with all applicable laws and regulations, including those relating to dual‑use technologies and end‑use restrictions.
         
         By accessing, using, modifying, or distributing the Licensed Work, the Licensee accepts this License and confirms understanding of the non‑commercial scope, no‑military/intelligence prohibitions, and redistribution/source‑availability obligations.
         
         
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.8
Requires-Dist: nanobind>=2.0.0
Description-Content-Type: text/markdown

# Matrices Evolved
<img width="1536" height="1024" alt="matrices_evolved" src="https://github.com/user-attachments/assets/49763adb-6660-438d-9791-0a3a0855d5a3" />




## Features

- **Dual Implementation Support** - Choose between C++ (nanobind) or Rust (PyO3) backends
- **Ed25519 Digital Signatures** - Fast cryptographic signing and verification
- **JSON Canonicalization** - Matrix-compatible canonical JSON encoding  
- **Base64 Operations** - Optimized encoding/decoding
- **Hash Computation** - SHA256 content and reference hashing
- **Key Management** - Generate, encode, and manage signing keys
- **Matrix Protocol Compatible** - Drop-in replacement for Matrix implementations
- **High Performance** - 10-100% faster than pure Python implementations

## Installation

### Prerequisites

**For C++ Implementation:**
- **Clang 20** (required for C++23 support)
- **Python 3.8+**
- **CMake 3.15+**

**For Rust Implementation:**
- **Rust 1.86+** (required for latest PyO3 features)
- **Cargo**

### Install from PyPI
### Only Python 3.11 wheels available. RHEL9/Ubuntu 22.04 both support it.
## Maybe Python 3.12 in future but for now only 3.11.
```bash
pip install matrices-evolved
```

### Build from Source

**C++ Implementation (default):**
```bash
git clone https://github.com/alessblaze/matrices_evolved.git
cd matrices_evolved
pip install .
```

**Rust Implementation:**
```bash
pip install . -C cmake.define.BUILD_RUST=ON -C cmake.define.BUILD_CPP=OFF
```

**Both Implementations:**
```bash
pip install . -C cmake.define.BUILD_RUST=ON
```

## Quick Start

```python
import matrices_evolved

# Generate signing keys
signing_key = matrices_evolved.generate_signing_key('ed25519')
verify_key = matrices_evolved.get_verify_key(signing_key)

# Sign a Matrix event
event = {"type": "m.room.message", "content": {"body": "Hello!"}}
signed_event = matrices_evolved.sign_json_object_fast(
    event, "myserver.com", signing_key, "ed25519:v1"
)

# Verify the signature
matrices_evolved.verify_signed_json_fast(signed_event, "myserver.com", verify_key)
print("✅ Signature verified!")
```

## Implementation Selection

```python
# Auto-select (prefers C++ if available)
import matrices_evolved

# Explicit C++ implementation
import matrices_evolved.cpp as crypto

# Explicit Rust implementation  
import matrices_evolved.rust as crypto

# Check available implementations
print(matrices_evolved.__implementations__)  # ['cpp', 'rust']
```

## Performance

Both implementations provide significant performance improvements over pure Python:

- **10-100x faster** signing and verification
- **5-50x faster** JSON canonicalization  
- **2-10x faster** base64 operations
- **Minimal memory overhead** with zero-copy operations

**Import Performance:**
- C++ import: ~3.5ms
- Rust import: ~0.1ms (25x faster)

## Development

For detailed build instructions, compiler requirements, and build options, see [BUILD.md](BUILD.md).

### Quick Development Setup

```bash
# Install Clang 20 from LLVM repository
wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
echo "deb http://apt.llvm.org/$(lsb_release -cs)/ llvm-toolchain-$(lsb_release -cs)-20 main" | sudo tee /etc/apt/sources.list.d/llvm.list
sudo apt update && sudo apt install clang-20

# Install Rust 1.86+
rustup toolchain install 1.86.0

# Development build with both implementations
pip install -e . -C cmake.define.BUILD_RUST=ON
```

## Compatibility

- **Python 3.8+**
- **Linux** (Ubuntu/Debian recommended)
- **100% compatible** with Matrix protocol specifications
- **Thread-safe** operations
- **Drop-in replacement** for existing Matrix crypto libraries

## Architecture

```
matrices_evolved/
├── cpp/                    # C++ nanobind implementation
│   ├── base64/            # SIMD-optimized base64 encoders/decoders
│   │   ├── encoders/      # Multiple encoder implementations
│   │   └── decoders/      # Multiple decoder implementations
│   ├── benchmark/         # Performance benchmarking suite
│   │   ├── simde/         # SIMD Everywhere submodule
│   │   └── full_bench.cpp # Comprehensive benchmarks
│   ├── crypto/            # Ed25519 cryptographic operations
│   │   └── ed25519.cpp    # Digital signatures & key management
│   ├── json/              # JSON canonicalization
│   │   └── canonicalization.cpp # SIMD-optimized JSON processing
│   ├── debug.h            # Debug infrastructure & shared definitions
│   ├── global.h           # Global includes & nanobind setup
│   └── lib.cpp            # Python bindings & module definition
├── rust/                  # Rust PyO3 implementation
│   ├── crypto/
│   │   ├── event_signing.rs # Ed25519 operations
│   │   ├── cache.rs       # LRU cache implementation
│   │   └── stream_change_cache.rs # Stream change tracking
│   ├── Cargo.toml
│   └── lib.rs
├── matrices_evolved/      # Python package
│   ├── __init__.py       # Auto-selection logic
│   ├── cpp.py            # C++ wrapper
│   └── rust.py           # Rust wrapper
└── CMakeLists.txt        # Build configuration
```
## In Progress

LRU, Stream Cache.
You would need a wrapper to function these properly. these expose core functionality in cache.rs and event_signing.rs but more needed on python wrapper.
the bindings are already there but currently not written in api docs.

# Synthetic Benchmarks
```
Pure Python LRU:
   synmark.suites.lrucache_auto: Mean +- std dev: 3.17 us +- 0.08 us
   synmark.suites.lrucache_evict_auto: Mean +- std dev: 3.06 us +- 0.08 us
   Rust Wrapper LRU:
   synmark.suites.lrucache_auto: Mean +- std dev: 900 ns +- 19 ns
   synmark.suites.lrucache_evict_auto: Mean +- std dev: 879 ns +- 20 ns

Formula:
   Improvement (%) = ((Python_time - Rust_time) / Python_time) × 100

Results:
    1. lrucache_auto:       ((3170 - 900) / 3170) × 100 ≈ 71.6% faster
    2. lrucache_evict_auto: ((3060 - 879) / 3060) × 100 ≈ 71.3% faster


crypto:
Pure rust bench:
    benches/crypto_bench.rs (/mnt/build/Tests/signal/hula/synapse/target/release/deps/crypto_bench-b4730a09c1fd000f)
    Gnuplot not found, using plotters backend
    Benchmarking pure_rust_canonicalization
    Benchmarking pure_rust_canonicalization: Warming up for 3.0000 s
    Benchmarking pure_rust_canonicalization: Collecting 100 samples in estimated 5.0027 s (9.1M iterations)
    Benchmarking pure_rust_canonicalization: Analyzing
    pure_rust_canonicalization
                        time:   [533.77 ns 534.46 ns 535.21 ns]
    Benchmarking pure_rust_ed25519_sign
    Benchmarking pure_rust_ed25519_sign: Warming up for 3.0000 s
    Benchmarking pure_rust_ed25519_sign: Collecting 100 samples in estimated 5.0250 s (601k iterations)
    Benchmarking pure_rust_ed25519_sign: Analyzing
    pure_rust_ed25519_sign  time:   [8.3256 µs 8.3447 µs 8.3633 µs]
    Found 2 outliers among 100 measurements (2.00%)
      2 (2.00%) high severe
    Benchmarking pure_rust_base64_encode
    Benchmarking pure_rust_base64_encode: Warming up for 3.0000 s
    Benchmarking pure_rust_base64_encode: Collecting 100 samples in estimated 5.0004 s (26M iterations)
    Benchmarking pure_rust_base64_encode: Analyzing
    pure_rust_base64_encode time:   [194.77 ns 195.08 ns 195.39 ns]
    Found 3 outliers among 100 measurements (3.00%)
      1 (1.00%) low severe
      2 (2.00%) high severe

Synmark bench Crypto:
Note: Python code probably has no keycaching as we did not write these functions. they are directly tested
against synapse provided functions.
Running PYTHON implementation:
    canonicalization: 1.99 μs per operation
    base64_encoding: 0.68 μs per operation
    base64_decoding: 1.34 μs per operation
    content_hash: 2.41 μs per operation
    json_signing: 19.75 μs per operation
    signature_verification: 48.15 μs per operation
    synmark.suites.crypto_operations_auto: Mean +- std dev: 73.0 us +- 1.5 us
Note: Now Rust implementation also uses keycaching but the vectorization is not done manually thus
the mean result may be a bit misleading in real life scenarios.
Running RUST implementation:
    canonicalization: 0.99 μs per operation
    base64_encoding: 4.74 μs per operation
    base64_decoding: 0.38 μs per operation
    content_hash: 0.99 μs per operation
    json_signing: 10.99 μs per operation
    signature_verification: 36.73 μs per operation
    synmark.suites.crypto_operations_auto: Mean +- std dev: 55.3 us +- 0.3 us

Note: C++ uses Vecorization if enables so synthetic benchmarks like synmark spawn many processes
usually in practice it would be faster due to continouous runs which reduces vecorization setup
times. Mainly in smaller inputs vectorizations is not recomended but we can utilize the workload
well in our scenatio, added private key caching improved the json signing but it is thread local
matrix signing usually uses one single key to sign so caching a key helps for key object processing
on openssl reduction on every call.
Note: C++ uses an iterative approach to json structure walk, Rust uses recursion.
Running C++ implementation:
    canonicalization: 0.60 μs per operation
    base64_encoding: 0.25 μs per operation
    base64_decoding: 0.16 μs per operation
    content_hash: 0.72 μs per operation
    json_signing: 9.69 μs per operation
    signature_verification: 35.68 μs per operation
    synmark.suites.crypto_operations_auto: Mean +- std dev: 46.5 us +- 1.3 us

    
Stream Change Bench Results :
Pure python:
    synmark.suites.stream_change_cache_auto: Mean +- std dev: 2.26 us +- 0.12 us
Rust Wrapper:
    synmark.suites.stream_change_cache_rust_auto: Mean +- std dev: 559 ns +- 28 ns
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

### Code Style

- **C++**: Follow C++23 best practices, use clang-format
- **Rust**: Follow rustfmt conventions, use clippy
- **Python**: Follow PEP 8, use black formatter

## License

See [LICENSE](LICENSE) file for details.

## Links

- **API Documentation**: [API.md](API.md)
- **Build Instructions**: [BUILD.md](BUILD.md)
- **Issues**: [GitHub Issues](https://github.com/alessblaze/matrices_evolved/issues)
- **Matrix Protocol**: [Matrix Specification](https://spec.matrix.org/)
