Represents a dynamic array of bytes in-circuit. More...

#include <byte_array.hpp>

Public Member Functions
	byte_array (Builder *parent_context, std::string const &input)
	Create a byte array out of a std::string object by decomposing the latter into a vector of bytes and feeding it into the constructor above.

	byte_array (Builder *parent_context, std::vector< uint8_t > const &input)
	Create a byte array out of a vector of uint8_t bytes.

	byte_array (const field_t< Builder > &input, const size_t num_bytes=32, std::optional< uint256_t > test_val=std::nullopt)
	Create a byte_array of length `num_bytes` out of a field element.

	byte_array (const byte_array &other)

	byte_array (byte_array &&other) noexcept

byte_array &	operator= (const byte_array &other)

byte_array &	operator= (byte_array &&other) noexcept

	operator field_t< Builder > () const
	Convert a byte array into a field element.

field_t< Builder >	operator[] (const size_t index) const

byte_array &	write (byte_array const &other)
	Appends the contents of another `byte_array` (`other`) to the end of this one.

byte_array &	write_at (byte_array const &other, size_t index)
	Overwrites this byte_array starting at index with the contents of other.

byte_array	slice (size_t offset) const
	Slice bytes from the byte array starting at `offset`. Does not add any constraints.

byte_array	slice (size_t offset, size_t length) const
	Slice `length` bytes from the byte array, starting at `offset`. Does not add any constraints.

byte_array	reverse () const
	Reverse the bytes in the byte array.

size_t	size () const

bytes_t const &	bytes () const

Builder *	get_context () const

std::vector< uint8_t >	get_value () const
	A helper converting a `byte_array` into the vector of its uint8_t values.

void	set_origin_tag (bb::OriginTag tag)

bb::OriginTag	get_origin_tag () const

void	set_free_witness_tag ()
	Set the free witness flag for the byte array.

void	unset_free_witness_tag ()
	Unset the free witness flag for the byte array.

Static Public Member Functions
static byte_array	constant_padding (Builder *parent_context, size_t num_bytes, uint8_t value=0)

Private Types
using	bytes_t = typename std::vector< field_t< Builder > >

Private Member Functions
	byte_array (Builder *parent_context, bytes_t const &input)

	byte_array (Builder *parent_context, bytes_t &&input)

Static Private Member Functions
static byte_array	from_constants (Builder *parent_context, std::vector< uint8_t > const &input)
	Create a byte_array from constant values without adding range constraints.

Private Attributes
Builder *	context

bytes_t	values

Detailed Description

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

Represents a dynamic array of bytes in-circuit.

The byte_array class provides a high-level abstraction over a sequence of field elements constrained to be bytes.

It supports construction from native values (std::string, std::vector<uint8_t>, or field_t) and conversion to a field_t elements, as well as various classical vector operations like slicing and reversing.

Used in hashing primitives.

Template Parameters

Builder The circuit builder type (e.g., UltraCircuitBuilder).

Definition at line 28 of file byte_array.hpp.

Member Typedef Documentation

◆ bytes_t

template<typename Builder >

using bb::stdlib::byte_array< Builder >::bytes_t = typename std::vector<field_t<Builder> >

private

Definition at line 29 of file byte_array.hpp.

Constructor & Destructor Documentation

◆ byte_array() [1/7]

template<typename Builder >

bb::stdlib::byte_array< Builder >::byte_array	(	Builder *	parent_context,
		bytes_t const &	input
	)

private

Definition at line 203 of file byte_array.cpp.

◆ byte_array() [2/7]

template<typename Builder >

bb::stdlib::byte_array< Builder >::byte_array	(	Builder *	parent_context,
		bytes_t &&	input
	)

private

Definition at line 209 of file byte_array.cpp.

◆ byte_array() [3/7]

template<typename Builder >

bb::stdlib::byte_array< Builder >::byte_array	(	Builder *	parent_context,
		std::string const &	input
	)

explicit

Create a byte array out of a std::string object by decomposing the latter into a vector of bytes and feeding it into the constructor above.

Warning: This constructor will instantiate each byte as a circuit witness, NOT a circuit constant. Do not use this method if the input needs to be hardcoded for a specific circuit

Definition at line 43 of file byte_array.cpp.

◆ byte_array() [4/7]

template<typename Builder >

bb::stdlib::byte_array< Builder >::byte_array	(	Builder *	parent_context,
		std::vector< uint8_t > const &	input
	)

explicit

Create a byte array out of a vector of uint8_t bytes.

Warning: This constructor will instantiate each byte as a circuit witness, NOT a circuit constant. Do not use this method if the input needs to be hardcoded for a specific circuit

Definition at line 23 of file byte_array.cpp.

