ezkl python bindings

class ezkl.PyCommitments

pyclass representing an enum, denoting the type of commitment

IPA = PyCommitments.IPA
KZG = PyCommitments.KZG
class ezkl.PyG1

pyclass containing the struct used for G1, this is mostly a helper class

x

Field Element representing x

y

Field Element representing y

z

Field Element representing y

class ezkl.PyG1Affine

pyclass containing the struct used for G1

x
y
class ezkl.PyRunArgs

Python class containing the struct used for run_args

Return type:

PyRunArgs

bounded_log_lookup

Should the circuit use unbounded lookups for log

Type:

bool

check_mode

check mode, accepts safe, unsafe

Type:

str

commitment

commitment type, accepts kzg, ipa

Type:

str

decomp_base

The base used for decomposition

Type:

int

decomp_legs

The number of legs used for decomposition

Type:

int

input_scale

The denominator in the fixed point representation used when quantizing inputs

Type:

int

input_visibility

accepts public, private, fixed, hashed/public, hashed/private, polycommit

Type:

string

logrows

The log_2 number of rows

Type:

int

lookup_range

The min and max elements in the lookup table input column

Type:

list[int]

num_inner_cols

The number of inner columns used for the lookup table

Type:

int

output_visibility

accepts public, private, fixed, hashed/public, hashed/private, polycommit

Type:

string

param_scale

The denominator in the fixed point representation used when quantizing parameters

Type:

int

param_visibility

accepts public, private, fixed, hashed/public, hashed/private, polycommit

Type:

string

rebase_frac_zero_constants

Should constants with 0.0 fraction be rebased to scale 0

Type:

bool

scale_rebase_multiplier

If the scale is ever > scale_rebase_multiplier * input_scale then the scale is rebased to input_scale (this a more advanced parameter, use with caution)

Type:

int

tolerance

The tolerance for error on model outputs

Type:

float

variables

Hand-written parser for graph variables, eg. batch_size=1

Type:

list[tuple[str, int]]

class ezkl.PyTestDataSource

pyclass representing an enum

File = PyTestDataSource.File
OnChain = PyTestDataSource.OnChain
ezkl.aggregate(aggregation_snarks=Ellipsis, proof_path=Ellipsis, vk_path=Ellipsis, transcript=Ellipsis, logrows=Ellipsis, check_mode=Ellipsis, split_proofs=False, srs_path=None, commitment=Ellipsis)

Creates an aggregated proof

Parameters:

  • aggregation_snarks (list[str]) – List of paths to the various proofs

  • proof_path (str) – Path to output the aggregated proof

  • vk_path (str) – Path to the VK file

  • transcript – Proof transcript type to be used. evm used by default. poseidon is also supported

  • logrows – Logrows used for aggregation circuit

  • check_mode (str) – Run sanity checks during calculations. Accepts safe or unsafe

  • split-proofs (bool) – Whether the accumulated proofs are segments of a larger circuit

  • srs_path (str) – Path to the SRS used

  • commitment (str) – Accepts “kzg” or “ipa”

Return type:

bool

ezkl.buffer_to_felts(buffer)

Converts a buffer to vector of field elements

Parameters:

buffer (list[int]) – List of integers representing a buffer

Returns:

List of field elements represented as strings

Return type:

list[str]

ezkl.calibrate_settings(data=Ellipsis, model=Ellipsis, settings=Ellipsis, target=Ellipsis, lookup_safety_margin=Ellipsis, scales=None, scale_rebase_multiplier=Ellipsis, max_logrows=None)

Calibrates the circuit settings

Parameters:

  • data (str) – Path to the calibration data

  • model (str) – Path to the onnx file

  • settings (str) – Path to the settings file

  • lookup_safety_margin (int) – the lookup safety margin to use for calibration. if the max lookup is 2^k, then the max lookup will be 2^k * lookup_safety_margin. larger = safer but slower

  • scales (list[int]) – Optional scales to specifically try for calibration

  • scale_rebase_multiplier (list[int]) – Optional scale rebase multipliers to specifically try for calibration. This is the multiplier at which we divide to return to the input scale.

  • max_logrows (int) – Optional max logrows to use for calibration

Return type:

bool

ezkl.compile_circuit(model=Ellipsis, compiled_circuit=Ellipsis, settings_path=Ellipsis)

Compiles the circuit for use in other steps

Parameters:

  • model (str) – Path to the onnx model file

  • compiled_circuit (str) – Path to output the compiled circuit

  • settings_path (str) – Path to the settings files

