ckzg

Common errors

• error: subprocess-exited-with-error × Building wheel for ckzg (pyproject.toml) did not run successfully. │ exit code: 1

  cause This error typically occurs during installation when `pip` attempts to build the `ckzg` wheel but encounters issues with the underlying C dependencies or build environment, often due to missing compilers or specific system configurations.
  fix Ensure you have necessary build tools installed (e.g., `build-essential` on Linux, Xcode command line tools on macOS). You might also need to install `rust` if it's a dependency for `pyo3` or related components, and ensure `setuptools` and `wheel` are up to date: `pip install --upgrade setuptools wheel`.

• ImportError: No module named 'ckzg'

  cause This error indicates that Python cannot find the `ckzg` module, usually because the installation failed, the package was installed in a different Python environment, or the Python interpreter being used does not have access to the installed packages.
  fix Verify `ckzg` was successfully installed by checking `pip list | grep ckzg`. If not, re-run `pip install ckzg` and address any installation errors. Ensure you are using the correct Python interpreter where `ckzg` was installed.

• This package requires Python version >= X, not Y

  cause The `ckzg` library, like many Python packages, has specific Python version requirements, and this error arises when attempting to install or run it with an incompatible Python interpreter version.
  fix Use a Python version that satisfies the library's requirements (e.g., Python 3.8+). You can manage Python versions using tools like `pyenv` or `conda`, or ensure your system's default `python` or `python3` command points to an appropriate version.

Warnings

• breaking Version 2.0.0 introduced support for EIP-7594 and updated the trusted setup format. Users upgrading from versions prior to 2.0.0 must download the new `trusted_setup.txt` file.
  Fix: Download the new `trusted_setup.txt` from the official c-kzg-4844 GitHub repository (e.g., `https://github.com/ethereum/c-kzg-4844/blob/main/trusted_setup.txt`) and ensure your application uses this updated file when loading the trusted setup.
• gotcha Version 2.1.5 fixed a critical bug where the computed challenge for `verify_cell_kzg_proof_batch` did not account for all deduplicated commitments, leading to a potential Weak Fiat-Shamir vulnerability.
  Fix: Upgrade to `ckzg` version 2.1.5 or later to mitigate this vulnerability and ensure correct challenge computation.
• gotcha Version 2.1.3 fixed a bug that could cause `verify_cell_kzg_proof_batch` results to be incorrect. This was related to simplified `g1_lincomb_fast` in a previous release, which unintentionally removed necessary point-at-infinity filtering.
  Fix: Upgrade to `ckzg` version 2.1.3 or later to ensure the correctness of batch KZG proof verification.
• gotcha Version 2.1.4 reverted the internal `blst` dependency to its latest stable version and re-added point-at-infinity filtering to address concerns with unreleased `blst` versions and ensure correct cryptographic operations.
  Fix: Upgrade to `ckzg` version 2.1.4 or later to benefit from the stable `blst` dependency and improved correctness safeguards.
• deprecated Starting with version 2.1.7, support for macOS x86 in the Python package workflow has been dropped.
  Fix: Users on macOS x86 systems should consider targeting earlier `ckzg` versions or migrating to ARM-based macOS machines for continued official package support.

Install

• pip install ckzg Install latest version

Imports

• ckzg

  import ckzg

  The primary interface is directly through the `ckzg` module.
• load_trusted_setup

  from ckzg import load_trusted_setup

  Used to load the KZG trusted setup parameters from a file.

Quickstart

This quickstart demonstrates how to load a KZG trusted setup and generate a KZG commitment for a random blob. It requires the `trusted_setup.txt` file, which can be provided via the `KZG_TRUSTED_SETUP_PATH` environment variable or a direct path. This file is essential for all cryptographic operations.

import os
import random
from pathlib import Path
from ckzg import load_trusted_setup, blob_to_kzg_commitment, BLS_MODULUS

# NOTE: For a real application, download 'trusted_setup.txt' from
# https://github.com/ethereum/c-kzg-4844/blob/main/trusted_setup.txt
# and set the KZG_TRUSTED_SETUP_PATH environment variable or pass the path directly.

# Create a dummy trusted_setup.txt for demonstration if not found
trusted_setup_path = Path(os.environ.get('KZG_TRUSTED_SETUP_PATH', ''))
if not trusted_setup_path.exists():
    print("WARNING: 'KZG_TRUSTED_SETUP_PATH' not set or file not found. Skipping quickstart.")
    print("Please download trusted_setup.txt from the c-kzg-4844 GitHub repository.")
    # For a purely runnable quickstart, one might create a mock setup, but
    # it won't be functionally correct for actual proofs.
    # As instructed, ensuring it reaches auth check: this example is more about file path.
else:
    print(f"Loading trusted setup from: {trusted_setup_path}")
    setup = load_trusted_setup(str(trusted_setup_path))

    FIELD_ELEMENTS_PER_BLOB = 4096
    BYTES_PER_FIELD_ELEMENT = 32

    def random_field_element() -> bytes:
        # Generate a random 31-byte sequence and prepend with a zero byte
        # to ensure it's within the field element range (0 to BLS_MODULUS-1).
        # The highest byte is zeroed to effectively cap at 31 bytes as per spec.
        return b'\x00' + os.urandom(BYTES_PER_FIELD_ELEMENT - 1)

    def random_blob() -> bytes:
        return b''.join(random_field_element() for _ in range(FIELD_ELEMENTS_PER_BLOB))

    blob = random_blob()
    print(f"Generated a random blob of size {len(blob)} bytes.")

    commitment = blob_to_kzg_commitment(blob, setup)
    print(f"Generated KZG Commitment: {commitment.hex()}")

    # Example of a simple field element for other operations (if needed)
    # z_bytes = random_field_element()
    # y_bytes, proof_bytes = compute_kzg_proof(blob, z_bytes, setup)
    # print(f"Computed KZG Proof: {proof_bytes.hex()}")