ROM/RAM logic handler for UltraCircuitBuilder. More...

#include <rom_ram_logic.hpp>

Public Types
using	FF = typename ExecutionTrace::FF

using	CircuitBuilder = UltraCircuitBuilder_< ExecutionTrace >

Public Member Functions
	RomRamLogic_ ()=default

size_t	create_ROM_array (const size_t array_size)
	Create a new read-only memory region.

void	set_ROM_element (CircuitBuilder *builder, const size_t rom_id, const size_t index_value, const uint32_t value_witness)
	Initialize a rom cell to equal `value_witness`

void	set_ROM_element_pair (CircuitBuilder *builder, const size_t rom_id, const size_t index_value, const std::array< uint32_t, 2 > &value_witnesses)
	Initialize a ROM array element with a pair of witness values.

uint32_t	read_ROM_array (CircuitBuilder *builder, const size_t rom_id, const uint32_t index_witness)
	Read a single element from ROM.

std::array< uint32_t, 2 >	read_ROM_array_pair (CircuitBuilder *builder, const size_t rom_id, const uint32_t index_witness)
	Read a pair of elements from ROM.

void	create_ROM_gate (CircuitBuilder *builder, RomRecord &record)
	Gate that'reads' from a ROM table, i.e., the table index is a witness not precomputed.

void	create_sorted_ROM_gate (CircuitBuilder *builder, RomRecord &record)
	Gate that performs consistency checks to validate that a claimed ROM read value is correct.

void	process_ROM_array (CircuitBuilder *builder, const size_t rom_id)
	Compute additional gates required to validate ROM reads. Called when generating the proving key.

void	process_ROM_arrays (CircuitBuilder *builder)
	Process all of the ROM arrays.

size_t	create_RAM_array (const size_t array_size)
	Create a new updatable memory region.

void	init_RAM_element (CircuitBuilder *builder, const size_t ram_id, const size_t index_value, const uint32_t value_witness)
	Initialize a RAM cell to equal `value_witness`

uint32_t	read_RAM_array (CircuitBuilder *builder, const size_t ram_id, const uint32_t index_witness)

void	write_RAM_array (CircuitBuilder *builder, const size_t ram_id, const uint32_t index_witness, const uint32_t value_witness)
	Write a cell in a RAM array.

void	create_RAM_gate (CircuitBuilder *builder, RamRecord &record)
	Gate that performs a read/write operation into a RAM table, i.e. table index is a witness not precomputed.

void	create_sorted_RAM_gate (CircuitBuilder *builder, RamRecord &record)
	Gate that performs consistency checks to validate that a claimed RAM read/write value is correct.

void	create_final_sorted_RAM_gate (CircuitBuilder *builder, RamRecord &record, const size_t ram_array_size)
	Performs consistency checks to validate that a claimed RAM read/write value is correct. Used for the final gate in a list of sorted RAM records.

void	process_RAM_array (CircuitBuilder *builder, const size_t ram_id)
	Compute additional gates required to validate RAM read/writes. Called when generating the proving key.

void	process_RAM_arrays (CircuitBuilder *builder)

bool	operator== (const RomRamLogic_ &other) const noexcept

Public Attributes
std::vector< RamTranscript >	ram_arrays
	Each entry in ram_arrays represents an independent RAM table. RamTranscript tracks the current table state, as well as the 'records' produced by each read and write operation. Used in `compute_prover_instance` to generate consistency check gates required to validate the RAM read/write history.

std::vector< RomTranscript >	rom_arrays
	Each entry in rom_arrays represents an independent ROM table. RomTranscript tracks the current table state, as well as the 'records' produced by each read operation. Used in `compute_prover_instance` to generate consistency check gates required to validate the ROM read history.

Detailed Description

template<typename ExecutionTrace>
class bb::RomRamLogic_< ExecutionTrace >

ROM/RAM logic handler for UltraCircuitBuilder.

Definition at line 122 of file rom_ram_logic.hpp.

Member Typedef Documentation

◆ CircuitBuilder

template<typename ExecutionTrace >

using bb::RomRamLogic_< ExecutionTrace >::CircuitBuilder = UltraCircuitBuilder_<ExecutionTrace>

Definition at line 125 of file rom_ram_logic.hpp.

◆ FF

template<typename ExecutionTrace >

using bb::RomRamLogic_< ExecutionTrace >::FF = typename ExecutionTrace::FF