Return type:

bool

ezkl.create_evm_data_attestation(input_data=Ellipsis, settings_path=Ellipsis, sol_code_path=Ellipsis, abi_path=Ellipsis, witness_path=None)

Creates an EVM compatible data attestation verifier, you will need solc installed in your environment to run this

Parameters:

  • input_data (str) – The path to the .json data file, which should contain the necessary calldata and account addresses needed to read from all the on-chain view functions that return the data that the network ingests as inputs

  • settings_path (str) – The path to the settings file

  • sol_code_path (str) – The path to the create the solidity verifier

  • abi_path (str) – The path to create the ABI for the solidity verifier

Return type:

bool

ezkl.create_evm_verifier(vk_path=Ellipsis, settings_path=Ellipsis, sol_code_path=Ellipsis, abi_path=Ellipsis, srs_path=None, reusable=Ellipsis)

Creates an EVM compatible verifier, you will need solc installed in your environment to run this

Parameters:

  • vk_path (str) – The path to the verification key file

  • settings_path (str) – The path to the settings file

  • sol_code_path (str) – The path to the create the solidity verifier

  • abi_path (str) – The path to create the ABI for the solidity verifier

  • srs_path (str) – The path to the SRS file

  • reusable (bool) – Whether the verifier should be rendered as a reusable contract. If so, then you will need to deploy the VK artifact separately which you can generate using the create_evm_vka command

Return type:

bool

ezkl.create_evm_verifier_aggr(aggregation_settings=Ellipsis, vk_path=Ellipsis, sol_code_path=Ellipsis, abi_path=Ellipsis, logrows=Ellipsis, srs_path=None, reusable=Ellipsis)

Creates an evm compatible aggregate verifier, you will need solc installed in your environment to run this

Parameters:

  • aggregation_settings (str) – path to the settings file

  • vk_path (str) – The path to load the desired verification key file

  • sol_code_path (str) – The path to the Solidity code

  • abi_path (str) – The path to output the Solidity verifier ABI

  • logrows (int) – Number of logrows used during aggregated setup

  • srs_path (str) – The path to the SRS file

  • reusable (bool) – Whether the verifier should be rendered as a reusable contract. If so, then you will need to deploy the VK artifact separately which you can generate using the create_evm_vka command

Return type:

bool

ezkl.create_evm_vka(vk_path=Ellipsis, settings_path=Ellipsis, sol_code_path=Ellipsis, abi_path=Ellipsis, srs_path=None)

Creates an Evm VK artifact. This command generated a VK with circuit specific meta data encoding in memory for use by the reusable H2 verifier. This is useful for deploying verifier that were otherwise too big to fit on chain and required aggregation.

Parameters:

  • vk_path (str) – The path to the verification key file

  • settings_path (str) – The path to the settings file

  • sol_code_path (str) – The path to the create the solidity verifying key.

  • abi_path (str) – The path to create the ABI for the solidity verifier

  • srs_path (str) – The path to the SRS file

Return type:

bool

ezkl.deploy_da_evm(addr_path, input_data, settings_path=Ellipsis, sol_code_path=Ellipsis, rpc_url=None, optimizer_runs=Ellipsis, private_key=None)

deploys the solidity da verifier

ezkl.deploy_evm(addr_path, sol_code_path=Ellipsis, rpc_url=None, contract_type=Ellipsis, optimizer_runs=Ellipsis, private_key=None)

deploys the solidity verifier

ezkl.encode_evm_calldata(proof=Ellipsis, calldata=Ellipsis, addr_vk=None)

Creates encoded evm calldata from a proof file

Parameters:

  • proof (str) – Path to the proof file

  • calldata (str) – Path to the calldata file to save

  • addr_vk (str) – The address of the verification key contract (if the verifier key is to be rendered as a separate contract)

Returns:

The encoded calldata

Return type:

vec[u8]

ezkl.felt_to_big_endian(felt)

Converts a field element hex string to big endian

Parameters:

felt (str) – The field element represented as a string

Returns:

field element represented as a string

Return type:

str

ezkl.felt_to_float(felt, scale)

Converts a field element hex string to a floating point number

Parameters:

  • felt (str) – The field element represented as a string

  • scale (float) – The scaling factor used to convert the field element into a floating point representation

Return type:

float

ezkl.felt_to_int(felt)

Converts a field element hex string to an integer

Parameters:

felt (str) – The field element represented as a string

Return type:

int

ezkl.float_to_felt(input, scale)

Converts a floating point element to a field element hex string

