Chia Proof of Space (chiapos)

Common errors

• ModuleNotFoundError: No module named 'chiapos'

  cause The chiapos library is not installed or not accessible in the current Python environment.
  fix Run `pip install chiapos` to install the library.

• RuntimeError: Missing or invalid k size

  cause The K-size parameter (e.g., 32 for mainnet plots) passed to plotting or proving functions is outside the valid range or is not supported.
  fix Ensure the K-size is a valid integer (e.g., 32) as required by the specific chiapos function or Chia protocol version. Check function documentation for allowed ranges.

• TypeError: validate_proof() missing 1 required positional argument: 'challenge_hash'

  cause A required argument for a chiapos function (in this case, `challenge_hash` for `validate_proof`) was not provided or was provided with an incorrect keyword.
  fix Check the function signature and provide all necessary positional and keyword arguments. Refer to the library's `*.pyi` stubs or the `chia-blockchain` source for correct usage.

• Permission denied: '/path/to/plot.plot' or OSError: [Errno 13] Permission denied: '...

  cause The Python process does not have write permissions to the specified directory where a plot file is attempted to be created or read.
  fix Ensure the user running the Python script has appropriate read/write permissions for the target plotting directory or the existing plot file location. Use `chmod` or adjust directory permissions.

• error: command 'gcc' failed with exit status 1 (or similar compilation error during install)

  cause This error occurs during `pip install chiapos` when a pre-built wheel is not available, and the system lacks the necessary C++ compiler or CMake to build the package from source.
  fix Install C++ development tools (e.g., `sudo apt-get install build-essential cmake` on Linux, Xcode Command Line Tools on macOS, Visual Studio Build Tools on Windows) and then retry `pip install chiapos`.

Warnings

• gotcha chiapos is a C++ wrapper. If pre-built wheels are not available for your specific Python version, operating system, and architecture (e.g., ARM Macs, less common Linux distributions), pip will attempt to build from source. This requires a C++ compiler (like g++ or clang) and CMake to be installed on your system.
  Fix: Ensure you have C++ development tools (e.g., build-essential on Debian/Ubuntu, Xcode Command Line Tools on macOS, Visual Studio Build Tools on Windows) and CMake installed before attempting to `pip install chiapos` if wheels are unavailable.
• gotcha The `create_plot_disk` and `create_plot_ram` functions are extremely resource-intensive. Plotting requires significant CPU, RAM (e.g., 256 GiB for K=32 in RAM plots, ~4GiB for disk plots peak), and sustained high disk I/O for hours to days. Ensure your system meets the Chia Network's plotting specifications before attempting to generate plots.
  Fix: Consult the official Chia Network documentation for recommended hardware specifications for plotting. Start with small `k_size` values for testing on limited hardware.
• breaking Version 2.x introduced significant internal refactorings and updates to C++ dependencies (e.g., pybind11, cmake). While direct Python API changes are not explicitly documented in all cases, users upgrading from 1.x should test their code thoroughly as argument signatures or available functions might have changed.
  Fix: Review the latest official `chiapos` examples and the `chia-blockchain` repository's usage of `chiapos` for any potential API changes if upgrading from a 1.x version. Update your code to match the current 2.x API.

Install

• pip install chiapos Install chiapos

Imports

• DiskProver

  from chiapos import DiskProver

• Verifier

  from chiapos import Verifier

• create_plot_disk

  from chiapos import create_plot_disk

  A top-level function for creating plots on disk.

Quickstart

This quickstart demonstrates how to initialize the `Verifier` class and call its `validate_proof` method using placeholder data. Note that actual plotting and proof generation are resource-intensive operations and are not included in this simple example. The `DiskProver` class is used to interact with existing plot files for generating proofs.

import hashlib
from chiapos import Verifier
import os

# Note: Generating an actual plot and proof is extremely resource-intensive
# and time-consuming. This example uses placeholder values to demonstrate
# the Verifier API, not a successful real-world verification.

# 1. Initialize the Verifier
verifier = Verifier()

# 2. Prepare dummy data for verification
# In a real scenario, these would come from the blockchain or a prover
plot_id_hex = "0x" + hashlib.sha256(b"my_plot_id_seed").hexdigest()
challenge_hash_hex = "0x" + hashlib.sha256(b"my_challenge_seed").hexdigest()
proof_bytes = b'\x00' * 64 # A dummy 64-byte proof (actual proofs are complex)

# Convert hex strings to bytes as required by the Verifier
plot_id = bytes.fromhex(plot_id_hex[2:])
challenge_hash = bytes.fromhex(challenge_hash_hex[2:])

print(f"Using Plot ID: {plot_id.hex()}")
print(f"Using Challenge Hash: {challenge_hash.hex()}")

# 3. Attempt to validate a proof with dummy data
# This demonstrates the API call. With dummy data, it will likely return None
# or raise an error, which is expected.
try:
    # `k_size` typically 32 for mainnet plots
    quality_string = verifier.validate_proof(plot_id, 32, challenge_hash, proof_bytes)
    if quality_string:
        print(f"Proof validation returned quality: {quality_string.hex()}")
    else:
        print("Proof validation returned None (expected with dummy data).")
except Exception as e:
    print(f"Proof validation failed with an error (expected with dummy data): {e}")

print("\nFurther usage of DiskProver and create_plot_disk requires actual plot files and significant resources.")