LLZK 2.1.1
An open-source IR for Zero Knowledge (ZK) circuits
Loading...
Searching...
No Matches
llzk::witgen Namespace Reference

Classes

struct  ArrayValue
 Materialized array value with flattened element storage. More...
class  FunctionInterpreter
 Execute one flattened LLZK function body over runtime values. More...
struct  InputBinding
 Describe one JSON-visible main input binding. More...
class  Interpreter
 Drive witness generation for the concrete llzk.main instance. More...
struct  JSONMismatch
 One structured JSON mismatch between expected and actual witgen output. More...
struct  OutputBinding
 Describe one selected witness output leaf. More...
struct  PodValue
 Materialized POD value keyed by record name. More...
struct  StructValue
 Materialized struct value keyed by member name. More...
struct  WitgenOptions
 Configure one llzk-witgen execution. More...

Typedefs

using ArrayValueRef = std::shared_ptr<ArrayValue>
 Shared runtime storage for LLZK array values.
using PodValueRef = std::shared_ptr<PodValue>
 Shared runtime storage for LLZK POD values.
using StructValueRef = std::shared_ptr<StructValue>
 Shared runtime storage for LLZK struct values.
using WitnessVal
 Runtime value representation used by the tool-local interpreter.

Enumerations

enum class  SerializationMode : std::uint8_t { PublicOutputsOnly , AllSignals }
 Select how struct values are filtered during JSON serialization. More...
enum class  UninitializedBehavior : std::uint8_t { Zero , Random , Fail }
 Control how witgen materializes uninitialized/default values. More...
enum class  Backend : std::uint8_t { Interpreter , ExecutionEngine }
 Select the execution backend used by llzk-witgen. More...
enum class  OutputScope : std::uint8_t { Public , FullWitness }
 Select the JSON scope emitted by llzk-witgen. More...

Functions

llvm::Error makeError (const llvm::Twine &msg)
 Build a string-backed error for user-facing witgen failures.
llvm::Expected< llvm::json::Value > runWithExecutionEngine (ModuleOp moduleOp, SymbolTableCollection &tables, const Field &field, const llvm::json::Value &input, const WitgenOptions &options)
 Execute witness generation through MLIR lowering and the LLVM execution engine.
llvm::Expected< llvm::json::Value > runWithExecutionEngine (mlir::ModuleOp moduleOp, mlir::SymbolTableCollection &tables, const llzk::Field &field, const llvm::json::Value &input, const WitgenOptions &options)
 Execute witness generation through MLIR lowering and ExecutionEngine.
llvm::Expected< WitnessValparseJSONValue (const llvm::json::Value *json, Type type, const Field &field, Operation *origin)
 Parse a supported LLZK input type from JSON.
llvm::Expected< llvm::json::Value > serializeJSONValue (const WitnessVal &value, Type type, SymbolTableCollection &tables, Operation *origin, SerializationMode mode)
 Serialize a supported LLZK runtime value into JSON.
llvm::Expected< llvm::json::Object > buildInputsJSONObject (ArrayRef< InputBinding > bindings, ArrayRef< WitnessVal > values, SymbolTableCollection &tables, Operation *origin)
 Serialize named input values into a JSON object.
llvm::Expected< WitnessValextractValueAtPath (const WitnessVal &root, Type rootType, ArrayRef< std::string > path, SymbolTableCollection &tables, Operation *origin)
 Extract one nested runtime leaf by path.
void diffJSON (const llvm::json::Value &expected, const llvm::json::Value &actual, llvm::SmallVectorImpl< JSONMismatch > &out, llvm::StringRef path="$")
 Compare two JSON values structurally and append any mismatches to out.
void printJSONMismatches (llvm::raw_ostream &os, llvm::ArrayRef< JSONMismatch > mismatches)
 Render one human-readable mismatch report.
llvm::Expected< WitnessValparseJSONValue (const llvm::json::Value *json, mlir::Type type, const llzk::Field &field, mlir::Operation *origin)
 Parse one JSON value into the tool's runtime representation.
