Metadata-Version: 2.4
Name: chikvdf
Version: 1.2.2
Summary: Chik vdf verification (wraps C++)
Home-page: https://github.com/Chik-Network/chikvdf
Author: Florin Chirica
Author-email: florin@chiknetwork.com
License: Apache-2.0
Requires-Python: >=3.11, <4
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-python
Dynamic: summary

# Chik VDF

![Build](https://github.com/Chik-Network/chikvdf/actions/workflows/build.yml/badge.svg)
![PyPI](https://img.shields.io/pypi/v/chikvdf?logo=pypi)
![PyPI - Format](https://img.shields.io/pypi/format/chikvdf?logo=pypi)
![GitHub](https://img.shields.io/github/license/Chik-Network/chikvdf?logo=Github)

[![CodeQL](https://github.com/Chik-Network/chikvdf/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/Chik-Network/chikvdf/actions/workflows/codeql-analysis.yml)

## What this repository provides

chikvdf implements the Verifiable Delay Function used by Chik'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 Chik VDF ASIC client and board test.
- `emu_hw_vdf_client` and `emu_hw_test` - hardware-free emulators for CI and
  development.
- The `chikvdf` Python bindings used by chik-blockchain to validate proofs of
  time, plus optional `chikvdfc` 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 [Chik Homebrew tap](https://github.com/Chik-Network/homebrew-chik):

```bash
brew install chik-network/chik/chikvdf
```

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

### Windows

Install through winget:

```powershell
winget install --id Chik.chikvdf --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%\Chik\chikvdf\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
`chikvdf-<version>-windows-amd64.zip` from a
[release](https://github.com/Chik-Network/chikvdf/releases) instead. The
shared FTDI driver is left installed when chikvdf is uninstalled. Open a new
terminal after installation so the updated `PATH` is visible. See
[README_ASIC.md](README_ASIC.md) and `assets/windows-installer.md`.

### Linux

Add the Chik apt repository and install `chikvdf`:

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

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 chikvdf`; see
[Building the Python wheel](#building-the-python-wheel).

## Run a timelord

A timelord needs a synced Chik 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 chik-blockchain's
[install-timelord.sh](https://github.com/Chik-Network/chik-blockchain/blob/main/install-timelord.sh),
which installs the chikvdf package and builds `vdf_client` from source. Then
start the full node, timelord, and launcher:

```bash
chik start node timelord
```

The launcher starts the software `vdf_client` processes. For full node and
timelord setup, see the
[Chik timelord install guide](https://docs.chiknetwork.com/reference-client/install-and-setup/timelord-install/).
To build and test the client directly from this repository, see
[Building Timelord and related binaries](https://github.com/Chik-Network/chikvdf#building-timelord-and-related-binaries).

### Hardware timelord (Chik VDF ASIC)

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

```bash
chik start node timelord-only
hw_vdf_client 8000 3
```

See
[README_ASIC.md](https://github.com/Chik-Network/chikvdf/blob/main/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 `chikvdf` wheels contain the native verifier bindings that
chik-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.11 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.

```bash
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](https://cmake.org/cmake/help/latest/module/FetchContent.html)
to download [pybind11](https://github.com/pybind/pybind11).
[cibuildwheel](https://github.com/joerick/cibuildwheel) manages the wheel
builds. Install a published wheel with `pip install chikvdf`.

## 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 `CHIKVDF_LOG_AVX=1` to emit AVX feature detection logs during startup.

For the ASIC client, `hw_vdf_client`, see
[README_ASIC.md](https://github.com/Chik-Network/chikvdf/blob/main/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:

```bash
cmake -S src -B build \
  -DBUILD_PYTHON=OFF \
  -DBUILD_CHIKVDFC=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](https://github.com/Chik-Network/chikvdf/blob/main/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:

- `CHIKVDF_LOG_AVX=1`: emit AVX detection logs at startup
- `CHIK_DISABLE_AVX2=1`: disable AVX2 path even when supported
- `CHIK_FORCE_AVX2=1`: force AVX2 path
- `CHIK_DISABLE_AVX512_IFMA=1`: disable AVX-512 IFMA path
- `CHIK_ENABLE_AVX512_IFMA=1`: enable AVX-512 IFMA path when CPUID support is present
- `CHIK_FORCE_AVX512_IFMA=1`: force AVX-512 IFMA path

The chik-blockchain
[install-timelord.sh](https://github.com/Chik-Network/chik-blockchain/blob/main/install-timelord.sh)
script automates the software timelord installation and builds the
`vdf_client` binary from the chikvdf 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
`CHIKVDF_PROVER_TEST_FAST=1` to run a short, CI-friendly correctness check.

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

```bash
cmake -S src -B build \
  -DBUILD_PYTHON=OFF \
  -DBUILD_CHIKVDFC=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\.'
```

### 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 chik-blockchain's
[CONTRIBUTING.md](https://github.com/Chik-Network/chik-blockchain/blob/main/CONTRIBUTING.md).

`main` is the default branch. Tagged releases are published to PyPI and
consumed by chik-blockchain, so `main` can be ahead of the version
chik-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](https://github.com/Chik-Network/chikvdf/blob/main/README_BACKGROUND_COMPETITION.md).
