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: 5 - Core Types & Network Primitives

Reading Time: ~20 minutes

Depends On: kinetic-types, kinetic-verify

What Is This?

In the Kinetic Network, the boundary between raw cryptographic consensus and user-facing features is mediated by core network primitives. This document explores the miscellaneous, yet vital, types located within the kinetic-core/src/types directory. We are specifically looking at the implementations and rules defined in clock.rs, infrastructure.rs, vdf.rs, name_record.rs, and the overarching mod.rs file.

These files do not represent a single monolithic subsystem like the DNS resolver or the identity layer. Instead, they provide the essential structural “glue” that binds the decentralized network together. They handle the translation of absolute machine consensus time into human-readable network time formats. They safeguard the critical routing infrastructure of the network from hostile takeovers and domain squatters. They enforce strict memory bounds on incoming cryptographic proofs to prevent denial-of-service attacks. And they define the mathematical rules for distributing data securely across the distributed hash table (DHT). Understanding these primitives is absolutely essential because they are injected into nearly every other component of the Kinetic architecture, from the mining pool loop to the frontend RPC endpoints.

Why Kinetic Needs This

Standard blockchains rely on relatively simple primitives: Unix timestamps for block times, basic ECDSA signatures for transactions, and flat state structures. Kinetic’s architecture is radically different. Because it is a decentralized, quantum-resistant naming system driven by Verifiable Delay Functions (VDFs) and synchronized by an external randomness beacon (Drand), standard primitives are entirely insufficient.

The Timekeeping Problem: In a distributed, permissionless system, relying on local machine clocks leads to clock drift and consensus failures. Malicious actors manipulating their local time causes nodes to disagree on when events occurred, leading to network forks. Kinetic solves this by tying all time strictly to the emissions of the Drand randomness beacon. Every time Drand emits a pulse (every 3 seconds), the network advances by one tick, known as a “Kyn”. However, a raw integer counter of Kyns is completely unreadable to end users. A governance proposal stating “Voting ends at Kyn 1,532,900” is incomprehensible. We need a deterministic system to translate raw machine time into a predictable, branded hierarchy (known as The Crystal Lexicon) so that frontends, block explorers, and users have a shared, intuitive understanding of network time.

The Infrastructure Security Problem: Kinetic is an open, permissionless system; anyone can compute a VDF to claim an available name. But what happens if a malicious actor claims the domain seed.kin or explorer.kin? The seed domain is hardcoded into new node software to bootstrap their initial connection to the network. If an attacker hijacked it, they could execute a massive eclipse attack, isolating new nodes into a fake, shadow network. We require absolute, structural protection for these category 2 reserved names baked directly into the protocol’s validation logic.

The Cryptographic Payload Size Problem: Kinetic utilizes ML-DSA-65, a lattice-based post-quantum cryptographic signature scheme. Lattice cryptography produces enormous keys and signatures. An ML-DSA-65 public key is 1,952 bytes, and the signature is 4,627 bytes. Contrast this with a traditional Ed25519 keypair which is 32 bytes and 64 bytes respectively. If the network blindly accepted and attempted to deserialize any payload submitted to it, an attacker could flood nodes with large invalid payloads. We need strict validation traits that enforce length limits before any cryptographic processing begins.

The Storage Redundancy Problem: When a user claims a name, that record is not stored on a central server; it is broadcast into the Kademlia DHT. Nodes in a peer-to-peer network constantly churn—they go offline, lose internet connection, or crash. If a name record is stored on only one node, the domain goes dark the moment that node restarts. We need a mathematically deterministic way to derive multiple storage locations (redundancy) across the network, ensuring that no matter which nodes drop off, the domain remains resolvable to the rest of the world.

How It Works

1. The Clock and Branded Time (clock.rs)

At the core of the network’s timekeeping is the concept of the Drand beacon. The network defines a Genesis Kyn, which represents the specific Drand round when the Kinetic network officially launched and generated its genesis state. All time calculations across the entire ecosystem are relative to this single genesis point.

-> See: kinetic-core/src/types/clock.rs — Lines 1 to 15