llvm::Expected< llvm::json::Value > serializeJSONValue (const WitnessVal &value, mlir::Type type, mlir::SymbolTableCollection &tables, mlir::Operation *origin, SerializationMode mode=SerializationMode::PublicOutputsOnly)
 Serialize one runtime value into the user-facing JSON output format.
llvm::Expected< llvm::json::Object > buildInputsJSONObject (llvm::ArrayRef< InputBinding > bindings, llvm::ArrayRef< WitnessVal > values, mlir::SymbolTableCollection &tables, mlir::Operation *origin)
 Serialize named input values into a JSON object.
llvm::Expected< WitnessValextractValueAtPath (const WitnessVal &root, mlir::Type rootType, llvm::ArrayRef< std::string > path, mlir::SymbolTableCollection &tables, mlir::Operation *origin)
 Extract one nested runtime leaf by path.
llvm::Expected< bool > asBool (const WitnessVal &value)
 Require a boolean value from the runtime variant.
llvm::Expected< int64_t > asIndex (const WitnessVal &value)
 Require an index value from the runtime variant.
llvm::Expected< llvm::DynamicAPInt > asFelt (const WitnessVal &value)
 Require a felt value from the runtime variant.
llvm::Expected< ArrayValueRefasArray (const WitnessVal &value)
 Require an array value from the runtime variant.
llvm::Expected< PodValueRefasPod (const WitnessVal &value)
 Require a POD value from the runtime variant.
llvm::Expected< StructValueRefasStruct (const WitnessVal &value)
 Require a struct value from the runtime variant.
llvm::Expected< WitnessValdefaultValue (Type type, SymbolTableCollection &tables, Operation *origin, const Field &field, UninitializedBehavior behavior, std::mt19937_64 *rng)
 Build a default value for a supported LLZK type.
llvm::Expected< WitnessValdefaultValue (mlir::Type type, mlir::SymbolTableCollection &tables, mlir::Operation *origin, const llzk::Field &field, UninitializedBehavior behavior, std::mt19937_64 *rng=nullptr)
 Build a default value used for llzk.nondet and aggregate constructors.
llvm::Expected< llvm::json::Value > runWitgen (ModuleOp moduleOp, const llvm::json::Value &input, const WitgenOptions &options)
 Run include preprocessing, field validation, and backend execution.
llvm::Expected< llvm::json::Value > runWitgen (mlir::ModuleOp moduleOp, const llvm::json::Value &input, const WitgenOptions &options)
 Run the full llzk-witgen pipeline on a parsed module.
void addWitgenPreparePipeline (OpPassManager &pm, const WitgenOptions &)
std::unique_ptr< Pass > createLowerComputeToCorePass (const WitgenOptions &options)
 Create the pass that lowers supported LLZK compute IR into core MLIR dialects suitable for LLVM lowering.
std::unique_ptr< Pass > createCreateWitgenEntryPass (bool emitFullWitness)
 Create the pass that synthesizes the stable llzk-witgen JIT entry wrapper.
void addWitgenPreparePipeline (mlir::OpPassManager &pm, const WitgenOptions &options)
 Add the preprocessing pipeline required before witgen backend execution.
llvm::Expected< size_t > checkedDynamicAPIntToSize (const llvm::DynamicAPInt &value, llvm::StringRef context)
 Convert a DynamicAPInt into size_t after validating its range.
llvm::Expected< size_t > checkedShapeDimToSize (int64_t dim, llvm::StringRef context)
 Convert one static dimension to size_t, rejecting dynamic or invalid sizes.
llvm::Expected< size_t > getStaticShapeElementCount (llvm::ArrayRef< int64_t > shape, llvm::StringRef context)
 Return the static element count for one shape, rejecting dynamic sizes.
llvm::Expected< size_t > getStaticElementCount (ShapedType type, llvm::StringRef context)
std::mt19937_64 makeDefaultValueRng (const WitgenOptions &options)
 Seed an RNG for random/default witness value materialization.
llvm::DynamicAPInt randomFieldElement (std::mt19937_64 &rng, const Field &field)
 Draw a uniformly distributed field element in [0, prime).
int64_t randomIndexValue (std::mt19937_64 &rng)
 Draw a uniformly distributed signed index value.
bool randomBoolValue (std::mt19937_64 &rng)
 Draw a uniformly distributed boolean value.
