Struct Goldilocks 

pub struct Goldilocks(pub u64);

Goldilocks field element.

The Goldilocks field uses prime modulus p = 2^64 - 2^32 + 1, which is optimized for:

• Fast modular reduction using bit manipulation
• Efficient 64-bit CPU operations
• Zero-Knowledge proof systems (Plonky2, STARKs)

Example

use poseidon_hash::Goldilocks;

let a = Goldilocks::from_canonical_u64(42);
let b = Goldilocks::from_canonical_u64(10);
let sum = a.add(&b);
let product = a.mul(&b);

Tuple Fields

0: u64

Implementations

impl Goldilocks

pub const MODULUS: u64 = 0xffffffff00000001

Field modulus: p = 2^64 - 2^32 + 1 = 0xffffffff00000001

pub const EPSILON: u64 = 0xffffffff

Epsilon constant: (1 << 32) - 1 = 0xffffffff Used for efficient modular reduction

pub const ORDER: u64 = Self::MODULUS

The order of the field (same as MODULUS)

pub fn zero() -> Self

Returns the zero element of the field.

pub fn one() -> Self

Returns the multiplicative identity (one) of the field.

pub fn is_zero(&self) -> bool

Checks if this element is zero.

pub fn to_canonical_u64(&self) -> u64

Converts this field element to its canonical representation as a u64.

The canonical form ensures the value is in the range [0, MODULUS).

pub fn add(&self, other: &Goldilocks) -> Goldilocks

Adds two field elements with modular reduction.

Example

use poseidon_hash::Goldilocks;

let a = Goldilocks::from_canonical_u64(100);
let b = Goldilocks::from_canonical_u64(50);
let sum = a.add(&b);
assert_eq!(sum.to_canonical_u64(), 150);

pub fn sub(&self, other: &Goldilocks) -> Goldilocks

Subtracts two field elements with modular reduction.

Example

use poseidon_hash::Goldilocks;

let a = Goldilocks::from_canonical_u64(100);
let b = Goldilocks::from_canonical_u64(50);
let diff = a.sub(&b);
assert_eq!(diff.to_canonical_u64(), 50);

pub fn mul(&self, other: &Goldilocks) -> Goldilocks

Multiplies two field elements with modular reduction.

Uses optimized reduction algorithm for the Goldilocks prime.

Example

use poseidon_hash::Goldilocks;

let a = Goldilocks::from_canonical_u64(10);
let b = Goldilocks::from_canonical_u64(5);
let product = a.mul(&b);
assert_eq!(product.to_canonical_u64(), 50);

pub fn square(&self) -> Goldilocks

Computes the square of this field element.

More efficient than self.mul(self) as it can use optimized squaring formulas.

pub fn double(&self) -> Goldilocks

Doubles this field element (multiplies by 2).

pub fn neg(&self) -> Goldilocks

Computes the additive inverse (negation) of this field element.

Returns 0 for the zero element; otherwise returns p - x where p is the modulus.

Example

use poseidon_hash::Goldilocks;

let a = Goldilocks::from_canonical_u64(42);
let neg_a = a.neg();
assert!(neg_a.add(&a).is_zero(), "a + (-a) must be zero");
assert_eq!(neg_a.neg().to_canonical_u64(), a.to_canonical_u64(), "-(-a) must equal a");

pub fn inverse(&self) -> Goldilocks

Computes the multiplicative inverse of this field element.

Uses Fermat’s little theorem: a^(-1) ≡ a^(p-2) mod p

Returns 0 when called on the zero element (analogous to inverse_or_zero()). Use the explicit check if self.is_zero() before calling when a zero input indicates a logic error in your code.

pub fn from_canonical_u64(val: u64) -> Goldilocks

Creates a field element from a canonical u64 value.

The input value is unconditionally reduced modulo MODULUS, so values in the range [MODULUS, u64::MAX] are accepted and normalised. In debug builds an assertion fires for non-canonical inputs so callers can catch unintended use early.

Example

use poseidon_hash::Goldilocks;

let a = Goldilocks::from_canonical_u64(42);
// Values above MODULUS are silently reduced.
let b = Goldilocks::from_canonical_u64(Goldilocks::MODULUS + 1);
assert_eq!(b.to_canonical_u64(), 1);

pub fn from_noncanonical_u64(val: u64) -> Goldilocks

Creates a field element from any u64 value, reducing modulo MODULUS.

Use this when the input may legitimately exceed MODULUS (e.g. when deserialising untrusted data or computing intermediate results).

pub fn from_i64(val: i64) -> Goldilocks

Creates a field element from an i64 value.

Negative values are handled using two’s complement representation. The field operations will automatically reduce the value modulo MODULUS.

Example

use poseidon_hash::Goldilocks;

let a = Goldilocks::from_i64(-10);

pub fn sqrt(&self) -> Option<Goldilocks>

Computes the square root of this field element using Tonelli-Shanks algorithm.

Returns Some(sqrt) if the square root exists, None otherwise.

For Goldilocks field p = 2^64 - 2^32 + 1, implements full Tonelli-Shanks. p - 1 = 2^32 * (2^32 - 1) = 2^32 * q where q = 0xFFFFFFFF is odd.

pub fn exp_power_of_2(&self, n: usize) -> Goldilocks

Raises this element to the power of 2^n by repeated squaring.

Example

use poseidon_hash::Goldilocks;

let a = Goldilocks::from_canonical_u64(5);
let result = a.exp_power_of_2(3); // a^(2^3) = a^8

pub fn equals(&self, other: &Goldilocks) -> bool

Checks if two Goldilocks elements are equal.

pub fn exp(&self, exponent: u64) -> Goldilocks

Exponentiation: raises this element to a power.

Uses binary exponentiation (square-and-multiply algorithm).

impl Goldilocks

pub fn to_bytes_le(&self) -> [u8; 8]

Serialises this element as 8 little-endian bytes.

The output always uses the canonical representation (value reduced mod MODULUS).

pub fn from_bytes_le(bytes: &[u8]) -> Result<Self, String>

Deserialises a Goldilocks element from 8 little-endian bytes.

Returns Err if bytes is not exactly 8 bytes long or if the decoded u64 value is ≥ MODULUS (i.e. not a canonical field element).

pub fn to_hex(&self) -> String

Encodes this element as a 16-character lowercase hex string.

The hex string always represents canonical (reduced) bytes, little-endian.

pub fn from_hex(s: &str) -> Result<Self, String>

Decodes a Goldilocks element from a 16-character hex string.

Accepts an optional 0x prefix. Returns Err if the hex is malformed, the wrong length, or the decoded value ≥ MODULUS.

Trait Implementations

impl Clone for Goldilocks

fn clone(&self) -> Goldilocks

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Goldilocks

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Goldilocks

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<u64> for Goldilocks

fn from(val: u64) -> Self

Converts to this type from the input type.

impl PartialEq for Goldilocks

Two Goldilocks elements are equal iff they represent the same field element, i.e., their canonical (reduced mod p) values are identical. This is necessary because arithmetic operations (especially mul) can produce non-canonical representations where the raw u64 exceeds the modulus.

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Zeroize for Goldilocks

fn zeroize(&mut self)

Zero out this object from memory using Rust intrinsics which ensure the zeroization operation is not “optimized away” by the compiler.

impl Copy for Goldilocks

impl Eq for Goldilocks