Chia VDF

What this repository provides

chiavdf implements the Verifiable Delay Function used by Chia's timelord. It builds on Linux (x86_64 and arm64), macOS (Intel and Apple Silicon), and Windows (x64), and produces:

• vdf_client - the CPU software timelord client.
• vdf_bench - a CPU benchmark for estimating iterations per second.
• hw_vdf_client and hw_test - the Chia VDF ASIC client and board test.
• emu_hw_vdf_client and emu_hw_test - hardware-free emulators for CI and development.
• The chiavdf Python bindings used by chia-blockchain to validate proofs of time, plus optional chiavdfc shared/static libraries.

CI builds the CPU and ASIC binaries on all of those platforms. The ASIC emulator tests run without a board.

Install a published build

Release binaries are available through Homebrew, winget, and apt. These channels install the same binaries as the GitHub release archives.

macOS

Install through the Chia Homebrew tap:

brew install chia-network/chia/chiavdf

This installs vdf_client, vdf_bench, hw_vdf_client, hw_test, and the emulators. The bundled FTDI libraries are installed under libexec/chiavdf. Install the FTDI D2XX driver before using the ASIC tools with a board; see README_ASIC.md.

Windows

Install through winget:

winget install --id Chia.chiavdf --exact

The winget package is a machine-scope Inno Setup installer. It installs all six tools (vdf_client, vdf_bench, hw_vdf_client, hw_test, emu_hw_vdf_client, and emu_hw_test) under %ProgramFiles%\Chia\chiavdf\bin, adds that directory to the system PATH, and stages the FTDI CDM driver (ftdibus.inf and ftdiport.inf) with pnputil. One install therefore covers software timelords and ASIC hosts. The installer requires x64 Windows 10 version 2004 or newer and will show a UAC prompt. If you cannot elevate, use the portable chiavdf-<version>-windows-amd64.zip from a release instead. The shared FTDI driver is left installed when chiavdf is uninstalled. Open a new terminal after installation so the updated PATH is visible. See README_ASIC.md and assets/windows-installer.md.

Linux

Add the Chia apt repository and install chiavdf:

sudo apt-get update
sudo apt-get install ca-certificates curl gnupg
curl -sL https://repo.chia.net/FD39E6D3.pubkey.asc | sudo gpg --dearmor -o /usr/share/keyrings/chia.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/chia.gpg] https://repo.chia.net/chiavdf/debian/ stable main" | sudo tee /etc/apt/sources.list.d/chiavdf.list
sudo apt-get update
sudo apt-get install chiavdf

The package installs vdf_client, vdf_bench, hw_vdf_client, hw_test, and the emulators under /usr/bin, plus libft4222.so and the udev rule for the ASIC board.

The Python bindings are installed separately with pip install chiavdf; see Building the Python wheel.

Run a timelord

A timelord needs a synced Chia full node and one or more VDF clients connected to the timelord's port 8000. Choose the CPU or ASIC path below.

Software timelord (CPU)

Use vdf_client. The normal installation path is chia-blockchain's install-timelord.sh, which installs the chiavdf package and builds vdf_client from source. Then start the full node, timelord, and launcher:

chia start node timelord

The launcher starts the software vdf_client processes. For full node and timelord setup, see the Chia timelord install guide. To build and test the client directly from this repository, see Building Timelord and related binaries.

Hardware timelord (Chia VDF ASIC)

Use hw_vdf_client with a Chia VDF ASIC board. Hardware support is available on Linux x86_64 and arm64, macOS Intel and Apple Silicon, and Windows x64. chia-blockchain does not start the hardware client, so start the node and timelord without the software launcher, then start the client yourself:

chia start node timelord-only
hw_vdf_client 8000 3

See README_ASIC.md for board and FTDI requirements, packaged and source builds, --device-loc when using multiple boards, timelord allowlisting, service setup, and troubleshooting. emu_hw_vdf_client and emu_hw_test let you exercise the hardware paths without a board.

Building the Python wheel

The published chiavdf wheels contain the native verifier bindings that chia-blockchain uses to validate proofs of time. This lets a node install a prebuilt wheel instead of compiling the C++ library itself.

The Python bindings require Python 3.10 or newer. Building them requires CMake, a C++17 compiler, and GMP (MPIR on Windows). Building the timelord client and tests also requires Boost headers.

python3 -m venv venv
source venv/bin/activate

