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

#include <cycle_scalar.hpp>

Public Types
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)

	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

size_t	num_bits () const

bool	skip_primality_test () const

bool	use_bn254_scalar_field_for_primality_test () const

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

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) const
	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 cycle_scalar	from_u256_witness (Builder *context, const uint256_t &bitstring)
	Construct a cycle scalar from a uint256_t witness bitstring.

static cycle_scalar	create_from_bn254_scalar (const field_t &_in)
	Construct a cycle scalar (grumpkin scalar field element) from a bn254 scalar field element.

Public Attributes
field_t	lo

field_t	hi

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, const size_t bits, const bool skip_primality_test, const bool use_bn254_scalar_field_for_primality_test)

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
size_t	_num_bits = NUM_BITS

bool	_skip_primality_test = false

bool	_use_bn254_scalar_field_for_primality_test = false

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. It largely exists to abstract away the details of performing these operations with values of different origins, which may or may not originate from the Grumpkin scalar field, e.g. u256 values or BN254 scalars. In these cases we convert scalar multiplication inputs into cycle_scalars to enable scalar multiplication to be complete. E.g. multiplication of Grumpkin points by BN254 scalars does not produce a cyclic group as BN254::ScalarField < Grumpkin::ScalarField.

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.

Definition at line 30 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 35 of file cycle_scalar.hpp.

◆ Curve

template<typename Builder >

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

Definition at line 33 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 32 of file cycle_scalar.hpp.

◆ ScalarField

template<typename Builder >

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

Definition at line 34 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,
		const size_t	bits,
		const bool	skip_primality_test,
		const bool	use_bn254_scalar_field_for_primality_test
	)

inlineprivate

Definition at line 62 of file cycle_scalar.hpp.

◆ 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 27 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
	)

Definition at line 16 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

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 135 of file cycle_scalar.cpp.

Member Function Documentation

◆ create_from_bn254_scalar()

template<typename Builder >

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

static

Construct a cycle scalar (grumpkin scalar field element) from a bn254 scalar field element.

This method ensures that the input is constrained to be less than the bn254 scalar field modulus to ensure unique representation in the grumpkin scalar field.

Template Parameters

Builder

Parameters

in	a field_t representing a bn254 scalar field element

Returns: cycle_scalar<Builder> a cycle_scalar representing the same value in the grumpkin scalar field

Definition at line 89 of file cycle_scalar.cpp.

◆ 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 57 of file cycle_scalar.hpp.

◆ from_u256_witness()

template<typename Builder >

cycle_scalar< Builder > bb::stdlib::cycle_scalar< Builder >::from_u256_witness	(	Builder *	context,
		const uint256_t &	bitstring
	)

static

Construct a cycle scalar from a uint256_t witness bitstring.

Used when we want to multiply a group element by a string of bits of known size, e.g. for Schnorr signatures.

Note: This constructor method will make our scalar multiplication methods not perform primality tests.

Template Parameters

Builder

Parameters

context
value

Returns: cycle_scalar<Builder>

Definition at line 68 of file cycle_scalar.cpp.

◆ 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.

Note: Sets the free witness tag on the two limbs since they are not constrained in any way

Template Parameters

Builder

Parameters

context
value

Returns: cycle_scalar<Builder>

Definition at line 45 of file cycle_scalar.cpp.

◆ get_context()

template<typename Builder >

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

inline

Definition at line 86 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 105 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 228 of file cycle_scalar.cpp.

◆ is_constant()

template<typename Builder >

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

Definition at line 205 of file cycle_scalar.cpp.

◆ num_bits()

template<typename Builder >

size_t bb::stdlib::cycle_scalar< Builder >::num_bits ( ) const

inline

Definition at line 87 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 119 of file cycle_scalar.hpp.

◆ set_origin_tag()

template<typename Builder >

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

inline

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

Parameters

tag

Definition at line 111 of file cycle_scalar.hpp.

◆ skip_primality_test()

template<typename Builder >

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

inline

Definition at line 88 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 127 of file cycle_scalar.hpp.

◆ use_bn254_scalar_field_for_primality_test()

template<typename Builder >

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

inline

Definition at line 89 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

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

Checks against either bn254 scalar field or grumpkin scalar field based on internal flags

Checks against either bn254 scalar field or grumpkin scalar field based on internal flags. If _skip_primality_test is true, no validation is performed.

Note: : Implies (lo + hi * 2^LO_BITS) < field_modulus as integers when combined with appropriate range constraints on lo and hi.

Template Parameters

Builder

Definition at line 219 of file cycle_scalar.cpp.

Member Data Documentation

◆ _num_bits

template<typename Builder >

size_t bb::stdlib::cycle_scalar< Builder >::_num_bits = NUM_BITS

private

Definition at line 45 of file cycle_scalar.hpp.

◆ _skip_primality_test

template<typename Builder >

bool bb::stdlib::cycle_scalar< Builder >::_skip_primality_test = false

private

Definition at line 46 of file cycle_scalar.hpp.

◆ _use_bn254_scalar_field_for_primality_test

template<typename Builder >

bool bb::stdlib::cycle_scalar< Builder >::_use_bn254_scalar_field_for_primality_test = false

private

Definition at line 49 of file cycle_scalar.hpp.

◆ hi

template<typename Builder >

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

Definition at line 42 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 39 of file cycle_scalar.hpp.

◆ lo

template<typename Builder >

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

Definition at line 41 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 38 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 37 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

Public Attributes

Static Public Attributes

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ BigScalarField

◆ Curve

◆ field_t

◆ ScalarField

Constructor & Destructor Documentation

◆ cycle_scalar() [1/4]

◆ cycle_scalar() [2/4]

◆ cycle_scalar() [3/4]

◆ cycle_scalar() [4/4]

Member Function Documentation

◆ create_from_bn254_scalar()

◆ decompose_into_lo_hi_u256()

◆ from_u256_witness()

◆ from_witness()

◆ get_context()

◆ get_origin_tag()

◆ get_value()

◆ is_constant()

◆ num_bits()

◆ set_free_witness_tag()

◆ set_origin_tag()

◆ skip_primality_test()

◆ unset_free_witness_tag()

◆ use_bn254_scalar_field_for_primality_test()

◆ validate_scalar_is_in_field()

Member Data Documentation

◆ _num_bits

◆ _skip_primality_test

◆ _use_bn254_scalar_field_for_primality_test

◆ hi

◆ HI_BITS

◆ lo

◆ LO_BITS

◆ NUM_BITS