Definition at line 124 of file rom_ram_logic.hpp.

Constructor & Destructor Documentation

◆ RomRamLogic_()

template<typename ExecutionTrace >

bb::RomRamLogic_< ExecutionTrace >::RomRamLogic_ ( )

default

Member Function Documentation

◆ create_final_sorted_RAM_gate()

template<typename ExecutionTrace >

void bb::RomRamLogic_< ExecutionTrace >::create_final_sorted_RAM_gate	(	CircuitBuilder *	builder,
		RamRecord &	record,
		const size_t	ram_array_size
	)

Performs consistency checks to validate that a claimed RAM read/write value is correct. Used for the final gate in a list of sorted RAM records.

Parameters

builder
record	Stores details of this read operation. Mutated by this fn!

Definition at line 430 of file rom_ram_logic.cpp.

◆ create_RAM_array()

template<typename ExecutionTrace >

size_t bb::RomRamLogic_< ExecutionTrace >::create_RAM_array ( const size_t array_size )

Create a new updatable memory region.

Creates a transcript object, where the inside memory state array is filled with "uninitialized memory" and empty memory record array. Puts this object into the vector of ROM arrays.

Parameters

array_size The size of region in elements

Returns: size_t The index of the element

Definition at line 271 of file rom_ram_logic.cpp.

◆ create_RAM_gate()

template<typename ExecutionTrace >

void bb::RomRamLogic_< ExecutionTrace >::create_RAM_gate	(	CircuitBuilder *	builder,
		RamRecord &	record
	)

Gate that performs a read/write operation into a RAM table, i.e. table index is a witness not precomputed.

Parameters

builder
record	Stores details of this read operation. Mutated by this fn!

Definition at line 398 of file rom_ram_logic.cpp.

◆ create_ROM_array()

template<typename ExecutionTrace >

size_t bb::RomRamLogic_< ExecutionTrace >::create_ROM_array ( const size_t array_size )

Create a new read-only memory region.

Creates a transcript object, where the inside memory state array is filled with "uninitialized memory" and empty memory record array. Puts this object into the vector of ROM arrays.

Parameters

array_size The size of region in elements

Returns: size_t The index of the element

Definition at line 8 of file rom_ram_logic.cpp.

◆ create_ROM_gate()

template<typename ExecutionTrace >

void bb::RomRamLogic_< ExecutionTrace >::create_ROM_gate	(	CircuitBuilder *	builder,
		RomRecord &	record
	)

Gate that'reads' from a ROM table, i.e., the table index is a witness not precomputed.

Parameters

builder
record	Stores details of this read operation. Mutated by this fn!

Definition at line 147 of file rom_ram_logic.cpp.

◆ create_sorted_RAM_gate()

template<typename ExecutionTrace >

void bb::RomRamLogic_< ExecutionTrace >::create_sorted_RAM_gate	(	CircuitBuilder *	builder,
		RamRecord &	record
	)

Gate that performs consistency checks to validate that a claimed RAM read/write value is correct.

sorted RAM gates are generated sequentially, each RAM record is sorted first by index then by timestamp

Parameters

builder
record	Stores details of this read operation. Mutated by this fn!

Definition at line 417 of file rom_ram_logic.cpp.

◆ create_sorted_ROM_gate()

template<typename ExecutionTrace >

void bb::RomRamLogic_< ExecutionTrace >::create_sorted_ROM_gate	(	CircuitBuilder *	builder,
		RomRecord &	record
	)

Gate that performs consistency checks to validate that a claimed ROM read value is correct.

sorted ROM gates are generated sequentially, each ROM record is sorted by index

Parameters

builder
record	Stores details of this read operation. Mutated by this fn!

Definition at line 161 of file rom_ram_logic.cpp.

◆ init_RAM_element()

template<typename ExecutionTrace >

void bb::RomRamLogic_< ExecutionTrace >::init_RAM_element	(	CircuitBuilder *	builder,
		const size_t	ram_id,
		const size_t	index_value,
		const uint32_t	value_witness
	)

Initialize a RAM cell to equal value_witness

Initialize an element of the RAM array.

Parameters

builder
ram_id	The index of the RAM array, which cell we are initializing
index_value	The index of the cell within the array (an actual index, not a witness index)
value_witness	The index of the witness with the value that should be in the