pip install wheel setuptools_scm pybind11
BUILD_VDF_CLIENT=N pip wheel .

BUILD_VDF_CLIENT=N builds only the Python extension. The next section builds the CPU timelord client and related binaries.

The Python wheel build uses GitHub Actions to build binary wheels for Linux (x86_64 and arm64), macOS (Intel and Apple Silicon), and Windows (x64), and publishes them, plus a source distribution, to PyPI. See .github/workflows/build.yml. CMake uses the installed pybind11 package when available and falls back to FetchContent to download pybind11. cibuildwheel manages the wheel builds. Install a published wheel with pip install chiavdf.

Building Timelord and related binaries

The same source tree also builds the CPU timelord client and benchmark on Linux, macOS, and Windows. vdf_client is the CPU process that computes the Proof of Time requested by the timelord. vdf_bench estimates iterations per second on a given CPU. Try ./vdf_bench square_asm 250000 on x86/x64 for the phased/asm pipeline. On non-x86 architectures, use ./vdf_bench square 250000 (NUDUPL).

Set CHIAVDF_LOG_AVX=1 to emit AVX feature detection logs during startup.

For the ASIC client, hw_vdf_client, see README_ASIC.md.

For direct CMake builds, the following options are available:

• BUILD_VDF_CLIENT - build vdf_client
• BUILD_VDF_BENCH - build vdf_bench
• BUILD_VDF_TESTS - build test binaries (1weso_test, 2weso_test, prover_test) and CTest/GoogleTest targets (for example vdf_client_session_test)
• BUILD_HW_TOOLS - build the ASIC timelord tools (hw_vdf_client, hw_test, emulators, and hw_proof_wait_test)
• ENABLE_GNU_ASM - enable GNU-style asm pipeline on x86/x64 (enabled by default)
• GENERATE_ASM_TRACKING_DATA - enable track_asm() instrumentation in generated asm (off by default to avoid hot-loop overhead)

Example:

cmake -S src -B build \
  -DBUILD_PYTHON=OFF \
  -DBUILD_CHIAVDFC=OFF \
  -DBUILD_VDF_CLIENT=ON \
  -DBUILD_VDF_BENCH=ON \
  -DBUILD_VDF_TESTS=ON
cmake --build build --target vdf_client vdf_bench 1weso_test 2weso_test prover_test vdf_client_session_test

For the ASIC tools, add -DBUILD_HW_TOOLS=ON and follow README_ASIC.md for FTDI libraries and the Windows clang-cl/Ninja setup used by CI.

The legacy setup.py + Makefile.vdf-client flow runs make for native binaries when either BUILD_VDF_CLIENT=Y (the default) or BUILD_VDF_BENCH=Y is set. Set both to N to skip native binaries. The Makefile's default target builds vdf_client, vdf_bench, and the integration test binaries; for selective builds, call make -f Makefile.vdf-client <target> directly.

For direct CMake builds, use -DBUILD_* flags instead.

AVX runtime flags:

• CHIAVDF_LOG_AVX=1: emit AVX detection logs at startup
• CHIA_DISABLE_AVX2=1: disable AVX2 path even when supported
• CHIA_FORCE_AVX2=1: force AVX2 path
• CHIA_DISABLE_AVX512_IFMA=1: disable AVX-512 IFMA path
• CHIA_ENABLE_AVX512_IFMA=1: enable AVX-512 IFMA path when CPUID support is present
• CHIA_FORCE_AVX512_IFMA=1: force AVX-512 IFMA path

The chia-blockchain install-timelord.sh script automates the software timelord installation and builds the vdf_client binary from the chiavdf package.

The following tests are available, depending on which type of timelord you are running:

• ./1weso_test for sanitizer_mode.
• ./2weso_test for a timelord that extends the chain with the slow algorithm.
• ./prover_test for a timelord that extends the chain with the fast algorithm.

Those tests simulate vdf_client and verify that the produced proofs are correct.

Note: ./prover_test defaults to a long soak/stress run. Set CHIAVDF_PROVER_TEST_FAST=1 to run a short, CI-friendly correctness check.

Regression tests for specific bugs use GoogleTest and run via CTest. Example:

cmake -S src -B build \
  -DBUILD_PYTHON=OFF \
  -DBUILD_CHIAVDFC=OFF \
  -DBUILD_VDF_CLIENT=OFF \
  -DBUILD_VDF_BENCH=OFF \
  -DBUILD_VDF_TESTS=ON \
  -DBUILD_HW_TOOLS=OFF