Parameters:

  • input (float) – The field element represented as a string

  • scale (float) – The scaling factor used to quantize the float into a field element

Returns:

The field element represented as a string

Return type:

str

ezkl.gen_settings(model=Ellipsis, output=Ellipsis, py_run_args=None)

Generates the circuit settings

Parameters:

  • model (str) – Path to the onnx file

  • output (str) – Path to create the settings file

  • py_run_args (PyRunArgs) – PyRunArgs object to initialize the settings

Return type:

bool

ezkl.gen_srs(srs_path, logrows)

Generates the Structured Reference String (SRS), use this only for testing purposes

Parameters:

  • srs_path (str) – Path to the create the SRS file

  • logrows (int) – The number of logrows for the SRS file

ezkl.gen_vk_from_pk_aggr(path_to_pk=Ellipsis, vk_output_path=Ellipsis)

Generates a vk from a pk for an aggregate circuit and saves it to a file

Parameters:

  • path_to_pk (str) – Path to the proving key

  • vk_output_path (str) – Path to create the vk file

Return type:

bool

ezkl.gen_vk_from_pk_single(path_to_pk=Ellipsis, circuit_settings_path=Ellipsis, vk_output_path=Ellipsis)

Generates a vk from a pk for a model circuit and saves it to a file

Parameters:

  • path_to_pk (str) – Path to the proving key

  • circuit_settings_path (str) – Path to the witness file

  • vk_output_path (str) – Path to create the vk file

Return type:

bool

ezkl.gen_witness(data=Ellipsis, model=Ellipsis, output=Ellipsis, vk_path=None, srs_path=None)

Runs the forward pass operation to generate a witness

Parameters:

  • data (str) – Path to the data file

  • model (str) – Path to the compiled model file

  • output (str) – Path to create the witness file

  • vk_path (str) – Path to the verification key

  • srs_path (str) – Path to the SRS file

Returns:

Python object containing the witness values

Return type:

dict

ezkl.get_srs(settings_path=Ellipsis, logrows=None, srs_path=None, commitment=None)

Gets a public srs

Parameters:

  • settings_path (str) – Path to the settings file

  • logrows (int) – The number of logrows for the SRS file

  • srs_path (str) – Path to the create the SRS file

  • commitment (str) – Specify the commitment used (“kzg”, “ipa”)

Return type:

bool

ezkl.ipa_commit(message, vk_path=Ellipsis, settings_path=Ellipsis, srs_path=None)

Generate an ipa commitment.

Parameters:

  • message (list[str]) – List of field elements represnted as strings

  • vk_path (str) – Path to the verification key

  • settings_path (str) – Path to the settings file

  • srs_path (str) – Path to the Structure Reference String (SRS) file

Return type:

list[PyG1Affine]

ezkl.kzg_commit(message, vk_path=Ellipsis, settings_path=Ellipsis, srs_path=None)

Generate a kzg commitment.

Parameters:

  • message (list[str]) – List of field elements represnted as strings

  • vk_path (str) – Path to the verification key

  • settings_path (str) – Path to the settings file

  • srs_path (str) – Path to the Structure Reference String (SRS) file

Return type:

list[PyG1Affine]

ezkl.mock(witness=Ellipsis, model=Ellipsis)

Mocks the prover

Parameters:

  • witness (str) – Path to the witness file

  • model (str) – Path to the compiled model file

Return type:

bool

ezkl.mock_aggregate(aggregation_snarks=Ellipsis, logrows=Ellipsis, split_proofs=False)

Mocks the aggregate prover

Parameters:

  • aggregation_snarks (list[str]) – List of paths to the relevant proof files

  • logrows (int) – Number of logrows to use for the aggregation circuit

  • split_proofs (bool) – Indicates whether the accumulated are segments of a larger proof

Return type:

bool

ezkl.poseidon_hash(message)

Generate a poseidon hash.

Parameters:

message (list[str]) – List of field elements represented as strings

Returns:

List of field elements represented as strings

Return type:

list[str]

ezkl.prove(witness=Ellipsis, model=Ellipsis, pk_path=Ellipsis, proof_path=None, proof_type=Ellipsis, srs_path=None)

Runs the prover on a set of inputs

Parameters:

  • witness (str) – Path to the witness file

  • model (str) – Path to the compiled model file

  • pk_path (str) – Path to the proving key file

  • proof_path (str) – Path to create the proof file

  • proof_type (str) – Accepts single, for-aggr

  • srs_path (str) – Path to the SRS file

Return type:

bool

