Represents a member of the Grumpkin curve scalar field (i.e. BN254 base field). More...

#include <cycle_scalar.hpp>

Public Types
enum class	SkipValidation { FLAG }

using	field_t = stdlib::field_t< Builder >

using	Curve = typename Builder::EmbeddedCurve

using	ScalarField = typename Curve::ScalarField

using	BigScalarField = stdlib::bigfield< Builder, typename ScalarField::Params >

Public Member Functions
	cycle_scalar (const ScalarField &in=0)
	Construct a circuit-constant cycle scalar from a value in the Grumpkin scalar field.

	cycle_scalar (const field_t &lo, const field_t &hi)
	Construct a cycle_scalar from lo and hi field elements.

	cycle_scalar (BigScalarField &scalar)
	Construct a new cycle scalar from a bigfield scalar.

bool	is_constant () const

ScalarField	get_value () const

Builder *	get_context () const

const field_t &	lo () const

const field_t &	hi () const

OriginTag	get_origin_tag () const
	Get the origin tag of the cycle_scalar (a merge of the lo and hi tags)

void	set_origin_tag (const OriginTag &tag)
	Set the origin tag of lo and hi members of cycle scalar.

void	set_free_witness_tag ()
	Set the free witness flag for the cycle scalar's tags.

void	unset_free_witness_tag ()
	Unset the free witness flag for the cycle scalar's tags.

Static Public Member Functions
static cycle_scalar	from_witness (Builder *context, const ScalarField &value)
	Construct a cycle scalar from a witness value in the Grumpkin scalar field.

Static Public Attributes
static constexpr size_t	NUM_BITS = ScalarField::modulus.get_msb() + 1

static constexpr size_t	LO_BITS = field_t::native::Params::MAX_BITS_PER_ENDOMORPHISM_SCALAR

static constexpr size_t	HI_BITS = NUM_BITS - LO_BITS

Private Member Functions
	cycle_scalar (const field_t &lo, const field_t &hi, SkipValidation flag)
	Private constructor that skips field validation (for internal use only)

void	validate_scalar_is_in_field () const
	Validates that the scalar (lo + hi * 2^LO_BITS) is less than the Grumpkin scalar field modulus.

Static Private Member Functions
static std::pair< uint256_t, uint256_t >	decompose_into_lo_hi_u256 (const uint256_t &value)
	Decompose a uint256_t value into lo and hi parts for cycle_scalar representation.

Private Attributes
field_t	_lo

field_t	_hi

Detailed Description

template<typename Builder>
class bb::stdlib::cycle_scalar< Builder >

Represents a member of the Grumpkin curve scalar field (i.e. BN254 base field).

The primary use for this class is scalar multiplication of points on the Grumpkin curve. For simplicity, class is hardcoded for 254-bit scalars

Note: The reason for not using bigfield to represent cycle scalars is that bigfield is inefficient in this context. All required range checks for cycle_scalar can be obtained for free from the batch_mul algorithm, making the range checks performed by bigfield largely redundant.

Warning: : The field validation performed by cycle_scalar constructors assumes that the lo/hi limbs will be range-constrained during scalar multiplication. The validation is ONLY sound when the cycle_scalar is used in a batch_mul operation (which applies range constraints as part of the MSM algorithm).

Definition at line 31 of file cycle_scalar.hpp.

Member Typedef Documentation

◆ BigScalarField

template<typename Builder >

using bb::stdlib::cycle_scalar< Builder >::BigScalarField = stdlib::bigfield<Builder, typename ScalarField::Params>

Definition at line 36 of file cycle_scalar.hpp.

◆ Curve

template<typename Builder >

using bb::stdlib::cycle_scalar< Builder >::Curve = typename Builder::EmbeddedCurve

Definition at line 34 of file cycle_scalar.hpp.

◆ field_t

template<typename Builder >

using bb::stdlib::cycle_scalar< Builder >::field_t = stdlib::field_t<Builder>

Definition at line 33 of file cycle_scalar.hpp.

◆ ScalarField

template<typename Builder >

using bb::stdlib::cycle_scalar< Builder >::ScalarField = typename Curve::ScalarField

Definition at line 35 of file cycle_scalar.hpp.

Member Enumeration Documentation

◆ SkipValidation

template<typename Builder >

enum class bb::stdlib::cycle_scalar::SkipValidation

strong

Enumerator
FLAG

Definition at line 46 of file cycle_scalar.hpp.

Constructor & Destructor Documentation

◆ cycle_scalar() [1/4]

template<typename Builder >

bb::stdlib::cycle_scalar< Builder >::cycle_scalar	(	const field_t &	lo,
		const field_t &	hi,
		SkipValidation	flag
	)

private

Private constructor that skips field validation (for internal use only)

This constructor is used internally in contexts where validation has already been performed externally or where it is not required at all (e.g., 256-bit bitstrings).

