Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

01 — Overview

Crate: kinetic-vdf (Folder: vdfrs) Stage: 5 of 10 Reading time: ~4 minutes Depends on: kinetic-core, kinetic-types

What Is This?

The kinetic-vdf crate is the primary Verifiable Delay Function (VDF) wrapper for the Kinetic network. It acts as the bridge between Kinetic’s pure-Rust architecture and the optimized C++ chiavdf library.

Why Kinetic Needs This

A VDF is a cryptographic function that takes a predictable, sequential amount of time to compute (like solving a puzzle on a single CPU core) but can be verified almost instantly. Kinetic uses VDFs to enforce time-locked grace periods on .kin domain registrations and transfers. This forces an attacker to spend significant time (e.g., 30 days of CPU time) before claiming a name, neutralizing domain sniping and hostile takeovers.

How It Works

Important

Because VDF calculations are heavy, kinetic-vdf uses OS-level file locks to ensure that no two VDF computations can ever run simultaneously on the same machine. This prevents CPU starvation, which would otherwise crash the entire P2P node daemon. It also houses the critical “Differential Fuzzer” — a test suite that ensures the C++ implementation agrees with Kinetic’s pure-Rust verifier (kyn-vdf).

Key Pieces (Topic File Breakdown)

This crate is composed of 725 total lines of code, broken down into the following topics:

  1. 02_engine.md — Covers ChiaVdfEngine, the core FFI wrapper, and the OS-level file locking defense mechanisms.
  2. 03_tests.md — Covers the Differential Cryptography test suite. Explains how bitwise XORs and hardcoded byte anchors protect the network from accidental forks.
  3. 04_binaries.md — Covers benchmark.rs and prove_timing.rs, the CLI tools used to calibrate node difficulty based on actual CPU hardware speeds.

How This Connects to the Rest of Kinetic

  • CROSS-CRATE: Implements the VdfEngine trait defined in kinetic-core.
  • FORWARD DEPENDENCY: The transaction mempool and consensus engine (kinetic-daemon) will invoke this engine whenever they need to construct or validate a time-locked registration.
  • FORWARD DEPENDENCY: The test suite in this crate continuously cross-checks itself against the kyn-vdf crate (Stage 6).

Quick Reference

  • Total Lines: 725
  • Underlying Engine: C++ chiavdf (via FFI bindings)
  • DoS Protection: Single OS-level fs2 lock.
  • Max Iterations Bound: 400 Billion.

Open Questions / Things to Revisit

Warning

  • Mobile/Web Fallbacks: The engine currently hard-errors with UnsupportedPlatform on Android and WASM because the C++ bindings can’t compile there. If Kinetic ever requires mobile nodes to generate proofs, a pure-Rust prover will be needed. (Currently, mobile nodes can only verify proofs using kyn-vdf).