ezkl.setup(model=Ellipsis, vk_path=Ellipsis, pk_path=Ellipsis, srs_path=None, witness_path=None, disable_selector_compression=Ellipsis)

Runs the setup process

Parameters:

  • model (str) – Path to the compiled model file

  • vk_path (str) – Path to create the verification key file

  • pk_path (str) – Path to create the proving key file

  • srs_path (str) – Path to the SRS file

  • witness_path (str) – Path to the witness file

  • disable_selector_compression (bool) – Whether to compress the selectors or not

Return type:

bool

ezkl.setup_aggregate(sample_snarks=Ellipsis, vk_path=Ellipsis, pk_path=Ellipsis, logrows=Ellipsis, split_proofs=False, srs_path=None, disable_selector_compression=Ellipsis, commitment=Ellipsis)

Runs the setup process for an aggregate setup

Parameters:

  • sample_snarks (list[str]) – List of paths to the various proofs

  • vk_path (str) – Path to create the aggregated VK

  • pk_path (str) – Path to create the aggregated PK

  • logrows (int) – Number of logrows to use

  • split_proofs (bool) – Whether the accumulated are segments of a larger proof

  • srs_path (str) – Path to the SRS file

  • disable_selector_compression (bool) – Whether to compress selectors

  • commitment (str) – Accepts kzg, ipa

Return type:

bool

ezkl.setup_test_evm_witness(data_path, compiled_circuit_path, test_data, input_source, output_source, rpc_url=None)

Setup test evm witness

Parameters:

  • data_path (str) – The path to the .json data file, which should include both the network input (possibly private) and the network output (public input to the proof)

  • compiled_circuit_path (str) – The path to the compiled model file (generated using the compile-circuit command)

  • test_data (str) – For testing purposes only. The optional path to the .json data file that will be generated that contains the OnChain data storage information derived from the file information in the data .json file. Should include both the network input (possibly private) and the network output (public input to the proof)

  • input_sources (str) – Where the input data comes from

  • output_source (str) – Where the output data comes from

  • rpc_url (str) – RPC URL for an EVM compatible node, if None, uses Anvil as a local RPC node

Return type:

bool

ezkl.swap_proof_commitments(proof_path=Ellipsis, witness_path=Ellipsis)

Swap the commitments in a proof

Parameters:

  • proof_path (str) – Path to the proof file

  • witness_path (str) – Path to the witness file

ezkl.table(model=Ellipsis, py_run_args=None)

Displays the table as a string in python

Parameters:

model (str) – Path to the onnx file

Returns:

Table of the nodes in the onnx file

Return type:

str

ezkl.verify(proof_path=Ellipsis, settings_path=Ellipsis, vk_path=Ellipsis, srs_path=None, reduced_srs=Ellipsis)

Verifies a given proof

Parameters:

  • proof_path (str) – Path to create the proof file

  • settings_path (str) – Path to the settings file

  • vk_path (str) – Path to the verification key file

  • srs_path (str) – Path to the SRS file

  • non_reduced_srs (bool) – Whether to reduce the number of SRS logrows to the number of instances rather than the number of logrows used for proofs (only works if the srs were generated in the same ceremony)

Return type:

bool

ezkl.verify_aggr(proof_path=Ellipsis, vk_path=Ellipsis, logrows=Ellipsis, commitment=Ellipsis, reduced_srs=Ellipsis, srs_path=None)

Verifies and aggregate proof

Parameters:

  • proof_path (str) – The path to the proof file

  • vk_path (str) – The path to the verification key file

  • logrows (int) – logrows used for aggregation circuit

  • commitment (str) – Accepts “kzg” or “ipa”

  • reduced_srs (bool) – Whether to reduce the number of SRS logrows to the number of instances rather than the number of logrows used for proofs (only works if the srs were generated in the same ceremony)

  • srs_path (str) – The path to the SRS file

Return type:

bool

ezkl.verify_evm(addr_verifier, proof_path=Ellipsis, rpc_url=None, addr_da=None, addr_vk=None)

verifies an evm compatible proof, you will need solc installed in your environment to run this

Parameters:

  • addr_verifier (str) – The verifier contract’s address as a hex string

  • proof_path (str) – The path to the proof file (generated using the prove command)

  • rpc_url (str) – RPC URL for an Ethereum node, if None will use Anvil but WON’T persist state

  • addr_da (str) – does the verifier use data attestation ?

  • addr_vk (str) – The addess of the separate VK contract (if the verifier key is rendered as a separate contract)

Return type:

bool