The time units are structured mathematically to map perfectly to standard Earth time while maintaining the precise 3-second heartbeat of the consensus engine:

  • 1 Kyn = The atomic unit of time. Exactly 3 seconds.
  • 1 Facet = 1,200 Kyns. Because 1,200 * 3 = 3,600 seconds, this equals exactly 1 Hour.
  • 1 Prism = 28,800 Kyns. Because 28,800 * 3 = 86,400 seconds, this equals exactly 1 Day.
  • 1 Matrix = 7 Prisms. This equals exactly 1 Week.
  • 1 Lattice = 30 Prisms. This equals exactly 1 Month (standardized to 30 days for simplicity in smart contracts).
  • 1 Apex = 365 Prisms. This equals exactly 1 Year.

-> See: kinetic-core/src/types/clock.rs — Lines 47 to 60

When translating raw machine time to user time, the function KineticTime::from_kyn(target_kyn, genesis) subtracts the genesis Kyn from the target_kyn to determine the total_kyns elapsed since the network launched. It then uses modulo arithmetic and integer division to break this vast number down into its constituent parts. For instance, if 31,245 total Kyns have elapsed since genesis:

  • 31,245 / 28,800 = 1 Prism.
  • The remainder is 2,445 Kyns.
  • 2,445 / 1,200 = 2 Facets.
  • The remainder is 45 Kyns. The result is precisely Prism 1, Facet 2, Kyn 45. This ensures that every explorer and frontend renders time exactly the same way without relying on external APIs.

2. Safeguarding the Core Network (infrastructure.rs)

The Kinetic network differentiates heavily between standard user-owned domains and critical infrastructure that the protocol relies on to function.

-> See: kinetic-core/src/types/infrastructure.rs — Lines 22 to 24

The INFRASTRUCTURE_NAMES list statically defines domains like seed, node, docs, dao, explorer, status, api, blog, and rpc. These are classified as Category 2 reservations. (Note that Category 1 reservations are standard ICANN testing domains like localhost or test, which are handled by a different validation rule).

-> See: kinetic-core/src/types/infrastructure.rs — Lines 34 to 43

The is_infrastructure_name function acts as the primary protocol gatekeeper. When a raw domain string is passed in, it first calls normalize_name to strip out erratic capitalization and whitespace (for example, normalizing “ SEED.kin “ to “seed.kin”). It then extracts the apex label (the root name without the TLD). If this label matches anything in the reserved array, the function returns true. This function is executed at the very edge of the RPC server and the mining pool. If a user attempts to mine an infrastructure name, the process halts immediately and returns a NamesError::InfrastructureName before any CPU cycles are wasted on VDF verification.

-> See: kinetic-core/src/types/infrastructure.rs — Lines 45 to 60

Furthermore, standard domains on the Kinetic network are subject to “thermodynamic pruning”. If a user abandons a domain, they stop broadcasting their cryptographic heartbeat signals. After a certain period (STEAL_TARGET_ROUNDS), the domain’s temperature drops, and it becomes eligible for takeover by another user. However, infrastructure names must never drop off the network. The requires_heartbeat function hardcodes a permanent exemption for these names. Because is_infrastructure_name evaluates to true, requires_heartbeat returns false, completely removing these vital names from the garbage collection and pruning cycles.

3. Validation of Verifiable Delay Function Payloads (vdf.rs)

In order to claim a name, a miner must submit a Reveal payload containing their VDF proof and the necessary cryptographic signatures proving ownership of the public key.

-> See: kinetic-core/src/types/vdf.rs — Lines 26 to 74

The RevealExt trait implements the validate method. This method serves as a rigid, unforgiving series of fail-fast checks designed to protect the node from malicious data. First, it explicitly checks that self.protocol_version == 1. This allows the network to seamlessly upgrade payload structures in the future without breaking older clients or creating consensus ambiguities. Second, it validates the requested name itself, ensuring it strictly adheres to valid Letter-Digit-Hyphen (LDH) rules. Third, it checks the payload size against MAX_PAYLOAD_SIZE. Finally, it validates the structural lengths of the cryptography arrays. ML-DSA-65 requires exactly 1952 bytes for a public key and 4627 bytes for a signature. The Drand signature requires exactly 192 bytes. The VDF proof must not exceed 2048 bytes. If an attacker submits a payload where the signature is off by one byte, validation fails.

