primitives.expression_bytecode.expressions_bin

Expression binary parser.

Faithful translation from: - pil2-stark/src/starkpil/expressions_bin.hpp - pil2-stark/src/starkpil/expressions_bin.cpp

Parses compiled expression bytecode from expressions.bin files. The binary file contains: 1. Expression bytecode (operations and arguments) 2. Constraint bytecode (for debugging/verification) 3. Hints (for witness generation)

Key types referenced by OpType:

Zi – inverse vanishing polynomial 1/Z_H(x) where Z_H(x) = x^N - 1 xDivXSubXi – x/(x - xi), precomputed quotient for FRI opening xi – challenge evaluation point (random point from Fiat-Shamir)

Attributes

EXPRESSIONS_SECTION
CONSTRAINTS_SECTION
HINTS_SECTION
N_SECTIONS
GLOBAL_CONSTRAINTS_SECTION
GLOBAL_HINTS_SECTION
N_GLOBAL_SECTIONS

Classes

OpType	Operation argument types.
ParserParams	Parameters for a single expression.
ParserArgs	Global bytecode and constants.
HintFieldValue	Hint field value.
HintField	Hint field.
Hint	Hint for witness generation.
BinFileReader	Binary file reader with little-endian decoding.
ExpressionsBin	Compiled expression database.

Functions

optype_from_string(→ OpType)

Convert string to OpType enum.

Module Contents

primitives.expression_bytecode.expressions_bin.EXPRESSIONS_SECTION = 1

primitives.expression_bytecode.expressions_bin.CONSTRAINTS_SECTION = 2

primitives.expression_bytecode.expressions_bin.HINTS_SECTION = 3

primitives.expression_bytecode.expressions_bin.N_SECTIONS = 3

primitives.expression_bytecode.expressions_bin.GLOBAL_CONSTRAINTS_SECTION = 1

primitives.expression_bytecode.expressions_bin.GLOBAL_HINTS_SECTION = 2

primitives.expression_bytecode.expressions_bin.N_GLOBAL_SECTIONS = 2

class primitives.expression_bytecode.expressions_bin.OpType(*args, **kwds)

Bases: enum.Enum

Operation argument types.

Corresponds to C++ enum opType in stark_info.hpp (lines 30-49). These define the source/destination types for expression operands.

const_ = 0

cm = 1

tmp = 2

public_ = 3

airgroupvalue = 4

challenge = 5

number = 6

string_ = 7

airvalue = 8

proofvalue = 9

custom = 10

x = 11

Zi = 12

eval = 13

xDivXSubXi = 14

q = 15

f = 16

primitives.expression_bytecode.expressions_bin.optype_from_string(s: str) → OpType

Convert string to OpType enum.

class primitives.expression_bytecode.expressions_bin.ParserParams

Parameters for a single expression.

Corresponds to C++ struct ParserParams in expressions_bin.hpp (lines 53-69).

Attributes:

stage: Proof stage (0=custom, 1=trace, 2+=intermediate) exp_id: Expression ID in the expression database n_temp1: Number of scalar temporaries needed n_temp3: Number of field extension (dim=3) temporaries needed n_ops: Number of operations in this expression ops_offset: Offset into global ops array n_args: Number of arguments (8 per operation) args_offset: Offset into global args array first_row: First valid row for cyclic constraints last_row: Last valid row for cyclic constraints dest_dim: Destination dimension (1 or 3) dest_id: Destination identifier im_pol: Is intermediate polynomial line: Source code line (for debugging)

stage: int = 0

exp_id: int = 0

n_temp1: int = 0

n_temp3: int = 0

n_ops: int = 0

ops_offset: int = 0

n_args: int = 0

args_offset: int = 0

first_row: int = 0

last_row: int = 0

dest_dim: int = 0

dest_id: int = 0

im_pol: bool = False

line: str = ''

class primitives.expression_bytecode.expressions_bin.ParserArgs

Global bytecode and constants.

Corresponds to C++ struct ParserArgs in expressions_bin.hpp (lines 71-77).

Attributes:

ops: Operation codes (uint8). Each value is 0-2:

0 = dim1 x dim1 -> dim1 (scalar operation) 1 = dim3 x dim1 -> dim3 (field extension x scalar) 2 = dim3 x dim3 -> dim3 (field extension x field extension)

args: Operation arguments (uint16). 8 values per operation:

