Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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.