4. Distributed Hash Table Storage Derivation (name_record.rs)

Once a domain is successfully claimed, its DNS and routing records must be stored in the Kademlia DHT.

-> See: kinetic-core/src/types/name_record.rs — Lines 14 to 16

The protocol mandates an M_REDUNDANCY constant set to 32. This means that every single domain record is duplicated across 32 distinct, geographically dispersed storage nodes. Given the typical churn rates of peer-to-peer networks, an M-value of 32 statistically guarantees that the domain remains highly available and resolvable even if 90% of the network temporarily partitions or goes offline.

-> See: kinetic-core/src/types/name_record.rs — Lines 24 to 39

The derive_storage_keys function is responsible for deterministically calculating these 32 locations. It loops from index 0 up to 31. For each iteration, it concatenates the raw bytes of the domain name, the current loop index integer, and the KINETIC_NETWORK_ID. It then hashes this combined, salted byte array using SHA-256. The resulting 32 hashes represent the exact topological locations in the DHT ring where the data must be placed. The inclusion of the network ID (for example, testnet-alpha versus mainnet-beta) is absolutely critical. Without this salt, a node running on a testnet might inadvertently overwrite or conflict with a mainnet record if they happen to connect to the same bootstrap peer, as both networks would otherwise derive the exact same DHT keys for the domain saif.kin.

5. Module Aggregation (mod.rs)

The mod.rs file acts as the facade for all these types.

-> See: kinetic-core/src/types/mod.rs — Lines 1 to 30

It exports clock, dns, name_record, identity, infrastructure, names, and vdf. -> See RUST_CONCEPTS.md for an explanation of pub use.

Key Pieces

KineticTime

  • What it does: Represents a specific, exact point in time on the Kinetic network, dynamically broken down into Prisms (Days), Facets (Hours), and Kyns (3-second ticks).
  • File & Line: Re-exported from kinetic-types in clock.rs:15. (Logic is defined deeply within kinetic-types).
  • Why it matters: It bridges the architectural gap between raw machine consensus (meaningless Drand rounds) and human-readable time, allowing user interfaces and developers to display branded Kinetic time reliably.

INFRASTRUCTURE_NAMES

  • What it does: A static, immutable array of string slices defining the core network infrastructure names (seed, node, explorer, api, etc.).
  • File & Line: infrastructure.rs:22
  • Why it matters: It prevents the core mechanics of the network from being disrupted by aggressive domain squatters. These specific names are structurally protected at the protocol level and cannot be mined by conventional means.

is_infrastructure_name

  • What it does: Takes a raw string, passes it through the domain normalizer, extracts the apex portion, and strictly checks if it exists in the INFRASTRUCTURE_NAMES array.
  • File & Line: infrastructure.rs:34
  • Why it matters: Used heavily by the mining pool layer and the inbound RPC server to instantly reject any attempts to mine protected names before the system wastes any valuable compute cycles evaluating VDF proofs.

requires_heartbeat

  • What it does: Determines if a domain name is subject to the network’s thermodynamic pruning and expiration rules.
  • File & Line: infrastructure.rs:57
  • Why it matters: Explicitly exempts infrastructure names from needing constant thermodynamic upkeep, ensuring core services and bootstrap nodes never accidentally drop off the network due to missed heartbeats.

RevealExt::validate

  • What it does: A trait method implementation that exhaustively validates the structure, version, and byte-sizes of a VDF Reveal payload.
  • File & Line: vdf.rs:26
  • Why it matters: Acts as a strict memory firewall against malformed or maliciously oversized cryptographic payloads. Given the massive sizes of quantum-resistant ML-DSA-65 keys, this is crucial for preventing out-of-memory crashes on validators.

