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?