## ⚡ hyper-u256
[](https://crates.io/crates/hyper-u256)
[](https://docs.rs/hyper-u256)
[](LICENSE)
[](#)
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 :
| **`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