hyper-u256 0.1.0

Arithmétique 256-bit ultra-rapide en no_std avec optimisation SIMD et zéro allocation pour les corps finis et la cryptographie.
Documentation
 ## ⚡ hyper-u256

[![Crates.io](https://img.shields.io/crates/v/hyper-u256.svg)](https://crates.io/crates/hyper-u256)
[![Documentation](https://docs.rs/hyper-u256/badge.svg)](https://docs.rs/hyper-u256)
[![License: GPL v2+](https://img.shields.io/badge/License-GPL_v2%2B-blue.svg)](LICENSE)
[![no_std](https://img.shields.io/badge/no__std-compatible-success.svg)](#)

Bibliothèque Rust **`no_std`**, **zéro allocation** et **100 % sécurisée (`#![deny(unsafe_code)]`)** conçue pour l'arithmétique haute performance sur des entiers non signés de 256 bits (`U256`).

Elle fournit des primitives d'arithmétique tronquée (*wrapping*), de réduction modulaire de Montgomery (*REDC*) et de traitement vectoriel par lots (*batching*), optimisées pour l'auto-vectorisation par le compilateur.

---

## ✨ Points forts

* **🔒 100 % Safe Rust** : Aucune utilisation de bloc `unsafe` (`#![deny(unsafe_code)]`).
* **📦 `no_std` & Zero-Allocation** : Aucun gestionnaire d'allocation requis ; tout s'exécute sur la pile (*stack*) et dans les registres CPU.
* **🎯 Alignement Mémoire Explicite** : 
  * `U256` est aligné sur **32 octets** (`#[repr(align(32))]`) pour coïncider avec la taille des registres 256-bit (AVX2/AVX-512) et optimiser les accès cache.
  * `U256x2` est aligné sur **64 octets** (`#[repr(align(64))]`), épousant exactement la taille d'une ligne de cache L1 moderne (*cache line*).
* **⚡ Conçu pour l'Auto-Vectorisation** : Structures adaptées à l'optimisation `autovectorize` de LLVM sans compromettre la sécurité de la mémoire.

---

## 🛠 Structure du projet

La crate est articulée autour de trois piliers principaux :

| Module / Structure | Description |
|---|---|
| **`U256`** | Entier 256 bits représenté sous forme de 4 mots de 64 bits (`[u64; 4]`). Supporte l'addition, la soustraction et la multiplication tronquées (`wrapping`). |
| **`MontgomeryContext`** | Gestionnaire de réduction modulaire de Montgomery (REDC) prenant une entrée de 512 bits (2x `U256`) pour retourner un résultat de 256 bits mod $N$. |
| **`U256x2`** | Structure de traitement SIMD/batching regroupant deux instances de `U256` (`low` et `high`) traitées en parallèle sans fuite de retenue (*carry*) entre les voies. |

---

## 🚀 Installation

Ajoute la dépendance suivante dans ton fichier `Cargo.toml` :

```toml
[dependencies]
hyper-u256 = "0.1.0"
```

## 📖 Exemples d'utilisation1. Arithmétique de base (wrapping_add, wrapping_sub, wrapping_mul)

```rust
use hyper_u256::U256;
// Instanciation à partir de 4 limbs u64 (du mot de poids faible au mot de poids fort)
let a = U256::from_limbs([u64::MAX, 0, 0, 0]);
let b = U256::ONE;

// Addition wrapping (2^256)
let sum = a.wrapping_add(&b);
assert_eq!(sum, U256::from_limbs([0, 1, 0, 0]));

// Soustraction wrapping
let diff = sum.wrapping_sub(&b);
assert_eq!(diff, a);

// Multiplication wrapping
let prod = a.wrapping_mul(&U256::from_limbs([2, 0, 0, 0]));
```
## 2. Réduction Modulaire de Montgomery (MontgomeryContext)Effectue la réduction REDC d'un nombre de 512 bits (représenté sous forme de deux U256 : low et high) vers un U256 strictement inférieur au module N.
```Rust 
use hyper_u256::montgomery::MontgomeryContext;
use hyper_u256::U256;

// Module BN254_P
const BN254_P: U256 = U256::from_limbs([
    0x43e1f593f0000001,
    0x2833e84879b97091,
    0xb85045b68181585d,
    0x30644e72e131a029,
]);

// Constante k0 = -N^-1 mod 2^64
const BN254_K0: u64 = 0xc2e1f593efffffff;

let ctx = MontgomeryContext::new(BN254_P, BN254_K0);

// Réduction de (low=0, high=0) -> 0
let res = ctx.reduce(U256::ZERO, U256::ZERO);
assert_eq!(res, U256::ZERO);

```
## 3. Traitement Vectoriel par Lots (U256x2)Exécute deux opérations arithmétiques 256 bits simultanément tout en garantissant l'isolation complète des voies (lanes).

```Rust
use hyper_u256::simd::U256x2;
use hyper_u256::U256;

let pair1 = U256x2::new(U256::ONE, U256::from_limbs([10, 0, 0, 0]));
let pair2 = U256x2::new(U256::from_limbs([5, 0, 0, 0]), U256::from_limbs([20, 0, 0, 0]));

// Addition en parallèle
let sum = pair1.add_pair(&pair2);
assert_eq!(sum.low, U256::from_limbs([6, 0, 0, 0]));
assert_eq!(sum.high, U256::from_limbs([30, 0, 0, 0]));

// Multiplication en parallèle
let prod = pair1.mul_pair(&pair2);
assert_eq!(prod.low, U256::from_limbs([5, 0, 0, 0]));
assert_eq!(prod.high, U256::from_limbs([200, 0, 0, 0]));
```

## 📐 Alignement et Finesse Mémoirehyper-u256 est conçu pour maximiser l'utilisation de la bande passante mémoire et éliminer les pénalités d'accès désalignés :
U256   (32 octets)  : [ Limb 0 | Limb 1 | Limb 2 | Limb 3 ] -> Alignement 32 bytes
U256x2 (64 octets)  : [      U256 low      |     U256 high     ] -> Alignement 64 bytes (1 L1 Cache Line)

## 🛡 Garanties de Sécurité
- #![no_std] : Compatible avec les environnements bare-metal, WebAssembly et noyaux applicatifs.
- #![deny(unsafe_code)] : Interdit tout comportement indéfini (undefined behavior). La sûreté mémoire est garantie à 100 % au niveau de la compilation.

## ✅ Tests
```bash
cargo test
```
Couvre l'addition, la soustraction, la multiplication (y compris des cas de non-régression sur la propagation de retenue entre limbes) et la réduction de Montgomery contre des vecteurs vérifiés indépendamment.

## 🔬 Fuzzing Industriel (AFL / libFuzzer)

Le projet intègre un harness de fuzzing dans le dossier fuzz/ pour valider l'exactitude mathématique contre la référence num-bigint sur des centaines de millions de cas générés aléatoirement :
Bash

cargo +nightly fuzz run fuzz_ops

## 📜 Licence

Ce projet est publié sous GPL-2.0-or-later. Voir le fichier LICENSE pour les détails.

## Copyright (C) 2026 Jorge Andre Castro