Struct FieldElement

Source

pub struct FieldElement { /* private fields */ }

Expand description

FieldElement represents an element of the field modulo p = 2^255 - 19.

Values are stored in Montgomery form for efficient multiplication.

Implementations§

Source §

impl FieldElement

Source

pub fn from_bytes(bytes: &[u8; 32]) -> Result<Self, MathError>

Create a FieldElement from bytes (canonical representation).

The bytes must represent a value in the range [0, p). Values outside this range will result in an error.

§Examples

use clock_curve_math::FieldElement;

let bytes = [1u8; 32]; // Little-endian representation of a small number
let element = FieldElement::from_bytes(&bytes).unwrap();
assert_eq!(element.to_bytes(), bytes);

§Errors

Returns crate::error::MathError::InvalidBytes if the byte representation is not in [0, p).

Source

pub fn to_bytes(&self) -> [u8; 32]

Convert to bytes (canonical representation).

Returns the canonical little-endian byte representation of the field element. The result is guaranteed to be in the range [0, p).

§Examples

use clock_curve_math::FieldElement;

let element = FieldElement::from_u64(42);
let bytes = element.to_bytes();
let reconstructed = FieldElement::from_bytes(&bytes).unwrap();
assert_eq!(element, reconstructed);

Source

pub fn from_u64(value: u64) -> Self

Create a FieldElement from a u64 value.

The value is automatically reduced modulo p if necessary.

§Examples

use clock_curve_math::FieldElement;

let zero = FieldElement::from_u64(0);
let one = FieldElement::from_u64(1);
let large = FieldElement::from_u64(u64::MAX); // Will be reduced mod p

Source

pub fn from_bigint(value: &BigInt) -> Result<Self, MathError>

Create a FieldElement from a BigInt value with validation.

The value must be in the range [0, p) where p is the field modulus.

§Examples

use clock_curve_math::{FieldElement, BigInt};

let value = BigInt::from_u64(42);
let element = FieldElement::from_bigint(&value).unwrap();

§Errors

Returns crate::error::MathError::InvalidFieldElement if the value is not in [0, p).

Source

pub fn to_bigint(&self) -> BigInt

Convert a FieldElement to a BigInt.

Returns the Montgomery representation of the field element as a BigInt. To get the regular representation, use from_montgomery on the result.

§Examples

use clock_curve_math::{FieldElement, BigInt};

let element = FieldElement::from_u64(42);
let bigint = element.to_bigint();
let regular = clock_curve_math::montgomery::from_montgomery_p(&bigint);
assert_eq!(regular, BigInt::from_u64(42));

Source

pub fn conditional_select(a: &Self, b: &Self, choice: Choice) -> Self

Constant-time conditional selection.

Returns a if flag == 1, b if flag == 0. Executes in constant time regardless of the flag value.

§Safety

flag should be either 0 or 1 for correct behavior.

§Examples

use clock_curve_math::FieldElement;

let a = FieldElement::from_u64(10);
let b = FieldElement::from_u64(20);

let selected = FieldElement::conditional_select(&a, &b, clock_curve_math::ct::Choice::from_bool(true)); // selects a
assert_eq!(selected, a);

let selected = FieldElement::conditional_select(&a, &b, clock_curve_math::ct::Choice::from_bool(false)); // selects b
assert_eq!(selected, b);

Source

pub fn conditional_swap(a: &mut Self, b: &mut Self, flag: u64)

Constant-time conditional swap.

Swaps a and b if flag == 1, leaves them unchanged if flag == 0. Executes in constant time regardless of the flag value.

§Safety

flag should be either 0 or 1 for correct behavior.

§Examples

use clock_curve_math::FieldElement;

let mut a = FieldElement::from_u64(10);
let mut b = FieldElement::from_u64(20);

FieldElement::conditional_swap(&mut a, &mut b, 0);
assert_eq!(a, FieldElement::from_u64(10)); // unchanged
assert_eq!(b, FieldElement::from_u64(20)); // unchanged

FieldElement::conditional_swap(&mut a, &mut b, 1);
assert_eq!(a, FieldElement::from_u64(20)); // swapped
assert_eq!(b, FieldElement::from_u64(10)); // swapped

Source

pub fn is_valid(&self) -> bool

Check if the value is valid (in range [0, p)).

Returns true if the field element represents a value in [0, p). Field elements created through the public API are always valid.

§Examples

use clock_curve_math::FieldElement;

let element = FieldElement::from_u64(42);
assert!(element.is_valid());

Source

pub fn neg(&self) -> Self

Compute the additive inverse (negation).

Returns -self mod p, which satisfies self + (-self) ≡ 0 mod p.

§Examples

use clock_curve_math::{FieldElement, FieldOps};

let a = FieldElement::from_u64(5);
let neg_a = a.neg();
let sum = a.add(&neg_a);
assert_eq!(sum, FieldElement::from_u64(0));

Source

pub fn is_zero(&self) -> bool

Check if this field element is zero.

Returns true if the field element represents the additive identity (zero).

§Examples

use clock_curve_math::FieldElement;

let zero = FieldElement::from_u64(0);
let nonzero = FieldElement::from_u64(42);

assert!(zero.is_zero());
assert!(!nonzero.is_zero());