cmake --build build --target vdf_client_session_test
ctest --test-dir build --output-on-failure -R '^regression\.'

Blockchain proof corpus

verify_vdf_corpus is a standalone Unix tool that validates binary VDF proof corpora independently of a blockchain database. Supply one or more files on the command line; there is no default sample or environment-variable configuration. The existing ReferenceGoldenRegressionTest retains the arithmetic regression coverage.

Export more proofs with export-vdf-proofs in the chia_rs repository:

cargo run --release -p chia-tools --bin export-vdf-proofs -- \
  /path/to/blockchain.sqlite mainnet-proofs.bin

The tool opens the database read-only, includes orphan blocks, reports progress, and resolves partial-proof inputs using ancestor records. It refuses to overwrite an existing output file. If extraction fails, discard the partial output.

The file is a sequence of independently serialized Streamable records. There is no file header or record count. The Rust CorpusEntry layout is:

struct CorpusEntry {
    height: u32,
    input: ClassgroupElement,
    info: VDFInfo,
    proof: VDFProof,
}

Streamable integers are big-endian. The 100 raw bytes of input follow the four-byte height immediately. The discriminant size is a fixed 1024 bits in the verifier and is not stored in the corpus. Witness bytes have a u32 byte length prefix. VDFInfo contains the 32-byte challenge, u64 iteration count, and output element. VDFProof contains the u8 witness type, length-prefixed witness, and one-byte normalized flag. input and info.number_of_iterations are the resolved verifier arguments, including adjustments for partial proofs. The C++ reader does not reapply the normalized flag. Block hashes and proof field names are omitted; failures identify the file, height and record number.

Exports can be combined with cat mainnet-proofs.bin testnet11-proofs.bin testneta-proofs.bin > proofs.bin. The corpus omits version, network and proof field metadata. No compression is required.

Build and run from the chiavdf repository (GoogleTest is not required):

cmake -S src -B build -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_PYTHON=OFF -DBUILD_VDF_TESTS=OFF
cmake --build build --config Release --target verify_vdf_corpus -j 4
./build/verify_vdf_corpus mainnet-proofs.bin testnet11-proofs.bin testneta-proofs.bin
./build/verify_vdf_corpus --start-height 1000000 mainnet-proofs.bin

For multi-configuration generators such as Xcode, run the executable from build/Release/ instead.

Files are processed in argument order. Verification uses one worker per hardware thread reported by std::thread::hardware_concurrency() (with a fallback of one worker), maps each corpus file and parses records as workers need them. With --start-height, the verifier still scans every record because the corpus has no height index and sorting proofs by challenge can move heights out of order. It validates only proofs at or above the specified height. Decoded proof memory is bounded by the worker count. Progress is printed every 10,000 proofs, followed by per-file and overall totals. Failures include the filename, block height and record number. Empty, truncated, unreadable or malformed corpora cause a nonzero exit status. A malformed record stops that file, and the tool continues with subsequent files. Invalid proofs are reported while checking the remaining records. Exit status is 0 when every file passes, 1 on failure, or 2 if no files were supplied. Use --help for usage. The tool checks VDF validity, not block consensus.

Testing matrix

• Binary integration tests: 1weso_test, 2weso_test, prover_test; these simulate vdf_client and validate proof correctness.
• Regression tests: GoogleTest targets executed via CTest (for example vdf_client_session_test, typically filtered with ctest -R '^regression\.').
• Hardware tests: standalone binaries such as hw_test, emu_hw_test, and hw_proof_wait_test; build and run instructions are in README_ASIC.md.

Fuzzing

Fuzz targets live under rust_bindings/fuzz. The prove target includes an iteration cap to avoid out-of-memory conditions in CI. If you want deeper iteration coverage, raise the cap in rust_bindings/fuzz/fuzz_targets/prove.rs after validating memory usage and exec/s on your runner.

Contributing and workflow

Contributions are welcome. More details are available in chia-blockchain's CONTRIBUTING.md.

main is the default branch. Tagged releases are published to PyPI and consumed by chia-blockchain, so main can be ahead of the version chia-blockchain currently pins. Branch from main, open a pull request against main, and make sure the CI build and CodeQL analysis pass. Merging requires a completed review.

Historical background

The original VDF competition background, attribution, and implementation notes are in README_BACKGROUND_COMPETITION.md.