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

#include <byte_array.hpp>

Public Member Functions
	byte_array (Builder *parent_context=nullptr)

	byte_array (Builder *parent_context, size_t const n)

	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 (Builder *parent_context, bytes_t const &input)

	byte_array (Builder *parent_context, bytes_t &&input)

	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)

byte_array &	operator= (const byte_array &other)

byte_array &	operator= (byte_array &&other)

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

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

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

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. Asserts that the write does not exceed the current size.

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.

std::string	get_string () const
	Given a `byte_array`, compute a vector containing the values of its entries and convert it to a string.

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.

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

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/9]

template<typename Builder >

bb::stdlib::byte_array< Builder >::byte_array ( Builder * parent_context = nullptr )

Definition at line 17 of file byte_array.cpp.

◆ byte_array() [2/9]

template<typename Builder >

bb::stdlib::byte_array< Builder >::byte_array	(	Builder *	parent_context,
		size_t const	n
	)

Definition at line 22 of file byte_array.cpp.

◆ byte_array() [3/9]

template<typename Builder >

bb::stdlib::byte_array< Builder >::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.

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 54 of file byte_array.cpp.

◆ byte_array() [4/9]

template<typename Builder >

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

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 34 of file byte_array.cpp.

◆ byte_array() [5/9]

template<typename Builder >

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

Definition at line 195 of file byte_array.cpp.

◆ byte_array() [6/9]

template<typename Builder >

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

Definition at line 201 of file byte_array.cpp.

◆ byte_array() [7/9]

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`
	)

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 104 of file byte_array.cpp.

◆ byte_array() [8/9]

template<typename Builder >

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

Definition at line 207 of file byte_array.cpp.

◆ byte_array() [9/9]

template<typename Builder >

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

Definition at line 214 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 76 of file byte_array.hpp.

◆ get_context()

template<typename Builder >

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

inline

Definition at line 78 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 92 of file byte_array.hpp.

◆ get_string()

template<typename Builder >

std::string bb::stdlib::byte_array< Builder >::get_string ( ) const

Given a byte_array, compute a vector containing the values of its entries and convert it to a string.

Note: Used only in tests.

Definition at line 329 of file byte_array.cpp.

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

The transformation is injective when the size of the byte array is < 32, which covers all the use cases.

Definition at line 239 of file byte_array.cpp.

◆ operator=() [1/2]

template<typename Builder >

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

Definition at line 227 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 219 of file byte_array.cpp.

◆ operator[]() [1/2]

template<typename Builder >

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

inline

Definition at line 60 of file byte_array.hpp.

◆ operator[]() [2/2]

template<typename Builder >

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

inline

Definition at line 54 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 301 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 104 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 85 of file byte_array.hpp.

◆ size()

template<typename Builder >

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

inline

Definition at line 74 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 278 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 288 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 114 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 256 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. Asserts that the write does not exceed the current size.

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

Private Types

Private Attributes

Detailed Description

Member Typedef Documentation

◆ bytes_t

Constructor & Destructor Documentation

◆ byte_array() [1/9]

◆ byte_array() [2/9]

◆ byte_array() [3/9]

◆ byte_array() [4/9]

◆ byte_array() [5/9]

◆ byte_array() [6/9]

◆ byte_array() [7/9]

Description of circuit

◆ byte_array() [8/9]

◆ byte_array() [9/9]

Member Function Documentation

◆ bytes()

◆ get_context()

◆ get_origin_tag()

◆ get_string()

◆ get_value()

◆ operator field_t< Builder >()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ 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