Kinetic Architecture Documentation

Welcome to the internal documentation for the Kinetic Network.

Use the sidebar to navigate the different modules and crates of the Kinetic codebase. Each document breaks down the internal architecture, reasoning, and Rust implementations step-by-step.

Kinetic: Rust Concepts Glossary

This document serves as a centralized glossary for all the high-level, advanced Rust concepts used extensively throughout the entire Kinetic monorepo (core, network, daemon, node, host, cli, vdf, dns, pac, etc.).

By centralizing these concepts, we avoid documenting the same pattern redundantly across every crate.

1. Concurrency, Async, and Threading

tokio::spawn and tokio::task::spawn_blocking

#![allow(unused)]
fn main() {
// Launch async task
tokio::spawn(async move { handle_request().await; });

// Offload heavy CPU math
tokio::task::spawn_blocking(move || { compute_vdf() }).await;
}

• What it is: tokio::spawn launches an asynchronous background task on the Tokio runtime, allowing highly concurrent I/O operations (like handling hundreds of HTTP requests). spawn_blocking offloads heavy, CPU-bound computations (like VDF generation, PoW hashing, or disk I/O) to a dedicated OS thread pool.
• How Kinetic uses it: The kinetic-daemon and kinetic-cli use spawn_blocking extensively for cryptographic tasks. If this math were run on the normal async thread, it would starve the executor and drop incoming network packets.
• WASM Equivalent: In kinetic-wasm, standard Tokio threading is unsupported. wasm_bindgen_futures::spawn_local is used instead to bridge Rust’s async futures with the browser’s native JavaScript microtask queue.

Note

Standard Tokio threading is unsupported in WebAssembly. Always use wasm_bindgen_futures::spawn_local for WASM targets.

std::sync::Mutex vs tokio::sync::Mutex vs RwLock<T>

• What they are: Synchronization primitives that safely lock data for multi-threaded access.
• How Kinetic uses them:
  • std::sync::Mutex is used for ultra-fast, synchronous updates where the lock is never held across an .await point.
  • tokio::sync::Mutex safely yields execution back to the runtime while waiting, which is required if the lock is held across network calls.
  • RwLock (Read-Write Lock) allows infinite simultaneous readers but only one writer. It is used heavily in kinetic-host and kinetic-dns (e.g., caching upstream resolvers) because reads happen thousands of times per second, but writes (config reloads) are rare.

Asynchronous Channels (mpsc, oneshot, broadcast, watch)

• What they are: Thread-safe queues for passing messages between tasks.
• How Kinetic uses them:
  • mpsc (Multi-Producer, Single-Consumer): Used to funnel API commands from multiple HTTP threads into the single-threaded Libp2p swarm event loop.
  • oneshot: Bundled inside the mpsc commands to route the exact network response back to the specific foreground API thread that requested it.
  • broadcast: Fans out identical messages (like Gossipsub events) to multiple consumers, such as live SSE streams.
  • watch: Retains only the latest value (like the current_drand_kyn epoch), dropping outdated state instantly so observers never process stale data.

tokio::select! and tokio::join!

#![allow(unused)]
fn main() {
tokio::select! {
    _ = sigterm.recv() => { println!("Shutting down"); }
    packet = socket.recv() => { process(packet); }
}
}

• What they are: Macros for managing multiple asynchronous futures concurrently.
• How Kinetic uses them: select! races multiple branches and executes the first one that completes (e.g., racing incoming network packets against a graceful shutdown SIGTERM signal). join! waits for all branches to finish concurrently.

tokio::sync::Semaphore

• What it is: Limits how many tasks can access a resource simultaneously.
• How Kinetic uses it: The try_acquire_owned() method acts as a non-blocking rate limiter for gossip messages and VDF evaluations, instantly dropping packets during DDoS attacks instead of halting the executor or exhausting RAM.

std::sync::atomic::AtomicU64

• What it is: A variable that can be safely mutated across threads at the hardware level without a Mutex.
• How Kinetic uses it: Used in kinetic-storage to cleanly track database corruption fallback counters without risking deadlocks during panic handling.

2. Memory, Pointers, and Data Types

Box<T> and Arc<dyn Trait> (Dynamic Dispatch)

• What they are: Heap allocations. Box owns the data. Arc (Atomically Reference Counted) safely shares read-only ownership across multiple threads. dyn Trait hides the concrete type behind a standard interface.
• How Kinetic uses them: NameRecord::Standard uses Box<Reveal> to prevent the massive Reveal struct from bloating the entire enum’s memory footprint. Arc<dyn VdfEngine> allows the daemon to hot-swap cryptographic engines at runtime without altering the networking code.

&[u8] vs Vec<u8> vs bytes::Bytes

• What they are: Different ways to interact with byte arrays in memory.
• How Kinetic uses them: Kinetic returns &[u8] for cryptographic validations (like checking signatures) to avoid memory allocation overhead. It uses bytes::Bytes in the HTTP proxy to pass multi-megabyte video streams through the pipeline by just incrementing a tiny pointer counter, preventing massive RAM duplication.

Cow<'_, T> (Clone-On-Write)

• What it is: A smart pointer that holds either borrowed references (fast) or owned data (slow).
• How Kinetic uses it: In kinetic-network, the record store returns a cheap reference for reads, but dynamically allocates a copy only if the data needs mutation.

Option<T> and Result<T, E>

• What they are: Rust’s zero-cost replacements for null and Exceptions.
• How Kinetic uses them: Option forces the compiler to ensure code explicitly handles missing data (like an optional manifest signature). Result safely propagates errors. E.g., Result<Option<T>, E> rigorously maps three states: invalid, missing, or present.

Specialized Collections (BTreeMap, LruCache, HashMap)

• What they are: Highly optimized data structures.
• How Kinetic uses them:
  • HashMap provides O(1) lookups for DNS zones.
  • BTreeMap keeps keys sorted, enabling blazing-fast scan_prefix operations for the WASM fallback database.
  • lru::LruCache ejects the Least Recently Used elements, preventing RAM exhaustion from malicious peers overflowing the banned peer list.

3. Macros and Code Generation

thiserror (#[error], #[from], #[source])

• What it is: An external macro that auto-generates error trait implementations.
• How Kinetic uses it: Removes hundreds of lines of boilerplate. #[from] allows automatic conversion of system errors (like std::io::Error) into unified KineticError variants via the ? operator.

serde (#[serde(untagged)], #[serde(tag = ...)], #[serde(other)])

• What it is: Directives for parsing JSON and binary structures.
• How Kinetic uses it:
  • untagged allows seamless wire transmission of different payload variants without bloated "type" JSON keys.
  • other safely catches unrecognized DNS records sent by future protocol versions without crashing the parser.

#[cfg(...)] and #![no_std] (Conditional Compilation)

#![allow(unused)]
fn main() {
#[cfg(not(target_arch = "wasm32"))]
pub mod native_db;

#[cfg(target_arch = "wasm32")]
pub mod wasm_db;
}

• What it is: Tells the compiler to include or exclude code based on the target environment.
• How Kinetic uses it: #[cfg(not(target_arch = "wasm32"))] strips out native Sled database I/O when compiling for browsers. #![no_std] ensures the kyn-vdf core cryptographic math can compile without an operating system.

Important

#![no_std] is an absolute requirement for compiling the pure-Rust cryptographic math into secure WebAssembly environments.

proptest!

• What it is: A property-based fuzzer.
• How Kinetic uses it: Generates thousands of randomized, hostile byte arrays to test the DNS parser in kinetic-dns, ensuring it cannot panic regardless of malicious inputs.

4. Systems, Safety, and Advanced Syntax

Filesystem Locks & Atomic Writes

• What it is: Safe interaction with the host OS.
• How Kinetic uses it: fs2 uses OS-level flock to ensure only one VDF process runs per machine, preventing cross-daemon CPU saturation. When writing config files (like PAC scripts), Kinetic writes to a .tmp file and calls std::fs::rename() to atomically replace the old file, guaranteeing zero corruption if power is lost mid-write.

Constant-Time Equality (subtle::ConstantTimeEq)

• What it is: A mathematical comparison that always takes the exact same number of CPU cycles.
• How Kinetic uses it: Prevents cryptographic timing attacks on the API. Without it, an attacker could guess an API Bearer token character-by-character by measuring microsecond variations in how fast the server rejects the request.

Warning

Never use standard == string comparisons for API tokens. Always use ConstantTimeEq to prevent microsecond timing attacks.

std::process::Command (Process Delegation)

• What it is: Shells out to execute external OS processes.
• How Kinetic uses it: kinetic-cli acts as a unified delegator. Instead of running networking code directly, it executes commands like sudo kinetic-dns start and streams the output directly to the user’s terminal.

Extension Trait Pattern

• What it is: Bypasses Rust’s “Orphan Rule” (which forbids implementing standard methods on external types).
• How Kinetic uses it: Kinetic creates custom traits (like DnsZoneExt) to bolt heavy validation logic (parse_payload) onto lightweight structs provided by third-party libraries (like hickory-dns).

Differential Fuzzing in Cryptography

• What it is: Testing two entirely different implementations against each other instead of static answers.
• How Kinetic uses it: kinetic-vdf tests the pure Rust verification logic (kyn-vdf) against the C++ FFI library (chiavdf) with millions of random inputs, ensuring absolute mathematical parity to prevent network forks.

PhantomData and the Newtype Pattern

• What it is: Zero-overhead type system strictness.
• How Kinetic uses it: KineticDid wraps a String privately. The only way to instantiate it is via a constructor that validates the syntax. Thus, any function accepting a KineticDid knows with 100% certainty the DID is valid without ever re-running validation checks.

01 — Overview (kinetic-types)

Crate: kinetic-types Stage: 1 of 10 Reading time: ~5 minutes Depends on: None Source files: All files in kinetic-types/src/

What Is This?

This crate is the zero-dependency structural foundation of the Kinetic network. It defines the exact shapes of the data (structs, enums) that flow through the network. It does not implement heavy logic like consensus, networking, or cryptographic math — it simply defines the contracts that all those other systems must agree on.

Why Kinetic Needs This

Important

Without a centralized, zero-dependency type hub, you end up with “dependency hell.” If the browser extension, the node daemon, and the offline signing tools all defined their own version of a NameRecord, they would eventually drift out of sync. By having kinetic-types stand alone with no dependencies on heavy networking libraries, light clients (like WASM frontends or air-gapped signers) can import these exact schemas without bloating their binaries.

How It Works

This crate acts as a dictionary. When a node receives bytes over the wire, it uses the definitions in this crate to decode those bytes into meaningful Rust objects.

• It uses serde for JSON and binary serialization.
• It defines exact byte-layouts for signatures to prevent ambiguity.
• It organizes types by their domain: time (clock), identity (KIDs), names, VDFs, and governance.

Key Pieces

This documentation is split into 7 deep-dive topic files:

1. 02_error_and_severity.md: The foundational error taxonomy (Severity) used to categorize failures across the network.
2. 03_identity.md: AuthorizedKid and AuthorizedManifest — how decentralized identities and capabilities are cryptographically bound to .kin names.
3. 04_clock.md: KineticTime — the branded time hierarchy (Kyns, Facets, Prisms, etc.) built on network beacons.
4. 05_vdf_types.md: The structures backing the two-phase commit-and-reveal name registration protocol and VDF proofs.
5. 06_governance_types.md: Opcodes and structures for root authority actions like halting the network or granting premium names.
6. 07_name_record.md: The ultimate source of truth for name ownership, DHT redundancy, and heartbeat liveness proofs.
7. 08_dns_proxy_cdn.md: Decentralized DNS schemas, IPC proxy payloads for the browser extension, and CDN caching types.

How This Connects to the Rest of Kinetic

FORWARD DEPENDENCY: Literally every other crate in the Kinetic workspace imports kinetic-types.

• kinetic-network uses it to parse incoming P2P messages.
• kinetic-verify uses it to extract the public keys and signatures from records to validate them.
• kyn-vdf and vdfrs provide the mathematical engines that populate the VdfProof structures defined here.

Quick Reference

• Crate purpose: Data schemas and serialization.
• Dependencies: None (zero internal workspace dependencies).
• Primary tool: serde (Serialization/Deserialization).
• Design pattern: Strict separation of data (here) from behavior (elsewhere).

Open Questions / Things to Revisit

Note

• Are there any types currently in kinetic-types that accidentally pull in heavy dependencies and should be refactored out? (e.g., Does importing thiserror or ml_dsa defeat the zero-dependency goal, or are they lightweight enough?)
• Should the IPC proxy types live here, or belong in a dedicated kinetic-ipc crate to keep this crate strictly focused on network consensus types?

kinetic-types — Stage 1, Topic 02: Error Taxonomy & Crate Entry Point

Crate: kinetic-types Stage: 1 of N Estimated reading time: 12 minutes Depends on: Topic 01 (KineticTime / clock subsystem) — helpful but not required

What Is This?

error.rs defines Severity — a four-level enum that every domain error type in Kinetic uses to classify how bad a problem is. It is the single source of truth for log filtering, UI alert levels, and automated node decision-making across the entire workspace.

lib.rs is the crate’s front door. It declares every subsystem module — clock, dns, name_record, governance, identity, proxy, cdn, vdf — and documents what the crate is for. Together these two files establish the crate’s contract with the rest of Kinetic.

-> See: kinetic-types/src/error.rs — Lines 1 to 34 -> See: kinetic-types/src/lib.rs — Lines 1 to 29

Why Kinetic Needs This

Kinetic is a distributed network. At any given moment a node is processing DNS lookups, verifying VDF proofs, handling governance votes, streaming CDN chunks, and maintaining heartbeat liveness proofs — all concurrently, all of which can fail in different ways.

Without a shared severity taxonomy, every subsystem would invent its own language for “this is bad.” One module might log a string “fatal”, another might return an integer 2, a third might panic. When a node’s supervisor loop — the code that decides whether to retry an operation, send an alert, or halt cleanly — reads these results, it has no common vocabulary to reason with. It cannot distinguish a transient DNS cache miss (retry in 5s) from a cryptographic signature forgery (halt and alert the operator immediately).

Severity gives the whole network one answer to the question: how urgently does this need a response? Because it lives in kinetic-types — the zero-dependency type hub — every crate that imports kinetic-types gets access to it without pulling in consensus engines, networking stacks, or any heavy machinery.

lib.rs matters for a complementary reason: it is the declaration that kinetic-types exists as a coherent unit. Without it, Rust does not know that clock, dns, error, and the other modules belong to the same crate. Every use kinetic_types::error::Severity statement anywhere in the workspace resolves through the pub mod error; line in lib.rs.

How It Works

The Severity Ladder (error.rs Lines 13-22)

Severity is an enum with exactly four variants, ordered from least to most urgent:

Info — Something happened and it is fine. A DNS record was fetched from cache. A heartbeat arrived on schedule. No action is needed by the caller. Nodes log these at trace level and move on.

Warning — Something is degraded but not broken. A VDF proof took longer than expected. A DNS record is close to its TTL expiry. The correct response is to monitor, maybe retry, but not to alert anyone. The node can continue normal operation.

Error — A specific operation failed and the caller must handle it. A name record signature did not verify. A CDN chunk was unavailable. This needs attention from the client or from the node’s retry logic, but it does not threaten the node’s overall health.

Caution

Critical — A protocol-level, cryptographic, or safety violation occurred. A governance message was signed with a revoked key. A VDF reveal did not match its committed value. A replay-protection counter went backwards. When a node sees Critical, it should stop trusting the source of that error and possibly alert the operator. Continuing blindly past a Critical severity is how security vulnerabilities propagate through distributed systems.

The ladder is intentional. Kinetic is designed so that node operators — and the automated supervisor loops that monitor node health — can filter on Severity without reading the full error message. A monitoring dashboard can count Critical events in a time window and page an operator when that count crosses a threshold, without understanding anything about VDF math or governance opcodes.

How Domain Errors Plug Into Severity

Every domain-specific error enum in Kinetic — DnsError, GovernanceError, VdfError, and others — implements a severity() method that returns a Severity variant for each of its own variants. The signature looks like this:

#![allow(unused)]
fn main() {
fn severity(&self) -> Severity { ... }
}

This means a caller can always ask any Kinetic error “how bad are you?” without knowing what kind of error it is. The Severity type is the bridge between domain-specific error detail and network-wide operational policy. The same supervisor loop code can handle a failed DNS lookup, a VDF rejection, and a bad governance signature — because they all speak the same severity language.

FORWARD DEPENDENCY: DnsError, GovernanceError, VdfError and their severity() methods are defined in other modules of kinetic-types and documented in later topics. When you read those files, look for how each variant maps to a Severity level — the mapping is a design decision that encodes protocol intent directly into the type system.

The Display Implementation (error.rs Lines 24-33)

Severity implements std::fmt::Display, which means when you write {severity} in a format string or log statement, Rust calls this code and prints INFO, WARNING, ERROR, or CRITICAL. This is not automatic — Rust does not know how to turn your enum into a human-readable string unless you explicitly implement it.

-> See: kinetic-types/src/error.rs — Lines 24 to 33

The implementation uses a match block that exhaustively covers all four variants. Rust enforces exhaustiveness at compile time: if someone adds a fifth variant to Severity and forgets to update the Display implementation, the build fails with a clear error. This makes the type system itself a safety net for protocol evolution — you cannot silently omit a case.

The uppercase string format ("CRITICAL" not "Critical") is a deliberate convention. It matches standard syslog severity formats and makes Kinetic log output grep-friendly. A DevOps engineer monitoring Kinetic nodes with standard log tooling will instantly recognize the format.

The Derive Macro Line (error.rs Line 12)

The line above the enum definition reads:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
}

This single annotation instructs the Rust compiler to automatically generate implementations of eight different traits.

-> See RUST_CONCEPTS.md for a full breakdown of #[derive(...)].

The Crate Entry Point (lib.rs Lines 20-28)

-> See: kinetic-types/src/lib.rs — Lines 20 to 28

These nine pub mod declarations are Rust’s way of saying “these source files are part of this crate and their public items are accessible from outside.” The keyword pub before mod means other crates in the workspace — kinetic-kid, kinetic-verify, the browser extension bridge — can import from these modules. A mod without pub would be private, visible only within kinetic-types itself.

The module list is also an architectural statement: every concern in Kinetic that produces shared data types has its own module. Clock lives separately from DNS. DNS lives separately from governance. This separation means that kinetic-kid can import only kinetic_types::vdf::VdfProof without being forced to compile or depend on DNS type code. Rust compiles only what you use, and module boundaries make that precise.

Zero-Dependency Philosophy (lib.rs Lines 1-6)

Important

The lib.rs doc comment calls kinetic-types a “zero-dependency, lightweight type hub.” This is a load-bearing architectural decision, not a style preference. Any crate in the workspace that defines or consumes shared types — including offline tools, browser extensions, hardware wallets — must be able to import kinetic-types. If kinetic-types depended on a networking library, every offline tool would be forced to compile that library too. If it depended on a consensus engine, it could never run in a browser WebAssembly context where networking is sandboxed.

The only external dependencies kinetic-types may carry are serialization (serde) and cryptographic primitives — things so fundamental that every possible consumer needs them anyway. This is why Severity derives Serialize and Deserialize from serde rather than implementing a custom wire format: serde is already a cost every consumer accepts.

Key Pieces

Severity — kinetic-types/src/error.rs Lines 13-22

The four-level classification enum. Every error in the Kinetic system answers to this type. Choosing the right variant for an error is a protocol design decision: it tells operators and automated systems how to respond without requiring them to understand the domain. Getting this wrong — tagging a signature forgery as Warning instead of Critical — is a security decision embedded in code, invisible until something goes wrong in production.

impl std::fmt::Display for Severity — kinetic-types/src/error.rs Lines 24-33

Converts a Severity variant to an uppercase string for logs and error messages. The match is exhaustive — Rust will refuse to compile if a variant is missing from the arm list. The uppercase format matches syslog conventions for grep-friendly log tooling.

pub mod error; — kinetic-types/src/lib.rs Line 23

The one line that makes Severity importable as kinetic_types::error::Severity from anywhere in the workspace. Without this declaration, error.rs would be an orphaned file that the compiler ignores entirely.

Nine pub mod declarations — kinetic-types/src/lib.rs Lines 20-28

The module declarations that constitute the crate’s public surface. Each one corresponds to a source file or directory under kinetic-types/src/. The ordering roughly follows dependency direction: error is declared before governance because governance errors reference Severity.

How This Connects to the Rest of Kinetic

Every other crate in the workspace that can produce an error uses Severity from this module. That makes kinetic-types::error the most imported error module in the codebase. It is infrastructure as fundamental as the clock subsystem — arguably more so, because errors happen everywhere.

CROSS-CRATE: Severity — this is the canonical definition. All other crates import it from here. It has no definition anywhere else in the workspace.

FORWARD DEPENDENCY: kinetic-kid — the node identity and key management crate — will import Severity to classify key-loading and signature errors. When a KID (Key Identifier) cannot be loaded, that error’s severity() method will return a variant defined right here.

FORWARD DEPENDENCY: kinetic-verify — the proof verification engine — uses Severity to signal whether a failed VDF proof is a transient computation error (Warning) or a deliberate submission of an invalid proof (Critical). The distinction matters because a Critical here triggers blacklisting logic at the network layer, not just a retry.

FORWARD DEPENDENCY: The browser extension proxy (proxy module declared in lib.rs Line 26) serializes errors over an IPC channel back to the browser. Because Severity derives Serialize/Deserialize, the browser receives a structured severity level it can use to display the right UI alert color without parsing a raw string.

FORWARD DEPENDENCY: The governance module (governance, lib.rs Line 24) produces GovernanceError variants that each carry a Severity. A governance message with an invalid binary opcode gets Warning; a message with a forged signature gets Critical. Node operators can configure severity-gated alerting rules that fire on Critical governance errors specifically, independently of other error streams.

Quick Reference

Severity decision flow for node supervisors:

Open Questions / Things to Revisit

1. No severity ordering trait. Severity does not implement PartialOrd or Ord, so you cannot write if severity >= Severity::Error. A supervisor loop that wants to handle “anything Error or worse” must use a match arm or a helper function. The ordering is obvious (Info < Warning < Error < Critical) and the omission may be intentional — forcing explicit match arms prevents accidentally skipping a case — but it is worth revisiting if supervisor logic grows verbose.

2. No KineticError trait definition. error.rs describes (in comments) that domain errors implement a severity() method, but there is no Rust trait that formally requires this. Each domain error type adds severity() by convention, not by compiler enforcement. A future trait KineticError { fn severity(&self) -> Severity; } would make this a compile-time guarantee rather than a code review concern.

3. Wire format for Severity is unspecified. Serialize/Deserialize on Severity means serde knows how to handle it, but the actual wire format (JSON string “Critical”, integer, MessagePack byte) depends on the serializer each subsystem chooses. If the proxy subsystem uses JSON and the VDF subsystem uses MessagePack, a Severity crossing that boundary may need a translation step. Worth confirming all subsystems agree on a single encoding.

4. lib.rs module order is not documented as intentional. The nine pub mod declarations follow a rough dependency order (error before governance, which uses it) but this is not documented anywhere in the file. If a new subsystem is added, the author needs to know where to insert it. A short comment in lib.rs explaining the ordering rule would prevent future confusion.

Stage 1 · identity.rs — Authorization Containers for .kin Names

Crate: kinetic-types Source: kinetic-types/src/identity.rs — Lines 1–97 Estimated reading time: ~12 minutes Depends on: 01_lib.md (crate overview), 02_name.md (.kin name model)

What Is This?

identity.rs defines two authorization containers: AuthorizedKid and AuthorizedManifest. Each one wraps a cryptographic identity document or capability declaration and binds it to a specific .kin name, sealed with the name-owner’s digital signature. This is how Kinetic proves that the person who owns alice.kin is the one who chose to attach a particular key or capability — not a stranger injecting their own.

Why Kinetic Needs This

Without these containers, any node on the network could claim “I am alice.kin” by presenting any key document whatsoever — there would be no proof the name owner agreed. AuthorizedKid provides that proof for identity keys. AuthorizedManifest provides the same proof for capability rules (“this key may only sign name-transfer messages, nothing else”).

There is a second, more subtle problem: a valid cryptographic signature is just bytes. If the signing input is not locked to a specific network context, an attacker could take a signature produced on the production .kin network and replay it on a test network like .corp or .local, where the same key might have different privileges. The signable_bytes methods on both structs solve this by baking the network_id string directly into the bytes that get signed. No network_id → no valid signature.

How It Works

Concept 1 — What Is a KID?

KID stands for Key Identifier. Think of it as a decentralized identity card. It is a structured document that says: “Here are the public keys that represent this identity, here is who controls them, and here is the proof.” KID documents are the Kinetic equivalent of a DID Document in the W3C DID standard.

The actual KidDocument type lives in the kinetic-kid crate (Stage 3). Inside identity.rs it appears as kinetic_kid::document::KidDocument — Kinetic uses the full path because kinetic-types depends on kinetic-kid.

FORWARD DEPENDENCY: KidDocument — defined in kinetic-kid/src/document.rs. Full documentation in docs/learn/kid/ (Stage 3). Conceptually: a structured document containing the public keys and controller metadata for one Kinetic identity.

Concept 2 — What Is a CapabilityManifest?

A CapabilityManifest is a declaration of what a key is permitted to do. Rather than saying “this key can do everything”, Kinetic lets identity owners publish narrow permissions: “this key may only register sub-names”, or “this key may only publish data records, not transfer ownership.” This is capability-based access control applied to a decentralized network.

FORWARD DEPENDENCY: CapabilityManifest — defined in kinetic-kid/src/manifest.rs. Full documentation in docs/learn/kid/ (Stage 3). Conceptually: a signed list of permitted operations scoped to one key.

Concept 3 — AuthorizedKid: Binding an Identity to a Name

-> See: kinetic-types/src/identity.rs — Lines 20 to 57

AuthorizedKid has three fields:

• name — the .kin name this authorization is for (e.g. "alice.kin").
• kid_doc — the full KidDocument being attached. Contains public keys.
• owner_signature — the signature the name-owner produced over signable_bytes(...).

When a node in Kinetic receives an AuthorizedKid, it:

1. Reconstructs the expected byte sequence using signable_bytes(network_id).
2. Verifies owner_signature against that byte sequence using the name-owner’s currently-registered public key.
3. If it checks out, the kid_doc is accepted as the authorized identity for that name.

If any of those three fields is tampered with — the name changed, a different key inserted, the signature swapped — step 2 fails and the document is rejected.

Concept 4 — AuthorizedManifest: Binding Capabilities to a Name

-> See: kinetic-types/src/identity.rs — Lines 60 to 96

AuthorizedManifest has four fields:

• name — same idea; the .kin name this manifest governs.
• manifest — the CapabilityManifest declaring permitted operations.
• kid_doc — an optional KidDocument. Sometimes you publish capabilities alongside the identity document; sometimes you publish them separately. Option<KidDocument> lets both cases exist without duplicating the struct.
• owner_signature — same role as in AuthorizedKid; the name-owner’s seal of approval.

The Option<T> here is a deliberate design choice: a capability manifest may be published independently of a KID update. Forcing kid_doc to always be present would mean every manifest update re-uploads an unchanged identity document — wasted bandwidth and storage.

Concept 5 — Replay Protection and signable_bytes, Step by Step

This is the most important mechanism in the file. Read it carefully.

Warning

Why replay attacks exist: A cryptographic signature only proves “someone signed this exact sequence of bytes.” It says nothing about which network that signing was intended for. If two networks accept the same key, an attacker can lift a valid signature from one and present it as proof of authorization on the other.

How Kinetic defeats it: Every call to signable_bytes(network_id) begins by embedding the network’s unique identifier string into the byte payload before anything else. Different network, different prefix, different bytes, different signature required.

The byte layout for AuthorizedKid::signable_bytes:

-> See: kinetic-types/src/identity.rs — Lines 42 to 56

Walk through each piece in order:

1. network_id bytes — e.g. b"kin" for the production network. This is the anti-replay anchor. A .corp node uses b"corp" here, producing a completely different byte sequence even for the same name and document.

2. b"-auth-kid-v1" — a fixed ASCII tag. Together with step 1 this forms the full prefix kin-auth-kid-v1. The v1 suffix means this layout can be versioned if the format ever needs to change without breaking old signatures.

3. u32_be(name.len()) — four bytes encoding the byte-length of the name as a big-endian 32-bit unsigned integer. This is called a length prefix. Without it, a parser cannot tell where the name ends and the JSON begins. An attacker could craft a name whose bytes overlap with the start of the JSON, confusing the verifier.

4. name_bytes — the raw UTF-8 bytes of the .kin name. Length determined by step 3.

5. u32_be(canon_json.len()) — four bytes encoding the byte-length of the canonical JSON. Same reason as step 3 — unambiguous boundary.

6. canon_json_bytes — the canonical JSON serialization of the KidDocument. “Canonical” means the JSON is always produced in the same way regardless of how the struct was constructed — same key order, same whitespace rules (none). This is what canonicalize() does (see Concept 6 below).

For AuthorizedManifest::signable_bytes the layout is identical except step 2 uses b"-auth-manifest-v1" and step 6 serializes the CapabilityManifest instead.

-> See: kinetic-types/src/identity.rs — Lines 81 to 95

The implementation uses Vec::with_capacity(...) to pre-allocate the exact number of bytes needed before filling them in — a small but real performance optimization that avoids repeated heap reallocations as data is appended.

Concept 6 — What Does canonicalize() Do?

-> See: kinetic-types/src/identity.rs — Lines 44 and 83

UNVERIFIED — the canonicalize method is defined in kinetic-kid. The following is the expected behavior based on the naming convention and cryptographic context; verify against kinetic-kid documentation when Stage 3 is written.

canonicalize() converts a struct into a canonical JSON string — a JSON representation where key ordering is deterministic and no optional whitespace is included.

The problem it solves: JSON is not unique. The same Rust struct can serialize to {"name":"alice","keys":[...]} or {"keys":[...],"name":"alice"} depending on which serializer ran first. If two nodes produce different byte sequences for the same logical document, their signature hashes will differ and verification will fail randomly. Canonical JSON eliminates this by specifying exactly one valid serialization per document.

The .unwrap_or_default() call after canonicalize() means: if canonicalization somehow fails (e.g. a field contains a value that cannot serialize), produce an empty string rather than crashing. An empty canonical payload would cause signature verification to fail, which is the safe outcome.

Key Pieces

AuthorizedKid

File: kinetic-types/src/identity.rs — Lines 20–57 What it does: Wraps a KID document and proves the .kin name-owner authorized it. Why it matters: Without it, any node could attach any key to any name unchecked.

AuthorizedManifest

File: kinetic-types/src/identity.rs — Lines 60–96 What it does: Wraps a capability manifest and proves the name-owner authorized it. Why it matters: Enables scoped-permission keys; proves the name-owner set the scope.

AuthorizedKid::signable_bytes

File: kinetic-types/src/identity.rs — Lines 42–56 What it does: Produces a deterministic, network-scoped byte sequence for signing. Why it matters: This exact byte sequence is what gets signed and what gets verified. Any mismatch — wrong name, wrong network, wrong document — causes verification to fail.

AuthorizedManifest::signable_bytes

File: kinetic-types/src/identity.rs — Lines 81–95 What it does: Same role as above, for capability manifests. Why it matters: The -auth-manifest-v1 tag prevents manifest signatures and KID signatures from being confused with each other even on the same network.

#[derive(Debug, Clone, Serialize, Deserialize)]

File: kinetic-types/src/identity.rs — Lines 20 and 60 -> See RUST_CONCEPTS.md for an explanation of #[derive(...)].

How This Connects to the Rest of Kinetic

Both structs embed types from kinetic-kid directly:

FORWARD DEPENDENCY: kinetic_kid::document::KidDocument — used in AuthorizedKid.kid_doc (Line 25) and AuthorizedManifest.kid_doc (Line 67). Defined in kinetic-kid. When Stage 3 is documented, cross-reference: docs/learn/kid/XX_document.md.

FORWARD DEPENDENCY: kinetic_kid::manifest::CapabilityManifest — used in AuthorizedManifest.manifest (Line 65). Defined in kinetic-kid. When Stage 3 is documented, cross-reference: docs/learn/kid/XX_manifest.md.

The name field on both structs ties back to the .kin naming model introduced in 02_name.md. An AuthorizedKid is only meaningful if you already understand what a .kin name is and how ownership is established.

The owner_signature field (a Vec<u8> on both structs) is raw bytes. The actual signature verification logic — checking this signature against the name-owner’s key — lives in kinetic-verify (a later stage). kinetic-types only holds the data shape; it does not verify anything itself.

FORWARD DEPENDENCY: Signature verification of owner_signature — handled by kinetic-verify. When that stage is documented, add a cross-reference here.

Quick Reference

Important

The anti-replay rule to remember: network_id is always the first bytes written. Change the network, change the required signature. Period.

The length-prefix rule: Every variable-length field is preceded by 4 bytes (u32, big-endian) saying how long it is. This makes the byte sequence parseable without ambiguity.

Open Questions / Things to Revisit

Note

1. canonicalize() — UNVERIFIED. The behavior described in Concept 6 is inferred from naming and cryptographic convention. Once Stage 3 (kinetic-kid) is documented, confirm exactly which JSON canonicalization scheme is used (JCS? custom?), whether it sorts keys, and whether it handles nested structures deterministically.

2. unwrap_or_default() on canonicalize. If canonicalization fails silently (empty string), the resulting signature will also be wrong silently. Is there an error path that surfaces canonicalization failures to callers? Worth checking whether this should return Result<Vec<u8>, Error> rather than Vec<u8>.

3. Who verifies owner_signature? This file only defines the shape. The verification logic is deferred to kinetic-verify. When that crate is documented, confirm which key (from which field of KidDocument) is used to verify the signature and how the verifier knows which network_id to use.

4. kid_doc is Option on AuthorizedManifest but required on AuthorizedKid. Was this intentional from the start, or an evolving design? If a manifest is published without a KID, how does a verifier know which public key to check the owner_signature against? This might be answered by looking at how the verifier resolves the name’s current key before checking the manifest.

5. Version tag v1. The -auth-kid-v1 suffix implies a versioning plan. Is there a migration path documented for what happens when the signing format needs to change? Who increments the version, and how do nodes handle both v1 and v2 during transition?

clock.rs — Kinetic Network Timekeeping (The Crystal Lexicon)

What Is This?

clock.rs defines how Kinetic measures and expresses time on its own terms. Rather than leaning on Unix timestamps (seconds since January 1, 1970), Kinetic has its own named time units called The Crystal Lexicon: Kyn, Facet, Prism, Matrix, Lattice, and Apex. The KineticTime struct holds a decoded snapshot of exactly where the network is in that hierarchy at any given moment.

-> See: kinetic-types/src/clock.rs — Lines 1–12 (module-level doc comment listing all six units)

Why Kinetic Needs This

Without a custom time system, every frontend, explorer, and monitoring tool would independently interpret raw beacon numbers differently. You’d get one dashboard showing Unix timestamps, another showing block heights, and a third showing something else entirely. That confusion is a support nightmare and it makes Kinetic look like a generic chain rather than a purpose-built network.

There is also a practical reason: Kinetic’s consensus engine works in beacon slots — absolute counters that tick every 3 seconds. Those raw counters mean nothing to a human. The Crystal Lexicon translates them into something a user can read: “Prism 14, Facet 3 (Kyn 401)” instead of “412,601 beacons since genesis.” The time system is also a guard against confusion with wall-clock time — a Prism is not a “day” in the POSIX sense; it is exactly 28,800 Kyns, which happens to equal 24 hours of real time. Naming it differently keeps Kinetic network time and system time clearly separated in code and in conversation.

How It Works

The Six Units — sizes and rationale

The Crystal Lexicon is a strict hierarchy. Each unit is a fixed multiple of the one below it:

The Kyn is the heartbeat. Every time the network’s consensus engine produces a beacon, one Kyn has passed. At 3 seconds per Kyn, this is a deliberate engineering choice: it is long enough for a message to propagate across the globe, but short enough that the network feels responsive. Everything above a Kyn is just grouping those heartbeats into human-friendly containers.

-> See: kinetic-types/src/clock.rs — Lines 7–12 (the hierarchy comment block)

The KineticTime struct

-> See: kinetic-types/src/clock.rs — Lines 26–36

KineticTime has four fields:

• total_kyns — the raw count of Kyns elapsed since the network’s genesis point. This is the authoritative number; all other fields are derived from it.
• prism — how many complete Prisms (days) have passed since genesis. Not the prism-of-the-year; the total prism count from day zero.
• facet — how many complete Facets (hours) have passed within the current incomplete Prism. This is always in the range 0–23.
• kyn — how many complete Kyns have passed within the current incomplete Facet. Always in the range 0–1199.

Think of it like a digital clock. The hours hand doesn’t keep counting past 23; it resets at midnight. Same principle here: facet resets every Prism, kyn resets every Facet. The only field that never resets is total_kyns.

The #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] line above the struct tells Rust to auto-generate several standard behaviours. See RUST_CONCEPTS.md — #[derive] for what each of those means.

from_kyn() — converting a raw beacon number into human time

-> See: kinetic-types/src/clock.rs — Lines 44–68

This is the only constructor. It takes two arguments:

• current_kyn — the absolute beacon number the network is at right now.
• genesis_kyn — the beacon number at which this particular chain’s counting started. (More on why this matters in a moment.)

Important

The function has a safety check first: if current_kyn is somehow less than genesis_kyn (the clock hasn’t reached genesis yet, or the inputs are mismatched), the function returns a zeroed-out KineticTime rather than panicking or underflowing. This matters because u64 cannot go negative — subtracting a larger number from a smaller one would wrap around to an enormous number and silently corrupt the time. The guard prevents that entirely.

The arithmetic uses basic integer division (/) and remainders (%) in two passes to extract the full Prisms, Facets, and Kyns from the total elapsed kyns.

Concrete example — total_kyns = 50,000:

• 50,000 / 28,800 = 1 complete Prism.
• 21,200 Kyns remain.
• 21,200 / 1,200 = 17 complete Facets.
• 800 Kyns remain.
• Display: “Prism 1, Facet 17 (Kyn 800)”

In real time, that 50,000 Kyn mark is 1 day, 17 hours, and 40 minutes after genesis (800 Kyns × 3 seconds = 2,400 seconds = 40 minutes).

Why genesis_kyn exists

The consensus engine counts beacons from the very start of the software’s life. But Kinetic may have multiple environments: the main network, a testnet that launched later, a devnet that launched later still. Each of those networks has its own genesis point within the global beacon stream. Without genesis_kyn, every environment would have to pretend it started at beacon zero, which would make a testnet launched at beacon 1,000,000 appear to be almost 35 days old from the very first moment. By subtracting genesis_kyn, the clock always reads “how long since this network started” rather than “how long since the software was first compiled.”

-> See: kinetic-types/src/clock.rs — Lines 44–52 (the guard and the subtraction)

matrix(), lattice(), apex() — computed, not stored

-> See: kinetic-types/src/clock.rs — Lines 70–83

These three methods return the week, month, and year counts respectively. They are not fields in the struct. Instead, they are calculated on demand from self.prism:

#![allow(unused)]
fn main() {
matrix()  ->  self.prism / 7
lattice() ->  self.prism / 30
apex()    ->  self.prism / 365
}

The reason they are methods instead of stored fields is that storing them would be redundant. If you know prism, you can always derive the others with one integer division. Storing them alongside prism would mean four numbers that must all be kept in sync — and every place that creates or modifies a KineticTime would have to update all four correctly. One source of truth (prism) is simpler, safer, and uses less memory. This pattern — “store the minimum, derive the rest” — is a common design discipline in Rust and in systems programming generally.

These methods will mainly be used by analytics layers: “how many Apexes has this validator been active?” or “show me all events within Lattice 3.”

to_display_string() — human-readable output

-> See: kinetic-types/src/clock.rs — Lines 85–91

This method produces a String formatted as:

#![allow(unused)]
fn main() {
"Prism 1, Facet 17 (Kyn 800)"
}

It uses the format!() macro — Rust’s way of building strings with embedded values. See RUST_CONCEPTS.md — format!() for details.

This string is designed for UIs: block explorers, node dashboards, wallet history screens. It shows the three most human-relevant units (Prism = which day, Facet = which hour, Kyn = sub-hour precision) without overwhelming the user with total_kyns or matrix/lattice/apex counts. Those larger and smaller values are available on the struct and via methods if a UI wants them.

Key Pieces

How This Connects to the Rest of Kinetic

KineticTime is purely a data type — it does not talk to the network, read files, or produce side effects. Its job is to be created, carried around, and read. That means it will appear as a field or return value in many other crates.

FORWARD DEPENDENCY: kinetic-kid — the KID node will produce the raw current_kyn value from its consensus engine and pass it to from_kyn() to build a KineticTime for inclusion in block headers and status responses.

FORWARD DEPENDENCY: kinetic-verify — the verifier will likely use KineticTime to timestamp proofs and check whether events fall within expected time windows.

FORWARD DEPENDENCY: Explorer and frontend tooling — to_display_string() exists specifically for this layer. Any dashboard that shows “current network time” will call this method and render its output directly.

The Serialize and Deserialize derives (from the serde crate) mean that KineticTime can be converted to and from JSON automatically. This is how it will travel over the network — a node serializes it to JSON, sends it over HTTP or WebSocket, and the receiving frontend deserializes it back into a KineticTime struct without any custom parsing code.

Quick Reference

1 Kyn     = 3 seconds       (network heartbeat)
1 Facet   = 1,200 Kyns      (1 hour)
1 Prism   = 28,800 Kyns     (1 day)
1 Matrix  = 7 Prisms        (1 week)   — computed via .matrix()
1 Lattice = 30 Prisms       (1 month)  — computed via .lattice()
1 Apex    = 365 Prisms      (1 year)   — computed via .apex()

Constructor: KineticTime::from_kyn(current_kyn, genesis_kyn)
Display:     my_time.to_display_string()  ->  "Prism N, Facet N (Kyn N)"

Fields stored:   prism, facet, kyn, total_kyns
Fields derived:  matrix(), lattice(), apex()

Guard: if current_kyn < genesis_kyn -> returns all zeros, never panics

Open Questions / Things to Revisit

Note

• Leap seconds and clock drift: Kinetic time is defined purely by beacon count. If the real-world 3-second interval ever drifts (node clock skew, consensus delays), Kinetic time and wall-clock time will diverge silently. There is no correction mechanism in this module. Worth flagging for production monitoring.
• Lattice is 30 Prisms, not a calendar month: Real months have 28–31 days. Kinetic Lattices are always exactly 30 Prisms. This simplifies math but means “Lattice 1” does not map cleanly to “February 2027.” Explorers should clarify this distinction in their UI copy.
• apex() denominator is 365, not 365.25: Real years have leap years. Kinetic Apexes are exactly 365 Prisms. Over four years, Kinetic time will fall roughly one day behind the Gregorian calendar. Likely intentional (simplicity), but it should be documented in the network spec.
• No locale support in to_display_string(): If frontends want to localize (e.g., “Day 2, Hour 5, Beat 800” in another language), they will need to build their own formatter on top of the raw struct fields.
• #[allow(clippy::absurd_extreme_comparisons)] on line 43: This lint suppression is needed because Clippy misreads the current_kyn < genesis_kyn guard as impossible (both are u64). The guard is meaningful and correct — it prevents a silent underflow wrap. Keep an eye on this if the argument types ever change.

Stage 1 · kinetic-types · VDF Types

Source file: kinetic-types/src/vdf.rs — Lines 1–325 Reading time: ~20 minutes Depends on: docs/learn/types/01_error_types.md (for Severity)

What Is This?

vdf.rs defines every wire type involved in Kinetic’s two-phase name registration protocol. A “wire type” is a data structure that travels across the network — between a name owner’s client, a miner, and the Kinetic validator — and must be serialized, deserialized, and cryptographically verified consistently everywhere.

This file is the backbone of how Kinetic assigns ownership of .kin names. It contains the structures for both phases: the opaque commitment that establishes priority, and the full reveal that proves ownership with a post-quantum signature and a Verifiable Delay Function proof. Nothing about name registration happens without the types defined here.

The file also defines VdfVerifyError, the structured error type returned when post-quantum signature verification fails, and VdfJobRequest, the parameters sent to a miner when asking it to compute a VDF proof.

Why Kinetic Needs This

Important

Kinetic’s name system has one brutal requirement: no one can steal a name you are legitimately registering, and no one can fake the work required to register it.

Without the two-phase commit-reveal protocol defined here, two attacks are trivially possible:

Warning

Attack 1 — Front-running. You broadcast “I want to register alice.kin.” A malicious validator node reads your transaction out of the mempool and immediately submits its own registration for alice.kin with higher priority. You did the work; it gets the name. The Commitment struct stops this because you submit only a hash of your name first, not the name itself. The hash hides the name while still locking in your timestamp priority. Nobody can steal what they cannot see.

Attack 2 — Precomputation. Because VDF computation takes real wall-clock time, an adversary could try to precompute VDF proofs for all possible names ahead of time and then submit instantly when they see a commitment. The drand_kyn field (a randomness beacon tied to real network time) is included in the signed and proofed data so every VDF proof is bound to a specific moment in history. A precomputed proof from yesterday is invalid today.

Without VdfVerifyError and verify_signature(), the network could not reject tampered or forged proofs. Without PreviousProof, name renewals would have no cryptographic continuity — anyone could claim an expiring name by submitting a brand-new registration and pretending they are the incumbent owner.

How It Works

Background — Cryptographic Primitives

VDF (Verifiable Delay Function): Kinetic uses chiavdf to enforce a time delay on name registration. The iterations field controls the delay, and VdfProof wraps the output.

drand (Distributed Randomness): A public randomness beacon. Kinetic includes drand_kyn and drand_signature in proofs to tie the computation to a specific real-world moment, preventing precomputation attacks.

ML-DSA-65: A NIST-standardized post-quantum signature algorithm (FIPS 204). Kinetic uses it to ensure .kin name ownership remains secure against future quantum computers. It requires large public keys (~1,952 bytes) and signatures (~3,309 bytes).

Phase 1 — The Commitment

-> See: kinetic-types/src/vdf.rs — Lines 74–96

Phase 1 begins when a client wants to register a name. It picks a random 32-byte salt, computes SHA-256(name_bytes + salt_bytes), and wraps the result in a Commitment { hash: [u8; 32] }. It then puts the name and commitment into a CommitRequest and submits it to the Kinetic network.

The hash is exactly 32 bytes — always, no matter how long the name is. The network timestamps this commitment and records priority. At this moment, the name itself is invisible to everyone else on the network. Only the submitter knows the name and the salt.

The #[serde(deny_unknown_fields)] attribute on Commitment means that if any extra JSON or binary field arrives that is not hash, deserialization fails immediately. This prevents protocol confusion attacks where an attacker might sneak extra data into a commitment hoping a validator will interpret it differently.

-> See RUST_CONCEPTS.md entry: #[serde(deny_unknown_fields)]

Phase 2 — The Reveal

-> See: kinetic-types/src/vdf.rs — Lines 176–311

After the VDF computation finishes (which takes real time — that is the point), the client submits a Reveal. This is the largest structure in the file and contains everything the network needs to:

1. Confirm the commitment hash matches the submitted name and salt
2. Verify the drand randomness is real and from the right epoch
3. Accept the VDF proof as valid work
4. Verify the ML-DSA-65 signature over everything above
5. Optionally verify a chained renewal from a previous registration

Every field in Reveal is part of the signed payload. This means that changing any single field — even the protocol_version byte — invalidates the signature.

The protocol_version field defaults to 1 if not present in the incoming data. This lets the network handle older clients that do not include this field explicitly, without breaking deserialization.

-> See RUST_CONCEPTS.md entry: #[serde(default = "...")]

How signable_bytes() Works

-> See: kinetic-types/src/vdf.rs — Lines 239–310

signable_bytes() is the method that both the signer (the name owner’s client) and the verifier (kinetic-verify) must call and get identical output. If they disagree by even one byte, signature verification fails.

The method builds a flat byte buffer in this exact order:

1. Network prefix — the string "{network_id}-vdf-reveal-v1" as UTF-8 bytes. This domain-separates the signature so a reveal signed for the testnet cannot be replayed on mainnet.
2. protocol_version — 1 byte.
3. name — 4-byte big-endian length, then the UTF-8 name bytes.
4. payload — 4-byte big-endian length, then the payload bytes.
5. salt — exactly 32 bytes (no length prefix — it is always 32).
6. drand_kyn — 8 bytes, big-endian.
7. drand_signature — 4-byte length, then the hex string bytes.
8. iterations — 8 bytes, big-endian.
9. vdf_proof.proof_bytes — 4-byte length, then the proof bytes.
10. pubkey — 4-byte length, then the ML-DSA-65 public key bytes.
11. previous_proof option flag — 1 byte: 1 if present, 0 if absent. If present: 4-byte length + the serialized PreviousProof.proof_bytes().
12. miner_pubkey option flag — 1 byte: 1 if present, 0 if absent. If present: 4-byte length + the miner’s public key bytes.

-> CROSS-CRATE: 03_identity.md — see “Concept 5” for a full breakdown of why we use length-prefixing to prevent boundary ambiguity.

The big-endian byte order is a convention: the network byte order standard (RFC 1700) uses big-endian. Kinetic follows it for all multi-byte integers in wire formats.

How verify_signature() Works Step by Step

-> See: kinetic-types/src/vdf.rs — Lines 208–236

This method is called by the validator when a Reveal arrives. Here is what happens internally, step by step:

Step 1 — Build the canonical bytes. self.signable_bytes(network_id) is called. The result is the exact same byte sequence the name owner’s client signed. If the Reveal fields have been tampered with in any way, this byte sequence will differ from what was originally signed.

Step 2 — Parse the public key. ml_dsa::VerifyingKey::<ml_dsa::MlDsa65>::new_from_slice(&self.pubkey) tries to parse the raw bytes in pubkey as a valid ML-DSA-65 public key. If the bytes are corrupt or wrong length, it returns an error — mapped with .map_err(|_| VdfVerifyError::MalformedPublicKey) to Kinetic’s error type.

-> See RUST_CONCEPTS.md entry: map_err()

Step 3 — Parse the signature. ml_dsa::Signature::<ml_dsa::MlDsa65>::try_from(&self.signature) parses the raw signature bytes. ML-DSA-65 signatures have a fixed structure; if these bytes do not conform, you get VdfVerifyError::MalformedSignature.

Step 4 — Verify the main signature. pubkey.verify(&signable, &sig) runs the ML-DSA-65 mathematical verification. This is the cryptographic core: it checks that the signature was produced by the private key corresponding to pubkey, over exactly the bytes in signable. Any mismatch gives VdfVerifyError::InvalidSignature.

Step 5 — Verify the previous proof’s signature (if present). If self.previous_proof is Some(prev), the method also verifies that prev.signature was produced by the same pubkey over prev.signable_bytes(). This is the continuity check: it proves the same identity that owns the name now also signed the previous registration. You cannot chain in someone else’s old proof.

Step 6 — Return Ok(()). If all checks pass, the method returns Ok(()) — Rust’s idiom for “success with no value.” The caller in kinetic-verify then proceeds to validate the VDF proof itself.

The ? operator is used internally on each fallible step. If any step fails, execution exits immediately and the error is returned to the caller without reaching the next step.

PreviousProof and Renewal Chains

-> See: kinetic-types/src/vdf.rs — Lines 98–173

When a .kin name expires and the owner wants to renew it, they do not just submit a fresh registration as if they were a new registrant. Instead, they include a PreviousProof inside their new Reveal.

PreviousProof contains the salt, drand values, iteration count, VDF proof, and signature from the previous registration of this name. By signing over the previous proof with the same private key used in the new registration, the owner creates a cryptographic chain: “I am the same entity who held this name before, and I am extending my ownership.”

The signable_bytes() method on PreviousProof produces the bytes that were originally signed when that old registration was submitted. The proof_bytes() method produces the same content plus the previous signature itself — this is what gets embedded inside the new Reveal.signable_bytes() so that everything is covered by the new signature.

The prefix "{network_id}-vdf-prev-v1" domain-separates previous proofs from reveal proofs, preventing any cross-type reuse of a signature.

VdfJobRequest — Kicking Off the VDF Computation

-> See: kinetic-types/src/vdf.rs — Lines 313–324

Once the commitment is submitted, the client (or a miner acting on its behalf) needs to compute the actual VDF proof. VdfJobRequest is the message that starts that job. It contains:

• challenge_hash — the 32-byte commitment hash. The VDF is computed over this input.
• name_length — the character length of the name being registered. Kinetic uses name length to determine how many iterations are required. Shorter names are more valuable, so they may require more iterations.
• hashcash_nonce — a proof-of-work nonce, adding an additional spam barrier on top of the VDF time cost.
• drand_kyn — the drand round number that this VDF computation is anchored to.

FORWARD DEPENDENCY: VdfJobRequest is consumed by the VDF miner service (not in kinetic-types). The miner reads this struct, runs the chiavdf engine, and returns a VdfProof that gets embedded in the Reveal.

Key Pieces

VdfVerifyError

File: kinetic-types/src/vdf.rs — Lines 13–68 What it does: A three-variant enum representing every way that ML-DSA-65 signature verification can fail on a Reveal. Uses thiserror::Error derive so it integrates automatically with the ? operator and the Display trait. Why it matters: Gives the validator precise, actionable signals. A MalformedPublicKey means the submitted key bytes are garbage — a Warning that might indicate a client bug. An InvalidSignature is an Error — someone is submitting a tampered reveal.

Each variant has a machine-readable code() (KIN-VDF-040 through KIN-VDF-042) and a severity() for log routing. is_retryable() is always false — none of these errors can resolve without the client fixing its data. error_type_uri() produces an RFC 7807-compliant URL for API responses.

-> See RUST_CONCEPTS.md entry: thiserror::Error -> See RUST_CONCEPTS.md entry: &'static str

Commitment

File: kinetic-types/src/vdf.rs — Lines 74–80 What it does: Wraps exactly 32 bytes — the SHA-256 hash of name + salt. Why it matters: This is the atomic unit of Phase 1. Its hash: [u8; 32] is a fixed-size array (not a Vec<u8>), meaning the compiler enforces the 32-byte constraint — you literally cannot construct a Commitment with 31 or 33 bytes. deny_unknown_fields keeps deserialization strict.

-> See RUST_CONCEPTS.md entry: [u8; 32] vs Vec<u8>

VdfProof

File: kinetic-types/src/vdf.rs — Lines 82–87 What it does: Wraps the raw output bytes from the chiavdf engine as a Vec<u8>. The proof size is variable depending on the VDF parameters. Why it matters: This struct is embedded in both PreviousProof and Reveal. It is what the validator passes to the chiavdf verifier to confirm that real sequential computation happened. The size is not known at compile time, so Vec<u8> (heap-allocated) is the right choice here.

CommitRequest

File: kinetic-types/src/vdf.rs — Lines 89–96 What it does: The full Phase 1 HTTP/network payload. Bundles the name being registered (as a plain String) with its Commitment hash. Why it matters: The name in CommitRequest is stored by the validator but not yet verified — the validator just records “this name was committed at this time.” The hash is what gets timestamped. Phase 2’s Reveal must match.

PreviousProof

File: kinetic-types/src/vdf.rs — Lines 98–173 What it does: Carries all fields from a prior name registration, including the signature over that prior registration. Why it matters: Makes name renewals cryptographically auditable. The chain of PreviousProof objects forms an unbroken ownership history from the first registration to the current one. Key methods:

• proof_bytes(&self, network_id) — serializes all 6 fields including the signature. Used as embedded content inside a new Reveal.signable_bytes().
• signable_bytes(&self, network_id) — serializes the same 5 fields excluding the signature. This is what the original ML-DSA-65 private key signed when the prior registration was submitted.

Reveal

File: kinetic-types/src/vdf.rs — Lines 176–311 What it does: The full Phase 2 payload. Contains all 12 fields needed for a complete name registration: the name, payload, salt, drand anchor, VDF proof, post-quantum signature, and optionally a renewal chain and miner key. Why it matters: This is the centerpiece of the entire VDF module. Every other type in this file either feeds into Reveal or exists to help verify it. Key methods:

• verify_signature(&self, network_id) — the validation entrypoint. Returns Ok(()) on success or a VdfVerifyError on any failure.
• signable_bytes(&self, network_id) — produces the exact byte sequence that was signed. Both client and validator call this independently; they must agree.

miner_pubkey — Miner Delegation

The miner_pubkey: Option<Vec<u8>> field on Reveal is how Kinetic accommodates the reality that VDF computation is resource-intensive. Instead of requiring every name owner to run a VDF engine locally for minutes, they can hand off a VdfJobRequest to a miner. The miner computes the proof and returns it. When the owner builds their Reveal, they include the miner’s public key so the network can route compensation to the miner. This is included in signable_bytes(), which means the owner explicitly endorses this specific miner by signing over their public key. The owner cannot be retroactively charged for a different miner’s work.

VdfJobRequest

File: kinetic-types/src/vdf.rs — Lines 313–324 What it does: Packages the parameters needed for a miner to begin VDF computation: the challenge hash, name length, hashcash nonce, and drand round. Why it matters: Decouples the name owner from the VDF computation. The owner can hand off this struct to a miner, go offline, and come back later to receive the completed VdfProof.

How This Connects to the Rest of Kinetic

VdfVerifyError uses Severity from the Kinetic error module. -> See: docs/learn/types/01_error_types.md for the full Severity enum.

The Reveal struct and its verify_signature() method are the primary inputs to the kinetic-verify crate. That crate receives a Reveal off the wire and calls verify_signature() first, before doing any VDF-specific validation.

FORWARD DEPENDENCY: kinetic-verify — takes a Reveal, calls verify_signature(), then passes vdf_proof.proof_bytes to the chiavdf library verifier. Explained in Stage N kinetic-verify docs.

FORWARD DEPENDENCY: kinetic-kid — the name owner client that constructs CommitRequest and Reveal, computes the SHA-256 commitment hash, picks the salt, and generates the ML-DSA-65 key pair. The client side of the protocol.

FORWARD DEPENDENCY: VDF Miner Service — receives VdfJobRequest, runs chiavdf computation, returns a VdfProof to be embedded in the Reveal.

CROSS-CRATE: ml_dsa crate — provides VerifyingKey<MlDsa65>, Signature<MlDsa65>, KeyInit, and the Verifier trait. Referenced directly in verify_signature(). This is the post-quantum cryptography engine.

CROSS-CRATE: serde crate — provides Serialize and Deserialize derives on every struct. Enables JSON and binary encoding for all wire types.

CROSS-CRATE: thiserror crate — provides the #[derive(thiserror::Error)] macro that makes VdfVerifyError implement std::error::Error and Display automatically without boilerplate.

Quick Reference

signable_bytes() field order (Reveal): network prefix → protocol_version → name → payload → salt → drand_kyn → drand_signature → iterations → vdf_proof → pubkey → previous_proof flag → miner_pubkey flag

signable_bytes() field order (PreviousProof): network prefix → salt → drand_kyn → drand_signature → iterations → vdf_proof

Length-prefix rule: Every variable-length field is prefixed with its length as a 4-byte big-endian u32. Fixed-size fields (salt = 32 bytes, drand_kyn = 8 bytes) have no prefix.

Network domain separation:

• Reveal: "{network_id}-vdf-reveal-v1"
• PreviousProof: "{network_id}-vdf-prev-v1"

is_retryable(): Always false for all VdfVerifyError variants. A malformed or invalid submission cannot succeed by retrying — the client must fix its data.

Open Questions / Things to Revisit

Note

1. VDF iteration count determination. VdfJobRequest carries name_length so the miner can derive iterations, but the actual formula mapping name length to iteration count is not in this file. Where does that mapping live? What prevents a miner from using fewer iterations than required and submitting a too-easy proof?

2. Commitment hash re-verification in Phase 2. Reveal contains name and salt, which together should reproduce the original Commitment.hash. The verify_signature() method does not do this check — it only verifies the ML-DSA-65 signature. Somewhere in kinetic-verify, the SHA-256 reproduction check must happen. Confirm where.

3. Miner compensation flow. miner_pubkey is included in the signed reveal so the miner can be paid, but this file has no payment logic. How does the miner actually get compensated? Is there a separate transaction? Is it part of the block reward?

4. Salt storage between phases. The salt is a random 32-byte value picked in Phase 1 but only submitted in Phase 2. Between the two phases, the client must store the salt somewhere safe. If the salt is lost, the commitment cannot be revealed and the name registration is forfeit. This is a user-experience risk worth documenting in the kinetic-kid client docs.

5. payload field semantics. Reveal.payload is described as “arbitrary name metadata or DNS zone record payload bytes.” What is the maximum size? Is there a validator-enforced limit? What is the wire format inside payload for DNS records?

6. No expiry field. Reveal has no expires_at or duration field. Does the network derive name expiry from the drand timestamp, from the number of VDF iterations, or from some external configuration? Renewal via PreviousProof implies names do expire — but the mechanic is opaque from this file alone.

7. hashcash_nonce validation. VdfJobRequest contains a hashcash_nonce described as an “evaluated Hashcash proof-of-work nonce,” but the Hashcash difficulty target and validation logic are not in this file. What makes a valid nonce and who checks it?

Crate: kinetic-types

Stage: 1

Reading Time: 25 minutes

Depends On: 01_kyns.md, 02_errors.md (conceptually)

What Is This?

This file (governance.rs) defines the foundational data structures, precise binary parsing logic, and execution opcodes for governance actions on the Kinetic network. In any distributed system, the rules of the protocol handle 99.9% of interactions automatically. However, there is always a tiny fraction of network operations that require human oversight, privileged authority, or emergency intervention. These are governance actions.

In Kinetic, governance actions bypass the standard Proof-of-Work (PoW) name registration and execution state machines. They are highly privileged commands injected directly into the network stream by an authorized council. This file strictly defines what those commands are, what data they carry, and most importantly, how they are mathematically packed into bytes.

Important

A critical design choice for governance.rs is its absolute isolation. This file is “self-contained,” meaning it deliberately avoids importing large, complex dependencies from the rest of the Kinetic ecosystem. It does not import network sockets, peer discovery, database layers, or even the actual cryptographic verification logic. This is not an accident. It ensures that the governance logic can be compiled onto a tiny, physically air-gapped machine (a computer with its network card physically removed). Network administrators can use this air-gapped machine to safely construct, inspect, and mathematically sign governance proposals without ever exposing their supreme private keys to the internet or to a bloated software supply chain.

Why Kinetic Needs This

To understand why this module exists, you have to look at what would happen to the Kinetic network if it were entirely automated without any governance override. Without the data structures defined in this file, the network would face several existential threats:

1. The Premium Name Problem: In Kinetic, usernames or application names are extremely valuable commodities. Single-character names (like a, x, 7) or widely recognized brand names (like btc, eth, pay) carry immense prestige and utility. If Kinetic allowed these to be registered via standard Proof-of-Work, massive industrial mining pools would immediately point their hash power at the network the second it launched, sniping every valuable name in existence. By reserving these as “Premium Names”, the network requires a GrantPremiumName action. This allows the network stewards to auction these names equitably, distribute them fairly, or reserve them for long-term ecosystem partners, rather than rewarding whoever has the biggest server farm on day one.

2. Infrastructure Naming Hijacking: The network relies on hardcoded routing names to function. For example, when a new node joins the network, it might look for a name like seed or api to find its initial peers. These are Category 2 names. If a malicious actor successfully mined the name seed, they could redirect all new nodes joining the network to a malicious server, effectively partitioning the network and executing a massive eclipse attack. The GrantInfrastructureName action ensures that only the authorized governance council can point these critical infrastructure names to verified public keys.

3. Disaster Recovery and Zero-Day Exploits: No software is perfect. If a critical bug or a zero-day exploit is discovered in the core Kinetic protocol—for instance, a flaw in the Verifiable Delay Function (VDF) math that allows an attacker to bypass time calculations—the network needs an emergency brake. Without an EmergencyHalt action, the attacker could exploit the bug indefinitely while developers scramble to write, test, and release a patch. The EmergencyHalt allows the council to instantly freeze all state transitions, preserving the integrity of the network while a fix is coordinated.

4. Key Compromise and The Escape Hatch: Security is about assuming the worst. What happens if the governance multi-signature keys themselves are compromised by a highly sophisticated attacker? If there was no way to change the keys, the network would be permanently taken over. The RotateRootKey action provides a built-in escape hatch. If the current council realizes their keys are at risk, they can rapidly sign a rotation command to transfer ultimate authority to a fresh, uncompromised keypair, locking the attacker out.

5. Deterministic Serialization: If the council decides to act, they need a way to broadcast their action that is absolutely immune to interpretation errors. If they used JSON like {"action":"halt"}, different programming languages might serialize the spacing differently, altering the final bytes and causing the digital signatures to fail validation. Kinetic needs this file to provide a deterministic, byte-level specification so that every computer on earth produces the exact same array of bytes for a given command.

6. Decentralization vs Pragmatism: In crypto-economic design, purists often argue that there should be zero governance—that the code is the ultimate law. However, real-world experience over the last decade shows that immutable bugs destroy networks. Kinetic takes a pragmatic approach. It builds a governance framework that is mathematically transparent (everyone can see the action and verify the multi-sig on the blockchain) but retains the ability to save the system from existential threats. The transparency of canonical serialization guarantees that governance cannot act secretly; every node logs the event.

How It Works

The core of this module is built around transforming high-level Rust enums into a rigid, sequential byte array, and vice versa. This process is called “canonical serialization.”

The Multi-Signature Structure

Let’s examine how actions are packaged. -> See: kinetic-types/src/governance.rs — Lines 71-154

The SignedGovernanceMessage is the envelope that carries the governance action across the network. Notice that the signatures field is of type Vec<SignatureBytes>. The use of a Vec (Vector/List) instead of a single signature is a profound architectural statement. Kinetic operates on a multi-signature (multi-sig) security model. A single human making a single mistake should not be able to halt the network or give away premium names. The system might be configured to require 3 out of 5, or 5 out of 7 authorized signatures. This struct acts as a carrier, holding all the independent signatures together so that a receiving node can loop through and verify each one against the known governance threshold.

Transforming Commands to Canonical Bytes

When the air-gapped machine is ready to produce a command, it calls the to_canonical_bytes() method. This method does not use any third-party serialization libraries (like serde_json or bincode). It manually constructs the byte array to guarantee absolute determinism.

1. The Opcode Prefix: The very first byte of the output array is the “opcode” (operation code). This is a single, hardcoded hexadecimal number that identifies the command. For example, if the action is RotateRootKey, the first byte is strictly 0x0B. This allows parsing logic to instantly know what data to expect next.

2. Payload Serialization (Strings): If the command involves a string (like the name in GrantPremiumName), it uses “length-prefixing”. It first writes the length of the string as a 4-byte integer (u32), encoded in Big-Endian format. Then, it writes the actual UTF-8 bytes of the string. -> See RUST_CONCEPTS.md for Big-Endian Parsing.

3. Payload Serialization (Public Keys): If the command includes a public key, the raw bytes of that key are appended sequentially. Because ML-DSA-65 keys are large but fixed in context, they are laid out exactly as they exist in memory without needing length prefixes.

Important

4. The Replay-Protection Timestamp: Finally, regardless of what the command is, the system always appends an 8-byte integer (u64) representing the current Unix timestamp in seconds (timestamp_sec). This is arguably the most important part of the serialization. It prevents “Replay Attacks.” If the council signs a command to grant the name test to Bob, and Bob later loses that name, Bob cannot simply take the old, validly signed byte array and broadcast it again to steal the name back. The network validators will look at the timestamp appended to the bytes, see that it is drastically out of date, and reject the transaction.

Parsing Canonical Payload from the Network Wire

When a node receives raw bytes from a peer, it needs to decode them safely using the parse_canonical_payload() function. -> See: kinetic-types/src/governance.rs — Lines 221-333

1. Size Verification: The function immediately verifies that the byte slice is at least 9 bytes long. Why 9? Because the smallest possible command (like EmergencyHalt) consists of a 1-byte opcode and an 8-byte timestamp. Anything smaller is physically impossible to be a valid command.

2. Extracting the Timestamp: Because the timestamp is always the last 8 bytes, the parser slices them off the end of the array, reverses the Big-Endian encoding using u64::from_be_bytes(), and stores the timestamp. The remaining bytes are now isolated as the “payload.”

3. Opcode Switching (The Match Statement): The parser takes the first byte of the payload and uses a match statement (Rust’s powerful switch equivalent) to route the execution logic.

4. Safe Extraction: If the opcode is 0x0A (GrantPremiumName), it reads the first 4 bytes to find the name length, safely slices that exact number of bytes to construct the string (verifying it is valid UTF-8 along the way), and treats the rest of the payload as the public key. If the bytes run out unexpectedly, or if the string is mangled, the parser safely aborts and returns a specific GovernanceTypeError instead of panicking and crashing the node.

Key Pieces

type Hash256 = [u8; 32]

-> See: kinetic-types/src/governance.rs — Line 24 -> See RUST_CONCEPTS.md for an explanation of Type Aliases. Why it matters: Naming [u8; 32] as Hash256 anchors the concept and makes function signatures instantly readable, distinguishing it from random data or partial keys.

type PublicKeyBytes = Vec<u8>

-> See: kinetic-types/src/governance.rs — Line 26 -> See RUST_CONCEPTS.md for an explanation of Type Aliases. Why it matters: ML-DSA-65 public keys are massive (typically 1952 bytes). PublicKeyBytes represents the raw binary data of these keys as they travel over the wire.

type SignatureBytes = Vec<u8>

-> See: kinetic-types/src/governance.rs — Line 28 -> See RUST_CONCEPTS.md for an explanation of Type Aliases. Why it matters: Just like the public keys, ML-DSA-65 signatures are exceptionally large (~3309 bytes). This alias clarifies the intent of the data.

enum GovernanceAction

-> See: kinetic-types/src/governance.rs — Lines 30-69 -> See RUST_CONCEPTS.md for an explanation of Enum variants with named fields. What it does: This is the master ledger of every permissible governance command, with each variant holding exactly the unique data it requires. Why it matters:

• GrantPremiumName { name: String, target_pubkey: PublicKeyBytes } (Opcode 0x0A): Used to bypass the standard mining process and allocate a high-value 1-character name to a specific cryptographic identity.
• RevokePremiumName { name: String } (Opcode 0x0E): Provides a mechanism to strip a premium name from a user. This is critical if a premium name is abandoned, transferred incorrectly, or if the governance council needs to reclaim it.
• GrantInfrastructureName { name: String, target_pubkey: PublicKeyBytes } (Opcode 0x0F): Functions identically to premium names, but is semantically separated for Category 2 infrastructure names like api, seed, or telemetry.
• RevokeInfrastructureName { name: String } (Opcode 0x10): Reclaims an infrastructure name, ensuring routing can be updated if an official node goes offline or is compromised.
• RotateRootKey { new_key: PublicKeyBytes } (Opcode 0x0B): The ultimate security fallback. If the current council multi-sig is compromised, this command replaces the master key authorized to execute all other governance commands.
• EmergencyHalt (Opcode 0x0C): Carries no payload. When verified, it instructs the state machine to instantly reject all new blocks and registrations. The network freezes in time.
• EmergencyResume { paused_kyns: u64 } (Opcode 0x0D): Unfreezes the network. The paused_kyns field is mathematically crucial. Kinetic measures network time in “kyns” using a Verifiable Delay Function (VDF). If the network is halted for 48 hours, resuming it without accounting for that missing time would destroy the difficulty adjustment algorithm (the network would think time leaped forward inexplicably). The paused_kyns value tells the network state machine exactly how much “time” to subtract from its ledgers so that calculations remain stable.

struct SignedGovernanceMessage

-> See: kinetic-types/src/governance.rs — Lines 71-154 What it does: This is the primary transport object. It wraps a specific GovernanceAction alongside the timestamp_sec when it was issued, and the signatures array that proves it is legitimate. Why it matters: This struct implements the vital to_canonical_bytes() serialization function. It is the bridge between human-readable Rust structs and the raw, rigid binary needed for the peer-to-peer network.

thiserror and Severity

-> See: kinetic-types/src/governance.rs — Lines 156-219 What it does: The GovernanceTypeError utilizes the thiserror crate via a derive macro. This macro auto-generates the boilerplate required to implement Rust’s standard std::error::Error trait. Why it matters: Instead of manually writing Display implementations for every error variant, developers can simply annotate the enum variants with #[error("...")]. This is crucial for network diagnostics. When a node operators sees KIN-GOV-031 in their logs, they immediately know an UnknownOpcode was received, rather than a generic “Parsing Failed” message. Furthermore, the Severity categorization (Warning vs Error) allows the network layer to decide whether to simply drop the connection to the offending peer (for an Error) or just drop the packet (for a Warning).

enum GovernanceTypeError

-> See: kinetic-types/src/governance.rs — Lines 156-219 What it does: An exhaustive catalog of exactly how the parsing process can fail when attempting to read canonical bytes. Why it matters:

• BufferTooSmall (KIN-GOV-030): Emitted if the byte array is shorter than 9 bytes. This is flagged as a Warning because it might simply be the result of a dropped TCP packet or a noisy network connection, rather than an active attack.
• UnknownOpcode(u8) (KIN-GOV-031): Emitted if the first payload byte is not recognized (e.g., 0x99). This is flagged as an Error because it implies a peer is transmitting malicious junk data or is running an incompatible, highly divergent version of the software.
• InvalidUtf8 (KIN-GOV-032): Emitted if the string parsing encounters bytes that violate the strict rules of UTF-8 text encoding. This is a Warning.
• InvalidPubkeyLength (KIN-GOV-033): Emitted if the public key slice does not match expected length parameters. Also a Warning.

Crucially, every single one of these errors hardcodes is_retryable() to false. If a governance message is malformed, attempting to parse it again will not magically fix it. It is permanently invalid and should be immediately dropped.

How This Connects to the Rest of Kinetic

Because kinetic-types is a foundational crate at the bottom of the dependency hierarchy, this file does not import logic from higher-level crates. Instead, it provides the strict blueprints that those higher-level crates must follow.

• FORWARD DEPENDENCY: kinetic-network: When a node is listening to peer gossip traffic, it will receive raw bytes. It uses the kinetic-network crate to route those bytes directly into this module’s parse_canonical_payload function. If the function succeeds, the networking layer knows it has a properly structured message.
• FORWARD DEPENDENCY: kinetic-verify: This module does absolutely zero cryptographic verification. It only parses the bytes. Once a message is successfully parsed, it is handed off to the kinetic-verify crate. That crate will take the signatures array, load the ML-DSA-65 algorithms, and mathematically prove that the signatures match the root key.
• FORWARD DEPENDENCY: kinetic-state: After the signatures are verified, the action is passed to the kinetic-state machine. If the action is EmergencyResume, the state machine extracts the paused_kyns integer and manually recalibrates the global network VDF clock before accepting new blocks.

Quick Reference

• Parsing Logic: Controlled by deterministic byte manipulation to ensure identical cross-platform representation without heavy JSON/Protobuf libraries.

• Security Posture: Enforces a multi-signature model via Vec<SignatureBytes>.
• Replay Protection: Strictly enforced by the 8-byte timestamp_sec appended to every single serialized payload.
• Main Entrypoint: GovernanceAction::parse_canonical_payload(bytes: &[u8]).

Open Questions / Things to Revisit

Warning

• Hardcoded Length Vulnerabilities in Parsing: The current implementation of parse_canonical_payload reads a 4-byte Big-Endian integer (u32) to determine the length of a name string. A u32 can represent a number up to 4.2 billion. If a malicious node sends a valid opcode but maliciously sets the length prefix to 4 billion, the node might attempt to allocate 4 gigabytes of memory for a string, resulting in an instant Out-Of-Memory (OOM) crash. This parsing function urgently needs a sanity-check limit (e.g., rejecting any name length over 255 bytes) before slicing the array.

• Cryptographic Agility for Opcodes: Currently, the system implicitly expects public keys and signatures to conform to ML-DSA-65 lengths. If the National Institute of Standards and Technology (NIST) releases a newer standard, and Kinetic wishes to upgrade its cryptography, the parsing logic will break if the new keys are different lengths. We may need to introduce versioned opcodes (e.g., GrantPremiumNameV2) or start prefixing public keys with their byte lengths just like we do for strings.

• Timestamp Drift Windows: The file includes a timestamp to prevent replay attacks, but it does not dictate how “old” an action can be before it is rejected. It simply parses the timestamp. The upstream consensus layers must rigorously define an expiration window (e.g., “reject governance actions older than 4 hours”) to prevent a leaked, validly signed command from being strategically deployed days or weeks later.

kinetic-types :: Name Records

Stage: 1
Reading Time: ~10-12 minutes
Depends on: 06_vdf.md (for understanding the Reveal struct wrapped inside NameRecord::Standard)

What Is This?

This file (kinetic-types/src/name_record.rs) defines the ultimate source of truth for name ownership on the Kinetic network. It describes exactly what a .kin name record looks like when it is flying across the network as a UDP packet. It also describes how it looks when it is sitting statically in the Distributed Hash Table (DHT). In Kinetic, a NameRecord is the fundamental data structure that answers the question “Who owns this name and what does it resolve to?” They are the fundamental building block that turns a chaotic network of peers into an organized, discoverable domain system.

It also defines Heartbeats, which are cryptographic pings. Owners must periodically broadcast these pings to prove they are still alive and actively maintaining their names. Without both of these structures, Kinetic would not function as a decentralized naming system.

Why Kinetic Needs This

Without a standardized NameRecord, the Kinetic network would have no way to enforce name ownership or route traffic. When a user tries to access mysite.kin, the network has to ask the DHT for the record associated with that name. If that record didn’t exist in a universally understood format, the network couldn’t know whether the name is available. It also wouldn’t know who has the right to update its IP address, or what its current routing payload is.

Furthermore, Kinetic is completely decentralized. There is no central database, and there is no “Kinetic Inc.” to manually clean up abandoned names. If someone registers a name and loses their private key, or dies, that name could be locked forever. Without these mechanisms, the system would rapidly degrade into a graveyard of lost, unreachable names that nobody could manage.

Important

The Heartbeat mechanism solves this massive problem: If a node doesn’t see a valid, freshly signed heartbeat for a name within a specific timeframe, the network considers the name abandoned.

Once abandoned, the network allows it to be reclaimed by someone else. The NameRecord and Heartbeat structures are therefore the absolute foundation of Kinetic’s decentralized domain name system (DNS) replacement.

How It Works

The architecture of name ownership is bifurcated into two parallel tracks that share a common interface.

The Two Classes of Names

#![allow(unused)]
fn main() {
// See: kinetic-types/src/name_record.rs — Lines 45 to 61
}

The NameRecord is an enum with two distinct variants:

1. Standard: This is how 99.9% of names are registered on Kinetic. A user performs Proof of Work, computes a Verifiable Delay Function (VDF), and publishes a Reveal. The network verifies the cryptography. This variant wraps the Reveal struct (which we look at in vdf.rs).
2. Premium: These are special, typically 1-character apex names (like a.kin or x.kin). They are excluded from the standard mining process to prevent domain squatters from grabbing the most valuable network assets instantly. Instead of being mined, they are granted by the Governance Root Authority key. The Premium variant holds the grant details, including a timestamp and a direct signature from the authority.

Because both variants are packed into the single NameRecord enum, the rest of the networking code doesn’t have to care whether a name is Standard or Premium. The NameRecord provides uniform methods like .pubkey() or .payload() that automatically pull the right data out of whichever variant is being used. This is a powerful use of Rust’s pattern matching.

Preventing Enum Bloat

#![allow(unused)]
fn main() {
// See: kinetic-types/src/name_record.rs — Line 47
}

Notice that the Standard variant holds Box<crate::vdf::Reveal>.

Note

See RUST_CONCEPTS.md for Box<T> and why it is used here to prevent enum memory bloat.

Borrowing Data Instead of Copying

#![allow(unused)]
fn main() {
// See: kinetic-types/src/name_record.rs — Lines 64 to 94
}

The NameRecord implements several methods that return data, like pubkey(), payload(), and signature(). Notice that these methods return &[u8] instead of Vec<u8>.

Note

See RUST_CONCEPTS.md for &[u8] (Borrowed Byte Slice) and how it achieves zero-cost, read-only data access without expensive memory copies.

Signature Verification

#![allow(unused)]
fn main() {
// See: kinetic-types/src/name_record.rs — Lines 97 to 124
}

A name record is completely useless if someone can forge it. The verify_signature method ensures the data hasn’t been tampered with by a man-in-the-middle. For a Standard name, this simply delegates to the Reveal struct’s internal verification logic. For a Premium name, it does something more manual: It takes the name bytes, the zone payload, and the network ID. It packs them together into a single byte array. It then verifies the ML-DSA-65 post-quantum signature against the public key stored in the record. If the signature doesn’t match the bytes exactly, the record is rejected as fraudulent.

Important

By including the network_id in the signature, it prevents a record from one Kinetic testnet from being replayed on the mainnet.

Name Normalization

#![allow(unused)]
fn main() {
// See: kinetic-types/src/name_record.rs — Lines 133 to 139
}

When a user types MYSITE.KIN. or mysite.kin, they fundamentally mean the same thing. The normalize_name function aggressively converts the string to lowercase. It also strips all trailing dots. If Kinetic didn’t do this, a malicious actor could register MYSITE.KIN as a separate record from mysite.kin. This would fracture the network, confuse users, and enable phishing attacks. Normalization guarantees a single canonical form before any hashing occurs. It ensures that everyone is talking about the exact same sequence of bytes.

Storage Keys vs Heartbeat Keys

#![allow(unused)]
fn main() {
// See: kinetic-types/src/name_record.rs — Lines 145 and 169
}

To store a name in a Distributed Hash Table (DHT), you need a key. This key is essentially an address in the network where the data lives. Kinetic stores every name at 32 different addresses to ensure extreme fault tolerance. If 20 nodes go offline, the name is still safely reachable on 12 others.

1. derive_storage_keys generates 32 keys by hashing the normalized name, an index i (0 to 31), the network ID, and the string -dht-v1.
2. derive_heartbeat_keys generates 32 different keys by hashing the network ID, the string -hb-v1, the normalized name, and the index i.

The input fields are intentionally fed into the SHA-256 hasher in a completely different order. This guarantees that a storage key and a heartbeat key for the exact same name will never collide. If they did collide, a network node might accidentally overwrite a NameRecord with a Heartbeat packet in its local database.

Warning

By strictly separating the hashing domains (using -dht-v1 and -hb-v1), Kinetic prevents database poisoning.

Key Pieces

NameRecord

#![allow(unused)]
fn main() {
// See: kinetic-types/src/name_record.rs — Line 45
}

The central enum that dictates ownership across the entire platform. It is marked #[serde(untagged)], which means when it is serialized to JSON or binary, it doesn’t include an artificial "type": "Standard" field. Instead, Serde attempts to parse incoming bytes as Standard first. If that fails, it tries to parse them as Premium. This keeps the network wire format lean, self-describing, and bandwidth-efficient.

Heartbeat

#![allow(unused)]
fn main() {
// See: kinetic-types/src/name_record.rs — Line 18
}

A struct that proves the owner of a name is still alive and cares about the name. The owner signs it with their ML-DSA-65 private key. Without these heartbeats flowing through the network, the DHT would eventually drop the NameRecord. This frees it for someone else to register, preventing dead names from cluttering the namespace forever.

signable_bytes() (Inside Heartbeat)

#![allow(unused)]
fn main() {
// See: kinetic-types/src/name_record.rs — Line 28
}

This method prepares the exact sequence of bytes that the owner must sign to produce a valid heartbeat. It carefully packs the network ID, the literal string -heartbeat-v1, the length of the name, the name itself, and the drand kyn number. This strict, deterministic layout guarantees that the signature is completely locked to this exact context. An attacker cannot take a signature meant for a heartbeat and try to reuse it to authorize a payload update, because the prefix -heartbeat-v1 will not match the other format.

latest_drand_kyn (Inside Heartbeat)

#![allow(unused)]
fn main() {
// See: kinetic-types/src/name_record.rs — Line 22
}

A specific field inside the Heartbeat that references a time pulse from the drand network. This ties the heartbeat to an exact moment in real-world time. If this wasn’t here, an attacker could record an old heartbeat from three years ago. They could then replay it forever, preventing the name from ever expiring even if the owner died. This provides absolute replay protection.

M_REDUNDANCY

#![allow(unused)]
fn main() {
// See: kinetic-types/src/name_record.rs — Line 129
}

A constant set to 32. It defines the replication factor across the DHT. When you register a name or send a heartbeat, you aren’t sending it to one central server. You are sending it to 32 independent nodes to ensure high availability and censorship resistance.

normalize_name

#![allow(unused)]
fn main() {
// See: kinetic-types/src/name_record.rs — Line 133
}

A critical utility function that squashes case differences and removes trailing dots. MyName.kin. becomes myname.kin. This is executed before any keys are derived. It ensures canonical uniqueness across the entire global state.

payload()

#![allow(unused)]
fn main() {
// See: kinetic-types/src/name_record.rs — Line 81
}

A helper method on NameRecord that returns the raw byte slice (&[u8]) of the zone data. This payload contains the actual DNS records. These are the IP addresses, IPFS hashes, or Tor onion addresses that the name should resolve to. Notice it returns a borrowed &[u8], providing a read-only window into the data without triggering expensive memory copies.

How This Connects to the Rest of Kinetic

• FORWARD DEPENDENCY: kinetic-dht: The 32 keys generated by derive_storage_keys and derive_heartbeat_keys are directly consumed by the routing layer in the kinetic-dht crate. The DHT uses these 32 hashes to figure out exactly which physical IP addresses need to receive the NameRecord packet.
• CROSS-CRATE: crate::vdf::Reveal: The Standard variant tightly couples with the VDF crate. A standard name is entirely defined by the cryptographic proof that someone burned CPU time to claim it. The NameRecord is essentially just a transport wrapper around that Reveal.
• FORWARD DEPENDENCY: kinetic-node (Liveness tracking): The background workers in kinetic-node use the Heartbeat struct to update local timestamps in their state maps. If the local timestamp for a name falls too far behind the current time, the node will aggressively purge the NameRecord from its local memory.
• FORWARD DEPENDENCY: kinetic-client: The client-side CLI tools construct the Heartbeat objects by filling out latest_drand_kyn and generating the ML-DSA-65 signature before transmitting them to the network.

Quick Reference

Open Questions / Things to Revisit

1. Governance Key Rotation: The Premium names rely on a “Governance Root Authority key”. If that key is ever compromised or needs rotation, how does the network update all existing Premium names? This might need an explicit revocation or update mechanism built into a future network upgrade.
2. Payload Size Limits: The NameRecord carries the payload (DNS zone data). However, there is no explicitly defined maximum size limit enforced anywhere in this specific file. A malicious user could theoretically attach a 500MB payload and overwhelm the DHT if bounds checking isn’t strictly enforced at the network ingress layer.
3. Heartbeat Frequency: How often must a Heartbeat be sent? This file defines what a heartbeat is, but the actual TTL (Time To Live) is handled elsewhere. We should ensure the TTL math perfectly aligns with the Drand network’s pulse frequency to avoid edge cases where valid names are dropped.
4. Signature Verification Overhead: For Premium names, we are concatenating strings and byte arrays (signable.extend_from_slice(...)) every single time we verify a signature. This involves dynamic memory allocation (Vec::new()) on the hot path. We might want to pre-allocate this vector or use a streaming hashing interface that takes parts individually to improve node throughput.

08_dns_proxy_cdn.md

Crate: kinetic-types Stage: 1 Reading Time: 15 minutes Depends On: vdf.rs, name_record.rs

What Is This?

This document extensively covers three highly interconnected modules: dns.rs, proxy.rs, and cdn.rs. Together, they fundamentally define how the Kinetic network translates .kin human-readable names into actual underlying network primitives. They also define exactly how those translations are safely, reliably, and efficiently routed across isolated processes and caching layers. At a high, conceptual level, this document is examining the structural foundation for decentralized naming within the Kinetic ecosystem. It forms the bedrock of identity resolution. It also serves as the core infrastructure for content delivery. By establishing the exact memory layout for network records, it guarantees uniformity across the network. Furthermore, by providing zero-copy message structures, it ensures that the user-facing browser extension can talk to the background core node at blazing fast speeds.

Why Kinetic Needs This

If the Kinetic network only resolved .kin names to standard, traditional IP addresses, it would fail its core mission. It would not be a true peer-to-peer network. Instead, it would essentially just operate as an alternative version of ICANN, heavily reliant on central points of failure. The network absolutely requires a highly flexible way to link names directly to cryptographic identities. This is achieved using Key Identifiers (KID). It also requires the ability to link names to distributed decentralized storage. This is achieved using InterPlanetary File System (IPFS) content identifiers. Finally, it must link names directly to libp2p network nodes using PeerIds. All of this must happen without ever relying on centralized servers or authorities.

Furthermore, the architectural design of Kinetic places the user-facing browser extension and the underlying Kinetic network node in completely separate operating system processes. Because they are isolated for security reasons, they desperately need a blisteringly fast way to communicate with one another. Without specialized, zero-copy Inter-Process Communication (IPC) structures (like those carefully designed in proxy.rs and cdn.rs), the system would grind to a halt.

Warning

Every single network request would incur massive, unnecessary memory overhead. Constantly allocating new memory and deeply copying request strings across process boundaries is computationally expensive.

Similarly, deeply copying heavy response payloads (like large images or video buffers) across boundaries would cripple overall network performance. It would immediately spike CPU and memory usage, making the extension unusable for end users.

How It Works

DNS Resolution Pipeline

When a user attempts to resolve a decentralized domain, such as mysite.kin, a complex process begins. The Kinetic network initiates a traversal of the Distributed Hash Table (DHT). Its goal is to locate a NameRecord mathematically corresponding to that specific domain. Once the network successfully finds this record, it extracts the raw byte payload embedded within it. This raw payload is fundamentally a serialized DnsZone structure.

#![allow(unused)]
fn main() {
// See: kinetic-types/src/dns.rs — Lines 11 to 15
}

The DnsZone struct is designed to hold a standard HashMap. This HashMap actively maps subdomain labels (for example, “www”, “api”, or simply “@” for the root domain) to a dynamically sized list of DnsRecords. The network node looks up the user’s requested subdomain in this exact map. This lookup directly determines where the network traffic should actually be routed.

#![allow(unused)]
fn main() {
// See: kinetic-types/src/dns.rs — Lines 17 to 27
}

The DnsRecord enum is where the core decentralization magic actually happens in the codebase. It fully supports standard internet routing mechanisms. For example, it supports A and AAAA records for traditional IP addresses. It also supports CNAME for standard domain aliases. But more importantly, it introduces custom, Kinetic-specific variants meticulously tailored for Web3 interactions:

• PeerId(String): This critical variant routes traffic directly to a specific libp2p peer. Instead of resolving to a fragile IP address that might change dynamically or sit invisibly behind a strict NAT firewall, it resolves to a permanent, persistent network identity. This directly enables true decentralized peer discovery without requiring a central matchmaking server.
• KID(String): This points directly to a Key Identifier document on the network. This allows anyone traversing the network to rigorously and cryptographically verify the exact identity and public keys of the name owner.
• IPFS(String): This variant links directly to an IPFS content identifier (often called a CID). By utilizing this, users can seamlessly host fully decentralized, static websites that are linked directly to a .kin name.

High-Performance IPC (Inter-Process Communication)

The browser extension cannot read the DHT directly. This is because it runs inside a highly restricted, isolated browser sandbox environment. Instead, to fetch data, it must send an HTTP-like request to the local background Kinetic node using IPC.

#![allow(unused)]
fn main() {
// See: kinetic-types/src/proxy.rs — Lines 15 to 22
}

The ProxyRequest struct mathematically bridges this process gap. It captures all the standard elements of an HTTP request: the method, the path, the headers, and the body. Crucially, the various string components inside this request exclusively use Arc<str>.

Note

Consider a scenario where 1,000 concurrent proxy worker threads are handling rapid requests. If they all share the exact same standard “User-Agent” header string, Arc<str> ensures a massive optimization. It guarantees the string is only actually allocated in system memory a single time.

The worker threads simply pass around ultra-lightweight reference counts instead of duplicating the exact same string 1,000 times on the heap.

#![allow(unused)]
fn main() {
// See: kinetic-types/src/proxy.rs — Lines 25 to 33
}

Similarly, the ProxyResponse structure encapsulates all returning data. To intelligently avoid copying massive web assets (like uncompressed images, heavy video files, or large WASM executable bundles) across operating system process boundaries, it employs a trick. It mandates the use of the bytes::Bytes type for the payload body. This functions practically as a zero-copy byte buffer. When the massive response body needs to be rapidly sent to multiple different parts of the system, it is cloned extremely cheaply. It does this simply by incrementing an atomic reference counter, outright avoiding the need to deeply copy every individual byte. Additionally, a custom serialization wrapper called serde_bytes_wrapper is utilized.

Important

This explicitly ensures these bytes are encoded efficiently as raw binary over the wire. If we relied on standard Rust serialization, it would encode the bytes as a highly inefficient sequence of JSON numbers, drastically increasing the network serialization overhead.

CDN Caching Layer

Fetching a NameRecord directly from the DHT every single time is far too slow for a seamless web browsing experience. Kinetic nodes actively mitigate this frustrating latency by caching records locally in memory. The CDN module elegantly provides the IPC structures needed for this direct, rapid cache access layer.

#![allow(unused)]
fn main() {
// See: kinetic-types/src/cdn.rs — Lines 14 to 21
}

The CdnRequest struct simply queries a domain name using a hyper-efficient, zero-copy Arc<str>. The CdnResponse responds dynamically with an Option<Vec<u8>>. The use of the Option type is absolutely crucial and intentional here. Returning None clearly and unambiguously signals a “cache miss” to the system. This immediately prompts the system to confidently fall back to a full, standard DHT lookup. Returning Some(bytes) explicitly means the cache was successfully hit. It instantly provides the fully serialized NameRecord without network delay.

Dynamic Host Routing

Sometimes, a peer’s physical network location or public IP address changes rapidly due to network topography. However, their logical, overarching host_id stays exactly the same.

#![allow(unused)]
fn main() {
// See: kinetic-types/src/dns.rs — Lines 30 to 45
}

The HostRoutingRecord struct exists explicitly to handle this dynamic mapping problem gracefully. Unlike a rigid, static DnsZone which maps subdomains to addresses in a fairly permanent, unmoving way, the HostRoutingRecord is fluid. It maps a constant, logical host_id directly to a current, potentially ephemeral libp2p current_peer_id. To guarantee security, this record is actively and securely signed by the owner. This cryptographic proof is securely stored in the signature field. It is also mathematically tied directly to the current verifiable drand round. This specific round number is stored securely in the drand_kyn field. This powerful cryptographic combination directly prevents dangerous replay attacks. It ensures that network routing stays fresh and accurate.

Important

A malicious attacker cannot successfully broadcast an old, outdated routing record. The cryptographic signature inextricably binds the record to a specific, unalterable point in time.

Key Pieces

• DnsZone (dns.rs:11) The structural root of any .kin network payload. It acts as a primary collection logically mapping string subdomains directly to decentralized network records. This is precisely what you receive when you successfully decode the raw payload of a NameRecord.
• DnsRecord (dns.rs:17) The absolute core routing primitive within the network. It bridges legacy internet protocols (like A and AAAA records) with Web3 specific protocols (like IPFS and PeerId).
• HostRoutingRecord (dns.rs:30) A dynamic, cryptographically signed mapping system. It continuously tracks roaming peers across the global network, ensuring you can always successfully find a host even if their underlying ISP dynamically changes their IP address.
• ProxyRequest (proxy.rs:15) A heavily optimized, zero-copy IPC payload. It allows the sandboxed browser extension to completely and accurately describe an HTTP request to the underlying node without ever allocating massive amounts of unnecessary memory.
• ProxyResponse (proxy.rs:25) The direct structural counterpart to ProxyRequest. It acts as the vehicle for returning HTTP status codes, parsed headers, and efficient zero-copy byte buffers (bytes::Bytes) back to the client cleanly and swiftly.
• CdnRequest (cdn.rs:14) A lightweight, ultra-efficient, zero-copy query payload. It is specifically used to ask the local node’s caching layer if it has a specific domain name securely recorded in memory.
• CdnResponse (cdn.rs:18) An elegant wrapper type explicitly leveraging Rust’s powerful Option enum. It allows the system to gracefully handle unexpected cache misses without relying on expensive exceptions or throwing heavy system errors.

How This Connects to the Rest of Kinetic

• CROSS-CRATE: NameRecord This is fundamentally defined and thoroughly explained in the dedicated documentation for name_record.rs. The physical byte payload of a NameRecord is strictly stored within the network DHT, but it is seamlessly and logically decoded into a readable DnsZone exclusively by this module.
• FORWARD DEPENDENCY: kinetic-kid The specific KID(String) variant located inside the DnsRecord enum actively relies heavily on the kinetic-kid crate. It needs this forward dependency to actually resolve Key Identifier documents efficiently across the network.
• FORWARD DEPENDENCY: kinetic-verify The signature field meticulously found within the HostRoutingRecord is rigorously and securely validated by specific cryptographic functions. These highly complex functions will be extensively explained in the upcoming kinetic-verify crate documentation.
• FORWARD DEPENDENCY: kinetic-drand The critical drand_kyn field explicitly ties active routing records to verifiable randomness beacons. This connection is fundamental for explicitly ensuring strict, mathematically sound time-bound validity for all network paths.

Quick Reference

Open Questions / Things to Revisit

• The HostRoutingRecord signature method actively requires a mysterious network_id for proper signing. How exactly is this network_id securely distributed and flawlessly agreed upon by all clients without accidentally introducing a highly vulnerable centralization vector?
• HostRoutingRecord inherently and permanently ties its entire validity to the drand_kyn field. If the local system clock drifts severely, or the external drand synchronization gets heavily delayed, could perfectly valid routing updates be erroneously rejected by the network node?
• Both ProxyRequest and ProxyResponse serialize active HTTP headers as a completely flat Vec<(Arc<str>, Arc<str>)>. Searching for a specific HTTP header therefore always requires a potentially slow linear scan (O(N)). If application header lists get particularly large, this architectural choice might become a noticeably painful performance bottleneck compared to using a traditional HashMap.
• The #[serde(other)] attribute currently silently and implicitly absorbs unrecognized DNS record types directly into the generic Other variant. Because it carelessly throws away the actual incoming type value, we permanently lose the critical ability to log or safely inspect what the unrecognized type string actually was. Should this implementation be modified immediately to actively capture unknown types for much better network telemetry?

01 — Overview

Crate: kinetic-kid Stage: 3 of 10 Reading time: ~5 minutes Depends on: kinetic-types, kinetic-verify

What Is This?

kinetic-kid handles Kinetic Identity Documents (KIDs). It provides the self-sovereign identity layer for the network. In the Kinetic ecosystem, a KID acts as a decentralized identifier (DID) anchored to the .kin network. This crate defines exactly how these identities are created, signed, cryptographically verified, and extended using capability manifests.

Why Kinetic Needs This

Important

In a decentralized network, there is no central database of users. Without this crate, there would be no way to securely prove who owns a specific .kin name or what their keys are authorized to do. By using ML-DSA-65 post-quantum signatures and RFC 8785 JSON Canonicalization, kinetic-kid guarantees that identities are cryptographically tamper-proof across the network.

How It Works

The crate exposes the core types required for identity management. The main entry point is lib.rs (208 lines), which publicly exports the modules.

• It heavily leverages the JCS (JSON Canonicalization Scheme) to ensure that the byte representation of an identity document is exactly identical across all platforms (Windows, Linux, WASM in browser) before it gets signed.
• It provides a robust, bounded parsing mechanism to defend against malicious peers sending massive payloads.

Key Pieces (Topic File Breakdown)

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

1. 02_document.md — Covers KidDocument and ControllerKey. This is the root identity document structure and signature verification logic.
2. 03_manifest.md — Covers CapabilityManifest and ServiceEntry. Explains how identities advertise web endpoints securely.
3. 04_error.md — Covers KidError. The robust 16-variant error taxonomy for the identity layer.
4. 05_did.md — Covers KineticDid. The strict parsing logic for did:kin:<hash> identifiers.
5. 06_bounded.md — Covers OOM defense mechanisms (BoundedVecVisitor) to stop network memory-bomb attacks.

How This Connects to the Rest of Kinetic

• CROSS-CRATE: Relies heavily on the ML-DSA-65 algorithms and structures from kinetic-types and kinetic-verify.
• FORWARD DEPENDENCY: The DHT/P2P network (kinetic-network) and the database layer (kinetic-storage) will ingest these structs. Specifically, they rely on KidDocument::is_authorized_update to manage key rotations securely across the network.

Quick Reference

• Total Lines: ~981
• Signature Algorithm: ML-DSA-65 (Post-Quantum)
• Canonicalization: JCS (RFC 8785)
• Bounds: Max 20 controller keys, max 50 services.

Open Questions / Things to Revisit

Warning

The tests module inside lib.rs contains hardcoded key generation for MlDsa65. In a production environment, test fixtures should ideally be isolated to prevent testing dependencies from bleeding into the compiled WASM binary.

Crate: kinetic-kid

Stage: 02

Reading Time: 25-30 minutes

Depends On: 01_did.md (Concept of KineticDid)

What Is This?

The KidDocument is the core cryptographic root of identity in the Kinetic network. It is a highly structured data format, heavily inspired by the W3C Decentralized Identifier (DID) specification. It mathematically binds a did:kin:<hash> identifier to a specific, rotating set of public keys. Defined entirely within document.rs, it acts as the self-certifying anchor for all user interactions. It proves, without relying on any centralized server, that “I am the owner of this identity.” It also proves “these are my current keys, and here is how you can verify my signatures.” Unlike traditional X.509 certificates used on the web, a KidDocument does not require a Certificate Authority to issue or validate it. Every single node in the Kinetic network can independently and deterministically verify the authenticity of this document. This forms the foundational layer for all peer-to-peer trust, messaging, and access control in the Kinetic ecosystem. It allows individuals, devices, and automated agents to prove who they are with absolute mathematical certainty. Without this core structure, the network would have to fall back on vulnerable centralized registries. Instead, identity is sovereign, portable, and entirely controlled by the user.

Why Kinetic Needs This

In a truly decentralized, peer-to-peer network like Kinetic, there is absolutely no central database. There is no root certificate authority, and no centralized user registry to look up who a user is. There is no centralized service to look up what their current public key is. When Alice wants to send a secure message to Bob, she needs his exact, current keys. When Alice wants to authorize a sensitive transaction on the network, the network nodes need her keys to verify it. Peers need a rigorous way to verify identity independently and deterministically without trusting a middleman or corporate server. Kinetic solves this fundamental problem by making the identity document explicitly self-certifying. The KidDocument contains the ML-DSA-65 post-quantum public keys required to verify cryptographic signatures. Because the DID identifier itself is derived directly from a one-way cryptographic hash of the document’s genesis key, anyone can verify it. Anyone can fetch the document from the network. Anyone can hash the first key themselves. Anyone can check that it perfectly matches the DID URI embedded in the document. This mathematically proves that the document is authentic and originally created by the owner of that key. Furthermore, digital identities are not static entities; they must evolve. Users lose mobile devices, and hardware security tokens get compromised or stolen. Network capabilities, service endpoints, and routing requirements change constantly over time. The document provides a standardized, machine-readable format to dynamically list authorized keys. It provides a standardized way to point to off-chain capability manifests for heavier profile data. It provides an extremely robust mechanism to facilitate secure key rotation and recovery. All of this is done without ever changing the underlying, permanent did:kin identifier. This allows a user’s identity to persist securely through compromises, hardware changes, and protocol upgrades.

Important

It fundamentally ensures that the kinetic network maintains incredibly high security standards against future post-quantum computing threats. This guarantees that Kinetic identities will remain mathematically secure for decades.

How It Works

The KidDocument lifecycle involves several distinct operational phases. Each phase heavily relies on strict cryptographic checks and bounds limits to maintain trust in a trustless environment. Let’s break down each crucial step of how the document functions under the hood.

1. Document Structure and Bounds

#![allow(unused)]
fn main() {
Option<T>
crate::bounded::deserialize_max_20
}

The document is a JSON-serializable struct containing metadata, authorized keys, and signatures. -> See: kinetic-kid/src/document.rs — Lines 38 to 63

-> See RUST_CONCEPTS.md for Option<T> (used here for optional fields like signature and ManifestPointer).

Warning

To prevent Denial of Service (DoS) memory exhaustion attacks, we use custom bounded deserialization (crate::bounded::deserialize_max_20). This ensures vectors never exceed 20 items at the parsing stage, rejecting inflated payloads before they reach expensive cryptographic logic.

2. Canonicalization (Determinism)

#![allow(unused)]
fn main() {
self.canonicalize()
serde_jcs
}

Before we can cryptographically sign the document, we must have a perfectly predictable representation of its bytes. If a JSON serializer adds a single extra space somewhere in the payload, the entire hash changes. If it uses different indentation or line endings, the hash changes completely. If it reorders the dictionary keys arbitrarily, the resulting hash will be radically different. Any of these tiny variations will cause the cryptographic signature verification to completely fail. -> See: kinetic-kid/src/document.rs — Lines 65 to 77 The canonicalize() method takes an immutable reference to the document to prepare it for signing or verification. First, it clones the struct to create a temporary, mutable copy in local memory. Next, it explicitly strips out the signature field by aggressively setting it to None. This is logically required because you mathematically cannot include a signature in the very payload that is currently being signed. Then, it uses serde_jcs (JSON Canonicalization Scheme, RFC 8785) to turn the struct into a highly deterministic JSON string. This strict canonicalization scheme guarantees totally predictable byte output regardless of the system environment. Whether the document was originally generated in Rust, a browser running TypeScript, or a backend Go service, the byte representation will match perfectly. The final bytes fed into the ML-DSA-65 signing algorithm will be exactly identical bit-for-bit across all operating systems and platforms. This prevents incredibly subtle cross-language compatibility bugs from accidentally breaking network consensus. This exact methodology is what allows disparate, heterogeneous clients to all agree on the validity of a single identity.

3. Verification (Stateless check)

#![allow(unused)]
fn main() {
verify()
.ok_or(KidError::MissingSignature)?
kinetic-kid-v1\0
.is_ok()
Ok(())
}

When a Kinetic node receives a new KidDocument over the wire, the absolute first thing it does is a stateless verification. This is the front-line, high-speed defense against invalid or intentionally malicious data. -> See: kinetic-kid/src/document.rs — Lines 79 to 170 The verify() method is termed purely “stateless” because it absolutely does not look at any network history. It does not check any ledger, DHT state, or blockchain state to figure out if the document is allowed. It only analyzes the exact bytes of the document currently loaded in memory in front of it. It performs a rigorous sequence of checks to ensure the document is internally self-consistent.

Warning

First, it performs extensive bounded fields validation on all internal collections. It explicitly checks that there aren’t too many controller keys. It checks that there aren’t too many revocation keys or manifest URLs. It carefully checks that string lengths do not exceed strict memory limits (e.g., public keys must be smaller than LIMITS_KID_MAX_PUBLIC_KEY_BYTES).

Next, it performs robust signature extraction and decoding. It safely extracts the base64url-encoded signature using the idiomatic Rust pattern .ok_or(KidError::MissingSignature)?. It then decodes the base64url string into raw binary bytes. It parses those raw bytes into a strongly typed ML-DSA-65 signature object native to the ml-dsa crate. If the bytes are malformed, it throws an InvalidSignature error immediately. Next, it reconstructs the original signed payload. It calls self.canonicalize() to get the deterministic JSON string representation. It deliberately prepends a kinetic-kid-v1\0 prefix to the JSON bytes before verification. This domain-separation prefix is an absolutely critical protocol security feature. It aggressively prevents cross-protocol signature reuse attacks. It totally stops an attacker from tricking a user into signing a DID document when the user genuinely thought they were signing a private chat message. Finally, it runs the core cryptographic verification loop. It iterates sequentially through the controller_keys list. If the document is marked as deactivated, it instead iterates sequentially through the revocation_keys list. The closure leverages .is_ok() to gracefully and silently ignore any keys that fail verification without crashing. It successfully returns Ok(()) the very moment any valid signature match is found in the authorized list. Notice carefully that this stateless method does not check if the did:kin string matches the public keys. This is an extremely intentional design decision that very often confuses new developers reading the code. Because keys can and must be rotated over the lifetime of a long-lived identity, the keys will drift and change. A perfectly valid, completely current document in year 5 might not contain the original genesis key from year 1 anymore. This strict separation of stateless structure checks and stateful logic is core to Kinetic’s architecture.

4. Genesis Binding (The Anchor)

#![allow(unused)]
fn main() {
verify_genesis()
did:kin:<hex(SHA256(primary_key_bytes))>
}

If verify() intentionally doesn’t check the DID string, how do we know a DID belongs to this document in the first place? How do we mathematically stop Alice from simply claiming Bob’s DID by uploading a document? This is exactly where the genesis check acts as the foundational root anchor for the entire network. -> See: kinetic-kid/src/document.rs — Lines 172 to 211 The verify_genesis() method is the absolute anchor of the whole decentralized identity system. It is strictly called only once when the document is first published to the network. It extracts the very first key in controller_keys, which is permanently designated as the primary genesis key. It hashes its raw public bytes using the industry-standard SHA-256 cryptographic algorithm. It systematically formats the resulting 32-byte digest as a lowercase hex string. Finally, it rigorously verifies that the resulting string exactly matches the suffix of the did:kin identifier in the document.

Important

This creates an unbreakable, mathematical binding at the very moment of creation. You cannot claim or squat on a DID unless you demonstrably possess the private key that generates the exact public key that hashes to that exact DID. Because SHA-256 is universally collision-resistant, it is practically impossible to find two different keys that hash to the exact same DID.

This brilliantly ensures a globally unique identity namespace without relying on any central registrar or DNS server. Once the genesis check passes, the DID is irrevocably bound to that user’s cryptosystem forever.

5. Authorized Updates (The Chain of Trust)

#![allow(unused)]
fn main() {
is_authorized_update(&self, previous_doc)
.iter().any(...)
}

When Alice wants to selectively rotate her keys because she bought a new laptop, she publishes a new KidDocument. This totally new document contains the newly generated key in the controller_keys list. How does the peer network know this isn’t an active attacker trying to hijack her DID by publishing a fake update? -> See: kinetic-kid/src/document.rs — Lines 213 to 261 The is_authorized_update(&self, previous_doc) method checks the new document’s signature against the authorized keys stored in the old, proven document (previous_doc).

-> See RUST_CONCEPTS.md for Closures & Iterators (used here via .iter().any(...) to efficiently verify the signature).

This guarantees that the new document was signed by an entity already recognized as an authorized controller in the previous state, maintaining an unbroken chain of trust back to the genesis key.

Key Pieces

This section deeply breaks down the core data structures and methods that define the identity subsystem. These are the foundational building blocks you will interact with most frequently when working on Kinetic identity features.

KidDocument (Struct)

#![allow(unused)]
fn main() {
KidDocument
}

-> See: kinetic-kid/src/document.rs — Line 38 This is the primary main identity container that wholly defines a Kinetic user. It safely holds the immutable DID string identifier for the user. It conservatively holds the Unix creation timestamp to formally establish the document’s age. It contains the strictly ordered lists of controller and revocation keys. It cleanly holds the Base64url signature that definitively authenticates the entire package. It is the absolutely fundamental data model actively passed around the Kinetic peer-to-peer network to establish digital identity. The vital deactivated boolean flag is also located here. It explicitly marks an identity as permanently burnt or compromised, permanently disabling standard signing operations forever.

ControllerKey (Struct)

#![allow(unused)]
fn main() {
ControllerKey
"ML-DSA-65"
}

-> See: kinetic-kid/src/document.rs — Line 9 This crucial struct tightly represents a specific public key authorized to act on behalf of the DID. It explicitly includes an id field, which is a fragment URI like #key-1 heavily used for relative referencing within the document itself. It includes the key_type field, which currently must absolutely always be set to the exact string "ML-DSA-65". It securely includes the raw Base64url-encoded public key bytes that will actively be used for mathematical verification.

ManifestPointer (Struct)

#![allow(unused)]
fn main() {
ManifestPointer
CapabilityManifest
}

-> See: kinetic-kid/src/document.rs — Line 21 Identities in the Kinetic network aren’t just used for basic signing; they possess vast network capabilities. They have complex profile data, avatars, and custom network routing endpoints. To fiercely keep the base KidDocument extremely small and cheap to verify across the network, these heavy operational details are removed. They are completely pushed out to a separate, much larger CapabilityManifest document. This struct safely provides a secure cryptographic hash of that external manifest payload. It also provides a reliable array of network URLs (like HTTPS or IPFS) to securely locate and download that off-chain manifest data. By deliberately separating the lightweight identity anchor from the heavy capability manifest, we ensure the core identity layer remains incredibly fast and cheap.

verify() (Method)

#![allow(unused)]
fn main() {
verify()
self.deactivated
revocation_keys
}

-> See: kinetic-kid/src/document.rs — Line 87 This critically important method performs the rigorous internal consistency check of the document structure and signature.

Note

Crucial note for Saif: Pay particularly close attention to exactly how this method checks the self.deactivated flag. If the document is officially marked as revoked, standard controller keys are immediately stripped of their signing authority. From that exact point forward, only dedicated, high-security revocation_keys can authorize any further operations or final updates. This intelligently ensures that if your daily-driver device is totally compromised, the attacker still cannot maliciously un-revoke the identity.

verify_genesis() (Method)

#![allow(unused)]
fn main() {
verify_genesis()
}

-> See: kinetic-kid/src/document.rs — Line 188 This fiercely enforces the mandatory, one-time initial binding of the DID string to the precise SHA-256 hash of the primary key. This mathematically prevents “squatting” on DIDs by early adopters or attackers. It absolutely guarantees that you cannot claim an identity string that rightfully belongs to another user on the network.

is_authorized_update() (Method)

#![allow(unused)]
fn main() {
is_authorized_update()
}

-> See: kinetic-kid/src/document.rs — Line 222 This is the absolute most structurally crucial method for all complex state transition logic in Kinetic. It ensures that any and all changes to an identity’s keys or manifest are cryptographically authorized by the immediately previous state of that identity. It forms an unbroken, verifiable chain of trust spanning all the way back to the original genesis key.

sign() (Method)

#![allow(unused)]
fn main() {
sign()
SigningKey
}

-> See: kinetic-kid/src/document.rs — Line 268 This is a highly developer-friendly utility designed to seamlessly sign the document during initial creation or later update. It fully automates the complex JCS canonicalization of the struct. It rapidly signs the resulting bytes using the provided ML-DSA-65 SigningKey. It then neatly injects the resulting encoded Base64url string back into the struct’s signature field. It conveniently returns the fully signed, ready-to-publish document directly to the caller.

How This Connects to the Rest of Kinetic

This file absolutely does not exist in a vacuum; it has profound and critical dependencies across the broader Kinetic codebase. CROSS-CRATE DEPENDENCIES:

1. kinetic-did: The vital kid field internally uses the robust KineticDid struct from the kinetic-did crate. The document.rs module safely assumes that the provided string has already been strictly validated as a structurally correct did:kin URI at parsing time. This avoids performing redundant string regex validations during heavy cryptographic operations.
2. ml-dsa: This entire crate heavily relies on the post-quantum ml-dsa crate for absolutely all cryptographic operations. It specifically utilizes standard cryptographic traits like Signer and Verifier from the broader Rust crypto ecosystem. These specific traits define the generic, highly standardized interface for digital signatures in Rust. This smart abstraction fundamentally allows us to seamlessly swap algorithms in the future if a critical vulnerability in ML-DSA is ever discovered.
3. Storage Layer (Forward Dependency): The stateful is_authorized_update method strongly implies a complex future storage layer is being built somewhere else. This could eventually be a Distributed Hash Table (DHT), a global verified blockchain, or a local verified database. That external storage layer is entirely responsible for securely fetching the proven canonical previous_doc and passing it directly to this method. The KidDocument itself is purely functional and purely stateless; it absolutely does not possess the network context to know how to fetch previous states from remote peers.

Quick Reference

Here is a highly scannable, rapid summary of the strict rules enforced by KidDocument:

• Algorithms Supported: Exclusively ML-DSA-65 (NIST Post-Quantum standard).
• Max Keys Limits: Hardcoded protocol safety limit of exactly 20 controller keys.
• Max Revocation Limits: Hardcoded protocol safety limit of exactly 20 revocation keys.
• Max Location Limits: Hardcoded protocol safety limit of exactly 20 manifest locations.
• Prefix Isolation: Signed data is always forcibly prepended with kinetic-kid-v1\0 to absolutely prevent replay attacks across entirely different cryptographic subsystems.
• Genesis Binding Formula: did:kin:<hex(SHA256(primary_key_bytes))>
• Serialization Standard: RFC 8785 JSON Canonicalization Scheme (JCS).
• Encoding: All binary keys and raw signatures are strictly Base64url encoded with NO padding characters whatsoever.

Open Questions / Things to Revisit

The current KidDocument implementation is incredibly robust, but there are several rough edges and deep architectural questions that critically need to be revisited as the network radically scales.

• Algorithm Agility Implementation: The current code heavily hardcodes "ML-DSA-65" string checks widely throughout the entire module. If we ever urgently need to migrate to a totally new post-quantum standard, we will need to introduce massive algorithm agility here. We will have to rigorously handle versioning extremely carefully to thoroughly prevent catastrophic downgrade attacks where an attacker forces a weak algorithm. This will likely require a v2 document schema to cleanly implement without breaking existing nodes.
• Key Rotation Race Conditions: If a user rapidly publishes two perfectly valid, conflicting updates to their document simultaneously, they might accidentally branch the entire chain of trust. The external storage and consensus layers will desperately need strict monotonic ordering or robust conflict resolution rules to precisely determine which specific update is mathematically canonical. Without this ordering, the network could split geographically on which key is the true controller.

Warning

• Manifest Fetching Guarantees: The document securely points to a manifest via URLs, but absolutely does not actively fetch it itself. We critically need to strongly ensure that the external network layer that actually fetches the manifest strictly verifies the downloaded payload against the exact hash provided in ManifestPointer. If the network layer accidentally forgets to check this hash, the entire critical separation of identity and capabilities is fatally compromised, opening the door to devastating spoofing attacks.

• Revocation Semantics: What exactly mathematically happens to historical signatures and capabilities permanently after a document is formally deactivated? The higher application layer needs exceptionally clear rules on whether past historical signatures remain definitively valid if a key is much later revoked. We must urgently decide if revocation retroactively invalidates all past data, or only prevents future new signatures from being formed. There is currently no explicit timestamp signaling when a revocation formally occurred.
• Key Expiry: Currently, the defined controller keys have absolutely no expiration date natively embedded in them. We may need to rigorously evaluate whether controller keys should optionally support intrinsic valid_until Unix timestamps. This feature would automatically and systematically force regular key rotation best practices for all users across the entire network, significantly reducing the blast radius of old leaked keys.
• State Proofs: As the continuous chain of document updates grows significantly over years, verifying a single identity from genesis to present could become extremely computationally expensive. We may actively need to aggressively investigate SNARKs, STARKs, or other zero-knowledge state proofs to radically compress this massive verification chain in the near future. This will become extremely relevant for light clients running on constrained mobile devices.
• Error Granularity: The KidError::TooManyKeys error variant is heavily and sloppily overloaded in the verify() method. It is bizarrely returned for too many keys, too many URLs, and even raw string lengths exceeding protocol limits. We should absolutely, urgently split this into much more explicitly granular error types (e.g., MaxUrlsExceeded, PublicKeyTooLong, TooManyControllerKeys). This granular split will significantly aid in debugging rejected documents for downstream external developers actively building on Kinetic. If they get a vague error, they will waste hours blindly guessing what limit they violated.

Manifest

title: CapabilityManifest & ServiceEntry crate: kinetic-kid stage: 3 reading_time: 15 mins depends_on: 01_did.md, 02_document.md

What Is This?

The CapabilityManifest is an optional, modular addition to a Kinetic Identity Document (KID). While the main KID document acts as your core identity and cryptographic root of trust, the manifest functions as your decentralized public bulletin board. It provides a structured, standardized way to advertise services associated with your identity. For example, you might list a personal website, a REST API endpoint, a decentralized storage gateway, or a messaging inbox. The network relies on DID identifiers which are effectively just cryptographic hashes. These hashes alone cannot tell a peer how to dial a WebSocket or where to make an HTTP request. The CapabilityManifest closes this gap by securely associating networking routing data with the mathematical identity. By storing this in a completely separate manifest structure, you actively avoid bloating or needlessly rotating your primary identity document. The ServiceEntry struct represents the individual, addressable services listed within this array.

Why Kinetic Needs This

In a decentralized network like Kinetic, users and nodes must have a standard, interoperable way to broadcast: “Here is exactly how you can contact me across the network” or “Here is precisely where my external data lives.” If we decided to put all of this volatile, fast-changing routing information directly into the core KidDocument, we would immediately face significant architectural and performance drawbacks. Any minor operational change—such as simply updating a domain name, changing an API port, or rotating cloud providers— would brutally force the user to issue a full identity rotation and generate a completely new core document revision. This process would unnecessarily stress the network’s consensus mechanisms, flood gossiping channels, and incur computational overhead. Without a separate manifest, Kinetic would either have to enforce rigid, unchangeable service definitions, or force users to abandon their long-term identities whenever their web hosting provider changes. Both options are terrible for user experience.

By strictly separating the CapabilityManifest from the KidDocument, we achieve a highly modular and robust architecture. The core identity remains inherently small, static, unchanging, and maximally secure. Simultaneously, the manifest effectively handles the dynamic, fast-changing, messy reality of real-world service endpoints. Crucially, the manifest remains cryptographically bound to the core identity at all times. It absolutely must be signed by one of the authorized controller keys explicitly listed in the corresponding KidDocument. This strict separation of concerns ultimately ensures that your core identity remains unconditionally stable, while your practical network capabilities remain highly flexible, scalable, and remarkably easy to update.

How It Works

The complete lifecycle workflow for creating, parsing, and verifying a manifest involves several distinct, rigorous steps:

1. Definition of Services: The process naturally begins by building an ordered list of ServiceEntry objects. Each discrete entry explicitly specifies a unique fragment ID (like "#website"), a broad service category classification, the underlying transport protocol required to connect, and the actual, fully-qualified string endpoint URI. -> See: crates/kinetic-kid/src/manifest.rs — Lines 9 to 21

2. Constructing the Manifest: These individual service entries are then securely bundled together into a single CapabilityManifest record. This overarching structure includes vital metadata parameters such as an incrementing version number and strict validity time periods. These specific fields are essential to proactively prevent replay attacks and intelligently manage the lifecycle of the advertised endpoints. -> See: crates/kinetic-kid/src/manifest.rs — Lines 29 to 49

3. Canonicalization: Before applying any post-quantum cryptographic signature, the manifest must be deterministically converted into bytes. The canonicalize() method uses JCS (JSON Canonicalization Scheme) to strictly serialize the entire manifest. It intentionally, necessarily, and completely omits the signature field (since it is mathematically impossible to sign an empty signature). -> See: crates/kinetic-kid/src/manifest.rs — Lines 51 to 63

4. Signing: The authentic document owner securely uses a valid ML-DSA-65 private key to sign the canonicalized bytes. This specific private key must correspond perfectly to a public key already authorized in their root KidDocument. We programmatically prepend a specific, hardcoded context prefix (b"kinetic-manifest-v1\0") directly to the message bytes. This aggressive prefixing strategy explicitly prevents devastating cross-protocol signature reuse attacks across the network. -> See: crates/kinetic-kid/src/manifest.rs — Lines 138 to 152

5. Verification: When an arbitrary peer node receives the gossiped manifest, they must thoroughly verify it against the publisher’s root KidDocument. The internal verify() method runs the data through an incredibly rigorous gauntlet of uncompromising security checks. First, it firmly ensures that the manifest’s declared kid strictly matches the parent document’s decentralized identifier (DID). Next, it meticulously evaluates time constraints, guaranteeing the manifest isn’t currently expired based on local time. It also verifies that its valid_from start time isn’t impossibly far in the future, guarding against malicious clock skew injection. Then, it firmly imposes strict mathematical size bounds: a strict maximum of 50 services, and very tight byte-length limits on all internal strings. This specific defense mechanism actively prevents memory exhaustion attacks where a malicious peer intentionally uploads a gigabyte-sized manifest. Finally, it properly decodes the Base64url signature and exhaustively checks it mathematically against every valid ML-DSA-65 controller key listed in the core document. -> See: crates/kinetic-kid/src/manifest.rs — Lines 75 to 136

Key Pieces

ServiceEntry

What it does: Completely represents a single, independently addressable way to interact with the owner’s identity over the network. Where it is: crates/kinetic-kid/src/manifest.rs — Line 11 Why it matters: It elegantly structures volatile endpoint data cleanly and predictably for the rest of the application. Fields like id purposefully allow referencing specific services unambiguously via fragments. The protocol and endpoint fields directly provide the actionable routing information necessary for executing peer-to-peer connections. This explicit structural separation completely prevents ambiguous, error-prone parsing logic across different network node implementations.

CapabilityManifest

What it does: The primary root parent structure directly holding the dynamic array of services, temporal validity bounds, and the final digital signature. Where it is: crates/kinetic-kid/src/manifest.rs — Line 30 Why it matters: It purposefully acts as the definitive cryptographic envelope for decentralized network capability communication. The doc_type string strongly ensures parsers are correctly interpreting the right schema version before attempting deserialization. The monotonically increasing version integer gracefully allows seamless conflict resolution if multiple overlapping manifests are ever found gossiping in the network. The critical valid_from and expires_at fields directly provide essential temporal scoping constraints. This strict temporal scoping is absolutely critical for long-term security in a loosely connected distributed network, as it mathematically ensures that old, outdated, or maliciously compromised routing data cannot continually resurface.

CapabilityManifest::canonicalize

What it does: Securely converts the struct into a deterministically ordered, fully predictable JSON string, specifically skipping the empty signature field. Where it is: crates/kinetic-kid/src/manifest.rs — Line 57 Why it matters: All modern cryptographic signature algorithms fundamentally require an exact, byte-for-byte matching input array. Standard, naive JSON serializers will frequently reorder dictionary keys arbitrarily depending on compiler-specific internal hash map layouts. Arbitrarily reordered keys would instantly invalidate the signature mathematically for any downstream receiving peer. Using the serde_jcs crate safely enforces strict, standardized alphabetical ordering to completely eliminate this issue.

CapabilityManifest::verify

What it does: Thoroughly, safely, and completely validates all internal parameters of the manifest explicitly against its parent KidDocument. Where it is: crates/kinetic-kid/src/manifest.rs — Line 75 Why it matters: This specific method effectively represents the absolute primary defense line against invalid, malformed, or blatantly malicious data ingestion. It is actively designed to be highly paranoid by default, trusting absolutely nothing. It tightly enforces arbitrary, hardcoded limits on total authorized key counts and embedded array lengths. It meticulously checks for excessive system clock skew to proactively prevent complex time manipulation network attacks. It validates all struct string sizes individually to aggressively guard against buffer overflows or intentional memory bloat attempts. Ultimately, it securely maps the provided signature bytes back to the core identity keys for cryptographic authorization validation.

How This Connects to the Rest of Kinetic

FORWARD DEPENDENCY: The CapabilityManifest architecture is inherently, intentionally, and irrevocably linked to the foundational KidDocument. You simply cannot cryptographically verify a manifest without first successfully fetching, parsing, and verifying the corresponding parent document. The parent document strictly acts as the sole cryptographic source of truth for the necessary controller_keys required for validation.

CROSS-CRATE: In the broader ecosystem of the entire Kinetic network (such as the Kademlia DHT implementation or peering protocol layers), participating nodes will constantly, asynchronously, and frequently gossip these manifests among themselves. The underlying network transport layer relies incredibly heavily on the strict structural bounds enforced here. The hard 50 service limit and precise string constraints confidently ensure that gossiped network payloads will perpetually and comfortably fit within standard, acceptable UDP/TCP MTU (Maximum Transmission Unit) sizes. They also formally guarantee highly predictable, bounded memory usage across all network peers, protecting small constrained nodes from malicious exhaustion.

Quick Reference

-> See RUST_CONCEPTS.md for explanations of:

• web_time::SystemTime (used for WASM compatibility)
• #[serde(skip_serializing_if = "Option::is_none")] (used to omit empty optional fields from the canonical JSON)
• #[serde(deserialize_with = "crate::bounded::deserialize_max_50")] (used to prevent memory exhaustion attacks by capping service arrays)

Open Questions / Things to Revisit

• The internal time skew allowance during timestamp validation is currently hardcoded to exactly 300 seconds (5 minutes).
• Is a 300 second threshold sufficiently robust for highly distributed global nodes with potentially wildly drifting hardware clocks?
• Currently, the ML-DSA-65 signature verification iteratively loops linearly over all valid controller_keys in the document.
• If a primary document has 20 unique keys, and the manifest happens to be signed by the 20th key, verification does a massive amount of unnecessary cryptographic math.
• Should we strongly consider including a lightweight key_id hint parameter directly in the manifest to natively optimize this lookup time?
• We presently only verify specific MlDsa65 key variants during the rigorous verification step.
• If Kinetic successfully adds new post-quantum signature schemes later, this specific verify block will immediately need substantial algorithmic modification or abstract trait abstraction.
• The b"kinetic-manifest-v1\0" context byte string is currently hardcoded inline within the signing methods.
• It would definitively be significantly better architecture to formally move this to a shared, public constant inside src/constants.rs.
• Centralizing this critical context string would definitively prevent accidental copy-paste typos in future refactoring efforts.

Error

crate: kinetic-kid stage: 4 reading_time: 15 mins depends_on: [01_did.md, 02_document.md, 03_manifest.md]

What Is This?

This file (kinetic-kid/src/error.rs) defines the comprehensive error handling system for the entire kinetic-kid crate. It introduces the KidError enum, which strictly categorizes every single way that parsing, validating, or verifying a Kinetic Identity Document (KID) or a Capability Manifest can fail. Instead of using generic Rust errors or raw strings, Kinetic defines 16 highly specific failure modes with stable protocol error codes. The file also provides automated error conversion rules for third-party libraries (like serde_json and base64). Finally, it maps these protocol-level errors to appropriate security severity levels, ensuring the network daemon knows how to react to failures. This is the single source of truth for all identity-related failures in the Kinetic ecosystem. When anything breaks in kinetic-kid, it returns a KidError.

Why Kinetic Needs This

In a decentralized peer-to-peer network, error handling is not just about developer debugging; it is a critical security boundary. When a Kinetic node receives a KID document from an untrusted peer on the network, it must process it carefully and deterministically. If the document is invalid, the node needs to know exactly why it is invalid before taking action.

Consider the difference in intent between two failures. If a document fails because a JSON bracket is missing or a timestamp field is misspelled, that might just indicate a buggy client or an outdated peer broadcasting malformed data. But if a document fails because the cryptographic signature is actively invalid (InvalidSignature), or it contains too many keys (TooManyKeys), that changes things entirely. That failure could indicate an active Denial of Service (DoS) attack designed to exhaust node memory. It could be an attempted cryptographic forgery. It could be a malicious actor trying to hijack an identity they do not own. By explicitly categorizing errors into 16 distinct variants, Kinetic can safely apply different severities to different failures, protecting the node.

Furthermore, we need stable error codes (like KIN-KID-015). Cross-language clients (like an Android app, a web dashboard, or a third-party wallet application) must reliably handle network rejections. They cannot rely on parsing fragile error strings, which might change in a future Rust update. A stable error code allows the frontend application to immediately show a localized, user-friendly message. It also allows automated bots to trigger specific recovery flows, relying on a guaranteed, unchanging API contract that bridges the Rust backend and external systems.

How It Works

The error system is built around the thiserror crate, which is the standard ecosystem pattern for defining custom library errors in Rust. Let’s break down how the file is structured and how the different features interlock to provide a robust boundary.

1. The KidError Enum Definition

-> See: kinetic-kid/src/error.rs — Lines 4 to 56

The core of the file is the pub enum KidError definition. -> See RUST_CONCEPTS.md for an explanation of the #[derive(Error)] macro (from the thiserror crate).

The #[error("...")] attributes attached to each variant define exactly how the error should be formatted when converted to a string. This is what shows up in the node’s server logs or terminal output when something fails.

The 16 variants are carefully designed to cover every possible failure in the lifecycle of a KID:

• Formatting & Parsing:
  • InvalidDidPrefix, InvalidDidFormat, InvalidDidHexLength, InvalidDidHexCharacters.
  • These ensure the DID string strictly matches our required format before the CPU even attempts expensive cryptographic operations. It acts as a cheap, early filter.
• Serialization & Encoding:
  • JsonParseError, CanonicalizationError, Base64Error.
  • These handle the mechanics of moving between raw network bytes, base64url strings, and structured JSON objects in memory.
• Cryptography & Security:
  • InvalidSignature, MissingSignature, KeyParseError, UnauthorizedManifestSignature.
  • These represent core security failures where ML-DSA-65 post-quantum verification fails entirely, or the keys themselves are completely malformed.
• Protocol Bounds & State:
  • TooManyKeys (which acts as DoS protection preventing massive JSON files from crashing the parser).
  • InvalidValidFrom, ManifestExpired (which handle time-based validity failures, ensuring old manifests cannot be replayed).
• Identity Lifecycle & Authority:
  • DidKeyMismatch (genesis binding failure when a new identity is first created, ensuring the DID hash matches the key).
  • UnauthorizedKidUpdate (update authorization failure when modifying an existing document without permission).

2. Automatic Error Conversion (The ? Operator Magic)

-> See: kinetic-kid/src/error.rs — Lines 58 to 68

-> See RUST_CONCEPTS.md for an explanation of the ? operator and impl From<T> for U.

This standard trait implementation keeps the main validation logic clean by automatically translating serde_json::Error and base64::DecodeError into our custom KidError variants.

3. Stable Protocol Codes

-> See: kinetic-kid/src/error.rs — Lines 81 to 100

The code() method uses a match statement to assign a hardcoded, static string prefix to every single variant of the enum. -> See RUST_CONCEPTS.md for an explanation of match and exhaustive pattern matching.

4. Severity Mapping for Network Operations

-> See: kinetic-kid/src/error.rs — Lines 107 to 117

The severity() method maps errors into either Severity::Warning or Severity::Error. Notice the specific syntax used here: Self::InvalidSignature | Self::UnauthorizedManifestSignature | ... => Severity::Error. This is advanced pattern matching at work, grouping multiple conditions together into a single logical branch. It declares “if the internal error state matches any of these specific, security-critical variants, return an Error severity level.” For absolutely everything else (which is handled by the _ => wildcard catch-all at the very bottom), it gracefully returns a Warning. This explicit separation is vital for building a resilient, autonomous network architecture. It allows the higher-level network layers to easily distinguish between a harmless client typo (which just needs a retry) and a serious cryptographic breach (which requires immediate isolation). Without this, the node would have to parse strings to guess if the error was dangerous.

Key Pieces

The KidError Enum

• What it does: The central error registry containing 16 specific failure modes for identity operations.
• File/Line: kinetic-kid/src/error.rs — Lines 4-56
• Why it matters: It forces the developer to explicitly account for every specific way identity validation can fail, rather than relying on lazy, generic “it broke” strings that provide absolutely no context.

The impl From<T> for U Trait Implementations

• What it does: Standard Rust trait implementations that automatically convert external, third-party errors into internal KidError types.
• File/Line: kinetic-kid/src/error.rs — Lines 58-68
• Why it matters: This trait is the hidden machinery that powers the ergonomic ? operator. It makes the core validation logic concise by completely hiding the error translation boilerplate.

The Severity Enum

• What it does: A simple binary categorization enum (Warning, Error) used to flag the danger level of KidError variants.
• File/Line: kinetic-kid/src/error.rs — Lines 70-77
• Why it matters: Provides an immediate, high-level signal to the caller (like the networking daemon or the peer-to-peer layer) about whether an error represents a malicious security threat or just malformed data.

The KidError::code() Method

• What it does: Returns a static string prefix like “KIN-KID-015” deterministically based on the specific error variant.
• File/Line: kinetic-kid/src/error.rs — Lines 81-100
• Why it matters: These alphanumeric codes form the permanent API contract with external clients. They are guaranteed not to change, ensuring frontends do not unexpectedly break even if the internal Rust logic completely shifts.

How This Connects to the Rest of Kinetic

CROSS-CRATE: kinetic-network and kinetic-node When the kinetic-node or kinetic-daemon receives a gossip message containing a KID document from another peer, it will invoke the validation functions found elsewhere in this crate. Those functions will invariably return a Result<(), KidError>. The node will then inspect the error’s severity by evaluating the output of err.severity(). If it encounters a Severity::Error (like InvalidSignature or TooManyKeys), the node instantly knows the peer sending the document is either severely compromised or actively malicious. In response, the network layer can immediately drop the peer TCP connection and heavily penalize their network reputation score. This aggressive pruning protects the local node from further abuse and isolates bad actors. Conversely, if it receives a Severity::Warning (like a JsonParseError), it might just ignore the message and send a soft rejection. It assumes the peer is merely running outdated software or experiencing a bit flip, rather than acting maliciously.

FORWARD DEPENDENCY: JSON-RPC and REST API Error Responses The error_type_uri() and user_message() methods are specifically designed for the JSON-RPC or REST API boundary exposed to developers. When an external application, such as a command-line interface or a web wallet, submits an invalid identity update via the Kinetic API, the daemon will catch the resulting KidError. It will then serialize these string fields into a standard RFC 7807 Problem Details JSON HTTP response. This provides the external developer with exact, actionable frontend feedback—like “The DID method-specific ID is malformed”—rather than dumping a raw, incomprehensible Rust stack trace to their console.

Quick Reference

Here are the critical stable protocol codes generated by this module and what they represent in practice:

• KIN-KID-001 to KIN-KID-004: DID formatting failures (wrong scheme prefix, invalid hex characters, incorrect length).
• KIN-KID-005 to KIN-KID-006: Serialization and canonicalization failures (unable to parse JSON, or unable to serialize to JCS).
• KIN-KID-007 to KIN-KID-008: Core signature verification failures or missing signature fields entirely.
• KIN-KID-009 to KIN-KID-010: Base64url decoding failures or ML-DSA-65 cryptographic key parsing errors.
• KIN-KID-011: A capability manifest was explicitly signed by a key that isn’t authorized in the parent KID document.
• KIN-KID-012: DoS protection triggered (too many keys or endpoints embedded in a single document, exceeding hard memory bounds).
• KIN-KID-013 to KIN-KID-014: Time-based failures (the manifest valid_from timestamp is in the future, or the manifest has already expired).
• KIN-KID-015: Genesis binding failure (the DID hash does not mathematically match the primary controller key at creation time).
• KIN-KID-016: Unauthorized identity update (the new document version was not signed by a key specifically authorized in the previous version).

Open Questions / Things to Revisit

• Retry Logic and Transience:
  • Currently, the is_retryable() method always strictly returns false (Line 120).
  • This behavior makes perfect sense for strict cryptographic validation (if a signature is mathematically bad, trying it again won’t magically fix it).
  • However, as the Kinetic network evolves, will we ever introduce transient KID errors into the system?
  • For example, if validating a document eventually requires checking a decentralized revocation registry that might be temporarily unreachable, we might genuinely need a distinct Retryable error state to instruct the client to try again later without permanently failing the operation.
• Extensibility for Cryptographic Agility:
  • If we add new signature schemes (like an Ed25519 fallback) in the future, we might need significantly more granular key parsing errors.
  • Currently, the KeyParseError variant assumes an ML-DSA-65 post-quantum failure.
  • As we expand, we may need to distinguish between ML-DSA failures, Ed25519 failures, and ECDSA failures explicitly for better developer debugging.
• Validation Granularity in Parsing:
  • Should we attempt to expose the exact JSON field that failed parsing in the JsonParseError variant?
  • Currently, the error completely relies on serde_json’s raw string output.
  • While this is helpful for backend developers reading logs, it is not always perfectly structured for programmatic frontend handling where a UI might want to highlight a specific invalid text input box.

Crate: kinetic-kid

Stage: 1 - Core Identity and Parsing

Reading Time: 15 minutes

Depends On: error.rs (for KidError)

What Is This?

This file defines KineticDid, a custom Rust type that wraps a standard String to represent a Decentralized Identifier (DID) specifically for the Kinetic network. It ensures that any string claiming to be a Kinetic DID strictly adheres to the format did:kin:<64-character-lowercase-hex>. Because of the way this struct is built, it is literally impossible to have a KineticDid in your program that contains a malformed identifier. If the incoming data is invalid, it is caught and rejected at the system boundary before the struct is even allowed to exist. This strictness gives us immense confidence when passing it around the Kinetic codebase. The identifier consists of two main parts:

1. The scheme prefix, which is always expected to be did:kin:.
2. The method-specific identifier, which is a 64-character, all-lowercase hexadecimal string. This 64-character string is typically the hex-encoded SHA-256 hash of a public key or another underlying identity primitive in the Kinetic system.

Why Kinetic Needs This

You might wonder: why go through the trouble of creating a whole struct just to hold a single string? Why not just pass a normal String around in our functions?

If a Kinetic networking function takes a String as an argument representing a DID, it has no idea if that string is a valid DID, an empty string, or complete gibberish sent by a malicious peer. The function would either have to blindly trust the caller or re-validate the string itself, over and over again in every part of the codebase. If a developer forgets to validate it just once, invalid data poisons the system and could corrupt the Kinetic network state. This helps us avoid entire classes of bugs (like network spoofing) just by using a strong type.

Note

See RUST_CONCEPTS.md for an explanation of the “Newtype” pattern and the “Parse, don’t validate” philosophy used here. By wrapping a standard type in a custom struct (KineticDid), we force all parsing and validation to happen at the system boundary before the struct is constructed.

How It Works

The core logic of did.rs happens at the boundaries where a String tries to become a KineticDid.

#![allow(unused)]
fn main() {
// See: kinetic-kid/src/did.rs — Lines 6 to 9
}

Notice the #[derive(Debug, Clone, PartialEq, Eq, Hash)] macro above the struct.

Note

See RUST_CONCEPTS.md for #[derive(...)]. This ensures our custom struct can be copied, compared for equality, and used as a key in HashMaps (e.g., mapping a DID to a peer connection).

#![allow(unused)]
fn main() {
// See: kinetic-kid/src/did.rs — Lines 20 to 45
}

The new function is the gatekeeper. It performs four distinct, sequential checks, returning a specific variant of KidError the moment one fails:

1. First, it pulls in the required prefix using the env!("KINETIC_DID_PREFIX") macro. This macro actually reads an environment variable at compile time and bakes it into the binary. It verifies the string starts with this prefix.
2. It uses string slicing (&id_str[expected_prefix.len()..]) to safely extract the method-specific ID part of the string, and checks if it’s empty. String slices are fast, zero-copy views into the original string.
3. It explicitly checks that the method-specific ID is exactly 64 characters long, ensuring it matches the expected SHA-256 hex length.
4. Finally, it validates that every single character in the ID is correct.

Let’s look at the character validation closely:

#![allow(unused)]
fn main() {
// See: kinetic-kid/src/did.rs — Lines 35 to 40
}

The code method_specific_id.chars().all(|c| c.is_ascii_hexdigit() && !c.is_ascii_uppercase()) performs the check efficiently.

Note

See RUST_CONCEPTS.md for Closures & Iterators (used here via .chars().all(...) to validate each character with a short-circuiting check).

#![allow(unused)]
fn main() {
// See: kinetic-kid/src/did.rs — Lines 69 to 78
}

Another crucial part of how this works is the custom Deserialize implementation. By default, if you use a #[derive(Deserialize)] macro on a Newtype, Rust would blindly put the incoming network string directly into the private id field, bypassing our validation entirely. We override this behavior by implementing the Deserialize trait manually. When JSON or binary data arrives over the Kinetic network, our custom Deserialize block intercepts it. First, it uses the standard deserializer to parse the raw bytes into a normal, unverified String. Then, it immediately passes that unverified String to our strict KineticDid::new() function. If new() succeeds, we get our safe KineticDid. If new() fails, the entire network payload parsing is rejected and an error is thrown (serde::de::Error::custom).

Important

This guarantees that invalid DIDs cannot even enter the running application memory space. This makes debugging network payloads incredibly reliable.

Key Pieces

How This Connects to the Rest of Kinetic

FORWARD DEPENDENCY: Any component in the Kinetic network dealing with user identities, peer nodes, or cryptographic signatures will rely heavily on KineticDid. For example, when building the P2P networking layer or the underlying database schema, functions and structs will accept a KineticDid type instead of a String. This completely removes the need to clutter their business logic with string format validation, making the system much safer and easier to read.

CROSS-CRATE: Network payloads defined in other crates (like peer discovery messages or consensus blocks) will use KineticDid as a field type. Because of our custom Deserialize logic, the network parsing layer will automatically enforce our DID rules before the application logic even sees the incoming message. If a peer sends a malicious DID, the network layer drops it before the core node logic is even aware of it. By doing this, we guarantee that all network communication relies entirely on strictly verified DIDs.

Quick Reference

Open Questions / Things to Revisit

• Compile-time environment variable: Using env!("KINETIC_DID_PREFIX") means the did:kin: prefix is baked into the binary at compile time. Is there any scenario where we’d want this to be configurable at runtime, or is did:kin: totally permanent for the lifespan of the project?
• Proptests Expansion: The file currently includes a basic property-based test (Lines 80-91) ensuring the parser doesn’t panic or crash on garbage input strings. We should likely expand these proptests to ensure specific edge-case boundary conditions (like exactly 63 characters vs 65 characters) explicitly return the correct KidError variants, rather than just checking for crashes.
• Memory Allocation: Currently, KineticDid wraps a heap-allocated String. If we pass these around millions of times per second during consensus, the memory allocations could add up. We might want to revisit this later and explore using a fixed-size byte array (like [u8; 32]) internally to avoid heap allocations entirely while retaining the exact same Newtype safety guarantees.

Kinetic-KID: bounded.rs

Crate: kinetic-kid Stage: 06 Reading Time: 15 minutes Depends On: serde (external)

What Is This?

This module provides custom Serde deserialization helpers designed to strictly limit the maximum number of items in a deserialized array or vector. Rather than relying on standard Serde routines that happily ingest arrays of unlimited length, this code enforces a hard, unyielding cap at the exact moment of processing. It acts as an essential security gatekeeper during payload parsing in the Kinetic network. If a network peer tries to send a payload that exceeds these explicitly defined array lengths, the parser rejects it instantly instead of allocating unbounded memory. This file contains the primitive types and logic required to seamlessly integrate these bounded checks into standard Rust structs without writing custom parsers from scratch for every new network message struct.

Why Kinetic Needs This

In a decentralized network like Kinetic, we process un-trusted data sent from random peers over the open, unauthenticated internet. A classic attack vector against network nodes in systems programming is a “memory exhaustion attack” (often referred to as a memory bomb or resource exhaustion DoS). If we define a struct with a standard Vec<T>, a malicious actor could deliberately construct a payload with hundreds of millions of empty or tiny elements. Standard Serde arrays try to allocate memory to match the size of the incoming data before completely failing. If an attacker sends a JSON or binary document containing a massive array, Serde might attempt to allocate a multi-gigabyte vector on the heap right away.

Warning

This can easily crash our node by triggering a fatal Out Of Memory (OOM) panic in Rust, causing a catastrophic Denial of Service (DoS) across the network.

We absolutely must defend the node against this vector, as crashing nodes could partition the network. By wrapping list deserialization in explicit bounded caps, we guarantee our parsing logic aborts the exact moment an attacker exceeds the configured threshold. This approach prevents memory allocation attacks at the serialization boundary, ensuring Kinetic remains robust, predictable, and highly resilient under hostile network conditions.

How It Works

The standard deserialize provided by Serde is fully generic, meaning it has no inherent sense of maximum array bounds. To modify this core behavior, we implement our own deserialization logic using the Visitor trait.

Note

See RUST_CONCEPTS.md for an explanation of the serde::de::Visitor trait.

#![allow(unused)]
fn main() {
// See: kinetic-kid/src/bounded.rs — Lines 9 to 59
}

The custom behavior is driven by the internal BoundedVecVisitor<T> struct. When Serde detects a sequence, the visitor starts by defensively checking the size_hint() provided by the incoming sequence inside the visit_seq method.

#![allow(unused)]
fn main() {
// See: kinetic-kid/src/bounded.rs — Lines 37 to 41
}

If the underlying data format provides an upfront size (like knowing the array length in advance because of a binary prefix) and that size exceeds our hard max, we immediately return an invalid_length error.

Important

We do not allocate a single byte of heap memory for the vector yet. This is the optimal fast path for rejection, saving CPU cycles.

However, some formats (like streaming JSON) do not provide a size upfront. In those cases, we must allocate a vector to start storing the parsed elements, but we do so defensively and carefully.

#![allow(unused)]
fn main() {
// See: kinetic-kid/src/bounded.rs — Line 43
}

The capacity allocation is strictly limited to either the size hint or the max allowed limit, preventing us from pre-allocating an excessively large heap buffer. Then we begin to iterate through the sequence using seq.next_element()?, parsing and instantiating one element at a time.

#![allow(unused)]
fn main() {
// See: kinetic-kid/src/bounded.rs — Lines 46 to 55
}

For every single element popped off the wire and deserialized, we check if our running count has reached the max threshold. If it hits the ceiling, we immediately abort the while loop and return a custom Serde error indicating the boundary was crossed. This drops the partially built vector, freeing the memory instantly, and terminates the connection context via the bubbled-up Error. If the sequence ends before hitting the max, the returned vector is safely bounded and passed back into the struct being populated.

Key Pieces

BoundedVecVisitor<T>

#![allow(unused)]
fn main() {
// See: kinetic-kid/src/bounded.rs — Lines 9-21
}

This is the core struct driving the defensive parsing strategy. It holds a max value of type usize that determines the absolute ceiling for the array length.

Note

See RUST_CONCEPTS.md for PhantomData (used here to bind the generic type T without actually allocating it).

visit_seq

#![allow(unused)]
fn main() {
// See: kinetic-kid/src/bounded.rs — Lines 33-59
}

This is a required method on the Visitor trait where the actual bounded iteration logic lives. It is extremely important because this is the exact boundary layer where un-trusted network bytes are converted into Rust heap allocations. It correctly handles both early-abort checks using size hints, and mid-stream aborts if the incoming data stream deliberately hides its true length.

deserialize_max_20

#![allow(unused)]
fn main() {
// See: kinetic-kid/src/bounded.rs — Lines 66-72
}

A public helper function that sets up a visitor with a hard limit of exactly 20 elements. This is used across Kinetic when we know an array should be relatively small, such as a list of recent cryptographic signatures or short peer discovery lists.

deserialize_max_50

#![allow(unused)]
fn main() {
// See: kinetic-kid/src/bounded.rs — Lines 79-85
}

Similar to the above, but sets a hard limit of exactly 50 elements. Used for slightly larger payload arrays, such as transaction batches or mempool gossips, while still maintaining a strict memory bounds check against runaway allocations.

How This Connects to the Rest of Kinetic

FORWARD DEPENDENCY: You will see these exact helper functions heavily utilized across Kinetic’s core payload structures in other modules. Any struct that needs to be deserialized from a network payload and contains a Vec<T> should be explicitly annotated with #[serde(deserialize_with = "deserialize_max_20")] (or deserialize_max_50). Without this explicit annotation, the struct would silently fall back to Serde’s default, unbounded Vec deserialization, immediately re-opening the memory exhaustion attack vector.

CROSS-CRATE: This specific file acts as a foundational security primitive for the larger kinetic-network crate. When the peer-to-peer layer ingests raw bytes from a TCP/UDP socket, these bounds act as the absolute first line of defense, ensuring that maliciously crafted messages are dropped entirely without affecting the node runtime’s memory footprint or stability.

Quick Reference

Open Questions / Things to Revisit

• Currently, we only have hardcoded limits of 20 and 50 exposed as public helpers. Should we implement a Rust macro to generate generic bounded functions (e.g. 100, 500), or is this rigid approach safer for auditing? Having a small, fixed set of limits makes it easier to verify that developers aren’t accidentally allowing arrays of size 10,000 somewhere in the network crate.
• Is there a way to computationally penalize peers (e.g., lower their reputation score) at the network layer if they trigger the bound limit early in the connection phase to save bandwidth? We need to ensure we don’t accidentally penalize honest peers running outdated client software.
• Does the serde_json memory footprint still scale poorly with highly nested object structures (like { "a": { "b": { ... } } }) even if the child arrays themselves are strictly bounded? We might need a structural depth check in the future to defend against stack-overflow attacks.
• If we ever migrate from JSON payloads to a purely binary format like Bincode, do we still need this specific visitor, or does the binary format naturally prevent this type of resource exhaustion? Bincode often allocates based on size prefixes, so this vulnerability might actually be worse in binary if not handled correctly.
• Should we expose the BoundedVecVisitor directly so that other developers can use it in custom implementations, or keep it strictly encapsulated behind the deserialize_max_* macros?

01 — Overview and Errors

Crate: kinetic-verify
Stage: 2 of 10
Reading time: ~6 minutes
Depends on: kinetic-types
Source files: kinetic-verify/src/lib.rs (15 lines), kinetic-verify/src/error.rs (20 lines)

What Is This?

kinetic-verify is a highly specialized, ultra-lightweight cryptographic verification library for the Kinetic network. It acts as the mathematical bouncer for the network, ensuring that signatures and VDF proofs are valid before any heavy processing or storage occurs.

Why Kinetic Needs This

Why separate verification from kinetic-types or kinetic-network?

• Decoupling: P2P networking code is heavy and requires an operating system (sockets, threads). Verification is pure math. By keeping it separate and no_std compatible, you can compile the verification logic into an offline hardware wallet or a browser extension that doesn’t need to run a full node.
• Security: When a node receives a message, it needs to verify the cryptographic signatures before spending CPU cycles processing it. Having a dedicated verify crate ensures this critical boundary is cleanly enforced.

How It Works

Currently, this crate is extremely minimal (35 lines of code total). Its primary job right now is establishing the boundary and exporting the types needed for verification.

• It defines constants that all nodes must agree on (like MAX_PAYLOAD_SIZE).
• It exports the VDF types (from kinetic-types) so that downstream crates can just import kinetic-verify to get both the types and (eventually) the verification functions.
• It defines VerifyError to categorize exactly how a verification can fail.

Key Pieces

RESQUARING_EPOCH_KYNS

#![allow(unused)]
fn main() {
RESQUARING_EPOCH_KYNS
}

• What it does: A constant set to 5,256,000.
• Location: lib.rs:8
• Why it matters:

  Note

  At 3 seconds per Kyn, 5.25 million Kyns equals exactly 182.5 days (half a year). This is the network’s resquaring epoch interval. In VDF cryptography, proofs get larger over time, so the network must periodically “resquare” or reset the baseline to prevent proofs from taking too long to verify.

MAX_PAYLOAD_SIZE

#![allow(unused)]
fn main() {
MAX_PAYLOAD_SIZE
}

• What it does: A constant set to 65,536 (64 KB).
• Location: lib.rs:10
• Why it matters:

  Important

  This is the hard limit on the size of a name reveal payload. Without this, a malicious actor could submit a 10 GB payload, causing all nodes on the network to run out of memory trying to store or verify it.

VerifyError

#![allow(unused)]
fn main() {
VerifyError
}

• What it does: An enum with three variants: InvalidSignature, MalformedPublicKey, MalformedSignature.
• Location: error.rs:6-19
• Why it matters:

  Warning

  It is critical to distinguish why verification failed. A MalformedPublicKey might mean network corruption (a byte got flipped in transit). An InvalidSignature means the math doesn’t check out, which usually implies deliberate forgery or a malicious actor.

How This Connects to the Rest of Kinetic

• CROSS-CRATE: This crate re-exports the VDF types (Commitment, Reveal, VdfProof, etc.) which are defined in docs/learn/types/05_vdf_types.md.
• FORWARD DEPENDENCY: kinetic-kid and kinetic-core will consume this crate to validate incoming registrations and capability manifests.
• FORWARD DEPENDENCY: vdfrs and kyn-vdf (the actual math engines) will be hooked into this crate to provide the deep algebraic verification.

Quick Reference

• Crate Size: ~35 lines of code.
• no_std: Designed to run without an operating system.
• Epoch: 182.5 days (RESQUARING_EPOCH_KYNS).
• Max Payload: 64 KB (MAX_PAYLOAD_SIZE).

Open Questions / Things to Revisit

• Missing implementation: Right now, this crate only defines the errors and exports types, but it doesn’t contain any actual verify() functions (like the ML-DSA-65 signature checks). Are those checks currently living directly inside kinetic-types (which violates the separation of concerns), or are they planned to be moved here?
• Severity mapping: VerifyError currently does not implement a severity() method returning Severity::Critical or Severity::Warning like the errors in kinetic-types. This should be added so network nodes know how to handle these failures automatically.

01 — Overview

Crate: kyn-vdf Stage: 6 of 10 Reading time: ~5 minutes Depends on: kinetic-vdf (conceptually)

What Is This?

kyn-vdf is Kinetic’s pure-Rust implementation of Verifiable Delay Functions. It implements Imaginary Quadratic Class Groups, Shanks’ composition algorithms, and Wesolowski verification entirely from scratch in safe Rust.

Warning

(Note: While the core math is pure-Rust, the crate lacks the #![no_std] attribute and relies on thiserror, which inherently pulls in std).

Why Kinetic Needs This

In Stage 5 (kinetic-vdf), you saw that generating a VDF proof requires the heavy C++ chiavdf library. However, a major goal of Kinetic is to allow web browsers, mobile phones, and IoT devices to connect to the network as light clients without installing C++ toolchains. By writing the verification logic in pure Rust, kyn-vdf can be compiled directly to WebAssembly (WASM). This allows any web page to instantly verify 30 days of CPU time cryptographically, ensuring light clients do not have to blindly trust central servers.

How It Works

At its core, this crate performs math on large numbers (1024-bit integers).

1. It deterministically derives a prime number (the Discriminant $D$) using SHA-256 and Miller-Rabin tests.
2. It parses a compressed 100-byte BQFC network payload into a Quadratic Form $(a, b, c)$.
3. It performs sub-quadratic Euclidean exponentiation using Shanks’ NUCOMP and NUDUPL algorithms.
4. It checks the Wesolowski equation $\pi^B \cdot x^r = y$ to guarantee the proof is valid.

Key Pieces (Topic File Breakdown)

This crate is composed of ~1,480 total lines of code, broken down into the following dense mathematical topics:

1. 02_math_core.md — Defines the Form struct and the Gauss reduction algorithms to keep numbers canonical.
2. 03_math_comp.md — The complex Shanks’ NUCOMP and NUDUPL algorithms for fast algebraic composition.
3. 04_chia_prime.md — HashPrime and Discriminant derivation via the Miller-Rabin primality test.
4. 05_chia_bqfc.md — Binary Quadratic Form Compression (BQFC) to squish 130 bytes of data into exactly 100 bytes for optimal network MTU routing.
5. 06_verify.md — The Wesolowski verification equation that makes the entire time-lock system possible.

How This Connects to the Rest of Kinetic

• FORWARD DEPENDENCY: The network daemon (kinetic-daemon) will embed this crate to verify every single transaction.
• CROSS-CRATE: The C++ wrapper from Stage 5 (kinetic-vdf) uses this crate to perform continuous differential fuzzing to ensure the C++ and Rust engines never fork.

Quick Reference

• Total Lines: 1,480
• Math Type: Imaginary Quadratic Class Groups
• Primary Dependency: num-bigint
• WASM Compatible: Yes (though restricted by std usage via thiserror)

kyn-vdf: Imaginary Quadratic Class Groups Math Core

Crate: kyn-vdf Stage: 2 Reading Time: 40 minutes Depends On: 01_vdf_overview.md (Conceptual overview of VDFs)

What Is This?

This document breaks down the mathematical foundation of the Verifiable Delay Function (VDF) implementation in the Kinetic network. Specifically, it provides an explanation of the mathematical operations over Imaginary Quadratic Class Groups. These class groups provide the non-parallelizable, deterministic time-delay necessary for our network’s consensus mechanism to function safely. This file specifically documents the core operations found in kyn-vdf/src/math.rs (lines 1-226). It acts as the strict foundational bedrock for the entire cryptographic pipeline. It defines binary quadratic forms, encompassing arbitrary precision arithmetic, Shanks NUCOMP threshold calculations, partial Euclidean steps, and Gauss reduction algorithms. All of this is implemented in purely deterministic Rust code to ensure cross-network consensus stability and bit-for-bit accuracy. Without the precise mathematics in this file, Kinetic would not be able to securely elect block producers. It would also fail to verify elapsed time in a decentralized manner, which is the entire premise of the Kinetic network. This math forms the strict computational wall that prevents attackers from rushing or manipulating the network’s internal clock. It is the heart of the Kinetic VDF and the absolute source of truth for the entire sequence of squarings. Understanding this file is for anyone working on the consensus layer. It marries advanced algebraic number theory with low-level systems engineering.

Why Kinetic Needs This

At the very heart of Kinetic’s network security model is the Verifiable Delay Function (VDF). A VDF is a cryptographic primitive that guarantees that a certain amount of sequential computational time has unequivocally elapsed. This verifiable proof of elapsed time is crucial for preventing malicious actors from rushing the consensus process. In a proof-of-stake system like Kinetic, unpredictable randomness is required to elect leaders safely and fairly. If the randomness generation is instant, attackers can simulate thousands of forks and pick the one where they win the election. A VDF acts as an “randomness beacon” for the entire network. It prevents attackers from predicting or manipulating future block producers by forcing a , unavoidable time delay on the randomness generation.

To achieve this sequential delay, we need a mathematical structure known as a “group of unknown order”. In a group of known order, an attacker can use shortcut calculations (like Euler’s theorem) to compute the final result instantly. By bypassing the sequential delay entirely, the VDF loses its primary property and the network becomes vulnerable to immediate takeover. While standard RSA groups are indeed of unknown order, they come with a fatal flaw: they require a trusted setup.

Warning

A trusted setup means a trusted party must generate the prime factors and then securely destroy them. This represents a centralization risk and a single point of failure that Kinetic refuses to accept.

Imaginary Quadratic Class Groups offer a elegant, trustless alternative to RSA. We can generate a class group of unknown order simply by using a large negative prime number. This number is called a fundamental discriminant, commonly denoted as $D$. Because $D$ is just a prime number (which can be deterministically derived from a block hash), this entirely eliminates the need for a trusted setup phase. This preserves the true, permissionless decentralization of the Kinetic network from the genesis block onwards.

However, this mathematical elegance comes with heavy, engineering requirements. First, we must deal with integers to maintain robust cryptographic security against modern hardware and ASICs. For a standard 128-bit cryptographic security level, our discriminant $D$ needs to be a negative prime number that is thousands of bits long. Typically, in the Kinetic protocol, this means a 1024-bit or 2048-bit negative prime integer. Standard Rust primitive types like u64 or u128 simply cannot hold values of this enormous magnitude. This is exactly why we depend on the num-bigint crate to handle all values as heap-allocated BigInt objects. Without BigInt, we would not be able to store our parameters, let alone perform multi-million iteration squarings on them. These objects dynamically allocate memory to store as many bits as required for the calculation.

Second, the system demands absolute, bit-perfect determinism across the entire global network. Kinetic is a decentralized network running on heterogeneous hardware, from cloud servers to desktop PCs. When a node computes a VDF proof, every other node in the network must be able to verify it independently. They must arrive at the exact same mathematical conclusion down to the final bit, without exception. This means we cannot rely on floating-point arithmetic for any part of the calculation. Standard operations like f64::sqrt() are forbidden in our consensus-critical code. Floating-point precision, rounding behavior, and NaN handling can vary subtly between different CPU architectures (such as x86 vs ARM). Furthermore, different compiler optimizations can alter the order of operations, changing the final result of floating-point math. If nodes disagree on the result of a math operation by even a single bit, the network would instantly fork and fail to reach consensus. Therefore, every single calculation in math.rs must be , integer-based.

Finally, we need extreme, performance. VDFs are evaluated continuously by nodes, requiring billions of sequential squaring operations to prove elapsed time. If our BigInt math is inefficient, the baseline delay becomes artificially inflated. The sequential delay would be caused by memory allocations and garbage collection rather than actual cryptographic operations. This is why you will see a heavy reliance on passing variables by reference (e.g., &BigInt) rather than taking ownership. Taking ownership causes cloning, which means allocating new space on the heap, copying bytes, and eventually dropping the memory. Minimizing these costly heap allocations during the billions of additions and multiplications is a top architectural priority for kyn-vdf. Every single microsecond saved in the math core translates directly to a faster, more secure network. By passing immutable and mutable references , we allow the compiler to reuse memory allocations.

How It Works

The entire mathematical mechanism of the class group operates on structures known as “Binary Quadratic Forms”. A binary quadratic form is a homogeneous polynomial of degree two in two variables. Specifically, it takes the form $f(x, y) = ax^2 + bxy + cy^2$. In our codebase, we typically represent this polynomial simply as a tuple of its coefficients: (a, b, c). For a given negative discriminant $D$, these forms operate as the group elements of our cryptographic class group. The equivalence classes of these forms under modular transformations form a finite abelian group. This mathematical group provides the exact algebraic structure needed to chain squaring operations for the VDF.

In kyn-vdf/src/math.rs, the code is structured into a tight pipeline that supports two main operations. The first operation is composing two forms together (or squaring a form with itself). The second operation is reducing a form back to its canonical, minimal representation. Because the coefficients grow fast when composing forms, we use a sophisticated algorithm. This algorithm is called Shanks NUCOMP, and it keeps the coefficients as small as possible throughout the intermediate steps of the computation. Let’s walk through the exact flow of the code from lines 1 to 226 in extensive detail to understand this pipeline.

1. Calculating the NUCOMP Threshold

-> See: kyn-vdf/src/math.rs — Lines 10 to 45

When we compose two quadratic forms , the resulting coefficients can grow exceptionally large. Without optimization, they can easily grow to the size of $D^2$, which ruins cache locality and dramatically reduces performance. Shanks NUCOMP is a algorithmic optimization that performs a partial reduction during the composition step itself, rather than waiting until the end. By reducing early, it prevents the intermediate numbers from ever getting that large in memory, speeding up the overall calculation.

To know exactly when to stop this partial reduction, the NUCOMP algorithm requires a specific threshold value, usually denoted as $L$. This threshold is defined as the fourth root of the absolute value of the discriminant: $L = |D|^{1/4}$. In lines 10-45, we implement the isqrt_fourth(n) function to calculate this critical threshold. Because we are forbidden from using floating point math for consensus, this function computes the integer square root twice in succession. Applying the integer square root twice yields the integer fourth root exactly. It uses a purely deterministic Newton-Raphson method adapted for integer arithmetic. The algorithm starts with an initial, conservative guess and iteratively refines it using integer division and averaging. By staying entirely in integer space, we guarantee perfect consistency across all platforms. We ensure that every single Kinetic node calculates the exact same threshold $L$, down to the last bit. This is true regardless of whether the node is running on a high-end Intel server or a low-power ARM device. The function is written carefully to manage memory by reusing local mutable variables during the Newton-Raphson loop, avoiding excess allocations. It ensures that the fourth root calculation, while slightly slower than a hardware floating point equivalent, is 100% deterministic. This function is a great example of rewriting standard math primitives exclusively for cryptographic contexts.

2. The Partial Extended Euclidean Algorithm

-> See: kyn-vdf/src/math.rs — Lines 47 to 95

The standard Extended Euclidean Algorithm (XGCD) is a foundational algorithm in computational number theory. It finds the greatest common divisor of two integers and simultaneously computes the coefficients of Bézout’s identity. However, for the Shanks NUCOMP optimization, we do not want to run the XGCD all the way to completion. Instead, we run a specialized, modified version known as a “Partial” XGCD.

In the xgcd_partial function, we pass in two BigInt values and the specific threshold $L$. This threshold $L$ is exactly the value we just computed using the isqrt_fourth function. The loop inside this function executes the standard Euclidean division steps: dividing, finding the remainder, and shifting variables. But crucially, it includes a strict early-exit condition that defines the “partial” nature of the algorithm. It halts the moment the remainder drops below the threshold $L$.

Notice how heavily this specific section of code relies on Rust references and borrowing syntax. Mathematical operations like a = &b - &q * &r are written with explicit borrows on every single operand. If we were to blindly clone these 1024-bit integers on every single iteration of the Euclidean algorithm loop, performance would tank immediately. The memory allocator would thrash, and the VDF would become far too slow to run on consumer-grade hardware. By using references, the num-bigint crate can perform the arithmetic using the existing backing vectors. This minimizes the stress on the global system allocator and keeps the CPU cache piping hot for maximum instruction throughput. This pattern of utilizing references for num-bigint arithmetic is a hallmark of Kinetic’s cryptographic optimizations. Understanding lifetime scopes and borrow checking is critical to making sense of these dense mathematical loops.

3. Representing the Quadratic Form

-> See: kyn-vdf/src/math.rs — Lines 97 to 120

In this section, we define the central data structure of the entire crate: the Form struct. It is defined simply as a struct holding exactly three BigInt fields, named a, b, and c. These three fields map directly to the coefficients of our binary quadratic form $ax^2 + bxy + cy^2$. The quadratic form has deep connections to ideals in quadratic fields, making it the perfect algebraic structure for our group operations. There is a fundamental, mathematical invariant that this struct must always maintain at rest. The discriminant of the form must always equal the network’s globally chosen $D$. In equation terms, this means that the relation $b^2 - 4ac = D$ must always hold true for any valid form. This relation directly mirrors the standard quadratic formula discriminant, and it ties the specific form back to the global class group. If a form ever violates this invariant, it is invalid, cryptographically useless, and represents a critical consensus failure.

The struct provides various initialization methods to safely construct forms, ensuring the invariant holds upon creation. It carefully initializes the identity element of the class group, which is required to start the VDF sequence. More importantly, it provides the target receiver for our next, and most crucial, operation: reduction. The Form struct also implements traits like Clone and PartialEq. However, you must be careful: equality checking is only meaningful if both forms are in their reduced state. Comparing two unreduced forms directly via PartialEq is a logical error, as they may represent the exact same mathematical element in the class group but have wildly different coefficients. The system relies on strict reduced-form comparisons during the verification step to ensure consensus agreement. To avoid bugs, equality comparisons should always be preceded by a call to reduce().

4. Gauss Reduction Algorithm

-> See: kyn-vdf/src/math.rs — Lines 122 to 226

When operations like composition or squaring are performed on forms, they naturally become “unreduced”. An unreduced form represents the exact same mathematical equivalence class as a properly reduced form. However, its coefficients $a$, $b$, and $c$ are unnecessarily large and non-canonical. In order to deterministically compare forms (which the verifier must do to check the VDF proof), they must be standardized. They must be converted back into a unique, canonical state known as the “reduced” state. The reduce() method implements the classical Gauss reduction algorithm for this exact standardization purpose.

Gauss reduction is conceptually similar to the Euclidean algorithm, but it operates on two-dimensional quadratic forms instead of one-dimensional integers. A binary quadratic form is considered properly, reduced if and only if two strict conditions are met. First, the coefficients must satisfy the primary inequality: $-a < b <= a < c$. Second, if $a$ happens to exactly equal $c$, then $b$ must be greater than or equal to $0$. The reduce() function uses a mutable while loop that repeatedly applies two core normalization steps until these precise conditions are met.

The first step is logically called “Normalize B”. It shifts the value of the $b$ coefficient so that it falls precisely into the mathematical range $(-a, a]$. This step involves calculating a shift factor $q$ via a careful integer division. It then updates both the $b$ and $c$ coefficients accordingly using this calculated shift factor, preserving the overall discriminant invariant throughout the transformation. The preservation of the discriminant invariant is verified via robust unit testing, but logically it is guaranteed by the algebraic shifts applied. This step acts as a sliding window that bounds the size of $b$.

The second step is logically called “Minimize A”. If the coefficient $a$ is greater than $c$, the form is fundamentally unbalanced and clearly violates the reduction condition. To fix this imbalance, the algorithm dynamically swaps the values of $a$ and $c$, and simultaneously negates the value of the $b$ coefficient. This elegant mathematical swap immediately makes the new $a$ coefficient smaller than the new $c$ coefficient. This step acts as the primary driver of reduction, constantly pushing the maximum values downwards with every loop iteration.

The main loop in lines 122-226 alternates continuously between these two critical normalizations. Because the coefficient $a$ decreases every single time a swap operation occurs, the algorithm is guaranteed to eventually terminate. The heavy use of BigInt mutable references in this section is perhaps the single most performance-critical code in the entire repository. Gauss reduction runs iteratively after every single composition step in the main VDF prover loop. If this specific reduction loop is slow, the entire network’s baseline VDF delay increases, harming network throughput. Any future optimizations to Kinetic’s underlying math library will undoubtedly start right here in reduce().

Key Pieces

This section breaks down the critical components you need to understand in this file.

isqrt_fourth(n: &BigInt) -> BigInt

#![allow(unused)]
fn main() {
isqrt_fourth(n: &BigInt) -> BigInt
}

• What it does: Computes the deterministic integer fourth root of a number $n$.
• File:Line: kyn-vdf/src/math.rs — Lines 10-45.
• Why it matters: It calculates the foundational $L$ threshold required by the Shanks NUCOMP optimization.

Important

If this value is computed incorrectly by even a single bit, the partial XGCD will stop at the wrong time. Stopping at the wrong time corrupts the intermediate state and invalidates the entire VDF output, rendering the proof useless. The strict integer-only implementation is the bedrock that guarantees network-wide consensus determinism.

xgcd_partial(a: &BigInt, b: &BigInt, limit: &BigInt) -> (BigInt, BigInt, BigInt)

#![allow(unused)]
fn main() {
xgcd_partial(a: &BigInt, b: &BigInt, limit: &BigInt) -> (BigInt, BigInt, BigInt)
}

• What it does: Runs the Extended Euclidean Algorithm but forces a strict early stop when the remainder is less than or equal to the limit.
• File:Line: kyn-vdf/src/math.rs — Lines 47-95.
• Why it matters: It is the true computational engine of the Shanks NUCOMP optimization strategy. By strategically stopping the Euclidean algorithm early, we extract the exact intermediate Bézout coefficients needed for composition. These precise coefficients allow us to compose two forms without letting their intermediate values explode in system memory. This partial step is the crux of how Kinetic maintains memory-efficient group operations at scale.

struct Form

#![allow(unused)]
fn main() {
struct Form
}

• What it does: Represents the abstract mathematical object $ax^2 + bxy + cy^2$ using three arbitrary-precision BigInt fields.
• File:Line: kyn-vdf/src/math.rs — Lines 97-120.
• Why it matters: This simple struct is the atomic unit of the entire VDF architecture. The entire VDF computation is functionally just a long, sequential chain of squaring Form objects millions of times. It securely holds the cryptographic state that is ultimately passed between the prover and the verifier over the network. Without a tight, efficient Form abstraction, the code would be a sprawling mess of loose variables.

Form::reduce(&mut self)

#![allow(unused)]
fn main() {
Form::reduce(&mut self)
}

• What it does: Canonicalizes a quadratic form in-place so its internal coefficients satisfy the strict Gauss reduction inequality conditions.
• File:Line: kyn-vdf/src/math.rs — Lines 122-226.
• Why it matters: Without this mandatory reduction step, the coefficients $a$, $b$, and $c$ would grow with every single squaring operation. They would quickly consume gigabytes of memory and exhaust all available RAM on the node, fatally crashing the system. Reduction guarantees that the coefficients stay tightly bounded safely by the size of the discriminant $D$. It also ensures that every single node arrives at the exact same canonical representation for final verification. Verification hinges entirely on forms matching identically after reduction.

How This Connects to the Rest of Kinetic

This mathematical foundation is not an isolated academic exercise. It is deeply, inextricably wired into the cryptographic layers of the network and directly drives the consensus engine.

• FORWARD DEPENDENCY: kyn-vdf/src/prover.rs The prover module takes a starting Form and squares it $T$ times consecutively to generate the delay. To achieve this sequential squaring, it continuously and repeatedly calls both xgcd_partial and Form::reduce in a tight loop. The execution efficiency of the code in math.rs directly dictates how fast the prover can physically run on given hardware. This hardware speed, in turn, structurally defines the network’s minimum possible block delay.

• FORWARD DEPENDENCY: kyn-vdf/src/verifier.rs The verifier module uses the exact same mathematical operations defined here. It uses them to check the Wesolowski proof provided by the remote prover node. The verifier requires absolute, exact deterministic agreement on the reduce() outputs to accept a proof as valid and safe. Any discrepancy in math.rs means the verifier will falsely reject a valid proof.

• CROSS-CRATE: kinetic-core The core consensus mechanism in the kinetic-core crate relies heavily on the VDF as an , trustless clock. It treats the finalized, reduced Form output as a secure source of pseudo-randomness for electing the next block producer. If the underlying math in this file is flawed, the random seed generation for leader election breaks down, stalling the chain. kinetic-core trusts math.rs to provide the randomness needed for Proof of Stake.

Quick Reference

Here are the essential mathematical facts you need to memorize about this module.

• Primary Group Operation: Composition and Squaring of Binary Quadratic Forms.
• Discriminant ($D$) Size: Typically 1024 to 2048 bits (must be a negative prime number).
• Shanks NUCOMP Threshold ($L$): Defined as the fourth root of the absolute value of $D$ ($|D|^{1/4}$).
• Gauss Reduction Condition 1: The coefficients must satisfy $-a < b <= a < c$.
• Gauss Reduction Condition 2: Alternatively, if $a = c$, then $b >= 0$.
• Data Types: All heavy computation exclusively relies on num-bigint::BigInt for arbitrary precision.

Caution

• Determinism Constraint: NO FLOATING POINT math is allowed under any circumstances, ever, to prevent consensus forks.

• Memory Strategy: Aggressive use of references (&BigInt) and mutable in-place operations (&mut self) to avoid expensive heap allocations.
• Fundamental Invariant: The equation $b^2 - 4ac$ must always equal $D$ at all resting states.

Open Questions / Things to Revisit

There are several rough edges, architectural questions, and areas for future optimization in this file.

• Memory Allocations in reduce: Even with careful use of references, num-bigint occasionally reallocates internal backing vectors during division and modulo operations. We need to profile the reduce() function under heavy, sustained load to identify these hidden allocations. We should investigate if we can pre-allocate scratch space buffers to eliminate the remaining heap allocations and stabilize the garbage collector. This could provide a speedup for the prover.

• Alternative Math Backends: Currently, we use the num-bigint crate because it provides pure Rust compatibility, safety, and ease of auditing. However, GMP (GNU Multiple Precision Arithmetic Library) is widely known to be significantly faster for numbers of this specific 1024-bit size. Should we seriously consider a C-FFI wrapper to GMP for high-performance nodes that want to run optimized provers? If we do make this architectural shift, we must prove that determinism is preserved across the FFI boundary, which is risky.

• Constant Time Execution Considerations: Classical Gauss reduction is fundamentally a variable-time algorithm by its mathematical nature. Its actual execution time depends heavily on the specific coefficients being reduced during the loop. In the context of a VDF prover, this is generally acceptable because we actually want the prover to run as fast as natively possible. Furthermore, VDF proofs are inherently evaluated on public data, meaning secrecy is not the primary concern. However, we need a thorough, professional security audit to ensure this doesn’t open up any obscure timing side-channel attacks on the verifier side of the protocol.

• NUCOMP vs Standard Composition Crossover: For very small discriminants, the computational overhead of calculating xgcd_partial might actually be worse than just doing standard Arndt composition and then a full reduction. We should establish comprehensive benchmarks to find the exact performance crossover point where NUCOMP becomes superior to standard composition. This might allow us to switch algorithms dynamically based on the discriminant size for optimal performance.

• WebAssembly Compatibility: If we eventually want light clients or browser wallets to verify VDFs natively in the browser, this math must compile cleanly and efficiently to Wasm.

Important

We need to verify that our aggressive use of num-bigint does not introduce any Wasm-incompatible instructions or performance regressions when compiled to WebAssembly targets.

• Parallel Reduction Exploration: While the VDF itself is sequential by cryptographic design, could micro-parts of the reduction algorithm be parallelized safely using SIMD instructions? We need to deeply investigate if modern CPU vector extensions (like AVX-512) can accelerate the normalization steps without breaking the strict bit-level determinism requirement.

kyn-vdf: Math Composition (Stage 3)

Reading Time: 35 minutes Depends On: kyn-vdf/src/form.rs, kyn-vdf/src/xgcd.rs

What Is This?

This file contains the optimized mathematical foundation for multiplying and squaring elements within an imaginary quadratic class group. It fundamentally implements the exact algebraic rules required to advance the Verifiable Delay Function (VDF) state securely. Specifically, it provides Shanks’ NUDUPL algorithm for efficiently squaring a single form in the class group space. It also provides Shanks’ NUCOMP algorithm for efficiently composing two different forms together . Finally, it includes a fast binary exponentiation method to raise a given form to an arbitrary, integer power. These complex algorithms take one or two quadratic forms as inputs to begin the computational process. They perform structured polynomial transformations on these specific input variables. They then securely return a canonical reduced product form representing the final outcome. The internal logic heavily leverages the extended Euclidean algorithm to prevent intermediate numbers from growing too large. This careful, deliberate bounding of coefficient sizes ensures that memory allocations remain small and predictable throughout execution. Ultimately, this specific file serves as the absolute core cryptographic engine that guarantees the un-forgeable delay. This un-forgeable delay is what the entire Kinetic network consensus relies upon to function properly. Without this precise implementation, the network would collapse due to forged timestamps. It acts as the strict timekeeper for a globally distributed, trustless environment. Every line of code here represents a carefully considered tradeoff between mathematical purity and bare-metal performance.

Why Kinetic Needs This

Kinetic relies entirely on a Verifiable Delay Function to cryptographically prove that real-world time has elapsed between blocks. This cryptographic proof is actively generated by sequentially computing an immense number of repeated squarings. These sequential squarings happen inside a specialized mathematical structure called an unknown-order group. In our unique architecture, this unknown-order group is defined as an imaginary quadratic class group. This class group uses a carefully selected, cryptographically secure large prime discriminant. The standard, academically pure way to multiply two class group forms is widely known as naive Gaussian composition. However, naive Gaussian composition presents an insurmountable performance challenge for a high-throughput network like Kinetic. During naive Gaussian composition, the intermediate coefficients (a, b, c) balloon to large, unmanageable sizes. These sizes naturally occur immediately before the final standard reduction step is finally permitted to clean them up. Specifically, they can rapidly grow up to the exact mathematical square of the absolute size of the underlying network discriminant. If Kinetic uses a standard, secure 2048-bit discriminant, naive composition would routinely generate intermediate numbers exceeding 4096 bits. Performing raw mathematical arithmetic on 4096-bit numbers is more computationally expensive than operating on 2048-bit numbers. It is also significantly more memory-intensive across the entire hardware execution pipeline. It demands vastly more CPU cycles per individual multiplication, addition, or division instruction. It also forces the underlying system allocator to handle , unpredictable heap allocations continuously. Since generating a VDF proof fundamentally requires many millions of sequential squarings, this performance overhead compounds . Even a microscopic microsecond slowdown per single squaring operation destroys the absolute reliability of the global delay guarantee. This cascading failure breaks the core consensus timing assumptions entirely. Furthermore, it would slow down all other honest nodes on the broader network. These honest nodes must verify the block accurately before safely accepting it into their local decentralized chain. To resolve this critical computational bottleneck, Kinetic mandates the exclusive use of Shanks’ algorithms. Specifically, it enforces the NUDUPL and NUCOMP algorithms for all class group operations without exception. These specialized algorithms intercept the intermediate components before they are ever allowed to explode in memory size. They apply a partial extended greatest common divisor (XGCD) routine directly mid-calculation. This mid-calculation intervention actively reduces the internal values dynamically and predictably. This specific methodology guarantees that the intermediate BigInt structures stay bounded. They generally remain very close to the exact original bit-size of the discriminant itself throughout the entire execution lifetime. bounded sizes logically mean that dynamic memory allocations remain entirely predictable. They are remarkably cache-friendly and significantly faster to process directly at the hardware CPU level. By relying on these specific, tuned optimizations, Kinetic levels the computational playing field. This creates a fundamentally fair network for all disparate participants regardless of hardware budgets. If the operation were intentionally memory-hard instead of purely sequential, attackers could easily utilize specialized memory architectures. This would allow them to calculate the VDF faster and maliciously manipulate the network timestamp mechanism. Hardware advantages like parallel ALUs or expensive custom FPGAs become bottlenecked. They are constrained by the inherently sequential, step-by-step nature of this exact bounded arithmetic design. Without math.rs and its tuned, memory management, Kinetic’s consensus mechanism would be slow and insecure. It would be instantly vulnerable to well-funded participants leveraging superior, specialized computing hardware. Therefore, the density and performance of this single file arguably define the security perimeter of the entire Kinetic ecosystem.

How It Works

The overarching execution flow within this file is an absolute masterclass in managing arbitrary-precision BigInt memory allocations. It manages these allocations safely while performing dense, cryptography over complex algebraic structures. The entire mathematical processing pipeline is divided into three primary algorithms. Each of these algorithms serves a distinct, irreplaceable, and designed role in the full VDF lifecycle. The overall engineering objective here is to ensure that no single operation causes an unexpected garbage collection pause. It is equally critical that no operation forces the host CPU to catastrophically stall on predictable cache misses.

1. Shanks’ NUDUPL (Squaring)

-> See: kyn-vdf/src/math.rs — Lines 227 to 310 NUDUPL is unequivocally the absolute core of the prover’s execution loop. It easily ranks as the most frequently executed single function anywhere in the entire Kinetic network stack. It is a specialized variant of Shanks’ composition and exclusively tailored for squaring a single mathematical form. When a cryptographic form is composed with itself, many algebraic terms gracefully cancel each other out. This symmetric cancellation and permanently reduces the initial processing overhead. This is heavily contrasted with the much slower process of composing two entirely different forms together. The algorithm starts execution by cleanly extracting the a, b, and c coefficients directly from the input form’s state. It carefully avoids unnecessary copying during this initial coefficient extraction phase. It then immediately triggers the optimized partial extended Euclidean algorithm. This trigger occurs via a strict, direct call to the dedicated xgcd_partial function module. Instead of running naively until a full, final zero remainder is predictably reached, xgcd_partial is instructed to stop early. It deliberately halts its internal iterative loop exactly when the computed remainders cross a specific mathematical threshold. This strict threshold is precisely the fourth root of the absolute mathematical value of the network discriminant. This deliberate premature termination yields a specialized 2x2 mathematical transition matrix. This matrix is composed of remarkably small, easily manageable integer coefficients. The algorithm carefully takes this small transition matrix and cross-multiplies it iteratively with the original form components. This specific matrix cross-multiplication yields a brand new set of mathematical coefficients . Crucially, these newly minted coefficients are naturally, already partially reduced by design. By performing this precise matrix multiplication sequence, NUDUPL skips the dangerous computational phase entirely. This skipped phase is exactly where naive coefficients would have normally, disastrously doubled in bit length. This section heavily and intentionally utilizes Rust’s powerful num_integer::Integer trait to execute precise division semantics. Specifically, it relies on div_floor and mod_floor rather than using the basic native operators built into the Rust language. In strict cryptographic mathematics over class groups, taking a modulo of any negative number must universally wrap around. It must always wrap directly to a positive remainder to maintain structural integrity. Rust’s standard % operator simply truncates the division lazily toward zero. This default truncation yields destructive negative remainders for all negative inputs. Using % here would instantaneously corrupt the deep structural validity of the class group form permanently. This would result in invalid VDF proofs being broadcast to the network. After the transition matrix is successfully and safely applied, NUDUPL always triggers a standard, final reduction step. This final reduction logically guarantees that the newly squared form is canonical, unique, and minimal. Memory management dynamically here requires meticulous, manual oversight to ensure high performance without memory leaks. Because BigInt structures reside exclusively on the heap by design, they naturally drop their memory when fully consumed by an operator. The codebase heavily utilizes cleanly borrowed references (e.g., &a + &b) to securely execute arithmetic. It does this without erroneously taking permanent ownership of the transient variables. It manually triggers an explicit clone() only when a specific intermediate value must be preserved. This preservation only happens across volatile mutable boundaries for a subsequent, necessary calculation step.

2. Shanks’ NUCOMP (General Composition)

-> See: kyn-vdf/src/math.rs — Lines 312 to 420 NUCOMP brilliantly generalizes the fast composition logic to handle two different mathematical forms safely. Because the raw inputs are inherently distinct and asymmetric, the algorithm simply cannot rely on the symmetric mathematical cancellations. It cannot use the elegant shortcuts that NUDUPL heavily exploits for raw speed. Instead, it must painstakingly compute the full, unadulterated greatest common divisor . It computes this GCD specifically between the respective a coefficients of both individual input forms. This heavy initial phase involves safely calculating specific intermediate structural values correctly. These values are consistently referred to as s and m in deep academic cryptographic literature. Once these foundational values are cleanly found, the algorithm proceeds carefully to solve a series of strict linear congruences. The ultimate, necessary objective of these complex, interconnected congruences is to discover a single unified structural variable. This critical variable is typically denoted simply as V in the codebase. This specific variable V must uniquely and simultaneously satisfy two rigid, independent modular constraints. These precise constraints actively involve the original, unmodified b coefficients of the parent forms. V essentially acts as the critical mathematical bridge required to merge the independent states. It merges the states of the two distinct input forms into a single cohesive mathematical entity. If the protocol naively combined the forms directly using V right away, disaster would strike. The resulting leading A coefficient would instantaneously explode in size directly to the product of a1 * a2. NUCOMP elegantly and robustly prevents this impending, memory explosion . It does this by immediately feeding the discovered V and the original coefficients cleanly into xgcd_partial. Exactly like the NUDUPL implementation, it reliably retrieves a specialized transition matrix directly based exclusively on early-stopping GCD remainders. The various mathematical components of the two parent forms are then carefully cross-multiplied with this specific transition matrix. This cross-multiplication produces the final, safely bounded coefficients representing the merged state. This complex phase necessarily involves an high volume of temporary, volatile BigInt allocations in memory. These allocations are immediately, ruthlessly dropped from local scope immediately after their singular use. Managing these precise lifetimes safely during these dense, chaotic matrix multiplications is critical. It is the only reliable way to avoid devastating, compilation-halting borrow-checker errors in Rust. Finally, a standard, rigorous reduction pass is reliably applied to definitively yield the canonical product. This ensures the final representation of the two composed forms is minimal and unique. Because of the heavy initial GCD computations and complex, demanding congruence solving, NUCOMP is naturally much slower than NUDUPL. Therefore, the Kinetic network protocol and ensures it never, ever uses NUCOMP for the intensive sequential squaring loop. Instead, it is , unapologetically reserved exclusively for the verifier protocol execution phase. The verifier uses it sparingly but crucially to conclusively validate the final mathematical structure of the incoming proof.

3. Fast Exponentiation (fast_pow)

-> See: kyn-vdf/src/math.rs — Lines 422 to 502 This robust function implements a efficient, tightly controlled algorithmic loop. It precisely computes f^n for an arbitrarily large integer n with remarkable efficiency. It fundamentally and heavily utilizes the classic left-to-right binary exponentiation technique universally known in cryptography. This elegant technique is often colloquially called the square-and-multiply algorithm by cryptographic engineers. The strict algorithm carefully evaluates the absolute binary bit representation of the exponent n. It securely evaluates this representation sequentially, starting securely from the absolute most significant bit down to the absolute least. It first carefully initializes a mutable accumulator variable securely in memory. This accumulator typically, reliably starts directly as the mathematical identity form of the defined class group. For every single, distinct bit successfully evaluated in the binary string, a specific action occurs unconditionally. The accumulator form is unconditionally, reliably, and forcefully squared using the fastest available method. This critical, repetitive squaring operation is executed directly using the optimized nudupl function described extensively above. If the current binary bit being evaluated currently happens to be exactly a binary 1, an additional operational step occurs. This asymmetric, additional step is and securely triggered by the internal logic branch. The running accumulator is multiplied cleanly by the exact original base form f. It executes this multiplication using the versatile, generalized nucomp function for distinct forms. This deliberate, mathematical strategy dramatically reduces the required total operations required to finish safely. It drops the complexity from a purely, disastrously linear O(n) to an fast, manageable logarithmic O(log n). A , critical performance optimization nested deeply inside this hot loop is opportunistic reduction. During continuous, heavy mathematical composition, small, subtle inefficiencies can gradually, inevitably compound. This compounding causes the underlying form coefficients to slowly, consistently creep upward in raw size over time. The carefully designed algorithm actively intercepts this subtle, growing threat proactively. It does this by continuously, checking the absolute bit length securely of the accumulator’s internal a coefficient. If this specific, critical bit length unexpectedly exceeds exactly half the total bit width of the network discriminant, action is taken. The smart algorithm instantly, forcefully intervenes directly in the execution flow. It forces a rigid, standard reduction pass safely on the accumulator form. It successfully executes this reduction before allowing the loop to proceed cleanly to the next exponent bit. This brilliant, preemptive safeguard eliminates the , very real risk of a performance cliff. It prevents this cliff from occurring dangerously near the very end of very large, long-running exponentiations. The hot loop constantly, safely overwrites the main accumulator with newly generated forms continuously. This constant overwriting ensures old memory is cleanly, freed by the Rust garbage collector .

Key Pieces

The following structural components represent the most critical moving parts of the mathematical engine safely:

fn nudupl(f: &Form, d: &BigInt) -> Form

#![allow(unused)]
fn main() {
fn nudupl(f: &Form, d: &BigInt) -> Form
}

-> See: kyn-vdf/src/math.rs — Lines 227-310 This is undoubtedly the single, absolute most critical mathematical function for the overall performance of the entire VDF prover. It directly, consistently provides the high-speed squaring capability that fundamentally drives the entire verifiable delay sequence securely. Its raw, unadulterated performance characteristics directly, fundamentally dictate the exact real-world delay duration. This duration is inherently, required to maintain Kinetic’s target block intervals accurately. It prudently, intelligently receives the target form immutably to actively prevent unnecessary, expensive heap cloning. It then heavily internally manages its own transient, temporary memory allocations with absolute precision. Any regressions internally in this function directly, immediately weaken the economic security of the entire Kinetic network architecture significantly.

fn nucomp(f1: &Form, f2: &Form, d: &BigInt) -> Form

#![allow(unused)]
fn main() {
fn nucomp(f1: &Form, f2: &Form, d: &BigInt) -> Form
}

-> See: kyn-vdf/src/math.rs — Lines 312-420 This crucial function exclusively provides the generalized, robust composition logic for safely handling distinct, non-identical forms. It is an absolute, unavoidable requirement for the Wesolowski verification process executed securely by all honest network nodes. The network verifier must reliably, accurately multiply a standard cryptographic base form directly against a proof form safely. This proof form is raised to a dynamic, unpredictable challenge power derived from network state safely. It safely navigates complex linear congruences continuously without risking disastrous integer overflows . It does this while also avoiding precision loss or fatal division panics during runtime.

fn fast_pow(base: &Form, exp: &BigInt, d: &BigInt) -> Form

#![allow(unused)]
fn main() {
fn fast_pow(base: &Form, exp: &BigInt, d: &BigInt) -> Form
}

-> See: kyn-vdf/src/math.rs — Lines 422-502 This is the absolute primary orchestrator designated for safely raising any given mathematical form to an arbitrary BigInt power. It relies fundamentally, heavily on intelligently alternating sequenced calls to both nudupl and nucomp safely. It bases these specific calls entirely on strict, sequential binary bit evaluation securely. It matters intensely for rapid proof generation, where the prover must cleanly, accurately compute a quotient power dynamically. It effectively, permanently guarantees that even large, complex exponentiations reliably complete rapidly. They complete consistently in a tiny fraction of a single second rather than dangerously hanging indefinitely and stalling consensus.

BigInt Re-borrowing Patterns (&(&a + &b)) The Rust BigInt type definitely does not magically implement the standard Copy trait effortlessly. This is exactly because it relies heavily, consistently on dynamic, variable-length heap allocations exclusively. Consequently, utilizing any standard mathematical operators natively like + or * actively consumes the underlying values permanently by default. To prevent the strict Rust compiler from , prematurely destroying variables that are needed later, you must borrow them securely. You achieve this safely using the explicit & operator cleanly. Understanding exactly when to properly use &a, when to let the compiler safely consume a directly, and when to intentionally call a.clone() is . This careful, deliberate juggling of transient reference lifetimes is exactly what allows the cryptographic math to safely run at blazing speeds. It does this continuously without allocating endlessly and predictably crashing the entire host node gracefully. It is arguably the absolute most difficult aspect of writing -performant, memory-safe cryptography in pure Rust securely.

Caution

num_integer::Integer methods (mod_floor, div_floor) This sensitive module and universally requires correct Euclidean division rules when handling any negative numbers safely. Native arithmetic operators trivially like % in standard Rust simply, dangerously truncate toward zero continuously. This actively produces results that actively, break the underlying cryptographic structures securely. You must , use mod_floor consistently to ensure any negative dividends always wrap cleanly into positive remainders reliably. Failing to do so accurately will silently, dangerously yield invalid mathematical forms safely. This will permanently, irrevocably ruin the entire consensus proof validity .

How This Connects to the Rest of Kinetic

FORWARD DEPENDENCY: kyn-vdf/src/prover.rs The prover entirely, depends on nudupl to reliably, predictably execute the many millions of sequential squarings required. These squarings are required for the fundamental delay phase safely. Its core architectural execution loop is fundamentally, beautifully just a very tight, optimized continuous sequence . It is a sequence of continuous nudupl invocations executing flawlessly. Without optimized nudupl, the prover simply cannot logically securely generate a valid proof of elapsed time reliably.

FORWARD DEPENDENCY: kyn-vdf/src/verifier.rs The verifier relies structurally, on nucomp and fast_pow to independently securely validate proofs. It validates the pure mathematical integrity of all incoming proofs efficiently. It safely ensures that the block producer actually spent the exact required computational time reliably. It ensures they did not attempt to artificially forge the delay securely. This prevents malicious, aggressive nodes from endlessly spamming the secure network with instantly generated blocks safely.

CROSS-CRATE: kinetic-consensus/src/engine.rs The global, authoritative consensus engine actively, intelligently monitors the exact real-world time required . It monitors the time to successfully securely execute these specific mathematical functions reliably. It intelligently, dynamically uses this historical benchmarking data constantly to dynamically adjust . It cleanly adjusts the required VDF target iterations accurately for future upcoming network epochs safely. The pure algorithmic efficiency internally of math.rs is intrinsically, deeply, and directly permanently tied purely securely. It is tied to the absolute stability of the global, decentralized block interval reliably across all global continents safely.

Quick Reference

• Need to sequentially square a form? Always reliably use nudupl(f, D) directly.
• Why avoid nucomp for squaring? Do not use nucomp for simple squaring safely as it is computationally slower securely.
• Need to securely combine two distinct, separate cryptographic forms? Always securely confidently use nucomp(f1, f2, D) reliably.
• Need to securely precisely raise a specific base form smoothly to a very large power? Invoke fast_pow(f, exponent, D) reliably for lightning-fast explicit binary exponentiation securely.
• Doing complex group math safely with potential negative BigInts? Never, ever reliably use % natively. Always heavily rely on mod_floor securely from the trusted Integer trait .
• Compiler complaining about erroneously moved values abruptly? Check your mathematical expressions very carefully structurally.
• How to fix moved values securely? Ensure all critical mathematical operands are properly safely borrowed with & reliably.
• Why is exponentiation safely inexplicably slowing down over time? You likely mistakenly removed the opportunistic check.
• What got removed? You probably accidentally fully disabled the critical opportunistic standard reduction check deeply buried safely in fast_pow .

Open Questions / Things to Revisit

Warning

Timing Side-Channels in Exponentiation The fast_pow function branches its execution path based on the individual bits of the given exponent. It uses a strict square-and-multiply branching logic that is predictable. While VDF exponents are inherently public data in the Kinetic protocol, we must be careful. We must deeply analyze if this predictable branching exposes any subtle hardware vulnerabilities. We must investigate if it makes the network susceptible to CPU cache timing attacks. If a malicious node can optimize execution based on timing data, it ruins the delay proof.

Memory Allocation Overheads During Composition Both nucomp and nudupl rapidly allocate and cleanly deallocate dozens of temporary BigInt structures. They do this during every single mathematical execution loop. Running this continuously for millions of consecutive iterations places unrelenting stress on the system allocator. The default Rust allocator struggles to keep up with the continuous heap fragmentation. We should investigate implementing a custom slab allocator. Alternatively, we could build a pre-allocated BigInt memory pool specifically for this math module. This could reduce garbage collection pauses and speed up proof generation.

Important

WebAssembly Stack Limits for Light Clients If Kinetic nodes are ever compiled down to WASM for browser-based light clients, we face risks. The internal xgcd_partial routine must be thoroughly and audited. If it relies heavily on deep recursive function calls, it will fail. Recursive calls easily and reliably blow up the limited WASM call stack in browsers. An iterative rewrite might be necessary for broader, stable client compatibility. We must test this logic in a WASM sandbox before deploying light nodes.

Discriminant Pointer Indirection Overhead We are currently actively passing the discriminant D directly by reference. We pass it into every single mathematical function repeatedly across the entire codebase. This causes constant, unnecessary pointer indirection and cache misses. We should investigate encapsulating D securely inside a persistent ClassGroupContext struct. This would immediately eliminate this constant pointer passing natively. It would also and permanently clean up the external API surface.

Crate: kyn-vdf

Stage: 4

Reading Time: 45 minutes

Depends On: kinetic-core (hashing primitives, seed generation), num-bigint (arbitrary precision integer arithmetic), sha2 (SHA-256 implementation)

What Is This?

This document provides an , detailed conceptual breakdown of the deterministic prime generation logic used by the Kinetic network. The code resides in the kyn-vdf crate, specifically within kyn-vdf/src/chia.rs covering lines 1 to 235. Its sole responsibility is to generate a , 1024-bit negative prime number known as a discriminant for the Verifiable Delay Function (VDF). Without a valid, deterministically generated prime discriminant derived exactly from a network seed, the Kinetic VDF cannot operate securely. This document systematically maps the Rust implementation details directly to the dense mathematical requirements of the cryptographic protocol. It is critical for any core developer touching the consensus rules to thoroughly understand every single step of this exact file. A single bit of difference here will immediately cause a hard fork of the entire Kinetic blockchain. This is the single source of truth for the most sensitive cryptographic parameter in the system.

Why Kinetic Needs This

To fully appreciate the immense complexity of this file, you must first understand the fundamental “clock problem” in decentralized consensus systems. In a centralized database, a single authoritative server timestamps every transaction and event. This ensures that everyone agrees on the precise order of events. In a decentralized blockchain like Kinetic, there is no central authority to tell time. Furthermore, nodes fundamentally cannot trust each other’s internal system clocks. If nodes blindly trusted local timestamps, malicious actors could effortlessly spoof them. They would do this to strategically manipulate block rewards, reorder transactions, or rush the network’s block production schedule. Kinetic solves this existential threat by employing a cryptographic primitive called a Verifiable Delay Function (VDF). The VDF serves as a decentralized, cryptographic clock.

The Role of the VDF

A VDF acts as a strict, cryptographic clock that ticks predictably for the entire decentralized network. It is an algorithm designed to require a verifiable, unavoidable amount of sequential computational time to execute. Crucially, VDF computations are inherently and purposefully sequential by design. They cannot be sped up by throwing more CPU cores at them. They cannot be parallelized across a GPU cluster or an ASIC farm. Once the VDF finally finishes its long, arduous computation, the final mathematical proof it generates must be fast for other network nodes to verify. Our specific implementation of a VDF in Kinetic relies on a complex mathematical process known as “repeated squaring”. This squaring takes place within a rigorous structure known as an ideal class group of an imaginary quadratic field.

The Math of the Ideal Class Group

The absolute security, integrity, and operational safety of this ideal class group depend entirely on the properties of its core parameter. This parameter is universally known as the discriminant, which is denoted as $D$. The discriminant fundamentally and structurally defines the specific geometric and algebraic properties of the class group that the VDF operates within. The foundational mathematical laws governing the class group strongly require $D$ to be a strict negative prime number. This requirement ensures the group behaves exactly as expected cryptographically, without any underlying structural weaknesses.

Caution

If $D$ is inadvertently generated as a composite number (meaning it can be factored into smaller primes), the system fails. The entire security model collapses instantly and catastrophically in this scenario. An attacker who knows the secret prime factors of a composite discriminant $D$ can instantly leverage specialized mathematical shortcuts. One such devastating shortcut is the Chinese Remainder Theorem. These mathematical shortcuts allow the attacker to instantly compute the VDF result in a fraction of a millisecond. This and bypasses the required time delay that the VDF is supposed to enforce. This effectively grants the attacker the god-like ability to time-travel within the consensus protocol. They could effortlessly rewrite history, steal block rewards, and permanently destroy the blockchain’s integrity.

The Determinism Dilemma

Therefore, ensuring that $D$ is prime is a matter of life and death for the Kinetic blockchain. However, we face a severe, paradoxical cryptographic dilemma. We desperately need a trusted setup to generate this prime, but we cannot trust any single human entity or server to perform it for us.

Warning

If the core developers arbitrarily generated the prime $D$ and hardcoded it into the Kinetic software, they could secretly retain its factors. This would happen if they deliberately, maliciously chose a composite number that merely looked prime to standard, shallow tests. Doing so would create a , fully undetectable backdoor into the heart of the network.

To prevent this doomsday scenario, the decentralized network itself must logically generate $D$ dynamically for every single block that is produced. The discriminant must be generated deterministically from publicly verifiable, unpredictable data. Specifically, this data is the current block’s cryptographic seed. Because the seed changes randomly with every newly minted block, the generated discriminant changes constantly alongside it. This relentless changing ensures that no attacker ever has the necessary time to pre-compute the factors before the block becomes obsolete. But standard prime generation algorithms heavily and inherently rely on random number generators (RNGs). They use RNGs to pick candidate numbers to test. They also use RNGs to heavily select the testing bases for the probabilisitic primality checks. We cannot use random number generators in a strict blockchain consensus protocol under any circumstances whatsoever. If we foolishly did, Node A might roll a different random number than Node B. This would inevitably result in two entirely different prime discriminants being generated from the exact same block state. The network would immediately fork, shatter, and fail to agree on the state of the VDF clock. This specific file, chia.rs, is painstakingly and purposefully engineered to solve this exact, complex determinism dilemma. It and surgically strips all randomness out of standard prime generation algorithms. It replaces this randomness with strict, deterministic, seed-based derivation pipelines. It ensures that the generation of this critical cryptographic parameter is reproducible. It ensures it is fully verifiable and secure across the entire decentralized network.

How It Works

The intricate, relentless process of forging a tiny 32-byte seed into a colossal 1024-bit negative prime discriminant is rigorous. It is a multi-stage pipeline specifically designed for absolute determinism and absolute maximum performance. Every single step is carefully calibrated to ensure that given identical input, the output is always identical. This holds true down to the exact, precise bit level. The logic heavily handles raw memory management, low-level raw bit manipulation, fast-path divisional math, and deep cryptographic exponentiation sequentially.

Step 1: The Input Space and The Iterative Counter

-> See: kyn-vdf/src/chia.rs — Lines 70-85 The primary entry point for this dense mathematical logic is the critical hash_prime function. It takes exactly two defined arguments. The first argument is a 32-byte seed (derived cryptographically from the current block state). The second argument is a target bit length (which is and immutably fixed to exactly 1024 for our specific VDF implementation). We cannot simply hash the seed once and expect to magically receive a prime number. Finding a prime of this incredible magnitude is a slow process of relentless, iterative trial and error. Therefore, we initialize a specific u64 64-bit integer counter to exactly 0 before beginning the search. Using a full 64-bit counter securely provides over 18 quintillion potential iterations. This guarantees we will eventually locate a prime, no matter how unlucky the starting seed is. This counter is the core deterministic mechanism that safely allows us to systematically iterate through an infinite sequence of candidate numbers cleanly. If our first candidate number thoroughly fails the rigorous primality test, we simply increment this counter by exactly 1. We then boldly start the entire hashing process over again using the incremented counter. Because the starting seed is identical across the network, the sequence of tested candidates is flawlessly synchronized. The counter increments predictably across all running nodes, ensuring perfect consensus.

Step 2: The SHA-256 Concatenation Pipeline

-> See: kyn-vdf/src/chia.rs — Lines 86-115 A single execution of the standard SHA-256 algorithm via the sha2 crate only ever produces 256 bits of raw output data. We urgently require a 1024-bit number to successfully meet the strict cryptanalytic security bounds of the ideal class group. To effectively construct a number of this extreme magnitude, the function enters a specialized, high-speed hashing loop. It uses the Digest::update trait methods from the sha2 crate to dynamically append the data. It appends the current numerical state of our 64-bit counter directly to the 32-byte seed in memory. It then hashes this concatenated data using the SHA-256 engine. This generates the very first foundational block of 256 bits for our mathematical candidate. But we are still short of our required mathematical goal; we are exactly 768 bits short. The code then carefully appends an inner loop index (or modifies the counter slightly) and calls Digest::finalize. It hashes the seed once again, obtaining the very next sequential block of 256 bits. This specific, relentless concatenation process continues iteratively, hashing over and over again in a tight, hot loop. The resulting raw bytes are appended sequentially into a large, continuously growing Vec<u8> memory buffer. This memory buffer is pre-allocated in RAM to avoid resizing overhead. This intense loop continues unabated until we have accumulated exactly enough raw bytes to form a full, uninterrupted 1024-bit integer. The meticulous use of a pre-allocated buffer is critical here. It minimizes expensive, slow memory reallocations during this high-frequency, CPU-intensive execution loop.

Step 3: Byte-to-BigInt Conversion

-> See: kyn-vdf/src/chia.rs — Lines 116-130 Once our memory buffer is stuffed full of deterministic, pseudo-random bytes painstakingly derived from the SHA-256 hashes, we must proceed. We must carefully convert this raw buffer into a usable mathematical object for processing. Kinetic purposefully utilizes the popular, optimized num-bigint crate for actively managing these numbers. These numbers vastly exceed the capabilities of standard 64-bit or 128-bit CPU limits. The raw bytes sitting in our buffer are read using the BigInt::from_bytes_be function. This specific function parses them in strict big-endian format. In big-endian architecture, the most significant, largest byte always comes first at exactly index 0 of the array. Big-endian is specifically chosen to guarantee absolute cross-platform compatibility across the entire decentralized network. It ensures different CPU architectures (like Intel x86 versus Apple ARM) read the raw memory in exactly the same way. At this exact moment in the execution flow, the candidate is merely a random-looking 1024-bit integer residing in the heap. Statistically speaking, it is overwhelmingly likely to be a composite number. This means it is not yet prime and must be relentlessly, tested.

Step 4: The Bit Twiddling (Forcing Oddness and Exact Sizing)

-> See: kyn-vdf/src/chia.rs — Lines 131-150 Before we foolishly waste valuable CPU cycles testing the raw candidate for primality, we intervene. We apply strict bit-level constraints to forcibly shape it . First, a prime number (greater than the number 2) , unconditionally must be an odd number. Instead of wastefully testing if the candidate is even and discarding it if it is, we forcefully modify the number’s bits. We manipulate the bits directly to permanently make it odd, significantly saving execution time. We achieve this by calling the set_bit(0, true) method on the BigInt structure. This directly and instantly sets the very least significant bit in the binary representation to a value of 1. Second, we must and cryptographically guarantee that the candidate is exactly 1024 bits long. It must not be a single bit more, nor a single bit less. If the top bytes generated from our SHA-256 concatenation pipeline happened to contain leading zeros, a problem arises. Our final number might artificially and disastrously shrink to only 1000 bits or 1010 bits long. A discriminant that is inadvertently too small reduces the cryptanalytic security of the VDF. It makes the entire network vulnerable to devastating mathematical attacks. To preemptively prevent this fatal flaw, we forcefully set the most significant bit. Since bits are always 0-indexed in Rust, we specifically call set_bit(1023, true). This locks the 1024th bit to a permanent, unchangeable value of 1. This raw, low-level bitwise manipulation heavily guarantees the candidate permanently operates at the exact geometric scale. This is the precise scale required by the underlying class group security proofs.

Step 5: The Fast Path (Deterministic Small Prime Filtering)

-> See: kyn-vdf/src/chia.rs — Lines 15-25 (inside is_probable_prime) Rigorous primality testing via complex modular exponentiation is computationally agonizing. It is brutally slow for the CPU to perform repeatedly. We urgently want to avoid it entirely if the candidate number is obviously and trivially not prime. The code implements a optimized, lightning-fast mathematical filter to act as an bouncer. It and checks if the candidate is cleanly divisible by the first few hundred small prime numbers. These are primes such as 3, 5, 7, 11, 13, 17, and so forth. It does this with extreme mathematical efficiency by computing the mathematical modulo of the candidate. It calculates this against a single, pre-computed product of all these small primes combined together. This product is usually established early, perhaps even at compile time. This optimization ensures that a single, solitary modular division operation can implicitly check hundreds of prime factors at once. If the modulo operation yields exactly zero, the candidate is definitively cleanly divisible by at least one of these tiny small primes. In this case, we instantly and ruthlessly reject it as a composite number. We then immediately increment our main u64 iteration counter from Step 1. We restart the entire SHA-256 hashing pipeline from scratch. This elegantly simple mathematical division step definitively eliminates a vast majority of composite candidates. It does this in a mere fraction of a millisecond, dramatically increasing overall block validation speed across the node.

Step 6: The Miller-Rabin Mathematical Setup

-> See: kyn-vdf/src/chia.rs — Lines 26-40 If a fortunate candidate successfully survives the brutal small prime division filter, it progresses to the next stage. It is subsequently passed directly to the core Miller-Rabin probabilistic test logic. The acclaimed Miller-Rabin algorithm requires a very specific, strict mathematical decomposition of the candidate number. This decomposition must occur exactly before the actual testing logic can begin. Specifically, it requires writing the candidate minus one (expressed as $n - 1$). It must be written in the form of $2^r \cdot d$. In this formulation, the variable $d$ must be an odd number. The Rust code achieves this complex decomposition by utilizing fast binary methods. Methods like trailing_zeros() are used to rapidly and instantly identify the exact powers of 2. It systematically and shifts the binary representation rightward. It cleanly factors out the powers of 2 (carefully and counting them as the variable $r$). It continues this shifting until an unambiguously odd number definitively remains. This final odd number is then assigned to the variable $d$ for further calculations in the next step. This exact, precise decomposition is , fundamentally necessary. It is required for the complex modular exponentiation steps that form the beating heart of the Miller-Rabin test.

Step 7: The Deterministic Miller-Rabin Loop

-> See: kyn-vdf/src/chia.rs — Lines 41-69 This specific, intense step is the absolute cryptographic heart of the entire primality verification process. It is where the CPU predictably and unavoidably spends the vast majority of its execution time. Standard, textbook Miller-Rabin algorithms haphazardly choose random numerical bases. They test against the candidate using these random bases to determine primality probabilistically. As we have firmly and repeatedly established, we cannot use random bases in the Kinetic consensus protocol. Under no circumstances whatsoever is randomness permitted here. Instead, we use a fixed, hardcoded static array containing exactly the first 25 consecutive prime numbers. Specifically, these deterministic bases are exactly 2, 3, 5, 7, 11, 13, and so on up to the 25th prime. These serve as our purely deterministic, unvarying testing bases. The function resolutely enters a large, overarching loop specifically labelled 'outer. It sequentially iterates through these 25 bases one by one without fail, in exact order. For each individual base, we compute the heavy modular exponentiation equation. We use the modpow function to compute: $base^d \pmod n$. If the resulting computed value is exactly 1 or exactly $n - 1$, the candidate survives. It has successfully passed the rigorous test for that specific base, and we cautiously move to the very next base in the array. If the initial result is neither 1 nor $n - 1$, we inevitably enter a secondary, intensive inner squaring loop. We repeatedly square the intermediate mathematical result exactly $r - 1$ times. We continually and obsessively check if the intermediate value becomes exactly $n - 1$ at each step of the squaring. If the candidate tragically fails these strict, mathematical conditions for even a single deterministic base, it is over. It is definitively, proven to be a composite number. We safely reject it immediately, mercilessly halting the test and saving CPU cycles. However, if it successfully passes the rigorous mathematical conditions for all 25 specific deterministic bases, a mathematical guarantee is reached. The mathematical probability of it being a composite number is astronomically, practically exactly zero. We officially accept the hardened candidate as a valid, sound, securely derived prime number.

Step 8: Constructing the Final Negative Discriminant

-> See: kyn-vdf/src/chia.rs — Lines 180-235 The grueling, intense hash_prime function eventually returns our successfully tested, verified 1024-bit prime number. But our complex cryptographical work is not quite complete yet. The create_discriminant function confidently takes this raw prime and processes it further. It shapes it further to meet the specific geometric requirements of the ideal class group. Class groups , unequivocally require a negative discriminant to function correctly as an imaginary quadratic field. Positive discriminants will fail and fundamentally break the VDF math. Furthermore, the mathematical group structure and non-negotiably mandates an additional rule. The discriminant must satisfy a specific modular congruence: $D \equiv 1 \pmod 4$. The code applies careful modular arithmetic to gently adjust the raw prime accordingly. It does this specifically without accidentally breaking its hard-won primality. It first negates the prime directly using the standard negation operator to deliberately make it negative. It then computes the modulo against the number 4 using the Remainder operations provided by Rust. If necessary, it applies a carefully calculated mathematical offset. This offset might be a simple subtraction or addition, to satisfy the strict modulo condition. It simultaneously ensures the underlying number itself remains a valid, untouched prime. The final, resulting BigInt structure is the tested, negative discriminant $D$. It is deterministically derived and ready to empower the VDF clock.

Key Pieces

Function: is_probable_prime(candidate: &BigInt) -> bool

#![allow(unused)]
fn main() {
is_probable_prime(candidate: &BigInt) -> bool
}

• What it does: Executes the exceptionally heavy Miller-Rabin primality test. It uses a fixed, predefined deterministic set of exactly 25 small prime bases to eliminate randomness. It first efficiently filters out obvious composites using raw numerical division via a pre-computed product. Then, it systematically runs 25 rigorous mathematical rounds of intense modular exponentiation via the heavy modpow function to achieve near-absolute probabilistic certainty.
• Location: kyn-vdf/src/chia.rs — Lines 10-69
• Why it matters: This crucial function is the ultimate, arbiter of mathematical truth for all VDF parameters in Kinetic. Because it uses deterministic bases instead of unpredictable random ones, it is safe. It ensures that every single node in the global decentralized network invariably reaches the exact same conclusion about a candidate number’s primality. This and fully preserves critical network consensus.

Function: hash_prime(seed: &[u8], length_bits: usize) -> BigInt

#![allow(unused)]
fn main() {
hash_prime(seed: &[u8], length_bits: usize) -> BigInt
}

• What it does: Comprehensively orchestrates the entire, complex seed hashing sequence. It manages the raw byte accumulation pipeline, precise bit manipulation logic, and the overarching primality testing loop. It manages the vital u64 incrementing counter that flawlessly guarantees we will eventually find a valid prime, regardless of what the initial starting seed was.
• Location: kyn-vdf/src/chia.rs — Lines 70-179
• Why it matters: This essential function is the raw, unbridled engine of our network’s determinism. It takes wildly unpredictable block state (the seed) and deterministically maps it safely to a specific, secure mathematical parameter (a 1024-bit prime). It does this in a way that is universally reproducible by anyone on any hardware setup. It forms the most crucial bridge between standard cryptographic hashing and pure, unadulterated number theory.

Function: create_discriminant(seed: &[u8], length_bits: usize) -> BigInt

#![allow(unused)]
fn main() {
create_discriminant(seed: &[u8], length_bits: usize) -> BigInt
}

• What it does: Serves as the primary, accessible public interface for the entire, complex discriminant generation module. It calls hash_prime to securely obtain the foundational base prime. It then applies the final, strict mathematical constraints required by imaginary quadratic fields. Specifically, it applies the strict negativity constraint and the unyielding modulo 4 rules.
• Location: kyn-vdf/src/chia.rs — Lines 180-235
• Why it matters: This precise function returns the exact, final mathematical parameter that the heavy VDF evaluator and the network’s lightweight verifiers will dependently use to run the cryptographic clock. Its absolute correctness is totally . If this function ever fails to consistently produce a valid, correctly formed discriminant, the security of the entire proof-of-time layer is fundamentally and irrevocably compromised.

Rust Concept: Loop Labels and continue 'outer

• What it does: Rust safely allows developers to label specific loops with a distinctive tick mark. For example, writing 'outer: for i in .... When you are buried deep inside a nested inner loop, you can use the explicit, powerful command continue 'outer;. This immediately and abruptly halts the inner loop and jumps straight to the very next iteration of the labelled outer loop.
• Location: kyn-vdf/src/chia.rs — Heavily and strategically used inside the core Miller-Rabin primality test loops. This is specifically between Lines 41-69.
• Why it matters: Saif, you will see this specific, idiomatic pattern used extensively and deliberately in the primality tests. When testing a specific base in Miller-Rabin, if the inner squaring loop finds the critically required value $n-1$, the candidate has successfully passed for that specific base. We do not need to wastefully finish executing the remainder of the inner squaring loop. We use continue 'outer; to jump straight out and immediately begin testing the very next base in the sequence. This avoids the painful need for complex, messy, stateful boolean tracking variables (like let mut passed = false;). It effectively keeps the code fast, remarkably readable, and idiomatic. It is an exceptionally powerful control flow tool for organizing complex, heavily nested mathematical algorithms like this without losing track of state.

Rust Concept: Bit Manipulation on BigInt

• What it does: The standard, widely used num-bigint library provides direct, efficient bit-access methods. One key method is the set_bit(index, value) command. This allows developers to directly and instantly modify the raw binary representation of a integer sitting in system memory. It does this without resorting to performing outrageously costly mathematical arithmetic operations.
• Location: kyn-vdf/src/chia.rs — Used extensively and purposefully inside hash_prime. This occurs when forcefully guaranteeing oddness and enforcing strict length constraints, specifically around Lines 131-150.
• Why it matters: Saif, if we logically wanted to forcibly make a candidate number odd, we could theoretically do complex modulo math to check if it’s currently even. If so, we could perform a sluggish addition operation to precisely add 1. But standard mathematical arithmetic on gigantic 1024-bit numbers is , painfully slow for a CPU to perform repeatedly. Because BigInts are ultimately just simple, raw arrays of bits stored sequentially in memory, calling candidate.set_bit(0, true) instantly forces the very least significant bit in the array to a 1. In standard binary representation, any number ending in a 1 is unconditionally, odd. This guarantees oddness almost instantly with near-zero CPU overhead. We intelligently use this exact same blindingly fast technique to flip the top bit to 1 via set_bit(1023, true). This ensures the number is exactly, 1024 bits long. It is a brilliant, low-level memory optimization that is crucial for the high-speed performance of the block validator.

Rust Concept: std::cmp::max and std::cmp::min

• What it does: These are optimized, universally relied upon standard library functions. They precisely take two values of the exact same data type and safely, predictably return the larger or specifically smaller of the two, respectively. They do this without requiring custom if-else branching logic.
• Location: kyn-vdf/src/chia.rs — Used continuously and carefully during the delicate byte slicing and precise buffer management phases of the frantic SHA-256 pipeline.
• Why it matters: Saif, when we are actively and rapidly slicing the tiny 32-byte SHA-256 outputs to cleverly fit them exactly into our target byte length buffer, we have to be careful. We must painstakingly ensure not to accidentally read or write out of the allocated memory bounds. Doing so would instantly cause a severe, unrecoverable runtime panic that would crash the node immediately. std::cmp::min is used repeatedly and elegantly to calculate exactly how many bytes we can safely and legally copy. It copies them from the small hash output buffer directly into our main, candidate buffer without ever overflowing the dynamically allocated memory. It is a clean, safe, and idiomatic Rust way to elegantly handle delicate boundary logic. It does this without writing horribly verbose, intensely error-prone if-else blocks that would mercilessly clutter the codebase.

How This Connects to the Rest of Kinetic

• CROSS-CRATE (kinetic-core Consensus): The core, foundational consensus mechanism residing centrally in the kinetic-core crate , undeniably relies on the create_discriminant function. It relies on it for the strict, unforgiving validation of every single block traversing the network. When a node successfully receives a valid proof of space from the broader network, it immediately uses the challenge hash of that exact proof as the cryptographic seed. It uses this seed to generate this exact discriminant. If the generation fails or produces a complete mismatch compared to the block, the block is , brutally rejected by the node. This firmly halts malicious actors in their tracks.
• CROSS-CRATE (kinetic-cli Timelord): The Timelord is the specialized, powerful network node running the actual heavy VDF computation. It uses this exact same codebase and specific file. It must generate the exact same prime discriminant as all the validating nodes scattered on the network. If the Timelord’s chia.rs ever behaves even slightly differently due to a subtle software bug or a bizarre hardware quirk, disaster strikes. The Timelord will stubbornly compute a VDF over the wrong class group entirely. The network will swiftly and mercilessly reject its final proof. This wastes amounts of the Timelord’s precious CPU work, time, and expensive electricity.
• FORWARD DEPENDENCY (VDF Squaring Engine): The actual core VDF squaring engine implements the repetitive, intense squaring logic loop. It and blindly assumes that $D$ is a valid, uncompromised prime number. It does not attempt to wastefully verify the primality of $D$ itself before beginning the gruelling squaring process. Doing so on every single squaring step would be totally for overall performance, instantly bringing the network to a halt. The rigorous, unbreakable security of the entire squaring engine rests entirely on the unshakeable foundational assumption that this specific file did its job flawlessly.

Quick Reference

• Primary Goal: Transform a wildly unpredictable 32-byte seed into a valid, securely derived, undeniably 1024-bit negative prime discriminant.
• Primary Algorithm Pipeline:

1. Carefully Initialize 64-bit Iteration Counter for Determinism
2. Execute High-Speed SHA-256 Concatenation Pipeline
3. Execute Safe Big-Endian Memory Buffer to BigInt Conversion
4. Force Absolute Oddness and Strict 1024-bit Target Bit Length Restrictions
5. Execute Blindingly Fast Pre-computed Small Primes Division Check
6. Execute Strict Miller-Rabin Mathematical Decomposition ($2^r \cdot d$)
7. Execute Heavy Miller-Rabin Test (Using exactly 25 predefined deterministic bases)
8. Execute Precise Modulo 4 Structural Adjustment and Explicit Negation

• The Golden Determinism Rule: The exact same starting seed must always, unconditionally, flawlessly yield the exact same prime number. This must hold true across all computer architectures, operating systems, and node implementations without exception.
• Strict Mathematical Requirements: The successfully generated discriminant $D$ must fundamentally be a negative prime of exactly 1024 bits in length. It must also satisfy the strict mathematical condition $D \equiv 1 \pmod 4$.
• Performance Criticality: High. This complex, heavy code runs repeatedly and intensively during continuous block validation. Any inefficiencies or memory leaks here will slow down the entire network’s block propagation times.

Open Questions / Things to Revisit

Performance Bottlenecks

• Miller-Rabin Round Optimization: We are currently mandating a full 25 rounds of the heavy deterministic Miller-Rabin test. Current advanced cryptographic literature clearly suggests that for numbers over 1024 bits, far fewer rounds might provide entirely sufficient probabilistic certainty. We should , scientifically investigate if we can safely and responsibly reduce this to 15 or 20 rounds. This would dramatically speed up block validation without inadvertently opening up terrifying edge-case vulnerabilities to sophisticated attackers who might pre-compute composite edge cases.
• BigInt Memory Allocation Churn: The intricate, repetitive process of constantly accumulating SHA-256 hashes into a dynamic Vec<u8> is intense. Carefully converting it into a BigInt inevitably involves several heavy heap allocations directly inside the tight looping structure. In a high-throughput scenario, such as a brand new node rapidly syncing thousands of blocks from genesis, this is problematic. This will cause , unsustainable memory allocation churn and trigger the garbage collector or allocator overhead far too frequently. We should deeply explore pre-allocating these buffers globally once. Alternatively, we could use a specialized, stack-based big integer library , flawlessly optimized for this specific 1024-bit size constraint to bypass the heap entirely.

Security Audits

• Seed Entropy Source Audit: The foundational, absolute security of this entire file assumes that the input seed genuinely possesses 256 bits of true cryptographic entropy. It assumes this entropy is , irrecoverably unpredictable to all miners. We critically need to and independently audit the complex kinetic-core seed derivation path. If a clever attacker can successfully manipulate the block state to rapidly grind for favorable seeds, they might be able to easily find a weak discriminant. This weak discriminant makes the VDF easier to solve, fundamentally, irreparably compromising the blockchain’s clock mechanism and allowing them to steal rewards.
• Hardware Acceleration Extensibility: The heavy modular exponentiation required in the Miller-Rabin test is currently CPU-bound. It is done entirely in pure, unaccelerated software. As network difficulty inevitably and continuously increases, we may desperately want to selectively expose complex hooks. These hooks would allow powerful nodes with specialized, custom GPUs or FPGAs to offload the excruciating primality testing entirely. However, the strict, deterministic requirement must be maintained flawlessly and across wildly varying hardware implementations. This is a significant, terrifying, and daunting engineering challenge that we must confidently solve before scaling the network further.

Crate: kyn-vdf

Stage: 05

Reading Time: 25 minutes

Depends On: 04_chia_forms.md, 03_vdf_basics.md

What Is This?

This document explores the Binary Quadratic Form Compression (BQFC) implementation inside kyn-vdf/src/chia.rs (lines 237-597). At a high level, BQFC is a sophisticated mathematical and engineering technique for taking a large mathematical object—a binary quadratic form—and squeezing it down into the smallest possible representation without losing any critical information. In the Kinetic network, we are constantly passing around VDF (Verifiable Delay Function) proofs, which are primarily composed of these binary quadratic forms. A raw 1024-bit form, if just serialized directly as its constituent components a, b, and c, takes about 130 bytes of space. Using BQFC, we are able to compress this down to exactly 100 bytes. This document will walk you through exactly how the CompressedForm struct represents this compressed state. We will examine how bqfc_compr takes a raw form and compresses it. We will also see how bqfc_decompr reverses that process. Finally, we will cover how serialize_form and deserialize_form translate the mathematical data into raw bytes for network transmission. When a developer first looks at this file, the immediate question is usually: “Why are we doing so much math just to serialize an object?” The answer is that a binary quadratic form is not just a random collection of bytes; it has strict internal mathematical relationships. BQFC exploits these relationships. Because the values of a, b, and c are bound together by the discriminant equation b^2 - 4ac = d, sending all three is redundant. Sending a and b is better, but still redundant because b itself has internal symmetries we can exploit. BQFC is the process of stripping away every single bit of redundant data until we are left with the absolute theoretical minimum representation. This mathematical compression is fundamental to the scalability of the Kinetic blockchain, ensuring that our verifiable delay functions do not choke the peer-to-peer layer.

Why Kinetic Needs This

You might look at the difference between 130 bytes and 100 bytes and think, “Is this really worth the complexity?” The answer is an emphatic yes. In the Kinetic network, VDF proofs are not just calculated once and stored; they are constantly gossiped across the peer-to-peer (P2P) network. Every single node that participates in consensus needs to receive, verify, and potentially re-broadcast these proofs. When you have thousands of nodes broadcasting proofs every few seconds, that extra 30 bytes per form adds up . Let’s break down exactly why this compression is a feature for the Kinetic architecture.

First, consider MTU and Packet Fragmentation. Network packets have a Maximum Transmission Unit (MTU), which is typically around 1500 bytes for standard Ethernet. If a message exceeds this, it gets fragmented into multiple packets. Fragmentation increases latency and the chance of packet loss. VDF proofs are often bundled with other block headers and signatures. By keeping our VDF proofs as small as possible, we maximize the number of proofs we can fit into a single unfragmented UDP or TCP packet. A 100-byte footprint gives us crucial breathing room in our packet budgets. If we were to use the uncompressed 130-byte forms, a single broadcast containing a handful of proofs could easily spill over the MTU threshold.

Second, we must address Blockchain State Bloat. Over time, these VDF proofs end up being embedded into the historical record of the Kinetic blockchain. 30 extra bytes per block, extrapolated over years and millions of blocks, turns into gigabytes of pure waste. Storage is not free, and one of Kinetic’s primary goals is to keep the node requirements low enough that anyone can run an archival node on consumer hardware. By compressing forms at the network layer and persisting them in this compressed state, we are significantly reducing the long-term storage requirements. This has a direct impact on the decentralization of the network.

Third, Bandwidth Costs are a major concern. For light clients or nodes running in bandwidth-constrained environments (like mobile devices, rural internet connections, or satellite links), bandwidth is expensive and limited. Shaving off ~23% of the size of the most commonly transmitted data structure is a win for network inclusivity. Kinetic aims to be a globally accessible network, and every byte saved lowers the barrier to entry. When syncing from genesis, a node must download millions of these forms; a 23% reduction in size translates to hours saved during the initial sync process.

Fourth, there is an interesting dynamic regarding Processing Overhead and Cache Locality. While decompression takes a small amount of CPU work to perform the mathematical recovery, transmitting less data over the wire and reading fewer bytes from disk often results in an overall performance gain. Modern CPUs are fast, but memory bandwidth and cache misses are slow. Reading 100 bytes into the L1/L2 cache is faster than reading 130 bytes. The CPU overhead of running the math in bqfc_decompr is often hidden by the time saved not waiting for RAM or network I/O. This illustrates the principle of trading cheap compute cycles for expensive bandwidth and I/O.

Finally, consider DDoS Mitigation. Smaller packet sizes mean that an attacker trying to flood the network with fake proofs has to expend relatively more effort to saturate a node’s bandwidth. While BQFC wasn’t designed purely as a security feature, dense packing of data structurally hardens the P2P layer. An attacker must generate valid or pseudo-valid compressed forms, meaning they cannot just spray random large bytes at the network and expect them to be processed as VDF proofs.

How It Works

The BQFC process relies on a core insight from number theory: a binary quadratic form (a, b, c) of a known discriminant d has redundant information. Because the relationship b^2 - 4ac = d always holds true, if we know a and b (and d, which is a global network constant), we can easily calculate c. However, BQFC takes this even further. It turns out you don’t even need all of b. You can compress a and a specialized representation of b into a smaller space, and then reconstruct b on the other side. This process is broken down into several stages: structural representation, mathematical compression, byte serialization, byte deserialization, and finally mathematical decompression.

Step 1: The CompressedForm Structure

-> See: kyn-vdf/src/chia.rs — Lines 237-250

When we compress a form, we don’t just truncate bytes arbitrarily. We transform the standard (a, b, c) coordinate system into a specialized CompressedForm structure. This structure contains four key fields: a, t, g, and b0. The a field remains the exact same value as in the original form. It is the foundational pillar of the form and cannot be compressed away; its full precision is required. The t field is a partial quotient derived from running the Extended Euclidean Algorithm (XGCD) on a and b. The g field is the greatest common divisor extracted during that same XGCD step. The b0 field is a small remainder value, essentially a mathematical parity check. By storing these specific elements instead of the integer b, we encapsulate enough mathematical “breadcrumbs” to recreate the original b value. It is a form of lossy compression where the “lost” data can be deterministically recalculated on the other side without having to send the entire integer over the network. This structure is the cornerstone of our ability to hit the 100-byte target.

Step 2: Compression (bqfc_compr)

-> See: kyn-vdf/src/chia.rs — Lines 255-320

The bqfc_compr function is where the heavy lifting of compression occurs. It takes a raw, fully inflated binary quadratic form and produces a CompressedForm. The function first initiates a bounded version of the Extended Euclidean Algorithm on the inputs a and b. The Euclidean algorithm is typically used to find the greatest common divisor of two numbers, but here it is used to find a smaller representation of the relationship between a and b modulo a certain base. The algorithm runs until it reaches a specific bound, at which point it extracts the variables t and g. Once the XGCD yields t and g, the function calculates b0. Because the reconstruction process later will involve calculating square roots, and because square roots have multiple valid solutions in modular arithmetic, b0 acts as a crucial parity bit or remainder to resolve ambiguities later. The beauty of this algorithm is that it takes a number b that normally requires a amount of bits and shatters it into these smaller mathematical components (t, g, b0) that pack tightly together. This mathematical decomposition is what allows us to discard the bulk of b’s bits.

Step 3: Serialization (serialize_form)

-> See: kyn-vdf/src/chia.rs — Lines 325-390

Once we have a CompressedForm sitting in memory, we need to turn it into a flat array of exactly 100 bytes so it can be sent over a TCP or UDP socket. This is where serialize_form comes in. The function allocates a Vec<u8>, which is a dynamically sized, owned array of bytes on the heap. It then begins packing the fields a, t, g, and b0 into it. Because these fields are large, multi-precision integers (typically BigInts), it extracts the raw bytes of each number and concatenates them in a strict, deterministic order.

When writing this in Rust, the distinction between a Vec<u8> and a [u8] is . A Vec<u8> is an owned, growable array allocated on the heap. When serialize_form creates a new Vec<u8>, it is taking ownership of new memory. It populates this memory, and then returns ownership of this vector to the caller. The caller is then responsible for sending it over the network or dropping it, at which point the memory is freed. Conversely, the data it reads from the BigInts often comes out as a slice [u8]. A slice is just a borrowed view into memory owned by someone else. To get the data from the slice into the vector, the code uses copy_from_slice. This function performs a fast, safe memcpy under the hood. It ensures the vector has its own independent copy of the bytes, preventing any data races or use-after-free errors. This explicit copying is why the return type of serialize_form is an owned Vec<u8>.

Critically, it also packs metadata. To save space, it uses bit flags. For example, the sign of b (whether it is positive or negative) is essential for reconstruction. Allocating a whole byte just for a true/false value is wasteful. Instead, the sign is packed into a single bit of a single byte using a bitwise shift, specifically BQFC_B_SIGN = 1 << 0. This means we take the binary number 1 and shift it left by 0 positions, which just equals 1. If the sign is negative, we bitwise OR this value into our byte using the | operator. This technique allows us to cram up to 8 different boolean flags into a single byte of overhead. It is this aggressive, bit-level micromanagement that keeps the final serialized size capped at 100 bytes.

Step 4: Deserialization (deserialize_form)

-> See: kyn-vdf/src/chia.rs — Lines 395-460

On the receiving end, a Kinetic node receives a 100-byte packet from a peer. It uses deserialize_form to parse this raw byte array back into a usable CompressedForm structure in memory. This function takes a slice &[u8], which is a borrowed view into the bytes, rather than an owned Vec<u8>.

The parser is passed a &[u8], a read-only borrowed slice. This means the parser does not own the memory; it is just looking at the bytes received from the network socket. Because it’s a slice, it has a known length, and Rust will automatically bounds-check our reads to prevent buffer overflows. This built-in safety net is why Rust is chosen for these critical network parsers over C or C++. To track our progress through this slice, we use an &mut usize representing an offset. Why a mutable reference? If we just passed usize by value, the helper functions would get a copy of the number. When the helper function reads 4 bytes, it would add 4 to its own copy of the offset, and the main parser would be stuck at 0. By passing &mut offset, the helper function directly modifies the parser’s offset variable. This ensures that every sequential read picks up exactly where the last one left off, moving safely through the 100 bytes.

It reads the bit flags we packed earlier by taking a byte and using bitwise AND operations. By executing byte & BQFC_B_SIGN, the parser masks out all other bits and isolates exactly the boolean value it needs. This cleanly translates network bytes back into structured Rust logic.

Step 5: Decompression (bqfc_decompr)

-> See: kyn-vdf/src/chia.rs — Lines 465-597

Once the node has safely parsed the bytes into a CompressedForm, it still needs the actual, full (a, b, c) form to verify the VDF proof. The bqfc_decompr function performs this mathematical inflation. It takes a, t, g, and b0 and runs the algorithm to reconstruct the original b. This is a computationally intensive process. It involves calculating modular inverses over large finite fields, and eventually calculating modular square roots. Calculating a modular inverse means finding a number x such that (num * x) % mod = 1. Because square roots can have multiple valid answers in modular arithmetic, the algorithm reaches a fork in the road where it must decide which root is the correct one. This is exactly why the b0 value and the sign flags were packed earlier. They act as a tie-breaker, forcing the algorithm to select the exact root that corresponds to the original b. If we did not have these flags, we would have a 50/50 chance of picking the wrong root, which would invalidate the VDF proof. Finally, once a and b are fully recovered and verified, c is trivially computed using the fundamental discriminant equation: c = (b^2 - d) / (4a). The form is now fully restored and ready for VDF verification. The CPU overhead here is non-trivial, but as mentioned earlier, it is well worth the bandwidth savings.

Key Pieces

Here is a detailed breakdown of the critical types and functions you need to understand in this file. When modifying this file, these are the components you must be careful with.

CompressedForm

• What it does: A structured payload holding a, t, g, and b0.
• File & Line: kyn-vdf/src/chia.rs — Lines 237-250.
• Why it matters: This is the intermediate state between a full mathematical form and raw bytes. It defines exactly what mathematical components are necessary to achieve the 100-byte compression target. If you ever need to change the compression algorithm, this struct will be the first thing to change. It acts as the bridge between pure math and network serialization.

bqfc_compr

• What it does: Compresses a standard binary quadratic form into a CompressedForm.
• File & Line: kyn-vdf/src/chia.rs — Lines 255-320.
• Why it matters: This is the engine of the BQFC protocol. It uses the Extended Euclidean Algorithm to discard redundant bits of b and generate the minimal t and g values. It is optimized and any bugs here will result in forms that cannot be decompressed by peers. A bug here would effectively create a network fork, as nodes running the buggy code would produce forms that other nodes would reject as invalid.

bqfc_decompr

• What it does: Takes a CompressedForm and inflates it back into a standard (a, b, c) form.
• File & Line: kyn-vdf/src/chia.rs — Lines 465-597.
• Why it matters: Without this, the VDF proofs received from the network are useless. It performs complex modular arithmetic (inverses and square roots) to reconstruct the dropped data. Performance is critical here, as this runs directly during block validation. Any inefficiency here will slow down the entire node’s ability to sync with the network.

serialize_form

• What it does: Flattens a CompressedForm into a Vec<u8> of exactly 100 bytes.
• File & Line: kyn-vdf/src/chia.rs — Lines 325-390.
• Why it matters: This function bridges the gap between abstract Rust memory structures and physical network sockets. It handles byte-order (endianness) and tight bit-packing for boolean flags. It must be deterministic; the exact same mathematical form must always serialize to the exact same 100 bytes. If it is not deterministic, block hashes will diverge, causing consensus failures.

deserialize_form

• What it does: Parses a 100-byte slice [u8] back into a CompressedForm.
• File & Line: kyn-vdf/src/chia.rs — Lines 395-460.
• Why it matters: This is the entry point for all incoming network data related to VDFs. It safely validates that the incoming data is exactly 100 bytes and decodes the packed bit flags. It must be robust against malformed or malicious inputs to prevent panics. Because it touches untrusted network data, it is a prime target for fuzzing and security audits.

How This Connects to the Rest of Kinetic

CROSS-CRATE: kyn-network The kyn-network crate is the primary consumer of serialize_form and deserialize_form. When the network layer needs to broadcast a block containing a VDF proof, it calls serialize_form. This ensures the payload is as small as possible before constructing the final P2P protocol message. Conversely, when kyn-network receives a proof from a peer, it immediately calls deserialize_form. This step is required to validate the byte structure before passing the message further up the protocol stack. Without this tight integration, our P2P layer would be overwhelmed by large proof sizes.

CROSS-CRATE: kyn-consensus The kyn-consensus crate relies entirely on the successful output of bqfc_decompr. The consensus rules dictate that a block is only valid if the VDF proof checks out. The consensus engine must take the decompressed form, feed it into the VDF verification algorithm, and ensure it matches the expected difficulty. It also ensures the iterations match for that specific block height. If bqfc_decompr fails, or if it produces a structurally invalid form, the block is instantly rejected by consensus. There is no fallback mechanism; BQFC decompression must succeed for the chain to progress.

FORWARD DEPENDENCY: VDF Verification Engine The output of bqfc_decompr feeds directly into the squaring loop of the VDF verification process. The values of a and b generated here must be accurate down to the very last bit. If decompression yields even a single bit of error in b, the subsequent squaring operations will immediately diverge. They will stray from the prover’s original mathematical path. This leads to a failed verification, and usually results in the peer that sent the form being banned for providing invalid data.

Quick Reference

• Original Form Size: ~130 bytes (for a standard 1024-bit discriminant).
• Compressed Form Size: Exactly 100 bytes.
• CompressedForm fields:
• a: The primary coefficient. - t: The partial quotient from the XGCD run. - g: The greatest common divisor from the XGCD run. - b0: The mathematical remainder/parity check used to break ties.
• Compression Method: Partial Extended Euclidean Algorithm (XGCD) to discard redundant bits of b.
• Decompression Method: Modular inverses and modular square roots to recover the dropped bits of b.
• Serialization Format: Big-endian byte arrays combined with bit-packed boolean flags for maximum data density.
• Network Goal: Keeping VDF proofs well within standard MTU limits and reducing node storage bloat.

Open Questions / Things to Revisit

• BigInt Allocation Overhead: The bqfc_decompr function currently performs several large BigInt allocations when computing modular inverses and square roots. We should investigate if we can reuse a pre-allocated memory pool or bump allocator. This would reduce garbage collection and allocator pressure during heavy blockchain syncing. Currently, syncing from genesis allocates and deallocates millions of BigInts, which is not optimal for CPU caches.

• Constant Time Execution guarantees: Is bqfc_decompr currently constant-time? Almost certainly not, due to the nature of the XGCD and square root algorithms. Since this code is used for verification and not for signing or key generation, side-channel attacks (like timing attacks) are less of a concern. However, it is worth documenting so future developers do not mistakenly use these functions in a cryptographic context where constant-time execution is required. If we ever expose these functions to smart contracts, this could become a severe vulnerability.

• Error Handling on Malicious Packets: If an attacker sends garbage 100-byte payloads filled with random noise, does deserialize_form fail gracefully? More importantly, does bqfc_decompr waste excessive CPU cycles trying to calculate impossible square roots before realizing the form is invalid? We need to ensure we have strict, early exit paths to prevent asymmetric denial-of-service (DoS) vectors. An attacker could theoretically burn our CPU with cheap random bytes if we are not careful to abort early on impossible states.

• Memory Safety Review: While deserialize_form leverages Rust’s safe slices, we still need to audit the bounds checking logic manually. A panic here from an out-of-bounds slice access would crash the network layer. We need to guarantee that every single slice indexing operation is guarded by a length check before deployment.

• Future Optimizations: Can we compress these forms even further? Recent research in cryptography suggests that 96-byte compressions might be possible for 1024-bit discriminants. However, this would require a hard fork and rewriting both bqfc_compr and bqfc_decompr. For now, 100 bytes is the absolute sweet spot between implementation complexity, CPU verification time, and network bandwidth.

Crate: kyn-vdf

Stage: 06 (Verification)

Reading Time: 25 minutes

Depends On: kyn-vdf (Squaring / Proof Generation), kyn-types

What Is This?

This document covers the culminating step of the kyn-vdf crate: the Wesolowski verification phase. While earlier stages deal with the brutally slow and computationally intense process of generating a Verifiable Delay Function (VDF) proof through repeated squarings, this stage is entirely about validating that proof almost instantly. Specifically, this documentation explores the derivation of the Fiat-Shamir challenge, the fast verification mathematics, the pure-Rust entry point verify_chia_vdf in lib.rs, and the comprehensive error handling taxonomy defined in error.rs. In any system utilizing VDFs, the prover does all the heavy lifting over a sustained period of time, while the verifier must be able to confirm the work rapidly. This file explains how the Kinetic network achieves that critical asymmetry using pure Rust, enabling seamless execution across servers, mobile devices, and web browsers.

Why Kinetic Needs This

In a decentralized network like Kinetic, time must be objectively verifiable by anyone. Traditional consensus mechanisms often rely on raw hashing power (Proof of Work) or capital lockups (Proof of Stake). However, to prevent certain types of network manipulation— such as long-range attacks where an adversary tries to rewrite history— we need a cryptographic guarantee that a specific, unavoidable amount of sequential wall-clock time has passed. We use a VDF to prove this passage of time. A node generating a proof might spend 30 days of continuous CPU time computing billions of sequential operations. However, if verifying that proof also took 30 days, the entire network would grind to a halt. The nodes would never be able to synchronize. The entire system relies on an asymmetry: proof generation is intentionally slow and un-parallelizable, but verification must be almost instantaneous. Wesolowski’s protocol provides this exact mathematical property. It reduces a time-intensive operation into a quick cryptographic check, allowing the network to agree on the passage of time without having to re-compute the entire sequence.

But why do we need this specific implementation in pure Rust? Why not just use the existing, optimized C++ libraries provided by projects like Chia? The Kinetic architecture requires maximum portability and decentralization. We envision a network where a full node or a capable light client can run directly inside a standard web browser using WebAssembly (WASM). Traditional C++ cryptography libraries often rely heavily on underlying operating system APIs, custom memory allocators, and hardware-specific assembly instructions. These dependencies make them notoriously difficult and sometimes impossible to compile reliably to WASM. By rewriting the validation logic—specifically the Wesolowski verifier—in pure Rust, we leverage Rust’s powerful cross-compilation toolchains. More importantly, by utilizing the #![no_std] capability, we guarantee that this code does not depend on the standard C-like operating system underneath. It requires only a basic memory allocator. This means our VDF verifier can be deployed to any environment, including a browser, ensuring that users do not have to trust a centralized server to verify network state. It is lightweight, secure, and universally portable, which is a hard requirement for the frontend accessibility of the Kinetic ecosystem.

How It Works

The magic of Wesolowski verification lies in how it condenses billions of operations into a single equation: pi^B * x^r = y. To understand how this works in our codebase, we need to break down the environment, the variables, the math, and the exact code path. To prevent the prover from taking parallel shortcuts, the VDF operates within an Imaginary Quadratic Class Group. The crucial property of this mathematical group is that its “order” (the number of elements it contains) is unknown. Because the order is unknown, the prover cannot use shortcuts like Fermat’s Little Theorem to skip ahead in the computation. They are forced to perform every single squaring operation sequentially: x, x^2, x^4, x^8... up to x^(2^T).

When a prover finishes computing y = x^(2^T) (where T is the number of squarings, representing the time elapsed), they don’t just broadcast y. They also calculate and broadcast a proof element, pi. The verifier (any Kinetic node) must check if pi correctly proves that y was derived from x after exactly T squarings.

-> See: kyn-vdf/src/chia.rs — Lines 599 to 615 The first step in verification is determining the challenge, B. We cannot let the prover simply choose B, otherwise they could forge a valid-looking proof without doing the actual work. Instead, we use the Fiat-Shamir heuristic to make the process non-interactive and secure. We hash the public inputs together to deterministically generate a prime number. In our implementation, the function get_b takes the generator element x and the final output element y. It runs them through a secure cryptographic hash function to produce a 264-bit prime challenge. Because both the prover and verifier use the exact same deterministic hashing process on the identical inputs, they both arrive at the exact same prime B. The prover could not know B before they finished computing y, locking them into the honest computation.

-> See: kyn-vdf/src/chia.rs — Lines 616 to 640 Once the challenge B is derived, we must calculate the remainder r. Imagine dividing the total number of squarings 2^T by our challenge prime B. You would get some quotient q and a remainder r. , this is expressed as: 2^T = q * B + r. The verifier needs the remainder r. Fortunately, r is trivial to calculate quickly using modular arithmetic because we don’t actually need to compute the number 2^T. We simply compute r = 2^T mod B. Since B is a 264-bit prime, this modular exponentiation is fast, executing in microseconds.

-> See: kyn-vdf/src/chia.rs — Lines 641 to 670 Now we enter the core execution of verify_wesolowski. The prover has provided the proof pi. Under the hood, pi is actually the generator x raised to the quotient q (so, pi = x^q). The prover had to calculate this during the proof generation phase. We need to prove that the output equals the generator after T squarings: y = x^(2^T). We substitute our division formula for 2^T into the equation: y = x^(q * B + r). Using basic exponent rules, we can split this into two parts: y = (x^q)^B * x^r. Since the prover gave us pi (which represents x^q), we substitute pi in: y = pi^B * x^r. This is exactly the equation that verify_wesolowski calculates and checks. It takes the proof pi, raises it to the power of our derived prime challenge B, and multiplies it by the generator x raised to our calculated remainder r. If the result equals the claimed output y, the proof is cryptographically valid. Raising elements to the power of B and r only takes O(log B) operations using square-and-multiply algorithms. Since B is a 264-bit number, it takes roughly 264 squarings to verify the proof. It does not matter if T was a thousand or a billion; verification always takes roughly 264 operations. This is the breakthrough of Wesolowski’s protocol: compressing 30 days of computation into less than 100 milliseconds of verification time.

-> See: kyn-vdf/src/lib.rs While chia.rs handles the complex underlying mathematics, lib.rs provides the clean, unified entry point for the rest of the application: verify_chia_vdf. It bridges the gap between the raw bytes received over the Kinetic peer-to-peer network and the complex mathematical objects required by the verifier. It takes the serialized byte arrays for the discriminant, x, y, and the proof pi. It deserializes them, handles instantiation of the class group elements, and then cleanly orchestrates the call into verify_wesolowski. It acts as a strict abstraction boundary, shielding the rest of the Kinetic network daemon from the mathematical complexity, presenting a simple function that returns a successful Result or an error.

Key Pieces

get_b (Function)

-> See: kyn-vdf/src/chia.rs This function is responsible for executing the Fiat-Shamir transformation. It takes the serialized forms of the input generator and the output element, concatenates them, and hashes them repeatedly until it finds a valid 264-bit prime number. This matters tremendously because the entire security model of Wesolowski verification rests on B being a prime number that the prover could not predict or manipulate. By deriving it directly from the hash of the output y, we force the prover to finish computing the time-delay y before they can even know what B is, rendering forgery impossible.

verify_wesolowski (Function)

-> See: kyn-vdf/src/chia.rs This is the core mathematical engine of the crate. It is the direct implementation of the pi^B * x^r = y validation logic. It takes the generator x, the output y, the proof pi, the prime challenge B, and the remainder r. It performs the necessary imaginary quadratic class group operations— specifically squarings and multiplications— to evaluate the left side of the equation. This function relies on an underlying big-integer arithmetic library to handle the numbers involved. It is deeply optimized because a node syncing to the Kinetic network from scratch might need to verify thousands of these proofs in rapid succession.

verify_chia_vdf (Function)

-> See: kyn-vdf/src/lib.rs This is the primary public API of the crate. It is the integration and orchestration point. It accepts raw byte slices (&[u8]) for the inputs and the iteration count T. It safely parses these bytes into the mathematical ClassGroupElement structures, diligently handles any potential deserialization errors or malformed data, and coordinates the execution of verify_wesolowski. This is the function that the higher-level Kinetic daemon, the block validator, or the WASM wrapper will actively call.

KynVdfError (Enum)

-> See: kyn-vdf/src/error.rs This file defines the comprehensive taxonomy of everything that can possibly go wrong during the validation process. Using the thiserror crate, it defines clear variants such as:

• InvalidProofLength: Triggered if the byte array for pi is the wrong size.
• InvalidDiscriminantIdentity: Triggered if the prime discriminant doesn’t meet the strict cryptographic requirements for the class group.
• VerificationFailed: Triggered if the core math equation simply doesn’t balance out. This matters deeply because in an untrusted decentralized network, a node will constantly receive garbage data or malicious payloads. You must reject bad data with precise, typed, and understandable reasons to prevent cascading network failures and to allow developers to debug complex peer-to-peer data transmission issues effectively. The thiserror crate shines here by automatically deriving the Display and Error traits, eliminating hundreds of lines of tedious boilerplate code.

How This Connects to the Rest of Kinetic

CROSS-CRATE: This entire module acts as a vital, foundational cryptographic primitive for both the kinetic-verify and kinetic-node crates. When a Kinetic node receives a new block over the network or a time-challenge response, it cannot trust the data blindly. It extracts the raw VDF bytes from the block header and passes them directly to verify_chia_vdf exposed by lib.rs. If the function returns an error, the block is instantly dropped and the peer is penalized.

FORWARD DEPENDENCY: Because this verification logic is written in pure Rust and avoids standard library operating system calls (utilizing #![no_std]), it directly enables the kinetic-wasm crate. The kinetic-wasm crate will simply import kyn-vdf, wrap the verify_chia_vdf function in wasm-bindgen bindings, and output a Javascript-compatible WebAssembly module. This architecture guarantees that a Kinetic light client running in a web browser can verify time proofs locally and securely, without ever having to trust a centralized RPC server. This keeps the network genuinely decentralized down to the consumer frontend.

Quick Reference

• The Core Equation: pi^B * x^r == y
• T: The number of iterations (squarings), representing the exact amount of time elapsed.
• x: The initial generator value (the public input).
• y: The output value after precisely T squarings.
• pi: The proof element provided by the block generator.
• B: The Fiat-Shamir prime challenge, securely derived by hashing x and y.
• r: The remainder of 2^T mod B.
• Time Complexity: Proving requires O(T) sequential steps. Verifying requires only O(log B) steps.
• Portability Factor: Written in Pure Rust with zero C++ dependencies. no_std compatible, suited for WebAssembly compilation.

Open Questions / Things to Revisit

• Class Group Arithmetic Optimization: Are the underlying multiplications and squarings within verify_wesolowski as heavily optimized as possible? While the overall verification complexity is a minimal O(log B), implementing constant-time optimizations or advanced algorithms (like NUDUPL) in the underlying large integer library could yield measurable sync-time improvements during initial block download.
• WebAssembly Bundle Size: While pure Rust guarantees WASM compatibility, pulling in robust large integer math libraries might significantly inflate the final .wasm binary size. We should actively monitor and measure the compiled bundle size of kinetic-wasm to ensure it remains lightweight enough for instantaneous browser loading.
• Error Granularity and Telemetry: Should the generic VerificationFailed error variant be split into more specific granular variants? For example, separating a “mathematical mismatch” from an “invalid group element structure” might vastly improve debugging capabilities when analyzing edge cases in peer-to-peer data transmission or identifying new attack vectors on the node software.

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).

Crate: kinetic-vdf (Engine)

Stage: 02 Reading Time: 40 mins Depends On: kinetic-core

What Is This?

This file provides the primary implementation of the Verifiable Delay Function (VDF) engine for the entire Kinetic network architecture. It formally defines the ChiaVdfEngine struct within the Rust ecosystem. This struct acts as a robust, safe Rust wrapper around the external C++ chiavdf library. By wrapping this specific external library, Kinetic can harness production-ready, battle-tested cryptographic primitives. This eliminates the need for Kinetic developers to reinvent complex class group arithmetic natively in Rust, which is error-prone. Class group arithmetic involves deeply complex mathematical structures where the exact order of the group is unknown. This “unknown order” is the foundational security assumption for Wesolowski Verifiable Delay Functions. Without an unknown order, an attacker could trivially bypass the sequential delay by computing the order directly, defeating the entire mechanism. This wrapper code handles the crucial memory bridge between Kinetic’s internal Rust data structures (such as Commitment and VdfProof). It maps these clean Rust types to the low-level Foreign Function Interface (FFI) bindings provided by the chiavdf C++ codebase. The engine abstracts away the notorious complexity of C++ memory management, manual pointer casting, and cryptographic initialization configuration. It ensures that proper type conversions happen smoothly before bytes cross the language barrier. Ultimately, it presents a clean, memory-safe Rust trait (the VdfEngine trait) to the rest of the application. This ensures that all the unsafe C++ boundaries, memory allocations, and FFI idiosyncrasies are neatly and safely contained within this single file. Containing this unsafety prevents widespread memory leaks or segmentation faults from ever creeping into the rest of the node’s architecture.

Why Kinetic Needs This

In a decentralized, permissionless peer-to-peer network like Kinetic, time is inherently difficult to prove and agree upon across untrusted nodes. Unlike centralized servers, there is no master clock that all nodes trust implicitly. If a user wants to register or transfer a high-value domain name, malicious actors pose a severe and constant threat. Bots, predatory miners, or domain snipers might continuously monitor the unconfirmed transaction mempool, looking for valuable opportunities. When they see a valuable domain transfer pending, they can attempt to front-run the transaction by submitting a duplicate request but paying higher gas fees to miners. Imagine Alice wants to legitimately transfer alice.kin to a new wallet address to secure her assets. If she broadcasts the transaction normally, a sniper could instantly observe it, copy the payload, and submit it with a higher fee to steal the domain before Alice’s block is officially confirmed by the network. To prevent this unfair advantage, Kinetic enforces a strict, verified “time-locked grace period” on all domain transfers. A Verifiable Delay Function (VDF) is a specialized cryptographic algorithm designed specifically for this exact purpose. It requires a specific, predictable, and measurable amount of sequential computational work (the delay) to evaluate correctly. Crucially, it is designed to be fast to verify once the heavy computation is finally complete. By forcing a user to compute a VDF proof before their domain transfer transaction is considered valid, Kinetic proves to the entire network that a certain amount of real-world time has elapsed. Because the computation is sequential (meaning each calculation step depends on the exact output of the previous step), an attacker cannot speed it up. They cannot cheat the delay by throwing more CPU cores, parallel threads, ASICs, or server clusters at the problem; it must be done sequentially, step by step. However, this VDF evaluation is intensely CPU-heavy by explicit design. If an attacker deliberately submits hundreds of invalid or concurrent VDF evaluation requests to a single Kinetic node, the node’s CPU cores would all become fully saturated immediately. The node would rapidly exhaust its computational resources trying to evaluate the fake proofs simultaneously. This represents a Denial-of-Service (DoS) vulnerability that could easily crash the node, desync it from the network consensus, or trigger operating system out-of-memory (OOM) kills. Thus, Kinetic desperately needs this engine not only to compute the mathematical delays but also to enforce strict, operating-system-level resource management. This vital resource management is achieved via specialized filesystem locks. These file locks ensure that the node remains lightweight and responsive to the rest of the P2P network, carefully throttling the heavy delay computations to a manageable queue.

How It Works

1. Structure and Default Elements

#![allow(unused)]
fn main() {
-> See: src/lib.rs — Lines 30 to 52
}

The primary core type of the file is the ChiaVdfEngine struct, which acts as the main entry point for the module. It has no internal state fields, meaning it holds no variables, pointers, or flags. In standard Rust terminology, it is formally referred to as a zero-sized struct (ZST). This is because it merely orchestrates function calls to the external C++ library rather than storing persistent data in memory itself. The default_element() function is a crucial helper method that generates the identity element for the mathematical class group used by chiavdf. It constructs and returns a fixed 100-byte array where only the very first byte (index 0) is deliberately set to 0x08. The remaining 99 bytes of the array are initialized to zero during construction. This specific, hardcoded byte sequence is required by the underlying Wesolowski VDF implementation to function correctly. It serves as the standardized, universally agreed-upon starting point for the millions of repeated squaring operations that actually define the computational delay function. By standardizing this element, all nodes in the network agree on the exact mathematical starting line. The struct also implements the standard Default trait, allowing it to be instantiated ergonomically across the codebase without needing complex initialization parameters or factories.

2. Bounding the Execution to Prevent Infinite Loops

#![allow(unused)]
fn main() {
-> See: src/lib.rs — Lines 63 to 67
}

Inside the evaluate function, the very first operation executed is a critical safety check: if iterations > 400_000_000_000. A VDF’s total execution time is directly and linearly proportional to the number of iterations requested by the input challenge. > [!IMPORTANT]

If a malicious actor crafts a challenge with an artificially iteration count, the node could easily get stuck evaluating it for years. This would effectively lock up the node’s thread indefinitely, acting as a targeted DoS attack against specific peers. The arbitrary limit of 400 billion iterations equates roughly to 30 days of continuous computation on standard, modern hardware (assuming a relatively fast modern CPU architecture). By bounding this upper limit with a hardcoded ceiling, the node guarantees it will always eventually return from the function, even under adverse conditions. If the requested iterations exceed this hardcoded cap, the engine refuses to run at all. It immediately rejects the request with a safely typed VdfError::ProofGenerationError, sparing the node from useless computation.

3. Preventing CPU Starvation (The System Lock)

#![allow(unused)]
fn main() {
-> See: src/lib.rs — Lines 68 to 110
}

Important

This section implements the most critical defensive security mechanism in the entire file. Since the chiavdf C++ library is heavily optimized and computationally aggressive, running multiple instances concurrently will cause severe CPU thrashing. This aggressive thrashing would bring a typical server to its knees, starving all other critical background processes (like consensus validation and mempool management) of necessary CPU time. A standard Rust Mutex or RwLock would theoretically only lock threads within the currently running application process, which is insufficient. To enforce absolute mutual exclusion across the entire operating system (protecting against multiple Kinetic processes or isolated CLI tools running simultaneously), the engine leverages physical filesystem locks. It commands the OS to create a physical lock file on the disk uniquely named kinetic_vdf.lock. First, it intelligently attempts to find a suitable parent directory using the kinetic_core::config::get_base_dir() utility. If that primary directory creation fails, or if disk permissions are unexpectedly denied, it gracefully falls back to a Unix-specific temporary directory structurally bound to the active user’s UID (e.g., /tmp/kinetic-<uid>). Next, it securely configures standard file access options (specifically read, write, and create capabilities) using Rust’s std::fs::OpenOptions builder API. On Unix-based operating systems, it conditionally utilizes the std::os::unix::fs::OpenOptionsExt trait to set the libc::O_NOFOLLOW flag during file creation. This is a critical, subtle security measure designed to prevent devastating symlink attacks. Without this specific flag, a malicious user operating on a shared, multi-tenant server could secretly symlink the expected lock file path to a critical system file (such as /etc/shadow or a root binary). This would cause the Kinetic node (especially if inadvertently running with elevated privileges) to inadvertently corrupt or overwrite the system file with binary lock data, destroying the host operating system. Finally, after safely opening the file descriptor, it formally calls .lock_exclusive() provided by the external fs2::FileExt trait. This function call directly triggers a kernel-level OS file lock (such as flock on Linux/macOS or LockFileEx on modern Windows). If another local process already physically holds the active lock, this call will safely block the current thread until the lock is formally released by the kernel. This robustly guarantees that only one VDF evaluation happens on the physical machine at any given nanosecond, fully preserving vital system resources.

4. Generating the Proof via FFI

#![allow(unused)]
fn main() {
-> See: src/lib.rs — Lines 112 to 123
}

Once the OS lock is firmly and safely acquired by the thread, the engine confidently proceeds to call chiavdf::prove. It systematically passes the challenge.hash as the initial cryptographic random seed, the default_el identity bytes, the discriminant size (which is hardcoded securely to exactly 1024 bits), and the requested iterations. This specific action represents a complex Foreign Function Interface (FFI) call, crossing the strict memory boundary from safe Rust into unsafe, unmanaged C++. The underlying C++ library dynamically allocates the necessary heap memory, computes the Wesolowski proof through millions of repeated squaring steps, and finally returns the resulting byte array back to the Rust caller. Notice deeply that the lock file is never, ever unlocked via manual code (there is no unlock() method call written in the source). Rust elegantly utilizes the RAII (Resource Acquisition Is Initialization) memory management pattern to handle this . When the lock_file variable naturally goes out of scope at the absolute end of the evaluate function’s execution block, Rust’s Drop trait automatically engages in the background. The Drop trait cleanly and safely closes the underlying file descriptor tied to the lock. Closing the file descriptor automatically and natively instructs the operating system kernel to release the physical lock immediately across the whole system. This architectural design ensures no deadlocks occur, even if a runtime panic happens mid-computation or if the function returns early via the Rust ? operator.

5. Proof Verification and Size Bounds

#![allow(unused)]
fn main() {
-> See: src/lib.rs — Lines 131 to 140
}

Verification is routinely performed by all network validators whenever they receive a newly propagated block containing a time-sensitive domain transfer. The verify function must logically be fast, efficient, and lightweight to avoid significantly slowing down block propagation across the global network consensus layer. The very first check executed is a rudimentary basic sanity filter: if proof.proof_bytes.len() > 1024. Wesolowski proofs, by their fundamental mathematical nature, are guaranteed to be very small in byte size, regardless of the total iteration count processed. If a malicious peer intentionally sends a 50MB or 1GB proof over the network wire, it is undeniably an active attack. The attacker is obviously attempting to maliciously exhaust the node’s limited RAM during deserialization or trigger a forced OOM kill during verification processing. The engine rejects oversized proofs immediately, fully protecting the delicate C++ engine from ever allocating memory or processing malformed, intentionally bloated data.

6. Asymmetric Discriminant Derivation

#![allow(unused)]
fn main() {
-> See: src/lib.rs — Lines 142 to 149
}

This specific section highlights a slightly quirky and asymmetrical API design detail of the underlying chiavdf library bindings. When invoking the prove function earlier in the file, the C++ code natively takes the raw challenge hash and dynamically derives the 1024-bit prime discriminant entirely internally without user intervention. However, when invoking verify_n_wesolowski, the C++ API forces the Rust caller to provide the pre-derived discriminant as an argument. Therefore, Kinetic must manually allocate a 128-byte array buffer ([0u8; 128]) on the stack. It then manually calls the FFI function chiavdf::create_discriminant to derive the prime, operating symmetrically to how prove operates silently under the hood. A Discriminant is a vital mathematical parameter that defines the specific structure of the class group utilized for the sequential VDF operations. If this complex prime derivation fails (for instance, if the hash cannot be mapped to a valid, secure prime number), the engine gracefully bails and returns a DiscriminantError.

7. Calling the Verifier

#![allow(unused)]
fn main() {
-> See: src/lib.rs — Lines 151 to 162
}

The engine carefully bundles the freshly derived discriminant, the hardcoded 100-byte default element, the incoming untrusted proof bytes, and the original iteration count limit. It passes all these arguments directly into the chiavdf::verify_n_wesolowski FFI function to validate the math. The final argument passed is the recursion limit, which is hardcoded and permanently to 0. Some advanced VDF architectural configurations dynamically chunk their proofs into smaller sub-segments to heavily optimize specific edge cases or parallelize the verification process across multiple cores. However, Kinetic deliberately utilizes simple, small, single-segment Wesolowski proofs to minimize network overhead and consensus complexity. Because of this fundamental architectural choice, recursive segment checking is disabled entirely by passing 0 to the verifier. The C++ engine verifies the underlying mathematical proof against the inputs and returns a simple boolean indicating whether the proof is valid for the given challenge and iteration parameters.

8. Handling Unsupported Platforms (Mobile and Web)

#![allow(unused)]
fn main() {
-> See: src/lib.rs — Lines 165 to 195
}

Warning

The broader Kinetic ecosystem fully intends to extensively support lightweight client applications running natively on Android devices and within web browsers utilizing WebAssembly (WASM). However, the chiavdf library relies on intensely heavy C++ dependencies, deeply nested standard template libraries, and the GMP (GNU Multiple Precision Arithmetic Library). These complex, legacy dependencies simply do not cross-compile neatly, reliably, or natively to heavily constrained mobile or secure web environments. To elegantly handle this severe architectural limitation without bifurcating the entire codebase into separate repos, the file utilizes advanced Conditional Compilation via the #[cfg(...)] attribute macro. For specific unsupported compilation targets (namely target_os = "android" and target_arch = "wasm32"), the Rust compiler strips out the main C++ FFI implementation entirely during the build step. Instead of failing to compile, it neatly injects dummy implementations of the VdfEngine trait specifically tailored for these unsupported platforms. If a user mistakenly tries to evaluate or verify a VDF natively on a mobile phone or directly inside a browser extension, these lightweight dummy implementations engage safely. They immediately and safely return Err(VdfError::UnsupportedPlatform) without panicking, leaking memory, or crashing the host application.

Key Pieces

ChiaVdfEngine (Struct)

• What it does: Represents the primary, centralized VDF computation backend for the Kinetic daemon. It intentionally contains no state or fields.
• Where it is: src/lib.rs — Lines 30-31
• Why it matters: It is the concrete, strongly-typed implementation of the generic VdfEngine interface. This strict modularity allows Kinetic developers to swap out the underlying C++ library in the future (e.g., swapping for a pure Rust implementation) simply by writing a brand new struct that adheres to the identical core trait without rewriting consensus logic.

evaluate (Method)

• What it does: Computes the actual sequential delay function over time. It binds execution limits and securely enforces a global filesystem OS lock before safely calling into the C++ bindings.
• Where it is: src/lib.rs — Lines 63-123
• Why it matters: This is the core computational heavy lifter of the network. It protects the host node from DoS CPU starvation attacks via the robust OS-level fs2 lock. Furthermore, it ensures the computational time delay actually occurs physically as specified by the strict network consensus rules, protecting the domain registry.

verify (Method)

• What it does: Cryptographically checks a provided, untrusted VDF proof against a specific network challenge hash. It derives the required mathematical discriminant and formally delegates the intensive mathematical checks to the C++ verifier.
• Where it is: src/lib.rs — Lines 131-162
• Why it matters: This is the mission-critical fast path for block consensus. Network validators use this specific function to rapidly and decisively confirm that other peer nodes actually spent the necessary real-world time computing the VDF, securing the domain transfer mechanism against opportunistic front-runners.

fs2::FileExt::lock_exclusive()

• What it does: Safely obtains an exclusive, blocking file lock on the kinetic_vdf.lock file directly from the operating system kernel API.
• Where it is: src/lib.rs — Lines 104-110
• Why it matters: prevents multiple independent Rust threads, or entirely separate Kinetic daemon processes operating on the same physical machine, from fighting over CPU resources during intensive VDF generation, ensuring deeply stable node performance over long periods.

Conditional Compilation Attributes (#[cfg(...)])

• What it does: Directly instructs the Rust compiler to include or exclude specific blocks of implementation code based on the target operating system or hardware architecture provided at compile time.
• Where it is: src/lib.rs — Lines 54, 165, 181
• Why it matters: allows the entire unified Kinetic codebase to compile successfully on restricted mobile and web targets where the bulky C++ chiavdf library simply cannot be built, ensuring the rest of the application (like essential wallet management and basic peer discovery) still functions properly on those constrained platforms without issue.

How This Connects to the Rest of Kinetic

• CROSS-CRATE DEPENDENCY: This specific crate relies exceptionally heavily on kinetic-core for its foundational core types (specifically the Commitment and VdfProof structs) and its standardized network error handling enum (VdfError). It implements the VdfEngine trait originally defined in that core crate, adhering to the software dependency inversion principle to decouple logic.
• FORWARD DEPENDENCY: The primary network consensus engine (which is likely located in a downstream kinetic-consensus or kinetic-node crate architecture) will reliably instantiate ChiaVdfEngine during startup. It will then call the verify method sequentially during routine block validation to secure the chain. Additionally, the mempool or transaction builder module will call the evaluate method when an end-user formally initiates a time-locked domain transfer on the live network.

Quick Reference

• Max Iterations Hard Limit: 400,000,000,000 (allows up to approximately 30 days of continuous single-core CPU time before erroring out).
• Lock File Primary Search Location: kinetic_core::config::get_base_dir() (Standard application directory).
• Lock File Fallback Search Location: /tmp/kinetic-<uid> (This specific fallback is exclusively Unix specific).
• Lock File Standardized Name: kinetic_vdf.lock (Hardcoded string).
• Max Permitted Proof Byte Size: 1024 bytes (A strict 1 KB sanity check specifically against malicious memory exhaustion).
• Required Discriminant Size: 1024 bits (Equating to exactly 128 bytes of array data on the stack).
• Unsupported Platforms: Native android operating systems and wasm32 browser architectures.

Open Questions / Things to Revisit

• Mobile Verification Gap: Currently, native Android and WASM clients cannot verify VDF proofs locally because of the strict C++ dependency limitation. This realistically means light clients operating on mobile devices are forced to implicitly trust full remote nodes regarding the absolute validity of domain transfers. We may urgently need to find or build a pure-Rust VDF verifier in the near future to enable fully trustless, decentralized mobile clients without compromising security.
• Lock File Cleanup Strategies: The OS file lock is released gracefully and safely via Rust’s RAII drop mechanics, but the kinetic_vdf.lock file itself is permanently left lingering on the filesystem. Should there be an explicit, structured cleanup mechanism triggered if the daemon shuts down cleanly to prevent unnecessary clutter in the system’s temporary directories over the years?
• Hardcoded Default Element Assumptions: The default class group element (an array with 0x08 at the first byte) is hardcoded directly into the source code structure. If the mathematical class group specification ever changes in future network upgrades, this hardcoded array will need to be updated manually to match the new mathematical consensus rules.
• Fallback Lock Directory Behavior Risks: The fallback file path pointing to /tmp utilizes the running process ID on non-Unix systems. This could potentially lead to multiple unused, stale lock directories heavily piling up over time if the application forcefully crashes frequently or restarts unexpectedly often under heavy load.
• Error Handling Granularity Loss: The underlying C++ FFI layer returns a very simple Option (Some/None) for proof generation or a basic boolean for mathematical verification. We lose the diagnostic granularity of knowing exactly why the C++ engine actually failed during computation. It might be significantly beneficial to heavily modify the FFI wrapper to expose more detailed error codes directly from the chiavdf C++ bindings in future architectural updates to aid debugging.

Detailed Threat Model (The DoS Vector)

In blockchain networks, resource exhaustion is a primary attack vector. Because VDFs are inherently designed to be slow, they are a double-edged sword. If an attacker sends 10,000 invalid transactions to a node, standard signature verification might take a few milliseconds per transaction. The node can easily handle that throughput and ban the peer. However, if an attacker sends 100 transactions, each requiring a 5-minute VDF evaluation, the node is presented with 500 minutes of computation. If the node attempts to process these asynchronously using a thread pool, it will spawn 100 heavy threads. These threads will instantly lock up every CPU core on the machine at 100% utilization. During this time, the node cannot process legitimate blocks. It cannot respond to peer ping requests, causing it to be dropped from the network. It cannot serve RPC requests to the local user. The OS-level file lock (fs2) mitigates this by forcing a serial queue. Only one VDF is evaluated at a time, leaving the other CPU cores free for critical node operations. If the queue gets too long, the mempool can simply reject new VDF requests, preserving node stability.

Under the Hood: What is a Discriminant?

In the context of the Wesolowski Verifiable Delay Function, the mathematics operate within an imaginary quadratic number field. The “discriminant” is a negative prime number that uniquely defines this specific mathematical field. It is the cryptographic parameter that ensures the “unknown order” property holds true. To generate a secure VDF challenge, we must derive a unique discriminant for every single proof. Kinetic does this by taking the SHA-256 hash of the transaction commitment data. It then uses a deterministic algorithm (chiavdf::create_discriminant) to hunt for the nearest valid prime number to that hash. Because it is derived from the transaction hash, the discriminant is bound to that specific transaction. An attacker cannot reuse a VDF proof from a previous transaction because the hashes, and therefore the discriminants, will be entirely different. The size of this discriminant is fixed at 1024 bits (128 bytes). This size provides a cryptographic security margin against modern supercomputers. Even with parallelization, factoring a 1024-bit discriminant to discover the group order is computationally infeasible today.

Rust FFI Safety Practices

Integrating C++ code into a Rust project introduces memory safety risks. Rust’s compiler guarantees memory safety, but only for pure Rust code. The moment we cross the FFI boundary into chiavdf, those guarantees are temporarily suspended. If the C++ library has a buffer overflow or a double-free bug, it will crash the entire Rust application. To minimize this risk, this wrapper controls the data flowing into C++. It uses fixed-size arrays (like [u8; 100] for the default element and [0u8; 128] for the discriminant). By using fixed-size stack arrays, we avoid dynamic heap allocation issues on the Rust side. We pass these arrays to C++ as raw pointers (handled safely by the chiavdf binding crate). Furthermore, the sanity check if proof.proof_bytes.len() > 1024 acts as a crucial firewall. It prevents malformed, infinitely large byte arrays from the network from ever touching the C++ parsing logic. By keeping the unsafe FFI boundary as small and typed as possible, Kinetic maintains a high degree of overall system reliability.

03_tests.md - VDF Differential Cryptography Tests

Crate: kinetic-vdf Stage: 6 Reading Time: 25 minutes Depends on: lib.rs main implementation, kyn-vdf crate, chiavdf C++ bindings

What Is This?

This documentation covers the comprehensive internal test suite for the kinetic-vdf crate. Specifically, it focuses on the code located at the bottom of src/lib.rs (Lines 197-600). In Rust, it is a common idiom to place tests in the same file as the source code they are testing. These are usually wrapped in a mod tests block. They are conditionally compiled only during the testing phase using the #[cfg(test)] attribute. This ensures that the test code and its dependencies do not bloat the final release binary.

While standard unit tests usually just check if a single function returns an expected value, the tests contained in this file are far more advanced and critical to the network’s safety. This suite implements a series of rigorous Differential Cryptography Tests. Differential testing is an advanced software engineering and cryptography technique. It involves taking two entirely separate, independent implementations of a complex algorithm, feeding both implementations the exact same input data, and verifying that they produce the exact same outputs every single time.

In the context of this crate, the test suite acts as a bridge and an impartial referee. It compares two distinct VDF (Verifiable Delay Function) engines: 1. The original C++ chiavdf implementation, accessed via FFI (Foreign Function Interface) bindings. 2. The new pure-Rust kyn-vdf implementation, designed specifically for memory safety and strict parsing.

The tests in this file prove unequivocally that these two different codebases agree on the fundamental mathematical rules of the Kinetic network. They ensure that both engines recognize valid mathematical proofs as valid. More importantly, they guarantee that both engines will reject maliciously crafted, corrupted, or invalid proofs in the exact same manner, leaving no room for consensus discrepancies.

Why Kinetic Needs This

In a decentralized blockchain network like Kinetic, the consensus mechanism is everything. This consensus relies entirely on deterministic, unyielding mathematics. Every single node in the peer-to-peer network must independently verify the blockchain’s history. > [!WARNING]

If two nodes in the network disagree on whether a specific block’s VDF proof is valid, the network will instantly suffer a consensus failure. This disagreement will cause the blockchain to split into a hard fork.

Kinetic currently utilizes a dual-engine architecture for its Verifiable Delay Functions:

Because the proofs are created in C++ but verified in Rust, they must have absolute alignment. Their mathematical processing and binary parsing must be identical down to the very last byte. Consider a scenario where the C++ Timelord generates a proof that it believes is valid. If the Rust validator node rejects that exact same proof due to a slight parsing difference, or a minor mathematical rounding error, the entire blockchain halts immediately. Conversely, consider if a malicious attacker broadcasts a flawed, carefully crafted proof. If the C++ engine would correctly reject it, but the Rust engine accidentally accepts it due to a parser bug, the attacker could forge the blockchain history and hijack the network.

Differential testing is Kinetic’s primary, safety net against these apocalyptic scenarios. Instead of just hoping the two implementations match, this test suite guarantees it. It achieves this by throwing an , punishing battery of tests at both engines simultaneously. It uses valid proofs, invalid proofs, randomly corrupted proofs, proofs with mismatched parameters, and truncated byte arrays to verify that parity is absolute in every conceivable edge case.

Furthermore, this test suite acts as a powerful guarantee for strict Backwards Compatibility. When a blockchain relies on upstream C++ libraries, a silent version update can be deadly. An update might slightly alter how cryptographic seeds (called discriminants) are generated. If a new version silently changes the underlying math, all older blocks would suddenly fail validation. These tests hardcode known, historically expected outputs to act as immutable anchors in the codebase. If the underlying math ever changes silently, these tests will loudly fail during the local build process. This prevents an accidental network fork before the breaking code is even merged into the repository.

How It Works

The Baseline: Happy Path Verification

#![allow(unused)]
fn main() {
-> See: src/lib.rs — Lines 227 to 261
}

The test_kyn_vdf_verifies_kinetic_proof function establishes the fundamental differential baseline. It proves that the two distinct engines can communicate and fundamentally understand each other’s data formats. The test begins by initializing a new C++ ChiaVdfEngine instance. It creates a mock challenge hash, which is simply a structured array of thirty-two 1 bytes. It then instructs the C++ engine to perform exactly 1,000 iterations to generate a real, valid VDF proof.

Once the proof is successfully generated, the test enforces a strict, wire-format check: assert_eq!(proof.proof_bytes.len(), 200) Kinetic relies on the standard Chia wire format for all VDF proofs transmitted over the network. This standard requires the serialized proof to be exactly 200 bytes in length. The first 100 bytes represent the y coordinate of the proof. The second 100 bytes represent the pi structural proof.

Finally, the test takes those exact 200 bytes, straight from the C++ memory allocator, and passes them directly into the pure-Rust kyn_vdf::verify_chia_vdf() function. When the pure-Rust verifier successfully processes them and returns Ok(true), it establishes a critical fact. It proves that the core mathematics and the strict binary serialization format are aligned.

Concurrency and Thread Safety

#![allow(unused)]
fn main() {
-> See: src/lib.rs — Lines 263 to 286
}

The test_concurrent_evaluate function is crucial for testing the integrity and safety of the FFI boundary. C++ libraries are notoriously prone to severe thread-safety issues, especially when called from Rust. Rust is concurrent by design and expects fearless concurrency from all of its underlying dependencies. This test wraps the C++ engine in a Rust Arc (Atomic Reference Counted pointer). It then rapidly spawns multiple native OS threads using the thread::spawn API.

Each spawned thread independently and simultaneously attempts to generate a new VDF proof. They all use the exact same shared C++ engine concurrently. If the underlying C++ code had any unsafe global state, this test would catch it immediately. If it had hidden race conditions, or lacked proper thread-local memory isolation, this concurrent access would definitively trigger a segmentation fault or a memory corruption panic. By passing this test consistently, we guarantee that the kinetic-vdf crate is fully thread-safe. It is safe to use in a parallel, asynchronous environment like a high-throughput blockchain node.

Anchoring the Discriminant for Backwards Compatibility

#![allow(unused)]
fn main() {
-> See: src/lib.rs — Lines 321 to 340
}

The test_discriminant_consistency_across_versions function is our primary safeguard against dependency drift. In VDF cryptography, the “discriminant” is a number securely derived from the initial challenge hash. This discriminant defines the overarching mathematical group used for the sequential squaring operations. The test provides a specific, deterministic challenge hash: [42u8; 32]. It then asks the C++ engine to generate the 128-byte discriminant for this exact hash.

Crucially, the test then compares the first 16 bytes of the newly generated discriminant array against a hardcoded byte array that lives directly in the test source code: [237, 89, 165, 1, 5, 76, 207, 152, 207, 134, 182, 117, 254, 184, 124, 248] > [!IMPORTANT]

This hardcoded array acts as an immutable, unbreakable cryptographic anchor. If a future update to the chiavdf C++ library silently changes its internal hash algorithm, or if it subtly tweaks the derivation logic for the discriminant, the output will no longer match this array. The test will fail immediately and loudly during local development or in the CI pipeline. This warns the core developers that integrating the new C++ version will catastrophically break compatibility. It ensures that we never accidentally deploy a change that would invalidate historical blocks and fork the live network.

The Differential Fuzzer: Testing Failure Modes

#![allow(unused)]
fn main() {
-> See: src/lib.rs — Lines 343 to 598
}

The test_chiavdf_and_kyn_vdf_differential_compatibility function is the absolute crown jewel of the test suite. It acts as an , multi-step, relentless differential fuzzer. It runs a punishing gauntlet of seven rigorous checks over multiple different deterministic challenge hashes. Each of these mathematical challenges is evaluated for a realistic 10,000 iterations to ensure mathematical depth.

Step 1: Proof Generation The test uses the native C++ engine to generate a brand new, valid 200-byte proof. This generated proof is specific to the current deterministic challenge hash in the fuzzer loop.

Step 2 & 3: Dual Verification The test passes the newly generated proof back into the C++ verifier engine. This acts as a basic sanity check, ensuring the C++ engine actually accepts its own valid work. Then, it passes the exact same proof byte array into the pure-Rust kyn-vdf verifier engine. This ensures the Rust engine also accepts the valid proof, re-establishing the differential baseline.

Step 4: Single Bit Corruption -> See: src/lib.rs — Lines 427 to 470 The test intentionally and surgically corrupts the proof to ensure both engines detect the tampering. It clones the original proof bytes into a new, mutable array. It then cleverly uses the bitwise XOR assignment operator (^=) to flip exactly one single bit in the array: corrupted_bytes[50] ^= 0x01; Using XOR to selectively flip a bit in a valid proof is a standard, effective cryptographic testing technique. An attacker can easily provide purely random garbage data to a node. However, robust parsers often reject pure garbage data instantly, before ever reaching the complex mathematical logic. By flipping a single bit in an otherwise perfect and structurally sound proof, we ensure that the test bypasses these early, superficial parsing checks. This forces the verification engine to run the deep mathematical validation algorithms on corrupted data. The mathematical validation must ultimately and decisively fail. The C++ engine is expected to simply return a boolean false. The Rust engine (kyn_vdf) uses a Rust match statement to handle the rejection safely and gracefully. It correctly considers both Ok(false) (the math failed) and Err(_) (deserialization failed) as valid rejections. Both engines must universally reject the corrupted proof without crashing or panicking.

Step 5: Mismatched Iteration Counts -> See: src/lib.rs — Lines 472 to 508 The test takes the valid proof, but it lies to the verifiers about the required computational work. It passes iterations + 1 to both the C++ and Rust engines instead of the correct value. VDF proofs are , purposefully sensitive to the exact iteration count. Even being off by a single iteration means the resulting y coordinate should be , entirely different. This step ensures that both engines correctly and enforce the iteration parameter during verification. They must ruthlessly reject the proof if the parameter does not match the computational work encapsulated in the proof bytes.

Step 6: The Wrong Challenge Hash -> See: src/lib.rs — Lines 510 to 551 The test specifically mutates the original challenge hash. It again uses the XOR operator to flip the very first bit of the hash: wrong_hash[0] ^= 0x80;. However, it presents the original, valid proof bytes to the verifiers alongside this new, incorrect challenge. The challenge hash dictates the discriminant, which alters the mathematical group for the VDF. Therefore, a valid proof for Block A is meaningless garbage when evaluated for Block B. Both engines must firmly and immediately reject this attempt to replay a valid proof in the wrong context.

Step 7: Array Truncation -> See: src/lib.rs — Lines 553 to 590 The test removes the final byte of the serialized proof array. This artificially shrinks the array from the required 200 bytes down to an invalid 199 bytes. This step specifically tests the memory safety and boundary checking of the binary parsers in both languages. In C++, reading beyond the bounds of an array can easily cause a fatal segmentation fault or read uninitialized memory. The test verifies that the chiavdf C++ engine gracefully handles the truncated input array without any issues. It must return false cleanly without crashing the host process or corrupting the heap. For the Rust kyn-vdf engine, it verifies that the deserializer is enforcing the rigid wire format. It must return an explicit Err rather than attempting to pad the array with zeros or triggering a panic.

Key Pieces

The #[cfg(test)] Attribute

• What it is: A conditional compilation attribute directive built directly into the Rust compiler.
• Location: src/lib.rs — Line 197
• Why it matters: It tells the Rust compiler to ignore this module during standard release builds. The code is only compiled and included in the binary when the cargo test command is run. This ensures that heavy testing dependencies, mock data, and extensive fuzzing logic are never shipped to production nodes.

test_kyn_vdf_verifies_kinetic_proof

• What it does: Generates a real VDF proof using C++ and verifies it immediately using the pure Rust verifier.
• Location: src/lib.rs — Lines 228 to 261
• Why it matters: It proves that the “happy path” operates flawlessly across language boundaries and execution environments. It guarantees that the 200-byte binary serialization format translates between the C++ prover and the Rust verifier. It proves that the C++ prover and the Rust verifier speak the exact same mathematical language.

test_discriminant_consistency_across_versions

• What it does: Generates a discriminant from a known challenge and asserts an exact, byte-for-byte match.
• Location: src/lib.rs — Lines 321 to 340
• Why it matters: This is the primary, immovable defense mechanism against upstream dependency drift. It ensures that silent, undocumented changes to the C++ cryptographic library cannot inadvertently fork the blockchain.

test_chiavdf_and_kyn_vdf_differential_compatibility

• What it does: An extensive, multi-step, rigorous differential fuzzing test loop.
• Location: src/lib.rs — Lines 343 to 598
• Why it matters: It proves that the C++ and Rust engines have identical security profiles. They do not just agree on what a valid proof is when everything is correct and well-formed. They agree on exactly why and how invalid, malicious, or corrupted proofs should be rejected.

Bitwise XOR Mutation (^=)

• What it does: The bitwise XOR (exclusive OR) assignment operator, a staple in low-level programming. It compares the bits of a byte and flips the bit if they differ. For example, corrupted_bytes[50] ^= 0x01; takes the 50th byte and precisely flips its lowest bit.
• Location: src/lib.rs — Lines 438 and 518
• Why it matters: In cryptographic testing, providing invalid arrays is often entirely insufficient. Parsers will reject malformed arrays immediately without ever exercising the core mathematical validation logic. By using XOR to flip a single bit in a valid proof, the data looks legitimate enough to bypass the parser. This securely forces the engine to evaluate the complex math, ensuring the deep validation logic correctly catches the error.

The Commitment Struct

• What it is: A struct from kinetic_core::types used to represent a 32-byte hash.
• Location: src/lib.rs — Lines 205, 231, 323
• Why it matters: It encapsulates the challenge hash in a type-safe manner, ensuring that raw byte arrays are not accidentally passed around as valid challenge seeds.

How This Connects to the Rest of Kinetic

CROSS-CRATE DEPENDENCY: Validating kyn-vdf

This entire rigorous test suite is located inside the kinetic-vdf crate (which handles the legacy C++ FFI bindings). However, its true architectural purpose is to bless and validate the new kyn-vdf crate. When the main Kinetic consensus engine inside the kinetic-node crate calls the Rust verifier, it relies entirely, with full trust, on the absolute guarantees provided by this exact differential test suite. Without these tests passing consistently, kyn-vdf cannot be trusted to verify mainnet blocks.

FORWARD DEPENDENCY: Planned Consensus Hard Forks

If the Kinetic network ever decides to purposefully upgrade its cryptography in the future, such as switching to a significantly faster VDF class group or changing the underlying hashing algorithm, the hardcoded discriminant anchors within this file will intentionally and immediately fail. A core protocol developer will be required to manually calculate the new expected byte arrays. They will then have to purposefully update the hardcoded arrays in the source code themselves. This failure acts as a mandatory, unavoidable review gate for all developers. It ensures that any consensus hard fork is planned, thoroughly documented, and publicly communicated to node operators.

FORWARD DEPENDENCY: The Timelord Network Operations

In the live, production Kinetic network, Timelords will constantly execute the C++ chiavdf code. They will generate thousands of proofs every single day to secure the network. Every single validator node on the network will concurrently run the kyn-vdf Rust code to verify them. This test suite directly simulates and validates that exact, critical network interaction. Passing these tests is the primary indicator that the live network will be able to reach and maintain secure consensus.

Quick Reference

• Differential Testing: A strict testing methodology that runs identical inputs through two entirely distinct implementations. It guarantees identical outputs across different languages (C++ and Rust).
• Wire Format Requirement: Both engines must adhere to the 200-byte format constraint. This consists of exactly 100 bytes for the y coordinate and exactly 100 bytes for the pi proof structure.
• Discriminant Anchor: The 128-byte mathematical seed derived from a challenge hash is deeply anchored. It is anchored to hardcoded byte arrays to prevent silent upstream mathematical changes from causing accidental forks.
• Robust Failure Modes: The fuzzer tests how both engines react to adversarial network conditions. These conditions include specific bit corruption, incorrect iteration counts, mismatched challenge hashes, and array truncation.

Open Questions / Things to Revisit

• Test Execution Time Constraints: The differential fuzzer currently runs 10,000 iterations. It runs this heavy computational workload for multiple different challenge hashes in a loop. While thorough, this might significantly slow down execution times in debug builds. It could become a major bottleneck in continuous integration (CI) environments for every commit. We should strongly consider conditionalizing the iteration count based on the #[cfg(debug_assertions)] flag. This would allow local unit tests to run blazing fast with fewer iterations for developers. Meanwhile, the heavy 10,000 iteration test would be preserved for release builds and nightly CI runs.
• Property-Based Fuzzing Vectors: Currently, the bit corruption test only flips one single, specific bit. Specifically, it reliably executes corrupted_bytes[50] ^= 0x01;. We should deeply evaluate integrating a robust property-based testing framework like proptest. This would allow us to randomly and corrupt bits and bytes across the entire 200-byte proof payload. This advanced fuzzing would ensure that there are no specific, undiscovered byte offsets that could trigger a panic, segmentation fault, or unhandled exception in either the C++ or Rust parsers.
• Zero Iterations Differential Edge Case: The suite currently includes a standalone test_edge_cases function. This function (at Line 306) specifically verifies the C++ engine correctly rejects a proof with zero iterations. We should expand the main differential fuzzer suite to include this zero-iteration scenario as well. This will definitively ensure that the pure-Rust kyn-vdf engine handles this specific edge case identically to C++.
• Handling of C++ chiavdf Panics: The differential suite operates under a critical, optimistic assumption. It assumes that the C++ chiavdf library will gracefully return false or an error when presented with severe garbage. If the C++ library were to encounter a state that causes a hard segmentation fault or process abort, the Rust test runner would simply crash instantly without a clear Rust-level error trace or stack. This heavy reliance on the C++ library’s internal safety and error handling is precisely the reason why the Kinetic node architecture is actively migrating to the pure-Rust kyn-vdf engine. The Rust engine provides much stronger guarantees against fatal process crashes when handling untrusted remote network data.

Stage 4: VDF Utility Binaries (benchmark & prove_timing)

Crate: kinetic-vdf Reading Time: ~10-15 minutes Depends on: 03_engine.md (ChiaVdfEngine)

What Is This?

These are standalone utility programs compiled directly from the kinetic-vdf crate’s src/bin/ directory. They do not provide core network functionality to the Kinetic daemon itself. They are never imported as library code by other modules. Instead, they provide critical tooling used by developers and node operators.

Together, they form the hardware evaluation suite for Kinetic’s Verifiable Delay Function implementation.

Why Kinetic Needs This

Kinetic’s consensus security depends heavily on precise, hardware-dependent VDF timing. The core of a VDF is that it takes a verifiable, non-parallelizable amount of time to execute. You cannot throw more CPU cores at a VDF to make it go faster. It relies purely on the single-thread execution speed of the hardware.

If the required VDF iteration counts hardcoded into the network are too low:

• Blocks will be produced far too fast.
• The network will fork constantly.

If they are too high:

• The network grinds to a halt.
• Block production stalls for minutes at a time.

We need a concrete way to ask: “On this specific machine, how many VDF iterations equal exactly 60 seconds of computation?” That is precisely what benchmark.rs answers.

Similarly, Kinetic nodes spend a percentage of their CPU cycles verifying proofs generated by others. If verifying took as long as proving, the network would collapse under its own weight. We need empirical, real-world evidence to ensure that verification remains fast (logarithmic) compared to the slow, linear process of proof generation. prove_timing.rs acts as a developer sanity check. It guarantees the math holds up in the real world when interacting with the underlying C++ wrapper.

How It Works

The bin/ Directory Structure

In Rust, the src/bin/ directory is special. Cargo (Rust’s build system) automatically detects any .rs files placed in this directory. It builds them as standalone executable programs. This happens independently of the main library output of the crate.

They still have full access to the main library’s code. For example, they can import kinetic_vdf::ChiaVdfEngine. However, they get their own independent main() function entry point.

This pattern is why you don’t see these CLI tools polluting the core Kinetic daemon’s codebase. They sit cleanly alongside the VDF library code they test. This ensures the library remains lightweight while the tools are easily accessible via cargo run --bin.

Benchmark Routine

#![allow(unused)]
fn main() {
-> See: kinetic-vdf/src/bin/benchmark.rs — Lines 29 to 54
}

The benchmarking tool runs an infinite loop evaluating small chunks of the VDF. Instead of trying to run one evaluation that might overshoot the 60-second window, it executes the evaluate function in chunks of 10,000 iterations.

Step-by-step: 1. It instantiates the ChiaVdfEngine. 2. It creates a dummy 32-byte zeroed challenge hash. 3. It starts a high-precision timer using std::time::Instant::now(). 4. It enters a while loop, asking the ChiaVdfEngine to run exactly 10,000 iterations. 5. Every time a chunk finishes, it checks start.elapsed().as_secs() < 60. 6. If 60 seconds have passed on the monotonic clock, it breaks out of the loop. 7. It looks at the total iterations performed. 8. It then normalizes the result exactly to a 60.0-second window.

Normalization is fundamentally necessary. The very last 10,000-iteration chunk almost certainly pushed the clock slightly past the exact 60.000-second mark (e.g., stopping at 60.05 seconds). Normalization prevents timing drift.

This entire process repeats sequentially for 10 rounds. This smooths out random CPU spikes, thermal throttling, or operating system background tasks. The result is a stable, reliable hardware average.

Normalizing the Hardware Timing

#![allow(unused)]
fn main() {
-> See: kinetic-vdf/src/bin/benchmark.rs — Lines 62 to 72
}

Once the CPU’s average iterations-per-minute are averaged across all 10 rounds, the script fetches kinetic_core::constants::TARGET_MINUTES. This core constant determines what the target block time is supposed to be for the entire Kinetic network (usually a few minutes).

The script multiplies the hardware’s 1-minute baseline average by this network target. The result is the exact integer number that the user should copy and paste. It belongs in the network.json configuration file under the key benchmark_base_iterations.

Timing the Proofs vs Verification

#![allow(unused)]
fn main() {
-> See: kinetic-vdf/src/bin/prove_timing.rs — Lines 21 to 42
}

This script runs a preset array of iteration targets (T). These range from a trivial 100 all the way up to a 500,000 iterations.

For every single target T: 1. It first runs evaluate (proof generation) using a dummy 0x42 challenge hash. 2. It records the raw milliseconds elapsed. 3. Then, it takes the generated proof output. 4. It immediately runs verify on it. 5. It records that time separately.

Crucially, it runs assert!(valid) on the verification result. If the C++ library somehow generates an invalid proof, the script will panic and crash immediately rather than printing false data.

It prints the side-by-side comparison in a structured ASCII table. This proves that verification remains fast (usually well under 100ms). It holds true even as proof generation times scale linearly into the hundreds or thousands of milliseconds.

Key Pieces

std::time::Instant (Rust Standard Library)

#![allow(unused)]
fn main() {
-> See: kinetic-vdf/src/bin/benchmark.rs — Line 9
}

• What it does: Provides a monotonically non-decreasing hardware clock for the benchmark loop.
• Why it matters: Conceptually, Instant::now() is not asking the OS for the current date and time (like SystemTime). It queries a hardware counter. This guarantees that system clock changes (like NTP syncs or daylight savings adjustments occurring during a benchmark) do not suddenly warp the elapsed times. It purely measures absolute time passed.

chunk_size

#![allow(unused)]
fn main() {
-> See: kinetic-vdf/src/bin/benchmark.rs — Line 24
}

• What it does: Determines the stepping size for the evaluation loop (hardcoded to 10,000).
• Why it matters: If the chunk size was 1, the overhead of crossing the C++ FFI boundary would dwarf the actual VDF mathematical work. This would invalidate the benchmark entirely. If the chunk size was 1,000,000, we might wildly overshoot the 60-second timer window. We would be waiting minutes for the final chunk to finish before we can stop the clock.

total_iterations_per_minute (Vector)

#![allow(unused)]
fn main() {
-> See: kinetic-vdf/src/bin/benchmark.rs — Line 27
}

• What it does: A Vec that accumulates the normalized iterations across all 10 rounds.
• Why it matters: Storing these in a dynamically sized array allows us to calculate the true average at the very end of the run. In the future, this vector could easily be used to calculate standard deviation. It could also be used to discard statistical outliers if the CPU spiked randomly during one specific 60-second round.

t0.elapsed().as_secs_f64()

#![allow(unused)]
fn main() {
-> See: kinetic-vdf/src/bin/prove_timing.rs — Line 27
}

• What it does: Extracts the elapsed time from an Instant as a high-precision 64-bit float instead of an integer.
• Why it matters: For timing measurements in the microsecond or millisecond range, integer seconds are totally useless. They would just round down to 0. The float conversion lets us accurately scale down to exact fractional milliseconds for the output table by multiplying the result by 1000.0.

assert!(valid, ...)

#![allow(unused)]
fn main() {
-> See: kinetic-vdf/src/bin/prove_timing.rs — Line 36
}

• What it does: Instantly aborts the program if the verify function returns false.
• Why it matters: > [!IMPORTANT]

Silent failures in cryptography benchmarking are dangerous. If the engine somehow produces garbage bytes, assert! ensures the developer is notified via a loud panic. This is far better than silently logging 0ms verify times.

How This Connects to the Rest of Kinetic

CROSS-CRATE:

Both of these binaries directly pull in kinetic_core::traits::VdfEngine and kinetic_core::types::Commitment. This ensures they are using the exact same interface, traits, and data structures the main daemon uses.

FORWARD DEPENDENCY:

The console output of benchmark.rs forms the literal bedrock of Kinetic’s consensus difficulty. The benchmark_base_iterations value generated here is ingested by the networking stack upon node startup. It is used by the consensus layer to determine valid proof lengths during block generation. If this calibration is wrong, the network’s first epoch will have wildly unstable block intervals.

Quick Reference

• Command cargo run --release --bin benchmark - Find your machine’s optimal benchmark_base_iterations.
• Always run with --release otherwise debug overhead ruins the timing.
• Command cargo run --release --bin prove_timing - See the performance differences between generating and verifying proofs on your architecture.
• Both scripts rely entirely on the ChiaVdfEngine implementation binding to the underlying C++ libraries via FFI.
• The std::time::Instant type is crucial for all reliable sub-second hardware clock measurements in Rust.

Open Questions / Things to Revisit

• The benchmark script currently hardcodes the chunk size to exactly 10,000.
• Is this optimal for all hardware architectures?
• What if a future CPU is so fast that 10k iterations take less time than the Rust-to-C++ FFI context switch?
• The timing script notes at the bottom that pure-Rust kyn-vdf verify times are measured separately.
• It seems the pure-Rust verification might not be fully integrated into this automated test matrix yet, meaning the script only tests the C++ verify path.
• The benchmark runs for exactly 10 rounds of 60 seconds (10 full minutes total).
• This is a very long wait for a developer just trying to quickly spin up a local testnet.
• Perhaps we need to introduce a --fast command-line flag for quick-and-dirty calibrations that only run 1 or 2 rounds.
• The dummy challenge hash uses [0u8; 32] in the benchmark but [0x42u8; 32] in the timing script.
• This inconsistency has no functional impact, but it might be worth standardizing to avoid developer confusion.

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.

Types Names

crate: kinetic-core stage: 2 reading_time: 15 mins depends_on:

• crate::error::NamesError
• crate::constants::TLD_SUFFIX
• crate::types::infrastructure

What Is This?

This document breaks down the domain name validation module in kinetic-core/src/types/names.rs. It acts as the foundational authority for all .kin domain name registrations on the network.

Because Kinetic operates as a decentralized, permissionless ecosystem, there is no central authority or human-in-the-loop to review domain applications. Instead, the network relies entirely on deterministic, strictly codified rules running simultaneously on every node.

This file acts as the gatekeeper for the naming system, strictly defining what a valid domain name looks like and how it must be formatted before entering the state machine.

Because these rules are baked directly into the core Rust crate, every peer acts identically. Every peer parses incoming string requests in the exact same way. This ensures that the network state remains perfectly synchronized across thousands of nodes. It achieves this consensus without requiring any external or centralized validation services.

The logic within this module operates entirely statelessly. It does not check the blockchain state to see if a name is already owned or registered. Rather, it exclusively checks the syntactic validity of the requested name. It guarantees that no malformed data, hidden characters, or dangerous system names are ever submitted to the blockchain. By handling this at the lowest level, all higher-level smart contracts can trust the data implicitly.

Why Kinetic Needs This

The necessity of this module comes down to three primary pillars of decentralized network design:

1. State Consistency and Consensus Failures In a decentralized blockchain architecture, network consensus is extremely fragile. If two nodes disagree on how to interpret a piece of data, the network forks immediately. Consider a scenario where a user attempts to register the name EXAMPLE.KIN. Node A might decide to store the name exactly as written, in full uppercase. Node B, however, might run a normalization pass and convert it to lowercase example.kin. If a second user then attempts to register example.kin, the nodes will diverge in their validation. Node A would allow the registration, thinking it is distinct from the uppercase EXAMPLE.KIN. Node B would reject it, correctly identifying it as a duplicate registration attempt. This file completely eliminates that class of fatal consensus bugs. It forces a unified normalization step before any name is ever processed by the chain. Every peer that imports the kinetic-core crate will yield the exact same byte string. This guarantees cryptographic determinism across the entire decentralized network.

2. Defending Against Phishing and Homograph Attacks Decentralized networks and Web3 ecosystems are prime targets for scammers and phishers. If the naming system allowed unrestricted unicode characters, attackers would thrive instantly. Attackers could register domains that look visually identical to popular wallet services. For example, they could replace the standard Latin letter ‘a’ with a Cyrillic ‘a’. This Cyrillic letter has a completely different unicode byte value under the hood. However, it renders identically on a user’s screen in most modern web browsers. This is known in the cybersecurity world as a homograph attack. It is a major vector for wallet draining, phishing, and widespread credential theft.

Important

By strictly enforcing the standard DNS “LDH” rule (Letters, Digits, Hyphens), Kinetic stops this dead in its tracks. The system completely strips out any unicode, emojis, or complex international characters. This dramatically reduces the attack surface for visual spoofing against everyday users. Users can trust that what they see on their screen maps uniquely to a single ledger entry.

3. Infrastructure and System Protection Traditional operating systems, routers, and network stacks rely heavily on reserved domain names. Names like localhost, test, or invalid are deeply embedded into the fabric of the web. They exist in DNS resolvers, web browsers, and local routing configurations. If a malicious actor on Kinetic could register localhost.kin, the results would be disastrous. They could trick client applications into routing sensitive traffic improperly across the web. They could force web wallets or node software to talk to external IP addresses instead of local ones. Kinetic categorizes these globally understood system names as “Category 1” names. These are public utility names drawn directly from internet standards like RFC 2606 and RFC 6761.

Warning

By hardcoding a permanent blocklist of these Category 1 names, the network remains safe. It immunizes itself against a massive class of routing exploits and DNS rebinding attacks. Furthermore, the network protects its own future internal architecture by reserving “Category 2” names. Names such as seed, explorer, and docs are locked down by the protocol. This prevents opportunistic domain squatters from holding core infrastructure hostnames hostage.

How It Works

The lifecycle of domain name processing in Kinetic flows through a strict, multi-stage pipeline. Every user input string must pass through normalization, validation, and reservation checking.

The Normalization Pipeline

Before a name can be judged, it must be comprehensively cleaned and standardized. This prevents malicious actors from bypassing security checks using weird formatting tricks. -> See: kinetic-core/src/types/names.rs — Lines 19 to 28

The normalize_name function executes this critical cleaning process step-by-step:

• Lowercase Conversion: First, it calls .to_lowercase() on the raw input string. This ensures the entire Kinetic naming ecosystem is completely case-insensitive at the protocol level.
• Trailing Dot Removal: Next, it enters a while loop that continually pops off trailing dot characters (.). In legacy DNS architecture, a trailing dot signifies the absolute root of the internet. Kinetic strips it away to ensure canonical uniqueness.
• Suffix Appending: Finally, the function checks if the cleaned string already ends with the official network TLD. If the user only submitted “mywallet”, it automatically appends the TLD_SUFFIX. This provides a massive UX benefit for frontend developers, allowing them to submit partial names safely.

The Validation Pipeline

The is_valid_apex_name function is the primary and final gatekeeper for the network. -> See: kinetic-core/src/types/names.rs — Lines 75 to 124

Step 1: The Suffix Requirement Before any heavy processing occurs, it explicitly checks if the raw lowercase input ends with the TLD_SUFFIX. If it does not, it immediately throws an InvalidTLD error. This early exit ensures users cannot accidentally register .com or .eth domains on Kinetic.

Step 2: Total Length Limits The full string is measured against the strict, standard RFC 1035 length limits. The total length of the domain (including the suffix) cannot exceed 253 characters. Additionally, if the string is completely empty after normalization, it is instantly rejected.

Step 3: Label-by-Label Verification A standard domain name is made up of individual “labels” separated by dots. The function splits the normalized string by the . character and iterates through each label. The length of any single label cannot exceed a maximum of 63 characters. If a label is totally empty (like in the malformed string my..name.kin), it throws a LabelTooLong error.

Step 4: Character Allowlist (LDH) The function checks every single character residing within the current label. It heavily enforces the standard LDH rule: Letters, Digits, Hyphens only. If a character is not an ASCII lowercase letter, an ASCII digit, or a hyphen, it fails immediately. It throws an InvalidCharacter error, completely blocking emojis, spaces, underscores, and special symbols.

Step 5: Structural Edge Cases Even with allowed characters, their specific placement within the label heavily matters. A label is strictly forbidden from starting with a hyphen. A label is strictly forbidden from ending with a hyphen. Crucially, a label is also absolutely forbidden from starting with a digit. This specific rule prevents names from being confused with raw IP addresses or backend system flags.

Step 6: Apex Enforcement The Kinetic protocol currently only supports the registration of apex domains. Users are not permitted to register subdomains directly at the base protocol level. The validator extracts the apex of the string using the extract_apex_name helper function. If the normalized name does not perfectly match the extracted apex, it fails. The user’s request is safely rejected with a NotAnApexName error message.

Step 7: The Reservation Gauntlet The final step checks the normalized apex against the restricted reservation lists. It first calls is_reserved_name to check for collisions with Category 1 locked names. Then, it queries the external infrastructure module for Category 2 locked names. If the name hits either list, the validation fails and the transaction is aborted.

Extracting the Apex

To facilitate the apex enforcement rule, the system must isolate the base domain. -> See: kinetic-core/src/types/names.rs — Lines 126 to 137

The extract_apex_name function takes a fully normalized name string. It splits it into a standard vector of string slices (Vec<&str>). If this vector has 2 or more segments, it securely isolates the very last two segments. It joins them back together with a dot character and returns the newly formed string. If the vector has less than two segments, it simply returns the string exactly as it is.

Key Pieces

TLD Constant

• Name: TLD
• Type: &str
• Location: kinetic-core/src/types/names.rs — Line 4
• What it does: Defines the absolute primary top-level domain for the network.
• Why it matters: It acts as the central anchor for all domain-related logic in the crate. Hardcoding it here ensures no other module attempts to guess or reinvent the TLD.

PUBLIC_NAMES Constant Array

• Name: PUBLIC_NAMES
• Type: &[&str]
• Location: kinetic-core/src/types/names.rs — Lines 45 to 59
• What it does: A statically allocated slice of string slices representing Category 1 reserved names.
• Why it matters: These are globally recognized reserved domains defined by RFC 2606 and RFC 6761. Kinetic locks these names on-chain so internal network operations and Tor hidden services are never compromised.

normalize_name Function

#![allow(unused)]
fn main() {
pub fn normalize_name(name: &str) -> String
}

• Name: normalize_name
• Signature: pub fn normalize_name(name: &str) -> String
• Location: kinetic-core/src/types/names.rs — Lines 19 to 28
• What it does: Sanitizes messy user input into a canonical .kin formatted string.
• Why it matters: It ensures the complex validation logic only ever deals with perfectly clean data. It returns an owned String because it often needs to mutate the data by allocating memory to append the suffix.

is_reserved_name Function

#![allow(unused)]
fn main() {
pub fn is_reserved_name(name: &str) -> bool
}

• Name: is_reserved_name
• Signature: pub fn is_reserved_name(name: &str) -> bool
• Location: kinetic-core/src/types/names.rs — Lines 34 to 40
• What it does: Checks if a given name collides with the PUBLIC_NAMES array.
• Why it matters: It acts as an incredibly fast check for Category 1 collisions. It iterates through the array, appends the TLD suffix using a format macro dynamically, and checks for a direct match.

is_valid_apex_name Function

#![allow(unused)]
fn main() {
pub fn is_valid_apex_name(name: &str) -> Result<(), crate::error::NamesError>
}

• Name: is_valid_apex_name
• Signature: pub fn is_valid_apex_name(name: &str) -> Result<(), crate::error::NamesError>
• Location: kinetic-core/src/types/names.rs — Lines 75 to 124
• What it does: The master security gate and final authority for the naming system.
• Why it matters: It deliberately returns a Result instead of a simple boolean. This allows the Kinetic RPC servers to display highly specific error messages like NamesError::InvalidCharacter instead of a generic, unhelpful failure message to the end user.

extract_apex_name Function

#![allow(unused)]
fn main() {
pub fn extract_apex_name(name: &str) -> String
}

• Name: extract_apex_name
• Signature: pub fn extract_apex_name(name: &str) -> String
• Location: kinetic-core/src/types/names.rs — Lines 126 to 137
• What it does: Strips away arbitrary subdomains to return just the base registered apex string.
• Why it matters: When routing a transaction to api.wallet.kin, the network needs to accurately resolve the true owner of wallet.kin. This function provides a robust, fast way to find that base domain every time.

Property-Based Testing

• Location: kinetic-core/src/types/names.rs — Lines 259 to 281 -> See RUST_CONCEPTS.md for an explanation of proptest!. Property tests throw thousands of random, malformed strings at the functions to ensure they never trigger a Rust panic.

How This Connects to the Rest of Kinetic

This module serves as an essential foundational primitive sitting near the very bottom of the dependency graph.

FORWARD DEPENDENCY: crate::error::NamesError The primary validation function relies intimately on the NamesError enum defined elsewhere. It returns specific variants like NamesError::InvalidCharacter and NamesError::NotAnApexName. These rich error variants flow upward through the entire application stack. They eventually get translated into human-readable JSON responses by the RPC API endpoint.

FORWARD DEPENDENCY: crate::constants::TLD_SUFFIX Rather than hardcoding the raw string ".kin" inside the validation loop, the module imports TLD_SUFFIX. This is a highly critical architectural decision for the network’s future. It means developers can easily spin up private testnets that use a different suffix like ".test". They can accomplish this by changing one single constant, and all validation automatically adapts without rewrites.

CROSS-CRATE: crate::types::infrastructure::is_infrastructure_name This particular file handles Category 1 (internet-wide public utility) locked names. However, it explicitly delegates Category 2 names to the infrastructure module. Category 2 names are highly specific to Kinetic’s own internal architecture and deployment. By calling out to the infrastructure module, the naming layer maintains a beautifully clean separation of concerns.

Quick Reference

If you are developing a client application or wallet, you must adhere to these absolute rules:

• Canonical Suffix: The name must fundamentally end with the network suffix.
• Case Sensitivity: Names are totally case-insensitive on-chain; they always process as lowercase.
• Maximum Total Length: The complete domain name cannot ever exceed 253 characters.
• Maximum Label Length: Any single dot-separated segment cannot ever exceed 63 characters.
• Minimum Label Length: A segment cannot be completely empty; consecutive dots will fail.
• Allowed Character Set (LDH):
  • Lowercase ASCII letters (a through z).
  • ASCII digits (0 through 9).
  • Hyphens (-).
• Positional Rules:
  • A label MUST NOT begin with a hyphen.
  • A label MUST NOT end with a hyphen.
  • A label MUST NOT begin with a digit (e.g., 1wallet.kin is rejected).
• Subdomain Restriction: You can only register an apex domain. Third-level domains are heavily blocked.
• Reserved Names List: You cannot register any of the following restricted names: test, example, invalid, localhost, local, onion, arpa, null, none, zero, corp, lan, or internal.

Open Questions / Things to Revisit

There are several design limitations that the Kinetic engineering team will need to address over time.

1. Lack of Internationalized Domain Names (IDN) The validation pipeline is locked down to standard ASCII characters. This is the absolute safest choice for a decentralized network launch. It entirely avoids the immensely complex landscape of unicode homograph attacks. However, users globally will demand the ability to register names using non-Latin alphabets. To safely support this feature, the validation logic will need to fully integrate Punycode. This will add significant computational complexity and risk to the validation rules.

2. Second-Level TLD Extraction Vulnerability The extract_apex_name function blindly grabs the last two string segments of the domain. This works flawlessly right now under a single-level TLD architecture like .kin. However, if the network ever supports second-level TLDs (like .co.kin or .gov.kin), it will break. It would incorrectly identify user.co.kin as being the apex co.kin, destroying routing logic. If hierarchical TLDs are introduced, this function must be replaced by a Public Suffix List parser.

3. Performance of Normalization Allocations The normalize_name function is called constantly during network routing and block validation. Currently, it returns a brand new, heap-allocated String every single time it runs. In a high-throughput scenario processing thousands of transactions per second, this is a severe bottleneck. It is highly worth investigating whether this can be optimized using Rust’s Cow<'_, str> type. This Copy-on-Write pointer would gracefully avoid memory allocations when the input is perfectly formatted.

4. Protocol-Level Subdomain Support Currently, is_valid_apex_name explicitly blocks the base registration of any subdomains. If a user owns company.kin, they can configure local routing for blog.company.kin on their own node. However, they cannot trade blog.company.kin as an independent entity on the distributed ledger. If Kinetic wants to support granular subdomain leasing, a massive secondary validation path is needed. This new path would deliberately bypass the apex restriction while still strictly enforcing all other rules.

5. The Concept of Registration Expiration This entire module deals purely with syntactic validity. It asks a very simple question: “Is this string formatted correctly according to the rules?” It does not ask, “Is this name currently active, owned, or expired on the blockchain?” Passing the is_valid_apex_name check only means the string is syntactically allowed to exist. State-level checks and database lookups are always required before finalizing any registration transaction.

6. Penalizing Malicious Registration Attempts The validation logic quickly rejects bad names, but it is currently a free operation. If a malicious actor spams the network with thousands of invalid name registrations, the nodes must process them. Should the protocol implement a slashing mechanism or a minimum fee just for submitting a name? This would prevent denial-of-service attacks aimed specifically at the names.rs validation pipeline.

Types Identity

crate: kinetic-core stage: 3 reading_time: 45 mins depends_on: [kinetic_kid::document::KidDocument, kinetic_kid::manifest::CapabilityManifest, ml_dsa::MlDsa65]

What Is This?

This document covers the loading, derivation, and persistent storage of post-quantum ML-DSA-65 signing keypairs in identity.rs. The identity file serves as the root of trust for any node participating in the network. Without a functioning identity, a node cannot authorize namespaces, sign gossip messages, or establish authenticated P2P connections.

It outlines the authorization structures (AuthorizedKid and AuthorizedManifest) that bind cryptographic identities to human-readable network names (like .kin domains).

This module manages reconstructing post-quantum signature matrices from 32-byte seeds or BIP-39 mnemonic phrases. It secures these seeds via AES-256-GCM encryption on the filesystem, wipes intermediate memory using the zeroize crate, and enforces filesystem access controls to defend against local privilege escalation. -> See RUST_CONCEPTS.md for explanations of Zeroize, AES256Gcm, pbkdf2_hmac, and Nonce.

Why Kinetic Needs This

In a fully decentralized, self-sovereign environment like the Kinetic network, a node’s entire identity, authority, and reputation are completely defined by its cryptographic key material. Unlike traditional web systems where identity is tethered to and validated by a central certificate authority (like TLS certificates), Kinetic nodes must prove their identity autonomously. There is no central server to reset a password or recover an account. The node operator bears full sovereign responsibility for their cryptographic keys. However, Kinetic is built explicitly for the post-quantum era. It operates under the assumption that traditional cryptography will eventually fall to quantum computers. Post-quantum ML-DSA-65 (formerly known as Dilithium) keypairs are extremely large compared to classic Elliptic Curve Cryptography (ECC) or RSA keys. A single ML-DSA-65 public key is over 1 kilobyte in size. The private key matrix is substantially larger than the public key. Their sheer physical size makes them incredibly cumbersome to handle in everyday operations. They are difficult to transmit efficiently. They are effectively impossible to backup securely on physical paper without risk of transcription errors. They are complicated to store safely in environment variables.

Kinetic elegantly addresses this usability hurdle by taking a philosophical stance: it never persists or requires node operators to backup full, expanded ML-DSA-65 keypairs. Instead, it relies entirely on highly compressed, maximal-entropy 32-byte seeds as the root of all cryptographic derivation. These tiny 32-byte seeds can be seamlessly encoded as 24-word BIP-39 mnemonic seed phrases. This borrows a highly familiar, battle-tested, and user-friendly paradigm from cryptocurrency hardware wallets. This specific module implements the vital computational bridge. It expands these massive post-quantum keys from those tiny 32-byte seeds dynamically at runtime every single time the node starts up.

Furthermore, node operators frequently run their infrastructure on shared virtual private servers (VPS) or heavily multi-tenant cloud environments. Because of this, the local private key material must be aggressively protected. This protection must actively prevent side-channel filesystem extraction attacks. It must stop malicious co-tenants from stealthily accessing the keys via directory traversal. This strict threat model necessitates strict POSIX file permission enforcement at the operating system level. It also requires military-grade AES encryption for node operators who choose to encrypt their local disk state. Critically, it requires rapid intermediate memory zeroization (via the zeroize trait implementation) during key generation. This ensures that the raw seed phrase does not linger in RAM where a subsequent core dump could expose it to attackers.

Lastly, the Kinetic network scales across multiple distinct topologies. This includes the public mainnet, isolated developer testnets, and private corporate subnets. The system requires foolproof, unforgeable mechanisms to prevent cross-network replay attacks. An attacker must never be able to take a valid identity authorization signature generated harmlessly on a local testnet and broadcast it maliciously on the mainnet. Such an attack could allow malicious actors to hijack namespaces or impersonate legitimate services across network boundaries. The tightly controlled, network-scoped signable byte structures implemented in this module provide the cryptographic guarantees that completely neutralize this attack vector at the lowest serialization layer.

How It Works

The lifecycle of an identity in Kinetic is meticulously broken down into distinct, heavily guarded operational phases. These phases include secure generation and safe persistence from a human-readable phrase. They include highly protected retrieval and decryption at runtime. They include the deployment of that loaded key to authorize network-specific data structures.

1. Secure Mnemonic Key Generation and Derivation

The critical process of translating a human-readable string into a post-quantum signing key relies on aggressive cryptographic key stretching. This is explicitly designed to mathematically thwart offline dictionary and brute-force permutation attacks.

-> See: kinetic-core/src/types/identity.rs — Lines 150 to 186

When the save_keypair_from_mnemonic function is invoked by the node bootstrapping process, it executes a rigid pipeline:

1. Strict Mnemonic Validation: The function immediately parses the 24-word string using the bip39 crate. It strictly validates the mnemonic against the standard English wordlist. It also verifies the embedded checksum derived from the original entropy. If a user mistypes a single character or word, it immediately errors out with KIN-IDN-004. If the checksum is invalid, it errors out. This prevents the generation of an unrecoverable phantom key that the user cannot later restore.
2. Raw Entropy Extraction: The successfully validated mnemonic is converted into its raw 64-byte entropy seed form. At this stage, no additional passphrase is used for the BIP-39 algorithm itself. The empty string "" is explicitly passed to the derivation function.
3. Network-Specific Deterministic Salting: To ensure that the exact same seed phrase intentionally produces completely different mathematical keys across different network architectures, a salt is constructed dynamically at runtime. The salt format is exclusively format!("{}-seed-key-v1", network_id). This guarantees perfect cryptographic domain separation across networks. This means a testnet key derived from a phrase fundamentally cannot sign mainnet transactions, even if the node operator makes a configuration error.
4. Iterative Key Stretching (PBKDF2): The system heavily stretches the entropy using the pbkdf2_hmac algorithm. This algorithm is combined with the robust Sha512 hashing primitive. In release builds (triggered via the #[cfg(not(debug_assertions))] compiler flag), this runs through an astronomical 5,000,000 iterations. This extreme iteration count is critical for security against offline attacks. It ensures that even if a highly resourced attacker attempts to rapidly brute-force variations of a partially recovered seed, the sheer computational latency of millions of SHA-512 hashes per guess renders the attack mathematically infeasible on modern GPU clusters.
5. Post-Quantum Expansion: The resulting 32-byte derived output from the PBKDF2 operation is still not the final usable key. It is explicitly fed into the ml_dsa::SigningKey::<ml_dsa::MlDsa65>::from_seed constructor. The internal ML-DSA-65 algorithms then mathematically expand this minimal, high-entropy seed. They expand it into the massive, multi-kilobyte matrix structures required for post-quantum signature generation.

Important

6. Aggressive Memory Zeroization: This is a crucial, non-negotiable security guarantee against memory introspection. Immediately after the ML-DSA-65 key is successfully populated, the intermediate 64-byte raw mnemonic seed must be wiped. The 32-byte derived PBKDF2 output must also be wiped. They both have the .zeroize() method explicitly called upon them. This action physically overwrites the specific memory buffers in the process RAM with null bytes (0x00). If a malicious process attempts to execute a core dump a microsecond later, the seed material is already permanently destroyed in volatile memory. If an attacker uses a debugger to inspect the running process, they will only find null bytes.

2. Atomic File Persistence

Writing the 32-byte seed to the physical storage medium prioritizes data corruption prevention, transaction atomicity, and local operating system access control.

-> See: kinetic-core/src/types/identity.rs — Lines 187 to 210

Kinetic writes the newly derived seed to a temporary file with a .tmp extension alongside the intended destination path instead of overwriting existing key files directly.

Crucially, it utilizes the standard library’s OpenOptions::new() to apply strict 0o600 POSIX permissions upon file creation. This specific UNIX permission integer is passed to the OS kernel. It instructs the operating system kernel that only the exact user executing the node process is allowed to read or write to this file. All group members are hard-blocked from reading the file contents at the OS filesystem layer. All other generalized system users are also hard-blocked.

Once the exact 32-byte sequence is written to the operating system’s internal filesystem cache buffer, a vital stabilization step occurs. The system call file.sync_all() is immediately invoked on the open file handle. This system call forcefully bypasses the OS write cache. It forces the operating system block layer to perform a synchronous hardware-level flush to the physical disk platter or NVMe SSD storage controller. Only after the hardware controller explicitly acknowledges that the data is physically committed to non-volatile storage does the module proceed.

Finally, it utilizes the fs::rename operation to atomically swap the .tmp file over the active, primary key file path. By leveraging the atomic guarantees of POSIX rename operations, Kinetic guarantees absolute state consistency. It guarantees that a sudden data center power loss during the bootstrap sequence can never result in a corrupted identity file. It guarantees that a kernel panic during saving will never leave an empty file. It guarantees that an abrupt node termination will not result in a half-written file. The identity state on disk is always strictly binary: completely successfully written, or entirely absent.

3. Hydrating the Identity at Runtime

When the Kinetic node initiates its startup sequence, it must rapidly locate this persistent seed on disk. It must then re-hydrate the ML-DSA-65 signing key matrix into operational memory. The module provides dual support for reading both raw plaintext seed files and highly secure AES-encrypted seed files.

Loading Plaintext Keys

-> See: kinetic-core/src/types/identity.rs — Lines 45 to 65

For a standard node runtime leveraging load_keypair, the system first probes the filesystem. It does this by evaluating the ENV_KEY_PATH environment variable override (crate::constants::ENV_KEY_PATH). If this override is absent, it elegantly falls back to utilizing the default configuration base directory. It then appends the provided filename to this base path.

Upon successfully opening and reading the file, it enforces an uncompromising structural boundary check before processing the bytes. If the file is not exactly 32 bytes in length, the operation is immediately rejected entirely. It yields a CorruptedIdentityFile error (KIN-IDN-002) detailing the unexpected length. This specific, rigid constraint prevents the accidental ingestion of full-sized key files that a user might mistakenly paste in. It prevents the ingestion of malformed mnemonic string backups saved in text files. It prevents failures caused by randomly corrupted filesystem sectors. It strictly guarantees that only perfectly formed 32-byte seeds enter the complex ML-DSA-65 algorithms. After validation, it simply copies the bytes into a fixed-size [0u8; 32] array. Finally, it passes this array to the ml_dsa::SigningKey::<ml_dsa::MlDsa65>::from_seed() method.

Loading Encrypted Keys

-> See: kinetic-core/src/types/identity.rs — Lines 81 to 123

For highly security-conscious node operators utilizing load_encrypted_keypair, the underlying file layout is significantly more complex. It expects a rigid, concatenated binary payload sequence rather than raw bytes:

• 16 bytes: A cryptographically secure random salt generated exclusively for the PBKDF2 stretching phase during the initial encryption pass.
• 12 bytes: A unique, cryptographically secure random Nonce (Number used once) required by the AES-GCM cipher algorithm logic.
• Remaining bytes: The actual AES encrypted ciphertext natively alongside the implicitly attached 16-byte GCM MAC (Message Authentication Code).

When hydrating an encrypted key, the plaintext password supplied by the node operator must be aggressively stretched. This utilizes the exact same 5,000,000 iteration PBKDF2-HMAC-SHA512 process used in mnemonic generation. The password is mathematically hashed against the dynamically extracted 16-byte salt parsed from the file header block. This complex, highly intensive computational process deterministically derives the final 32-byte AES symmetric key required for decryption.

The Aes256Gcm cipher struct is then instantiated using this freshly derived key. The 12-byte nonce slice is aligned and passed into the decrypt method. The ciphertext payload is finally submitted for decryption. AES-GCM is an authenticated encryption cipher, which is a critical security property for Kinetic. This means it implicitly mathematically verifies the 16-byte MAC during the single decryption pass. Consequently, any malicious tampering with the file bytes on disk will result in a hard, immediate decryption failure. Any arbitrary bit-flipping caused by cosmic rays or failing SSD sectors will also result in immediate failure. This yields a DecryptionFailed error. It will absolutely never silently output garbage, unpredictable decrypted data into the highly sensitive ML-DSA-65 constructor. This strictly prevents undefined cryptographic behavior at the core node level.

4. Fortified Cross-Network Replay Protection

When a user’s cryptographic identity is successfully loaded into memory, it is utilized to authorize network primitives. A common, foundational example is securely linking a mathematical public key to the highly valuable saif.kin namespace document. A critical security invariant in this decentralized architecture is that an authorization signature generated on a specific network layer must absolutely only be mathematically valid on that exact intended network. It must never cross boundaries.

-> See: kinetic-types/src/identity.rs — Lines 35 to 55

Both the AuthorizedKid and AuthorizedManifest wrapper structures implement a crucial .signable_bytes(network_id) method. Rather than naively passing the raw JSON string to the signature algorithm, they construct a tightly controlled binary payload. Rather than using a loosely concatenated payload, they enforce a rigidly framed binary format:

1. network_id prefix (e.g., the raw UTF-8 bytes of the string kin-mainnet-v1 or kin-testnet-v2)
2. A literal protocol suffix byte string array: exactly -auth-kid-v1 or -auth-manifest-v1
3. A 32-bit big-endian length prefix precisely encoding the length of the namespace string (via u32::to_be_bytes())
4. The exact UTF-8 bytes of the associated network name string itself
5. A 32-bit big-endian length prefix encoding the exact byte length of the internal payload’s canonical representation
6. The canonical, perfectly ordered byte string of the core payload document itself

By permanently hardcoding the environment’s network_id string at the very absolute start of the binary serialization, signatures are explicitly scoped. A signature produced specifically for a local development network like kin-testnet structurally and mathematically cannot ever validate on the production kin-mainnet. The raw byte payload that the ML-DSA-65 signature natively wraps will intrinsically and catastrophically differ due to this prefix boundary.

Furthermore, the strategic use of strict length prefixing ensures that a sophisticated malicious actor cannot creatively exploit byte boundaries to forge signatures. Length prefixing is robustly achieved via the standard u32::to_be_bytes(). Without length prefixes, an attacker might attempt to creatively merge the trailing characters of a name with the leading characters of a payload. This could theoretically maliciously forge a completely different structural context that happens to hash to the exact same overall byte value. Length prefixes categorically eliminate this entire class of subtle boundary manipulation and semantic ambiguity attacks.

Key Pieces

load_keypair

• What it does: Reads a raw 32-byte seed sequence directly from the designated filesystem path.
• Validation: Strictly validates its exact physical byte length before any cryptographic processing begins.
• Expansion: Mathematically expands the 32-byte seed into a fully operational post-quantum ML-DSA-65 matrix keypair ready for rapid signature operations.
• Location: kinetic-core/src/types/identity.rs:39
• Why it matters: This function represents the primary initialization path for all standard Kinetic nodes to acquire their operational cryptographic identity.
• Error Codes: Can return KIN-IDN-001 (IO error), KIN-IDN-002 (Corrupted File), or KIN-IDN-003 (Not Found).
• Failure Impact: If this function fails due to filesystem errors, missing paths, or file corruption, the node is rendered cryptographically inert. It cannot sign internal gossip messages. It cannot participate in network consensus. It cannot authorize any namespace transactions.

load_encrypted_keypair

• What it does: Securely parses a concatenated AES-GCM encrypted binary payload from the local disk.
• Decryption Flow: It dynamically unpacks the embedded cryptographic salt and nonce headers from the unencrypted prefix bytes of the file.
• Key Stretching: It aggressively stretches the node operator’s provided plaintext password through 5,000,000 rounds of PBKDF2 to derive a symmetric AES decryption key.
• Finalization: It authenticated-decrypts the internal ciphertext using the MAC. It finally feeds the resulting raw 32 bytes into the ML-DSA-65 expansion algorithm.
• Location: kinetic-core/src/types/identity.rs:69
• Why it matters: This function provides vital, defense-in-depth security for high-value node runners (such as foundational relay nodes, critical infrastructure providers, or high-value namespace owners).
• Threat Model: These high-value nodes might be specifically targeted by sophisticated server breaches or zero-day OS exploits designed to steal key files. The extreme 5-million iteration PBKDF2 stretch makes offline dictionary cracking operations of these stolen files computationally bankrupting for the attacker.

save_keypair_from_mnemonic

• What it does: Thoroughly validates and parses a standard 24-word BIP-39 mnemonic string provided by the user.
• Derivation: It algorithmically derives a network-specific cryptographic salt and heavily stretches the resulting entropy via the PBKDF2 algorithm.
• Persistence: It persistently saves the resulting 32-byte output atomically to disk hardware using temporary files and POSIX rename operations.
• Security: It enforces tight 0o600 POSIX access control lists (ACLs) before explicitly and aggressively wiping intermediate RAM buffers containing the raw mnemonic entropy using the .zeroize() method.
• Location: kinetic-core/src/types/identity.rs:150
• Why it matters: This function is the sole, highly secure mechanism by which human-readable backups (which can be written on physical paper) are converted into operational, machine-readable post-quantum signature keys.
• Hardware Safety: The stringent atomic filesystem write operations guarantee absolute data safety against sudden hardware power interruptions or kernel panics during the highly vulnerable initial node provisioning sequence.

AuthorizedKid

• What it does: A comprehensive wrapper struct logically pairing a baseline KidDocument with a specific .kin network string name.
• Binding Mechanism: It is crucially bounded by a mathematically unforgeable, network-scoped ML-DSA-65 owner signature verifying the precise structural attachment of the name to the public keys.
• Fields:
  • name: The .kin string literal representing the human-readable namespace.
  • kid_doc: The embedded raw KID document containing the node’s public keys.
  • owner_signature: The raw bytes of the ML-DSA-65 post-quantum signature proving ownership.
• Location: kinetic-types/src/identity.rs:15
• Why it matters: Within the Kinetic architectural ecosystem, floating decentralized identifiers (KIDs) constitute the base, anonymous identity layer.
• Identity Elevation: This specific struct elevates an isolated, floating KID by cryptographically anchoring and binding it to a highly specific, easily human-readable namespace. This transformation makes the identity highly routable. It makes it globally discoverable. It makes it socially relevant within the P2P overlay network.

AuthorizedManifest

• What it does: A structural mirror to the KID authorization logic, this struct firmly pairs a complex CapabilityManifest with a network namespace.
• Composition: It optionally appends the parent contextual KID document. It binds all of these tightly together by the exact same network-scoped authorization signature.
• Fields:
  • name: The .kin string literal representing the human-readable namespace.
  • manifest: The embedded raw capability manifest document outlining node permissions and services.
  • kid_doc: Optional inclusion of the parent identity document for immediate verification context.
  • owner_signature: The raw bytes of the ML-DSA-65 post-quantum signature proving capability ownership.
• Location: kinetic-types/src/identity.rs:59
• Why it matters: This struct enables abstract network capabilities (such as localized service hosting, sub-protocol participation rights, or highly restricted data access scopes) to be demonstrably and publicly owned by a specific .kin name.
• Consistency: The internal byte layout and structural serialization design perfectly mirror the AuthorizedKid implementation. This maintains cognitive and structural homogeneity across the codebase’s core authorization mechanics.

How This Connects to the Rest of Kinetic

• FORWARD DEPENDENCY: The fully hydrated ML-DSA-65 keys generated by this module are heavily consumed globally by the network transport layer. -> See: kinetic-core/src/network/peer.rs These deeply derived keys are specifically utilized to digitally sign all internal network handshakes. This ensures every single P2P TCP connection is mutually authenticated using post-quantum cryptographic primitives.
• FORWARD DEPENDENCY: The heavily scrutinized AuthorizedKid and AuthorizedManifest serialization structs represent the primary, foundational payload structures physically transmitted over the global gossip network. -> See: kinetic-core/src/validation.rs The mathematically sound .signable_bytes() method is heavily invoked downstream by the consensus logic. This is done to independently verify the structural integrity of floating namespaces broadcast by untrusted remote network peers.
• CROSS-CRATE: This entire identity subsystem fundamentally relies on the isolated kinetic-kid crate for the baseline mathematical definitions of the KidDocument and CapabilityManifest internal structures. The logic defined here effectively serves as a higher-level organizational wrapper. It introduces the critical “name binding” and precise “network scope” validation metadata rigorously demanded by the active Peer-to-Peer operational layer.

Quick Reference

• Core Cryptographic Standard: ML-DSA-65 (NIST Post-Quantum Cryptography Standardization, formerly Dilithium).
• Physical Disk Footprint: Exactly 32 bytes strictly for plaintext seed operations.
• Encrypted Disk Footprint: Exactly 60 bytes for AES-encrypted payloads (16 byte Salt + 12 byte Nonce + 32 byte Ciphertext and appended MAC).
• Key Stretching Configuration: A strict requirement of 5,000,000 PBKDF2 iterations utilizing the SHA-512 hashing algorithm on compiled release builds. (1,000 iterations for debug builds).
• Operational Filesystem Permissions: Hardcoded to strictly enforce 0o600 access (Read and Write by file owner exclusively) on all UNIX-like operating systems.
• Cryptographic Replay Protection: Foundational protection implemented intrinsically via rigid network-prefixing at the raw binary serialization layer prior to any signature application.
• Memory Security Posture: Highly vulnerable intermediate RAM allocations are aggressively destroyed using the explicit zeroize operational trait to neutralize sophisticated memory dump extraction exploits.
• Key Derivation Path: Mnemonic Phrase -> 64-byte raw entropy -> PBKDF2-HMAC-SHA512 with network salt -> 32-byte derived seed -> ML-DSA-65 Expanded Key Matrix.

Open Questions / Things to Revisit

• PBKDF2 vs Argon2 Migration: The network is currently hardcoded to utilize PBKDF2-HMAC-SHA512. While this algorithm is highly robust, time-tested, and officially NIST approved, modern cryptographic research indicates that Argon2id provides fundamentally superior, memory-hard resistance against highly optimized ASIC (Application-Specific Integrated Circuit) and GPU-cluster cracking attempts. We should deeply evaluate and potentially schedule migrating the core key derivation function for the encrypted file loading sequence to provide superior resistance against offline brute-forcing.

Warning

• Windows File Permissions Parity: The explicit, strict 0o600 permission constraint is currently rigidly scoped via the #[cfg(unix)] compilation flag in Rust. We urgently need to investigate and ensure that native Windows OS compiled implementations correctly translate this requirement by aggressively restricting file Access Control Lists (ACLs) exclusively to the executing service user. Failure to do so risks trivial privilege escalation local reads on compromised Windows servers.

Important

• Browser WebAssembly (WASM) Ecosystem Support: Currently, the entire disk-based key loading and mnemonic saving logic is completely gated behind the #[cfg(not(target_arch = "wasm32"))] compilation flag due to its reliance on standard library file I/O operations (std::fs). If the long-term architectural goal dictates that lightweight web browser clients need to natively generate or securely load keypairs, we must meticulously implement a highly secure storage adapter. This could utilize IndexedDB or asynchronous Web Crypto API backed storage that strictly adheres to the exact same stringent hardware-level security guarantees currently provided by the native POSIX filesystem adapter.

• Cryptographic Key Rotation APIs: There is currently absolutely no public API surface exposed in this file to gracefully rotate an operationally compromised 32-byte seed into a completely new seed. Simultaneously, the node must safely maintain the exact same historical identity bindings and network reputation. This missing feature is a major friction point for long-term node sustainability and requires immediate architectural design to prevent node reputation loss upon key compromise.
• Password Strength Enforcement: The load_encrypted_keypair logic relies entirely on the user providing a “strong password” during the initial encryption pass. There is currently no API enforcement during the creation phase of an encrypted keypair to ensure the password meets standard entropy requirements (length, character complexity). We should seriously consider adding an entropy validation pass using a library like zxcvbn before allowing encryption to proceed to disk.

Deep Dive: ML-DSA-65 vs Classical Keys

To truly understand why Kinetic architected the system around 32-byte seeds instead of storing the keys directly, one must understand ML-DSA-65. ML-DSA-65 is the NIST standardization of the Dilithium algorithm.

Because quantum computers running Shor’s algorithm can trivially break RSA and ECC, those algorithms are obsolete for future-proof networks. However, the mathematical structures (matrices and polynomials) required for ML-DSA-65 are massive.

If Kinetic forced users to back up 4,032 bytes of random private key data, physical paper backups would be impossible. It would require printing QR codes that are extremely dense and prone to scanning failures. By deterministically generating the 4,032 bytes from a 32-byte seed at runtime, the physical backup remains a simple 24-word phrase.

Byte Serialization Example

The replay protection mechanism requires strict byte layout adherence. Consider a node authorizing the name saif.kin on kin-testnet. The .signable_bytes("kin-testnet") method constructs the exact array passed to the signer.

1. kin-testnet -> 11 bytes ([107, 105, 110, 45, 116, 101, 115, 116, 110, 101, 116]).
2. -auth-kid-v1 -> 12 bytes ([45, 97, 117, 116, 104, 45, 107, 105, 100, 45, 118, 49]).
3. Length of name saif.kin -> 8 bytes. As a 32-bit big-endian integer, this is [0, 0, 0, 8].
4. The name itself saif.kin -> 8 bytes ([115, 97, 105, 102, 46, 107, 105, 110]).
5. Length of canonical JSON -> [0, 0, 1, 144] (assuming 400 bytes).
6. The canonical JSON bytes. If a malicious actor captures this signature and broadcasts it to kin-mainnet, the validation logic will reconstruct the required bytes starting with [107, 105, 110, 45, 109, 97, 105, 110, 110, 101, 116]. Because the very first bytes of the hash input differ, the final hash differs entirely. The ML-DSA-65 signature verification will immediately mathematically reject the signature as invalid for the given payload.

Step-by-Step Flow: Encrypted Key Loading

Let’s walk through the exact execution trace when a user boots a node with an encrypted identity file.

1. The node process starts and reads KINETIC_KEY_PATH.
2. It calls fs::read and pulls the entire file into a heap-allocated Vec<u8>.
3. It performs a boundary check: bytes.len() < 16 + 12 + 16. If true, it returns CorruptedIdentityFile.
4. It slices &bytes[0..16] to extract the PBKDF2 salt.
5. It slices &bytes[16..28] to extract the AES-GCM Nonce.
6. It slices &bytes[28..] to extract the ciphertext and MAC.
7. It allocates a [0u8; 32] buffer for the AES key on the stack.
8. It invokes pbkdf2_hmac::<Sha512>. This blocks the thread, executing 5,000,000 SHA-512 hashes.
9. It instantiates Aes256Gcm::new using the resulting stack buffer.
10. It calls cipher.decrypt.
11. AES-GCM calculates the authentication tag over the ciphertext and compares it to the MAC.
12. If they match, the plaintext 32 bytes are returned.
13. The plaintext bytes are passed to ml_dsa::SigningKey::from_seed.
14. The fully hydrated key is returned to the node’s core state machine.

Detailed Error Analysis

The identity module utilizes a strict, custom error enum named IdentityError. Each variant maps to a highly specific failure mode during the bootstrap process. Understanding these errors is critical for debugging node initialization failures.

IdentityNotFound (KIN-IDN-003)

• Trigger: The fs::read system call yields a NotFound standard library IO error.
• Context: The node was started, but the identity.bin file simply does not exist at the resolved path.
• Resolution: The user must explicitly run kinetic seed init to generate a new key.
• Resolution (Recovery): Alternatively, the user must run kinetic seed restore and provide their 24-word backup phrase.

CorruptedIdentityFile (KIN-IDN-002)

• Trigger: The filesystem read succeeds, but the resulting byte vector length is unexpected.
• Context (Plaintext): The file length is not exactly 32 bytes.
• Context (Encrypted): The file length is less than 44 bytes (16 salt + 12 nonce + 16 MAC).
• Resolution: The file has been fundamentally tampered with or corrupted by the OS block layer. The user must delete the file and restore from their mnemonic backup.

DecryptionFailed

• Trigger: The Aes256Gcm::decrypt method returns an error.
• Context: This occurs for two primary reasons. First, the user provided the incorrect password, resulting in the wrong AES key, causing MAC validation to fail. Second, the ciphertext bytes on disk were modified, causing MAC validation to fail even with the correct password.
• Resolution: The user must retry with the correct password. If they have forgotten the password, the encrypted file is mathematically useless, and they must restore from the mnemonic backup.

InvalidSeedPhrase (KIN-IDN-004)

• Trigger: The bip39::Mnemonic::parse_in method returns an error.
• Context: The user attempted to restore a node, but the phrase provided contains invalid words, incorrect spelling, or an invalid cryptographic checksum.
• Resolution: The user must carefully verify their physical backup and ensure all words strictly match the BIP-39 English dictionary specification.

Error Design Philosophy

The overarching philosophy of this module is to fail closed. If there is any ambiguity whatsoever regarding the integrity of the key material, the node will panic and exit. It will never attempt to automatically guess a password. It will never attempt to truncate a corrupted file to 32 bytes. It will never bypass MAC validation. This rigid “fail closed” architecture prevents the node from ever booting into an undefined cryptographic state.

Types Dns

title: kinetic-core/src/types/dns.rs stage: 4 reading_time: 30 minutes depends_on: kinetic-types::dns, kinetic-core/src/error/dns.rs

What Is This?

This module serves as the boundary between the external internet and Kinetic’s internal DNS state machine.

It takes raw DNS zone data—submitted as JSON payloads—and enforces strict validation before allowing it to persist into the decentralized ledger.

In the Kinetic ecosystem, Domain Name System (DNS) resolution is not just about translating legacy domains like example.com into an IPv4 address. It is the fundamental routing layer for the decentralized web. Because of this dual mandate, this file handles both traditional internet DNS concepts (such as A, AAAA, CNAME, and TXT records) alongside Kinetic-native decentralized routing primitives (such as libp2p Peer IDs, Kinetic Key Identifiers, and IPFS content hashes).

Specifically, this file in kinetic-core implements the DnsZoneExt extension trait. This trait binds heavy, computationally expensive validation logic and memory-safe parsing directly to the bare, lightweight DnsZone data structures that are defined over in the kinetic-types crate.

Why Kinetic Needs This

When you build a decentralized peer-to-peer network, the data you receive from the outside world is fundamentally adversarial. You cannot trust the client submitting the data. If Kinetic validator nodes were to blindly accept whatever DNS JSON payloads were broadcasted to them, the network would collapse almost immediately due to a variety of attack vectors. Here is a detailed breakdown of why this specific validation layer is an absolute necessity:

1. State Bloat Protection: In a decentralized network architecture, every full node has to store the global state of the network. Storage is a premium resource.

Warning

If a malicious actor could publish a single DNS zone containing 10,000 garbage records, they could rapidly fill up the hard drives of every node on the network, effectively executing a resource-exhaustion attack for pennies in transaction fees. This file steps in and enforces a strict, hard-coded 50-record cap per DNS zone to guarantee bounded state growth.

2. Denial of Service (DoS) Prevention via JSON Bombs: Parsing JSON is computationally expensive and heavily utilizes the application’s call stack. Attackers often deploy “JSON bombs”—deeply nested recursive structures like [[[[{"a": "b"}]]]]. When standard JSON parsers attempt to evaluate these, they recurse so deeply that they blow past the operating system’s stack limit, instantly crashing the node. This module intentionally utilizes serde_json::from_slice which contains explicit, hard-coded recursion limits to protect the node’s memory architecture.
3. Delayed Routing Integrity: If a user submits an invalid libp2p PeerId (e.g., a string missing a few characters) or a malformed IPFS CID, and the consensus network accepts it without checking, the network will not crash immediately. Instead, the error lies dormant in the database. Hours or days later, when an innocent client attempts to connect to that peer, the client’s routing engine will panic or fail. We must fail early and loudly. This file ensures that invalid routing parameters never make it into the state database.
4. Standard DNS Specification Compatibility: Legacy DNS has strict, time- tested rules. For example, DNS RFCs mandate that a CNAME record acts as an exclusive alias—it cannot coexist on the same label as an IP address or a TXT record. Kinetic nodes must enforce these legacy rules flawlessly so that Kinetic domains can seamlessly bridge back to standard Web2 DNS resolvers (like Cloudflare or Google) without breaking them.
5. Deterministic Cryptographic Verification: In a decentralized environment, nodes must prove ownership over their routing changes. The validation structures contained in this file ensure that the bytes being cryptographically signed by the user are highly deterministic and resistant to parsing ambiguities, preventing signature-spoofing attacks.

How It Works

This file orchestrates a highly robust, multi-stage processing pipeline. It takes an array of raw, untrusted bytes from the network and walks it through parsing, normalization, capacity checking, and deep cryptographic validation.

Stage 1: Safe and Bounded Payload Parsing

The entire process begins when the network receives a DNS update request. At this point, the request is nothing more than an array of raw bytes (&[u8]). -> See: kinetic-core/src/types/dns.rs — Lines 28-30

A naive implementation might convert these bytes into a Rust String (which requires the CPU to perform an expensive, full-pass UTF-8 validation) and then parse that string into JSON. Instead, the code directly invokes serde_json::from_slice. This function operates directly on the underlying byte array. Because it operates on bytes, it is extremely fast and can perform zero-copy deserialization where possible, meaning it borrows strings directly from the byte array instead of allocating new memory for them. More importantly, it utilizes Serde’s built-in recursion limits, protecting the node from the stack- overflow DoS attacks mentioned earlier. If the JSON is invalid, it throws a standard error, halting the transaction instantly.

Stage 2: Normalization and Case-Insensitivity

By standard definition, DNS labels are supposed to be entirely case-insensitive. A user visiting API.kinetic.host expects to be routed to the exact same destination as a user visiting api.kinetic.host. However, underneath the hood, the data is stored in a Rust HashMap. A hash map calculates hashes based on precise bytes, meaning it treats "API" and "api" as two completely distinct, non-colliding keys. -> See: kinetic-core/src/types/dns.rs — Lines 31-36

To solve this discrepancy without frustrating the user by rejecting their payload, the parser automatically normalizes the data. It achieves this by allocating a brand new HashMap. It then drains the contents of the original, raw parsed map. For every single key-value pair, it converts the key to lowercase. It utilizes the powerful Rust idiom: .entry(k.to_lowercase()).or_default().extend(v). This looks up the lowercase key in the new map. If it doesn’t exist, it gracefully inserts an empty vector. Then, it extends that vector with the incoming records. If a user poorly formatted their payload and submitted separate records for both API and api, this logic safely and efficiently merges all of those records into a single, unified api array.

Stage 3: Network Capacity Limits

Once the data structure is fully normalized, the validate() method takes command of the pipeline. -> See: kinetic-core/src/types/dns.rs — Lines 55-60

Before it even looks at the content of the records, it performs a purely quantitative network capacity check. It iterates over all the values (the vectors of records) contained within the hash map, maps them to their respective lengths, and sums them up into a single integer. If the total number of records across the entire DNS zone exceeds 50, the function immediately aborts, returning a TooManyRecords error.

Important

This is a critical security constraint. It definitively bounds the maximum size of a single DNS state entry in the blockchain, ensuring that validation times and state synchronization metrics remain predictable and lightweight.

Stage 4: Label Syntax Enforcement

Next, the validator enters a loop, evaluating every single label (the subdomain string, like www, api, or @) provided in the zone. -> See: kinetic-core/src/types/dns.rs — Lines 61-78

It applies a battery of string-manipulation checks to ensure compliance with DNS standards:

• Length Limits: The label absolutely cannot be empty (length of 0), and it cannot exceed 63 characters in length. This is a strict limitation inherited from legacy DNS architecture.
• Root and Wildcards: It explicitly bypasses further string-character checks if the label is precisely @ (which represents the root apex of the domain) or * (which represents a wildcard routing mechanism).
• Hyphen Edge-Case Rules: The label cannot start with a hyphen, nor can it end with a hyphen (e.g., -www or api- are strictly invalid).
• Character Allowlist: It iterates character by character over the string. If a character is not an ASCII alphanumeric, a hyphen, or an underscore, it throws an InvalidLabelCharacters error. No emojis or arbitrary Unicode are allowed in raw labels without punycode encoding.

Stage 5: CNAME Exclusivity and Collision Avoidance

-> See: kinetic-core/src/types/dns.rs — Lines 80-85

This stage enforces one of the most commonly misunderstood rules of DNS RFCs. If a label contains a CNAME (Canonical Name) record, that label is acting as a hard, redirecting alias to another domain entirely. Therefore, it is mathematically and logically impossible for that label to also contain an A record (an IP address) or a TXT record alongside it. The validator checks the array of records. If any single record is a CNAME variant, the code asserts that the total length of the array must be exactly 1. If the length is greater than 1, it realizes a collision has occurred and throws an InvalidCnameConfiguration error, saving the user from a broken domain setup.

Stage 6: Granular Record-Specific Validation

Finally, it matches on the specific enum variant of each individual record and applies bespoke, tight validation rules based on the intended destination. -> See: kinetic-core/src/types/dns.rs — Lines 87-122

• TXT Records: Must be strictly bounded to 255 bytes or smaller, throwing TxtRecordTooLong if violated.
• CNAME Targets: The destination domain string cannot be empty, and it cannot exceed 253 characters.
• Peer IDs: The raw string is passed to libp2p_identity::PeerId::from_str. If the underlying libp2p cryptographic library cannot parse it into a valid, structurally sound peer identifier, the record is rejected. This guarantees routing integrity later in the node’s lifecycle.
• KIDs (Kinetic Identifiers): Kinetic Identity Documents must strictly begin with the exact prefix did:kin:. If a user attempts to map a domain to a different decentralized identifier method (like did:eth: or did:pkh:), the system will emit a warning log and reject the payload, ensuring only native identities are bound.
• IPFS CIDs: IPFS Content Identifiers must not be overly long (capped at 100 characters), and they must begin with either Qm (indicating an older CIDv0 Base58 encoded hash) or b (indicating a newer CIDv1 Base32 encoded hash).

Stage 7: Host Routing Serialization Protocol

While not part of the validate() function for the overarching zone, the HostRoutingRecord contains its own complex serialization pipeline for cryptographic validation. -> See: kinetic-types/src/dns.rs — Lines 61-79

When a routing record is signed, the signable_bytes() method constructs a deterministic byte array. It pre-allocates a vector with exact capacity to prevent memory reallocation lag. It then pushes the bytes in a highly structured format: first a network ID, then a hardcoded string -routing-v1, then the length of the host ID as a 4-byte big-endian integer, the host ID itself, the length of the peer ID as a 4-byte big-endian integer, the peer ID itself, and finally an 8-byte big-endian integer representing the Drand beacon timestamp. This rigidly structured byte payload guarantees that no two varying configurations can ever yield the same hash for signing.

Key Pieces

The Extension Trait Pattern (DnsZoneExt)

-> See: kinetic-core/src/types/dns.rs — Lines 9-16

-> See RUST_CONCEPTS.md for an explanation of the Extension Trait Pattern and the Orphan Rule. We use this to bolt validation logic onto DnsZone which is defined in the external kinetic-types crate.

DnsRecord Enum (from kinetic-types)

-> See: kinetic-types/src/dns.rs — Lines 19-40

This is a strongly typed enumeration defining every possible standard and decentralized DNS record type the Kinetic ecosystem understands. It utilizes the Serde attribute #[serde(tag = "type", content = "value")] to create an internally tagged representation for clean JSON parsing. Here is how the variants break down:

• A(Ipv4Addr): Stores a standard IPv4 address object for legacy routing.
• AAAA(Ipv6Addr): Stores a standard IPv6 address object.
• CNAME(String): A canonical alias string pointing to another domain label entirely.
• TXT(String): An arbitrary text field often utilized for domain ownership verification protocols.
• PeerId(String): Contains a libp2p cryptographic peer identifier, bypassing IP routing entirely in favor of direct peer-to-peer transport.
• KID(String): Contains a Kinetic Key Identifier (did:kin:...), mapping the domain to a globally authorized decentralized identity document.
• IPFS(String): Contains a content identifier hash, allowing a domain to seamlessly serve decentralized static web pages stored on IPFS.
• Other: The catch-all variant utilizing #[serde(other)]. If a newer network upgrade introduces a record type that an older node does not understand, this variant catches it, preventing a deserialization crash and ensuring forward- compatibility.

DnsZone Struct (from kinetic-types)

-> See: kinetic-types/src/dns.rs — Lines 11-17

What it does: A structural wrapper that encapsulates a HashMap<String, Vec<DnsRecord>>.

Why it matters: Notice the strategic #[serde(default)] attribute placed above the HashMap definition. If an end-user submits a JSON payload with an entirely empty body {} instead of the expected {"records": {}}, Serde will not panic and reject it. It will realize the records field is missing, look up the default implementation for a Rust HashMap (which is an empty map), and automatically substitute it. This makes the API endpoint extremely resilient and forgiving to slightly malformed but logically harmless inputs.

HostRoutingRecord (from kinetic-types)

-> See: kinetic-types/src/dns.rs — Lines 42-81

What it does: Maps a persistent, decentralized host identifier string to a fluid, currently active libp2p PeerId.

Why it matters: While standard DNS maps domains to static IP addresses, a peer-to-peer node’s active network connection (its peer ID and IP address) can fluctuate wildly as it disconnects, reboots, or changes networks. This record is highly dynamic. Crucially, look at the signable_bytes method provided in the implementation block. When a user applies a cryptographic signature to this record to prove they own the domain, the system does not just stringify the JSON and sign it. JSON keys can be arbitrarily rearranged by different libraries, which would cause the signature verification to fail unpredictably. Instead, the code aggressively packs the data into a strict, length-prefixed byte array format. By explicitly length-prefixing the individual strings before concatenating them together, it mathematically ensures that a clever attacker cannot dynamically shift bytes between different fields to trick the signature verification algorithm into validating a malicious payload. It also integrates a drand_kyn field. Instead of relying on a highly unreliable local UNIX timestamp to prove exactly when the routing record was generated, it utilizes the block number from the Drand distributed randomness beacon. This provides a globally verifiable, entirely decentralized clock mechanism, ensuring that attackers absolutely cannot replay older, intercepted routing records to maliciously hijack network traffic.

How This Connects to the Rest of Kinetic

CROSS-CRATE: The Divide Between kinetic-types and kinetic-core

A common question when viewing this file is: Why aren’t the DnsZone struct and the DnsZoneExt validation trait simply bundled together in the exact same file? The answer lies in strict dependency management. The kinetic-types crate is purposefully engineered to be universally importable across any platform architecture. A lightweight WebAssembly wallet running inside a mobile browser can import kinetic-types to properly serialize a DNS request. That browser environment does not need—and likely cannot support—the heavy cryptographic validation dependencies required to verify it, because the backend network will perform that validation anyway. By brutally splitting the raw data types from the complex validation logic, Kinetic maintains a very clean, modular, and fast- compiling dependency graph.

FORWARD DEPENDENCY: The State Transition Machine (Consensus)

When a validator node receives a transaction block containing a DNS state update payload, the core consensus engine will intercept the raw bytes and immediately pass them into the DnsZone::parse_payload(bytes) function defined in this file. If this function returns a validation error, the transaction is immediately marked as structurally invalid. The user loses their transaction gas fee, and the global state is never modified. The consensus layer trusts this specific file implicitly and exclusively to act as the ultimate gatekeeper of state purity.

FORWARD DEPENDENCY: The P2P Peer Routing Table

When a node resolves a domain like application.kin and receives a decentralized PeerId in response, it passes that raw string directly down into the libp2p networking stack to attempt a direct connection. If the string was malformed, the connection engine would panic or silently swallow the failure. Because this file strictly and definitively ran libp2p_identity::PeerId::from_str during the initial block validation phase, the routing layer can blindly trust that the string it pulled from the database is a cryptographically sound identifier, eliminating the need for redundant string checks during active routing.

Quick Reference

• Maximum Total Records: Hard-capped at precisely 50 records per domain zone to prevent unmitigated state bloat.
• Label Validation Parameters: Must be exactly 1 to 63 characters in length. Only alphanumeric characters, hyphens (but explicitly not at the leading or trailing edges), and underscores are permitted. The special @ (apex) and * (wildcard) labels bypass these specific string checks entirely.
• Record Collision Mechanics: A label housing a CNAME redirect record cannot possess any other records whatsoever; it demands exclusivity.
• Field Size Constraints: Standard TXT records are heavily constrained to 255 bytes. CNAME targets are constrained to 253 characters.
• JSON Payload Structure: Enforces {"type": "...", "value": "..."} formatting via Serde internal tags, diverging from raw nested structs.
• Data Normalization: All subdomain labels are automatically cast to lowercase before permanent storage. Duplicate labels submitted in varying cases (like Api and API) are seamlessly merged together utilizing hash map entry logic.
• P2P Ecosystem Integrations: Strictly enforces the internal string structure of libp2p PeerIds and native Kinetic KIDs before they touch the database.
• Dynamic Routing Safety: The HostRoutingRecord struct utilizes length- prefixed byte concatenation for deterministic cryptographic signing, anchored exclusively by a drand_kyn decentralized timestamp rather than local system clocks.

Open Questions / Things to Revisit

1. TXT Record Constraints and Developer Experience: Should TXT records really be strictly limited to a single 255-byte string limitation? Legacy standard DNS actually allows for multiple 255-byte chunks that can be conceptually concatenated by the client application. If external application developers need to store large cryptographic verification keys (like a Matrix server verification token or a domain-ownership proof) directly inside a TXT record, this hard 255-byte limit could cause massive developer friction and require hacky protocol workarounds.
2. The “Unknown Record” Silently Passing: The DnsRecord::Other fallback variant is an excellent architectural choice for forwards-compatibility, but during the validation loop, the code does exactly this: DnsRecord::Other => {}. It simply ignores it. This means a malicious actor could theoretically submit payloads filled entirely with Other records, bypassing all structural checks while still taking up valuable slots within the 50-record limit. Is this intentional behavior, or should Other records be explicitly rejected during active zone updates to prevent state-spamming?
3. Rudimentary IPFS CID Validation Mechanics: The current CID validation logic simply checks if the provided string begins with Qm or b. This is extremely rudimentary and highly trusting of the user. It does not verify the Base58 or Base32 encoding, nor does it verify the cryptographic multihash structure nested inside the CID. This implies that a blatantly invalid CID (like the string b-this-is-garbage-data-that-will-fail) will easily pass the validation layer, which could cause downstream IPFS resolver clients to crash when they attempt to fetch the non-existent content. We should strongly consider importing the official cid crate to perform actual, rigorous parsing at the edge.

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.