template<typename T, typename U>
llvm::Expected< T > checkedCast (U u)
llvm::Expected< size_t > getStaticElementCount (mlir::ShapedType type, llvm::StringRef context)
 Return the static element count for one shaped type.
bool memberIsSignal (component::StructDefOp owner, component::MemberDefOp member)
 Return true iff the member is considered a witness signal.
llvm::SmallVector< InputBindingcollectInputBindings (function::FuncDefOp computeFunc)
 Collect stable JSON bindings for the main compute inputs.
FailureOr< llvm::SmallVector< OutputBinding > > collectOutputBindings (component::StructDefOp mainDef, SymbolTableCollection &tables, Operation *origin, OutputScope scope)
 Collect the selected output bindings for the requested scope.
llvm::json::Value buildSignalsJSONObject (ArrayRef< OutputBinding > bindings, ArrayRef< llvm::json::Value > serializedLeaves)
 Assemble a nested JSON object from selected witness leaves.
mlir::FailureOr< llvm::SmallVector< OutputBinding > > collectOutputBindings (component::StructDefOp mainDef, mlir::SymbolTableCollection &tables, mlir::Operation *origin, OutputScope scope)
 Collect the selected output bindings for the requested scope.
llvm::json::Value buildSignalsJSONObject (llvm::ArrayRef< OutputBinding > bindings, llvm::ArrayRef< llvm::json::Value > serializedLeaves)
 Assemble a nested JSON object from selected witness leaves.

Typedef Documentation

◆ ArrayValueRef

using llzk::witgen::ArrayValueRef = std::shared_ptr<ArrayValue>

Shared runtime storage for LLZK array values.

Definition at line 42 of file ValueModel.h.

◆ PodValueRef

using llzk::witgen::PodValueRef = std::shared_ptr<PodValue>

Shared runtime storage for LLZK POD values.

Definition at line 45 of file ValueModel.h.

◆ StructValueRef

using llzk::witgen::StructValueRef = std::shared_ptr<StructValue>

Shared runtime storage for LLZK struct values.

Definition at line 48 of file ValueModel.h.

◆ WitnessVal

Initial value:
std::variant<
std::monostate, bool, int64_t, llvm::DynamicAPInt, ArrayValueRef, PodValueRef, StructValueRef>
std::shared_ptr< ArrayValue > ArrayValueRef
Shared runtime storage for LLZK array values.
Definition ValueModel.h:42
std::shared_ptr< PodValue > PodValueRef
Shared runtime storage for LLZK POD values.
Definition ValueModel.h:45
std::shared_ptr< StructValue > StructValueRef
Shared runtime storage for LLZK struct values.
Definition ValueModel.h:48

Runtime value representation used by the tool-local interpreter.

Definition at line 51 of file ValueModel.h.

Enumeration Type Documentation

◆ Backend

enum class llzk::witgen::Backend : std::uint8_t
strong

Select the execution backend used by llzk-witgen.

Enumerator
Interpreter 
ExecutionEngine 

Definition at line 28 of file WitgenDriver.h.

◆ OutputScope

enum class llzk::witgen::OutputScope : std::uint8_t
strong

Select the JSON scope emitted by llzk-witgen.

Enumerator
Public 
FullWitness 

Definition at line 34 of file WitgenDriver.h.

◆ SerializationMode

enum class llzk::witgen::SerializationMode : std::uint8_t
strong

Select how struct values are filtered during JSON serialization.

Enumerator
PublicOutputsOnly 
AllSignals 

Definition at line 21 of file JSON.h.

◆ UninitializedBehavior

enum class llzk::witgen::UninitializedBehavior : std::uint8_t
strong

Control how witgen materializes uninitialized/default values.

Enumerator
Zero 
Random 
Fail 

Definition at line 55 of file ValueModel.h.

Function Documentation

◆ addWitgenPreparePipeline() [1/2]

void llzk::witgen::addWitgenPreparePipeline ( mlir::OpPassManager & pm,
const WitgenOptions & options )

Add the preprocessing pipeline required before witgen backend execution.

◆ addWitgenPreparePipeline() [2/2]

