Crate: kinetic-network

Stage: 8

Reading Time: 360 mins

Depends On: kinetic-core, kinetic-types

What Is This?

This is the decentralized nervous system of Kinetic. The kinetic-network crate is responsible for peer-to-peer (P2P) communication, maintaining the Distributed Hash Table (DHT), enforcing gossipsub packet routing, and rejecting Sybil attacks via active Proof of Work (PoW) and Kademlia strike tracking.

If kinetic-core makes the rules, kinetic-network enforces them in the hostile environment of the public internet.

Key Pieces

The crate is divided into three distinct pillars:

1. The Store (src/store/): An fortified local Kademlia Record Store. It intercepts raw Kademlia reads/writes from the network and forces them through verification.rs to validate VDFs, Authorized Manifests, and Cryptographic tie-breakers before they ever touch the local Sled database.
2. The Client (src/client/): The asynchronous, multi-thread safe interface for the rest of the node (like kinetic-daemon or kinetic-rest) to send commands to the network. It uses MPSC channels and oneshot callbacks to pass messages without ever blocking.
3. The Event Loop (src/event_loop/): The single-threaded Libp2p Swarm. Because the Swarm cannot be shared across threads safely, it runs isolated in a massive tokio::select! loop inside core.rs. It acts as an Actor Model, listening for network events on one side and NetworkClient commands on the other, juggling them all asynchronously.

Why Kinetic Needs This

Warning

A standard Libp2p node is trusting. Out of the box, Libp2p Kademlia will gladly accept any data a peer sends it, allowing a single malicious node to overwrite every domain name on the network instantly (a classic Eclipse/Sybil attack).

Kinetic strips out the default Libp2p storage mechanics and injects the KineticRecordStore. kinetic-network exists to ensure that every single byte received from the network is cryptographically scrutinized (checking VDF proofs, verifying signatures, enforcing rate limits) before it is trusted.

How to Read This Stage

This is the largest and most complex crate in the codebase (29 source files, over 5,700 lines of code). We have broken it down into 19 densely packed documentation files.

• Begin with the Store files (02 to 05, 10) to understand how data is actually validated and saved.
• Move to the Client files (06, 07, 18) to understand how the node asks the network for data.
• Dive into the Event Loop (08, 09, 11 to 13) to see the beating heart that routes the packets.
• Finally, read the handlers and miscellaneous components (14 to 17, 19, 20) for the fine details on Gossipsub and PoW.