Template Parameters

Builder

Parameters

lo	Low LO_BITS of the scalar
hi	High HI_BITS of the scalar
flag	SkipValidation::FLAG explicitly indicates that validation should be skipped

Definition at line 26 of file cycle_scalar.cpp.

◆ cycle_scalar() [2/4]

template<typename Builder >

bb::stdlib::cycle_scalar< Builder >::cycle_scalar ( const ScalarField & in = 0 )

Construct a circuit-constant cycle scalar from a value in the Grumpkin scalar field.

Template Parameters

Builder

Parameters

in

Definition at line 59 of file cycle_scalar.cpp.

◆ cycle_scalar() [3/4]

template<typename Builder >

bb::stdlib::cycle_scalar< Builder >::cycle_scalar	(	const field_t &	lo,
		const field_t &	hi
	)

Construct a cycle_scalar from lo and hi field elements.

Standard public constructor. Validates that (lo + hi * 2^LO_BITS) is less than the Grumpkin scalar field modulus. Use this constructor when creating cycle_scalars from arbitrary field elements that may not have been previously validated.

Warning: The validation performed by this constructor is only sound if the resulting cycle_scalar is used in a scalar multiplication operation (batch_mul), which provides the necessary range constraints on lo and hi. See validate_scalar_is_in_field() documentation for details.

Template Parameters

Builder

Parameters

lo	Low LO_BITS of the scalar
hi	High HI_BITS of the scalar

Definition at line 46 of file cycle_scalar.cpp.

◆ cycle_scalar() [4/4]

template<typename Builder >

bb::stdlib::cycle_scalar< Builder >::cycle_scalar ( BigScalarField & scalar )

explicit

Construct a new cycle scalar from a bigfield scalar.

Construct the two cycle scalar limbs from the four limbs of a bigfield scalar as in the diagram below. Range constraints are applied as necessary to ensure the construction is unique:

BigScalarField (four 68-bit limbs): +-------—+-------—+-------—+-------—+ | limb0 | limb1 | limb2 | limb3 | +-------—+-------—+-------—+-------—+ | +-------—+-—+--—+-------—+-------—+ | limb0 | lo | hi | limb2 | limb3 | +-------—+-—+--—+-------—+-------—+ | +------------—+------------------------—+ | lo | hi | | (128 bits) | (126 bits) | +------------—|------------------------—+

The main steps of the algorithm are:

If necessary, self-reduce the bigfield scalar until it fits in LO_BITS + HI_BITS
Ensure limb0 fits in NUM_LIMB_BITS (if not, slice off excess and add to limb1)
Slice limb1 into two parts: limb1_lo (LO_BITS - NUM_LIMB_BITS bits), and limb1_hi (the remaining high bits)
Construct lo out of limb0 and limb1_lo
Construct hi out of limb1_hi, limb2 and limb3
Validate the scalar is in the Grumpkin scalar field

Note: To efficiently convert a bigfield into a cycle scalar we rely on the fact that scalar.lo and scalar.hi are implicitly range-constrained to be respectively 128 and 126 bits when they are further decomposed into slices for the batch mul algorithm.

Template Parameters

Builder

Parameters

scalar Note: passed by non-const reference since we may call self_reduce on it

Definition at line 126 of file cycle_scalar.cpp.

Member Function Documentation

◆ decompose_into_lo_hi_u256()

template<typename Builder >

static std::pair< uint256_t, uint256_t > bb::stdlib::cycle_scalar< Builder >::decompose_into_lo_hi_u256 ( const uint256_t & value )

inlinestaticprivate

Decompose a uint256_t value into lo and hi parts for cycle_scalar representation.

Parameters

value The value to decompose

Returns: std::pair<uint256_t, uint256_t> (lo, hi) where lo is LO_BITS and hi is the remaining bits

Definition at line 58 of file cycle_scalar.hpp.

◆ from_witness()

template<typename Builder >

cycle_scalar< Builder > bb::stdlib::cycle_scalar< Builder >::from_witness	(	Builder *	context,
		const ScalarField &	value
	)

static

Construct a cycle scalar from a witness value in the Grumpkin scalar field.

Creates a cycle_scalar from a witness and validates it is in the Grumpkin scalar field.

Note: Sets the free witness tag on the two limbs initially, but it is unset in validate_scalar_is_in_field.

Template Parameters

Builder

Parameters

context
value

Returns: cycle_scalar<Builder>

Definition at line 78 of file cycle_scalar.cpp.

◆ get_context()

template<typename Builder >

Builder * bb::stdlib::cycle_scalar< Builder >::get_context ( ) const

inline

Definition at line 78 of file cycle_scalar.hpp.

◆ get_origin_tag()

template<typename Builder >

OriginTag bb::stdlib::cycle_scalar< Builder >::get_origin_tag ( ) const