void llzk::witgen::addWitgenPreparePipeline ( OpPassManager & pm,
const WitgenOptions &  )

Definition at line 2338 of file WitgenLowering.cpp.

◆ asArray()

llvm::Expected< ArrayValueRef > llzk::witgen::asArray ( const WitnessVal & value)

Require an array value from the runtime variant.

Interpret a runtime value as an array reference.

Definition at line 60 of file ValueModel.cpp.

◆ asBool()

llvm::Expected< bool > llzk::witgen::asBool ( const WitnessVal & value)

Require a boolean value from the runtime variant.

Interpret a runtime value as a boolean.

Definition at line 27 of file ValueModel.cpp.

◆ asFelt()

llvm::Expected< llvm::DynamicAPInt > llzk::witgen::asFelt ( const WitnessVal & value)

Require a felt value from the runtime variant.

Interpret a runtime value as a field element.

Definition at line 49 of file ValueModel.cpp.

◆ asIndex()

llvm::Expected< int64_t > llzk::witgen::asIndex ( const WitnessVal & value)

Require an index value from the runtime variant.

Interpret a runtime value as an index-sized signed integer.

Definition at line 38 of file ValueModel.cpp.

◆ asPod()

llvm::Expected< PodValueRef > llzk::witgen::asPod ( const WitnessVal & value)

Require a POD value from the runtime variant.

Interpret a runtime value as a POD reference.

Definition at line 71 of file ValueModel.cpp.

◆ asStruct()

llvm::Expected< StructValueRef > llzk::witgen::asStruct ( const WitnessVal & value)

Require a struct value from the runtime variant.

Interpret a runtime value as a struct reference.

Definition at line 82 of file ValueModel.cpp.

◆ buildInputsJSONObject() [1/2]

llvm::Expected< llvm::json::Object > llzk::witgen::buildInputsJSONObject ( ArrayRef< InputBinding > bindings,
ArrayRef< WitnessVal > values,
SymbolTableCollection & tables,
Operation * origin )

Serialize named input values into a JSON object.

Definition at line 401 of file JSON.cpp.

◆ buildInputsJSONObject() [2/2]

llvm::Expected< llvm::json::Object > llzk::witgen::buildInputsJSONObject ( llvm::ArrayRef< InputBinding > bindings,
llvm::ArrayRef< WitnessVal > values,
mlir::SymbolTableCollection & tables,
mlir::Operation * origin )

Serialize named input values into a JSON object.

◆ buildSignalsJSONObject() [1/2]

llvm::json::Value llzk::witgen::buildSignalsJSONObject ( ArrayRef< OutputBinding > bindings,
ArrayRef< llvm::json::Value > serializedLeaves )

Assemble a nested JSON object from selected witness leaves.

Definition at line 190 of file WitnessSelection.cpp.

◆ buildSignalsJSONObject() [2/2]

llvm::json::Value llzk::witgen::buildSignalsJSONObject ( llvm::ArrayRef< OutputBinding > bindings,
llvm::ArrayRef< llvm::json::Value > serializedLeaves )

Assemble a nested JSON object from selected witness leaves.

◆ checkedCast()

template<typename T, typename U>
llvm::Expected< T > llzk::witgen::checkedCast ( U u)
inline

Definition at line 28 of file WitgenUtils.h.

◆ checkedDynamicAPIntToSize()

llvm::Expected< size_t > llzk::witgen::checkedDynamicAPIntToSize ( const llvm::DynamicAPInt & value,
llvm::StringRef context )

Convert a DynamicAPInt into size_t after validating its range.

Definition at line 43 of file WitgenUtils.cpp.

◆ checkedShapeDimToSize()

llvm::Expected< size_t > llzk::witgen::checkedShapeDimToSize ( int64_t dim,
llvm::StringRef context )

Convert one static dimension to size_t, rejecting dynamic or invalid sizes.

Definition at line 47 of file WitgenUtils.cpp.

◆ collectInputBindings()

llvm::SmallVector< InputBinding > llzk::witgen::collectInputBindings ( function::FuncDefOp computeFunc)

Collect stable JSON bindings for the main compute inputs.

Definition at line 152 of file WitnessSelection.cpp.

