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

Crate: kinetic-core

Stage: 7

Reading Time: 120 mins

Depends On: kinetic-types, kinetic-vdf, kinetic-storage, kinetic-network

What Is This?

While kinetic-types defines the data structures and kinetic-network handles peer-to-peer gossip, kinetic-core contains the business logic and consensus rules. It defines what makes a name valid, how governance proposals are executed, how cryptographic random beacons are fetched, and what happens when the network encounters an error.

The kinetic-core crate sits squarely in the middle of the stack. It orchestrates the flow of data between the networking layer and the storage engine.

Key Pieces

  1. Types (src/types/): Defines the internal representations of names, identities, DNS zones, and infrastructure constants.
  2. Errors (src/error/): An exhaustive taxonomy of every single failure mode across the network, mapped to stable, RFC-7807 compliant API codes (e.g. KIN-REG-001).
  3. Governance (src/governance/): The on-chain logic that determines how the network upgrades itself, handles proposals, and counts votes based on whether it is running as a SovereignEngine or a PermissionlessEngine.
  4. Drand (src/drand.rs): Connects to the League of Entropy to fetch unbiasable, distributed randomness beacons which act as the cryptographic seed for all VDF computations.
  5. Config (src/config.rs): Handles loading and parsing the node operator’s TOML configurations safely.
  6. Consensus Math (src/consensus_math.rs): Calculates the dynamic difficulty retargeting curves for the VDFs to prevent name squatting and Sybil attacks.

Why Kinetic Needs This

Without kinetic-core, the Kinetic network would just be a generic Kademlia DHT passing random data around. kinetic-core injects the specific rules of the protocol:

  • A .kin name must only contain lowercase alphanumeric characters.
  • A VDF must be computed for a specific number of iterations based on the name length.

Important

Only the offline Root key can execute a GovernanceAction::EmergencyHalt governance proposal in Sovereign mode (council signatures are explicitly ignored).

By abstracting this into a distinct core crate, Kinetic cleanly separates the rigid consensus rules from the TCP connections and HTTP servers.

How to Read This Stage

Due to the sheer size of kinetic-core (over 6,000 lines of source code), we have broken this down into 18 highly specific, dense files.

Begin with the Types to understand the shapes of the data. Move to the Errors to understand how the system fails safely. Then, dive into the Governance and Drand modules to see the state machine in action. Finally, explore the Config, Traits, and Build sections for deep-level systems architecture.