feat(ring): introduce RingElement API and bump version to 1.4.0 (#53)

* feat(ring): introduce `RingElement` API and bump version to `1.4.0`

- Add `RingElement<C>` for polynomial arithmetic in $R_q = \mathbb{Z}_q[X]/(X^N + 1)$ with dual-state (coefficient/NTT) representation and lazy conversion.
- Make `lumen_math::ring` module public for direct access.
- Update CHANGELOG, README, and tests to document and validate the new API.
- Bump crate version to `1.4.0`.

* feat(ring): add `modify_data` for safe coefficient modifications, refactor addition/subtraction logic, and expand tests

- Introduced `modify_data` method for safe mutation of polynomial coefficients, enforcing state consistency.
- Refactored addition and subtraction methods to simplify RHS state conversion logic.
- Expanded test coverage to validate edge cases, state transitions, format implementations, and API behavior.

Author: Tranduy1dol

CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.0] - 2026-01-06
+
+### Added
+
+- **Ring Element for Lattice Cryptography**: New `RingElement<C>` type for polynomials in $R_q = \mathbb{Z}_q[X]/(X^N + 1)$
+  - **Dual-state representation**: Coefficient form ↔ NTT form with lazy conversion
+  - **Arithmetic operations**: `Add`, `Sub`, `Mul`, `Neg` for both owned and reference types
+  - **State management**: `to_ntt()`, `to_coefficient()`, `into_ntt()`, `into_coefficient()`
+  - **Shared context**: Uses `Arc<NttContext<C>>` for efficient NTT table sharing
+  - **Query methods**: `state()`, `coefficients()`, `ntt_values()`, `is_zero()`, `scale()`
+  - Exports: `RingElement`, `RingElementState` from `lumen_math::ring`
+
+### Improved
+
+- **Public ring module**: `lumen_math::ring` is now public for direct access
+
 ## [1.3.0] - 2025-12-30
 
 ### Changed

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "lumen-math"
-version = "1.3.0"
+version = "1.4.0"
 edition = "2024"
 
 [dependencies]

Cargo.toml

@@ -15,6 +15,7 @@ A high-performance mathematical library for Rust, designed for cryptographic app
 - **Number Theoretic Transform (NTT)**: Fast polynomial multiplication using NTT (O(n log n)) with Cooley-Tukey algorithm.
 - **Negacyclic NTT**: Specialized NTT for lattice-based cryptography (Kyber/Dilithium) over rings $Z_q[X]/(X^N + 1)$.
 - **Small-Modulus Fields**: Optimized native `u32`/`u64` arithmetic with Barrett reduction for Kyber/Dilithium.
+- **Ring Elements**: `RingElement<C>` with dual-state (coefficient/NTT) representation and lazy conversion.
 - **Hardware Acceleration**: AVX2 optimized backend for specific operations on x86_64 architectures (e.g., XOR, conditional selection).
 - **GMP Integration**: Optional backend using GMP for verification and comparison (enabled via `gmp` feature).
 - **Cryptographic Protocols**: Implementation of Extended Euclidean Algorithm (GCD) and Chinese Remainder Theorem (CRT).
@@ -95,6 +96,25 @@ let d2 = DilithiumFieldElement::new(67890);
 let d_prod = d1 * d2;
 ```
 
+### Ring Elements (Polynomial Rings)
+
+For operations in polynomial rings $R_q = \mathbb{Z}_q[X]/(X^N + 1)$:
+
+```rust
+use lumen_math::{RingElement, NttContext, DefaultFieldConfig, fp};
+use std::sync::Arc;
+
+// Create shared NTT context
+let ctx = Arc::new(NttContext::<DefaultFieldConfig>::new(256));
+
+// Create ring elements
+let a = RingElement::new(vec![fp!(1u64); 256], ctx.clone());
+let b = RingElement::one(ctx);
+
+// Arithmetic (auto-converts between coefficient/NTT forms)
+let product = a * b;  // Uses NTT multiplication
+```
+
 ### Field Arithmetic (Generic)
 
 ```rust
@@ -152,6 +172,8 @@ The library is structured into several core modules:
 - **`protocol`**: Cryptographic primitives.
     - `gcd`: Extended Euclidean Algorithm.
     - `crt`: Chinese Remainder Theorem solver.
+- **`ring`**: Ring elements for lattice-based cryptography.
+    - `element`: `RingElement<C>` with dual-state (coefficient/NTT) representation.
 - **`traits`**: Core traits defining the interface for big integers and fields.
 
 ## Performance

README.md

@@ -249,6 +249,23 @@ $$
 | **Kyber** | 3329 | 256 | 17 | 289 |
 | **Dilithium** | 8380417 | 256 | 1753 | 3073009 |
 
+### Ring Elements
+
+The `RingElement<C>` type encapsulates polynomials in the ring $R_q$ with lazy state management:
+
+**State Representation:**
+- **Coefficient form**: $[c_0, c_1, \ldots, c_{N-1}]$ — natural representation
+- **NTT form**: $[\hat{c}_0, \hat{c}_1, \ldots, \hat{c}_{N-1}]$ — transformed for multiplication
+
+**Lazy Conversion:**
+- Addition/Subtraction: Operates in coefficient form (auto-converts if needed)
+- Multiplication: Operates in NTT form (pointwise multiplication is $O(N)$)
+- Negation: Works in either form (coefficient-wise negation)
+
+**Efficiency:**
+- Shared `NttContext<C>` via `Arc` avoids recomputing twiddle factors
+- State tracking prevents redundant conversions
+
 ---
 
 ## Number Theory Algorithms

THEORY.md

@@ -12,6 +12,7 @@ pub mod big_int;
 pub mod field;
 pub mod poly;
 pub mod protocol;
+pub mod ring;
 pub mod traits;
 
 pub use lumen_math_macros::FieldConfig;
@@ -45,6 +46,9 @@ pub use crate::poly::ntt::{NttContext, intt_negacyclic, mul_negacyclic, ntt_nega
 // Traits
 pub use traits::{BigInt, Digest};
 
+// Ring elements for lattice crypto
+pub use crate::ring::{RingElement, RingElementState};
+
 /// Computes N' for Montgomery reduction where P * N' = -1 mod 2^1024.
 ///
 /// This is a convenience re-export of `MontgomeryContext::compute_n_prime`.