Template Parameters

ExecutionTrace

Parameters

builder
ram_id
index_value	raw index in the array specified by `ram_id`. NOT a witness index.
value_witness

Note: If not for the line BB_ASSERT_EQ(ram_array.state[index_value], UNINITIALIZED_MEMORY_RECORD);, we could reinitialize an entry multiple times; there are no circuit constraints that prevent this. In particular, the functionality is nearly identical to that of write_RAM_array. (The only difference is that the current method takes a raw index_value while the latter takes a witness index.) Correspondingly, the access_type is RamRecord::AccessType::WRITE.

Definition at line 296 of file rom_ram_logic.cpp.

◆ operator==()

template<typename ExecutionTrace >

bool bb::RomRamLogic_< ExecutionTrace >::operator== ( const RomRamLogic_< ExecutionTrace > & other ) const

inlinenoexcept

Definition at line 304 of file rom_ram_logic.hpp.

◆ process_RAM_array()

template<typename ExecutionTrace >

void bb::RomRamLogic_< ExecutionTrace >::process_RAM_array	(	CircuitBuilder *	builder,
		const size_t	ram_id
	)

Compute additional gates required to validate RAM read/writes. Called when generating the proving key.

Parameters

ram_id	The id of the RAM table
gate_offset_from_public_inputs	Required to track the gate position of where we're adding extra gates

Definition at line 461 of file rom_ram_logic.cpp.

◆ process_RAM_arrays()

template<typename ExecutionTrace >

void bb::RomRamLogic_< ExecutionTrace >::process_RAM_arrays ( CircuitBuilder * builder )

Definition at line 602 of file rom_ram_logic.cpp.

◆ process_ROM_array()

template<typename ExecutionTrace >

void bb::RomRamLogic_< ExecutionTrace >::process_ROM_array	(	CircuitBuilder *	builder,
		const size_t	rom_id
	)

Compute additional gates required to validate ROM reads. Called when generating the proving key.

Parameters

builder
rom_id	The id of the ROM table
gate_offset_from_public_inputs	Required to track the gate position of where we're adding extra gates

Definition at line 176 of file rom_ram_logic.cpp.

◆ process_ROM_arrays()

template<typename ExecutionTrace >

void bb::RomRamLogic_< ExecutionTrace >::process_ROM_arrays ( CircuitBuilder * builder )

Process all of the ROM arrays.

Definition at line 264 of file rom_ram_logic.cpp.

◆ read_RAM_array()

template<typename ExecutionTrace >

uint32_t bb::RomRamLogic_< ExecutionTrace >::read_RAM_array	(	CircuitBuilder *	builder,
		const size_t	ram_id,
		const uint32_t	index_witness
	)

Definition at line 323 of file rom_ram_logic.cpp.

◆ read_ROM_array()

template<typename ExecutionTrace >

uint32_t bb::RomRamLogic_< ExecutionTrace >::read_ROM_array	(	CircuitBuilder *	builder,
		const size_t	rom_id,
		const uint32_t	index_witness
	)

Read a single element from ROM.

Parameters

builder
rom_id	ROM array id
index_witness	The witness with the index inside the array

Returns: uint32_t Cell value witness index

Note: If the entry in the index had two entries (i.e., was initialized with set_ROM_element_pair), then calling this method will cause a non-satisfying witness (unless we happened to have set the second entry to FF:zero()).

Definition at line 86 of file rom_ram_logic.cpp.

◆ read_ROM_array_pair()

template<typename ExecutionTrace >

std::array< uint32_t, 2 > bb::RomRamLogic_< ExecutionTrace >::read_ROM_array_pair	(	CircuitBuilder *	builder,
		const size_t	rom_id,
		const uint32_t	index_witness
	)

Read a pair of elements from ROM.

Parameters

rom_id	The id of the ROM array
index_witness	The witness containing the index in the array

Returns: std::array<uint32_t, 2> A pair of indexes of witness variables of cell values

Definition at line 112 of file rom_ram_logic.cpp.

◆ set_ROM_element()

template<typename ExecutionTrace >

void bb::RomRamLogic_< ExecutionTrace >::set_ROM_element	(	CircuitBuilder *	builder,
		const size_t	rom_id,
		const size_t	index_value,
		const uint32_t	value_witness
	)

Initialize a rom cell to equal value_witness

