protocol.proof

STARK proof and verifying key data structures.

Faithful Python translation of the Rust proof types from the stark-backend and Plonky3 FRI libraries, plus JSON parsing functions for deserialization from serde_json output.

Proof types reference:

stark-backend/src/proof.rs — Proof, Commitments, OpeningProof, OpenedValues,

AdjacentOpenedValues, AirProofData

p3-fri/src/proof.rs — FriProof, QueryProof, CommitPhaseProofStep p3-fri/src/two_adic_pcs.rs — BatchOpening

VK types reference:

stark-backend/src/keygen/types.rs — MultiStarkVerifyingKey, StarkVerifyingKey,

StarkVerifyingParams, TraceWidth

stark-backend/src/air_builders/symbolic/dag.rs — SymbolicExpressionDag,

SymbolicExpressionNode

stark-backend/src/air_builders/symbolic/symbolic_variable.rs — SymbolicVariable, Entry stark-backend/src/interaction/mod.rs — Interaction

Classes

Commitments	All commitments to a multi-matrix STARK (not preprocessed).
AdjacentOpenedValues	Opened values at zeta and zeta * g for one trace matrix.
OpenedValues	All opened values across preprocessed, main, after-challenge, and quotient.
CommitPhaseProofStep	One round of a FRI query: sibling value + Merkle proof.
BatchOpening	Opened values from a single MMCS batch at a query index.
QueryProof	FRI query proof for a single query index.
FriProof	Complete FRI proof.
OpeningProof	PCS opening proof with opened values.
AirProofData	Proof data for a single AIR.
FriLogUpPartialProof	Partial proof for the FRI LogUp challenge phase.
Proof	Full multi-AIR STARK proof.
EntryType	Kind of symbolic variable entry.
Entry	Symbolic variable entry with kind and offset/part_index.
SymbolicVariable	A variable within the evaluation window (column reference).
SymbolicNodeKind	Kind of symbolic expression node.
SymbolicExpressionNode	A node in the symbolic expression DAG.
SymbolicExpressionDag	DAG of symbolic expressions in topological order.
Interaction	A bus interaction.
SymbolicConstraintsDag	Complete symbolic constraints for a single AIR.
TraceWidth	Widths of different parts of a trace matrix.
StarkVerifyingParams	Verification parameters for a single STARK.
RapPhaseSeqKind	Supported challenge phase protocols.
VerifierSinglePreprocessedData	Verifier data for preprocessed trace for a single AIR.
StarkVerifyingKey	Verifying key for a single STARK (single AIR).
LinearConstraint	Linear constraint on trace heights.
MultiStarkVerifyingKey0	Inner verifying key data (without pre_hash).
MultiStarkVerifyingKey	Complete multi-AIR verifying key.
FriParameters	FRI protocol parameters.
AirInputData	Raw input trace matrices for one AIR, used by the prover.
ProverInputs	All input trace data needed by the prover.

Functions

parse_proof_json(→ Proof)	Parse a Proof from a JSON dict (serde_json format).
parse_vk_json(→ MultiStarkVerifyingKey)	Parse a MultiStarkVerifyingKey from a JSON dict (serde_json format).
parse_fri_params(→ FriParameters)	Parse FRI parameters from a test vector JSON dict.
parse_prover_inputs(→ ProverInputs)	Parse prover input vectors from JSON.
parse_e2e_vectors(→ tuple[Proof, FriParameters, dict])	Parse complete E2E test vectors.
serialize_proof_json(→ dict)	Serialize a Proof to serde-compatible JSON dict.

Module Contents

class protocol.proof.Commitments

All commitments to a multi-matrix STARK (not preprocessed).

Reference:

stark-backend/src/proof.rs (struct Commitments<Com>)

main_trace: list[primitives.field.Digest]

after_challenge: list[primitives.field.Digest]

quotient: primitives.field.Digest

class protocol.proof.AdjacentOpenedValues

Opened values at zeta and zeta * g for one trace matrix.

Reference:

stark-backend/src/proof.rs (struct AdjacentOpenedValues<Challenge>)

local: list[primitives.field.FF4Coeffs]

next: list[primitives.field.FF4Coeffs]

class protocol.proof.OpenedValues

All opened values across preprocessed, main, after-challenge, and quotient.

Reference:

stark-backend/src/proof.rs (struct OpenedValues<Challenge>)

preprocessed: list[AdjacentOpenedValues]

main: list[list[AdjacentOpenedValues]]

after_challenge: list[list[AdjacentOpenedValues]]

quotient: list[list[list[primitives.field.FF4Coeffs]]]

class protocol.proof.CommitPhaseProofStep

One round of a FRI query: sibling value + Merkle proof.

Reference:

p3-fri/src/proof.rs (struct CommitPhaseProofStep<F, M>)

sibling_value: primitives.field.FF4Coeffs

opening_proof: primitives.field.MerklePath

class protocol.proof.BatchOpening