◆ collectOutputBindings() [1/2]

mlir::FailureOr< llvm::SmallVector< OutputBinding > > llzk::witgen::collectOutputBindings ( component::StructDefOp mainDef,
mlir::SymbolTableCollection & tables,
mlir::Operation * origin,
OutputScope scope )

Collect the selected output bindings for the requested scope.

◆ collectOutputBindings() [2/2]

FailureOr< llvm::SmallVector< OutputBinding > > llzk::witgen::collectOutputBindings ( component::StructDefOp mainDef,
SymbolTableCollection & tables,
Operation * origin,
OutputScope scope )

Collect the selected output bindings for the requested scope.

Definition at line 168 of file WitnessSelection.cpp.

◆ createCreateWitgenEntryPass()

std::unique_ptr< mlir::Pass > llzk::witgen::createCreateWitgenEntryPass ( bool emitFullWitness)

Create the pass that synthesizes the stable llzk-witgen JIT entry wrapper.

Definition at line 2354 of file WitgenLowering.cpp.

◆ createLowerComputeToCorePass()

std::unique_ptr< mlir::Pass > llzk::witgen::createLowerComputeToCorePass ( const WitgenOptions & options)

Create the pass that lowers supported LLZK compute IR into core MLIR dialects suitable for LLVM lowering.

Definition at line 2350 of file WitgenLowering.cpp.

◆ defaultValue() [1/2]

llvm::Expected< WitnessVal > llzk::witgen::defaultValue ( mlir::Type type,
mlir::SymbolTableCollection & tables,
mlir::Operation * origin,
const llzk::Field & field,
UninitializedBehavior behavior,
std::mt19937_64 * rng = nullptr )

Build a default value used for llzk.nondet and aggregate constructors.

◆ defaultValue() [2/2]

llvm::Expected< WitnessVal > llzk::witgen::defaultValue ( Type type,
SymbolTableCollection & tables,
Operation * origin,
const Field & field,
UninitializedBehavior behavior,
std::mt19937_64 * rng )

Build a default value for a supported LLZK type.

Definition at line 93 of file ValueModel.cpp.

◆ diffJSON()

void llzk::witgen::diffJSON ( const llvm::json::Value & expected,
const llvm::json::Value & actual,
llvm::SmallVectorImpl< JSONMismatch > & out,
llvm::StringRef path )

Compare two JSON values structurally and append any mismatches to out.

Definition at line 473 of file JSON.cpp.

◆ extractValueAtPath() [1/2]

llvm::Expected< WitnessVal > llzk::witgen::extractValueAtPath ( const WitnessVal & root,
mlir::Type rootType,
llvm::ArrayRef< std::string > path,
mlir::SymbolTableCollection & tables,
mlir::Operation * origin )

Extract one nested runtime leaf by path.

◆ extractValueAtPath() [2/2]

llvm::Expected< WitnessVal > llzk::witgen::extractValueAtPath ( const WitnessVal & root,
Type rootType,
ArrayRef< std::string > path,
SymbolTableCollection & tables,
Operation * origin )

Extract one nested runtime leaf by path.

Definition at line 422 of file JSON.cpp.

◆ getStaticElementCount() [1/2]

llvm::Expected< size_t > llzk::witgen::getStaticElementCount ( mlir::ShapedType type,
llvm::StringRef context )

Return the static element count for one shaped type.

◆ getStaticElementCount() [2/2]

llvm::Expected< size_t > llzk::witgen::getStaticElementCount ( ShapedType type,
llvm::StringRef context )

Definition at line 71 of file WitgenUtils.cpp.

◆ getStaticShapeElementCount()

llvm::Expected< size_t > llzk::witgen::getStaticShapeElementCount ( llvm::ArrayRef< int64_t > shape,
llvm::StringRef context )

Return the static element count for one shape, rejecting dynamic sizes.

Definition at line 59 of file WitgenUtils.cpp.

◆ makeDefaultValueRng()

std::mt19937_64 llzk::witgen::makeDefaultValueRng ( const WitgenOptions & options)

Seed an RNG for random/default witness value materialization.

Definition at line 82 of file WitgenUtils.cpp.