inline

Get the origin tag of the cycle_scalar (a merge of the lo and hi tags)

Returns: OriginTag

Definition at line 88 of file cycle_scalar.hpp.

◆ get_value()

template<typename Builder >

cycle_scalar< Builder >::ScalarField bb::stdlib::cycle_scalar< Builder >::get_value ( ) const

Definition at line 223 of file cycle_scalar.cpp.

◆ hi()

template<typename Builder >

const field_t & bb::stdlib::cycle_scalar< Builder >::hi ( ) const

inline

Definition at line 81 of file cycle_scalar.hpp.

◆ is_constant()

template<typename Builder >

bool bb::stdlib::cycle_scalar< Builder >::is_constant ( ) const

Definition at line 198 of file cycle_scalar.cpp.

◆ lo()

template<typename Builder >

const field_t & bb::stdlib::cycle_scalar< Builder >::lo ( ) const

inline

Definition at line 80 of file cycle_scalar.hpp.

◆ set_free_witness_tag()

template<typename Builder >

void bb::stdlib::cycle_scalar< Builder >::set_free_witness_tag ( )

inline

Set the free witness flag for the cycle scalar's tags.

Definition at line 102 of file cycle_scalar.hpp.

◆ set_origin_tag()

template<typename Builder >

void bb::stdlib::cycle_scalar< Builder >::set_origin_tag ( const OriginTag & tag )

inline

Set the origin tag of lo and hi members of cycle scalar.

Parameters

tag

Definition at line 94 of file cycle_scalar.hpp.

◆ unset_free_witness_tag()

template<typename Builder >

void bb::stdlib::cycle_scalar< Builder >::unset_free_witness_tag ( )

inline

Unset the free witness flag for the cycle scalar's tags.

Definition at line 110 of file cycle_scalar.hpp.

◆ validate_scalar_is_in_field()

template<typename Builder >

void bb::stdlib::cycle_scalar< Builder >::validate_scalar_is_in_field ( ) const

private

Validates that the scalar (lo + hi * 2^LO_BITS) is less than the Grumpkin scalar field modulus.

Delegates to validate_split_in_field_unsafe, which uses a borrow-subtraction algorithm to check the inequality.

Warning

This validation assumes range constraints on the lo and hi limbs. Specifically:

lo < 2^LO_BITS (128 bits)
hi < 2^HI_BITS (126 bits)

By design, these range constraints are not applied by this function. Instead, they are implicitly enforced when the cycle_scalar is used in scalar multiplication via batch_mul.

Template Parameters

Builder

Definition at line 217 of file cycle_scalar.cpp.

Member Data Documentation

◆ _hi

template<typename Builder >

field_t bb::stdlib::cycle_scalar< Builder >::_hi

private

Definition at line 50 of file cycle_scalar.hpp.

◆ _lo

template<typename Builder >

field_t bb::stdlib::cycle_scalar< Builder >::_lo

private

Definition at line 49 of file cycle_scalar.hpp.

◆ HI_BITS

template<typename Builder >

constexpr size_t bb::stdlib::cycle_scalar< Builder >::HI_BITS = NUM_BITS - LO_BITS

staticconstexpr

Definition at line 40 of file cycle_scalar.hpp.

◆ LO_BITS

template<typename Builder >

constexpr size_t bb::stdlib::cycle_scalar< Builder >::LO_BITS = field_t::native::Params::MAX_BITS_PER_ENDOMORPHISM_SCALAR

staticconstexpr

Definition at line 39 of file cycle_scalar.hpp.

◆ NUM_BITS

template<typename Builder >

constexpr size_t bb::stdlib::cycle_scalar< Builder >::NUM_BITS = ScalarField::modulus.get_msb() + 1

staticconstexpr

Definition at line 38 of file cycle_scalar.hpp.

The documentation for this class was generated from the following files:

src/barretenberg/stdlib/primitives/group/cycle_scalar.hpp
src/barretenberg/stdlib/primitives/group/cycle_scalar.cpp

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ BigScalarField

◆ Curve

◆ field_t

◆ ScalarField

Member Enumeration Documentation

◆ SkipValidation

Constructor & Destructor Documentation

◆ cycle_scalar() [1/4]

◆ cycle_scalar() [2/4]

◆ cycle_scalar() [3/4]

◆ cycle_scalar() [4/4]

Member Function Documentation

◆ decompose_into_lo_hi_u256()

◆ from_witness()

◆ get_context()

◆ get_origin_tag()

◆ get_value()

◆ hi()

◆ is_constant()

◆ lo()

◆ set_free_witness_tag()

◆ set_origin_tag()

◆ unset_free_witness_tag()

◆ validate_scalar_is_in_field()

Member Data Documentation

◆ _hi

◆ _lo

◆ HI_BITS

◆ LO_BITS

◆ NUM_BITS