Opened values from a single MMCS batch at a query index.

Reference:

p3-fri/src/two_adic_pcs.rs (struct BatchOpening<Val, InputMmcs>)

opened_values: list[list[primitives.field.Fe]]

opening_proof: primitives.field.MerklePath

class protocol.proof.QueryProof

FRI query proof for a single query index.

Reference:

p3-fri/src/proof.rs (struct QueryProof<F, M, InputProof>)

input_proof: list[BatchOpening]

commit_phase_openings: list[CommitPhaseProofStep]

class protocol.proof.FriProof

Complete FRI proof.

Reference:

p3-fri/src/proof.rs (struct FriProof<F, M, Witness, InputProof>)

commit_phase_commits: list[primitives.field.Digest]

query_proofs: list[QueryProof]

final_poly: list[primitives.field.FF4Coeffs]

commit_pow_witnesses: list[int]

query_pow_witness: int

class protocol.proof.OpeningProof

PCS opening proof with opened values.

Reference:

stark-backend/src/proof.rs (struct OpeningProof<PcsProof, Challenge>)

proof: FriProof

values: OpenedValues

deep_pow_witness: int

class protocol.proof.AirProofData

Proof data for a single AIR.

Reference:

stark-backend/src/proof.rs (struct AirProofData<Val, Challenge>)

air_id: int

degree: int

exposed_values_after_challenge: list[list[primitives.field.FF4Coeffs]]

public_values: list[primitives.field.Fe]

class protocol.proof.FriLogUpPartialProof

Partial proof for the FRI LogUp challenge phase.

Reference:

stark-backend/src/interaction/fri_log_up.rs (struct FriLogUpPartialProof<Witness>)

logup_pow_witness: primitives.field.Fe

class protocol.proof.Proof

Full multi-AIR STARK proof.

Reference:

stark-backend/src/proof.rs (struct Proof<SC>)

commitments: Commitments

opening: OpeningProof

per_air: list[AirProofData]

rap_phase_seq_proof: FriLogUpPartialProof | None = None

class protocol.proof.EntryType(*args, **kwds)

Bases: enum.Enum

Kind of symbolic variable entry.

Reference:

stark-backend/src/air_builders/symbolic/symbolic_variable.rs (enum Entry)

PREPROCESSED

MAIN

PERMUTATION

PUBLIC

CHALLENGE

EXPOSED

class protocol.proof.Entry

Symbolic variable entry with kind and offset/part_index.

Reference:

stark-backend/src/air_builders/symbolic/symbolic_variable.rs (enum Entry)

kind: EntryType

offset: int | None = None

part_index: int | None = None

class protocol.proof.SymbolicVariable

A variable within the evaluation window (column reference).

Reference:

stark-backend/src/air_builders/symbolic/symbolic_variable.rs (struct SymbolicVariable<F>)

entry: Entry

index: int

class protocol.proof.SymbolicNodeKind(*args, **kwds)

Bases: enum.Enum

Kind of symbolic expression node.

Reference:

stark-backend/src/air_builders/symbolic/dag.rs (enum SymbolicExpressionNode)

VARIABLE

IS_FIRST_ROW

IS_LAST_ROW

IS_TRANSITION

CONSTANT

ADD

SUB

NEG

MUL

class protocol.proof.SymbolicExpressionNode

A node in the symbolic expression DAG.

Reference:

stark-backend/src/air_builders/symbolic/dag.rs (enum SymbolicExpressionNode<F>)

Fields vary by kind: - VARIABLE: variable is set - CONSTANT: constant_value is set - ADD/SUB/MUL: left_idx, right_idx, degree_multiple are set - NEG: idx, degree_multiple are set - IS_FIRST_ROW/IS_LAST_ROW/IS_TRANSITION: no extra fields

kind: SymbolicNodeKind

variable: SymbolicVariable | None = None

constant_value: primitives.field.Fe | None = None

left_idx: int | None = None

right_idx: int | None = None

idx: int | None = None

degree_multiple: int | None = None

class protocol.proof.SymbolicExpressionDag

DAG of symbolic expressions in topological order.

Reference:

stark-backend/src/air_builders/symbolic/dag.rs (struct SymbolicExpressionDag<F>)

nodes: list[SymbolicExpressionNode]

constraint_idx: list[int]

class protocol.proof.Interaction

A bus interaction.

Reference:

stark-backend/src/interaction/mod.rs (struct Interaction<Expr>)

In the DAG form, message and count are node indices (int).

message: list[int]

count: int

bus_index: int

count_weight: int

class protocol.proof.SymbolicConstraintsDag

Complete symbolic constraints for a single AIR.

Reference:

stark-backend/src/air_builders/symbolic/dag.rs (struct SymbolicConstraintsDag<F>)

constraints: SymbolicExpressionDag

interactions: list[Interaction]

class protocol.proof.TraceWidth

Widths of different parts of a trace matrix.

Reference:

stark-backend/src/keygen/types.rs (struct TraceWidth)

preprocessed: int | None

cached_mains: list[int]

common_main: int

after_challenge: list[int]

class protocol.proof.StarkVerifyingParams

Verification parameters for a single STARK.

Reference:

stark-backend/src/keygen/types.rs (struct StarkVerifyingParams)

width: TraceWidth

num_public_values: int

num_exposed_values_after_challenge: list[int]

num_challenges_to_sample: list[int]

class protocol.proof.RapPhaseSeqKind(*args, **kwds)

Bases: enum.Enum

Supported challenge phase protocols.

Reference:

stark-backend/src/interaction/mod.rs (enum RapPhaseSeqKind)

FRI_LOG_UP

class protocol.proof.VerifierSinglePreprocessedData

Verifier data for preprocessed trace for a single AIR.

Reference:

stark-backend/src/keygen/types.rs (struct VerifierSinglePreprocessedData<Com>)

commit: primitives.field.Digest

class protocol.proof.StarkVerifyingKey

Verifying key for a single STARK (single AIR).

Reference:

stark-backend/src/keygen/types.rs (struct StarkVerifyingKey<Val, Com>)

preprocessed_data: VerifierSinglePreprocessedData | None

params: StarkVerifyingParams

symbolic_constraints: SymbolicConstraintsDag

quotient_degree: int

rap_phase_seq_kind: RapPhaseSeqKind

class protocol.proof.LinearConstraint

Linear constraint on trace heights.

Reference:

stark-backend/src/keygen/types.rs (struct LinearConstraint)

coefficients: list[int]

threshold: int

class protocol.proof.MultiStarkVerifyingKey0

Inner verifying key data (without pre_hash).

Reference:

stark-backend/src/keygen/types.rs (struct MultiStarkVerifyingKey0<SC>)

per_air: list[StarkVerifyingKey]

trace_height_constraints: list[LinearConstraint]

log_up_pow_bits: int

deep_pow_bits: int

class protocol.proof.MultiStarkVerifyingKey

Complete multi-AIR verifying key.

Reference:

stark-backend/src/keygen/types.rs (struct MultiStarkVerifyingKey<SC>)

inner: MultiStarkVerifyingKey0

pre_hash: primitives.field.Digest

class protocol.proof.FriParameters

FRI protocol parameters.

Reference:

stark-sdk/src/config/mod.rs (struct FriParameters)

log_blowup: int

log_final_poly_len: int

num_queries: int

query_proof_of_work_bits: int

commit_proof_of_work_bits: int

protocol.proof.parse_proof_json(data: dict) → Proof

Parse a Proof from a JSON dict (serde_json format).

Handles the JSON produced by serde_json::to_vec(&proof) for Proof<BabyBearPoseidon2Config>.

Reference:

stark-backend/src/proof.rs (struct Proof<SC>)

protocol.proof.parse_vk_json(data: dict) → MultiStarkVerifyingKey

Parse a MultiStarkVerifyingKey from a JSON dict (serde_json format).

Reference:

stark-backend/src/keygen/types.rs (struct MultiStarkVerifyingKey<SC>)

protocol.proof.parse_fri_params(data: dict) → FriParameters

Parse FRI parameters from a test vector JSON dict.

Reference:

crates/test-vectors/src/lib.rs (struct FriParamsMeta)

class protocol.proof.AirInputData

Raw input trace matrices for one AIR, used by the prover.

Reference:

crates/test-vectors/src/lib.rs (struct AirInputVectors)

air_id: int

common_main: list[list[primitives.field.Fe]] | None

cached_mains: list[list[list[primitives.field.Fe]]]

preprocessed: list[list[primitives.field.Fe]] | None

class protocol.proof.ProverInputs

All input trace data needed by the prover.

Reference:

crates/test-vectors/src/lib.rs (struct ProverInputVectors)

per_air: list[AirInputData]

protocol.proof.parse_prover_inputs(data: dict) → ProverInputs

Parse prover input vectors from JSON.

Field values are canonical u32, no Montgomery conversion needed (traces are raw field elements, not serialized proof data).

Reference:

crates/test-vectors/src/lib.rs (struct ProverInputVectors)

protocol.proof.parse_e2e_vectors(vectors: dict) → tuple[Proof, FriParameters, dict]

Parse complete E2E test vectors.

Returns:

(proof, fri_params, commitments_meta) where: - proof: parsed Proof dataclass - fri_params: parsed FriParameters - commitments_meta: dict with main_trace_commitments, after_challenge_commitments,

quotient_commitment from the test vector (pre-extracted canonical values)

Reference:

crates/test-vectors/src/lib.rs (struct E2eProofVectors)

protocol.proof.serialize_proof_json(proof: Proof) → dict

Serialize a Proof to serde-compatible JSON dict.

Converts canonical field elements back to Montgomery form and uses the exact JSON structure produced by Rust’s serde_json.