◆ byte_array() [5/7]

template<typename Builder >

bb::stdlib::byte_array< Builder >::byte_array	(	const field_t< Builder > &	input,
		const size_t	num_bytes = `32`,
		std::optional< uint256_t >	test_val = `std::nullopt`
	)

explicit

Create a byte_array of length num_bytes out of a field element.

The length of the byte array will default to 32 bytes, but shorter lengths can be specified. If a shorter length is used, the circuit will NOT truncate the input to fit the reduced length. Instead, the circuit adds constraints that VALIDATE the input is smaller than the specified length e.g. if this constructor is used on a 16-bit input witness, where num_bytes is 1, the resulting proof will fail.

Description of circuit

Our field element is input. Say the byte vector provided by the prover consists of bits b0,...,b255. These bits are used to construct the corresponding reconstructedvalue reconstructed = reconstructed_lo + reconstructed_hi:= \sum_{i=0}^{8num_bytes-1} 2^{i}b_{i}, where reconstructed_lo is a field element representing the low 16 bytes of input, and reconstructed_hi is the high 16-bit limb shifted by 2^128. reconstructed is copy constrained to be equal to input. However, more constraints are needed in general.

Let r = bb::fr::modulus. For later applications, we want to ensure that the prover must pass the bit decomposition of the standard representative of the mod r residue class containing input, which is to say that we want to show that the actual integer value of reconstructed lies in [0, ..., r-1]. By the formula for reconstructed, we do not have to worry about wrapping the modulus if num_bytes < 32 or, in the default case, if the input fits into 31 bytes.

Suppose now that num_bytes is 32. We would like to show that r - 1 - reconstructed >= 0 as integers, but this cannot be done inside of uint256_t since reconstructed value can be any uint256_t, hence its negative is not constrained to lie in any proper subset. We therefore split it and r-1 into two smaller limbs and make comparisons using range constraints in uint256_t.

We separate the problem of imposing that reconstructed <= r - 1 into two cases.

Case 0: When s_lo <  reconstructed_lo, we must impose that reconstructed_hi <  s_hi, i.e., s_hi -

reconstructed_hi - 2 > 0. Case 1: s_lo >= reconstructed_lo, we must impose that reconstructed_hi =< s_hi, i.e. s_hi - reconstructed_hi - 1 > 0.

To unify these cases, we introduce a predicate that distinguishes them. Consider the expression s_lo - reconstructed_lo As an integer, it lies in [-2^128+1, 2^128-1], with Case 0 corresponding to the numbers < 0. Shifting to diff_lo := s_lo - reconstructed_lo + 2^128, Case 0 corresponds to the range [1, 2^128-1]. We see that the 129th bit of diff_lo exactly indicates Case 1. Extracting the 129th bit denoted diff_lo_hi and adding it to reconstructed_hi, we have a uniform constraint to apply. Namely, setting overlap := 1 - diff_overlap_lo_hi and diff_hi := s_hi - reconstructed_hi - overlap, range constraining y_hi to 128 bits imposes validator < r.

Definition at line 110 of file byte_array.cpp.

◆ byte_array() [6/7]

template<typename Builder >

bb::stdlib::byte_array< Builder >::byte_array ( const byte_array< Builder > & other )

Definition at line 215 of file byte_array.cpp.

◆ byte_array() [7/7]

template<typename Builder >

bb::stdlib::byte_array< Builder >::byte_array ( byte_array< Builder > && other )

noexcept

Definition at line 222 of file byte_array.cpp.

Member Function Documentation

◆ bytes()

template<typename Builder >

bytes_t const & bb::stdlib::byte_array< Builder >::bytes ( ) const

inline

Definition at line 84 of file byte_array.hpp.

◆ constant_padding()

template<typename Builder >

static byte_array bb::stdlib::byte_array< Builder >::constant_padding	(	Builder *	parent_context,
		size_t	num_bytes,
		uint8_t	value = `0`
	)

inlinestatic

Definition at line 54 of file byte_array.hpp.

◆ from_constants()

template<typename Builder >

byte_array< Builder > bb::stdlib::byte_array< Builder >::from_constants	(	Builder *	parent_context,
		std::vector< uint8_t > const &	input
	)

staticprivate

Create a byte_array from constant values without adding range constraints.

This is safe for constant data (like padding) because constants cannot be manipulated by the prover. Use this for padding, initialization, or other constant data to avoid unnecessary constraints.

Definition at line 53 of file byte_array.cpp.

◆ get_context()

template<typename Builder >

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

inline

Definition at line 86 of file byte_array.hpp.

◆ get_origin_tag()

template<typename Builder >

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

inline

Definition at line 99 of file byte_array.hpp.