derive_storage_keys

  • What it does: Generates 32 distinct, mathematically deterministic DHT storage keys for a single domain name, incorporating the specific network ID to prevent cross-network state collisions.
  • File & Line: Re-exported in name_record.rs:14, tested and demonstrated via name_record.rs:24.
  • Why it matters: Ensures domain name resolution is highly resilient to localized node failure and churn, distributing the query and storage load evenly across the Kademlia DHT ring.

How This Connects to the Rest of Kinetic

FORWARD DEPENDENCY: kinetic-rpc The RPC layer will heavily utilize requires_heartbeat and is_infrastructure_name. When a frontend client queries the status of a domain or attempts to register a new commitment, the RPC server will use these functions to validate the business logic of the request before forwarding it to the mining pool or the DHT network. If an RPC call attempts to touch seed.kin, it will be blocked here.

FORWARD DEPENDENCY: kinetic-dht The peer-to-peer DHT networking crate relies entirely on derive_storage_keys. When it receives a request to put a domain record into the network, it will call this specific function to determine the 32 exact PeerId locations on the Kademlia ring where the data should be replicated. Without this, routing fails completely.

CROSS-CRATE: kinetic-verify The vdf.rs module is tightly coupled to kinetic-verify. It re-exports types like Commitment, Reveal, and VdfProof. While kinetic-verify handles the pure mathematical verification of the underlying cryptographic proof, kinetic-core wraps these types in network-specific business logic via traits like RevealExt, providing the contextual validation required for the Kinetic protocol.

EXTERNAL DEPENDENCY: Explorers and Frontends Any visual representation of the network will pull the KineticTime struct to render timestamps. When a block is minted or a domain expires, a UI won’t display “Expires at Unix Timestamp 1754029100”; it will render natively as “Expires at Prism 342, Facet 12”.

Quick Reference

  • 1 Kyn = Exactly 3 seconds (One Drand beacon tick).
  • Genesis Kyn = The exact Drand round at which the Kinetic network launched. All KineticTime is relative to this zero-point.
  • Infrastructure Names = seed, node, docs, dao, explorer, status, api, blog, rpc.
  • Heartbeat Exemption = Infrastructure names are mathematically exempt; they NEVER expire.
  • VDF Payload Limits = Protocol Version 1 only. ML-DSA pubkeys must be exactly 1952 bytes. Signatures exactly 4627 bytes.
  • M_REDUNDANCY = 32. Every single domain is stored 32 separate times on the DHT.
  • Network Isolation = DHT keys are permanently salted with KINETIC_NETWORK_ID to prevent testnet/mainnet data bleed.

Open Questions / Things to Revisit

  • Hardcoded Cryptographic Lengths: In vdf.rs, the expected lengths for pubkey (1952) and signature (4627) are statically hardcoded for ML-DSA-65. If the network ever needs to upgrade to ML-DSA-87 (due to future cryptographic advancements breaking ML-DSA-65), this validate function will need a protocol version bump and a complex branching logic path. This is a potential pain point for seamless future upgrades.
  • Infrastructure List Extensibility: Currently, INFRASTRUCTURE_NAMES is a hardcoded static array baked into the node binary. If the Kinetic Council ever votes to add a new infrastructure name (e.g., bridge or relay), a full node software update across the entire network is required. Should this list be governed by an on-chain or in-network configuration state rather than hardcoded in the rust binary?
  • Genesis Kyn Dependency: The time logic tests heavily rely on KINETIC_GENESIS_DRAND_KYN being pulled from constants. If a node’s configuration is slightly out of sync regarding the genesis round, its entire timekeeping perspective will be misaligned with the rest of the network, potentially causing it to reject valid blocks. We need to ensure genesis state is aggressively validated and checksummed upon node boot.
  • Redundancy Cost: Storing 32 copies of every domain record provides excellent availability, but as the network grows to millions of domains, the bandwidth and storage overhead of M=32 could be significant. We may need to actively monitor DHT performance at scale and consider lowering this constant or introducing dynamic redundancy based on a domain’s semantic value.