◆ makeError()

llvm::Error llzk::witgen::makeError ( const llvm::Twine & msg)
inline

Build a string-backed error for user-facing witgen failures.

Definition at line 18 of file Errors.h.

◆ memberIsSignal()

bool llzk::witgen::memberIsSignal ( component::StructDefOp owner,
component::MemberDefOp member )

Return true iff the member is considered a witness signal.

Definition at line 147 of file WitnessSelection.cpp.

◆ parseJSONValue() [1/2]

llvm::Expected< WitnessVal > llzk::witgen::parseJSONValue ( const llvm::json::Value * json,
mlir::Type type,
const llzk::Field & field,
mlir::Operation * origin )

Parse one JSON value into the tool's runtime representation.

◆ parseJSONValue() [2/2]

llvm::Expected< WitnessVal > llzk::witgen::parseJSONValue ( const llvm::json::Value * json,
Type type,
const Field & field,
Operation * origin )

Parse a supported LLZK input type from JSON.

Definition at line 263 of file JSON.cpp.

◆ printJSONMismatches()

void llzk::witgen::printJSONMismatches ( llvm::raw_ostream & os,
llvm::ArrayRef< JSONMismatch > mismatches )

Render one human-readable mismatch report.

Definition at line 504 of file JSON.cpp.

◆ randomBoolValue()

bool llzk::witgen::randomBoolValue ( std::mt19937_64 & rng)

Draw a uniformly distributed boolean value.

Definition at line 123 of file WitgenUtils.cpp.

◆ randomFieldElement()

llvm::DynamicAPInt llzk::witgen::randomFieldElement ( std::mt19937_64 & rng,
const Field & field )

Draw a uniformly distributed field element in [0, prime).

Definition at line 91 of file WitgenUtils.cpp.

◆ randomIndexValue()

int64_t llzk::witgen::randomIndexValue ( std::mt19937_64 & rng)

Draw a uniformly distributed signed index value.

Definition at line 118 of file WitgenUtils.cpp.

◆ runWitgen() [1/2]

llvm::Expected< llvm::json::Value > llzk::witgen::runWitgen ( mlir::ModuleOp moduleOp,
const llvm::json::Value & input,
const WitgenOptions & options )

Run the full llzk-witgen pipeline on a parsed module.

◆ runWitgen() [2/2]

llvm::Expected< llvm::json::Value > llzk::witgen::runWitgen ( ModuleOp moduleOp,
const llvm::json::Value & input,
const WitgenOptions & options )

Run include preprocessing, field validation, and backend execution.

Definition at line 202 of file WitgenDriver.cpp.

◆ runWithExecutionEngine() [1/2]

llvm::Expected< llvm::json::Value > llzk::witgen::runWithExecutionEngine ( mlir::ModuleOp moduleOp,
mlir::SymbolTableCollection & tables,
const llzk::Field & field,
const llvm::json::Value & input,
const WitgenOptions & options )

Execute witness generation through MLIR lowering and ExecutionEngine.

◆ runWithExecutionEngine() [2/2]

llvm::Expected< llvm::json::Value > llzk::witgen::runWithExecutionEngine ( ModuleOp moduleOp,
SymbolTableCollection & tables,
const Field & field,
const llvm::json::Value & input,
const WitgenOptions & options )

Execute witness generation through MLIR lowering and the LLVM execution engine.

Definition at line 357 of file ExecutionEngineBackend.cpp.

◆ serializeJSONValue() [1/2]

llvm::Expected< llvm::json::Value > llzk::witgen::serializeJSONValue ( const WitnessVal & value,
mlir::Type type,
mlir::SymbolTableCollection & tables,
mlir::Operation * origin,
SerializationMode mode = SerializationMode::PublicOutputsOnly )

Serialize one runtime value into the user-facing JSON output format.

◆ serializeJSONValue() [2/2]

llvm::Expected< llvm::json::Value > llzk::witgen::serializeJSONValue ( const WitnessVal & value,
Type type,
SymbolTableCollection & tables,
Operation * origin,
SerializationMode mode )

Serialize a supported LLZK runtime value into JSON.

Definition at line 300 of file JSON.cpp.