[0] = operation type (0=add, 1=sub, 2=mul, 3=sub_swap) [1] = destination temp index [2] = source A type (OpType value or temp buffer index) [3] = source A column/index [4] = source A stride index (for opening points) [5] = source B type [6] = source B column/index [7] = source B stride index

numbers: Literal constants (Goldilocks field elements as uint64) n_numbers: Number of literal constants

ops: numpy.ndarray

args: numpy.ndarray

numbers: numpy.ndarray

n_numbers: int = 0

class primitives.expression_bytecode.expressions_bin.HintFieldValue

Hint field value.

Corresponds to C++ struct HintFieldValue in expressions_bin.hpp (lines 30-39).

operand: OpType

id: int = 0

commit_id: int = 0

row_offset_index: int = 0

dim: int = 0

value: int = 0

string_value: str = ''

pos: list[int] = []

class primitives.expression_bytecode.expressions_bin.HintField

Hint field.

Corresponds to C++ struct HintField in expressions_bin.hpp (lines 41-44).

name: str = ''

values: list[HintFieldValue] = []

class primitives.expression_bytecode.expressions_bin.Hint

Hint for witness generation.

Corresponds to C++ struct Hint in expressions_bin.hpp (lines 47-51).

name: str = ''

fields: list[HintField] = []

class primitives.expression_bytecode.expressions_bin.BinFileReader(file_path: str)

Binary file reader with little-endian decoding.

Mimics C++ BinFileUtils::BinFile interface for reading.

Corresponds to C++ BinFile constructor in binfile_utils.cpp (lines 63-131).

path

pos = 0

reading_section = None

sections

n_sections

read_bytes(n: int) → bytes

Read n raw bytes.

read_u8_le() → int

Read uint8 little-endian.

read_u16_le() → int

Read uint16 little-endian.

read_u32_le() → int

Read uint32 little-endian.

read_u64_le() → int

Read uint64 little-endian.

read_string() → str

Read null-terminated string.

Corresponds to C++ BinFile::readString() which reads until null byte.

start_read_section(section_id: int, section_pos: int = 0) → None

Start reading a section.

Corresponds to C++ BinFile::startReadSection() (lines 138-157).

Args:

section_id: Section identifier section_pos: Section instance index (default 0)

Raises:

ValueError: If section doesn’t exist

end_read_section(check: bool = True) → None

End reading a section.

Corresponds to C++ BinFile::endReadSection() (lines 159-166).

Args:

check: If True, verify we read exactly section_size bytes

class primitives.expression_bytecode.expressions_bin.ExpressionsBin

Compiled expression database.

Corresponds to C++ class ExpressionsBin in expressions_bin.hpp (lines 79-145).

This class loads and manages compiled expression bytecode from .bin files. The bytecode represents arithmetic constraint expressions compiled into a stack-based operation sequence.

n_ops_total: int = 0

n_args_total: int = 0

expressions_info: dict[int, ParserParams]

constraints_info_debug: list[ParserParams] = []

hints: list[Hint] = []

expressions_bin_args_expressions

expressions_bin_args_constraints

max_tmp1: int = 0

max_tmp3: int = 0

max_args: int = 0

max_ops: int = 0

classmethod from_file(file_path: str, global_bin: bool = False, verifier_bin: bool = False) → ExpressionsBin

Load ExpressionsBin from binary file.

Corresponds to C++ constructor (lines 3-13 of expressions_bin.cpp).

Args:

file_path: Path to .bin file global_bin: Load as global constraints binary verifier_bin: Load as verifier binary

Returns:

Loaded ExpressionsBin instance

get_expression(exp_id: int) → ParserParams

Get expression parameters by ID.

Args:

exp_id: Expression ID

Returns:

ParserParams for the expression

Raises:

KeyError: If expression ID not found

get_hint_ids_by_name(name: str) → list[int]

Get hint indices by name.

Corresponds to C++ ExpressionsBin::getHintIdsByName() (lines 684-691 of expressions_bin.cpp).

Args:

name: Hint name to search for

Returns:

List of hint indices with matching name

get_number_hint_ids_by_name(name: str) → int

Get count of hints by name.

Corresponds to C++ ExpressionsBin::getNumberHintIdsByName() (lines 694-704 of expressions_bin.cpp).

Args:

name: Hint name to search for

Returns:

Number of hints with matching name

get_hint_field(hint_id: int, field_name: str) → HintField

Get a specific field from a hint by name.

Args:

hint_id: Index into self.hints field_name: Name of field (e.g., “numerator”, “denominator”, “reference”)

Returns:

HintField containing the field values

Raises:

ValueError: If field not found in hint