◆ get_value()

template<typename Builder >

std::vector< uint8_t > bb::stdlib::byte_array< Builder >::get_value ( ) const

A helper converting a byte_array into the vector of its uint8_t values.

Note: Used only in tests.

Definition at line 324 of file byte_array.cpp.

◆ operator field_t< Builder >()

template<typename Builder >

bb::stdlib::byte_array< Builder >::operator field_t< Builder > ( ) const

explicit

Convert a byte array into a field element.

Definition at line 246 of file byte_array.cpp.

◆ operator=() [1/2]

template<typename Builder >

byte_array< Builder > & bb::stdlib::byte_array< Builder >::operator= ( byte_array< Builder > && other )

noexcept

Definition at line 235 of file byte_array.cpp.

◆ operator=() [2/2]

template<typename Builder >

byte_array< Builder > & bb::stdlib::byte_array< Builder >::operator= ( const byte_array< Builder > & other )

Definition at line 227 of file byte_array.cpp.

◆ operator[]()

template<typename Builder >

field_t< Builder > bb::stdlib::byte_array< Builder >::operator[] ( const size_t index ) const

inline

Definition at line 66 of file byte_array.hpp.

◆ reverse()

template<typename Builder >

byte_array< Builder > bb::stdlib::byte_array< Builder >::reverse ( ) const

Reverse the bytes in the byte array.

Definition at line 307 of file byte_array.cpp.

◆ set_free_witness_tag()

template<typename Builder >

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

inline

Set the free witness flag for the byte array.

Definition at line 111 of file byte_array.hpp.

◆ set_origin_tag()

template<typename Builder >

void bb::stdlib::byte_array< Builder >::set_origin_tag ( bb::OriginTag tag )

inline

Definition at line 92 of file byte_array.hpp.

◆ size()

template<typename Builder >

size_t bb::stdlib::byte_array< Builder >::size ( ) const

inline

Definition at line 82 of file byte_array.hpp.

◆ slice() [1/2]

template<typename Builder >

byte_array< Builder > bb::stdlib::byte_array< Builder >::slice ( size_t offset ) const

Slice bytes from the byte array starting at offset. Does not add any constraints.

Definition at line 284 of file byte_array.cpp.

◆ slice() [2/2]

template<typename Builder >

byte_array< Builder > bb::stdlib::byte_array< Builder >::slice	(	size_t	offset,
		size_t	length
	)		const

Slice length bytes from the byte array, starting at offset. Does not add any constraints.

Note that the syntax here differs for the syntax used for slicing uint256_t's.

Definition at line 294 of file byte_array.cpp.

◆ unset_free_witness_tag()

template<typename Builder >

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

inline

Unset the free witness flag for the byte array.

Definition at line 121 of file byte_array.hpp.

◆ write()

template<typename Builder >

byte_array< Builder > & bb::stdlib::byte_array< Builder >::write ( byte_array< Builder > const & other )

Appends the contents of another byte_array (other) to the end of this one.

Definition at line 263 of file byte_array.cpp.

◆ write_at()

template<typename Builder >

byte_array< Builder > & bb::stdlib::byte_array< Builder >::write_at	(	byte_array< Builder > const &	other,
		size_t	index
	)

Overwrites this byte_array starting at index with the contents of other.

Definition at line 272 of file byte_array.cpp.

Member Data Documentation

◆ context

template<typename Builder >

Builder* bb::stdlib::byte_array< Builder >::context

private

Definition at line 32 of file byte_array.hpp.

◆ values

template<typename Builder >

bytes_t bb::stdlib::byte_array< Builder >::values

private

Definition at line 33 of file byte_array.hpp.

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

src/barretenberg/stdlib/primitives/byte_array/byte_array.hpp
src/barretenberg/stdlib/primitives/byte_array/byte_array.cpp

Public Member Functions

Static Public Member Functions

Private Types

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ bytes_t

Constructor & Destructor Documentation

◆ byte_array() [1/7]

◆ byte_array() [2/7]

◆ byte_array() [3/7]

◆ byte_array() [4/7]

◆ byte_array() [5/7]

Description of circuit

◆ byte_array() [6/7]

◆ byte_array() [7/7]

Member Function Documentation

◆ bytes()

◆ constant_padding()

◆ from_constants()

◆ get_context()

◆ get_origin_tag()

◆ get_value()

◆ operator field_t< Builder >()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator[]()

◆ reverse()

◆ set_free_witness_tag()

◆ set_origin_tag()

◆ size()

◆ slice() [1/2]

◆ slice() [2/2]

◆ unset_free_witness_tag()

◆ write()

◆ write_at()

Member Data Documentation

◆ context

◆ values