Initialize a ROM cell to equal value_witness (or, more precisely, (value_witness, 0).

Parameters

builder
rom_id	The index of the ROM array, which cell we are initializing
index_value	The index of the cell within the array (an actual index, not a witness index)
value_witness	The index of the witness with the value that should be in the

Note: index_value is a RAW VALUE that describes the cell index inside of the specified ROM table (which we treat as an array). It is NOT a witness. When intializing ROM arrays, it is important that the index of the cell is known when compiling the circuit. This ensures that, for a given circuit, we know with 100% certainty that EVERY ROM cell is initialized; This method does not know what the value of record_witness will be.; There is nothing stopping us from running set_ROM_element on the same rom_id and index_value twice, as long as the value_witness is the same both times.

Definition at line 31 of file rom_ram_logic.cpp.

◆ set_ROM_element_pair()

template<typename ExecutionTrace >

void bb::RomRamLogic_< ExecutionTrace >::set_ROM_element_pair	(	CircuitBuilder *	builder,
		const size_t	rom_id,
		const size_t	index_value,
		const std::array< uint32_t, 2 > &	value_witnesses
	)

Initialize a ROM array element with a pair of witness values.

Initialize a ROM cell to (value_witness[0], value_witness[1]).

Parameters

builder
rom_id	ROM array id
index_value	Index in the array
value_witnesses	The witnesses to put in the slot

Definition at line 60 of file rom_ram_logic.cpp.

◆ write_RAM_array()

template<typename ExecutionTrace >

void bb::RomRamLogic_< ExecutionTrace >::write_RAM_array	(	CircuitBuilder *	builder,
		const size_t	ram_id,
		const uint32_t	index_witness,
		const uint32_t	value_witness
	)

Write a cell in a RAM array.

write an value (given by its witness index) to a RAM array

Parameters

builder
ram_id	The index of the RAM array, whose cell we are (re)writing
index_witness	The witness of the index cell in the RAM array. This is as a safeguard to make sure we have already initialized the RAM cell, so that we in particular have access to the index witness.
value_witness

Template Parameters

ExecutionTrace

Parameters

builder
ram_id
index_witness
value_witness

Note: Other than taking in an index_witness rather than a raw index, this is identical to init_RAM_element.. In particular, both use the RamRecord::AccessType::WRITE.

Definition at line 367 of file rom_ram_logic.cpp.

Member Data Documentation

◆ ram_arrays

template<typename ExecutionTrace >

std::vector<RamTranscript> bb::RomRamLogic_< ExecutionTrace >::ram_arrays

Each entry in ram_arrays represents an independent RAM table. RamTranscript tracks the current table state, as well as the 'records' produced by each read and write operation. Used in compute_prover_instance to generate consistency check gates required to validate the RAM read/write history.

Definition at line 134 of file rom_ram_logic.hpp.

◆ rom_arrays

template<typename ExecutionTrace >

std::vector<RomTranscript> bb::RomRamLogic_< ExecutionTrace >::rom_arrays

Each entry in rom_arrays represents an independent ROM table. RomTranscript tracks the current table state, as well as the 'records' produced by each read operation. Used in compute_prover_instance to generate consistency check gates required to validate the ROM read history.

Definition at line 141 of file rom_ram_logic.hpp.

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

src/barretenberg/stdlib_circuit_builders/rom_ram_logic.hpp
src/barretenberg/stdlib_circuit_builders/rom_ram_logic.cpp

Public Types

Public Member Functions

Public Attributes

Detailed Description

Member Typedef Documentation

◆ CircuitBuilder

◆ FF

Constructor & Destructor Documentation

◆ RomRamLogic_()

Member Function Documentation

◆ create_final_sorted_RAM_gate()

◆ create_RAM_array()

◆ create_RAM_gate()

◆ create_ROM_array()

◆ create_ROM_gate()

◆ create_sorted_RAM_gate()

◆ create_sorted_ROM_gate()

◆ init_RAM_element()

◆ operator==()

◆ process_RAM_array()

◆ process_RAM_arrays()

◆ process_ROM_array()

◆ process_ROM_arrays()

◆ read_RAM_array()

◆ read_ROM_array()

◆ read_ROM_array_pair()

◆ set_ROM_element()

◆ set_ROM_element_pair()

◆ write_RAM_array()

Member Data Documentation

◆ ram_arrays

◆ rom_arrays